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 around the live REPL prompt
 3    console         the terminal between two prompts: spacing, notices, errors
 4    render          markdown, tool indicators, todo lists, status lines
 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
12    sandbox         read-only confinement for execute_command
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    todo            the task list
17    image           format detection and transcoding
18    fs              private directories, atomic replace, file locks
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 the two terminal hosts (host/repl.rs, host/oneshot.rs) and by main.rs as tracing’s writer; it writes through console, which draws with render. render and console are reached only from host, cli and relay. 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 or an outcome delivery takes mark_busy; HTTP compact and rewind take claim_idle, which refuses while anything is in flight. The REPL 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, todos, 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 /messages, 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.
4. Recovery. A failed request goes through TurnRecovery, which decides between a retry, a degraded resend and a reported failure. Compaction runs when the context gauge says so, when the model asks through context_compact, or when the user asks.
5. Output. Text, thinking, tool indicators, approval prompts and elicitations all reach the user through the session’s Frontend. The REPL, 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: twenty-three entries today, so a current store reads PRAGMA user_version = 23, and HEAD_SCHEMA_FINGERPRINT in store/migrations.rs pins the columns of the twelve tables in HEAD_TABLES. The last two entries are sessions_have_an_inbox, which adds the inbox table, and messages_are_indexed_by_kind, which 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 them, 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.so/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.
• REPL: console.error(&error), the Display on stderr.
• 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 REPL 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.

• REPL: console.error(&error), the Display on stderr.
• One-shot and CLI: the Display on stderr and exit code 1; 130 when the turn was interrupted.

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 REPL and the one-shot share COMMANDS in host.rs for what a slash command is; ACP advertises the three rows marked for_editors (/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 cwd or profile, DELETE, fork, compact and rewind check in_flight (or fail claim_idle) and return 409 with type https://meka.so/errors/turn-in-flight, through turn_in_flight_conflict and ProblemDetail::for_error(MekaError::TurnInFlight). A second POST /turn 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 the round boundary after a tool round’s results, in the same user message and 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

Six things implement or stand in for Frontend: ReplFrontend (host/repl/frontend.rs, also 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 rows come from each host’s HostHooks (show_prompt, finished) rather than its Frontend, in host/repl.rs, host/acp/schedule.rs and host/http/schedule.rs.

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 (provider/registry.rs, host/assembly.rs) and MEKA_MOCK_PROVIDER_SCRIPT names the JSON script it plays back.

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/repl_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.