keep_aliveis runtime/session behaviorsession/external_eventqueues runtime-backed external work- committed success is not rewritten to cancellation
Getting started
1
Start the server
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
[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 inartifacts/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.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 sendstool/executerequests to clients for registered callback tools. - Response (back to the requester): echoes
idwithresultorerror. - Notification (either direction): has
method,params, noid, and receives no response.
Full lifecycle diagram
Full lifecycle diagram
Request cancellation
Cancel an in-flight request by its exact JSON-RPC request ID, preserving its number/string type. For example, whilesession/create request 2 is still
in flight, send this notification:
Client -> server notification
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
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 withtools/register:
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-rpcover 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.
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:
-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.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.
session/create
Create a new session and run the first turn. Setinitial_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.
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
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.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.
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.Provider name:
"anthropic", "openai", "gemini", or "self_hosted".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.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.Max retries for structured output validation. Omission/
null inherits
configuration (stock default 2); explicit 0 is preserved.Run-scoped hook overrides (entries to add, hook IDs to disable).
Override built-in tools (task management, etc.). Omission/
null inherits
host/factory configuration; explicit false disables them.Override the shell tool (requires built-ins). Omission/
null inherits
host/factory configuration; explicit false disables it.Override semantic memory (
memory_search tool + compaction indexing).
Omission/null inherits host/factory configuration; explicit false
disables it.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.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.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
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.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.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_REQUESTandevent 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_stepsof0. 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_PARAMSnaming the bound; page the log withevents/list_since, or export it to a file withrkat session export-atif, which has no such bound. - A session whose trajectory outgrows the outbound message limit (32 MiB) fails
with
BUDGET_EXHAUSTEDnaming 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.
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.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."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.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 beforemessage_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 throughmessage_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.
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 ofsession/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_policyreplaces 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 shell environment (
shell_env) given tosession/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.
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 ofsession/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.
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.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.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.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 ordinarycompaction_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.
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.codeisSESSION_BUSY); - a session runtime that needs a durability reload:
-32603.
-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.
Operator instructions
Operator instructions are standing System-plane instructions a host gives a session, or the members of a mob, by slot (anamespace 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:
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.
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.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:
-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.
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.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.
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.
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.
Provider override (e.g.
"anthropic", "openai", "gemini"). Typically inferred from model.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.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.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.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.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. Unliketurn/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).
outcome is one of:
stopped: the run was current.contributorslists every input bound to it, with the deliveredcompletionclass and the committedterminalclass. A cancelled joined steer reportscompletion: "runtime_terminated"withterminal: "cancelled"; readterminalfor 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:contributorsis empty, the run never resumes, and its inputs endcancelledwhen 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.
run_id is an invalid-params error.
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.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, useturn/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 iscancelled(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 (aturn/startrequest that waits on it is answered-32603withruntime terminated: input recalled before it started).attempt_countis 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);0means 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.phaseis the input’s lifecycle state (staged,appliedorapplied_pending_consumption) andrun_id, when the runtime has one, the run that holds it.already_terminal: the input already ended. Nothing was touched.terminalis its terminal class (completed,cancelled,abandoned,supersededorcoalesced). A second recall of a recalled input answerscancelledhere, also after a restart.
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.
{"by": "input_id", "value": "<input id>"} or
{"by": "idempotency_key", "value": "<key>"}.mob/member_send admission
An unkeyedmob/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:
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_idandcommitted_at_ms;statusmay 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,
strandedwhen 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, orsession/input_statusin the status’s session by itsdelivery_idas the idempotency key, or by itsinput_id), not by its caller key: the key belongs to the member identity, not to a session’s inputs. pending: committed, not admitted yet. Apendingthat survives a server restart is not proof of loss; do not resend it under a new key.admitted: queued insession_idasinput_id, not proof that a turn ran. Follow it withsession/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 settlesstranded.refused: settled as refused, never admitted;reasonnames why. A keyed send whose member became an identity entry, or whose name became reserved unreadable, after its commit settlesrefusedwithreasonauthority_deniedat delivery.
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.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 configuredTrustedPeers and active in-process registrations. Requires the comms feature.
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.List of
SkillEntry objects with key, name, description, scope, canonical source provenance, is_active, and optional canonical shadowed_by provenance.-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
Theevents/* family is the complete cursor-based replay surface for hosts that
report runtime/capabilities.features.event_replay = true:
events/latest_cursorreturns the latest cursor for a typed scopeevents/list_sincepages envelopes after an optional cursor and reportslatest_cursorplushas_moreevents/snapshotreturns a point-in-time session snapshot paired with its cursor
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-facingjobs/* 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 factdegraded: the census observed a stale lease, attention state, or backlogunreadable: 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 ofapproval/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
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.
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).
R3 human consent on a stock governed pipe
Whenrkat-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
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 withgrant_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/grantopens atargetfor thesubject: 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 innameswith 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, withtools(a non-empty list), only those of its tools named there. A server is gated when the gate names it, or when the gate’sunconfigured_mcp_serversis 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 notooltarget (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 refusedsubject_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 refusedsubject_unknowntoo, since the identity is out of the roster then: retry it once the respawn answers. Exactly one ofduration_msandexpires_at_ms(UNIX ms) bounds the grant, at most the host’s maximum lifetime (24 hours by default).scopeis{"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’sscopeis{"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 acurrent_rungrant with the request refusalrun_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’sissuerrecords it, as attribution only. An identity grant answersapplies, 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) orat_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 firstturn/start.tool_grants/revokeends a grant before its deadline. It is idempotent: revoking a grant that already ended answers it as it stands, andchangedsays whether this revoke ended it. A revoke at or after the deadline records the expiry instead.tool_grants/listanswers the subject’s grants, each due one settled asexpiredfirst. Ended grants (expired,revoked,run_ended) are listed only withinclude_ended;unreadablenames 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’sgate:running, what its live build gates (its gated names undertools, with its gated servers andunconfigured_mcp_servers) and the names it ignored as not mounted, ornullwhen no build of the member is live here; andnext_build, the gate its next build resolves, split the same way. Advisory, likeapplies. On a server that keeps durable decisions the subject’s grant requests follow its grants: each open or approved one asrequested, and withinclude_endedeach rejected, expired, withdrawn or refused one whose deadline is within the grant policy’s maximum lifetime of now asdeclined(itsended_at_mswhen it ended; an older one stays readable throughdecision/list). A request whose grant was issued is listed as that grant only.tool_grants/auditanswers a page of the subject’s audit log,granted(with the grant’sscope),expired(with thedriverthat observed it:timer,boundary,dispatch,read,revoke,build(a build reading which gated servers a grant covers), orrunandrecoveryfor a run that ended at or after the deadline),revoked,run_ended(with therun_idand thedriverthat ended it:runat the run’s end,recoverywhen durable-tail recovery closed a run a stopped process left open, or theboundaryordispatchof a later run) andrefusedrows, insequenceorder afterafter_sequence.limitdefaults to 100 rows and caps at 1000; a full page carriesnext_sequence, the next page’safter_sequence. A row this server cannot read is named inunreadablewith itssequence, and the rest of the page is served.tool_grants/requestasks for a grant a person approves. It names asubject(a session or a mob member identity), and thetargetandscopeas a grant does,duration_ms(the grant’s window from its issuance, at most the host’s maximum lifetime) and an optionalreason, and holds a durable decision of kindtool_grant.issuefor the approver idoperator, which expires after an hour undecided. This server is its requester (the runtime hostrkat-rpcof 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 (statusrequested, thegrant_idits grant gets, itsissuer{"kind": "approval", "approval_id": ...}naming the decision) and thedecision. 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 reasonsubject_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 refusedsubject_endedtoo, 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. Acurrent_runrequest 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 atool_grant_requestexternal event, like any input: thedecision_id, theoutcome(grantedwith thegrant_id,rejected,expired,withdrawn, orrefusedwith areason) and thetarget. An identity’s notice goes through the mob’s member input instead: a keyed member send under the decision’s key, whose text istool_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 itsrequest_tool_granttool (see scoped tool grants); while the server runs the executor of the kind, its agents’ requests name the realm’s agentrkat-agentas 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’sduration_ms.
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:
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.
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). Thedecision/* 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/listreads one page, in decision id order, of the decisions every set filter matches:kind,phase,approver_idandrequester(a principal key).limitis 100 when absent; a larger limit reads as 500, and a limit of 0 is invalid params.next_afternames the decision id to read the next pageafter. A decision past its deadline reads as expired. A row this server cannot read is listed underunreadableand nothing executes it. A phase this version does not know is refused, never read as no filter.decision/getreads one decision, and records its expiry when its deadline passed.include_request: trueadds the held request. A row this server cannot read answersdecision_unreadable. An executedgrant.childdecision carrieseffect, 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 noeffect. Every answer that carries a decision carries it alike:decision/list,decision/present,decision/withdrawand the host adapter’sdecision/decide. A later version may add fields toeffect: read it tolerantly.decision/renderingreturns the one canonical rendering of the held request, its renderer and subject digest, and its canonical parts formax_part_bytes(one part when absent): consecutive byte ranges on character boundaries, each with its own digest. Likedecision/get, it records the decision’s expiry when its deadline passed, and a row this server cannot read answersdecision_unreadable.decision/presentrecords what a host presenter showed: theaudience({"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 readingat_ms. A surface with a size limit that showed a summary saying it is shortened records it with thelinkthe 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’spresentationscarry each recorded link.decision/withdrawwithdraws an open decision as the host.
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, anrkat-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 theworkgraph_* 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.
workgraph/get
Read one WorkGraph item by id. Requires theworkgraph feature and a
realm-scoped runtime; a runtime without a realm identity returns a typed fault
instead of inventing a default scope.
WorkItem shape is in the
WorkGraph reference.
Defaults to the runtime’s realm. Any other value is rejected: the service holds exactly one
WorkGraphNamespaceGrant.Defaults to the granted namespace (
default on standard surfaces). Any other value is rejected.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.
Present in the wire shape, rejected by the standard single-grant services. A namespace grant never implies a multi-namespace capability.
Keep only items whose status is listed:
open, in_progress, blocked, completed, cancelled, failed. Checked before the terminality rule below.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.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.Maximum items returned. Omitted means 100; values above 1,000 fail with
INVALID_PARAMS before the store is queried.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.{"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_atolder than the one it had (the store clock moved back), so a reader that dedupes byidand keeps the higherrevisionis safe. - An item changed or created after the anchor can be missing from later
pages. Those pages say
changed_since_anchor: true, andworkgraph/eventswithafter_seqset toanchor_event_seqnames 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.
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 unresolvedblocks edge, parent join satisfied, and time gates passed. Params
are a ReadyWorkFilter.
Maximum items returned after sorting by priority (high first), then creation time, then id. Omitted means 100; above 1,000 is
INVALID_PARAMS.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.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 aWorkGraphSnapshotFilter 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 aWorkGraphEventFilter.
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.{"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 aGoalStatusRequest.
{"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 anAttentionListRequest; an empty object lists
every binding.
{"kind": "session", "session_id": ...} or {"kind": "lowered_owner", "owner_key": {...}}.Tagged by
state: {"state": "active"}, {"state": "paused", "until"?: timestamp}, {"state": "superseded"}, or {"state": "stopped"}.{"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 likegpt-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 calllive/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.
Optional input-turning mode. Omitted preserves provider-managed behavior.
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.
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
{ "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 whenLiveOpenResult.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.
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.Typed MCP server configuration. Include
name with either stdio fields (command, optional args/env) or HTTP fields (url, optional headers/transport).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.mcp/reload
Reload one or all MCP servers for a running session. Useful after config changes.Models
models/catalog
Return the curated model catalog with provider profiles, capability metadata, and parameter schemas.INVALID_PARAMS.
Structured catalog contract version with integer
major, minor, and
patch components. Unlike initialize, this result does not stringify it.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.
status values:
Config methods
config/get
Read current realm config envelope.Config write results
RPCconfig/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/patch
Merge-patch the config (RFC 7396). Returns the same config write result. This example changes onlymax_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 emitssession/event notifications with an
EventEnvelope<AgentEvent> under params.event:
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 (viasession/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.
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 additionalsession/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 (viamob/stream_open), the server emits mob/stream_event notifications. Requires the mob feature.
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:
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 themob feature. The mob terminal payload omits session_id:
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 typeddata its cause carries on every method; branch on the code
and data, never on the message text.
Reasoning effort refusal data
Areasoning_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_paramsorauth_bindingis answered busy even when the value equals the session’s. Only the level repeated withreasoning_effortis a repeat. - A level named inside
provider_paramsreplaces 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 fieldreasoning_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_paramscarryreasoning_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_paramsper turn (a temperature, say) is answered busy whenever another turn of the session runs or is queued, and so is amob/turn_startwith a model override on a busyturn_drivenmember 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
kindnames 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/startandmob/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_eventwhile 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 withsession/recall_input(itsinput_idis in the answer tosession/external_event), which answersabandonedand 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 failedcomms/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.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.