Code Map
Where things live in src/mindroom/, for locating code.
When you add, rename, or remove a key module, update its row in the same PR.
Inbound Turn Pipeline
The path from a Matrix message to a delivered response; Bot Runtime explains why the runtime is split this way.
Matrix sync callback
-> matrix/durable_ingestion.py (validate owned Nio work, commit its sequence and effects, then acknowledge)
-> bot.py (AgentBot runtime shell, for agents, teams, and the router)
-> journal_dispatch.py + pending_event_worker.py (fan admitted events out to callbacks; unsettled work is woken again)
-> turns/ingress.py (owns one event to gate admission: onboarding command -> approval reply -> precheck -> claim -> normalize -> resolve -> admit)
-> ingress_validation.py (classify provenance once, dedup, echo drop; commands exit before batching)
-> inbound_turn_normalizer.py + conversation_resolver.py (canonical turn input, conversation identity)
-> voice/ingress.py + turns/interactive_selection.py (voice readiness and selection answers, admitted in receipt order)
-> coalescing/ingress_ticket.py (one item's lane slot, turn claim, and queued notice until admission)
-> coalescing/ingress_lanes.py (per-(room, sender) receipt-order FIFO; STT readiness waits here)
-> coalescing/gate.py (ordinary text dispatches immediately; adaptive text and media debounce)
-> turns/dispatch.py (owns one turn from gate exit: prepare -> decide -> execute -> record)
-> turn_policy.py + command_turn_executor.py (ignore / route / respond decision, command execution)
-> response_runner.py -> ai.py / teams/envelope.py (lifecycle lock, entity envelopes)
-> reply_turn/locked_turn.py (one settlement for agent, team, and approval turns)
-> response_turn.py (shared streaming turn driver; blocking replies collect it)
-> streaming.py + delivery_gateway.py (progressive edits, Matrix send)
-> turn_store.py / event_journal/turn_rows.py (durable dedup so restarts don't double-reply)
Modules
| Module | Purpose |
|---|---|
failure_text.py |
The text a caught exception reports: its text, or its type name when it has none |
github_app_auth.py |
GitHub App installation tokens minted from an App private key and cached until near expiry, shared by Git knowledge sources and Agent Keys |
tls_trust.py |
Shared TLS trust (system store plus certifi's roots, unless the operator sets SSL_CERT_FILE or SSL_CERT_DIR) for Matrix, the egress broker's upstream connections, and Realtime speech |
bounded_bytes.py |
Shared asynchronous byte collection that rejects overflowing chunks before buffering them |
public_fetch.py |
The guarded fetch of one public HTTP(S) URL under one deadline, shared by the website, trafilatura, and newspaper tools, worker media, and plugins |
origins.py |
Shared browser-origin normalization and allowlist validation for dashboard auth, CORS, Connections same-origin checks, the Computers and Connections MindRoom Chat allowlists, and MCP gateway origins |
matrix_openid.py |
Matrix OpenID verification at the configured homeserver and audience binding, shared by Computers and the Connections portal |
atomic_file.py |
Shared atomic byte publication and cleanup relative to an opened directory |
delivery_replay.py |
Durable per-scope claims for inbound deliveries: event ids, Matrix thread roots, and nonces, each scope in its own file under its own lock; external triggers also split their old shared file through it |
orchestrator.py |
MultiAgentOrchestrator - composition root: wires the fleet, services, and reload lifecycle, and applies reload plans |
integrations.py |
The built-in integration registry, the one place core wires an integration's runtime: each integration's public routes, its binding to the live bots and the shutdown drain of what it bound, final-reply mirroring, config checks, and created-agent tool edits |
orchestration/ |
Extracted orchestrator helpers (config update plans, plugin watch, rooms, runtime) |
orchestration/config_lifecycle.py |
Debounced config-reload lifecycle: the process's one config load (published to the embedded API), queueing, response drain, and update-plan dispatch |
config/load_attempt.py |
The one config-file load attempt that the runtime and the dashboard API share |
config/commit.py |
The one config-file write: validated file content, include and personal-agent name refusals, and the staleness check for changes derived from a loaded config, under the roster lock |
api/config_lifecycle.py |
The dashboard API's published config snapshots: loads, commits published atomically with the file write, and the strict and last-good per-request readers |
orchestration/config_updates.py |
The config update plan: the one decision of what a reload restarts, starts, removes, and re-authorizes |
orchestration/entity_fleet.py |
The one owner of every managed bot's lifecycle: start, background retry, restart stop, removal, and process shutdown |
orchestration/rooms.py |
Managed room setup through the router: room creation, policy, invitations, root Space, server emoji room, and bot memberships |
orchestration/accounts.py |
Managed Matrix accounts: the internal user's and each configured entity's, localpart collisions checked before any is created, then the identity registry validated |
orchestration/storage_preparation.py |
Every startup migration, in the one order they depend on, before anything reads the storage root |
orchestration/turn_recovery.py |
When each bot replays the turn-journal work it left pending: once the bots its turns need completed their first sync |
config/bundle.py |
Native staged bundle validation, drift protection, directory publication, and recovery journals |
cli/config_bundle.py |
Bundle install, change-classification, and runtime-confirmed apply/rollback command adapters, plus initialize-only runtime bootstrap |
runtime_state.py |
Shared runtime readiness state for health/ready endpoints |
event_loop_stall.py |
Native-thread event-loop stall detector that logs the blocking stack |
runtime_resolution.py |
Authoritative runtime resolution for one agent materialization |
bot.py |
AgentBot runtime shell of every agent, team, and the router: Matrix lifecycle, sync callbacks, and room behavior |
bot_runtime_view.py |
One bot generation's runtime state: its run phase and admission fence, and the runtime's shared config, gate, and membership index read through its orchestrator |
bot_room_lifecycle.py |
One bot's room joins and leaves: configured and invited rooms, durable pending invites, following rooms listed under a room, cleanup of rooms it no longer keeps, the router's welcome, and an entity's notice in a managed room |
turns/ingress.py |
TurnIngress - owns one inbound text or media event from its Matrix callback to gate admission, including onboarding commands, approval replies, edits, and commands that bypass the gate |
turns/dispatch.py |
TurnDispatcher - owns one turn from the coalescing gate's exit to its recorded outcome: prepare, decide, execute, record |
turns/interactive_selection.py |
Admits an answer to an interactive question behind earlier ingress and runs its response after the gate |
turns/queued_notice.py |
The queued notice and approval-wait reaction that text, media, and voice ingress share |
voice/ingress.py |
VoiceIngress - fixes a voice message's conversation, then readies it behind its sender's lane |
voice/readiness.py |
Voice preparation and checkpointing, gated on the router's visible echo |
router/duties.py |
What only the router bot does: keep room-backed reply grants current from its sync, set up and welcome the rooms it joins, clean orphaned bot accounts, and emit room-membership hooks |
router/relay.py |
Router relay delivery: target readiness, handoff metadata, and visible delivery |
ingress_validation.py |
Ingress boundary validation: classify each event's provenance once against the entity registry, handled-id dedup, reply access at the first gate and again under the admission fence |
turns/facts.py |
One inbound event's classified provenance (IngressFacts), the turn origin derived from it, and the one command rule |
inbound_turn_normalizer.py |
Raw input shaping (text, voice, sidecars, media) into canonical turn inputs |
conversation_resolver.py |
A turn's thread decided once at ingress, the context read in that thread, and envelope assembly from classified provenance |
coalescing/ingress_ticket.py |
IngressTicket: one ingress item's lane slot, turn claim, and queued notice until gate admission moves them, released by one idempotent close |
coalescing/ingress_lanes.py |
Per-(room, sender) receipt-order FIFO delivering resolving ingress (voice/STT readiness) to conversations |
coalescing/gate.py |
Live message coalescing gate; ordinary text dispatches immediately, adaptive text waits for its quiet window, and media waits for attachments and a trailing caption |
coalescing/batch.py |
Coalesced dispatch batch construction |
turn_policy.py |
Pure turn policy: decide ignore, route, or respond for inbound turns |
participation.py |
Framework-independent participation state: one immutable decision, concurrent checks, and approval-preserving settlement |
participation_hook.py |
The reply's participation check as a pre-request loop hook: the configured judgment backend on a projection with tool calls and files as placeholders, or a decision request on the reply's exact messages, ending the run when it stays silent |
judgment/ |
Backend-independent boolean and choice questions, minimized context, shared execution limits, the bounded HTTP client, and LLM, System One, and OpenAI Decisions adapters |
participation_judgment.py |
Bind the participation rubric to an opt-in LLM, TypeSafe, or OpenAI Decisions judge and map its result to a participation decision |
mid_turn.py |
Per-response finish-or-wrap-up decisions over immutable queued-message snapshots |
mid_turn_judgment.py |
Bind the active request and agent settings to the shared LLM, TypeSafe, or OpenAI Decisions judgment backend |
config/mid_turn.py |
Opt-in agent settings for the mid-turn judgment backend and decision instructions |
judgment/cold_cache.py |
Decide from a thread's idle time and an opt-in judge whether the thread moves to the agent's cheap model |
config/cold_cache.py |
Opt-in agent settings for the cold-cache judgment backend |
config/room_activity.py |
defaults.room_activity and its per-agent field overrides for the other-threads note |
providers/tool_policy.py |
A decision request's tool policy: tool_choice "none" keeps tool schemas and allows no tool use, native tools included |
config/participation.py |
Opt-in participation settings for existing thread agents: bounded pause and decision instructions |
config/skill_learning.py |
Opt-in agent settings for skill reviews: interval, review model, notices, and archival |
dispatch_replay_guard.py |
Replay-guard checks for dispatch sequencing |
event_journal/ |
Durable ownership of admitted Matrix events, conversation projection, and delivery outbox |
event_journal/upgrades.py |
The ordered schema upgrades both backends run inside their schema transaction, against one schema inspector, then the current schema and the conversions that fill it |
event_journal/write_queue.py |
The one writer task each backend's writes queue for, from any event loop; the writes queued at once commit in one transaction |
response_sources.py |
Immutable response-attempt source identity shared by runtime and persistence boundaries, and the SourceFate a response returns for them |
reply_lifecycle.py |
Pure rules for durable reply records: every event that changes a reply, its spans, rows, and effects (see Reply Messages) |
reply_presentation.py |
Reply presentation model, its JSON codec, and rendering into a body, trace, and terminal wire status |
reply_scope.py |
ReplyRuntime and SpanHandle: reply claims, span exits, write-ahead, owed writes, and runtime ownership |
edit_regenerator.py |
Decides which message edits regenerate a reply and runs each off the room's event lane, as the entity answers now |
event_journal/views.py |
The narrow journal views collaborators are typed as, each operation declared once on the view that owns it; PrincipalStore inherits them |
event_journal/principal_rows.py |
PrincipalRows: the backend and principal a view is bound to, and the typed read, write, and recovery-read helpers that pick each operation's lane |
event_journal/matrix_delivery_rows.py |
The delivery outbox's transactions: enqueueing replies and final answers, acknowledgement, retirement, and permanent failure |
event_journal/replies.py |
ReplyStore: reply rules applied inside journal transactions, with their in-transaction effects |
event_journal/approval_store.py |
ApprovalStore: one principal's approval calls, cards, grants, scheduled calls, and paused-run continuations |
event_journal/approval_calls.py |
One row per gated call, whatever owns it, and resolve_call, the only writer of a call's decision and its card's terminal edit |
event_journal/approval_cards.py |
Approval cards and receipts: reservation, the events that show them, terminal edits, retirement, departure cleanup, and the typed ApprovalCardView clicks and recovery read |
event_journal/approval_grants.py |
Timed grants: the consent a card offers, the grant it originates, its batch, and revocation edits |
event_journal/approval_signals.py |
ApprovalSignals: what committed approval writes tell the process, each principal's paused replies that bots' holds follow and each decided call that wakes its waiter and sends its card's terminal edit |
event_journal/legacy_approval_records.py |
One-time conversion of an earlier release's per-kind approval tables to one row per call and card |
event_journal/legacy_response_attempts.py |
One-time cancellation of the approvals an earlier release left pending, and removal of the tables that kept their reply identity |
event_journal/turn_rows.py |
Turn state as rows, agent-scoped: lookups, narrow writes, the one reshape that forms a new source tuple, the agent's redaction record and the eligibility guard every write checks, delivery binding, and retention |
event_journal/legacy_turn_rows.py |
One-time conversion of turn_records blobs, journal redaction tombstones, and the pre-journal JSON ledger into turn rows |
event_journal/legacy_approval_failures.py |
One-time conversion of the free-text failure reasons failing approval continuations stored into their failure kind and detail |
event_journal/scheduled_approvals.py |
Stored scheduled tool calls and their one-shot approvals: binding, fire-time arming, withdrawal, claim with its receipt, and outcome |
journal_dispatch.py |
Fan admitted journal events out to typed Matrix callbacks and settle the ones that finish |
pending_event_worker.py |
Decides when pending journal work runs, and wakes itself again whenever a pass stops early |
command_turn_executor.py |
Command execution and durable command/config mutation journals |
reaction_dispatch.py |
Durable semantic routing for Matrix reactions, and the reaction:received hooks for reactions no built-in consumer took |
user_stop_reconciliation.py |
Records a Stop reaction on the reply it stops |
visible_response_reconciliation.py |
Visible Matrix response recovery, adoption, and replay reconciliation, and the settlement of the sources a turn's response left unclaimed |
turn_store.py |
One agent's turn state for the runtime: awaited reads and writes over event_journal/turn_rows.py, the in-process claim registry, and locked source and edit-snapshot preparation |
response_runner.py |
Response lifecycle execution: admission, the conversation lock, claiming the reply, preparing the agent or team turn, and streamed or collected delivery; it returns what the turn did with its sources and hands a paused turn to approval/continuation_runner.py |
reply_turn/inbox.py |
InboxResponses: owns detached inbox response tasks, and the turn claim each holds, until they finish, and proves their journal recovery when a shutdown drain cancels them |
reply_turn/enrichment.py |
Request enrichment for one reply turn: Matrix targeting context, silent-schedule guidance, timestamped model context, and the account of an interrupted attempt |
reply_turn/locked_turn.py |
LockedTurns: the settlement every locked reply turn shares (its ending, span exit, and lifecycle finalization), its effects and identity, and ReplyTurnDeps, which the response runner and the approval runner both settle through |
reply_turn/request.py |
ResponseRequest, the values one reply turn runs with, and the helpers every owner of its locked lifecycle shares (correlation, typing, reply authorization) |
response_turn.py |
The streaming response-turn driver behind agent and team turns and the collector blocking callers read it with (attempt loop, model-switch continuation, empty-run retry, the turn record and its interrupted row), ResponseTurnContext with a turn's inputs, and the run metadata and request-log context a turn binds around its model requests and stream pulls |
loop_hooks.py |
The hooks every run or resume installs on the agent loop, composed once in the order the turn applies them; agent_loop_hooks and leader_loop_hooks name what an agent's and a team leader's run differ by, and HookTurn holds what every run takes from its turn |
run_storage.py |
Where an agent or team run stores (RunStorage, taken from a scope context or bound to a turn), the terminal record it hands over and the error when it hands none, and the persist callback that keeps and stores it |
response_attempt.py |
Runs one visible response attempt as its reply span's cancellable task |
final_delivery.py |
TurnEnding, the one typed value of how a reply turn ended, the delivery outcome that carries it, and the views derived from it: an approval's failure, the message:cancelled reason, and the timing label |
response_lifecycle.py |
Shared response lifecycle helpers, the response hooks and silent-schedule result record, queued-notice state, and the approval holds it follows from ApprovalSignals |
execution_preparation.py |
Request-scoped execution preparation for prompts and persisted replay |
response_payload_preparation.py |
Execution-side, under-lock assembly of one response's payload from immutable ingress inputs |
delivery_gateway.py |
Visible Matrix delivery for already-generated responses (send, edit, finalize) |
custom_tools/matrix_message_idempotency.py |
Bounded durable keyed Matrix sends: preparation, receipts, retention, replay, and current authorization checks |
personal_room_lifecycle.py |
Personal-room command and membership policy, personal-agent provisioning from a template, target-service routing, reconciliation, and separate rejoin/cleanup retention projections |
personal_agents.py |
Onboarding one user's personal agent: name choice, Matrix account registration, then the roster entry |
config/contacts.py |
Opt-in contacts agent settings (rules, default tools, judgment) and the control tools a contact never offers |
contacts/store.py |
The contact records and their primary-only store, and the contact rooms an agent keeps across restarts |
contacts/parties.py |
Who can be a party of a contact (personal agents with contacts, people by canonical Matrix ID, and other deployments' agents by Matrix ID), target resolution, how a party is named, the Matrix accounts that speak for a party, and a user's personal room |
contacts/policy.py |
The contact message policy: the consecutive-agent-message limit, the contact:before_send hooks, and the optional judge, failing closed, plus an agent's effective rules for a contact |
contacts/turns.py |
Contact turns: the contact a room belongs to, who it admits, that its turns run as the agent's owner, and how a turn of an agent in its own contact room differs from a normal turn |
contacts/flow.py |
The contact operations behind the contacts tools and the Connections Contacts page: request (with the notice in the target owner's personal room), accept (creating the contact room, seating both parties, and starting the requesting agent's turn), decline, update, remove, and list, each run for a ContactActor owner and checked against their ownership |
contacts/federation.py |
Contacts with agents of other deployments: an invite matching contacts.remote_agents stored as a request and posted to the owner, and the contact room's membership accepting, declining, or ending such a contact |
custom_tools/contacts.py |
ContactsTools: the toolkit injected for agents with contacts, with confirmation cards on requests, acceptances, and rule changes |
post_response_effects.py |
Shared post-response effects after Matrix delivery |
thread_summary/state.py |
SummaryState: one walk of a thread's history into trusted summary notices, authorized human pins, and ordinary messages, and the current-title readers listings, exports, and calls share |
thread_summary/schedule.py |
The process's per-thread summary baselines and write locks, the next threshold, and the pre-queue gate |
thread_summary/generation.py |
The summary model call, its response schemas, and initial tag normalization |
thread_summary/notices.py |
Summary notice sends ordered after their predecessors, and the manual and welcome writes |
thread_summary/automatic.py |
The automatic pass after a reply: thresholds, pin and resolved checks, initial tags, and the source pin re-check before delivery |
room_activity/note.py |
The opt-in turn-context note listing the room's other threads with messages since the agent's last reply in its thread, read in one projection snapshot (event_journal/reads.py room_thread_activity) |
room_tree/note.py |
The turn-context note naming the rooms above, beside, and under a room of a room tree, with their room IDs, filtered by the requester's room access |
file_access.py |
Agent file_access resolution, the shared path authorization its callers, such as plugin tools, read and write model-supplied paths through, and the size-checked reads of files that upload tools send |
orchestration/config_warnings.py |
Startup and reload warnings for risky but allowed config choices (foreign homeserver authorities, unconfined primary-process tools next to worker code tools, Agent Keys opt-ins whose only command tool is a primary python) |
approval/tool_approval.py |
Tool-call approval rule evaluation and public approval API |
approval/execution.py |
Agent reconstruction and exact-call execution for persisted native approval continuations |
approval/resume.py |
Resuming a persisted paused agent run on the agent loop with exact decisions: its history replay, native history, hooks, and the parent continuation the delegation driver injects |
approval/receipt.py |
The trusted approval receipt: the text naming each decided call of one tool-approval continuation, and the request hook that adds it to a reader's messages before its first request |
approval/receipt_readers.py |
Which runs read the bound approval receipt: the binding an approval continuation sets around itself, free of model-loop imports so work the loop starts can leave it |
approval/tool_owners.py |
Recorded toolkit restoration and exact owner validation for saved approvals |
approval/response.py |
Which calls of a paused run need a person: the approval plan of a paused generation and the publication of its cards |
approval/continuation_rules.py |
Pure rules for what a paused reply does next: next_step over its continuation's state, lease or claim holder, failure kind, claim outcome, and final answer, for each trigger (dispatch, a resume's end, an unavailable owner, a minimal-mode exit) |
approval/continuation_runner.py |
ApprovalContinuationRunner: a reply's approval lifecycle that ResponseRunner hands paused turns to: pausing for approval, resuming the approved run in its reply, minimal-mode CLI waits, and running the steps continuation_rules decides, including failure settlement; it settles through reply_turn/locked_turn.py and knows nothing of the response runner |
approval/manager.py |
Matrix-backed tool approval runtime state: card publication, clicks, deadlines, and recovery over typed card reads |
approval/auto_approve_windows.py |
Durable per-conversation !auto_approve windows that approve one requester's gated calls without cards |
oauth/credential_binding.py |
Canonical OAuth provider and worker-target bindings for browser workflows |
oauth/credential_lifecycle.py |
Single transaction owner for scoped OAuth load, refresh, callback publication, invalidation, and reset state |
oauth/credential_store.py |
Per-scope SQLite OAuth credential storage, revisions, and reset receipts |
oauth/reset.py |
OAuth reset target resolution and requester-bound browser intents |
oauth/reset_execution.py |
MCP retirement and durable reset execution |
oauth/microsoft.py |
Microsoft 365 OAuth providers sharing one Entra app, with the tenant resolved per runtime |
oauth/spotify.py |
Spotify OAuth provider |
oauth/legacy_spotify_credentials.py |
Tokens the former Spotify routes stored, adopted once into a scope's OAuth store when that store is created |
custom_tools/oauth_connections.py |
Requester-bound agent tool for issuing OAuth reset confirmation links |
egress_broker/ |
Agent Keys: the egress broker in the primary that adds stored keys or connected-account tokens to worker HTTP(S) requests the worker never sees |
egress_broker/env.py |
Whether the broker and its personal page are on, the one rule for which agents use Agent Keys (egress_credentials plus a shell anywhere or a worker-routed python), and the call env overlay |
egress_broker/service.py |
Broker lifecycle on its own thread, secret resolution per verified worker scope, and the per-call broker env for worker-routed calls and primary shell calls |
egress_broker/proxy.py |
Authenticated forward-proxy listener: CONNECT interception or blind tunnels, plain HTTP forwarding, and the unmatched-host policy |
egress_broker/mitm.py |
TLS interception for hosts with rules: Host checks against the CONNECT target and per-request credential injection |
egress_broker/_relay.py |
HTTP/1.1 plumbing both listener paths share: request framing, guarded dialing, body streaming, refusals, and audit rows |
egress_broker/dial.py |
Guarded upstream dialing: refuses loopback, private, and cloud metadata destinations and connects only to the address it validated, through the operator proxy when the primary has one |
egress_broker/rules.py |
Pure rule matching, path restriction checks, ambiguous-path refusal, and credential injection into a header or query parameter |
egress_broker/user_services.py |
Services users define per scope, stored beside the scope's keys and merged after the config services into the config the broker matches |
egress_broker/github_app.py |
Tokens for github_app services: which repository a request names, and the installation token of its access level |
egress_broker/secrets.py |
Per-scope egress keys in the primary-only credential store and each service's key-or-account status |
egress_broker/oauth_reuse.py |
Per-service opt-ins that let Agent Keys use a connected OAuth account, stored beside the connection they unlock |
egress_broker/tokens.py |
Signed, expiring worker proxy tokens that carry the worker scope, agent, and requester |
egress_broker/audit.py |
Metadata-only SQLite request log, pruned to 30 days and 100,000 rows |
egress_broker/ca.py |
Local broker CA, per-host leaf certificates, the SNI check against the CONNECT host, and the worker trust bundle |
api/egress_broker.py |
Dashboard Agent Keys routes: service status, presets, keys, account connect, disconnect, and opt-in, the full request log, and the CA download |
api/client_sessions.py |
/api/client-sessions: exchanges a Matrix OpenID token from a web client for an in-memory, one-hour session token, resolves the token a request's Authorization header or a websocket's subprotocol presents for plugin routes and call transcript routes, checks a websocket's origin, and revokes it at sign-out, which ends the streams it signed in |
api/plugin_origins.py |
The listener MINDROOM_PLUGIN_ORIGIN_PORT turns on, which serves each plugin's origin_module router on its hosts <label>.<plugin>.<domain> with the API app as request.app, adds the frame-ancestors floor to every answer, and answers on-demand TLS /ask checks from the plugins' serves |
api/plugin_routes.py |
Lists the published plugins to signed-in clients at /api/plugins, and serves each one's routes_module router under /api/plugins/<plugin>/ from the app built as the plugin loads, looked up per request so reloads take effect |
api/connections_session.py |
Connections portal sign-in: exchanges a Matrix OpenID token from MindRoom Chat for a portal session cookie |
api/connections_contacts.py |
Contacts page routes under /api/connections/contacts: the signed-in owner's contacts with their own side's rules and tools, and accepting, declining, editing, and removing them without an approval card |
api/connections_native.py |
Connections portal sign-in from the iOS app: the browser gets a pending cookie, and the app confirms it with its own token before the session starts |
api/connections_session_cookie.py |
Signed, process-local portal session cookies with a fixed one-hour lifetime |
api/egress_credentials.py |
Personal /api/connections/egress routes: per-agent services and keys, user services, account connections and opt-ins, and the caller's request log |
api/egress_status.py |
Service status, preset, and request-log responses and the account-connection gate shared by both egress APIs |
config/egress_broker.py |
egress_broker config models: services, preset expansion, rules, auth types, and their validation |
egress_broker/key_access.py |
Who may use and manage an agent's Agent Keys, shared by the Agent Keys pages and secret requests |
secret_requests.py |
In-memory registry of pending secret requests, the card content they post, and the store of temporary secrets requesters gave conversations (in memory, or also one private file each) |
secret_request_cards.py |
The card a secret request posts and the wait for its answer, shared by request_secret and request_temporary_secret |
api/secret_requests.py |
POST /api/rooms/{room_id}/secret-requests/{request_id}: stores the requester's key in the agent's scope (first adding the service the card proposed), gives their temporary secret to the conversation that asked, or records a decline |
api/github_requests.py |
/api/github/request, /api/github/status, and /api/github/token: sends a client session user's /repos/<owner>/<repo> or /graphql call to api.github.com with their own saved personal access token or else their connected GitHub account, reports which, and saves or removes that token |
custom_tools/temporary_secrets.py |
temporary_secrets agent tool: request_temporary_secret asks the requester for a secret that the conversation's shell commands receive as an environment variable |
custom_tools/egress_credentials.py |
egress_credentials agent tool, whose presence opts an agent into Agent Keys: which services have a key or connected account in the agent's scope, where to add missing ones, and request_secret, which asks the requester for a key with a card, optionally for a new service of their own it proposes |
event_journal/tool_jobs.py |
Background tool job snapshots and outcome payloads, written only by the runtime generation that owns them |
tool_jobs/runtime.py |
Accepted execution ownership, what a job runs and how it is known, durable outcomes, scoped discovery, and result claims |
delegation/background.py |
A subagent call's job: the child it is known by, its saved snapshot, its outcome, and its cleanup inside the generic execution owner |
delegation/job_approvals.py |
A child's approval requests, asked through the cards of the job that runs it |
tool_jobs/instances.py |
One per-storage-root instance: startup-pinned setting and published runtime |
tool_jobs/settings.py |
Startup-pinned feature and toolkit exclusion settings |
tool_jobs/execution.py |
The loop's job admission middleware, the managed call it runs as a tool's or a subagent's job, and the background_after definitions step |
tool_jobs/consumption.py |
Exact durable acknowledgement after the parent run saves a consumed result |
tool_jobs/execution_scope.py |
Response execution envelopes |
tool_jobs/resources.py |
Retained resource cleanup ownership |
tool_jobs/authorization.py |
Current local grants using shared construction policy |
tool_jobs/execution_authority.py |
JobTool and JobCall, what job admission and grant checks read about an offered function and one call of it, and the application-entry authority checks on the call a task runs under |
tool_jobs/provenance.py |
Exact MCP bridge identity for grant checks |
tool_jobs/control.py |
Newer human messages that release waits, and cancellation checkpoints |
tool_jobs/background_after.py |
The reserved background_after argument of managed calls and its validation |
tool_jobs/results.py |
Non-executable durable tool-value and rich-artifact serialization |
tool_jobs/legacy_results.py |
Job result payloads in the shapes earlier releases saved them |
tool_jobs/conversation.py |
The conversation key a reply finds its jobs by, and how long a reply waits for a job's approval |
tool_jobs/notices.py |
The notice on a tool result and the turn-start note about jobs that ended |
tool_jobs/publication.py |
Each agent's live jobs, published per room as state for the client jobs bar |
tool_jobs/client_cancel.py |
Client cancel events, !jobs and !cancel_job, a stopped reply's jobs that await approval, and a left room's jobs |
tool_jobs/approvals.py |
Approval cards a job posts and owns for its child's or its own gated call, denied when the job ends early |
tool_jobs/follow_ups.py |
A follow-up's journal source, identity, streak, and envelope |
tool_system/construction.py |
Selected toolkit factory and digested constructor identity |
tool_system/filters.py |
Shared include/exclude function policy |
custom_tools/job.py |
Reserved job discovery and control tool |
orchestration/server_state.py |
Each entity's runtime origin, worker computer, and role, published per room as state so MindRoom Chat finds its server and shows what the entity does |
orchestration/services.py |
RuntimeService, the sync-and-stop shape of the long-running services that follow the active config |
orchestration/call_transcripts_runtime.py |
The call transcript service in the runtime: the router it reads and posts through, the loop that checks calls every 15 seconds (while call transcripts are off, only holding calls to the one-day limit), the service the API routes reach, and the agent call in a room, read through the agent answering calls there |
orchestration/tool_job_runtime.py |
Managed job lifecycle: recovery, revocation, published jobs state, follow-ups, and retention |
orchestration/script_runtime.py |
Background script lifecycle: startup recovery of preserved runs, reload revocation, maintenance passes, the published worker lease, and when script tools are served |
custom_tools/script.py |
script agent tool: start, inspect, cancel, and list the requester's background scripts |
script_runs/manager.py |
Starts, polls, and cancels script runs in a worker or unsafe-local, and finalizes their cleanup |
script_runs/store.py |
The primary-only SQLite store of script runs and their tool-call receipts, with atomic state transitions |
script_runs/legacy_schema.py |
Script-run columns that older releases' databases lack |
script_runs/models.py |
Run and call records, run states, and the run ID, supervisor handle, and worker key a run derives |
script_runs/reasons.py |
The durable reasons a run was cancelled or interrupted |
script_runs/policy.py |
The tool grants a launch captures and the current tool a script call resolves to |
script_runs/broker.py |
Authenticates a script's tool calls by capability and runs each claimed call under the run's current authority |
script_runs/recovery.py |
The recovery signature that lets a restarted primary adopt a still-running worker script |
script_runs/supervised.py |
Launch, status, and signal of one script process through a shell supervisor, shared by unsafe-local runs and worker routes |
script_runs/launch_contract.py |
Script environment names, size limits, and snapshot layout for launchers, the shim, and the SDK, plus the tool-call argument digest the SDK and the broker share |
script_runs/shim.py |
Import-light entry point that verifies a run's snapshot inside the script process and runs its source |
script_runs/wire.py |
The primary-worker script protocol: its version, request and response models, normalized receipts, and error |
script_runs/worker_client.py |
The primary's HTTP client for a worker's script routes |
api/sandbox_runner_scripts.py |
Worker routes that launch, poll, and signal a run under the worker's supervisor |
api/script_gateway.py |
Capability-authenticated HTTP gateway scripts call tools through, and the listener helper the second listeners beside the API share |
script_sdk.py |
The standard-library MindRoomTools client a script calls tools with |
workspaces.py |
Agent workspace scaffolding, template seeding, and context file resolution |
worker_computer/worker_browser.py |
Serializes dedicated-worker headless browser calls, retains browser resources, and owns configuration/environment retirement and shutdown cleanup |
agents.py |
create_agent: builds one configured agent's toolkits, prompt, model provider, and surface into an AgentBuild |
config/ |
Pydantic models for YAML config parsing (root model in config/main.py) |
config/resolution.py |
What one agent, team, or scope gets from the config, every inherited value filled in (resolve_scope, resolve_agent, and one function per fact) |
config/personal_rooms.py |
Opt-in personal-room settings and validation for commands, aliases, and message templates |
config/personal_agents.py |
personal_agents templates, the roster store, and expansion of roster entries into ordinary agents before config validation |
config/slack.py |
The top-level slack: section: the email domain and Matrix user ID template that map Slack workspace members to Matrix users; also validates the slack tool's channels and room across agents and lists the agents that answer Slack channels |
routing.py |
Intelligent responder selection when no agent or team is mentioned |
routing_judgment.py |
Opt-in bounded System One or OpenAI Decisions responder selection, with explicit no-fit outcomes and existing LLM routing fallback |
teams/formation.py |
Forming a team from one turn: who was asked, who is eligible, which members can be materialized, and the execution-time mode choice for an ad hoc team |
teams/members.py |
Resolving a team's exact members without silent shrinkage, the leader's and members' model aliases for a turn, and build_team_spec: the leader's model, prompt, job controls, call budget, and history settings with each member's roster entry and the build its first delegation makes |
teams/spec.py |
TeamMode, TeamMember with its MemberBuild, and TeamSpec: what a team run is built from |
teams/prompt.py |
The leader's system messages, rendered like an agent's: the stable one holds the team's identity, the markdown line, the roster and mode block, and tool instructions; the turn one holds the date, session context, and enrichment |
teams/delegate_tools.py |
delegate_task_to_member and delegate_task_to_members, the member result texts, the pause a paused member propagates to the team run, and the answer its resumed run gives the waiting call |
teams/runtime.py |
run_team and continue_team over the agent loop: members as child runs, member decisions routed by member and call, team usage |
teams/presentation.py |
The team reply document: header, member slots, consensus, tool trace, the durable team_stream snapshot an approval resume restores, the live document a resumed run publishes, and the document's text without tool markers that a reply records |
teams/legacy_team_presentation.py |
Team reply snapshots of version 2, which keyed member slots by Agno's url-safe member id, read as version 3 when an approval resume restores one |
teams/envelope.py |
team_response_stream: prepare a team turn, run its leader through the turn driver, and render the reply; run_prepared_team runs an OpenAI-compatible API team turn under the same leader hooks and storage |
teams/leader.py |
LeaderRun: how a team's leader runs in one turn or resume, its storage, hooks, request settings, and model, which a live turn and a saved approval's resume both build to start or continue the leader's run |
teams/attempt.py |
One attempt of a team run, a turn's or a resume's: the reply document its events build, the records the run hands over, the text an interrupted turn records (its document without tool markers), and its run metadata |
teams/resume.py |
Resuming a paused team run: TeamResume routes decisions to the calls the team waits for, drive_team_delegations runs a member's delegations and continues with their results, continue_paused_team_run rebuilds the team from a saved approval, and the document a team pause shows |
agent_policy.py |
Execution-policy derivation from one typed input, PolicyInputs, for validated agents, dashboard drafts, and worker config files |
agent_cli/minimal_agent.py |
Minimal mode: the bootstrap prompt and context documents from the build surface, and the turn's one provider-facing Bash tool over the build's catalog |
agent_cli/checkpoint.py |
Minimal Bash's provider batch, captured as a before_dispatch hook and saved as a run checkpoint before any Bash call takes effect, a failed save refusing the call |
agent_cli/cli_shell_agent.py |
Standard agents whose native shell commands call their other tools through mindroom-agent, bound per attempt |
agent_cli/ |
Response-owned CLI grants, call admission, shell access, discovery, and result projection |
agent_modes.py |
Conversation-scoped standard/minimal selection persistence |
agent_cli/minimal_mode_preflight.py |
Minimal-mode eligibility for !mode and minimal subagents, reported as one actionable checklist |
commands/mode_commands.py |
Authorized agent mode selection with canonical session scope and deployment preflight |
api/agent_cli.py |
Authenticated transport for response-owned CLI operations and live call receipts |
agent_cli/cli_approval_recovery.py |
Exact saved CLI approval execution through rebuilt canonical bindings and ordinary interrupted-response recovery |
agent_cli/cli_approval_waits.py |
Response-owned CLI approval waits, exact journal claims, and the end of each scope, which it reports to the approval runner |
tool_system/agent_tool_calls.py |
The live turn's catalog of qualified tools and their serialized execution through the build's tool policy |
tool_system/tool_access.py |
Shared qualified tool identities, discovery, schemas, and local argument validation |
memory/ |
Agent and team memory over Mem0 or Markdown files; an agent's lives at its state root or workspace, every team's Mem0 memory in one store at team_memory/, and each team's file memory at team_memory/<team scope>/ |
memory/_policy.py |
Memory scopes: the team scope ID, the team memory root and each team's file directory, the team scopes an agent reads, and the backend an agent or team uses |
memory/legacy_team_memory.py |
One-time startup merge of the team memory copies earlier releases kept in every member's storage |
memory/_entrypoint_snapshots.py |
Copy of each conversation's inlined MEMORY.md, one file per conversation under memory_entrypoint_snapshots/ in the agent's state root (a private instance's own), reused while that copy only gains lines, anywhere in a file within its preload caps and at the end of a capped one (whose preload keeps its first lines), and less than an hour has passed since the last model request that sent it; any other change loads the file again, which a held prompt (providers/pipeline/prompt_hold.py) tells as an update when one can state it exactly, the old lines staying quoted until the hold starts over |
memory/auto_flush.py |
Background passes that turn file-memory agents' new finished turns into daily notes, with per-conversation progress below tracking/, and the service that runs them while auto-flush is enabled |
memory/legacy_auto_flush.py |
Auto-flush state earlier releases wrote: the reply path's queue file, removed once, and progress entries and note tags in creation order, read as log positions when auto-flush next reads the conversation |
knowledge/file_memory_knowledge.py |
Shared resolution for agent file-memory semantic knowledge overlays |
memory_scope_ids.py |
Cycle-free canonical agent memory scope identifiers |
history/conversation_text.py |
What stored turns said, for background model calls and compaction hooks: which turns and messages count and who said each |
embeddings/ |
The Embedder interface semantic indexes embed queries and documents through, its OpenAI-compatible, Ollama, Vertex AI, and local sentence-transformers implementations, embedder health, and vector compatibility signatures |
knowledge/ |
Knowledge base / RAG file indexing with watcher |
knowledge/file_listing.py |
Which files belong to a knowledge base: include patterns, traversal, symlink-safe inclusion rules |
knowledge/collection_lifetime.py |
Compatible publication selection, shared reader locks, and exclusive collection reclamation |
knowledge/search.py |
What an agent searches: its published sources, the search_knowledge_base tool and its results, and the <knowledge_base> prompt block |
knowledge/readers.py |
The Agno document readers and chunkers knowledge indexing reads files with; the only knowledge module that imports Agno |
knowledge/collections.py |
Collection naming and ownership for one knowledge base: opening, writing a file's chunk rows, reclaiming superseded collections and legacy Chroma storage |
knowledge/vector_store.py |
One collection as one SQLite file: chunk rows, float32 vectors, an FTS5 keyword index, and the collection's own claims, failures, and lifecycle, changed in one transaction with its rows; in-process search |
knowledge/index_metadata.py |
A base's two state documents: the publication, written only by the publisher under the source-root lock, and the refresh status, written only by the runtime |
knowledge/manager.py |
The candidate lifecycle of one semantic base: which collection to resume, copy, or start, reconciling it with the source, and publishing it |
knowledge/file_indexer.py |
One refresh's file indexing: read, chunk, batch-embed, and write each file with its claim, with that refresh's failure evidence |
knowledge/corpus_signature.py |
File signatures, the stat-first corpus scan, and the corpus hash a publication records |
knowledge/legacy_index_state.py |
Startup conversion of knowledge state earlier releases kept outside each collection |
knowledge/index_reader.py |
Published index handle: embeds a query and searches the current compatible publication on a worker thread |
knowledge/git_source.py |
The Git checkout a knowledge base indexes: clone, fetch, force-align, LFS hydration, credential injection |
knowledge/refresh_runner.py |
One knowledge refresh: the child's work under the source-root lock, and the runtime side that spawns it and records its outcome in the refresh status |
knowledge/refresh_scheduler.py |
The process's one refresh scheduler: which bases are refreshing, one queued request each, the concurrency limit, and on-access cooldowns |
knowledge/refresh_locks.py |
The source-root lock that serializes one source's refresh and mutation work, in-loop and across processes |
knowledge_graph/scope.py |
Which graph an agent or private instance owns, named in code from its state root, embedder, and generation |
knowledge_graph/store.py |
The runtime's one Graphiti client and its episode, fact, and entity operations; health and the store registry |
knowledge_graph/clients.py |
Graphiti's LLM, embedder, and reranker clients backed by MindRoom's model and embedder construction |
knowledge_graph/usage.py |
Which conversation an extraction call's tokens are charged to |
knowledge_graph/extraction.py |
What Graphiti is told when it extracts an episode: the entity types and the extraction instructions, built-in, configured, and the names of the episode's known entities |
knowledge_graph/embedded_server.py |
The embedded FalkorDB server MindRoom starts, stops, and recovers after a crash |
knowledge_graph/episodes.py |
Stored runs rendered as conversation and tool_results episodes, and thread classification |
knowledge_graph/names.py |
The one name of each known agent, person, and knowledge_graph.aliases entry: speaker labels, names listed for extraction, and lookups |
knowledge_graph/ingestion.py |
Background ingestion passes over several graphs at once, with per-kind markers, backoff, and dropped episodes |
knowledge_graph/legacy_ingestion.py |
Ingestion markers earlier releases kept as run keys in creation order, read as log positions when ingestion next reads the conversation |
knowledge_graph/runtime.py |
Starts and stops the store and ingestion worker as agents enable the graph |
config/knowledge_graph.py |
The knowledge_graph section: extraction model, extraction instructions, ingestion settings, aliases, and generation |
custom_tools/knowledge_graph.py |
The knowledge_graph tool: lookups, and the edits knowledge_graph_edits allows; also the graph as a search_knowledge_base source |
tool_system/skills.py |
OpenClaw-compatible skill loading from skill roots and workspaces, and the read-only SkillsToolkit with its prompt block |
tool_system/skill_usage.py |
Workspace skill usage records the skill learner's archival reads as an inactivity clock |
tool_system/plugins.py |
Plugin generations: loading, publishing, and disposing them, candidate validation in a separate module namespace, and config_plugins, one config's tools, hooks, skill roots, and OAuth providers from one published generation |
tool_system/registry.py |
ToolRegistry, the tools one config can build (built-ins, its loaded plugins' tools, its MCP servers, and the tools of plugins that failed to load as unavailable), the built-in tools, and the registration scope plugin modules register into |
plugin_api.py |
The supported import surface for plugin code, re-exporting entry points from the modules that own them |
entity_directory.py |
entity_directory, the router and configured agents and teams with prepared Matrix accounts by user ID, with each one's kind, display name, and agent tool names, for plugins |
plugin_context.py |
PluginContext, a plugin's own settings, state directory, and config for its routes and tools, which fails closed once a reload disables the plugin |
plugin_lifecycle.py |
PluginLifespans runs the lifespan of each plugin the primary publishes, starting a reload's new lifespans before it closes the replaced plugins' websockets and stops the old ones, and stopping them all at shutdown |
plugin_testing.py |
The supported kit for a plugin's own tests: loads one plugin as startup does, serves its routes with real client sessions, and runs its tools and hooks behind the turn's admission decision, over stand-in rooms; MindRoom never imports it |
headless.py |
run_turn and validate_config: one configured agent's turn from another Python program, without Matrix or mindroom run, after refusing what needs a running MindRoom; a bound workdir replaces the tools' workspace |
plugin_http.py |
The supported import surface for plugin HTTP routes: client-session sign-in for HTTP and websocket routes, room-membership checks, room reads for routes and streams, and room admins' mode changes (RoomReader, RoomPower, RoomModes, RoomHistory, client_rooms, stream_room_reader), the agents a caller may use in a room with their workspaces (AgentWorkspace), posting as the router (RoomMessenger), administrator checks, the caller's own OAuth access token on an agent that keeps each person's connections apart (client_user_oauth_access_token), the route's PluginContext, and the URLs of the plugin's own hosts and the chat's origins for its pages (plugin_origin_url, client_origins) |
orchestration/plugin_http_runtime.py |
Live room reads for plugin HTTP routes: a running bot in the room answers each read, the router first, and concurrent membership callers for one room share a lookup |
matrix/history_visibility.py |
Where a joined member's view of a room's history begins under its history visibility, walking back from their member event to the join or invite that began their membership |
tool_system/google_workspaces.py |
Workspace-specific Google OAuth provider construction and tool registration |
tool_system/atlassian_connections.py |
Additional Atlassian Cloud connection providers and prefixed tool registration |
scheduling/tasks.py |
Cron and natural-language task scheduling |
scheduling/runtime.py |
The one owner of scheduled-task runners and of when each runner may use its task's owner bot |
scheduling/recurring_schedule.py |
Durable checkpoints for recurring task timers and their pending Matrix trigger |
scheduling/ownership.py |
Which bot runs a scheduled task, decided once at save time from the room's full state |
scheduling/errors.py |
SchedulingError, the one failure a scheduling operation reports, with subtypes for a missing task and failed task storage, which chat, the scheduler tool, and the schedules API each render |
scheduling/scheduled_tool_calls.py |
Resolving a scheduled call on the agent's own live tools and running it once by task ID with its approval |
scheduling/executor.py |
Fire one scheduled task: hook emission, visible or silent Matrix delivery, and failure notices |
scheduling/scheduled_run_records.py |
Agent-workspace JSON receipts for silent scheduled runs |
tools/ |
Built-in tool registrations and their helpers; importing the package registers every built-in tool |
tools/lumalabs.py |
Configurable SDK model binding for both inherited Luma video-generation methods |
tool_system/dependencies.py |
Auto-install per-tool optional dependencies at runtime |
ai.py |
The agent turn: stream_agent_response runs an agent through the turn driver, ai_response collects that stream, and delegated children run through it too |
providers/credentials.py |
Which key a configured model authenticates with: the dashboard key and the missing-key checks the CLI and dashboard report |
providers/key_checks.py |
The request that proves a provider API key valid, which mindroom doctor and the dashboard's provider setup send |
providers/names.py |
provider_route, the route a configured provider value selects with aliases such as gemini resolved, which model dispatch and the wire adapters compare, and ROUTE_PROVIDERS, the provider name of each route the provider registry builds, whose routes config validation accepts as a model's provider, in a module that imports nothing |
providers/identity.py |
model_identity, a configured model's provider name and effective model ID read from its config alone, which every provider builder and pricing take |
providers/anthropic/messages.py |
The Claude adapter (ModelProvider) for the direct API, Vertex AI, and Bedrock Mantle routes, with their client factories, error mapping, and build_provider |
providers/anthropic/settings.py |
Claude route settings parsed from extra_kwargs under Agno's field names, and the keys each route accepts |
providers/anthropic/wire.py |
Claude Messages API formatting of messages and tools, and parsing of the finished response into an assistant message that stores its blocks once, in request shape |
providers/anthropic/stored_turns.py |
The blocks a stored Claude assistant turn replays: its stored claude_blocks, or blocks rebuilt from its message fields, which never take a cache breakpoint |
providers/anthropic/legacy_stored_turns.py |
Claude turns stored before claude_blocks: response-shape blocks read in request shape, and older turns rebuilt from their fields |
providers/anthropic/repairs.py |
Replay-safe shapes of Claude blocks (citations, tool-search blocks) and request-scoped body repairs: unavailable tool references, tool-result order, inline media budgets |
providers/anthropic/prompt_cache.py |
The wire preparation of one Claude request body: history repairs, deferred tool search, tool choice, and the prompt-cache ladder |
providers/cache_ladder.py |
The Claude prompt-cache ladder primitives (breakpoint markers, message rungs, the tools marker) shared by the Claude adapter and the OpenRouter Claude ladder |
providers/anthropic/native_compaction.py |
Claude native compaction: the compaction edit, the checkpoint replay projection, and the checkpoint recorded on each response |
model_catalog.py |
Allowlisted model metadata, Matrix icon upload/cache, and catalog revision |
model_catalog_receiver.py |
Router discovery admission, authenticated responses, and scope/lifetime checks |
model_selection.py |
Structured model request/result values and frozen acknowledgement metadata |
model_selection_scope.py |
Current joined membership and readable-root eligibility for model selection |
ai_runtime.py |
The queued-message notice a reply's loop appends after a tool batch, its mid-turn judgment, whether the request a model answered told it to pause, and the empty-response notice |
providers/openai/ |
OpenAI-family adapters: one Chat Completions adapter for every OpenAI-compatible route, one Responses adapter for OpenAI and Codex, build_provider, the OpenRouter Claude cache ladder, OpenAI server-side tool search tagging, the Responses explicit cache breakpoint on the stable system message and ordered output replay, and the Responses route's request sizing (replay_estimate.py) |
providers/openai/legacy_response_replay.py |
The hosted tool-search items that Responses replies stored without an ordered output kept apart, read for replay |
providers/pipeline/ |
Stages composed around a provider's stream(): the system prompt a conversation holds while its prompt cache is warm, with later changes sent as system prompt updates, one file per conversation under prompt_holds/ in the agent's state root (prompt_hold.py), portable deferred tool search (llm/tool_search.py), media fallback, downloads of the media URLs a route does not send (remote_media.py), the malformed tool-call guidance retry, stream retry with the idle limit, the typed safeguard refusal, and request logging |
providers/registry.py |
build_model_provider, the only way a configured model is built: the dashboard key, the family adapter, and the request pipeline around it with the model's stream idle limit; check_extra_kwargs rejects, at config load and without loading a provider SDK, extra_kwargs keys the model's route does not accept |
providers/gemini/ |
Gemini adapter for the Gemini API and Vertex AI: contents, Files API uploads, Google Search grounding, decision-request config, reply parsing, and the extra_kwargs a Gemini model accepts (settings.py, which loads no Google SDK) |
providers/ollama/ |
Ollama adapter over the native chat API, the extra_kwargs an Ollama model accepts (settings.py, which loads no ollama SDK), and the Ollama SDK's failures as normalized provider errors, which the adapter and the Ollama embedder share (errors.py) |
providers/synthetic_adapter.py |
Synthetic provider streaming seeded Lorem Ipsum and shell calls |
providers/model_http_client.py |
The runtime-owned HTTP client the OpenAI and Anthropic SDK clients send their requests through |
providers/prompt_cache_key.py |
Stable prompt-cache routing keys derived from execution identity |
providers/extra_kwargs.py |
Parses a model's extra_kwargs into its adapter's settings, rejecting unknown keys, and reports the non-secret settings that request logs record as model params |
providers/errors.py |
One classification of provider statuses, context-window wording, and transport failures into the normalized provider errors, shared by every adapter |
providers/assistant_turn.py |
What adapters share to build a turn: the mindroom_model provenance stamp and timings, the progress event of a provider chunk without events, the events that end a finished turn, and the split of a leading inline <think> block into reasoning |
llm/request_context.py |
The per-request logging context (agent, session, correlation id) bound around a model request and read by request telemetry |
llm/request_identity.py |
The identity of what a model request holds before each message, which each answer records for the request it answered |
providers/media_files.py |
Reads the attachment files every wire sends; a file that cannot be read raises InvalidRequest, so the media fallback replaces that file with its note |
budgets/pricing.py |
Per-model USD pricing of token counters, keyed by the provider and model ID usage records |
budgets/spend.py |
Month-to-date per-requester spend derived from retained usage |
budgets/caps.py |
Per-user monthly caps kept as runtime state under the storage root, written atomically and read lock-free |
budgets/monitor.py |
Month-to-date spend from background usage scans plus each finished reply's cost, the per-user cap store, and the fallback-model decision turn_model.py applies |
config/budgets.py |
Opt-in budgets: default monthly cap and fallback model |
session_storage/agent_storage.py |
Opens an agent's, a team scope's, or the system usage ledger's conversation store, naming its owner, and prepares each database file once per process: the preflight archive check, the link-refusing connect, the tables of a new database, the conversion of one in an older layout, and the layout version upgrade |
session_storage/store.py |
The conversation store: one SQLite database of sessions, runs with a row per stored message and per tool execution, summary rows, and the usage ledger, with full run saves refused once a run is final and single facts patched onto stored rows, each operation in one transaction on its own connection |
session_storage/schema.py |
File and table names, a team scope's database name, identifier quoting, table and column listing, and the layout of a conversation database: the sessions table, the six *_log_* tables, the meta row naming the owner, and the usage ledger with its upsert |
session_storage/summary_rows.py |
The conversation log's summary rows: compare-and-append of compaction chunks and mid-turn folds, the event ids each row covers, the tool calls folds took, and edit and redaction cuts with the snapshot a cut is decided from |
session_storage/usage_reader.py |
Read-only reads of a conversation database's sessions, owner, layout version, and usage ledger for usage reports, returning what is stored unchecked for the report to validate |
session_storage/codec.py |
A run record to its run row, message rows, and tool-execution rows and back, with the JSON keys stored runs carry, and the JSON decode that reads worker-written text without failing |
session_storage/types.py |
ConversationSession and the other values the store reads and writes |
session_storage/lanes.py |
One FIFO lane per conversation database for storage operations started from async code |
session_storage/legacy_agno2_runs.py |
Data older Agno releases stored: Agno 2 run blobs, rows without a position, and odd timestamps, which the conversion reads, and session JSON columns encoded twice, which the conversion reads and stores once |
session_storage/legacy_tool_results.py |
Tool results an earlier release stored combined in one message, split into one message per result when a database converts |
session_storage/legacy_agno3_conversion.py |
The one-way conversion of an Agno-layout conversation database to storage v2, run by a store open that finds an older layout and by the startup sweep over the session state root |
session_storage/legacy_agent_session_owners.py |
Agent session rows and runs that name an id other than their agent, set to the agent once, as layout version 3, by the agent's store open and the startup sweep |
session_storage/legacy_session_columns.py |
The layout version upgrade: session rows that named their kind and owner and held their state inside session_data convert once to layout version 4, whose meta row names the owner, with the team owner the startup sweep reads from the rows, and every database then takes the later steps to the current version |
session_storage/legacy_paused_runs.py |
Paused runs earlier releases stored with a paused notice as their content, Agno's summary block in their system message, or delegation calls that do not name the member run they wait on, rewritten once at layout version 6 and at the end of the Agno-layout conversion |
session_storage/legacy_conversion_backup.py |
The <name>.db.pre-storage-v2 and <name>.db.pre-storage-v4 copies a database gets before its conversions, after a free-space check, through no-follow descriptors |
session_storage/legacy_agno3_schema.py |
The Agno layout's table names, DDL, run-row decoder, and member-subtree delete, read only by the conversion and its Agno-era steps |
session_storage/legacy_usage_ledger.py |
The conversion's step that seeds the usage ledger of an Agno-layout database without one from its run rows and Agno 2 blobs |
session_storage/legacy_usage_totals.py |
The layout version 7 step that keeps the usage stored session totals held beyond their run rows as one undated pre_ledger ledger row |
session_storage/legacy_scope_metadata.py |
The layout version 7 step that moves the owner's per-scope force-compaction flag and preserved seen ids into one metadata value |
session_storage/legacy_run_requirements.py |
The layout version 8 step, and the Agno-layout conversion's decode, that fold each paused run's stored requirements into the tool rows they copy, so a paused call is stored once |
session_storage/legacy_compaction_state.py |
The conversion's step that turns earlier compaction state, the compaction archive, and unpositioned run rows into summary rows and positioned runs before they convert |
history/mid_turn_compaction.py |
Compaction between the model requests of one reply: the limit check, folding, and the scoped or run-local summary |
history/run_checkpoint.py |
A run's checkpoints, saved before each tool batch runs and before each later request, and the recovery that finishes a run cut short as a turn of its own stored messages with every call answered |
history/turn_recorder.py |
TurnRecorder: what one turn did, which the turn driver writes, and the interrupted-replay snapshot the driver stores when the turn stops |
history/legacy_stored_tool_calls.py |
Tool-call shapes earlier releases stored, which the conversion to storage v2 stores in the current shape in every message a converted run replays |
history/summary_message.py |
The compaction summary as a user message: its text, its scope or run-local marker, and the marker that replays the scope's summary after a mid-turn compacted prompt |
history/session_runs.py |
The follower background readers share: a conversation's Matrix turns in log order, read in one snapshot with what a redaction would cut, the due scan, backoff, and where a conversation never read starts |
history/ |
Persisted history: what a request replays from stored runs, the replay budget, compaction before and during a reply, summary rows, and interrupted-turn replay |
history/request_messages.py |
A model request assembled from a scope's stored runs, its compaction summary, and the current turn |
history/replay.py |
Materializes, estimates, and fits persisted history within one replay budget |
history/request_size.py |
The one sizing rule of every model request: the latest answer's reported size when the request extends that answer's request, else the route's estimate; and the frame a reply's requests hold around its history |
history/runtime.py |
Prepares a scope's history before a reply (replay plan and compaction check) and runs its mid-turn and run-local compactions |
history/compaction.py |
Scoped compaction: summarizing a scope's runs, or a running turn, into its summary rows |
token_counting/families.py |
The local token counter of each model: its own tiktoken encoding on routes serving OpenAI's models, else o200k_base scaled by a per-family margin; loads o200k_base in the background |
token_counting/counts.py |
Every token count, from the route's local estimate, with a stand-in while the vocabulary loads, and verified text fitting |
token_counting/requests.py |
How a route sizes and identifies a request from the parts its body builder renders: text, JSON values, and priced costs such as media allowances |
skill_learning/capture.py |
The final model request of a counting response, kept for the review to fork |
skill_learning/runner.py |
In-memory reply counts per conversation; starts a review when a count reaches the interval, stops it when a new response starts, and posts change notices |
skill_learning/reviewer.py |
One bounded skill review: a fork of the response's final request with its tools unchanged, or a redacted digest replay when the request cannot be forked or another review model is set |
skill_learning/tools.py |
Skill tools shared by chat and the review: ownership, read-before-write, and landed-change tracking |
skill_learning/transcript.py |
Reply counting and the digest a replayed review reads: older turns shortened plus the newest messages verbatim |
skill_learning/library.py |
Confined workspace skill writes, ownership provenance, history snapshots, and archival |
listening/ |
Listening agents: durable per-room markers (markers.py), the polling service that hears rooms and decides when a silent turn is due (service.py), and the silent turn itself, which offers only listen.tools and never sends its text (turn.py) |
automations/runner.py |
Automation schedule loop: cron timing per shared agent or private instance, definition lookup and AutomationContext, the visible prompts tagged automation/<name> in the agent's room or the requester's personal room, and the steps after their runs |
automations/registry.py |
The @automation decorator, discovery in plugin hooks modules, and the catalog of plugin automations beside the lazily loaded built-ins, carried by the plugin snapshot (HookRegistry.automations) |
automations/steps.py |
AutomationContext, the Ask and Done steps an automation returns to the runner, the automation hook-source prefix, and the always-loaded workspace files the built-ins maintain |
automations/threads.py |
The record of threads automations started, under tracking/automations/, so none is read back as a conversation |
automations/prompt_curation.py |
The prompt_curation automation: size check over always-loaded files, the bounded prompt, and the verify that asks for a re-check |
automations/exploration.py |
The exploration automation: leads from conversations' tool calls, the prompt, and the follow-up that schedules ingestion |
automations/dreaming.py |
The dreaming automation: changed-input agenda, per-run staging of memory/, proposal validation, the fresh-thread review, and batch-conflict apply with progress in the automation state directory below tracking/ |
config/automations.py |
Automation entries (built-in and plugin) and their validation |
custom_tools/skill_manage.py |
Chat-time skill_manage, like Hermes' foreground tool, for agents that list it or learn skills |
session_storage/preflight.py |
Required session-column checks and retained archives for incompatible owned session stores |
agent_descriptions.py |
Shared agent description rendering for delegation and orchestration |
delegation/personas.py |
Agent-authored subagent personas: the authored prompt and tool, skill, and knowledge subsets, subagents/<name>.md workspace profiles, and the caller tool, skill, and knowledge checks |
delegation/activity.py |
The redacted, capped transcript, status, and usage of each running subagent (6,000 characters of text, 20 tool rows, 300-character previews), handed to its sink, which sends io.mindroom.subagents frames, at most every 250 ms off the child's path |
delegation/cost.py |
What the subagent turns whose results a turn received cost, collected while the turn runs, which its reply publishes as cost.subagents_usd and a child's settlement adds to its own cost |
delegation/direct.py |
Reserve, run, and settle one child turn inside the caller's tool call, shared by run_subagent and Dynamic Workflow subagent participants |
delegation/targets.py |
Turning a run_subagent or continue_subagent call into the child it starts or continues, for both the direct tools and the native driver |
delegation/workers.py |
Whether a caller may run a subagent in a dedicated worker, which options it is offered, and the placement each attempt of such a child binds |
delegation/legacy_records.py |
Delegation records whose working state lived only in their workspace files, left as they were |
delegation/legacy_snapshots.py |
Delegation child snapshots stored without a field a later release added, rewritten once in subagent session files at startup and in runs' metadata as conversation layout version 5 |
credentials/manager.py |
Credential stores (CredentialsManager) and credential_layers, the one resolver of where a service's credentials are read and written for a target |
credentials/policy.py |
Each credential service's placement per worker scope, and whether workers may receive it by grant or lease |
credentials/environment.py |
Credentials the environment declares (provider keys, bootstrap values, seeds), read by the primary under its saved ones |
matrix/ |
Matrix protocol integration (client, users, rooms, presence, provisioning, message formatting) |
matrix/room_thread_mode.py |
Router-owned effective room thread-mode state for client view selection |
matrix/room_accounts.py |
Router-owned room state listing the joined MindRoom accounts, so clients recognize agents by any user name |
matrix/state.py |
matrix_state.yaml accounts, rooms, space, and server emoji room, changed only through update_matrix_state |
matrix/large_messages.py |
Large-message sidecar storage and retrieval for oversized Matrix payloads |
matrix/server_features.py |
The unstable features a homeserver lists in /_matrix/client/versions |
matrix/user_masquerade.py |
HTTP-only client that acts as one person through an application service's token and marks each message event, redaction, and state event it sends as the agent's |
matrix/segmented_messages.py |
Lossless splitting of oversized text responses into ordered rich-text events (defaults.large_message_strategy: split) |
matrix/durable_ingestion.py |
Owned Nio batch validation, journal admission, and acknowledgement |
matrix/sync_continuity.py |
Durable pending join-fence persistence |
matrix/journal_ingress.py |
Typed event classification and replay parsing using Nio provenance |
matrix/message_content.py |
Canonical extraction and sidecar resolution for received Matrix messages and edits |
matrix/message_builder.py |
Message content building helpers |
matrix/guarded_rooms.py |
The one room a task context may send into only from an allowed scope, checked by every Matrix send: a contact turn guards its contact room, and matrix_message allows the sends its contact policy approved |
matrix/provisioning.py |
Hosted provisioning client flow used for local pairing and server-side agent registration |
matrix/provisioning_heartbeat.py |
Best-effort startup and periodic "last seen" heartbeat from paired installs to the hosted provisioning service |
matrix/provisioning_env.py |
Slim environment readers deciding whether a hosted install registers by token, shared secret, or pairing, plus the paired-install client-credential headers (no Matrix/HTTP imports) |
matrix/image_handler.py |
Image message download, decryption, and AI processing |
matrix/media.py |
Shared Matrix media encryption preparation, upload, download, and decryption helpers |
matrix/encrypted_file.py |
Dependency-free encrypted-file serialization shared by uploads, desktop, and runtime media |
matrix/room_cleanup.py |
Orphaned bot cleanup from rooms |
matrix/personal_rooms.py |
Target-agent service for eligible personal-room creation, ownership checks, invitations, and recoverable welcome delivery |
matrix/personal_room_store.py |
Durable per-requester room ownership, operator adoption attestations, welcome receipts, and cleanup retention |
matrix/event_info.py |
Event metadata parsing |
matrix/thread_membership.py |
Canonical Matrix thread identity and transitive relation membership |
matrix/projected_thread_membership.py |
Thread-root proofs for tools and outbound mutations, read from the conversation projection like turns |
matrix/thread_forks.py |
Forked threads: the parent chain's messages up to each fork point in front of a fork's reads, fork-root detection, and the parent threads a fork's attachments may come from |
matrix/identity.py |
Matrix ID parsing and utilities |
matrix/mentions.py |
Matrix mention formatting |
matrix/joined_members.py |
A room's joined members, read again while the durable client refuses a read that a membership change raced |
matrix/member_display_names.py |
Current member display names snapshotted from the synced nio room cache for model-facing <msg> tags |
matrix/typing.py |
Typing indicator utilities |
matrix/avatar.py |
Avatar management |
commands/ |
Chat command parsing (!help, !schedule, !config, etc.) |
commands/config_commands.py |
Chat-based config commands (!config) |
commands/config_confirmation.py |
Interactive config confirmation workflows |
voice/handler.py |
Voice message download, transcription, mention normalization, and ASR cleanup; transcribe_speech, the speech-to-text call transcripts share |
voice/openai_realtime_speech.py |
OpenAI text-to-speech through the Realtime API, shared by voice messages, the openai toolkit, and cascaded calls |
call_transcripts/service.py |
The rules of a call between people: who is in it, who may join or act on it, Pause, speech and its limits, its end, and each call's one task posting its row, its transcript message and the row's edits for the end and that message; and a call with an agent read as a live call, after any call between people in its room |
call_transcripts/store.py |
The SQLite store of live and recently ended calls between people, their lines until the transcript message is posted, what each call's row was last edited to say, who paused each call, and when each person's app last checked in to each call |
call_transcripts/wav.py |
The duration of an uploaded stretch of speech, read from its 16-bit PCM mono WAV header |
call_transcripts/router_room.py |
The router's side of calls between people: who is in a room, who may post there, display names, the row, its edits and the transcript message it posts, each at most once per call, and the request that the router title the row's thread from the notes |
call_transcripts/routes.py |
/api/call-transcripts/v1 for MindRoom Chat with client sessions: join and heartbeat, leave, Pause, speech read into memory only, and the live call with the lines added since the last poll; 404 while call transcripts are off, except the live call in a room an agent answers calls in |
call_transcripts/transcriber.py |
Speech-to-text of one stretch of a call through transcribe_speech, recording its usage |
call_transcripts/notes.py |
A finished call's notes from calls.transcripts.notes_model: what it was about, decisions, action items, and open questions |
matrix_rtc/realtime_tts.py |
LiveKit TTS for cascaded calls on gpt-realtime models |
matrix_rtc/audio_process.py |
Main-process side of a GPT-Live call whose media runs in its own process, plus the idle process started ahead of the next call |
matrix_rtc/audio_child.py |
Child process that runs one GPT-Live call's LiveKit room, frame encryption, and agent session away from the MindRoom event loop |
matrix_rtc/audio_protocol.py |
Length-prefixed JSON frames between MindRoom and a call's audio process |
tool_system/agent_tools.py |
The toolkits one agent may use per turn (AgentTools.candidates) and where each runs |
tool_system/sandbox_proxy.py |
The one tool placement decision (ToolPlacement) and the proxy that routes worker calls |
api/sandbox_request_cancellation.py |
Stops an in-flight sandbox runner request when the primary stops waiting for it |
api/sandbox_execute_stream.py |
Streams one runner call's progress and keep-alives before its result, and stops the call when the primary hangs up |
api/worker_preview.py |
Dedicated-worker runner routes that list the ports the worker's own apps listen on at its loopback and relay the primary's HTTP requests and WebSockets to them, or to a plugin's running worker service with its secret, refusing other containers' servers and the runner's own port |
previews/listeners.py |
Lists the TCP sockets listening on this machine's ports, through the kernel's socket diagnostics or /proc/net, and whether only the runner's process tree or cgroup, or one process group, holds them |
previews/relay.py |
Passes one WebSocket's messages both ways between an accepted socket and a client socket until either closes |
api/worker_services.py |
Dedicated-worker runner routes that start, report, and stop plugins' worker services, each with its process group, port, secret, and idle timer |
plugin_worker_relay.py |
The primary's client of a dedicated worker's runner relay, which plugin routes and tools open through plugin_http.worker_relay to reach their worker services by name or the agent's servers by port |
worker_computer/agent_browser.py |
A worker service's own CDP session on the agent's browser page: an allowlist of watching commands, acting ones only under the Computer's control lease, following the agent between pages, and releasing held input |
plugin_worker_services.py |
The primary's side of plugin worker services: the declaration plugins import, ensure and stop through the target's worker, and stopping the started ones when plugins reload or MindRoom stops |
tool_system/progress.py |
Live progress a running tool call reports to whatever owns it |
tool_system/dedicated_threads.py |
One thread per blocking call of a background job or worker proxy call, outside the bounded shared pools |
workers/in_flight.py |
Workers with a call in flight, which idle cleanup refreshes before it runs |
workers/placements.py |
The sessions whose worker-routed calls run in a dedicated subagent worker, bound for each attempt of such a child |
workers/protocol.py |
The typed requests and responses the primary and its sandbox runners exchange, and the worker protocol version both check |
workers/backend_kinds.py |
The worker backends MINDROOM_WORKER_BACKEND can select, the one table of its accepted values, and which backends are dedicated |
workers/progress.py |
Warmup progress of the workers a dedicated Docker or Kubernetes backend starts, sent to every caller waiting on the same worker |
workers/backends/dedicated_launch.py |
The runner environment and startup manifest every dedicated Docker or Kubernetes worker starts with, from its backend's container layout |
shell/output_capture.py |
Bounded shell output spools, completion validation, and atomic output-file publication |
shell/execution.py |
Shell command execution core: spawning, output buffering, stopping at a timeout, and the handle registry of Desktop shell and script runs |
shell/supervisor.py |
Worker-local shell supervisor process that runs shell commands and script handles for sandbox request subprocesses, stopping a command whose relay dies |
terminal/session.py |
Persistent shells in a pty in the sandbox runner: scrollback, attached viewers, input, resize, and the idle end |
api/worker_terminal.py |
Runner routes that open, list, and close an owner's terminals, and the websocket a viewer attaches with |
terminal/client.py |
The primary's client for an agent's terminals, reached with the request its worker-routed shell toolkit would send |
terminal/lines.py |
Each terminal's input line as the primary saw it typed and prompted, so terminal_run types only at an empty prompt |
terminal/resolution.py |
The terminals of an agent's workspace as its turn for one requester resolves them |
custom_tools/terminal.py |
The agent's terminal toolkit: open, run, type keys, read, and list, offering typing only while its shell commands never ask for approval |
api/agent_terminals.py |
Chat clients' routes to the terminals of the agents they may use in a room, and the rechecked terminal stream |
api/agent_streams.py |
What an agent's terminal stream and workspace change stream share: the recheck of the caller, running the stream's parts, and close codes |
streaming.py |
Streaming state machine: placeholder, progressive edits (durable checkpoints while live frames run), tool traces, reasoning, and the terminal write of a stream that finished; a stopped or failed stream raises for its span exit to end |
live_frames/frames.py |
The io.mindroom.live frame format: snapshots and UTF-16 splice deltas of a reply's live documents, and the durable checkpoint watermark key |
live_frames/publisher.py |
One streaming reply's frame loop: a frame per tick when its documents changed, periodic snapshots, and the watermark its durable writes carry |
live_frames/transport.py |
Whether the homeserver relays live frames, whether a frame fits the size limit as it goes out, and sending one frame, Megolm-encrypted in encrypted rooms, over the MSC2477 ephemeral route |
live_frames/subagents.py |
The io.mindroom.subagents frame format of a sub-agent run's transcript and status, and the publisher that sends the runs one account shows in a room within one budget |
prompts.py |
Built-in prompt defaults and prompt override registry |
attachments/storage.py |
Attachment persistence, registration, and context-scoped resolution |
attachments/ids.py |
Leaf attachment-ID helpers kept free of matrix-client imports |
attachments/media.py |
Convert attachment records to the model media values in llm/media.py |
media_inputs.py |
Shared media-input container passed across bot, teams, and AI layers |
api/ |
FastAPI REST API (dashboard, credentials, OpenAI-compatible endpoint) |
api/app_state.py |
One API app's state: what it owns itself, and the one EmbeddedRuntime value mindroom run lends it while it serves |
api/auth_user.py |
The typed login of one API request and the one rule for which Matrix user it acts as |
api/open_access.py |
Host allow-list and browser-origin guard for requests served without a credential (open dashboard auth, unauthenticated /v1) |
api/slack_events.py |
Public POST /api/slack/events: verifies Slack's signature, answers url_verification, and delivers events within Slack's 3-second limit, finishing slower deliveries in the background |
api/request_body_limit.py |
Pure ASGI middleware answering 413 for request bodies over 16 MiB on the dashboard API, except knowledge uploads, and on the plugin origin listener |
api/validation_errors.py |
422 handler for the dashboard API and sandbox runner that returns FastAPI's validation error detail without the rejected request values |
api/budgets.py |
Dashboard and budget-service routes for budget status and setting or clearing one user's cap |
api/usage_export.py |
Application-scoped usage-export preparation: one background scan, a bounded cache for daily/request-detail variants, committed-generation validation, and non-blocking shutdown cleanup |
custom_tools/ |
Built-in custom tool implementations (gmail, calendar, scheduler, etc.) |
custom_tools/microsoft_graph.py |
Shared Microsoft Graph client for the Microsoft 365 tools: requester tokens, error codes, and workspace downloads and uploads |
custom_tools/todo_state.py |
Leaf storage, the stored item shape and its strict reader, and actionability primitives for native per-thread todo state |
custom_tools/todo_poke.py |
Native scanner and background worker that wakes idle agents with actionable assigned todos |
custom_tools/todo_template_render.py |
Full-Jinja rendering of workspace todo templates in a short-lived, memory- and CPU-limited child process |
custom_tools/calculator.py |
Agno calculator with bounded factorial() and is_prime() arguments |
custom_tools/sleep.py |
Agno sleep toolkit with pauses capped at 300 seconds |
thread_export/workspace_sync.py |
Always-on debounced runner that keeps <workspace>/thread_exports/ current through the live bots' clients and journal principals |
background_tasks.py |
Background task management for non-blocking operations, and SupervisedLoop, which restarts a crashed long-running loop with backoff |
desktop/session.py |
Owns the desktop device's durable NIO session and storage binding |
desktop/transport.py |
Polls owned to-device work and acknowledges only after durable command admission |
desktop/command_journal.py |
Persists command admission, execution outcomes, and pending responses |
desktop/legacy_command_journal.py |
Validates historical JSON v1 receipts for the SQLite journal's one-time import |
desktop/bridge.py |
Enforces current local authority, routes app input, folder, and shell actions to their owners, runs browser actions, app launch, and app observation, and coordinates serial execution and response delivery |
desktop/command_parameters.py |
Parses the typed, length-bounded parameters of desktop commands |
desktop/reply_fitting.py |
Builds desktop success replies and fits trimmed replies within one encrypted to-device message |
desktop/file_actions.py |
Runs desktop folder listings and reads and fits them into one reply |
desktop/gui_actions.py |
Runs desktop app input actions (semantic element actions, pointer, text, scroll, and key chords) through the local GUI provider |
desktop/shell_actions.py |
Runs desktop shell actions, reports local and caller-scoped shell status, and delivers output inline or as an encrypted attachment |
desktop/bridge_session.py |
Opens, starts, and closes one Desktop bridge run (Matrix device, capability providers, bridge, admission, and workers) in one order, shared by the app helper and the terminal |
desktop/filesystem.py |
Bounded, descriptor-confined reads from explicitly selected local folders |
desktop/shell.py |
Runs locally approved desktop shell commands through MindRoom's shell engine |
desktop/login_environment.py |
Captures the account's login-shell environment once for locally approved desktop commands |
desktop/shell_prompt.py |
Local terminal approval for shell commands requested through a terminal-owned Desktop bridge |
desktop/observations.py |
Bounds observation references by requester, agent, session, application, and age |
desktop/displays.py |
Maps verified logical display bounds to capture pixel scale |
desktop/input.py |
Defines the allowed application-local keyboard and scroll inputs |
desktop/macos_input.py |
Sends bounded Quartz pointer input in global logical coordinates |
desktop/macos_capture.py |
Captures verified windows and displays through ScreenCaptureKit |
desktop/native_config.py |
Validates and persists private native-helper configuration |
desktop/native_protocol.py |
Parses and bounds requests on the local NDJSON channel |
desktop/native_host.py |
Owns helper setup, runtime lifecycle, local control, and stdio dispatch |
desktop/local_dashboard.py |
Validates the loopback dashboard URL and provides its credential through the private native-host pipe |
desktop/startup_errors.py |
Translates desktop startup failures into actionable protocol errors and recovery advice |
desktop/native_entry.py |
Starts the packaged native desktop helper |
tool_system/events.py |
Tool-event formatting and metadata for Matrix messages |
tool_system/call_record.py |
Context-scoped recorder the tool hook bridge tells of each tool call before it runs, which reply spans persist |
tool_system/declarations.py |
Leaf tool metadata enums and dataclasses shared by implementations and the runtime catalog |
tool_system/registration.py |
Leaf built-in and plugin tool registration surface |
tool_system/metadata.py |
Tool construction from a ToolRegistry, authored override validation, and metadata export |
tool_system/runtime_context.py |
Shared runtime ContextVar for tool calls (including attachment scope), the identity a call runs as (current_execution_identity, detached and team-member scopes), and the hook bindings a turn carries |
tool_system/tool_function.py |
The tool values, free of Agno: ToolFunction, the only tool shape the agent loop sees (finished schema, the gate that says why a call waits, the stop flag, entrypoint, what each injected parameter receives) and the owner of how a call of it pauses, AdaptedToolkit, ToolValue, a finished tool value's text and media, and ToolOutcome, a call's value with its stop and failure flags |
tool_system/authoring.py |
MindRoom's Agno-free tool authoring API, which MindRoom's own tools use and plugins import: Toolkit, @tool, passthrough_tool for a function offered with the schema it authors, current_call() for the call a function runs for, and toolkit_functions() for a toolkit's callables by name as a run calls them |
tool_system/tool_schema.py |
Derives the description and parameter schema of every tool function whose signature gives them, MindRoom's own and Agno toolkits' alike, from its docstring and annotations, as Agno derives them for the annotations in use except that Any and object take any JSON value and *args and **kwargs stay out of the schema, and validates a call's arguments against them |
tool_system/agno_toolkits.py |
Adapts Agno and owned toolkits and functions to ToolFunction, applying the function filters, output files, and worker stand-ins their builder configured, and, besides the vendor toolkit subclasses and the Google auth binding in oauth/agno_compat_google_auth.py, is the only module that looks inside an Agno toolkit: its function names, one function by name, renames, and connection; builds the Agno-shaped call-time arguments (run context, actor stand-in) vendor entrypoints expect, and reads the Agno ToolResult a vendor tool returns or streams as a ToolValue |
tool_system/toolkit_connections.py |
Connects the requires_connect toolkits, such as Postgres, around each run that offers them, and holds the per-call toolkit lifetime (connect, owned bodies, close, retained cleanup) the script broker and MCP gateway share |
tool_system/invocation.py |
Decodes a model's tool-call arguments, runs one call through middleware to its outcome for the loop or to the tool's own value for runners outside it (injection, synchronous offload, generator draining, error text), and reads that value as the text and media references a runner hands its client |
tool_system/tool_hooks.py |
MindRoom's tool-call policy as middleware around every call: plugin before-call, environment, and after-call hooks, the background-script approval gate, job and authority checkpoints, durable call recording, and failure records |
tool_system/tool_environment.py |
The environment one tool call gives its shell commands, local or worker-routed: the plugin hooks' changes with the response's CLI grant over them |
llm/ |
Provider-neutral values the runtime shares: messages, media, usage, run records and the pause requirements read from their tools, run events, the ModelProvider protocol, and normalized provider errors, with the dict keys stored runs carry |
llm/legacy_run_content.py |
The content a failed run earlier releases stored: its failure text in place of the model's, handed over redacted |
llm/tool_search.py |
Portable deferred tool search for routes the build marks portable: the pipeline stage that leaves deferred schemas off the request and shows stored deferred calls as call_tool calls, the loop's rewrite of a model's call_tool calls to the functions they name, and the argument parsing both share, which every wire that sends tool-call arguments as an object uses to replay a call another provider stored |
agent_loop/model_loop.py |
run_model_loop, the request and tool loop agents, team leaders, and skill reviews share: send the messages, append the answer, run its tool calls, and stop on a final answer, a stopping tool, a pause, a hook, the request cap, or a tool the model keeps calling after its refusal for failing |
agent_loop/run.py |
run_agent and resume_agent: agent runs and approval resumes over the model loop, each ending in one terminal record handed to the persist callback before the run ends |
agent_loop/spec.py |
AgentSpec and RunContext: what an agent run is built from and the run's own identity |
agent_loop/tools.py |
The tools a run offers, and one assistant message's tool calls planned, run, and answered: resolution, the tool-call limit, refusal of a tool that keeps failing, pause classification, and result messages |
agent_loop/build.py |
AgentBuild, what create_agent produces for the loop, and prompt_for_turn, its stable and turn system messages with one turn's context appended to the turn one |
agent_loop/prompt.py |
PromptSpec and render_system_messages: an agent's system prompt from named sections, as a stable system message and a turn system message |
agent_loop/structured.py |
The schema-derived JSON prompt a JSON-mode route needs for an output schema, the answer text of a forced-tool route's forced call, and parsing answers into the schema: strict where the route enforces the schema, with repairs only on JSON-mode routes |
agent_loop/helper.py |
complete_prompt: one helper request, without the caller's tools, whose system message is its instructions as written, optionally read into a schema, with the call's content-free usage (HelperUsage), which the caller records through helper_usage.py |
agent_loop/output_limit.py |
output_limit_policy: answers the tool calls of a response the output limit cut off instead of running them, and fails the run on the third cut-off response |
tools/agno_compat_*.py, custom_tools/agno_compat_*.py, and oauth/agno_compat_google_auth.py |
Repairs of Agno toolkits and of Google auth's toolkit binding; see docs/architecture/agno-compatibility.md for the boundary inventory and upstream tracking |
constants.py |
Shared constants, paths, and environment variable defaults |
error_handling.py |
User-friendly error message extraction |
authorization.py |
Sender and per-agent authorization checks |
room_agent_access.py |
The room access check the worker Computer and plugin routes share, and each admitted agent's workspace root and file and terminal access for one caller in one room |
api/agent_profiles.py |
GET /api/rooms/{room_id}/agents/{agent_user_id}/profile: an agent's role, the model it runs in the room, and a catalog of the toolkits its config gives its Matrix turns there (registry names, descriptions, categories; no toolkit is built), for Chat's agent card |
api/workspace_files.py |
Chat clients' /api/rooms/{room_id} routes to the workspaces of a room's agents: list them, read and change their files, follow changes |
workspace_files/operations.py |
The file operations behind those routes, confined to the workspace without following links out, and the credentials they hide (is_hidden) |
workspace_files/watch.py |
One scanner per workspace that feeds its change streams the changed paths, scanning without following links |
access_policy.py |
Resolve membership access config into immutable effective room and responder policies |
config/access.py |
Membership access configuration models (responder access, room defaults) |
config/legacy_access.py |
One-shot migration from retired access fields to the membership schema; delete with the retired fields |
thread_utils.py |
Thread analysis and agent detection |
session_ids.py |
Leaf helpers for the canonical persisted room/thread session ID |
turn_model.py |
The model one turn runs: explicit choice, thread and room overrides, authored model, the team rule, then the budget fallback |
thread_models.py |
Durable per-thread model overrides backing !model and the thread_model tool |
room_model_overrides.py |
Durable per-room runtime model defaults backing !room_model |
room_reply_modes.py |
A room's reply mode override, its reply_mode room setting in room state, backing !reply_mode, plugin routes and clients |
room_modes.py |
The one path !thread_mode and plugin routes take to change a room's thread mode override and republish it |
file_watcher.py |
File change detection for config hot-reload |
interactive.py |
Interactive Q&A system via Matrix reactions |
stop.py |
SpanRegistry: cancels exactly the reply span a Stop reaches; the Stop button reaction |
topic_generator.py |
Managed room topics from the configured description or generated with AI |
debug_report.py |
Read-only collection of what the backend stored about one reported conversation: event journal, stored runs, tool-call and LLM request logs, and log lines |
cli/main.py |
Main CLI entry point (Typer app) |
cli/banner.py |
CLI startup banner |
cli/config.py |
Config subcommand logic |
cli/connect.py |
mindroom connect pairing helpers and owner placeholder replacement |
cli/debug_report.py |
mindroom debug-report command: bug report parsing, config-only storage location, and JSON output |
cli/doctor.py |
Doctor command implementation |
cli/help_format.py |
Help-page panel order, green help theme, and the examples epilog shared by CLI commands |
cli/interactive.py |
Arrow-key prompts and step headers for terminal setup, with line prompts for piped input |
cli/local_stack.py |
Local stack setup command |
credentials/sync.py |
Shared provider keys, the embedder key, and the Ollama host as the runtime resolves them |
logging_config.py |
Structured logging setup |
knowledge/utils.py |
Resolves the knowledge bases an agent searches: published indexes, availability notices, and refresh scheduling |
custom_tools/chat_ui.py |
Runtime-bound MindRoom Chat UI action requests with canonical Matrix conversation and sender identity |
custom_tools/react.py |
Reaction-only agent tool: reacts in the current room under matrix_message's per-room rate limit |
custom_tools/matrix_user.py |
The matrix_user toolkit: a personal agent reads Matrix as its owner, and writes as them, on a client created per call |
custom_tools/matrix_user_authority.py |
Whom a matrix_user call acts as: the owner of the personal agent making it, decided by the call's identity and room alone |
custom_tools/matrix_user_reads.py |
What matrix_user_read reads as the owner: rooms, messages, search, people, files, and read markers |
custom_tools/matrix_user_writes.py |
What matrix_user_write does as the owner, one event per call: a message or a file, a reaction, an edit, or a redaction, each sent marked agent-authored, and joins, leaves, invitations, and new rooms, which carry no marker; a send to a person uses their existing DM and never makes one; logs one audit line per write |
custom_tools/stop_reply.py |
Agent tool that stops another agent's reply with a 🛑 reaction relaying the caller's requester |
custom_tools/shared_directories.py |
Agent tool that creates shared directories, invites agents at once on behalf of a user who may use them or as pending invitations otherwise, and accepts or declines invitations through the invited agent |
shared_directories/ |
The primary-only membership ledger and storage of shared directories, the paths agents see, and the share roots filesystem accepts |
custom_tools/thread_move.py |
Copies a thread into another room as a new thread: per-entity re-posts, mention-guarded router relays, tag copy, and the moved notice in the source thread |
custom_tools/computer_announcement.py |
Tool hook that shows a chat_ui agent's worker computer in MindRoom Chat on its first worker browser call in a conversation |
tools/react.py |
Tool-catalog registration for the reaction-only tool |
tools/chat_ui.py |
Tool-catalog registration and discovery metadata for Chat UI actions |
voice/visible_voice_echo.py |
Immediate router voice-placeholder delivery, replacement ordering, and deduplication |
avatar_generation.py |
Generates and manages avatar assets for agents, rooms, and spaces |
slack/ |
Native Slack: the minimal Web API client, personal and project tools, events, and agent reply mirroring |
slack/api.py |
Minimal async Slack Web API client over httpx, with Slack error and rate-limit mapping, parsing of conversation, message, permalink, and user targets, and message permalinks |
slack/app.py |
The Slack app's workspace-wide credentials from the shared credential store, and the bot identity auth.test reports for them, cached per bot token |
slack/events.py |
Pure Slack event handling: the signing-secret check, which Events API messages may wake anyone, the thread keys, which project agent answers an event, and which personal watches an event may be for |
slack/files.py |
Slack file transfers: a download from Slack's file host, refused past 50 MB and written into the workspace's slack-downloads/ without following links, and the external upload flow, which never sends the token to Slack's presigned upload link |
slack/identity.py |
Maps a Slack author to a MindRoom account: the Slack display name and, for full workspace members whose profile email is in slack.email_domain, the Matrix user ID from slack.matrix_user_id_template; cached for ten minutes per team and user; also looks up a channel with conversations.info, cached the same way for names but fresh for deciding whether the app may act there, and holds that project channel rule |
slack/integration.py |
Slack's entry in the integration registry: the events route, the runtime those events reach bound to the live bots, project-turn reply mirroring, and the Slack config checks; it loads the Slack runtime only on first use, because config validation reads the registry |
slack/oauth.py |
The built-in slack OAuth provider: each requester's own Slack user token requested as user_scope, accepted only from the workspace the bot token belongs to |
slack/render.py |
Plain dictionaries for agents from Slack answers: messages with author names and permalinks, people, conversations, and the display-name rule; Slack message markup as plain text |
slack/delivery.py |
Delivers a Slack event to the project agent answering its channel, while the app is still in it, as the mapped author, then to personal watches; retries after the route acknowledged, reacts 👀, and sends notices only the author sees |
slack/turns.py |
Posts a Slack message as one target agent's own hook dispatch, mentioning only that agent with the Slack text fenced as plain text; claims each message once per target and keeps a Slack thread on its Matrix thread |
slack/reply_mirror.py |
Posts the final reply of an agent's Slack project turn into its Slack thread as the app, in the background after the Matrix reply; only a managed account's hook dispatch whose Slack thread delivery bound to this room and Matrix thread, in a channel and room the agent currently answers |
slack/watch_delivery.py |
Delivers a Slack event to the personal watches it is for, once Slack confirms the owner can see it and while the watch room may receive it |
slack/watches.py |
Personal Slack watches: the durable store of who receives which Slack mentions and direct messages in which room, the check that a room holds only the owner and MindRoom's accounts and hides earlier messages from people who join later, and the slack_watch actions that start, stop, and report a watch |
custom_tools/slack.py |
The slack toolkit: personal calls with the requester's own Slack user token, project calls with the app's bot token only in listed channels the bot belongs to; search, recent conversations, read, post, edit, delete, react, workspace downloads and uploads through slack/files.py, rendered by slack/render.py; in a personal toolkit built for a Matrix room, slack_watch runs the watch actions of slack/watches.py |
Persistent State
Data Persistence lists the main directories under the storage root (mindroom_data/ by default, overridable via MINDROOM_STORAGE_PATH).
An agent's conversation database is agents/<agent>/sessions/<agent>.db, and private agents keep the same per-agent layout under their resolved private state roots.
Its tables are named after its sessions table <agent>_sessions: _log_runs holds a row per run, _log_messages a row per stored message, _log_tools a row per tool execution, _log_summaries the compaction summary rows, _log_removed the runs that edits and redactions removed, _log_meta the layout version, run counter, and owner, and _usage the usage ledger.
A database converted from the Agno layout keeps its pre-conversion copy beside it as <agent>.db.pre-storage-v2, and one converted from layout version 2 or 3 as <agent>.db.pre-storage-v4.
tracking/personal_agents.json is the roster of agents generated from personal_agents templates, read on every config load.
tracking/contacts.json holds the contacts between personal agents and people, written only by the primary.
tracking/listening_markers.json holds where each listening agent has heard each listened room up to.
call_transcripts/calls.db holds live and recently ended calls between people, each call's lines until its transcript message is posted, what each call's row was last edited to say, who paused each call and since when, and when each person's app last checked in to each call.