Skip to main content
Meerkat exposes a JSON-RPC 2.0 surface for IDE integration, desktop apps, and automation tools. Stdio is the default, and the binary also supports TCP plus optional WebSocket and feature-gated WebRTC live transports. Like the REST and MCP servers, RPC composes the shared runtime-backed service so agents can stay alive between turns. RPC adds a broad typed method and notification surface suited to interactive clients. The RPC surface is fully runtime-backed:
  • keep_alive is runtime/session behavior
  • session/external_event queues runtime-backed external work
  • committed success is not rewritten to cancellation

Getting started

1

Start the server

The server reads newline-delimited JSON (JSONL) from stdin and writes JSONL to stdout. Each line is a complete JSON-RPC 2.0 message.Optional listener modes:
TCP and live WebSocket listeners are local-only by default. Binding a non-loopback address such as 0.0.0.0:9001 requires --allow-remote; that flag only opts in to network exposure and does not add authentication or encryption. Use it behind a production-safe transport wrapper such as SSH tunneling, mTLS, or another authenticated encrypted channel. Plain TCP host capabilities continue to report secure_remote_rpc: false.rkat-rpc --tcp is a JSON-RPC host transport. It is not the signed Meerkat peer/comms channel used by remote agents or external mob members; use rkat run --comms-listen-tcp ... for that.
2

Send the handshake

3

Create a session

rkat-rpc defaults to a new isolated realm each time. To share sessions with another process, use the same --realm <id> and physical --state-root, or a matching --context-root that resolves the same project-local root.

Runtime scope

rkat-rpc accepts global scope flags:
  • --realm: explicit sharing/isolation key
  • --instance: optional instance metadata
  • --realm-backend: creation hint only; actual backend is pinned per realm manifest
OS process confinement flags (see OS process confinement):
They replace the realm’s composed [confinement] for every launch kind of this process. The workspace preset confines each launch to --context-root; without --context-root the server refuses to start with it. A start in which a confined process could change the server’s realm state or user config document is refused (see the host’s own inputs). At startup the server logs each launch kind’s requested and effective confinement and warns for each required kind its platform cannot confine. Transport and live-channel flags are:
--live-webrtc is present only in builds with the live-webrtc feature. --live-ws-scheme wss changes the advertised bootstrap URL for a TLS-terminating proxy; the listener itself still accepts plain WebSocket bytes.

Method overview

This table mirrors the generated catalog in artifacts/schemas/rpc-methods.json (meerkat_contracts::rpc_method_catalog). initialize returns the methods enabled by both the compiled build and runtime composition. Reduced builds, an absent skill runtime, or unconfigured live transports can expose a subset of this full catalog. Auth method errors (auth/*) carry a typed reason in error.data.reason, one of the closed WireAuthErrorReason values (for example slot_occupied, account_mismatch, attempt_missing, reauth_required, infrastructure). Branch on the reason, not the message text. Infrastructure failures have a fixed message. Some errors also carry a stable sub-kind in error.data.detail: remote_custody_required (reason invalid_target), and upstream_timeout or upstream_timeout_after_code (reason upstream_failure: a network stage of an MCP login got no answer within its bound, before or after the authorization code was sent; nothing was published). The reason commit_unsettled means a credential commit’s outcome is unknown (an MCP login’s commit did not report in time, the commit’s owner ended before it reported, or the commit failed and could not restore the previous credential): whether the credential landed is unknown until it settles, so read auth/status/get later, and log in again if a use is then refused for authorization. A failed credential commit of auth/profile/create or auth/login/provision_api_key carries its typed reason too, with a fixed message. Both helper parameter types (MobSpawnHelperParams, MobForkHelperParams) require result_label and max_text_bytes. MobHelperResult is the exact operation carrier: output, tokens_used, agent_identity, member_ref, bounded_result, session_id, usage, turns, and tool_calls are required, while retirement_error reports post-result cleanup debt when present. mob/profile/create and mob/profile/update are a host’s own caller’s methods and accept the stored profile form: beyond the fields of MobProfileInput, which their parameter schemas describe, a profile may carry auth_binding, tools.mcp_servers and tools.rust_bundles, and its tools.bundles is stored as sent. Members spawned from that realm profile build on the binding, start the servers and mount the bundles of tools.rust_bundles and tools.bundles that the host registered for child mobs. A profile read back (mob/profile/get, mob/profile/list, and the answers of create and update) shows none of these four fields. The agent profile tools take MobProfileInput only and refuse all four on a realm profile; the MCP profile tools take MobProfileInput and auth_binding, and refuse the other three. An update through either replaces the stored profile whole, so it removes from a profile a host stored every one of these fields that the update does not send.
Every Schedule result is one flattened public object. Configuration fields including planning_horizon_days, planning_horizon_occurrences, labels, created_at_utc, and updated_at_utc are top-level; there is no nested config and persisted machine authority is not exposed as machine_state.
WorkGraph goal and attention mutation methods require trusted host/session authority. JSON-RPC exposes observability reads; goal creation, reassignment, policy escalation, confirmation, and closure stay on trusted in-process host and agent-tool surfaces.
Generated assistant images use the same surface-neutral history and blob APIs as other blob-backed artifacts. Read session/history, find assistant blocks with block_type: "image", then call blob/get with data.blob_ref.blob_id to retrieve the base64 payload.
Live channels provide low-latency audio/text streaming with model-gated image input. Create a session with a realtime-capable model (e.g. gpt-realtime-2), then call live/open to start the channel. The --live-ws <addr> flag on rkat-rpc enables the WebSocket listener required for audio transport. Use live/status to observe channel state and check live/open’s capabilities.image_in before sending image context.
RPC is the canonical typed substrate for the SDKs: use explicit mob/* lifecycle, host-ingress, and observation methods from apps. Inside running sessions, mob capability is exposed by composing meerkat-mob-mcp (MobMcpState + AgentMobToolSurfaceFactory) into SessionBuildOptions.mob_tools, which provides authorized mob_* tools to the agent. external_tools remains for callback and MCP-backed tool dispatchers.
WorkGraph RPC methods are observability reads. Programmatic hosts inspect WorkGraph through workgraph/get, list, ready, snapshot, events, goal/status, and attention/list; agents mutate ordinary WorkGraph state through the workgraph_* tools. Authority-bearing attention reassignment and policy escalation are runtime-injected WorkGraph tool operations, not public JSON-RPC methods.

Runtime host projections and health

runtime/host_info is a read-only projection of process identity, host ID scope, realm and endpoint metadata, feature flags, and health. It does not enroll a member host or grant mob placement authority. runtime/capabilities returns a contract version plus boolean RuntimeHostFeatureFlags: runtime_backed_sessions, mobs, mcp_live, comms, blobs, session_events, session_streams, schedules, skills, event_replay, artifacts, approvals, external_members, secure_remote_rpc, multi_host_mobs, and durable_jobs. These host facts are distinct from the generic status-bearing CapabilityId entries returned by capabilities/get. Older payloads that omit multi_host_mobs or durable_jobs decode those fields as false; clients should use the flag and not infer multi-host support from a version number. runtime/health returns the worse-wins rollup across five declared dimensions: jobs, session_liveness, session_durability, session_runtime_loop, and session_run_start. This RPC host probes all five. A plain check key is a measured result. unreadable:<dimension> means a probe ran but could not obtain a reading and rolls the overall status to at least degraded. unmeasured:<dimension> is a coverage marker for a surface with no probe and does not enter the rollup. The session liveness check covers queued work parked on an active executor with no run in flight, including repeated staging churn. session_run_start covers a current staged run that is overdue to begin. Neither claims to measure a run that began and then stopped producing progress.

Protocol

Standard JSON-RPC 2.0 with "jsonrpc": "2.0" on every message. Three message types:
  • Request (either direction): has id, method, params. The server sends tool/execute requests to clients for registered callback tools.
  • Response (back to the requester): echoes id with result or error.
  • Notification (either direction): has method, params, no id, and receives no response.

Request cancellation

Known issue, noted 2026-11-13: in Meerkat 0.8.0 through 0.9.14, cancelling a request that is still waiting behind another turn can permanently destroy the mobs of the session it was queued for. See the known issue on the 0.9.14 release page for the affected releases, the cases and what to do.
Cancel an in-flight request by its exact JSON-RPC request ID, preserving its number/string type. For example, while session/create request 2 is still in flight, send this notification:
Client -> server notification
The notification has no id and receives no reply. When cancellation wins before the original request commits success, the original request receives REQUEST_CANCELLED (-32005):
Server -> client response to the original request
The target is a request ID, not a session ID, so cancellation can be sent before session creation returns an identity. It is not a rollback guarantee: committed success is not rewritten to cancellation. This is separate from turn/interrupt, which targets an existing session’s turn. MCP uses the different notifications/cancelled notification and requestId spelling described in the MCP reference.

Callback tools

Register client-owned foreground tools with tools/register:
Registration advertises the tool; execution requires the reverse exchange. During a turn, the server sends its own JSON-RPC request:
Echo the server request’s id, not the turn’s ID or tool_use_id. tool_use_id is the provider’s tool-call correlation identity; name selects the registered tool and arguments contains its JSON arguments. In the result, content defaults to an empty string and is_error defaults to false if omitted. A client can instead return a JSON-RPC error for the same request ID; the server projects it as a tool-execution error. Since 0.9.5 a request for a call made in a run’s tool round also carries dedupe_key, an object with run_id, round, call_id and call_digest. A durable run that continues after a restart sends the same call again, with the same key. A tool whose effect must not happen twice records the key with the effect and answers a repeat from that record; see Durable Runs: Tools That Run Again. Since 0.9.11 a request also carries requester when the run the call serves has an original requester (see Authorization): {"principal": {"kind": "human", "id": "...", "qualification": {"kind": "qualified", "trust_domain_id": "..."}}}, with "carried": true when the run’s work reached its agent through another actor, such as a peer hop. The runtime sets it from the run’s admitted inputs; a requester inside arguments is only an argument. A tool that acts in one person’s name serves only that person’s requester, and only when it is not carried; it refuses a call with another requester or none. The callback/job/start request of a detached callback tool carries the same field: the requester of the run that submitted the job, recorded with the job. The SDKs pass it to a handler that declares a requester parameter (Python), or as the handler’s optional third argument (TypeScript). Keep reading and answering reverse requests while waiting for the turn’s result, or the turn cannot finish its callback. This foreground RPC exchange is neither MCP’s pending_tool_calls/meerkat_resume continuation nor the separate detached-job callback extensions. tool/execute is not a client-callable catalog method.

Mob members

A mob’s members call the callback tools of the connection that holds the mob’s callback route. mob/create gives the route to the creating connection, and returns the mob’s claim token once, to that connection ({"mob_id":"team","claim_token":"mct_..."}): only a connection that presents it can take the route later. The mob keeps only the token’s SHA-256, in its own store, so the token survives restarts but is never read back; a mob destroyed and created again under its id gets a new one. Keep the token secret and out of logs. It decides which connection a route claim follows and nothing else: every connection to one rkat-rpc host keeps the same owner authority. It cannot be minted again: the host mint described below refuses a mob that keeps a verifier, so a lost token is lost for good, and destroying the mob and creating it again is the only recovery. A creator that must claim the route after a restart (its own or the server’s) persists the token. Where a restored mob’s route starts depends on the server:
  • On a connection-owned server, where every connection owns its own route (rkat-rpc over stdio or TCP), a mob restored after a restart starts with no route.
  • An embedding host that installed the process-default callback channel (SessionRuntime::init_callback_channel, the single-client default route) keeps that channel’s contract: a restored mob’s route starts held by the default route, and its members reach that host’s callbacks without a claim.
A mob with no route, or one whose holding connection closed, fails a member’s callback call tool_unavailable (“no connected client holds the callback route that serves it”); the call is never delivered to a closed connection. The tool definitions the closed connection registered stay advertised to the mob’s members until the next claim. A connection claims the route with:
The claim needs the console owner and the mob state’s admission; it does not ask the host’s create hook, since a claim creates nothing. The token is checked first: a claim without one, or with one that is not a claim token, is invalid (-32602); a token that is not the mob’s is refused with -32002 and data {"mob_id":"team","reason":"claim_token_mismatch"}; and a mob created without one (by an agent’s mob_create, implicitly, by a host’s Rust create, or before 0.9.3) is refused with {"mob_id":"team","reason":"not_claimable"}, unless its host minted it a token (MobMcpState::mint_callback_claim_token, a Rust API with no wire method). After an upgrade to 0.9.3, a mob created over RPC before it has no token, so no connection can claim its route over the wire until the mob is destroyed and created again or its host mints it one. With the mob’s token, the claim returns {"mob_id":"team"} and reaches the mob’s live members and the ones it spawns later, which then call the tools this connection registered. While the connection that holds the route is open, another connection’s claim is refused with -32002 and data {"mob_id":"team","reason":"held_by_open_connection"}; the holder’s own repeated claim succeeds. Once the holder has closed, the first claim presenting the token wins, including the pending detached callback jobs the closed connection’s tools started: a claimer that registers tools of the same name and runner reconciles and cancels them, and runs the queued ones, but only where its tool declares exactly what the job recorded when it was submitted (the tool’s description, schema, provenance, audience and execution contract, runner included). Every route other than the connection that submitted a job, and every route after a restart, is held to that declaration. A running job whose recorded declaration differs goes to needs_attention with the reason callback_binding_changed instead of being reconciled or cancelled through that route; a queued job is not that route’s to start and stays queued, unchanged, for a route that declares what it recorded or for the connection that submitted it, until one of them starts it or jobs/cancel cancels it. A job submitted before 0.9.3 recorded no declaration and goes to needs_attention (callback_binding_changed) at its first start, reconcile or cancel. A job whose recorded specification no longer decodes goes to needs_attention with the reason callback_specification_unreadable. A detached callback call made while no open connection holds the route is refused before anything durable is written.

Session methods

initialize

Handshake. Returns server capabilities.
The example array is abbreviated. The actual array reflects the compiled build and the runtime’s enabled composition: skills/list requires a skill runtime; live/* requires a configured live transport, and live/webrtc/answer additionally requires enabled WebRTC support. For the full catalog rather than this runtime subset, including parameter/result type names, use artifacts/schemas/rpc-methods.json.
string
Server name.
string
Server version.
string
Protocol contract version.
array
List of supported method names.

session/create

Create a new session and run the first turn. Set initial_turn to "deferred" to return a pending session_id without running the first turn; that returned session_id is valid for the first turn/start, including sessions created with inline external_tools.
Only prompt is required. Other fields follow the per-field defaults and override rules below; not every omitted value inherits configuration. During execution, session/event notifications are emitted (see Notifications).

Parameter reference

ContentInput (string | ContentBlock[])
required
The user prompt as a string or typed content-block array, for example [{"type":"text","text":"Hello"}]. Media support depends on the selected model/provider; see model capabilities.
ContentInput[] | null
default:"null"
Host-attached injected context for the first turn. Each entry materializes as a separate typed injected-context user-channel message immediately before the first turn’s user message, in order; injected context is excluded from semantic-memory indexing.
string | null
default:"null"
Non-empty, exact request-only host facts for the immediate first turn; whitespace is significant. The pending runtime input retains the bytes for crash retry; the Session transcript, compaction summarizer, and extraction phase never receive them. Deferred create rejects this field; provide it on the eventual turn/start.
string | null
default:"config/catalog default"
Model name (e.g. "claude-opus-4-8", "gpt-5.5").
string | null
default:"inferred from model"
Provider name: "anthropic", "openai", "gemini", or "self_hosted".
WireAuthBindingRef | null
default:"null"
Structural credential selector, for example {"realm":"prod","binding":"anthropic","profile":"claude_oauth"}. realm and binding are required when supplied; profile is optional. Configure the referenced realm, binding, and auth profile first. Omission/null lets the create resolver choose credentials. A colon-delimited CLI string is not accepted; provenance is server-owned.
u32 | null
default:"config default"
Max tokens per turn.
SystemPromptOverride
default:"inherit"
Omission/null inherits the base prompt; a string sets an explicit base prompt; {"action":"disable"} suppresses inherited/config/default/AGENTS base prompt sources. Separately appended dispatcher, tool, and additional instruction sections may remain, so disabling is not a promise of no System content. This create-time policy differs from turn/start’s ordinary ordered System-message string.
object | null
default:"null"
JSON schema for structured output extraction (wrapper or raw schema).
u32 | null
default:"null (config default)"
Max retries for structured output validation. Omission/null inherits configuration (stock default 2); explicit 0 is preserved.
HookRunOverrides | null
default:"null"
Run-scoped hook overrides (entries to add, hook IDs to disable).
bool | null
default:"null (host/factory default)"
Override built-in tools (task management, etc.). Omission/null inherits host/factory configuration; explicit false disables them.
bool | null
default:"null (host/factory default)"
Override the shell tool (requires built-ins). Omission/null inherits host/factory configuration; explicit false disables it.
bool | null
default:"null (host/factory default)"
Override semantic memory (memory_search tool + compaction indexing). Omission/null inherits host/factory configuration; explicit false disables it.
bool | null
default:"null"
Override schedule tools for this session. null uses the surface default.
bool | null
default:"null"
Override WorkGraph tools for this session. null uses the surface default.
bool
default:"false"
Keep the new session alive after its turn for comms. Omission is false; null is rejected on create. true requires comms_name. This differs from turn/start’s nullable override of existing session intent. With true, session/create answers once its first turn has built the session and lets that turn run on, so the result carries none of the turn’s output; a build that fails is answered as for any create.
string | null
default:"null"
Agent name for inter-agent communication.
object | null
default:"null"
Provider-specific parameters (e.g., thinking config, reasoning effort).
string | null
default:"null"
From 0.9.15; an older server ignores the field. The 0.9.15 Python and TypeScript SDKs refuse to send it to an older server, so nothing is sent. The session’s provider-neutral reasoning effort level: none, minimal, low, medium, high, xhigh or max (see Reasoning effort). It is the same setting as provider_params.reasoning_effort; a request that gives both must give the same level, or it is refused as invalid params. A level the model or its route does not accept fails the session’s build with invalid params whose data is {"kind": "reasoning_effort_refused", "retryable": false, "reasoning_effort_refusal": {...}}, before any provider request.
object | null
default:"null"
Scoped tool grant gate, {"families": [...], "tools": [...], "mcp_servers": [...], "unconfigured_mcp_servers": true}: built-in tool families, tool names and MCP servers whose tools the session mounts hidden and refuses at dispatch until a live grant opens them (see Scoped tool grants). unconfigured_mcp_servers gates every MCP server the session does not configure, so a server a later mcp/add attaches is gated too. The session records its gate. A field the gate does not know is an invalid parameter, and a gate no grant could honour (an unknown or disabled family, a name nothing mounts) fails the session’s build with invalid params whose data is {"kind": "tool_grant_gate_refused", "tool_grant_gate_refusal": {...}}. session/create answers it, with keep_alive: true too; a deferred create reports it at its first turn/start.

Response fields

string
UUID of the created session.
string
The agent’s response text.
u32
Number of LLM calls made.
u32
Number of tool calls executed.
WireUsage
Token usage breakdown.
JSON (optional)
Parsed structured output when extraction succeeds. Omitted when absent.
ExtractionError (optional)
Post-turn extraction failure details: last_output is the committed main-turn assistant text that extraction attempted to transform, attempts is the number of extraction attempts made, and reason describes the failure. Omitted when absent.
SchemaWarning[] (optional)
Schema compatibility warnings. Omitted when absent.
A successful run result can retain committed text even when post-turn structured-output extraction fails. Inspect structured_output together with extraction_error; absence of structured output does not prove extraction was never requested. These optional fields in WireRunResult are omitted when absent, not filled with null.

session/history

Read committed transcript history for an existing session.
Returns oldest-to-newest committed messages plus pagination metadata. This method follows the same owner-resolution rules as session/read, including mob-owned session IDs when mob support is enabled. When limit is omitted, the server returns at most 100 messages. The maximum accepted limit is 1,000 and the maximum offset is 1,000,000; larger values fail with INVALID_PARAMS before the session store is queried.

session/export_atif

Export the currently available event audit/replay projection as an ATIF (Agent Trajectory Interchange Format) v1.7 trajectory document.
agent_name, agent_version, and model_name are optional overrides for the trajectory’s agent block; when model_name is omitted the session’s model is used. The export replays the currently projected event log page by page, so it requires a host with event projection installed. Projection is asynchronous best-effort derived state and the handler does not drain it first; an export can therefore lag the latest committed session state. Outcomes:
  • A host without durable event replay fails with INVALID_REQUEST and event replay is not enabled for this runtime host.
  • An existing session whose durable log is empty (for example a session created with a deferred first turn) returns a trajectory that names the session with no steps and final_metrics.total_steps of 0. It is not a missing session.
  • A session that does not exist fails with SESSION_NOT_FOUND.
  • A session whose durable log exceeds 500,000 events fails with INVALID_PARAMS naming the bound; page the log with events/list_since, or export it to a file with rkat session export-atif, which has no such bound.
  • A session whose trajectory outgrows the outbound message limit (32 MiB) fails with BUDGET_EXHAUSTED naming that limit and the bytes it had accumulated. The fold measures itself page by page, so the refusal arrives while the document is still partial rather than after the whole log is in memory.
The two bounds answer with different codes on purpose: the event bound is a property of the request (INVALID_PARAMS), the size bound is a property of the response, so it answers the way outbound admission answers any oversized result (BUDGET_EXHAUSTED). They cover different content mixes: an all-delta log can hold hundreds of thousands of events and still fold into a small document, which is what the event bound is for; a tool-heavy log outgrows the response long before that count, which is what the size bound is for.

session/rewrite_transcript

Commit a transcript rewrite without changing the session identity. The request names a message-range selection, supplies replacement messages, and records a machine-readable reason. The session appends a rewrite commit, advances its transcript head, and retains the parent revision for audit and restore.
Returns the stable session_id, the parent revision, the new revision, and the updated message count. running_behavior currently supports "reject", which returns SESSION_BUSY if the target session has active work.

session/transcript_revision

Read one retained transcript revision body by revision id.
Use "current" to read the active transcript head, or pass a concrete revision returned by session/rewrite_transcript or session/restore_transcript_revision.

session/transcript_revisions

List retained transcript revision commits (oldest first) together with the current transcript head revision. Each entry records the revision the commit produced, the parent it was applied against, the recorded actor, the rendered rewrite reason, and the commit timestamp.
Sessions without any rewrite commit return an empty list; head_revision still names the active transcript head. Pass a returned revision to session/transcript_revision to read the retained body, or to session/restore_transcript_revision to restore it.

session/restore_transcript_revision

Restore a retained transcript revision as the active transcript head without changing the session identity. Restore is represented as another rewrite commit so the graph remains append-only even though the source transcript projection is updated in place. revision accepts the same selector as session/transcript_revision: "current" resolves to the head revision, so restoring it surfaces the typed no-op rewrite error. The restored rows are the session’s own retained rows, so every restored block_assistant row keeps its assistant_message_id (a session/rewrite_transcript replacement never carries one).

session/fork_at

Create a new idle session whose transcript is the source session prefix ending before message_index. The source session is not mutated.
running_behavior currently supports "reject", which returns SESSION_BUSY if the source session has active work. session/fork_at, session/fork_replace, session/rewrite_transcript and session/restore_transcript_revision refuse a mob member’s session with INVALID_PARAMS (-32602), since the member’s mob owns its transcript; fork a member at a message boundary with mob/fork_member (below). inherited_instructions decides what the child does with the instruction activations it copies from the prefix. The child is not materialized, so nobody can activate it before its first turn: with the field absent or "require_explicit_activation" (the default), and with "refuse", a prefix that carries activation rows is refused before anything is committed with FORK_INSTRUCTION_REFUSED (-32037), whose data carries kind: "fork_instruction_refused" and the typed fork_instruction_refusal (cause, keys). "reactivate_inherited" appends the child’s own activation of every key that was effective in the source; the result’s reactivated_instruction_count counts those rows, which message_count includes. Under it, a prefix whose last row of a key is one whose body a compaction of the source retired (a later row of that key, past the prefix, superseded it) is refused with cause head_body_retired; a fork at a later boundary copies the superseding row, with its body. A prefix without activation rows forks the same way under every value.

session/fork_replace

Create a new idle session from the source prefix through message_index, replacing the addressed message or block with a typed replacement. Later source messages are intentionally omitted so callers continue from the edited branch instead of replaying stale descendants.
Supported replacement variants are message, user_content_block, assistant_block, and tool_result_content_block. Edits always create a new session identity. inherited_instructions works as on session/fork_at.

What a fork child inherits

A child of session/fork_at or session/fork_replace runs its turns under its source’s session configuration:
  • the source’s model, provider and tool access policy (a call’s tool_access_policy replaces the policy on the child only);
  • the output schema, hook overrides, budget limits, shell and tool call timeouts, comms settings, application context and additional instructions;
  • the source’s callback tool definitions. A client that runs the child must answer those tools’ calls for the child’s session id.
The child does not inherit:
  • the shell environment (shell_env) given to session/create. The source keeps it when it resumes; the child runs shell commands without it.
  • MCP server attachments. Attach the servers the child needs to the child.
  • mob operator authority, the comms name, peer metadata and mob member binding, and keep_alive.
The child’s first turn continues the transcript prefix, System message included; it does not write a second System message from the inherited instructions. A fork derives the child’s build state from its source’s. A source with session metadata but no build state is refused before anything is committed, with INVALID_PARAMS (-32602) and data {"kind": "fork_source_build_state_missing", "source_session_id": "<source id>"}. A child forked by Meerkat 0.9.3 or earlier that never ran a turn has no build state: its turn/start fails with INTERNAL_ERROR (-32603) “turn abandoned: persisted session <id> is missing session build state”. Fork its source again instead.

mob/fork_member

Fork a mob member’s session at a message boundary into a new member: the member counterpart of session/fork_at. The new member agent_identity is seated on a committed fork of source_member_id’s session whose transcript is the source’s messages before message_index (the source’s committed end when it is absent), System message included. Requires the mob feature.
The new member takes the source member’s profile and runtime mode unless profile or runtime_mode names others, runs with the source’s tool restrictions, and records the source session as its fork source; the source member keeps its session and transcript. The host’s fork instruction policy decides what the child does with the instruction activations it inherits, as for every member fork. A source that runs under the host’s tool dispatch admission is forked only when the host’s spawn customizer installs one for the child too, and the child then runs its tool calls under it; otherwise the call is refused with -32602 and data.kind dispatch_admission_required (member_id), and nothing is forked. A source whose turn is in flight, or that owes queued work, is refused with SESSION_BUSY and data.kind fork_source_unavailable (source_member_id, cause running), and nothing is seated: fork it again once it is idle. A source without a session (cause no_session) is refused with -32602 and the same data.kind. An agent_identity that is already a member is refused with -32602 before anything is forked. A fork that committed but could not seat its member is refused with data.kind fork_member_provision_failed, whose fork_session_id names the committed child session (recovery resume_committed_fork_session); a member seated under agent_identity between that check and the fork’s own seat is answered this way. That session is bound to agent_identity: resume it under that identity once the identity is free, or archive it.

session/list

List sessions.
Each row is a WireSessionSummary with created_at and updated_at in Unix seconds. is_active is the reported session activity flag, not a runtime-state enum. Optional session_ref and non-empty labels may also be present. session/list is owner-paginated rather than load-all/truncate: omitted limit defaults to 100, the maximum is 1,000, and offset is capped at 1,000,000. The same 100/1,000 collection limits apply to events/list_since, workgraph/list, workgraph/ready, workgraph/snapshot, and workgraph/events. WorkGraph workgraph/ready and workgraph/snapshot read one atomic observation of the whole namespace and classify readiness against all of it, however many items, edges and attention bindings the namespace holds. limit then cuts the result, and workgraph/list, workgraph/ready and workgraph/snapshot report the cut: total_items counts the items that matched before it (for workgraph/ready, the ready items), and truncated is true when matching items exist after the last one returned. A page that ended early names a next_cursor; pass it back as cursor for the next page (see workgraph/list below). workgraph/events pages with after_seq and reports truncated and next_after_seq. A result without these fields comes from an older server and may still have been cut.

session/read

Get session metadata.
string
required
Session ID to read.
The result is WireSessionInfo, not the list summary: it includes model/provider but no total_tokens or state. Timestamps are Unix seconds, and is_active is the reported activity flag. Optional fields include session_ref, last_assistant_text, resolved_capabilities, and non-empty labels.

session/archive

Remove a session from the runtime.
string
required
Session ID to archive.

session/compact

Ask a live session’s next compaction check to compact. The session is not rebuilt and no compaction threshold changes: the check that precedes the session’s next model request (in its running turn, once that turn’s tool results are in, or in its next turn) consumes the request and runs a compaction whatever the thresholds and their cadence would decide. The compaction publishes the ordinary compaction_started, then compaction_completed or compaction_failed. Its own rules still hold: a turn in flight keeps its request and newest round, and before a session’s first model request there is nothing to compact. When the check that consumes the request compacts nothing, it publishes requested_compaction_skipped instead, with the run_id of the run whose check it was and the reason: first_model_request (the check came before the session’s first model request) or nothing_to_fold (the turn in flight keeps its request and newest round, and nothing else was left to fold). A nothing_to_fold skip records a compaction attempt like any other, so the ordinary trigger may then wait up to min_turns_between_compactions checks. If a store fence gap stops the run at the check that consumed the request, the request is dropped: nothing is compacted or published for it, and a host asks again. The request lives in the session’s runtime registration only. It is never persisted: a restart of the server, an unload or a reload of the session drops it, and a per-build threshold override is neither read nor changed. A session whose agent has no compactor (a server built without the session-compaction feature, or a host that composes its agents without one) never consumes a request: it stays requested, and every later request answers already_requested.
The outcome is requested, or already_requested when a request that no check consumed yet was already recorded (nothing changes, and the next check compacts once). A request never loads or wakes a session. Refusals:
  • an unknown or archived session: -32001 (session not found);
  • a session with no live runtime in this server (not opened since the server started, unloaded, a deferred session before its first turn, or a mob member’s session its mob has not woken): -32003 (session not running);
  • a session runtime that is initializing, retired or stopped: -32600;
  • a session runtime that is being unregistered: -32002 (session busy, retryable; data.code is SESSION_BUSY);
  • a session runtime that needs a durability reload: -32603.
A request that races the session’s unregister can answer -32600 where a later one answers -32003: the runtime went between the server’s check and the request. No refusal records anything. mob/compact_member (mob_id, agent_identity) asks the same of a live mob member, without a respawn, and answers the same outcome with the member’s mob_id and agent_identity. A member that is dormant or waking, or whose runtime is retired or stopped, is refused as not live and is never woken; a member placed on a member host is refused as unsupported.
string
required
Session ID.

Operator instructions

Operator instructions are standing System-plane instructions a host gives a session, or the members of a mob, by slot (a namespace the host owns and a key), revision and body. A write answers once it is durable; the session applies it at its next fresh run start as one System entry, never inside a run. They are host verbs: no agent tool sets, revokes or reads them. They replace instruction activations (session/activate_instruction, deprecated since 0.9.11). session/set_instruction records a session-owned write, and session/revoke_instruction revokes a slot at a higher revision:
A revision is at least 1 and strictly increasing per slot. An exact retry answers duplicate. content_sha256, when given, is the body’s digest (sha256: and 64 lowercase hex digits) and must match it. A body is at most 256 KiB, and a session holds at most 64 slots and 1 MiB of Active bodies. session/instruction_status reads the session’s committed state without materializing it: the owner (unowned, session, or mob with its mob_id and agent_identity), the target_generation, the highest entry_sequence, the model’s lowering when the service can tell, and per slot what is recorded, the entry that put it in effect (effective: its entry_sequence, kind delta or snapshot, run_id and message_index) and its state: effective, pending with a reason, or not_targeted. A mob member’s session belongs to its mob: session/set_instruction and session/revoke_instruction on it answer owned_by_mob, and session/instruction_status reads it (owner mob). Write to a member with mob/set_instruction and a member target. mob/set_instruction writes one slot for the members a target selects: {"kind":"mob"} (every member), {"kind":"profile","profile":"worker"} or {"kind":"member","agent_identity":"worker-1"}. A target is a predicate over the roster: a member added later, or moved to the profile later, receives the record then, and a target that names a missing profile or member selects nobody. A member’s snapshot is the shared records (targeted at every member or at a profile) plus the member-targeted records that name it (and, for a fork, the records written for the first member of its fork family and its forks, see include_forks below); any other member-targeted record is not in it. The limits bound one member’s snapshot: at most 64 records and 1 MiB of Active bodies, the shared records and the member’s own together (slot_limit_exceeded, active_set_budget_exceeded). A mob therefore holds a member-targeted record for each of any number of members, while the shared records, which are in every snapshot, stay within 64 and 1 MiB. The limits count a member-targeted record under the member it names, seated or not, and a shared record must fit beside the most any one name holds (and beside what another name’s records pass to its forks); a refused shared write does not name that member (the status read’s desired list shows each record’s target). A member target may carry include_forks ({"kind":"member","agent_identity":"worker-1","include_forks":true}; a boolean, false when absent and left out of every answer when false). The record then follows the member’s fork family from its root: written for a member that is not itself a fork it selects that member and every fork below it, forks of forks included; written for a member that is itself a fork it selects that member only (a fork of a fork follows the records written for the first member of its family). The family’s root is a name, as a member target is: its forks keep following the records written for that name after the root is removed, so a record written with include_forks for a new member seated under that name also reaches the earlier member’s forks. A selected durable fork’s snapshot, with the record, is recorded before its seat (a helper fork is born with it), a higher revision and the revoke reach a seated fork as entries appended at its next fresh run start, and the fork’s row of mob/instruction_status lists the record (each member’s row lists the records of its snapshot; the write’s matched_members counts the seated members the record selects). Without it a member-targeted record is its member’s alone and a fork runs without it. Such a record counts in the snapshot of every other name too, so it is refused when it would not fit beside the most another name holds (a member that holds 64 records of its own blocks every such write for another member); the refusal does not name that member, the mob’s log does (a warning at the refused write names the member whose snapshot would be full and what fills it, or says that the shared records alone fill every snapshot). See operator instructions in the mobs guide for the fork routes and what a fork’s model reads.
The result returns once the record is in the mob’s journal: the disposition (committed, or duplicate for an exact repeat), the mob’s operator-instruction generation after the write and matched_members, the members the target selects now. Delivery is asynchronous: the mob records each selected member’s whole snapshot in the member’s session, through the session while it is live and store-only while it is dormant, never waking it. A placed member’s session is on its member host, which records the snapshot there over the supervisor bridge. A member placed by a spawn that mints its session on a 0.9.11 member host is born with the snapshot, so its first turn has the instructions; on an older or a governed member host it is born without them, and its delivery then blocks it as follows. A member host that runs a release before 0.9.11 refuses that, nothing is recorded, and the member reads blocked with reason member_host_unsupported until its host runs 0.9.11 and a write selects it again. A governed member host refuses the record prepared_authorization_required, and a snapshot whose record would not fit the bridge’s frame (about 1 MiB) is not sent; both block the member member_host_unsupported until a write selects it again. mob/revoke_instruction revokes a slot at a higher revision; the record keeps its target. mob/instruction_status reads the mob’s records (desired) and one page of members in identity order (offset, and limit from 1 to 200, 100 when absent; next_offset names the next page), optionally for one namespace, key, agent_identity or profile. Each member carries its residency (live, dormant or unborn), its delivery (the recorded_generation, and state current, owed with the generation and the last_failure, or blocked with a reason), per slot of its snapshot (the shared records and the member-targeted records that name it, for a fork also the records written with include_forks for the first member of its fork family, plus a record that moved to another member until the member’s session has revoked it; for a member whose session the read does not reach, such a record leaves its slots at once and its delivery reads owed until the new snapshot is recorded) the desired, recorded and effective views and the slot’s state (as above, or blocked with a reason), effective_read (ok, or unreadable with a reason: the member’s session could not be read, and the page still answers; a placed member’s session is on its member host, which the read does not reach) and live_channel_open (operator instructions apply to the member’s turns, not to a live channel). The read never wakes or materializes a member. A member’s delivery is blocked with reason owned_by_session, owned_by_other_mob, slot_managed_by_activation, durability_unavailable (its session service keeps no durable session document) or member_host_unsupported. last_failure is diagnostic and is not kept across a restart. Writes need the AdminHost scope, the read ReadHistory. A refused write answers INVALID_PARAMS (a malformed instruction history INTERNAL_ERROR) with its closed code in error.data.instruction_set_code: invalid_request, digest_mismatch, stale_revision, revision_conflict, unknown_slot, slot_limit_exceeded, body_too_large, active_set_budget_exceeded, owned_by_mob, owned_by_session, owned_by_other_mob, slot_managed_by_activation, durability_unavailable, mob_terminal, malformed_instruction_history or prepared_authorization_required (a governed runtime: see Operator instructions). A mob that cannot answer fails as every mob method does. Dispositions, refusal codes, effects, entry kinds and the state kinds are closed. The advisory values of the status reads (a pending or blocked reason, residency, lowering) may grow: a reader keeps a value it does not know. A session observes each applied entry as an operator_instructions_applied event (see Notifications); the status read is the authority.

Turn methods

turn/start

Start a new turn on an existing session.
Returns the same run-result shape as session/create. A turn/start that arrives while another turn on the same session is running is queued behind it: it runs once the running turn finishes, and the call returns its own result. It is not refused with -32002 (SESSION_BUSY). From 0.9.15 there is one exception: a turn that would change the session’s model settings beside a provider-neutral reasoning effort level (reasoning_effort, or the key of that name inside provider_params) is not queued behind unfinished work. It is answered -32002 at once with the data {"kind": "reasoning_effort_change_needs_idle_session"} and stores nothing: wait for the running turn’s answer, then send it again. The cases are in the table under Model settings on a busy session. A later release is planned to queue it. Since 0.9.5, "session_events": false asks that the turn’s events not be written as session/event notifications. A caller that reads them from a session/stream_open subscription, or reads only the run result, sends it so each event reaches it once. Absent or true keeps them. A turn that also carries the input of another request that wants them still writes them, to that request’s connection (see Notifications). session/create (for its first turn) and mob/turn_start take the same field. A server before 0.9.5 refuses it on turn/start and mob/turn_start, so the Python and TypeScript SDKs send it, from calls that do not stream their turn, only to a server whose contract version is 0.9.5 or later. A turn that fails returns the JSON-RPC code of its typed cause, as the session error mapping does for the same causes: -32010 (provider error) for llm_failure and retry_exhausted, -32011 (budget exhausted) for budget_exhausted and time_budget_exceeded, -32012 (hook denied) for hook_denied, and -32005 for cancellation. Any other cause is -32603. The typed turn error (kind, detail, and the provider facts when known) is in data.error. For the two provider causes the provider facts are provider, retryable and reason (tagged on reason_type), plus model when the failure names one: provider and reason describe the attempt that ended the retries: after a model fallback they are the fallback target’s. retryable: true names the class of the failure: a failure of that class can succeed on a later attempt. It does not say that this one will. It is advice for the caller, and Meerkat itself does not retry the turn again. Read reason beside it; the advice is weakest for three reasons: llm_provider_error with provider_error_kind unknown (a failure nothing classified, retried because nothing says it is final), connection_reset (an endpoint that is never reachable fails the same way every time) and llm_call_timeout (a call_timeout or stream_inactivity_timeout set shorter than the request needs ends every attempt). Treat the provider facts as optional: a turn error with only kind, terminal, outcome and detail is valid, and it is what a server sends for retry_exhausted before these fields were filled for it. The data of a turn whose provider answered 503 until the retries ran out:
A turn the session’s runtime refuses to admit keeps the refusal’s typed code (see Error codes): -32602 for an input the runtime rejects as invalid (an idempotency conflict names the existing input in data.existing_id), -32030 or -32031 when the native owner refuses the input or its readiness is unavailable (the typed detail is in data), -32001 when the runtime driver has no runtime under the session’s id, -32002 when another runtime owner hosts the session or its runtime teardown is still running, -32032 when its runtime authority is unavailable (data.kind runtime_shutting_down once the session runtime’s shutdown began, host_runtime_stopped once the host’s runtime the session ran on stopped and its registration waits for its reload), and -32600 when the runtime’s lifecycle state admits no new input (a retired runtime, or the destroyed runtime of a session that is gone; the message names the state). Only a mechanical failure is -32603.
string
required
Session ID to continue.
ContentInput (string | ContentBlock[])
required
The follow-up prompt as text or typed content blocks, for example [{"type":"text","text":"Continue"}]. Media support is model/provider dependent; see model capabilities.
ContentInput[] | null
default:"null"
Host-attached injected context for this turn. Each entry materializes as a separate typed injected-context user-channel message immediately before the turn’s user message, in order; injected context is excluded from semantic-memory indexing.
string | null
default:"null"
Non-empty, exact request-only host facts for this newly admitted turn; whitespace is significant. Projected before the admitted conversational user message for foreground model calls only; never appended to Session.
string | null
default:"from session"
Model override for this turn. On pending (deferred) sessions this sets the model before materialization. On materialized sessions this hot-swaps the LLM client for the remainder of the session. Known issue, noted 2026-11-13: in releases up to and including 0.9.14 (the first affected release differs by case: see the release page for the range of each), a turn that cannot be started can permanently destroy the mobs its session owns. See the known issue on the 0.9.14 release page for the affected releases, the cases and what to do.
string | null
default:"from session"
Provider override (e.g. "anthropic", "openai", "gemini"). Typically inferred from model.
TurnMetadataOverride | null
default:"preserve"
Omission/null preserves current session parameters. {"action":"set","value":{"thinking_budget_tokens":10000}} replaces the stored override; {"action":"clear"} clears it. The compatibility form {"thinking_budget_tokens":10000} is also accepted as a Set payload. The inner object is the typed ProviderParamsOverride with temperature, top_p, max_output_tokens, reasoning, thinking_budget_tokens, and typed provider_tag extensions, not an arbitrary bag of provider-native keys. Applies alongside model/provider overrides.
TurnMetadataOverride | null
default:"preserve"
From 0.9.15; an older server refuses the field. The 0.9.15 Python and TypeScript SDKs refuse to send it to an older server, so nothing is sent. The session’s provider-neutral reasoning effort level from this turn on (see Reasoning effort). A level ("high", or {"action":"set","value":"high"}) sets it, {"action":"clear"} removes it, and omission/null keeps it. It is its own setting: a turn that replaces or clears provider_params keeps the level unless it also names this field, or its new params name the nested reasoning_effort key. A turn that names both must ask for one outcome: two different levels, or a clear beside a nested level, are refused as invalid params. A level the model or its route does not accept is refused with the reasoning_effort_refused data of session/create, and the session keeps its identity; that refusal is answered when the request arrives, also while another turn of the session runs. A turn that would change the session’s model settings beside a provider-neutral level is taken only when the session has no unfinished work; otherwise it is answered session busy at once (code -32002, data.kind reasoning_effort_change_needs_idle_session) and nothing is stored. The cases are in the table under Model settings on a busy session. mob/turn_start (valid for turn_driven members) takes the same field and is answered the same; a member built from a profile whose provider_params carry a level holds that level.
TurnMetadataOverride | null
default:"preserve"
Omission/null preserves the session’s binding. {"action":"set","value":{"realm":"prod","binding":"anthropic","profile":"claude_oauth"}} selects an existing configured binding/profile; profile is optional. A bare binding object such as {"realm":"prod","binding":"anthropic"} is also accepted as a Set payload. {"action":"clear"} removes the persisted override and resumes normal credential resolution; it does not disable credentials. Do not supply server-owned provenance.
max_tokens, output_schema and structured_output_retries are build settings, fixed when the session’s agent is built. turn/start (and mob/turn_start) refuses each of them while it parses its params, before any session work, with -32602 (invalid params) naming the setting. Set them on session/create, including a deferred create ("initial_turn": "deferred"); a mob member’s are fixed when it is spawned. An explicit null is accepted and keeps the session’s setting.
object[] | null
Tagged structured skill references to resolve and inject for this turn. Each entry uses {"kind":"structured","source_uuid":"...","skill_name":"..."}.

turn/interrupt

Cancel an in-flight turn. No-op if the session is idle.
string
required
Session ID to interrupt.

turn/stop_run

Stop one exact run and terminalize every input already bound to it, including durable steers that joined the run at a model boundary. Unlike turn/interrupt, a joined steer never takes a follow-up turn, and a failed attempt is never replayed. Input admitted but not yet joined to the run stays queued and runs afterwards. Learn the run id from the run_started event (identity.run_id) or from an input’s last_run_id (session/input_status).
The call returns once every contributor has reached its terminal. The receipt outcome is one of:
  • stopped: the run was current. contributors lists every input bound to it, with the delivered completion class and the committed terminal class. A cancelled joined steer reports completion: "runtime_terminated" with terminal: "cancelled"; read terminal for the lifecycle fact. A run a store fence gap suspended, one a restart left open that has not resumed yet, or one whose session store’s writer is stopped, is stopped without waiting: contributors is empty, the run never resumes, and its inputs end cancelled when the runtime settles it (once the store takes writes again, after a gap); read their outcome later.
  • not_current: the run is no longer (or never was) current. Nothing was touched, and newer runs and queued input are not interrupted.
  • not_stoppable: the run is still bound, but a runtime stop or teardown owns it (state). Nothing was staged.
A malformed run_id is an invalid-params error.
string
required
Session ID.
string
required
Exact run to stop.
string
required
Reason recorded with the interrupt.
interrupted is derived from the typed result. The public classifier reports "interrupted"/true for an existing idle session’s no-op as well as a live interruption; it is not proof that a live turn was cancelled. An admitted deferred/staged session has no materialized run to interrupt and returns "staged_noop"/false. Failures use JSON-RPC errors rather than these successful outcomes.

Event methods

session/external_event

Queue a runtime-backed external event for an existing session.
An optional idempotency_key makes the call safe to retry. A retry under the same key admits nothing new: it answers outcome_type deduplicated and names the first admission in existing_id. The same key with other event content is refused with -32602 and data.code INPUT_IDEMPOTENCY_CONFLICT, naming the first admission in data.existing_id; the first admission stands. The key is scoped to the session and kept for the session’s life, across restarts. Object key order inside payload does not matter. The key is canonical text: non-empty, no surrounding whitespace, no control characters, at most 256 bytes; any other key is refused with -32602. A server older than contract 0.9.5 ignores the field and admits the call unkeyed, so a raw JSON caller checks the contract_version from initialize before relying on it. session/input_status with the selector {"by": "idempotency_key", "value": "<key>"} reads the input back by the key the caller supplied; a server older than contract 0.9.12 finds no input that way, so read it there by the input_id the call answered.

session/recall_input

From 0.9.15. Withdraw one queued input of a session, only if no run has taken it yet. The session’s runtime decides in one step whether the input is still queued, the same fact a run reads when it takes the input: either the recall withdraws the input or a run runs it, never both. A recall never interrupts started work; to stop a run, use turn/stop_run. The recall is session-level: any caller that can act on the session can recall any queued input of it, also one another caller submitted, and also by an idempotency key it did not mint. Recalling an input withdraws everything the queue coalesced into it: when a later input took a queued earlier one in (the earlier one’s terminal is coalesced), recalling the later one withdraws both contents. The answer names only the recalled input and does not say that other content went with it. A recall of the earlier input answers already_terminal with coalesced and withdraws nothing. selector names the input exactly as session/input_status does: by the input_id the submit answered, or by the idempotency_key you submitted it under. A client can name only an input whose submit has answered: mob/member_send names the member’s session and the admitted input in its answer (admission, or a keyed send’s continuation status), and session/external_event answers its input_id when the event is admitted, which is at once on a session with no turn running (the event then waits queued for the session’s next turn, except in the instant after a turn’s call has answered: a session still finishing that turn takes the event as soon as the turn ends, as a new turn) and only after the running turn has ended on a session with one (whether the event is then taken at once, as it is over REST, is not established by a run); until then its idempotency key finds no input (session/input_status answers an empty object). A turn/start that waits behind a running turn takes no idempotency key and answers nothing until its own turn ends, so no call names its input: withdraw it by cancelling its request (see Request cancellation).
recall.outcome is one of:
  • abandoned: the input was still queued and is now withdrawn. Its terminal is cancelled (durably, on a persistent runtime), no run will take it, and a caller waiting on it is answered that the runtime ended it before a run (a turn/start request that waits on it is answered -32603 with runtime terminated: input recalled before it started). attempt_count is the number of run attempts counted for the input before it was withdrawn (a failed attempt that returned the input to the queue to be retried); 0 means no attempt was counted. It is not proof that no run ever saw the input: a steer that joined a running turn and went back to the queue because that turn discarded what it had appended counts no attempt.
  • not_queued: a run has taken the input and it has not ended. Nothing was touched and the run is not interrupted. phase is the input’s lifecycle state (staged, applied or applied_pending_consumption) and run_id, when the runtime has one, the run that holds it.
  • already_terminal: the input already ended. Nothing was touched. terminal is its terminal class (completed, cancelled, abandoned, superseded or coalesced). A second recall of a recalled input answers cancelled here, also after a restart.
The list of outcomes can grow: keep an outcome you do not know as it is. Refusals use the existing error codes. An input this session does not hold (another session’s input, an unknown key) and a malformed input_id are -32602; nothing is touched. An unknown or archived session is -32001. The recall never loads or wakes a session: one with no live runtime in the server answers already_terminal from its stored row when the input has ended, and is otherwise refused with -32003 (session not running), so recall the input once the session runs again. A runtime without a store has only its live state to answer from. A server that does not serve the method (0.9.14 and earlier) answers method not found (-32601) and changes nothing. The session’s ordinary refusals apply too: a session that is being torn down, or whose durable state needs a reload after a failed write, refuses the recall as it refuses its other mutations. An error is never an outcome: it does not say whether the input was withdrawn. After a durability refusal no call reloads the session: the runtime reloads it from its store the next time it prepares the session for a turn, and when the server restarts. So start the session’s next turn, or restart the server, then read the input’s status (session/input_status) or recall again: an input the failed call did withdraw is cancelled (a recall answers already_terminal), and one it did not withdraw is queued again and can be recalled, or is held by its run. Do not take session/input_status as that answer before the reload: until then it reads the live runtime, which can be ahead of the store after a failed write. There is no REST route for the recall, and no mob-level method that reaches a member hosted on another host: call session/recall_input on the host that serves the session (for a mob member, its member session, with the input_id the send answered). A send to an autonomous member answers no input_id, on 0.9.14 as on 0.9.15 (by reading the code, not run): see mob/member_send admission.
string
required
Session ID.
object
required
{"by": "input_id", "value": "<input id>"} or {"by": "idempotency_key", "value": "<key>"}.

mob/member_send admission

An unkeyed mob/member_send answers admission when the member’s runtime admitted the send before the send answered: the member session and the input id the runtime admitted, the same pair a keyed send’s admitted status names. Two sends of the same content get two different input ids, so each client can tell its own send apart:
Match input_id against boundary_append_applied.input_id (a steer that joined a running turn) and boundary_appends_discarded.input_ids, or follow it with session/input_status, which also covers a steer that started its own run. An applied event can arrive before the send’s answer: keep unmatched applied input ids for a short time and match them when the answer arrives. admission is absent for a keyed send (its continuation status names its input), when the answer precedes runtime admission (an autonomous member’s inbox delivery), for a member that is not served by a local runtime (not runtime-backed, peer-only or hosted elsewhere), and from a server older than contract 0.9.12. mob/ingress_interaction carries it in delivery.

mob/member_send keys

mob/member_send takes the same optional idempotency_key, deduplicated for the member identity: it survives a respawn. A keyed send is committed as a member continuation and the result carries continuation, a receipt and a delivery status, not a turn:
  • A replay of the key repeats delivery_id and committed_at_ms; status may advance.
  • Keys never expire. A key stays bound for the member identity across respawns and across a re-creation of the mob under the same id (after a destroy or a crash stop): its replay answers the first delivery and its status, stranded when the incarnation it was bound to never admitted it. Send new content under a new key.
  • A keyed send is read through its receipt (continuation.status, or session/input_status in the status’s session by its delivery_id as the idempotency key, or by its input_id), not by its caller key: the key belongs to the member identity, not to a session’s inputs.
  • pending: committed, not admitted yet. A pending that survives a server restart is not proof of loss; do not resend it under a new key.
  • admitted: queued in session_id as input_id, not proof that a turn ran. Follow it with session/input_status.
  • stranded: committed and never admitted, because the member incarnation it was bound to was replaced. This is final: resend the content under a new key. A member’s runtime stops admitting external work only as a new incarnation (a respawn or a rotation, onto a profile that admits none included), so a keyed send committed before that settles stranded.
  • refused: settled as refused, never admitted; reason names why. A keyed send whose member became an identity entry, or whose name became reserved unreadable, after its commit settles refused with reason authority_denied at delivery.
A first keyed send asks the same external admission as an unkeyed one and answers exactly as it does, before anything is committed: a send to an identity entry, or to a member whose name is reserved unreadable, is refused with data.kind identity_member, and a send to a member whose runtime admits no external work is refused as not externally addressable. A profile’s external_addressable defaults to false; setting it on the profile admits external sends, keyed or not, to its members that are no identity entries. Other content under a used key is refused with -32602 and data.kind input_idempotency_conflict, naming the first delivery in data.delivery_id. A keyed send differs from an unkeyed one: the member’s delivery owner admits it with system origin, it is ordered only among keyed sends, render_metadata is refused with a key (-32602), and a host without a continuation service or a governed runtime refuses it with -32020 and data.kind idempotency_unavailable (data.cause no_continuation_service or governed_runtime). A first keyed send to a member without a session binding is refused with -32020 before anything is committed. A status read that cannot be made now answers -32032 (data.kind continuation_status_unavailable): the commit stands, retry the same key. -32603 with data.kind continuation_status_inconsistent is not retryable.

session/peer_response_terminal

Admit a correlated terminal peer response through the typed runtime ingress.
string
required
Session ID to admit the peer response to.
string
required
Canonical peer routing ID.
string
Optional presentation label. It is not used as routing identity.
string
required
Peer correlation ID for the request this terminal response completes.
string
required
Terminal response status: "completed", "failed", or "cancelled".
any JSON
required
Peer-returned terminal payload.
A refused runtime admission keeps its typed code, as for turn/start; -32602 if the session locator is invalid. This is a queue-only runtime admission path; it does not create a second direct execution loop.

comms/peers

List discoverable peers from configured TrustedPeers and active in-process registrations. Requires the comms feature.
string
required
Session ID to query peers for.
Use peer_id as the to value for comms/send; name is display-only and may collide. Each entry uses the canonical typed PeerDirectoryEntry shape: address is {transport, endpoint}, source records discovery provenance, sendable_kinds states supported comms operations, capabilities carries the versioned capability envelope, and meta contains supplementary description and labels.

skills/list

List all skills with provenance information, including active and shadowed entries.
array
List of SkillEntry objects with key, name, description, scope, canonical source provenance, is_active, and optional canonical shadowed_by provenance.
Returns error -32603 if skills are not enabled. skills/inspect is not part of the advertised RPC catalog. Use skills/list for provenance, or the CLI/MCP skill inspection surfaces when full skill bodies are needed.

Event replay and durable projection

The events/* family is the complete cursor-based replay surface for hosts that report runtime/capabilities.features.event_replay = true:
  • events/latest_cursor returns the latest cursor for a typed scope
  • events/list_since pages envelopes after an optional cursor and reports latest_cursor plus has_more
  • events/snapshot returns a point-in-time session snapshot paired with its cursor
The current public EventReplayScope is {"type":"session","session_id":"..."}. A cursor is scope-bound and monotonic; scope mismatch and a cursor ahead of the latest sequence fail typed rather than being silently clamped. Live session subscribers use a bounded 256-entry broadcast. If a consumer falls behind, it receives AgentEvent::StreamTruncated with StreamLagged { dropped }, then retained events. Persistent hosts can install one internal audit projector through a separate unbounded queue and warn when the queue reaches 1,024 pending events. UI lag cannot drop projector input. EventStore append remains asynchronous best-effort derived state: an append fault latches projection halt and replay fails closed, but does not undo the committed turn. The RuntimeStore/backend carrier remains session authority; SessionStore rows and EventStore are component/content and projection seams.

Durable jobs and monitors

The app-facing jobs/* methods expose realm-scoped job projections without worker attempt IDs or fence tokens. Read methods cover summaries, progress, terminal results, artifact references, and health. jobs/cancel commits a cancellation request, jobs/retry asks the generated job machine to schedule a retry at retry_due_at_ms, and subscribe/unsubscribe manage durable record/notification/event delivery. monitors/start is the explicit high-trust script-monitor entry point. It requires session_id, a caller-stable submission_key, command, positive timeout_secs, restart_class, and delivery. The default output protocol is framed_jsonl; lines is also supported. Agent-authored monitors cannot claim the adoptable restart class. Detached shell execution fails closed unless the realm supplies persistent job and blob stores plus its runtime delivery projector; there is no volatile fallback. The meta/jobs/* methods are host-worker mutation methods. Every heartbeat, progress, checkpoint, completion, failure, or cancellation acknowledgement is admitted under the exact attempt and fence authority carried by its typed params. Application clients should not synthesize worker mutations from the safe JobSummary projection.

jobs/health

jobs/health returns { "detached_jobs": JobHealthSummary }. The summary separates three states:
  • ok: the complete census observed no unhealthy job fact
  • degraded: the census observed a stale lease, attention state, or backlog
  • unreadable: a read failed or the bounded census was truncated, so it did not establish health
coverage is either {"kind":"complete"} or {"kind":"truncated","scanned":N,"limit":N}. A truncated census always has status: "unreadable"; its counts are lower bounds. Keep pending_outbox_jobs separate from runtime_inbox_backlog: the former counts realm jobs whose delivery was never handed to a runtime, while the latter is a host-store-scoped count of committed runtime deliveries that were accepted but not drained. It can therefore include sessions from other logical realm IDs on the same host.

Blobs and artifacts

blob/get accepts a realm-local blob ID and returns BlobPayload with blob_id, media_type, and base64 data. Assistant image blocks and job results can carry blob references instead of inline bytes. Artifacts are stable metadata records over generated output. artifact/list filters by optional session_id and exact labels, artifact/get reads one record, and artifact/download resolves a blob-backed payload with an optional expected_media_type integrity check. Artifact IDs are opaque realm-local identities, not filesystem paths.

Approvals

The approval family consists of approval/request, approval/list, approval/get, and approval/decide. Requests carry a typed owner, resource, proposed action, risk, non-empty allowed_decisions, optional expiry, metadata, and provenance.
Request
Owners are runtime, session, mob, run, tool_call, or external_member. Resource kinds are file, shell_command, tool_call, device, runtime, network, or other; risk is low, medium, high, or critical. Proposed action kinds are shell_command, file_write, file_delete, network_call, device_control, tool_call, or other. Decisions are approve or deny, and record status is pending, approved, denied, expired, or cancelled. The service rejects an empty decision set, an unsupported decision, or a second terminal decision. Expiry is evaluated lazily on approval/get, approval/list, or approval/decide: a past-due request may first be stored as pending, but its next observation persists expired and it can no longer be decided. cancelled is a durable status that can be restored, but the current public RPC service has no approval/cancel transition. external_member is an audit owner shape, not a cross-host forwarding contract. Multi-host v1 keeps approval records and decisions host-local. RPC opens <store_path>/approvals.json whenever its PersistenceBundle exposes a store path, including a named built-in memory realm. Only an ad hoc bundle with no store path falls back to process-local approval records. The approvals runtime host feature is true only when this approval service is persistent. The file store is a one-host sidecar. It serializes updates with a process-local mutex and atomic temp-file rename, but has no cross-process lock, revision, or CAS. Run only one approval-owning RPC host against a given approvals.json; shared-state multi-host approval writing is not supported.
Approval records are audit data, not a secret store. The proposed action body, request body, metadata, and provenance are persisted as supplied. Do not put credentials or tokens in those fields, and protect the resolved realm store directory with host filesystem permissions. FileApprovalStore does not currently force a private file mode independently of the process umask.
These methods maintain approval audit lifecycle records only. Creating or deciding a record does not automatically gate, authorize, or execute a shell command, tool call, device action, or any other side effect. Plain approval records emit no notification: a client polls approval/list or approval/get to see a request and its decision, and a host operation that needs its decision pushed holds a durable decision instead (DurableDecisionService::hold, through SessionRuntime::decision_service).
requester and the actor supplied to approval/decide are audit identities, not transport authentication proofs. rkat-rpc does not authenticate them. Authorize approval decisions in the trusted host or authenticated proxy before forwarding the RPC call. REST, MCP, and CLI do not expose approval methods.
When rkat-rpc serves a stock governed realm whose owner requires R3 for an operation (see governance settings), the realm’s native owner issues one consent approval for the exact call and the stdio pipe’s operator decides it. The pipe’s operator is the operating-system user who started it: device trusted, in the pipe’s own authentication scope, so a rule that requires a person refuses it. The scope ends with the pipe: from EOF on, while the connection drains its in-flight requests, no decision in it is eligible. approval/consent_decide takes only the approval and the decision. The connection names the approver, its assurance and its scope; any other field is an invalid parameter. It is listed by initialize only on a pipe that serves consent.
Request
Each recorded transition arrives as an approval/consent_notice notification (ConsentNoticeParams): kind is requested, approved, denied, used or withdrawn. An approval executes nothing by itself. The pipe keeps answering for its operator on an approved approval until it is used or withdrawn: only the pipe’s end revokes the operator, so an approved consent whose spend comes after the pipe ended is withdrawn as authority_changed, with zero entry. A requested notice carries the approval’s presentation (ConsentPresentationParams), projected from the approval owner’s own record before any decision: the exact action (its kind, the tool and the call’s arguments), its risk, the account the operation acts with and the mandate it runs under (each as the operation’s owners stated it, absent when they stated none), the accepted_assurance of the owner’s rule and expires_at. The record keeps the account and the mandate in its stock.action_account and stock.review_mandate labels. The pipe decides only what it presented: an approval is issued only while the pipe is open, and a decision on an approval the pipe never presented is refused.
Notification

Scoped tool grants

A session created with grant_gated_tools mounts its gated tool families and names hidden, and the tools of its gated MCP servers too, from the moment they appear: the model is not shown them and every call is refused until a live grant opens them (see scoped tool grants). A mob member’s build gates what its profile’s tools.grant_gated and its role’s current gate name; a gated MCP server a member’s profile configures starts no process until a live grant of that server covers it at the member’s build (the build decides this as it composes the member’s tools), so after such a grant the member connects it at its next build (a mob/respawn, for one). tool_grants/grant, tool_grants/revoke, tool_grants/list and tool_grants/audit manage the grants of a session or of a mob member identity, and tool_grants/request asks for a grant a person approves. They read and write grant rows (and a request its decision) only: no method loads, registers or wakes the session or the member.
Request
Response
  • tool_grants/grant opens a target for the subject: a tool name ({"kind": "tool", "name": ...}) the subject’s gate names or a gated family provides, a family the gate names ({"kind": "family", "family": ...}; the server fills in names with the names the family can provide, so omit them), or an MCP server the gate gates ({"kind": "mcp_server", "server": ..., "tools": [...]}): every tool that server provides when a boundary or a call adjudicates the grant, or, with tools (a non-empty list), only those of its tools named there. A server is gated when the gate names it, or when the gate’s unconfigured_mcp_servers is on and the subject’s build does not configure it; a grant of a server a session configured itself opens nothing, since that server is not gated. A tool name only a gated server provides is no tool target (target_not_gated, whose message names the server form). The subject is a session ({"kind": "session", "session_id": ...}), whose recorded gate the target must be in, or a mob member identity ({"kind": "identity", "mob_id": ..., "identity": ...}), which must be in the mob’s roster and whose gate is the one its next build resolves: its profile’s gate joined with its role’s current gate (the role’s current gate is the own gate of a store-owned identity declared with its role’s named profile). An identity grant is decided against the mob’s live roster as it commits, in order with the retirements that end an identity: a member retired before the commit is refused subject_unknown, and a retirement after the commit ends the grant. A grant between a respawn’s retirement of the old member and the seating of its replacement is refused subject_unknown too, since the identity is out of the roster then: retry it once the respawn answers. Exactly one of duration_ms and expires_at_ms (UNIX ms) bounds the grant, at most the host’s maximum lifetime (24 hours by default). scope is {"kind": "window"} (the default) or {"kind": "current_run"}: the grant then also admits only the calls of the run its subject is running now, and ends with that run (the grant’s scope is {"kind": "current_run", "run_id": ...}). A session’s run is its own; an identity’s is the run of the session its member holds on this server, and the member’s end of that run ends the grant. A subject that runs no turn (an idle session, or an identity whose member runs no turn here) refuses a current_run grant with the request refusal run_not_active (below), and nothing is issued. decision_ref, when given, is the host’s reference to the decision it made before issuing (non-empty, at most 1024 bytes, no control character): the grant’s issuer records it, as attribution only. An identity grant answers applies, whether it applies to the member’s running build: now (that build gates the target), not_mounted (that build, or with no live build the next one, ignores the target as not mounted) or at_next_build (the member is not live here, its live build predates the gate that names the target, or the target is a gated MCP server the member’s profile configures that its live build left unattached, since no live grant covered it then). It is advisory: the grant is issued either way. A session before or during its first turn is granted from its staged build. A gate no grant could honour fails the session’s build, which a deferred create reports at its first turn/start.
  • tool_grants/revoke ends a grant before its deadline. It is idempotent: revoking a grant that already ended answers it as it stands, and changed says whether this revoke ended it. A revoke at or after the deadline records the expiry instead.
  • tool_grants/list answers the subject’s grants, each due one settled as expired first. Ended grants (expired, revoked, run_ended) are listed only with include_ended; unreadable names any stored grant this server cannot read (written by a newer version, or damaged), which opens nothing, and any grant a host store quarantined (the store reports a conflict for its scope, so its session and tools are unknown), whatever session it was granted to. For a member identity in the roster it also answers the member’s gate: running, what its live build gates (its gated names under tools, with its gated servers and unconfigured_mcp_servers) and the names it ignored as not mounted, or null when no build of the member is live here; and next_build, the gate its next build resolves, split the same way. Advisory, like applies. On a server that keeps durable decisions the subject’s grant requests follow its grants: each open or approved one as requested, and with include_ended each rejected, expired, withdrawn or refused one whose deadline is within the grant policy’s maximum lifetime of now as declined (its ended_at_ms when it ended; an older one stays readable through decision/list). A request whose grant was issued is listed as that grant only.
  • tool_grants/audit answers a page of the subject’s audit log, granted (with the grant’s scope), expired (with the driver that observed it: timer, boundary, dispatch, read, revoke, build (a build reading which gated servers a grant covers), or run and recovery for a run that ended at or after the deadline), revoked, run_ended (with the run_id and the driver that ended it: run at the run’s end, recovery when durable-tail recovery closed a run a stopped process left open, or the boundary or dispatch of a later run) and refused rows, in sequence order after after_sequence. limit defaults to 100 rows and caps at 1000; a full page carries next_sequence, the next page’s after_sequence. A row this server cannot read is named in unreadable with its sequence, and the rest of the page is served.
  • tool_grants/request asks for a grant a person approves. It names a subject (a session or a mob member identity), and the target and scope as a grant does, duration_ms (the grant’s window from its issuance, at most the host’s maximum lifetime) and an optional reason, and holds a durable decision of kind tool_grant.issue for the approver id operator, which expires after an hour undecided. This server is its requester (the runtime host rkat-rpc of the realm); the stdio operator can grant directly, so approving a request this server made adds an approval record, not authority. Nothing is issued: the result is the request as a list shows it (status requested, the grant_id its grant gets, its issuer {"kind": "approval", "approval_id": ...} naming the decision) and the decision. Once a person approves the decision (see durable decisions), this server issues the grant under that id, its window starting then, while the realm still lists the approver id for the operator; a request rejected, withdrawn or left undecided past its deadline issues nothing, and neither does an approval of an identity’s request executed while no member holds the identity’s name (its member retired, its entry ended, or its mob was reset) or after its mob was replaced, refused with the reason subject_ended, or while the server cannot tell what the identity is (subject_unknown, fail closed). A request records the life of the identity it was asked in: an approval executed after that life ended (its member retired, its entry ended or its mob was reset, even when a new member took the name in the same incarnation since) is refused subject_ended too, and its notice reaches no member of a later life. A respawn keeps the life. A one-entry unlist or a complete roster’s seal of an identity entry with no member leaves no record a restart reads, so after a restart an approval of a request asked before such an end can reach a new member of the name: reject or withdraw an identity’s open requests before declaring its name again (Known limitations). An identity end that lands while the approval is being executed, after the server read the identity and before the grant’s commit, can leave the grant live on the ended identity: revoke it. A current_run request names the run its subject is running when it is asked, and is refused when the subject runs another run by its approval. When the request ends, its session receives a tool_grant_request external event, like any input: the decision_id, the outcome (granted with the grant_id, rejected, expired, withdrawn, or refused with a reason) and the target. An identity’s notice goes through the mob’s member input instead: a keyed member send under the decision’s key, whose text is tool_grant_request: followed by the same fields as JSON, admitted into the session the identity’s member holds when it is delivered; an identity with no member left ends the notice failed. A server whose persistence keeps no durable decisions answers capability unavailable (data.kind = "no_decision_store"). A gated session’s agent asks the same way through its request_tool_grant tool (see scoped tool grants); while the server runs the executor of the kind, its agents’ requests name the realm’s agent rkat-agent as their requester. A replayed agent call answers the request it held; an agent’s call for a target its subject already has an open or approved window request for joins that request while it is open instead of holding another, and holds a new one after it ends. A joined request keeps its own duration, which can differ from the one asked: the tool’s answer says the call joined and gives that request’s duration_ms.
List and audit read the subject’s grant rows without checking that the session or the member exists: an archived session’s grants and a retired identity’s grants stay listable and auditable, and a subject with no grants answers empty. An identity subject resolves its mob only, in the mob’s running incarnation. A member identity’s grant opens its names for the member’s builds while the mob runs at the incarnation it was issued in, across respawns, restarts and upgrades; a mob destroyed and created again under the same id is a new incarnation, whose identities hold none of the old grants. A member’s tool_grant_required refusals are audited under its identity. An identity’s grants end, revoked, when the identity ends, and so do the grants of the session the mob holds for it then (its member’s session, or an identity entry’s archived session). The identity ends at the end of a plain retire of its member; at the end of a retirement that unlists or removes its identity entry; at the one-entry unlist of an unseated identity entry, or a complete roster’s seal of one it does not list and no host’s intent row names; at the removal of an unseated store-owned identity; when a respawn whose replacement fails after the old member’s archive is abandoned, by its own step or by the resume after a stop; and at a reset of its mob, which ends every identity the mob held. A respawn keeps them, and so does a retirement an identity entry outlives (the entry stays unseated, and the next apply seats it on its own session), and so does a host’s adoption of a declared identity, which ends the identity’s entry, not the identity: the identity continues under the host’s intent. A grant ended with its identity explains no later refusal: a name created or declared again, on a fresh session or on the old one, needs a grant of its own (tool_grant_required). The one exception is a session the mob no longer held for the identity when it ended (an archived session of an earlier fresh-session rotation, or the old session of a respawn abandoned after its old member’s archive): its own session grants stay live until they expire, so revoke them before resuming that session (Known limitations). A grant’s status is active, expired, revoked or run_ended; a grant request’s is requested or declined. A request’s subject, target and scope refuse a kind or a field this server does not know (invalid params), so a request is never read as wider than it asked. Every vocabulary a result carries (subject, target and scope kind, status, issuer, audit event kind, expiry driver, refusal reason) decodes a value a later version adds as unknown, which this server never sends: a client older than run scopes reads run_ended as unknown. Every refusal of a request’s subject, target, scope, window or duration, grant id, decision reference or page limit answers invalid params with typed data, the request refusal under tool_grant_request_refusal:
Its kind is subject_unknown (no such session, or no such mob or member identity; an unparseable session id included), target_not_gated (the subject’s gate does not name the target), invalid_window (a window that is past, empty, longer than the maximum, or given twice or not at all), empty_target, not_found (an unknown or malformed grant id, with grant_id), invalid_decision_ref, invalid_page_limit (an audit limit of 0) or run_not_active (a current_run grant or request whose subject runs no turn). A request’s duration_ms is refused as a grant’s window is (invalid_window). server_not_installed, no_live_grant and invalid_wait are reserved for hosts that keep an installation list or attach a granted MCP server live; rkat-rpc never sends them. A request that does not decode (an unknown subject, target or scope kind, an unknown field, a malformed value) is refused as plain invalid params, with no data, and so is a request too large for a decision to hold (its reason past the 256 KiB bound of a decision’s rendering or body). Other errors use the standard codes: SESSION_BUSY when concurrent writers changed the grant under a grant or revoke twice, which a retry resolves; capability unavailable for an identity subject on a server that runs no mobs, a store without grant support, or a request to a server that keeps no durable decisions. A request’s decision is held as any decision is: its errors are the durable decision errors. The stock governed stdio pipe serves a fixed method set: it does not serve the tool_grants/* methods, and its session/create refuses grant_gated_tools as an unsupported parameter.
rkat-rpc does not authenticate the caller of these methods: a grant’s issuer is recorded as an operator without a caller, and a request’s requester is the server itself. Authorize grant administration in the trusted host or an authenticated proxy before forwarding the call.

Durable decisions

A durable decision holds one operation until an attested party decides it, its requester or the host withdraws it, or its deadline passes (see durable decisions). The decision/* methods read and act on the decisions of the runtime’s persistence, one row or one index page per call: decision/list, decision/get, decision/rendering, decision/present and decision/withdraw. They are served since 0.9.11; an older server answers them method not found (-32601). A runtime whose persistence keeps no durable decisions answers them capability unavailable, with data.kind = "no_decision_store".
Request
Response
  • decision/list reads one page, in decision id order, of the decisions every set filter matches: kind, phase, approver_id and requester (a principal key). limit is 100 when absent; a larger limit reads as 500, and a limit of 0 is invalid params. next_after names the decision id to read the next page after. A decision past its deadline reads as expired. A row this server cannot read is listed under unreadable and nothing executes it. A phase this version does not know is refused, never read as no filter.
  • decision/get reads one decision, and records its expiry when its deadline passed. include_request: true adds the held request. A row this server cannot read answers decision_unreadable. An executed grant.child decision carries effect, what its execution did: {"grant_id": ...}, the id of the approval-carried grant it issued. A decision that is not executed, and a decision of any other kind, carries no effect. Every answer that carries a decision carries it alike: decision/list, decision/present, decision/withdraw and the host adapter’s decision/decide. A later version may add fields to effect: read it tolerantly.
  • decision/rendering returns the one canonical rendering of the held request, its renderer and subject digest, and its canonical parts for max_part_bytes (one part when absent): consecutive byte ranges on character boundaries, each with its own digest. Like decision/get, it records the decision’s expiry when its deadline passed, and a row this server cannot read answers decision_unreadable.
  • decision/present records what a host presenter showed: the audience ({"kind": "approver", "approver_id": ...} or {"kind": "reviewer", "reviewer": ...}), the digest of the rendering shown, the part size and the parts shown, the channel and message references, and the host clock reading at_ms. A surface with a size limit that showed a summary saying it is shortened records it with the link the summary carried to the full presentation: {"reference": ..., "served_digest": ...}, the digest of the rendering that link served. It counts only when it shows every canonical part of the held rendering, or its link served the held rendering (its served digest is the subject digest), to the party that decides now; a presentation at 0 is no reading of when it was shown and is refused. A decision’s presentations carry each recorded link.
  • decision/withdraw withdraws an open decision as the host.
A failed call is a JSON-RPC error. The answers the decision methods type carry a closed data.kind: Store faults carry no data and use the approval store codes: -32033 store unavailable (nothing was written), -32034 conflict (another owner changed the decision) and -32035 commit unknown (the write may have committed). Each decision call opens its own store connection and never waits, so a call made while another one writes (a connection recording a presentation, for one) can answer -32033: the caller makes it again. A request value this version cannot read is invalid params (-32602) with no data. The refusal kinds are closed, because they bear authority: a client can match on every kind, and this version sends no other. The vocabularies a result carries (phase, stage, notice and the others) may gain values in a later version; a client keeps a value it does not know as the server wrote it. No request body names who decides a decision. A host’s trusted transport adapter decides one by dispatching decision/decide through MethodRouter::dispatch_with_decision_event with the AuthenticatedDecisionEvent it built from the human’s authenticated event: the attested decision (who decided, how they were authenticated, the ingress and event reference, the time the ingress observed the event and the digest of the rendering they saw) and the evidence that they may act for the decision’s approver id. The request names only decision_id, approve, presented_digest and an optional reason, and must equal what the event binds; a request that names an approver, actor, assurance or scope is invalid params. Plain dispatch answers decision/decide method not found, except on a stdio connection whose operator decides (below). A host’s adapter learns that a decision opened without polling: DurableDecisionService::subscribe_openings, on the owner SessionRuntime::decision_service returns, yields each decision the owner opens from then on (DecisionOpening::Opened), as the hold wrote it, with the rendering to show. The adapter shows it to the person and relays their authenticated answer through MethodRouter::dispatch_with_decision_event. A subscriber that falls behind reads DecisionOpening::Missed and lists the open decisions to catch up, as it does when it starts; a decision another process holds in the same store is not announced. A decision held in its review stage is announced when it opens; its later escalation to the human stage is not. A host’s own hold, read or decide can answer store unavailable (DecisionError::Unavailable, -32033 on the wire) while a connection records a presentation, with nothing written: the host makes it again. Only a connection whose operator decides a decision is told when it opens (below): a connection without an operator, a TCP connection among them, gets no decision/notice.

The operator of a stdio connection

On a Unix build with local authorization, an rkat-rpc stdio connection has an operator who decides durable decisions on it: the operating-system user who started it, device trusted, in an authentication scope of the connection’s own. The operator acts for the approver ids the realm’s configuration lists for it, ["operator"] unless [governance.decisions] operator_approver_ids says otherwise. The connection presents decisions to its operator when they open and when its client lists them. A decision the runtime’s decision owner opens while the connection is open, that waits for a human and is addressed to an approver id the operator acts for, is presented at once, without a request, as it stands when the connection reaches it: one decided in the meantime is not shown. A connection that falls behind the openings catches up: it presents, page by page, each open decision the operator acts for that it has not presented yet, one held before the connection started included. Before it answers a decision/list, the connection presents each decision of the returned page that is open, waits for a human, is addressed to an approver id the operator acts for and was not presented on this connection yet, in page order: one held before the connection started or by another process, or one that reached its human stage later. Starting the connection presents nothing, and the client’s own paging (after, limit) reaches every decision. A decision is presented once per connection: a list does not present again a decision the connection presented when it opened. For each, the connection reads its clock, writes a decision/notice notification carrying the whole rendering as one canonical part, waits until the notice is on the pipe, and only then records the presentation: to the approver, on the connection’s own channel (a channel_ref that starts with rkat-rpc:stdio:), under the notice’s id (message_ref equals notice_id), at that clock reading. A list’s notices precede its answer, and the answered page carries each decision it presented as recorded. A notice that could not be written records nothing, and a decision whose presentation was not recorded is presented again by a later list, so a client keys notices by decision_id. The channel_ref is an opaque string; nothing parses it.
Notification
event is presented; a client reads an event it does not know as unknown and ignores it. The operator decides with decision/decide. The request names only decision_id, approve, presented_digest and an optional reason; the connection builds the authenticated event itself: the operator as the decider (device_trusted, in the connection’s scope), ingress rkat-rpc-stdio, an event reference from the request id, the server’s clock as the observed time, and the approver id of the stored decision. A decide is eligible only for a decision this connection presented, while the configuration still lists its approver id when the decide arrives and while the connection is open; a decide waits for a presentation in flight on the connection. Any other decide is refused as invalid params with data.kind = "decision_refused" and data.decision_refusal.kind = "not_eligible". A client’s own decision/present records a host presenter’s showing; it never makes a decision decidable on the connection. A connection without an operator presents nothing on decision/list, is told nothing when a decision opens, and answers decision/decide method not found (-32601, no data.kind): a TCP connection, a build for another platform or without local authorization, and a router an embedder dispatches to directly. The stock governed stdio pipe serves the same two methods for its operator, in its consent surface’s scope, presents to it in the same way, and lists the methods in its initialize answer. Its approver ids are the host’s configuration as the pipe started; a change reaches the pipe at its next start.

Schedules, WorkGraph, and multi-host mobs

The schedule family provides CRUD, pause/resume, occurrence listing, tool schema discovery, and direct typed tool calls. Schedule and WorkGraph state are realm-scoped durable domains when the owning feature and store are available. Public WorkGraph RPC is intentionally observational: item get/list, ready work, snapshot, event history, goal status, and attention-list reads. Agents mutate WorkGraph through the workgraph_* tool family; trusted in-process hosts own goal and attention mutation authority. Multi-host mob RPC includes host bind/revoke, host and route observation, scope grants, hard cancel, placed member history, and member live-channel control. Check runtime/capabilities.features.multi_host_mobs rather than inferring support from generic mobs or the server version. mob/member_live_open opens a member’s live channel through its mob, for local and placed members alike: the mob checks the member, then the member’s own live host serves the requested transport or refuses it typed. With transport: "webrtc" the result is a WebRTC bootstrap whose offer is answered with live/webrtc/answer on this server. A host that serves no WebRTC refuses it (INVALID_PARAMS, cause LiveTransportUnsupported) before it connects a provider; a member host started by rkat mob host serves WebSocket only. The optional execution_identity selects a channel-scoped execution profile exactly as on live/open, for example gpt-live-1 with {"version": "v1", "profile_id": "openai.gpt-live-1.client-context.v1"}. It requires transport: "webrtc" (INVALID_PARAMS otherwise) and a server composed with an execution-identity authority (-32020, capability unavailable, otherwise), and it is served for a member local to this server only: a placed member refuses it (INVALID_PARAMS, cause Unsupported) with nothing dispatched to its host. An execution-identity authority’s refusal (access denied, an identity it does not admit, a member it finds ineligible) answers -32026 (host unavailable) with the authority’s reason, where live/open answers -32020 or INVALID_PARAMS. The connection that opened the channel keeps its playback custody and answers its offer with live/webrtc/answer, as for a strict live/open; mob/member_live_close closes it through the same authority. In multi-host v1, controller session/* methods do not proxy a placed member’s host-local session. The session-scoped live/open opens no live channel on a mob member’s session, live or not, and never restores one from storage: the member’s mob does both, after checking the member (not retiring, in cleanup or revoke, and restored). It answers INVALID_PARAMS (-32602) with data kind mob_member_session_addressed_by_id (and the session, mob and member), and nothing is opened or restored. Open the member’s channel with mob/member_live_open. Durable member role migration is not part of mob/spawn, profiles, or any public JSON-RPC/SDK params. The one-shot resume_from_role declaration exists only on trusted in-process SpawnMemberSpec and the private remote-host MaterializeLaunchMode::Resume wire. It authorizes one exact cold migration from the stored predecessor role while keeping mob ID, member identity, session, and transcript fixed; live sessions and mismatched declarations fail closed. A mob/spawn or mob/spawn_many item whose launch_mode resumes an existing session delivers the member’s first turn (its kickoff or initial_message) only while that session’s first turn has never started, and then once. Otherwise the resume runs no kickoff and does not deliver initial_message; a first turn that started and was interrupted is not re-run. A placed member follows the same rule; a resume on a member host of 0.9.4 or earlier still runs the first turn. A resume of a session that is bound to another member (its member binding, or the comms name it was created under, names another mob or member) is refused with -32602 and data.kind resume_session_bound_to_another_member (session_id, member_id, bound_mob_id, bound_member_id), and nothing is seated.
Known issue, noted 2026-11-13: in Meerkat 0.7.29 through 0.9.14 (0.6.0 through 0.7.28 not established), a mob/spawn that resumes an existing session can archive that session if the mob is stopped, completed, reset or destroyed, or the host shuts down, while the spawn is still in progress, or if the attach itself is refused after it was prepared. Read from the source and not yet confirmed by a test: the mobs that session owns are then destroyed at the next start. See the known issue on the 0.9.14 release page for the affected releases, the cases and what to do.

workgraph/get

Read one WorkGraph item by id. Requires the workgraph feature and a realm-scoped runtime; a runtime without a realm identity returns a typed fault instead of inventing a default scope.
The response is abridged; the full WorkItem shape is in the WorkGraph reference.
string
required
The WorkItemId.
string
Defaults to the runtime’s realm. Any other value is rejected: the service holds exactly one WorkGraphNamespaceGrant.
string
Defaults to the granted namespace (default on standard surfaces). Any other value is rejected.
Every evidence entry, here and everywhere a WorkEvidenceRef appears (the workgraph_add_evidence tool argument, host mutation surfaces such as Meta’s meta/workgraph/evidence/add), has the shape {"kind": string, "id": string, "label"?: string, "summary"?: string, "withdraws"?: string[]}. kind is an opaque provenance label (artifact, pr, log, summary, notification, …); the reserved confirmation kinds (host_confirmation, principal_confirmation, supervisor_confirmation, reviewer_confirmation) are refused from generic callers and stamped only by trusted goal-confirm authority. withdraws lists the ids of earlier evidence on the same item that the entry withdraws; nothing is removed, and an entry is withdrawn when a later entry lists its id (see Withdrawing Evidence).

workgraph/list

List items in the granted realm and namespace, most recently updated first (updated_at, then id, both descending), so a cut keeps the most recently updated items. Params are a WorkItemFilter; all fields are optional and an empty object lists live work.
string
Defaults to the runtime’s realm; must equal the granted realm.
string
Defaults to the granted namespace; must equal it.
boolean
default:"false"
Present in the wire shape, rejected by the standard single-grant services. A namespace grant never implies a multi-namespace capability.
WorkStatus[]
Keep only items whose status is listed: open, in_progress, blocked, completed, cancelled, failed. Checked before the terminality rule below.
string[]
Every listed label must be present on the item (a conjunction). ["release", "docs"] returns only items carrying both; filter on one label to widen the result.
boolean
default:"false"
When false, completed, cancelled, and failed items are dropped even if statuses names them: {"statuses": ["completed"]} alone returns an empty list. Set it to true to read closed work.
integer
default:"100"
Maximum items returned. Omitted means 100; values above 1,000 fail with INVALID_PARAMS before the store is queried.
string
The next_cursor of the previous page. The page holds the items strictly after the cursor’s position, in the same order, so items never shift between pages. Pass it with any filter. A cursor is opaque and continues only the read that returned it: a cursor that does not decode, has another version, or came from workgraph/ready or workgraph/snapshot fails with INVALID_PARAMS. It is not authority: the namespace grant scopes every page.
The result is {"items": [...], "total_items": N, "truncated": bool, "next_cursor": "...", "anchor_event_seq": N, "changed_since_anchor": bool}. total_items counts every item that matched the filter at this read, before the cursor and limit cut them. truncated is true when matching items exist after the last one returned, and next_cursor is present exactly then (a limit: 0 page returns only the totals). anchor_event_seq is the event ledger’s high-water mark when the walk began: the first page reads it before its rows, and the cursor carries it (it is absent when the ledger had no event). changed_since_anchor is true when the ledger has moved past it. A walk over every page keeps these promises:
  • An item that does not change during the walk is on exactly one page.
  • An item that changes during the walk is on at most one page. It can repeat only when a write gives it an updated_at older than the one it had (the store clock moved back), so a reader that dedupes by id and keeps the higher revision is safe.
  • An item changed or created after the anchor can be missing from later pages. Those pages say changed_since_anchor: true, and workgraph/events with after_seq set to anchor_event_seq names every such item. Execution-binding events also move the ledger, so the flag can be true with no public change. The flag covers writes only: a change that writes no event, such as readiness arriving as time passes, is not flagged.
Items and edges are never deleted. There is no unlink or delete method on any surface and no tool for it; the graph is an append-only ledger. To take an item out of live views, close it as cancelled (it then hides behind include_terminal); to replace it, create the successor and link a supersedes edge from the new item (from_id) to the old one (to_id).

workgraph/ready

List items whose machine-derived readiness holds right now: live status, no unresolved blocks edge, parent join satisfied, and time gates passed. Params are a ReadyWorkFilter.
string
Defaults to the runtime’s realm; must equal the granted realm.
string
Defaults to the granted namespace; must equal it.
string[]
Every listed label must be present (same conjunction as workgraph/list).
integer
default:"100"
Maximum items returned after sorting by priority (high first), then creation time, then id. Omitted means 100; above 1,000 is INVALID_PARAMS.
string
The next_cursor of the previous workgraph/ready page: the page holds the ready items after it in the same order. A cursor of another read, of another version, or one that does not decode fails with INVALID_PARAMS.
There is no include_terminal here because a terminal item is never ready. Readiness is evaluated atomically over every live item of the namespace, however many it holds, and the cursor and limit then cut the sorted ready items. The result has the page fields of workgraph/list, where total_items counts every ready item. The cursor’s order key is the priority, creation time and id: an item whose priority changes during a walk can move across the cursor either way, so it can be missing or appear twice, and one whose readiness changes during the walk can be missing. changed_since_anchor flags the items an event changed after the anchor, such as a priority update or a blocker’s close. Readiness that arrives by time passing (not_before, snoozed_until) writes no event, so it is not flagged. A reader that dedupes by id and keeps the higher revision is safe.

workgraph/snapshot

Read one atomic observation of the namespace. Params are a WorkGraphSnapshotFilter with the same fields and semantics as WorkItemFilter (realm_id, namespace, all_namespaces, statuses, labels, include_terminal, limit, cursor); a cursor continues only a workgraph/snapshot walk.
statuses, labels, and include_terminal select the items exactly as in workgraph/list; limit then keeps the most recently updated of them after the cursor (default 100, maximum 1,000), and total_items, truncated and next_cursor report the cut as in workgraph/list. A first page’s edges contains only edges whose both endpoints are among its items; a continuation page adds the edges from its items to the items at or before the cursor, so a walk reports every edge between the items it returned once, on the page of the edge’s later end. attention holds only bindings on the page’s items, and ready_item_ids the page’s items that are ready at captured_at. A snapshot therefore omits an edge to a terminal item unless include_terminal is true. limit bounds the items only: edges and attention follow the returned items and are neither counted nor cut on their own. Readiness is classified against the whole namespace, however many items, edges and attention bindings it holds: a returned item is not ready while a blocker the cut left out is unresolved. The walk’s anchor is the first page’s own event_high_water_mark, and changed_since_anchor is true when a later page’s event_high_water_mark is past it.

workgraph/events

Read the public event history of the namespace. Params are a WorkGraphEventFilter.
string
Defaults to the runtime’s realm; must equal the granted realm.
string
Defaults to the granted namespace; must equal it.
boolean
default:"false"
Rejected by the standard single-grant services.
integer
Return only events with seq strictly greater than this value. Use the last seq you saw, or a snapshot’s event_high_water_mark, to page forward.
integer
default:"100"
Maximum events returned; above 1,000 is INVALID_PARAMS.
The result is {"events": [...], "truncated": bool, "next_after_seq": N, "event_high_water_mark": N}, in seq order. truncated is true when matching events exist after the last one returned, and next_after_seq is then that event’s seq: pass it back as after_seq for the next page. event_high_water_mark is the ledger’s highest sequence in the namespace at this read. It counts the execution-binding events this projection omits, so it can be past the last event returned. Each event carries seq, realm_id, namespace, optional item_id, kind (created, updated, readiness_observed, claimed, released, blocked, closed, linked, evidence_added, attention_created, attention_updated), at, a kind-specific payload (an item event carries the whole item), and any typed facts committed with the mutation ({"kind": "item_ready" | "lease_expired" | "namespace_terminal", ...}). Flow execution-binding events are kept in the durable journal but omitted from this projection.

workgraph/goal/status

Read one goal: the work item plus its attention binding. Params are a GoalStatusRequest.
string
required
The WorkAttentionBindingId.
string
Defaults to the runtime’s realm; must equal the granted realm.
string
Defaults to the granted namespace; must equal it.
The result is {"item": WorkItem, "attention": WorkAttentionBinding}. An unknown binding is INVALID_PARAMS with the typed not-found message.

workgraph/attention/list

List attention bindings in the granted namespace, optionally narrowed by target or status. Params are an AttentionListRequest; an empty object lists every binding.
string
Defaults to the runtime’s realm; must equal the granted realm.
string
Defaults to the granted namespace; must equal it.
WorkAttentionTarget
{"kind": "session", "session_id": ...} or {"kind": "lowered_owner", "owner_key": {...}}.
WorkAttentionStatus
Tagged by state: {"state": "active"}, {"state": "paused", "until"?: timestamp}, {"state": "superseded"}, or {"state": "stopped"}.
The result is {"attention": [WorkAttentionBinding, ...]}. Attention reassignment and policy escalation are not RPC methods; they are authority-bearing tools injected into turns that carry an active attention projection.

Live channel methods

Live channels provide low-latency audio and text streaming plus model-gated still-image input on sessions that use a realtime-capable model. Create a session with a model like gpt-realtime-2, then call live/open to start the channel explicitly. Start rkat-rpc with --live-ws <addr> for WebSocket transport, or with the feature-gated --live-webrtc flag for WebRTC signaling. At least one live transport must be enabled for the live/* family to be advertised. See the Live Channels guide for the full flow.

Opening a live channel

Create a session on a realtime-capable model and call live/open:
live/open returns a LiveOpenResult with transport bootstrap (e.g. WebSocket URL), WireLiveChannelCapabilities, and WireLiveContinuityMode, plus advisories when the open went ahead without something. Today that is staged_prompt_refused: a run-start hook refused the session’s staged create-time prompt, so the realtime model was not given it, and it stays staged for the session’s first text turn or a later open. The advisory vocabulary may grow: an advisory a client does not know is not an error, and the SDKs keep it as the string the server sent.
string
required
Session whose canonical history seeds the live channel.
provider_managed | explicit_commit | null
default:"null"
Optional input-turning mode. Omitted preserves provider-managed behavior.
websocket | webrtc | null
default:"null"
Optional live transport. Omitted uses the server default.
usize | null
default:"null"
Optional positive serialized-character budget for the core-owned seed message window. Omitted preserves the complete canonical history. When present, core selects a recent complete-turn replay suffix. Contiguous System, SystemNotice, and injected-context messages immediately preceding a selected user turn stay with that turn; older System rows may be omitted. An existing compaction-summary head may also be retained. Any truncation returns degraded continuity. Zero is rejected.
System messages follow the same bounded replay policy as other ordered transcript data; their combined historical size need not fit the window. The complete canonical System sequence is retained separately as a refresh drift witness, not as hidden provider instructions that restore omitted rows. Canonical multimodal sidecars also remain outside the message window: image identity, tombstones, and aggregate accounting stay complete even when older replay messages are omitted.

live/webrtc/answer

For WebRTC, request "transport": "webrtc" on live/open. The returned transport bootstrap contains a single-use token and names live/webrtc/answer as the canonical signaling method. Send the browser offer SDP with that token:
Request
The result is { "answer_sdp": "v=0..." }. Tokens are channel-bound, short-lived, and single-use; replay, expiry, or a channel mismatch fails typed.

live/status

Read the current state of a live channel.

live/send_input

Send one typed input chunk. Image input is available only when LiveOpenResult.capabilities.image_in is true; an image is staged as context for the next text, audio, or explicitly committed response. Every image must carry a caller-stable, session-scoped idempotency_key. Send no input before the channel reports ready: input sent earlier is refused and is not held for later. See Wait for ready before the first input. The JSON-RPC JSONL transport accepts frames up to 64 MiB, excluding the trailing newline. Direct live WebSocket frames are a different input path: they support JSON text chunks and negotiated raw PCM audio only, with a 2 MiB aggregate/per-frame ceiling. Images always use this JSON-RPC method, even when the channel’s observation/audio transport is WebSocket or WebRTC. Server-originated JSON-RPC responses are capped at 32 MiB and queued notifications at 8 MiB. Their byte/count reservations are process-wide and remain owned through the bounded transport write; oversized collection reads must use pagination instead of relying on socket buffering.
The key must be non-empty, no more than 128 UTF-8 bytes, contain no control characters, and have no leading or trailing whitespace. Replay the same key with the same canonical MIME and bytes after a lost receipt: Meerkat does not resend it to the provider and emits the existing durable identity again. Reusing a key for different content is rejected as image_input_idempotency_conflict. If text or audio is already staged, commit it before submitting an image; otherwise the image is rejected as image_input_requires_commit. { "status": "sent" } proves only that the adapter queue accepted the command. Wire validation and queue admission can instead fail immediately with typed LiveSendInputErrorData. A check that fails after acceptance is emitted as a typed command_rejected observation. Only a user_content_committed observation carrying the same idempotency_key proves the provider-acknowledged image reached durable canonical session history. The receipt is redacted: it contains identity, ordering, media type, and the key, never image bytes. Each image is limited to 20 MiB decoded, and canonical live image history is limited to 40 MiB decoded in aggregate, counting repeated references as separate occurrences. live/send_input rejects a new image that would cross the aggregate ceiling as image_input_history_budget_exceeded before provider send or persistence. That keeps every successfully committed live image reopenable. Legacy or out-of-band history already above the ceiling, missing blobs, and content-address mismatches fail live/open rather than trimming, substituting, or changing image context. See the Live Channels guide for retry and transport details.

Live channel lifecycle methods (live/*)

Public Live WebRTC channels also send the notification live/assistant_playback_hint { channel_id, hint: "duck" | "restore" }: duck local assistant playback while assistant audio overlaps the user’s speech, restore it afterwards. It is purely additive (clients that ignore it behave as before); see Barge-in playback hint for the recommended client policy. WebSocket calls require --live-ws <addr>. WebRTC open/answer requires a build with the live-webrtc feature and startup with --live-webrtc. If both are enabled, select the transport explicitly or accept the server default.

MCP methods

mcp/add

Stage a live MCP server addition for a running session. The server is connected at the next turn boundary.
string
required
Session ID to add the server to.
object
required
Typed MCP server configuration. Include name with either stdio fields (command, optional args/env) or HTTP fields (url, optional headers/transport).
bool
default:"false"
Whether to also write the server to disk config.

mcp/remove

Stage removal of an MCP server from a running session. Active tool calls drain before the server disconnects at the next turn boundary.
string
required
Session ID to remove the server from.
string
required
Name of the MCP server to remove.
bool
default:"false"
Whether to also remove from disk config.

mcp/reload

Reload one or all MCP servers for a running session. Useful after config changes.
string
required
Session ID to reload servers for.
string | null
default:"null"
Specific server to reload. If null, reloads all servers.

Models

models/catalog

Return the curated model catalog with provider profiles, capability metadata, and parameter schemas.
No parameters are required. The catalog is resolved from built-in model metadata plus config-backed provider/server entries; invalid provider config can yield INVALID_PARAMS.
ContractVersion (object)
Structured catalog contract version with integer major, minor, and patch components. Unlike initialize, this result does not stringify it.
array
List of provider entries, each containing provider, default_model_id, and models.
object
Model profile with capability flags (supports_temperature, supports_thinking, supports_reasoning) and params_schema.

Capabilities

capabilities/get

Return capabilities registered by the running build’s linked owners, with status resolved against current config. This is not an enumeration of every capability vocabulary member: an unavailable feature can have no row at all. A registered declaration can still report {"NotCompiled":{"feature":"..."}}; missing declarations are not automatically synthesized with that status.
Possible status values:

Config methods

config/get

Read current realm config envelope.

Config write results

RPC config/set and config/patch return ConfigWriteResult: the committed ConfigEnvelope fields (config, generation, realm_id, instance_id, backend, resolved_paths) are flattened at the top level, with optional live_propagation. The report is omitted when the write does not fan out; the current fan-out trigger is a change to agent.model. When present, it contains: Inspect skipped even when clean is true: clean does not mean every session changed, nor that identity lookup succeeded for every session. It describes this report’s synchronous failure lists, not eventual provider application. Observe subsequent live-channel status and errors to determine whether an accepted refresh was applied. Propagation occurs after the config generation commits. A non-clean report is a successful config write with live-propagation failures, not a rollback of the committed generation. Reconcile the listed sessions/channels separately. This report is specific to RPC writes, not config/get or the REST/MCP config envelope.

config/set

Replace config, optionally using generation CAS. Returns the config write result.
config/set replaces the realm’s whole config document. The request is read as a typed Config, so every key it leaves out is written with its default. In a child realm each written key is the child’s own override: the realm stops inheriting those keys from its parent, and capabilities the parent disabled whose defaults are on (tools.schedule_enabled, provider web search, Gemini Google search, skills.enabled) are enabled again. Sending back the config of a config/get response does the same, because that config has every default filled in. For a partial edit, use config/patch (below).

config/patch

Merge-patch the config (RFC 7396). Returns the same config write result. This example changes only max_tokens_per_turn, leaving agent.model unchanged, so its result omits live_propagation.
config/set also accepts a direct config object as params for compatibility. In that mode, no CAS check is applied.

Refused config writes

A config write that would administer a section the host administers in the document itself is refused with -32602 (invalid params), and nothing is written. The error’s data.type names the section: A refusal for changed realm sections names the change and the realm in its message, for example removing [realm.global] would change the [governance] section a realm whose own document states no parent and no [realm.global] composes. See governance settings and OS process confinement.

Notifications

During turn execution, the server emits session/event notifications with an EventEnvelope<AgentEvent> under params.event:
Inspect params.event.payload.type and (for text deltas) params.event.payload.delta, not params.event.type. event_id, typed source, seq, and timestamp_ms belong to the envelope; optional mob_id is envelope metadata. A turn’s session/event notifications go to the connection whose request started it (turn/start, session/create, mob/turn_start, help/ask), unless that request sent "session_events": false; a turn that carries the inputs of several requests goes to each of their connections. A turn no request waits on (queued work such as session/external_event, comms, schedules, a resumed run) goes to the connection that holds the session: the one that created it (session/create, help/ask) or forked it (session/fork_at, session/fork_replace) or, once that one is gone, the next one that starts a turn on it. While the holder is gone the notifications are written nowhere; read the turn back with session/history, or watch the session with session/stream_open. No other connection receives them. On a TCP server (--tcp), a session no connection holds (one the host or a mob created, or one from before a restart, that no connection has started a turn on) has its turns written to no connection; a stdio server writes them to its one client. Event types match the AgentEvent enum in crates/meerkat-core/src/event.rs (agent_event_type assigns each variant its stable wire name) and its schema projection in artifacts/schemas/events.json. New variants must appear in both that enum and this table. The decodable vocabulary includes the explicitly marked legacy row; not every variant is emitted by current writers. Since 0.9.4 the tool_config_changed entry of WireEvent.known_payloads in that file is generated from the typed payload. The hand-written entry before it required a status field the event never carried (its status is status_info), so every real tool_config_changed event failed validation against it; the generated entry accepts the events the runtime serializes, including those stored by 0.9.3 and earlier with their persisted bit. Message-scoped events (turn_started, reasoning_delta, reasoning_complete, text_delta, text_complete, server_tool_content, assistant_image_appended, turn_completed, retrying) carry an optional assistant_message_id. It equals assistant_message_id on the committed block_assistant row returned by session/history, so clients join live rows to history by id rather than by text or position. run_completed carries the id of the message whose text result repeats. Only a history row carrying the id is the commit: turn_completed is a live signal that can precede work that still fails the run, and can be absent for a committed row. Rows the realtime transcript materializer commits carry no assistant_message_id; they carry realtime_origin.provider_item_ids, which match the provider item ids on the live transport’s realtime observations. See assistant message identity. Reconcile boundary_append_applied against boundary_appends_discarded for the same session, run, and input, and against canonical transcript history. A run terminal alone does not prove that an append was discarded. A discard does not terminalize the input or invalidate its later application in another run; canonical retained history remains authoritative. live_channel_closed tells every session observer why a live channel closed without polling live/status. reason is one of: reopen_recommended is true only for a media_fault while the session’s one reopen is still available; the reopened channel keeps its retained context. stream_truncated is subscriber-local. It reports UI-ring lag or dropped source events at an explicit session stream’s outbound queue, not an EventStore projection result. Use events/list_since or events/snapshot when that optional replay surface is healthy, and reconcile against current session state after receiving it.

session/stream_event notifications

When a session event stream is open (via session/stream_open), the server emits session/stream_event notifications. params.event is the same nested EventEnvelope<AgentEvent> as in session/event, scoped by an outer stream handle.
Outer sequence numbers the explicit stream’s deliveries and is distinct from the source envelope’s event.seq. Outer stream_id and session_id are routing fields; scoped streams can additionally carry scope_id and scope_path. None of these flattens or replaces event.payload. Temporary outbound admission or notification-channel saturation keeps the session subscription open. Before delivering its next source event, the server emits a stream_truncated marker with event.seq: 0 and reason: {"kind":"stream_lagged","dropped":N}. The count includes source events that could not be admitted; refused synthetic markers do not increase it. Admission stays nonblocking, so a slow subscriber does not reserve capacity ahead of RPC responses or callback requests. This is a loss notice, not replay. Mob streams (member-scoped and aggregate) retain their existing overflow termination behavior. Aggregate recovery requires separate attribution because a mixed-member gap cannot be attributed to one member’s event envelope.

session/stream_end notifications

Session and mob streams reserve terminal delivery capacity before opening. The process admits at most 4096 active or queued terminal obligations; an additional session/stream_open or mob/stream_open returns BUDGET_EXHAUSTED until capacity is released. Each terminal is bounded to 16 KiB, with diagnostic detail limited to 1 KiB of UTF-8 text. Data-event admission cannot consume these reservations. A slow reader retains its terminal reservation until the transport writes or discards the notification. An explicit session stream terminates with this notification:
outcome is "remote_end", "terminal_error", or "explicit_close". Calling session/stream_close normally terminates the handle with explicit_close; normal upstream exhaustion uses remote_end. If dropped events remain without a delivered gap marker, either path uses terminal_error with stream_queue_overflow and the unreported source-event count. When a terminal error is reported, the notification additionally contains error: {"code":"stream_queue_overflow","message":"..."} or error: {"code":"stream_receiver_gone","message":"..."}. stream_truncated is an event-level lag observation, not this terminal protocol. Stop consuming a terminated handle and reopen/reconcile as needed. A disconnected transport or lost notification receiver cannot be relied on to deliver its final end notification. Python and TypeScript EventSubscription iterators drain earlier queued events, then raise EventSubscriptionError when the terminal contains an error. The error retains the raw terminal, including unknown server codes, and the last delivered RPC and envelope sequence values. Error-free remote_end and explicit_close still end iteration normally. Subscription failure does not itself establish that the agent’s run failed or stopped. On a mob member stream the subscription also reports the last event’s epoch (last_event_epoch, lastEventEpoch); with its envelope sequence it is the cursor that resumes the stream (see mob/stream_event below).

mob/stream_event notifications

When a mob event stream is open (via mob/stream_open), the server emits mob/stream_event notifications. Requires the mob feature.
For mob-wide streams the event is an AttributedEvent (source member identity + profile + envelope). For per-member streams the event is the raw EventEnvelope<AgentEvent>. Runtime incarnation ids and fence tokens are bridge-internal and are not part of public stream payloads. A member stream’s events also carry epoch: the sequence space of the envelope’s event.seq. epoch and event.seq together are the event’s position in the member’s event sequence. The epoch changes whenever the member’s sequence space restarts: after a runtime restart, when the member moves to another session, or when a placed member moves to a new host binding. Mob-wide events interleave several members’ sequences and carry no epoch. A member stream opened without cursor is live: it delivers only events published after it opens. To continue a member stream after a disconnect, open it again with cursor set to the position of the last event received:
The new stream first replays the events the member still retains after that position (each member keeps its latest 1024 events and 4 MiB by default), then streams live, with nothing delivered twice or skipped between the two. If the member is live when the stream opens and its retained events no longer reach back to the position, the replay starts with a stream_truncated event (reason: {"kind":"stream_lagged","dropped":N}). A stream_truncated event does not move the position a client resumes from. A cursor of another sequence space, or one ahead of the space’s newest event, replays the current space from its earliest retained event instead; its events carry the current epoch, so the client sees the change. A member that is dormant when the stream opens (seated, but not materialized in this runtime) is not woken by it: the stream attaches when the member wakes and replays from the woken member’s first event, whatever the cursor. The events the member published after the cursor and before it went dormant are not replayed, and no stream_truncated event marks them: a client that resumes a dormant member reads them from its history (mob/member_history). A cursor without agent_identity, or one whose epoch is not a UUID, is refused with -32602 (invalid params).

mob/stream_end notifications

Requires the mob feature. The mob terminal payload omits session_id:
As with session streams, outcome is "remote_end", "terminal_error", or "explicit_close"; mob/stream_close selects explicit-close termination. Conditional error contains code ("stream_queue_overflow" or "stream_receiver_gone") and message; it is absent without an error. Stop using the terminated handle and reopen/reconcile as appropriate. A member stream reopened with the last event’s cursor continues after it (see mob/stream_event above). Transport disconnection can prevent delivery of this final notification. Neither stream-end notification is a callable RPC method.

Error codes

Standard JSON-RPC codes plus Meerkat-specific application codes. An error keeps the typed data its cause carries on every method; branch on the code and data, never on the message text.

Reasoning effort refusal data

A reasoning_effort level that the model’s route does not accept is refused with -32602 (invalid params) and this error.data:
reason is one of unsupported_level, supported_levels_unknown, supported_levels_unavailable, conflicting_provider_effort, conflicting_thinking_budget, conflicting_thinking_type, conflicting_reasoning_body and conflicting_reasoning_mode. route, supported and facts are always present, never left out: route is null when the client that serves the session reports no route, and supported and facts are null when no source states the levels the route accepts, or the source cannot be read now. A conflict also names conflicting_param, and conflicting_level when the conflicting setting is itself a level. retryable is true only for supported_levels_unavailable (the account’s model list is not loaded): the same request can succeed later with no change. Meerkat does not retry a refused level for the caller. The answer is the same wherever the level is refused, with two exceptions: a schedule’s create spec and its prompt action refuse the key itself, with the schedule’s invalid-params answer and no typed refusal data (see Scheduling). Second, through the MCP server a meerkat_resume of, or a meerkat_comms_send to, the session of a mob member that is not live, when that member’s own build is refused for the level in its profile, answers the generic agent error (-32013) with a message that contains the refusal’s sentence and no reasoning_effort_refused data; a level the resume itself carries is judged after the wake and is answered by the typed refusal as everywhere else. A session’s level is checked when its agent is built: session/create answers the refusal (a deferred create reports it at its first turn/start), and so does the build of a resumed or recovered session, whose stored identity stays as it was. A turn/start whose overrides move a session to a model or level its route does not accept is refused the same way, before its input is stored: the session keeps its model, its level, its stored params and its live registration, and nothing is queued for the turn. That holds on a live session, also while another turn of it runs (that turn and the requests behind it go on as they were), and on a stored session that is not live (after a restart); there a turn that names no level is judged too, for the level the session holds, and a turn that clears the level or names one the route accepts is the way out. A request the route does accept can still be answered -32002 (SESSION_BUSY) with the data {"kind": "reasoning_effort_change_needs_idle_session"} when the session has unfinished work (the cases are in the table under Model settings on a busy session): that answer is not a level refusal, it carries no reasoning_effort_refusal, and the same request is taken once the session has no unfinished work. The other surfaces answer the same request in their own way: REST answers a level on a message for a session it holds live with HTTP 500 session is busy. The MCP server’s meerkat_resume that names the level while a turn of the session runs is answered the same busy kind at once, by the MCP server’s own rule: every resume that names the level then, whatever the session holds (a repeat, and a clear on a session that holds no level, are busy there, where the table below queues them); with no turn running it rebuilds the session (see REST and MCP). A level is judged again when its turn starts. From 0.9.16 a turn/start refused there, after its input was stored, ends alone while the session is live: it is answered the typed refusal, its stored input ends as abandoned with the reason never_executed, the session’s live runtime stays, and the other requests queued on that session run. In 0.9.15 such a refused turn was a failed start: its stored input ended as abandoned with the reason stopped, the session’s live runtime was retired, and the other requests queued on that session ended without a run. When the session is not live at the refusal (the level is refused by the session’s build), the session’s runtime registration is retired as after a failed start and the other requests queued on that session end without a run (see Known limitations in the changelog); so it is for a refused turn whose answer is resolved after a restart, or while another run’s result is the one the session’s runtime holds open. What can still be refused at its start: a deferred create’s first turn; a turn on a stored session that is not live whose level cannot be judged yet (supported_levels_unavailable); a request sent without waiting for another one, when it reaches admission in the time between that other turn’s admission on a session that has no turn running and its start (on a stored session that is not live: until that turn’s rebuild ends); a model-identity change carried by an input that enters through the runtime without a turn request (a mob’s own send, or a member turn an in-process Rust host starts with such an option); and a turn admitted while no turn was running, on a session whose model, level or route is changed by something else (a host’s reconfiguration of a mob member, a config reload, an account’s model list) between its admission and its start. A run that fails for the refusal reports it in run_failed as the error_report reason {"reason_type": "reasoning_effort_refused", "refusal": {...}} with class config. No provider request is made for a refused level. The MCP server answers a refused level on meerkat_run and meerkat_resume as a tool error with the same code and data, except when the session is that of a mob member that is not live and that member’s own build is refused for the level in its profile: that case is answered the generic agent error (-32013) with no typed data (the second exception above).

Model settings on a busy session

On a session that holds a provider-neutral reasoning effort level, anything that changes the model identity needs a session with no unfinished work; plain turns and true repeats of the level queue. On a session that holds none, only setting a level needs a session with no unfinished work; everything else queues as on 0.9.14. “Busy” in the table is -32002 (SESSION_BUSY) with error.data {"kind": "reasoning_effort_change_needs_idle_session"}, answered at once, with nothing stored. It applies to turn/start and mob/turn_start while the session has an unfinished turn or queued input, and on a deferred session while its first turn is still building it. On an autonomous mob member (runtime_mode autonomous_host, the default) the unfinished work can be the member’s own: a turn it started for its kickoff or on what its peers sent it, or a peer input queued on it. The caller cannot know when such a member is idle, and a plain turn first does not help against the member’s own turns. Two ways on: send the request again (in two runs it was taken after 5 s and after 21 s; a member whose peers keep sending may stay busy for longer), or set the level in the member’s profile or at its spawn, which does not depend on the member’s traffic. is_active: false from session/read does not promise the change is taken (seen in a run). An autonomous member is addressed by turn/start with the member’s session id: mob/turn_start is only valid for turn_driven members and is refused for an autonomous one with -32602 before this rule is reached (seen in a run).
  • The model identity is the model, the provider, the self-hosted server, the provider params, the auth binding, and the level itself (set, change, clear).
  • Naming a field counts as changing it: on a busy session that holds a level, a turn that names model, provider, self_hosted_server_id, provider_params or auth_binding is answered busy even when the value equals the session’s. Only the level repeated with reasoning_effort is a repeat.
  • A level named inside provider_params replaces the provider params and is never a repeat: on a busy session that holds a level it is answered busy even when it equals the held level. A client repeats its level with the field reasoning_effort.
  • A session holds a level when a request set one (on create or on a turn), when it was forked from or resumed as a session that holds one, and when it is a mob member built from a profile whose provider_params carry reasoning_effort. No host or realm configuration gives sessions a level.
  • The price of holding a level: a client that sets a level once and then varies provider_params per turn (a temperature, say) is answered busy whenever another turn of the session runs or is queued, and so is a mob/turn_start with a model override on a busy turn_driven member built from a profile with a level. Wait for the running turn’s answer, then send the request again; do not poll (an autonomous mob member is the exception: see the paragraph under the table). A session with standing work may never be idle for such a request: stop sending, let its queue drain, then make the change. On an autonomous mob member the standing work is not the caller’s to stop: send the request again, or set the level in the member’s profile or at its spawn.
  • The one kind names the level in every busy cell, also when the request only changed the model.
  • No flow step, kickoff, peer message, member send, scheduled delivery or wake is answered busy; the rule is on turn/start and mob/turn_start. A model-identity change carried by such an input, or by a member turn an in-process Rust host starts with a model, provider, params or binding option, is queued and judged only when its turn starts.
  • Unfinished work is not only a running turn: an event queued on a session that has no turn running counts. A session that received a session/external_event while no turn was running (confirmed by a test), or one configured with silent comms intents that holds an unread silent request (by reading the code, not run), counts that input as unfinished work until its next turn, and a turn from a busy cell is answered busy there. Nothing is running to wait for. Three ways on: send a plain turn first, then the change (confirmed by a test); or recall the event’s input with session/recall_input (its input_id is in the answer to session/external_event), which answers abandoned and withdraws the event: the session never receives it; then send the change (seen in a run); or set the level when the session is created. The busy answer’s text names the first and the third. On an autonomous mob member the unfinished work can be the member’s own: see the paragraph under the table.
  • A later release is planned to queue these turns.

comms/send error data

A failed comms/send returns -32603 (-32602 for invalid_command) with a typed CommsSendErrorData object in error.data, tagged on code. Every variant also carries a message. peer_wake_refused names why in refusal.kind, a closed vocabulary. retryable is true when a later send can succeed without an operator action.

Architecture

The RPC server is stateful: agents stay alive between turns through the shared runtime-backed service also used by REST and MCP. RPC’s distinguishing surface is its broad JSON-RPC method catalog, scoped subscriptions, and server notifications.
Each session gets a dedicated tokio task that exclusively owns the Agent. This solves the cancel(&mut self) requirement without mutex. Commands (StartTurn, Interrupt, Shutdown) are sent via channels.
The JSONL writer and notification queues are bounded, and ordinary session subscriptions are best-effort. A slow client can therefore receive a typed stream_truncated marker instead of every live event. Persistent event audit projection can use a separate unbounded internal queue, so UI lag does not drop projector input. The EventStore remains asynchronous derived state rather than session completeness authority.

Comparison with other surfaces

See also