Skip to main content

Version

Primary handles

  • MeerkatClient owns the runtime process and transport.
  • Session is a live multi-turn handle.
  • DeferredSession is a created session that has not run its first turn yet.
  • LiveChannel is the session-bound wrapper for the live/* RPC surface.
  • Mob is a first-class mob control handle.

Session result and metadata types

RunResult

Returned by session.turn(), deferred.start_turn(), and available as events.result after streaming. Fields:
  • session_id: str
  • text: str
  • turns: int
  • tool_calls: int
  • usage: Usage
  • terminal_cause_kind: str | None
  • session_ref: str | None
  • structured_output: Any | None
  • extraction_error: ExtractionError | None
  • schema_warnings: list[SchemaWarning] | None
  • skill_diagnostics: SkillRuntimeDiagnostics | None

SessionSummary

Returned by client.list_sessions(...).
  • session_id: str
  • session_ref: str | None
  • created_at: int
  • updated_at: int
  • message_count: int
  • total_tokens: int
  • labels: dict[str, str]
  • is_active: bool

SessionDetails

Returned by client.read_session(session_id).
  • session_id: str
  • session_ref: str | None
  • created_at: int
  • updated_at: int
  • message_count: int
  • labels: dict[str, str]
  • is_active: bool
  • model: str
  • provider: str
  • last_assistant_text: str | None
  • resolved_capabilities: ResolvedModelCapabilities | None

SessionInfo

Base shared metadata type for session identity/timestamps/state.

Usage

  • input_tokens: int
  • output_tokens: int
  • cache_creation_tokens: int | None
  • cache_read_tokens: int | None
  • accounting: ProviderTokenAccounting | None

ProviderTokenAccounting

  • provider: str
  • model: str
  • presented_tokens: int
  • convention: str
  • aggregation: str
One Usage type serves two different accounts. When present on the TurnCompleted event it is per-call usage: input_tokens is the raw provider counter (for Anthropic, uncached input only) and accounting names the resolved provider/model plus the normalized presented_tokens for that call. On RunResult.usage and the RunCompleted event it is the session-cumulative total: input_tokens is already the sum of every recorded call’s presented_tokens, it is persisted with the session so it keeps growing across turns, and accounting is None because a session may span models. Do not sum the cumulative value with anything - take the latest one - and sum accounting.presented_tokens rather than per-call input_tokens. An agent-loop call publishes a turn_completed row when its turn completes; extraction requests publish theirs on the extraction outcome event, and compaction summaries and turns that fail after the provider answered publish none, even when the failed turn’s assistant row was already committed (a committed row does not imply a turn_completed). So the turn_completed rows need not reconcile with the cumulative total. See Usage accounting for the worked example. TurnCompleted.usage is Usage | None. None is honest unmeasured accounting, not a zero-token call. Skip the row; the paired turn_usage_accounting_unmeasured wire event carries the reason.

Config API contract

get_config returns ConfigEnvelope; set_config and patch_config return ConfigWriteResult:
ConfigEnvelope fields:
  • config: dict[str, Any]
  • generation: int
  • realm_id: str | None
  • instance_id: str | None
  • backend: str | None
  • resolved_paths: dict[str, str] | None
ConfigWriteResult carries the same fields plus live_propagation: WireLiveConfigPropagationReport | None, the typed per-channel hot-swap / refresh / close outcome (swapped, skipped, swap_failed, refreshed, closed, refresh_failed, close_failed).

Models and schedules

Models catalog

  • contract_version: {"major": int, "minor": int, "patch": int}
  • providers: list[ProviderCatalog]

Schedule wrappers

Public methods:
  • create_schedule(request)
  • get_schedule(schedule_id)
  • list_schedules(labels=None, limit=None, offset=None)
  • update_schedule(request)
  • pause_schedule(schedule_id)
  • resume_schedule(schedule_id)
  • delete_schedule(schedule_id)
  • list_schedule_occurrences(schedule_id, include_terminal=None)
  • list_schedule_tools()
  • call_schedule_tool({"name": "...", "arguments": ...})
Return payloads are JSON-shaped schedule contracts with typed top-level wrappers:
  • ScheduleListResult
  • ScheduleOccurrencesResult
  • ScheduleToolsResult
ScheduleRecord is the canonical flattened RPC object: configuration fields such as planning_horizon_days, created_at_utc, and labels are top-level; there is no nested config or public machine_state. The wrappers reject a missing/malformed schedules, occurrences, or tools array and reject schedule entries missing required identity, policy, planning, or timestamp facts.

WorkGraph wrappers

WorkGraph is a host-observation surface in the SDK. Use get_workgraph_item, list_workgraph_items, list_ready_workgraph_items, get_workgraph_snapshot, list_workgraph_events, get_workgraph_goal_status, and list_workgraph_attention. Agents own graph mutation through their WorkGraph tools.

Session runtime input helpers

Immediate creation and turn methods accept host-owned context separately from the user prompt:
  • injected_context: list[ContentInput] | None is ordered durable user-channel context immediately before the prompt
  • transient_turn_context: str | None is request-only host context
  • turn methods also accept self_hosted_server_id for an exact configured local model route
Deferred creation can store injected_context for its eventual first turn but does not accept transient_turn_context; pass transient facts to DeferredSession.start_turn(...).

inject_context

stop_run

Stops exactly run_id (read it from the run_started event’s identity.run_id) and terminalizes every input already bound to that run, including durable steers that joined it. Returns StopRunResult / MobStopMemberRunResult whose receipt["outcome"] is stopped (with contributors), not_current (the run is no longer current; nothing was touched), or not_stoppable. 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: stopped with no contributors, and its inputs end cancelled when the runtime settles it (once the store takes writes again, after a gap).

recall_input

From 0.9.15.
Withdraws one input of the session, only while it is still queued (session/recall_input). Name it by the input_id its submit answered or by the idempotency_key it was submitted under (exactly one). Returns RecallInputResult whose recall["outcome"] is abandoned (the input was queued and is now withdrawn: its terminal is cancelled and no run will take it; attempt_count is 0 when no run attempt was counted for it), not_queued (a run holds it: nothing was touched and the run is not interrupted; phase says where it is and run_id, when the runtime has one, names the run that holds it) or already_terminal (it already ended; terminal is its terminal class, cancelled for a second recall). The list of outcomes can grow: keep an outcome you do not know as it is (the method returns it unchanged and raises nothing). An input the session does not hold raises MeerkatError with the invalid-params code. The recall is session-level (any queued input of the session, whoever submitted it) and withdraws everything the queue coalesced into the input; see session/recall_input. A server that does not serve the method (0.9.0 through 0.9.14; an older server is refused when the SDK connects) answers method not found, and the call raises MeerkatError with the code "-32601"; the method does not read the server’s contract version or capabilities first, and the refused call changes nothing.

compact

Asks the live session’s (or mob member’s) next compaction check to compact, without a rebuild or a respawn and without changing any compaction threshold: the check before its next model request compacts. Returns CompactSessionResult / MobCompactMemberResult whose outcome is requested, or already_requested when a request no check consumed yet was already recorded. A check that consumes the request and has nothing to compact (before the session’s first model request, or with nothing to fold) publishes the requested_compaction_skipped event with its reason instead of compaction_started. The request is never persisted, and a session or member with no live runtime is refused, never woken.

send_external_event

Returns ExternalEventOutcome (runtime admission outcome payload). With idempotency_key, a retry admits nothing new: it answers outcome_type deduplicated and names the first admission in existing_id. The same key with other event content raises INPUT_IDEMPOTENCY_CONFLICT. The key is scoped to the session and needs a server contract of 0.9.5 or later; against an older server the SDK raises CAPABILITY_UNAVAILABLE instead of sending it. send_mob_member_content(..., idempotency_key=None) and Member.send(..., idempotency_key=None) take the same key, deduplicated for the member identity. A keyed send answers continuation (delivery_id, committed_at_ms and a status of pending, admitted with session_id and input_id, stranded or refused); see mob/member_send keys in the RPC reference. An unkeyed send answers admission (session_id and input_id) when the member’s runtime admitted it before the send answered, so a client can tell its send from another client’s send of the same content; see mob/member_send admission in the RPC reference.

Transcript and input reconciliation

A fork child runs under its source’s session configuration, without the source’s shell environment, MCP attachments or mob operator authority; see what a fork child inherits. Since 0.9.4 a fork child can run turns. A child forked by 0.9.3 or earlier that never ran a turn cannot: fork its source again. Both fork calls take inherited_instructions, the fork instruction policy for the instruction activations the prefix carries: "require_explicit_activation" (the default), "reactivate_inherited" or "refuse". A forked child is not materialized, so under the default and under "refuse" a prefix that carries activation rows is refused before anything is committed with FORK_INSTRUCTION_REFUSED; MeerkatError.details carries the typed fork_instruction_refusal (its cause and keys). Pass "reactivate_inherited" to give the child its own activation of every key that was effective in the source; SessionForkResult.reactivated_instruction_count counts those rows, which message_count includes. A prefix without activation rows forks the same way under every value. See session/fork_at.

Additional client wrappers

The Python SDK also exposes:
  • realm helpers: list_realms(), get_realm(...)
  • auth helpers: list_auth_profiles(...), get_auth_profile(...), create_auth_profile(...), delete_auth_profile(...), auth_login_*, auth_provision_api_key(...), auth_status(...), auth_logout(...)
  • blob/skill/MCP helpers: get_blob(...), list_skills(), mcp_add(...), mcp_remove(...), mcp_reload(...)
  • comms helpers: session.send(...), session.peers()
  • typed ingress helper: send_peer_response_terminal(...)
  • runtime host inspection: get_runtime_host_info(), get_runtime_host_capabilities(), get_runtime_host_health()
Auth profiles and persisted credentials are realm-scoped. Login/provisioning returns an auth binding; pass that binding through session auth_binding or a mob member spec instead of embedding provider secrets. A remote member host resolves the declared binding in its authorized realm.

Detached jobs and monitors

The public job wrappers are jobs_get, jobs_list, jobs_cancel, jobs_progress, jobs_result, jobs_artifacts, jobs_retry, jobs_health, jobs_subscribe, and jobs_unsubscribe. monitors_start creates a detached monitor job. Meta worker implementations additionally use the six meta_job_* authority-checked mutation methods. Every public Python RPC wrapper binds its request and result transport boundary to generated RPC-schema contracts. The job request and result dataclasses in 0.8.24 are available from meerkat.generated.types, but are not re-exported from meerkat:

Approvals, artifacts, and projected events

  • approvals: request_approval, list_approvals, get_approval, decide_approval
  • artifacts: list_artifacts, get_artifact, download_artifact
  • cursor-based event recovery: latest_event_cursor, list_events_since, event_snapshot when host event projection is enabled
Approval calls maintain audit records only; they do not automatically gate, authorize, or execute an action. Records persist when the RPC bundle exposes a store path and otherwise remain process-local. See JSON-RPC approvals.

Reasoning effort

create_session(..., reasoning_effort="high") (and the streaming and deferred variants) sets the session’s provider-neutral reasoning effort level: "none", "minimal", "low", "medium", "high", "xhigh" or "max" (meerkat.REASONING_EFFORT_LEVELS). Session.turn(...), Session.stream(...), DeferredSession.start_turn(...) and client.mob_turn_start(...) take the turn’s tri-state: a level sets it from that turn on, meerkat.REASONING_EFFORT_CLEAR ({"action": "clear"}) removes it, and omitting it keeps it. The client sends the field only to a server whose contract is 0.9.15 or later and raises CapabilityUnavailableError otherwise, before anything is written: an older server ignores it on session/create and refuses it on a turn. A level the model or its route does not accept fails the call with a MeerkatError whose code is "-32602" (invalid params) and whose details hold the refusal data. meerkat.reasoning_effort_refusal(error) returns the typed ReasoningEffortRefusal (requested, provider, model, route, reason, supported, facts, conflicting_param, conflicting_level, retryable, and the transient property), or None for any other error:
reason is one of the eight closed reasons (meerkat.REASONING_EFFORT_REFUSAL_REASONS). transient is true only for supported_levels_unavailable; every other reason is permanent until the request or the configuration changes. A refusal with a reason this SDK does not know is not parsed (None), and error.details keeps the data as sent. The route’s names and facts are advisory: a value this SDK does not know is kept as a string. route, supported and facts are always present in the refusal data: None when they have no value, never left out. One case is not recognisable by its data kind: a meerkat_resume of, or a meerkat_comms_send to, the session of a mob member that is not live, whose own build is refused for the level in its profile, is answered the generic agent error (-32013) with a message and no reasoning_effort_refused data. A turn that would change the model identity of a session that has unfinished work is not queued behind that work (the rule of the JSON-RPC turn requests: Model settings on a busy session). It fails at once with a MeerkatError whose code is "-32002" (session busy) and whose details are {"kind": "reasoning_effort_change_needs_idle_session"}; nothing is stored for the turn. The one kind covers every cause. On a session that holds a provider-neutral 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). On a session that holds no level: a turn that sets one. Plain turns, and turns that repeat the session’s level with reasoning_effort, queue as before. This is not a level refusal, so reasoning_effort_refusal(error) returns None for it; a level the model does not accept is still answered with its refusal first. Wait for the running turn’s answer, then send the turn again; do not poll. A later release is planned to queue such a turn.
parse_reasoning_effort_report(...) reads the reasoning_effort block of a run result (requested, and one sent row per distinct resolution: level, provider, model, route, fields, facts, decided_by, requests), and parse_reasoning_effort_resolution(...) the resolution run_started, run_resumed and request_reasoning_effort_resolved carry.

Scoped tool grants

create_session(..., grant_gated_tools={"families": ["shell"]}) (and the streaming and deferred variants) gates built-in tool families and tool names: the session mounts them hidden and refuses their calls until a grant opens them. The client sends a gate only to a server whose contract is 0.9.9 or later, and otherwise raises CapabilityUnavailableError: an older server would build the session with the gated tools ungated.
grant_tool takes exactly one of tool and family and one of duration_ms and expires_at_ms, and raises ValueError before sending otherwise. See scoped tool grants.

Operator instructions

Since 0.9.11 a host sets standing System-plane instructions by slot, revision and body, for one session or for the members of a mob, and reads their status:
A member target ({"kind": "member", "agent_identity": "worker-1"}) may carry "include_forks": True since 0.9.15: the record then also selects the forks of the member’s fork family, and a status read shows the key on such a record (see operator instructions). The client methods are set_session_instruction, revoke_session_instruction, session_instruction_status, set_mob_instruction, revoke_mob_instruction and mob_instruction_status. The results are dicts in the wire shape, checked on read: a disposition, effect, entry kind or state kind this SDK does not know fails the read (INVALID_RESPONSE), while an advisory value it does not know (a pending or blocked reason, residency, lowering) reads as {"unknown": <the value>}. A refused write raises MeerkatError; meerkat.errors.instruction_set_code(error) reads its closed code (for example stale_revision, owned_by_mob or prepared_authorization_required), None for any other error. See RPC operator instructions. When projection is enabled, use cursor replay or a snapshot after reconnect or a typed live-stream lag marker. A live subscriber is an observation surface, not the persistence boundary. Explicitly ephemeral memory realms do not expose the replay APIs.

Durable decisions

A server whose persistence keeps durable decisions reads, presents and withdraws them; one that keeps none answers capability unavailable. The methods need a Meerkat 0.9.11 or newer server: an older one answers method not found (-32601), raised as a MeerkatError that names the method.
present_decision records what a host presenter showed; the presentation counts only when it shows every canonical part of the rendering, or is a summary whose link served the held rendering, to the party that decides now. No SDK method decides a durable decision: a host’s trusted adapter decides one with the human’s authenticated event. See durable decisions.

Mob profile and events surfaces

Multi-host operator surface

The client exposes host inventory and route installs, host bind/revoke, grant/revoke/list scopes, remote member history, hard cancel, and remote live channel control. These JSON-RPC methods are trusted operator controls. Public REST/MCP and agent-callable tools intentionally expose narrower read or member surfaces, and agent spawn cannot authorize the Rust-only resume_from_role durable role migration.

Mob event history

Returns MobEventsResult.

Realm profile CRUD

Types:
  • MobProfile, MobProfileTools
  • StoredMobProfile
  • DeletedMobProfile

Streaming

EventStream is returned by session.stream(...) and client.create_session_streaming(...).
  • synchronous constructor style (session.stream(...) returns stream object)
  • request is sent on async with entry
  • events.result is available after iteration
  • BackgroundJobCompleted.terminal_status is the typed terminal status for background jobs (job_id, display_name, terminal_status, detail)

Live channels

RealtimeChannel and the old realtime convenience helpers are no longer public SDK handles. The current helper is LiveChannel.session(client, session_id, ...), which binds a session id and stores the channel_id returned by live/open.
Direct MeerkatClient helper names mirror the RPC methods:
  • live_open(session_id, turning_mode=None, transport=None, seed_max_chars=None)
  • live_webrtc_answer(channel_id, token, offer_sdp)
  • live_status(channel_id)
  • live_close(channel_id)
  • live_send_input_text(channel_id, text)
  • live_send_input_audio(channel_id, data_base64, sample_rate_hz, channels)
  • live_send_input_image(channel_id, idempotency_key, mime, data_base64)
  • live_send_input_video_frame(channel_id, codec, data_base64, timestamp_ms)
  • live_commit_input(channel_id, response_modality=None)
  • live_interrupt(channel_id)
  • live_truncate(channel_id, item_id, content_index, audio_played_ms)
  • live_refresh(channel_id)
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. live_send_input_image requires a caller-stable, session-scoped key. Its return value proves queue acceptance only; durable success is the later user_content_committed observation carrying that same key. Pass a positive seed_max_chars to bound serialized seed messages and request a core-owned whole-turn suffix at open time. Omission preserves the complete seed; zero is rejected. Every ordered System message must fit; an existing compaction summary may be retained, and any truncation reports degraded continuity. Canonical image identity, tombstone, and accounting sidecars remain complete. live_open returns a discriminated transport object. The websocket variant has url and token. The webrtc variant has token, answer_method, and an optional http_url; create an SDP offer and pass it to live_webrtc_answer. Do not assume every transport has a URL. WebRTC requires connect(live_webrtc=True) and an rkat-rpc binary compiled with its non-default live-webrtc Cargo feature. The 0.8.24 auto-downloaded release binary does not include that feature. Add an audio track or the meerkat.live data channel, set the browser peer’s local description, wait for ICE gathering to complete, then send peer.localDescription.sdp. The protocol has no candidate-trickle RPC. Install the returned answer_sdp as the browser peer’s remote description before sending live input. MeerkatClient.parse_live_observation(raw) type-narrows a frame from the live transport against WireLiveAdapterObservation. Since 0.9.4 that union includes turn_failed, a response the provider ended without completing. Its failure is a WireLiveResponseFailure: route on status ("failed", "incomplete", "in_progress", or {"unknown": {"debug": ...}} for a status without a wire name); reason, code and message are diagnostics only. WireLiveResponseFailure and WireLiveResponseFailureStatus are exported from meerkat. See the realtime guide for what the channel does next.

Event compatibility note

The parser raises MeerkatError with code UNKNOWN_EVENT_TYPE only when a present event type is outside the generated known-event inventory. An inventory-known type without a handwritten parser class arrives as UnknownEvent, preserving the wire type in event.type and the complete payload in event.data. A missing event type or a malformed payload for a handwritten parser class is preserved as UnknownEvent with type="malformed_event". The current inventory includes server_tool_content, all four model_fallback_* events, transcript_rewrite_audit_receipt_committed, boundary_append_applied, and boundary_appends_discarded. These currently use the raw-preserving UnknownEvent path, as do reasoning_delta, reasoning_complete, assistant_image_appended, turn_usage_accounting_unmeasured, turn_usage_accounting_identity_disputed, interaction_callback_pending, peer_content_ingested, provider_cache_breakpoints_discarded, tool_results_bounded_for_request, requested_compaction_skipped, and operator_instructions_applied. See the RPC event reference for their wire contracts. From 0.9.15, request_reasoning_effort_resolved has a handwritten parser class and arrives as a typed RequestReasoningEffortResolved event: resolution, turn_number and fallback_attempt. It is published once for each request handed to the provider client with the session’s reasoning effort level; parse_reasoning_effort_resolution(...) reads its resolution (see Reasoning effort). An SDK older than 0.9.15 raises UNKNOWN_EVENT_TYPE on it. live_channel_closed has a handwritten parser class and arrives as a typed LiveChannelClosed event: session_id, channel_id, reason and reopen_recommended. It is published once for every committed close of one of the session’s live channels. reason is one of the LiveChannelCloseReason values client_requested, client_disconnected, provider_closed, error, media_fault, replaced or open_abandoned; any other value is preserved as UnknownEvent with type="malformed_event". reopen_recommended is true only for a media_fault whose session may still reopen the channel with its retained context. RunStarted.input preserves the typed RunInput: either {"kind": "content", "content": ...} or {"kind": "pending_tool_results"}. Content may be text or content blocks; the continuation variant does not fabricate a prompt. RunFailed accepts the current error_report and derives its error_class and error display fields from that report. Since 0.9.4 a run that failed because the provider refused or filtered the response (error_class content_filtered) carries error_report.reason as an AgentErrorReason with reason_type == "content_filtered", stop ("refusal" or "content_filter") and detail, the provider’s own account as a dictionary tagged by "provider" (anthropic, open_ai or gemini), or None when the provider gave none. A detail that is not a provider-tagged dictionary reads as None, and a stop the SDK does not know reads as an unknown reason with the wire object in raw. SDKs before 0.9.4 read every such reason as unknown and keep it raw. ToolConfigChanged.payload is a ToolConfigChangedPayload whose settled field replaces persisted in 0.9.4. It says whether the change is a settled lifecycle fact rather than a pending or draining step, derived from status_info the way rkat-rpc derives it; the stored bit (settled, or persisted from rkat-rpc 0.9.3 and earlier) is used only for a status the SDK does not know. It says nothing about configuration: whether a change was written there is the persisted of the mcp_add, mcp_remove and mcp_reload responses. Stored notices in session history stay raw and can carry either key. A 0.9.3 SDK requires persisted and fails on every tool_config_changed event from a 0.9.4 rkat-rpc. The binary the SDK downloads always matches it, so this happens only with a binary you supply (MEERKAT_BIN_PATH, an explicit rkat_path, or rkat-rpc on PATH); upgrade the SDK with the binary. CompactionCompleted carries two fields new in 0.9.4:
  • summary_source (CompactionSummarySource): who wrote the summary. kind is provider_call (with source_bound, a SummarizationSourceBound whose kind is whole, trimmed with through = tool_results, context or user_requests, or requests_only with kept and of), host_curator or mechanical_fallback. A kind this SDK does not know is unknown, with the wire kind in raw_kind and the wire object in raw. None for a completion recorded before 0.9.4.
  • estimated_history_tokens_after: the estimated history tokens the rewrite left, in the unit of CompactionStarted.estimated_history_tokens; None for a completion recorded before 0.9.4 or when the history could not be measured.
Retrying parses the current wire shape, which carries one typed retry schedule: attempt, max_attempts, error and delay_ms are projections of retry.plan.attempt, retry.plan.max_retries, retry.failure.message and retry.plan.selected_delay_ms, and the schedule itself is kept in retry. The flat legacy shape is still accepted. HookFailed.reason contains a known native cause or an UnknownHookFailureReason with reason_code="unknown". Unknown wire reason codes and confinement refusal strings retain the exact original dictionary in reason["raw"] and its original reason code in reason["raw_reason_code"]; their error display is "unknown hook failure". Known native dictionaries stay unchanged. Read their reason_code and, for confinement refusal, refusal instead of parsing the display-only error. Check field types before using values inside the unknown wrapper’s raw. The legacy flat error wire remains accepted with reason=None. A present reason is authoritative even when error is also supplied. Malformed required fields in a known cause still produce UnknownEvent(type="malformed_event") with the raw payload preserved, without falling back to the legacy error. request_reasoning_lowered is likewise recognized through the generated inventory and arrives as UnknownEvent with its payload in event.data. hook_launch_refused is recognized through the current generated inventory and arrives as UnknownEvent with the full wire payload in event.data, including reason and the exact optional tool_use_id. This mechanical prelaunch fact is separate from a permission denial or a terminal run event.

Assistant message identity

TurnStarted, TextDelta, TextComplete, TurnCompleted and Retrying carry an optional assistant_message_id. It equals assistant_message_id on the block_assistant SessionMessage that history returns for the same message, so join live rows to history by that id, never by text or position. RunCompleted.assistant_message_id names the message whose text result repeats. The raw-preserving UnknownEvent payloads of reasoning_delta, reasoning_complete, server_tool_content and assistant_image_appended carry the same key in event.data. The value is None on data written before 0.8.45. Only a history row carrying the id is the commit: TurnCompleted is a live signal that can arrive before work that still fails the run, and can be missing for a committed row, so reconcile against history when the run ends. Rows the realtime transcript materializer commits have no id; their SessionMessage.realtime_origin["provider_item_ids"] match the provider item ids on the live transport’s realtime observations. See assistant message identity for retry, compaction and rewrite semantics.

Capability and error model

Capabilities:
Errors:
All SDK errors derive from MeerkatError. BinaryIntegrityError (code BINARY_INTEGRITY_MISMATCH) means the auto-downloaded rkat-rpc archive, the binary inside it or its cached copy does not match the sha256 the package pins; it carries asset, path (the cached binary, or None for a download), expected_sha256 and actual_sha256, and the SDK never falls back to another binary. BINARY_DIGEST_UNAVAILABLE means the package pins no digest for this version and platform (a source or git install), so it will not download one; its message names the exact release asset URL. BINARY_DOWNLOAD_FAILED is a transport fault (a detected cut-off body included): a transport fault the SDK can detect is never reported as tamper. BINARY_DOWNLOAD_TOO_LARGE is an archive over 256 MiB. See The rkat-rpc binary. When the rkat-rpc child exits by itself (a crash, for example), pending and later requests fail with CONNECTION_CLOSED, keeping the child’s stderr tail. Since 0.9.4 they fail at most about a second after the exit, even while a process the child started still holds its output pipes; before, they could wait until those pipes closed. MeerkatClient.close() likewise returns once the child has exited: it terminates the child, waits up to 5 seconds, then kills it. On Python 3.11 and 3.12, and on 3.13 and 3.14 before the fix for CPython issue 119710, close() used to wait the full 5 seconds for a child that had already exited. A failed session.send(...) carries the server’s typed CommsSendErrorData in MeerkatError.details, tagged on code (peer_not_found_or_not_trusted, peer_unreachable, peer_admission_dropped, peer_input_rejected, peer_wake_refused, send_ambiguous, send_failed, invalid_command). peer_wake_refused is a seated member whose wake was refused: nothing was delivered, refusal["kind"] says why and retryable whether a later send can succeed. comms_send_error(error) returns it, or None for any other error. Branch on code, never on the message text. send_ambiguous means the delivery may already have landed (retry_safe is False, required_action is "reconcile"): reconcile by its envelope_id before any new attempt, since a retry can duplicate it.
A mob destroy that did not finish (mob_destroy, or mob_lifecycle with "destroy") fails with code mob_destroy_incomplete; its details carry the destroy_report and retryable: True. mob_destroy_incomplete_report(error) returns that report as a WireMobDestroyReport, or None for any other error. Retry the destroy later: member_reload_refusals names each member whose reload the runtime refused, with its typed refusal (a kind this SDK does not know reads as {"kind": "unknown"}).
A call that addresses a quarantined mob (a persisted mob whose store did not restore; see Quarantined mobs and degraded members) fails with details of kind mob_quarantined. mob_quarantined(error) returns a MobQuarantinedRefusal (mob_id, quarantine_class, retryable, cause, code), or None for any other error. A store_unavailable mob is re-attempted by the next call that addresses it; repair the store of any other class, then call mob_restore_retry. list_quarantined_mobs() lists the quarantined mobs (list_mobs() lists only the managed ones).