Version
Primary handles
MeerkatClientowns the runtime process and transport.Sessionis a live multi-turn handle.DeferredSessionis a created session that has not run its first turn yet.LiveChannelis the session-bound wrapper for thelive/*RPC surface.Mobis 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: strtext: strturns: inttool_calls: intusage: Usageterminal_cause_kind: str | Nonesession_ref: str | Nonestructured_output: Any | Noneextraction_error: ExtractionError | Noneschema_warnings: list[SchemaWarning] | Noneskill_diagnostics: SkillRuntimeDiagnostics | None
SessionSummary
Returned by client.list_sessions(...).
session_id: strsession_ref: str | Nonecreated_at: intupdated_at: intmessage_count: inttotal_tokens: intlabels: dict[str, str]is_active: bool
SessionDetails
Returned by client.read_session(session_id).
session_id: strsession_ref: str | Nonecreated_at: intupdated_at: intmessage_count: intlabels: dict[str, str]is_active: boolmodel: strprovider: strlast_assistant_text: str | Noneresolved_capabilities: ResolvedModelCapabilities | None
SessionInfo
Base shared metadata type for session identity/timestamps/state.
Usage
input_tokens: intoutput_tokens: intcache_creation_tokens: int | Nonecache_read_tokens: int | Noneaccounting: ProviderTokenAccounting | None
ProviderTokenAccounting
provider: strmodel: strpresented_tokens: intconvention: straggregation: str
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: intrealm_id: str | Noneinstance_id: str | Nonebackend: str | Noneresolved_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": ...})
ScheduleListResultScheduleOccurrencesResultScheduleToolsResult
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. Useget_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] | Noneis ordered durable user-channel context immediately before the prompttransient_turn_context: str | Noneis request-only host context- turn methods also accept
self_hosted_server_idfor an exact configured local model route
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
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.
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
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
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
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_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 arejobs_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_snapshotwhen host event projection is enabled
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:{"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-onlyresume_from_role
durable role migration.
Mob event history
MobEventsResult.
Realm profile CRUD
MobProfile,MobProfileToolsStoredMobProfileDeletedMobProfile
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 withentry events.resultis available after iterationBackgroundJobCompleted.terminal_statusis 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.
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)
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 raisesMeerkatError 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.kindisprovider_call(withsource_bound, aSummarizationSourceBoundwhosekindiswhole,trimmedwiththrough=tool_results,contextoruser_requests, orrequests_onlywithkeptandof),host_curatorormechanical_fallback. A kind this SDK does not know isunknown, with the wire kind inraw_kindand the wire object inraw.Nonefor a completion recorded before 0.9.4.estimated_history_tokens_after: the estimated history tokens the rewrite left, in the unit ofCompactionStarted.estimated_history_tokens;Nonefor 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: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.
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"}).
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).
