Internals

A map of the source tree for contributors: how the modules depend on each other, how one turn travels through them, where state lives, which rules are enforced by a single named predicate, and what each host offers. The code is the reference; this page says where to look. Every name here was checked against the tree when it was written, so if a name is missing, grep for it before assuming the page is right.

Layering

The tree reads top-down. Each module calls the ones below it and never the ones above or beside it, and tests/layering.rs scans every crate:: path in production code to keep it that way. Every top-level module has a rank there; an edge may only point at a strictly greater rank. The tolerated list is empty. One upward edge is by design, tools/subagent.rs building an Agent, because a sub-agent is an agent.

rank  module          holds
 0    main            argument parsing; picks a host or a cli handler
 1    host            the layer between a host and the agent, and the four hosts under it
 2    cli             clap definitions and one handler file per subcommand group
 2    relay           tracing output routed to the screen, or to stderr
 3    installation    the doors that edit config.toml and the credential rows: accounts, profiles, MCP servers
 4    render          the screen's rows and markdown layout, the approval block, status lines, the one-shot's answer
 5    agent           the turn loop, tool dispatch, compaction, recovery
 5    view            the JSON record shapes --format json and the HTTP API share
 6    tools           the Tool trait, the registry, the built-ins, MCP tools as Tools
 7    prompt          the system prompt and the per-turn context block
 8    session         the materials a session is built from, and its live cells
 9    scheduler       the sweep that claims due jobs and hands a Wakeup to a host
 9    background      tool calls the agent starts and does not wait for
10    mcp             the MCP client: connections, published tools, progress, auth
11    provider        the Provider trait, wire types, the registry, one backend per API
12    frontend        the Frontend trait, its events, and the two generic frontends
12    skills          skill discovery and loading
12    instructions    the standing instructions file
12    oauth           expiry, refresh, the refresh lock, PKCE, the person's side of a browser login
12    sandbox         read-only confinement for shell_execute
13    workspace       cwd, roots, the write fence, private-directory refusals
13    tokens          token estimates for the gauge between provider reports
14    store           every SQL statement, behind one connection owner
15    schedule        what a scheduled job is: parsing, gates, the scheduler's memory
16    conversation    the event-log conversation and its title
16    stats           per-session counters
16    config          config.toml, ResolvedConfig; profile.rs holds accounts and profiles
16    memory          the memory entry
17    entry           what skills and memories share: an indexed entry
17    permission      levels, the enabled set, the shared cell, the approvals switch
17    checklist       the checklist: items, states, the open rule
17    image           format detection and transcoding
18    fs              private directories, atomic replace, file locks
18    process         the one door for every process meka starts: behind meka for memory
19    error           MekaError
19    sync            locks that outlive a panic
19    streams         raw stderr
19    paths           the config and data directories
20    text            pure text helpers: widths, columns, sizes, timestamps, unknown_name

relay is installed by main.rs as tracing’s writer; the screen drains it, and every other run writes it to stderr. render is reached only from host and cli. text is the lowest leaf so that error can render MekaError::ProfileNotConfigured through text::unknown_name.

Put new code where its callers already are: a type read by store and host belongs in store or below, never in host. A new module fails the test until it is given a rank.

One turn

A host admits the turn, the agent runs it, and everything the user sees comes back through a Frontend.

1. Admission. A ResidentSession counts its work in one cell, in_flight, and holding the conversation mutex is what “a turn is in flight” means. HTTP and ACP admit a typed prompt with admit_turn, which hands back a TurnGuard and samples the cancel epoch; HTTP wraps it in host::http::state::admit_turn to add the process-wide cap. A scheduled fire, an outcome delivery or an inbox turn goes through HostHooks::admit, which under serve counts on the same cap and steps back for the next tick when it is full; HTTP compact and rewind take claim_idle, which refuses while anything is in flight. The screen and the one-shot drive one session from one thread, so they sample cancel.admit() themselves and take the conversation lock.
2. Input. The host builds a TurnInput: the typed prompt or the outcomes it carries, images, and the retention, which the scheduler sets per job and the HTTP turn takes from the request. TurnInput::from_parts is the empty-prompt rule, raising MekaError::EmptyPrompt before admission.
3. The loop. Agent::run_turn appends one user message of two blocks: a TurnContext block holding everything meka injected (permission and environment context, world state, budget, background outcomes, the resume notice) and a Text block holding the words as typed. Providers render the first as text ahead of the second; exports, GET /history, replays and the title read the words. It then sends a CompletionRequest and dispatches every tool call the response carries. admit_arguments type-checks the call’s arguments and takes out background, the flag that detaches it; admit_tool_call decides run, ask or refuse. Each call gets a ToolContext: the session id, the tool-use id, the prompt id, the frontend and the cancellation token. Every request carries the conversation whole; the context ceiling and compaction are its only bound. The world state’s [Tool discovery] index is bounded like the skills and memory indexes, in prompt::render_tool_discovery: summaries while the section fits 8 KB, names past it, and past 200 names a count that points at tool_search. Root agents and sub-agents share this per-turn renderer over their own registries. Workers receive permitted server instructions and granted memories here; their system prompts carry the role and granted standing instructions, without repeating active tool descriptions. Skill updates use the same bounded renderer as the initial skill index. The execution context states the active profile’s image-input capability and whether the host can deliver later turns. admit_tool_call lives in tools, where tool_search and tool_load consult it to say what a call would do before the model makes it.
4. Recovery. A failed request goes through TurnRecovery, which decides between a retry, a degraded resend and a reported failure. A rejection that MekaError::rejects_thinking_signature names, Claude rejecting a thinking block sent back, is answered first, by a resend of the conversation since the last compaction with Message::without_claude_thinking applied, recorded as an Event::Unsign that names no message; a compaction’s checkpoint and summarizer do the same to their own copies. Once a profile’s retries are spent on an error that says the profile cannot serve (MekaError::is_profile_unavailable), agent::fallback opens that profile’s breaker in the ProviderRegistry, binds the next profile in its chain the turn has not tried, breaker or not, and re-sends under the retry’s own no-output guard; the turn’s end restores the named profile and its row records the one that served. The published profile cell holds both the named profile and the one serving, so a worker spawned mid-turn binds to the named one and a repin ends the substitution. Compaction runs when the context gauge says so, when the model asks through context_compact, or when the user asks. A checkpoint’s request carries the turn’s own tool list, so it shares the turn’s cached prefix; its guidance names the subset it may call, and a call to the rest is refused at dispatch. Every summary, from the checkpoint or the summarizer, has the same four sections: rules and authorizations, commitments and their state, facts established, next action; a compaction-specific focus adds emphasis within them and drops none. The messages received during the summarized turns are copied into the summary message by code, newest first within a third of the verbatim budget when there are any, so what a person sent never depends on the summary. A checkpoint that ends without calling context_replace falls back to the summarizer; its closing text is never taken as the summary. Every compaction restores full live context before the agent’s next request, including memory, discovery, permission, and execution guidance. The world snapshot advances only after the replacement is saved. Finished background outcomes are not delivered again during this rebuild.
5. Output. Text, thinking, tool calls, approval prompts and elicitations all reach the user through the session’s Frontend. The screen, the one-shot run, ACP and HTTP each implement it once; a sub-agent’s PermissionForwardingFrontend forwards its approval prompts and notices to its parent’s; SilentFrontend answers a call with nobody behind it.

Where state lives

Non-secret settings live in config.toml. Secrets live in the store. Environment variables are operational only. The store is one SQLite file, meka.db under MEKA_DATA_DIR, opened by Store, and its shape is whatever the migration ledger says it is: a current store’s PRAGMA user_version is the number of entries in the ledger, and HEAD_SCHEMA_FINGERPRINT in store/migrations.rs pins the columns of the tables in HEAD_TABLES. The count is the ledger’s to state: the_ledger_is_append_only digests every entry, so read the ledger rather than this sentence for what the last ones do. The entries after messages_are_indexed_by_kind give sessions a title, a pin and a search index, fold every diacritic in the search indexes, and number turns. Before them, sessions_have_an_inbox adds the inbox table and messages_are_indexed_by_kind indexes a session’s rows by kind so a resume finds its last compact_boundary row and the context block counts them without reading the whole log; before those, names_follow_the_vocabulary gives every table, column and index the name the vocabulary uses and drops the provider_credentials view and a column nothing read. That view existed for one replay: the frozen sessions_name_their_provider reads the name when no default profile resolves, so classify_by_shape classifies a store that lost its user_version and has no such view at the version this entry leaves it, past that step, rather than at the baseline. Before it, sessions_record_their_context_tokens adds the occupancy a resume checks its first turn against, background_tasks_spell_canceled_with_one_l rewrites a task status an earlier meka stored as cancelled, and root_rows_take_the_default_level_once_the_config_reads stamps [permissions].default on a root row that still records no level and refuses to migrate while config.toml cannot be read.

Per-process state that is not a table has an owner too: the scheduler’s memory of which refusals it has already reported is the SchedulerMemory on the Store; MCP progress routing and resource updates live on the McpClientContext; the per-path write locks are the WriteLocks on the host’s SharedDeps, cloned into every session’s CoreMaterials; a frontend’s sticky approval answers are its StickyApprovals, in memory and never persisted.

The doors

Most defects that survive review are one rule enforced at one entry point and forgotten at a sibling. The rules below are each written once and called from every path that reaches the thing they guard. When adding a path, call the predicate rather than restating the rule.

One error, one mapping per host

MekaError carries the refusals the doors raise: SessionNotFound, TurnInFlight { doing }, EmptyPrompt, DisabledLevel { level, enabled }, ProfileNotConfigured { name, known }, RequestTooLarge, beside SessionLocked, SessionNotDrivable, Usage and Config. Each host maps the enum once, and no handler rewrites the sentence:

• HTTP: ProblemDetail::for_error in host/http/errors.rs. SessionNotFound is 404 (session-not-found); TurnInFlight and SessionLocked are 409 (turn-in-flight, session-locked); EmptyPrompt, DisabledLevel, ProfileNotConfigured, Usage and Config are all 422 under invalid-body, so a client tells them apart by detail; RequestTooLarge is 422 under its own request-too-large, because meka refused it and there is no provider response behind it. The type URIs live under https://meka.bot/errors/.
• ACP: acp_error_for in host/acp.rs. Everything the caller can act on is InvalidParams (-32602) with the Display as data; everything else is InternalError.
• Screen: an error item in the transcript, the Display text.
• One-shot and CLI: the Display on stderr and exit code 1; 130 when the turn was interrupted.

Two classes never travel verbatim, on either wire. Installation is meka’s own sentence about the operator’s setup – a [web] client that will not build, a base_url shape a backend refuses – so it names a path or an endpoint from config.toml that no caller can act on: HTTP answers a sanitized 500 and ACP an InternalError with the text in the log, while the screen and the CLI print it, since their reader is the operator. The web client is built once in build_shared_deps, so on every host a bad [web] block fails the process at startup rather than surfacing per session.

And an upstream’s own response text travels only when [serve] relay_provider_errors says so, which host::relay_provider_errors reads once for both hosts. for_error attaches it as provider_response; acp_error_for appends it to data; both bound it with error::bounded_upstream_body. An MCP connector’s reason, a Database and an Io never travel at all, on either.

What each host offers

The hosts do not offer the same operations, and the gaps are recorded here rather than filled. “Run” is meka with -p, -c, -r, --profile and --permission; the one-shot is that run with --oneshot.

The screen and the one-shot share COMMANDS in host.rs for what a slash command is; ACP advertises the three rows with an editor_help (/mcp, /status, /usage) as available_commands.

Mid-turn

Only HTTP and ACP can receive a request while a turn holds the session, and the two answer differently by design.

• HTTP refuses what needs the turn to end. A PATCH naming working_directory or profile, DELETE, fork, compact and rewind check in_flight (or fail claim_idle) and return 409 with type https://meka.bot/errors/turn-in-flight, through turn_in_flight_conflict and ProblemDetail::for_error(MekaError::TurnInFlight). A second POST /turns on the session gets the same 409. The detail names what was refused (doing), and a session_id member carries the id. A PATCH naming only permission or approvals writes the cells and the row without waiting, the same three steps ACP takes below. POST /v1/sessions/{id}/inbox never refuses for a turn in flight: it writes an inbox_items row (store/inbox.rs) and wakes the driver (host/http/inbox.rs). The row reaches the model at one of four places, all in Agent::run_attributed_turn so no host door can forget one: a steer or an interrupt at a round boundary, after a tool round’s results or after a reply that would have ended the turn, in the same user message or the one that follows the reply, stamped appended_at by the same transaction (save_events_atomic_marking_inbox); an interrupt the moment it lands while a provider call is in flight; any class at the next turn’s opening, after the words, whoever started the turn; or as the opening message of a turn the driver starts (host::scheduler::run_inbox_turns) when the session is idle. The item is delivered where last_accepted_len is stamped, which is the request the provider accepted, and FrontendEvent::InboxDelivered is what the feed and the webhook relay.
• An interrupt is decided by the loop, never by a host. Each provider call runs under a child of the turn’s token, and watch_for_interrupts polls the inbox once a second (INTERRUPT_POLL_INTERVAL) and cancels the child when an interrupt row is pending: polled rather than signaled, so a parent’s agent_steer on a running worker needs no registry to reach it. The call returns as it does on a stop, and absorb_interrupt reads the tokens to tell the two apart. What streamed is kept through without_tool_use, the items follow as the next user message, and the loop continues in the same turn. Nothing streamed means the items join the user message that was cut, as a withdrawal and a re-append in one write, so the log still ends on an appended turn opening and withdraw_unanswered_prompt takes the items back with the prompt if the turn then fails before the provider accepts anything. A tool round is never cut.
• ACP applies the level and the switch, and refuses the rest. session/set_mode and the permission and approvals options of session/set_config_option write the cells without taking the conversation mutex, so an editor toggle takes effect on the very next tool call, and then record the row. The profile option try_locks the conversation first and refuses with InvalidParams (TurnInFlight { doing: "switch profile" }) so that a switch refused for a turn in flight leaves the row where it was. A second session/prompt is refused InvalidParams (TurnInFlight { doing: "prompt" }), and so is a session/fork of the session (TurnInFlight { doing: "fork the session" }), which try_locks the conversation the same way and holds it across the copy.

Frontends

Seven things implement or stand in for Frontend: TuiFrontend (host/tui/frontend.rs, the screen), PlainFrontend (host/oneshot/frontend.rs, the plain one-shot), AcpFrontend (host/acp/frontend.rs), HttpFrontend (host/http/http_frontend.rs, which records for the blocking response and broadcasts to SSE through host/http/sse.rs), JsonFrontend (host/oneshot.rs, --format json), SilentFrontend and PermissionForwardingFrontend (frontend.rs; the latter forwards notices and approval prompts to the parent’s frontend and drops the rest). Where they differ:

The scheduled-fire failure row comes from each host’s HostHooks (finished) rather than its Frontend, in host/tui.rs, host/acp/schedule.rs and host/http/schedule.rs. The fire’s prompt takes no hook: the agent emits MessageAppended where it appends a turn’s opening, which is the one place every door passes, so a report riding a client’s turn is announced as a fire’s is.

The ACP frontend sends each tool call under an id CallIds (host/acp/frontend.rs) gives it, since a provider may give one id to every call or reuse its ids each round: the provider’s own id the first time the session sends it, else one minted with a token unique to the frontend, and always a minted one when the session was opened as EditorThread::Inherited (resume, fork, a reopen after the idle sweep), whose thread the editor already holds. Every event about a call after its ToolCallStarted, an approval prompt’s PromptedCall::Announced included, goes under that id, the oldest still running under the provider’s id, and session/load’s replay goes through the same CallIds, so a live call after it is told apart from the replayed ones. A sub-agent’s activity goes under the id its agent_spawn card had when the sub-agent started (AcpFrontend::for_subagent), since a background sub-agent outlasts its call. A call ToolCallDropped names, or one still running at TurnEnded, is closed failed, unless a session/cancel stopped the turn, which the client marks; a detached command streams no output (OutputRelay::for_call), its call having returned.

Building

Two Cargo features shape a build. serve, on by default, is meka serve: the HTTP API and the dependencies only it needs, so --no-default-features builds a meka without one; src/host/http.rs is behind cfg(feature = "serve"). mock-provider compiles in provider/mock.rs, the scripted provider the test suites drive every host with; debug builds carry it regardless, and CI enables it so a release-profile build is testable too. A shipped artifact is built without it. At run time, MEKA_MOCK_PROVIDER=1 selects that provider on every host and MEKA_MOCK_PROVIDER_SCRIPT names the JSON script it plays back; both are read by ResolvedConfig::resolve, like every other MEKA_* variable, and acted on by host::build_shared_deps.

The integration crates are gated on the same fact: tests/acp.rs and tests/cli.rs carry #![cfg(any(debug_assertions, feature = "mock-provider"))]; tests/serve.rs and tests/multiprocess.rs add feature = "serve"; tests/tui_pty.rs adds unix. Only tests/layering.rs runs unconditionally. Unit tests open the store with Store::for_test(), an in-memory database at the current schema; Path::new(":memory:") is spelled out because None means the default path. The integration crates share tests/harness/support.rs, whose Install is a temporary root with a config directory, a data directory and a work directory; Install::env points a meka command at it (MEKA_CONFIG_DIR, MEKA_DATA_DIR, HOME, XDG_*, MEKA_MOCK_PROVIDER=1, the script when one was written) and Install::meka(args) builds one.

The exact gate CI runs is in AGENTS.md under “Build gate”; run it before declaring a change done, since clippy and rustdoc deny warnings there and not locally. The one-shot conversion for a 0.45 config.toml, migrate-0.45-to-0.46.py, is not in the repository: like the 0.42 script before it, it is attached to its release as an asset by hand and carries its own --self-test fixture.