Generated wire catalogs
The public protocol catalogs are generated frommeerkat-contracts and
committed with the repository:
These files are generated outputs. Change the owning Rust catalogs and run
make regen-schemas; do not hand-edit committed schema JSON. Use
make verify-schema-freshness, make verify-rpc-surface-alignment, and
make verify-rest-surface-alignment to check source/catalog/router parity.
For complete error projections, use ErrorCode::jsonrpc_code(),
ErrorCode::http_status(), and ErrorCode::cli_exit_code() in
crates/meerkat-contracts/src/error/mod.rs, or the error-code table
below. errors.json does not contain full HTTP or CLI projection tables.
The JSON-RPC initialize method on rkat-rpc returns the subset enabled by
both the compiled build and runtime composition: skills require a skill
runtime, and live methods require configured live transport support.
capabilities/get similarly reports linked owners’ registered capabilities
with config-resolved statuses, not every vocabulary member; an unavailable
feature may have no row. The catalog above is the full documented surface,
including sessions, events,
streams, blobs, artifacts, approvals, durable jobs and monitors, schedules,
WorkGraph, runtime health, live channels, mobs, MCP, comms, models,
capabilities, config, auth, realms, and usage.
Surface entry points
Core types
Traits
Runtime-backed build seam
For runtime-backed Rust surfaces, the canonical path is:MeerkatMachine::prepare_bindings(session_id)SessionBuildOptions.runtime_build_mode = RuntimeBuildMode::SessionOwned(bindings)SessionService::create_session(...)
RuntimeBuildMode::StandaloneEphemeral explicitly.
Mobs (Rust SDK)
Mob runtime APIs live primarily in:meerkat_mob(core runtime)meerkat_mob_mcp(tool-dispatch helpers)
Core Rust types
MobBuilder methods
MobHandle methods
Durable member role migration
MemberLaunchMode::Resume carries bridge_session_id and optional
resume_from_role. Use
SpawnMemberSpec::with_resume_bridge_session_id_from_role(...) for an explicit
trusted resume, or declare_resume_from_role(...) from a
SpawnMemberCustomizer handling SpawnSource::Resume.
The declaration authorizes one exact (mob, identity, stored role) to
requested-role transition for one cold resume. Mob ID, AgentIdentity, session
ID, and transcript do not migrate. Omission when the durable role differs
returns MemberRoleMigrationRequired; a wrong predecessor, inapplicable
declaration, or exact session that is still live returns
MemberRoleMigrationRejected. Success restamps current comms identity, typed
member binding, role/profile labels, callback context, and explicitly
configured tooling. Migration is forward-only; rollback is another declared
forward migration or restoration of separately versioned durable state.
The private remote-host equivalent is
MaterializeLaunchMode::Resume { session_id, resume_from_role }. Public
JSON-RPC/SDK spawn params, REST, MCP, CLI helpers, standing profiles, and the Web
SDK deliberately do not expose this authority.
Rust example
Agent-Side Mob Integration (meerkat-mob-mcp)
Agent-side mob capability is exposed by composing:
meerkat_mob_mcp::MobMcpStatemeerkat_mob_mcp::AgentMobToolSurfaceFactory
SessionBuildOptions.mob_tools(meerkat_core::service).
mob_* tools to the agent.
external_tools remains the surface for custom callback tools and MCP-backed
dispatchers. Mob orchestration has its own late-bound mob_tools factory slot,
which receives session-scoped runtime authority before producing the dispatcher.
Public host surfaces use typed control planes instead:
- JSON-RPC / SDKs: typed
mob/*methods - Public MCP hosts: typed
meerkat_mob_*tools
meerkat-mob-mcp also exposes:
meerkat_mob_mcp::public_tools_listmeerkat_mob_mcp::handle_public_tools_call
AgentMobToolSurface
remains the agent-side mob_* tool surface, late-bound through
SessionBuildOptions.mob_tools.
Public mob host methods
Public application hosts should use the typed control planes rather than the agent-internalmob_* tool dispatcher:
The WorkGraph-to-Flow composition is currently a deliberate MCP host contract:
meerkat_workgraph_flow_launch, meerkat_workgraph_flow_reconcile, and
meerkat_workgraph_flow_abandon_uncertain, with redacted linkage reads through
meerkat_workgraph_flow_binding_get and
meerkat_workgraph_flow_binding_list. Its semantic owner is the shared
meerkat-mob::WorkGraphFlowBridge; MCP only adapts that owner to a public
surface. Hosts start an autonomous reconciler at bootstrap, so durable bindings
recover without another caller request. REST and generated JSON-RPC clients do
not yet claim this composition contract; their ordinary Mob and WorkGraph
surfaces remain independent.
Shared generated schemas include supervisor-bridge component types. Public
comms/send and MCP comms requests can carry a BridgeCommand, but acceptance
remains receiver-machine-authorized; callers do not gain supervisor authority
by constructing the payload. Exposure is established by route and method
signatures, not by a type merely appearing in wire-types.json, params.json,
or OpenAPI components.
For cross-surface behavior and examples (CLI/RPC/REST/MCP/Python/TypeScript), see Mobs.
SDK entry points
Structured output types
See the structured output guide for usage details.
Hook types
See the hooks guide for usage details.
Skill types
See the skills guide for usage details.
Wire types (meerkat-contracts)
Error code reference
This table describes the higher-level canonicalErrorCode/wire envelope view.
It is not identical to the lower-level SessionError transport mapping used by
the session service adapters.
Every ErrorCode maps to a stable string, JSON-RPC code, HTTP status, and CLI exit code:
INPUT_REFUSED and INPUT_NOT_READY carry the native owner’s typed detail
(WireInputAdmissionErrorDetail): {"type": "refused", "kind": "denied" | "malformed_facts"}
or {"type": "not_ready", "reason": {"kind": ...}}, where reason is a
WireControllerReadinessFailure. Since 0.9.4 its kinds include
original_admission_pending: an original the input or operation relies on is
still its source owner’s submission candidate, whose admission the owner has
not settled yet. Treat it as unavailable and retry later. A Rust decoder of
WireControllerReadinessFailure built before 0.9.4 rejects the new kind; the
Python, TypeScript and Web SDKs keep error details as untyped data.
Since 0.9.15 SESSION_BUSY (-32002) with the data
{"kind": "reasoning_effort_change_needs_idle_session"} answers a JSON-RPC
turn request (turn/start, mob/turn_start) that would change the model
identity of a session while the session has unfinished work (a running turn,
or anything queued). The turn is not queued and nothing is stored for it. The
one kind covers every cause. On a session that holds a provider-neutral
reasoning effort level: a turn that sets, changes or clears the level, or
that changes the model, the provider, the self-hosted server, the provider
parameters or the auth binding (a level named inside provider_params
replaces those parameters, so it is one of these even when the level is the
same; repeat a level with the direct field reasoning_effort). On a session
that holds no level: a turn that sets one. Plain turns, turns that repeat the
session’s level, and on a session without a level every other change queue
as before; the table is in
Model settings on a busy session.
A client may send the same turn again: wait for the running turn’s answer
first, and do not poll. A later release is planned to queue such a turn. A
level the model or its route does not accept is answered with its typed
refusal (INVALID_PARAMS and the reasoning_effort_refused data) before
this answer, and that refusal is not retried unchanged.
That rule lives in the JSON-RPC turn requests only. The MCP server’s
meerkat_resume uses the same kind, in its tool error’s data, for a case
of its own: a resume that names the level (set or clear, as the member or
inside provider_params) while a turn is running on the session, whatever
the session holds; there the level is judged only after the busy answer, when
the resume is sent again (see MCP). REST does not use the kind:
see POST /sessions/{id}/messages in REST.
For session-service transport behavior specifically, see the Capability matrix.
Provider clients
All implement
AgentLlmClient and normalize streaming responses to LlmEvent (text deltas, tool call deltas, usage updates, done).
Each client maps its provider’s stop reason to a typed StopReason. A reason the client does not know fails the response with the retryable IncompleteResponse instead of ending the turn, and a model fallback policy with the empty_output trigger may switch models on that failure before the run fails. An Anthropic stream that carries no stop reason at all, and a Chat Completions stream without a finish_reason, still end as EndTurn. The agent loop commits nothing of a turn that stops with Refusal, ContentFilter or ContextWindowExceeded, runs none of its tool calls and does not run PostLlmResponse hooks for it: the first two fail the run with AgentError::ContentFiltered, the last as context exceeded (LlmFailureReason::ContextExceeded; its requested is the call’s reported tokens and can be at or below max, so do not compute an overflow from it). Since 0.9.4 AgentError::ContentFiltered carries the refusing stop (stop: refusal or content_filter) and, when the provider sent one, its own account of it (detail, a ProviderStopDetail tagged by provider), and the run_failed event carries both as error_report.reason. A Gemini prompt blocked before any candidate (promptFeedback.blockReason, no finishReason) now ends as ContentFilter whatever the block reason, OTHER and an unknown one included, instead of the retryable IncompleteResponse, so the run fails after one provider call. An OpenAI Responses refusal output part or a Chat Completions delta.refusal ends the response as Refusal, even beside text or tool calls; the refusal text travels as the provider detail, never as answer text. A PauseTurn turn (a provider server-tool loop reached its iteration limit) commits like an end of turn, and its server-tool blocks go back to the provider as history with the next request.
LlmError variants: RateLimited, ServerOverloaded, NetworkTimeout, ConnectionReset, ServerError, InvalidRequest, RequestTooLarge, InvalidInputShape, InvalidConfig, AuthenticationFailed, AuthorizationRouteChanged, ContentFiltered, PolicyStop, ContextLengthExceeded, ModelNotFound, InvalidApiKey, QuotaExhausted, Unknown, StreamParseError, IncompleteResponse. Use error.is_retryable() to check whether the error is retryable, respecting its recovery boundary:
RequestTooLargerequires request-size remediation, not an unchanged automatic retry; optionalencoded_bytesandmax_bytesdescribe the cap.AuthorizationRouteChangedis retryable, but retry must happen above request projection so provider-specific lowering is rebuilt for the new authorization route.PolicyStoprequires operator review. Do not automatically retry it, switch providers, or reset the conversation to bypass the stop.
Storage implementations
See also
- Rust SDK reference - full API with examples
- Architecture - crate structure and agent loop
- Capability matrix - build profiles and feature behavior
- Session contracts - lifecycle operational contracts
