TypeScript SDK reference

Public SDK interfaces use camelCase by default. Protocol-bound multimodal content keys (media_type, blob_id, duration_ms) intentionally remain wire-shaped.

Imports

The stable domain types and helpers are re-exported from the package root:

import {
  MeerkatClient,
  Session,
  LiveChannel,
  Mob,
  EventStream,
  EventSubscription,
  MeerkatError,
  CapabilityUnavailableError,
  SessionNotFoundError,
  SkillNotFoundError,
  CONTRACT_VERSION,
} from "@rkat/sdk";

import type {
  RunResult,
  Usage,
  SessionInfo,
  SessionOptions,
  LiveChannelOptions,
  LiveOpenResult,
  LiveStatusResult,
  LiveInputChunkWire,
  ContentBlock,
  Capability,
  SkillKey,
  SkillRef,
  SkillRuntimeDiagnostics,
  SchemaWarning,
  AgentEvent,
  StreamEvent,
  AgentEventEnvelope,
  AttributedMobEvent,
  EventEnvelope,
  AttributedEvent,
  MobMember,
  MobStatus,
  MobSummary,
  SpawnSpec,
  MobFlowStatus,
  MobLifecycleAction,
  MobDefinition,
  TextDeltaEvent,
  TurnCompletedEvent,
  // ... all event types
} from "@rkat/sdk";

Every public TypeScript RPC wrapper binds its request and response transport boundary to generated RPC-schema contracts. Generated job, approval, artifact, and durable-event parameter/result names appear in the public client declarations but are not re-exported from the package root in 0.8.24. Pass structural object literals to those methods. This is an export/code-generation gap, not a second wire contract.

Additional client wrappers

The package exports more than the core session lifecycle. The MeerkatClient also exposes:

auth-profile helpers: authProfileList, authProfileGet, authProfileCreate, authProfileDelete
auth-login helpers: authLoginStart, authLoginComplete, authLoginDeviceStart, authLoginDeviceComplete, authLoginProvisionApiKey, authStatusGet, authLogout
realm helpers: realmList, realmGet
typed ingress helper: sendPeerResponseTerminal
MCP live-op helpers: mcpAdd, mcpRemove, mcpReload
blob/skill helpers: getBlob, listSkills
runtime host helpers: getRuntimeHostInfo, getRuntimeHostCapabilities, getRuntimeHostHealth
transcript and recovery helpers: inputState, exportSessionAtif, revision read/list, fork-at/fork-replace, rewrite, system-prompt update, and restore
WorkGraph observability: item/ready/event listing, snapshot, goal status, and attention listing
detached jobs and monitors: the jobs* family plus monitorsStart and the authority-checked mobkitJob* worker mutations
approvals and artifacts: request/list/get/decide plus list/get/download artifacts
projected event recovery: latestEventCursor, listEventsSince, eventSnapshot when host event projection is enabled
live-channel helpers: liveOpen, liveStatus, liveClose, liveSendInput, liveSendInputImage, liveSendInputVideoFrame, liveCommitInput, liveWebrtcAnswer, liveInterrupt, liveTruncate, liveRefresh, and parseLiveObservation

Approval calls maintain audit records only; they do not automatically gate, authorize, or execute an action. Records persist when the RPC persistence bundle exposes a store path. See JSON-RPC approvals. Auth profiles and persisted credentials are realm-scoped. Auth login or API key provisioning yields an auth binding; pass it as SessionOptions.authBinding or in a mob member spec instead of embedding provider secrets. A remote member host resolves that binding only inside its authorized realm.

Core types

RunResult

The result returned by session.turn(), session.invokeSkill(), and deferred.startTurn(). Session creation returns runtime-backed Session or DeferredSession wrappers, and the latest RunResult remains available through session.lastResult or stream.result after an EventStream is fully consumed.

interface RunResult {
  readonly sessionId: string;
  readonly sessionRef?: string;
  readonly text: string;
  readonly turns: number;
  readonly toolCalls: number;
  readonly usage: Usage;
  readonly terminalCauseKind?: TurnTerminalCauseKind;
  readonly structuredOutput?: unknown;
  readonly extractionError?: ExtractionError;
  readonly schemaWarnings?: readonly SchemaWarning[];
  readonly skillDiagnostics?: SkillRuntimeDiagnostics;
}

Field	Type	Description
`sessionId`	`string`	Stable UUID for this session
`sessionRef`	`string \| undefined`	Optional human-readable reference
`text`	`string`	Full assistant text from the last LLM turn
`turns`	`number`	Number of LLM turns in this run
`toolCalls`	`number`	Total tool calls executed in this run
`usage`	`Usage`	Token usage for this run
`terminalCauseKind`	`TurnTerminalCauseKind \| undefined`	Machine-owned terminal cause when success carries a typed terminal condition (e.g. budget exhaustion)
`structuredOutput`	`unknown \| undefined`	Parsed structured output when `outputSchema` was provided
`extractionError`	`ExtractionError \| undefined`	Extraction failure details (`lastOutput`, `attempts`, `reason`) when schema extraction failed after a completed main run
`schemaWarnings`	`SchemaWarning[] \| undefined`	Warnings emitted when structured output didn’t fully match the schema
`skillDiagnostics`	`SkillRuntimeDiagnostics \| undefined`	Runtime diagnostics from the skill subsystem

Session

client.createSession() returns a runtime-backed Session wrapper.

class Session {
  readonly id: string;
  readonly ref?: string;
  readonly text: string;
  readonly usage: Usage;
  readonly turns: number;
  readonly toolCalls: number;
  readonly structuredOutput?: unknown;
  readonly lastResult: RunResult;
}

The Session methods are thin conveniences over canonical runtime calls:

await session.turn(...)
session.stream(...)
await session.history(...)
await session.archive()
await session.interrupt()
await session.stopRun(runId, reason)
await session.invokeSkill(...)
await session.subscribeEvents()

DeferredSession

client.createDeferredSession() reserves session identity now and runs the first turn later through await deferred.startTurn(...), or streams it through deferred.stream(...) -> EventStream. Although deferred creation reuses SessionOptions, the server rejects transientTurnContext because no immediate turn exists. Current DeferredTurnOptions omits injectedContext, transientTurnContext, and selfHostedServerId. Set injected context during deferred creation; transient first-turn context and a self-hosted server route are not expressible through the current deferred TypeScript wrapper. Both deferred turn methods accept skillRefs, turnToolOverlay, additionalInstructions, keepAlive, model, provider, maxTokens, systemPrompt, outputSchema, structuredOutputRetries, and providerParams.

LiveChannel

LiveChannel is the session-bound helper for the live/* RPC surface. RealtimeChannel was removed with the live-adapter surface; use LiveChannel.session(client, sessionId, options?) instead.

const channel = LiveChannel.session(client, session.id, {
  turningMode: "explicit_commit",
  seedMaxChars: 24_000,
});

const opened: LiveOpenResult = await channel.open();
await channel.sendInputImage("turn-42-diagram", "image/png", imageDataBase64);
// Queue acceptance is not durability; wait for user_content_committed with
// idempotency_key === "turn-42-diagram" before sending dependent input.
await channel.sendInputText("hello");
await channel.commitInput("text");
const status: LiveStatusResult = await channel.status();
const refresh = await channel.refresh();
await channel.close();

The helper stores the channel_id returned by live/open. It does not own the transport. Branch on opened.transport.transport: websocket carries url and token; webrtc carries token, answer_method, and optional http_url. Use client.liveWebrtcAnswer(...) to exchange a completed browser-created SDP offer. Do not assume every bootstrap has a URL. The Node SDK does not provide RTCPeerConnection; inject an implementation or forward browser-created SDP to the Node process. Add an audio track or the meerkat.live data channel, set the local description, wait for ICE gathering to complete, and send peer.localDescription.sdp. The 0.8.24 answerLiveWebrtcOffer(...) helper does not perform that wait and sends the original offer SDP, so use direct client.liveWebrtcAnswer(...) for the canonical browser exchange. WebRTC also requires an rkat-rpc binary compiled with the non-default live-webrtc Cargo feature. The 0.8.24 release binary does not include that feature, so liveWebrtc: true requires a custom binary. The direct helper has the same required identity: client.liveSendInputImage(channelId, idempotencyKey, mime, dataBase64). LiveChannelOptions.seedMaxChars forwards as LiveOpenParams.seed_max_chars. It must be positive, bounds serialized seed messages, and requests a core-owned whole-turn suffix; omission preserves the complete canonical seed. Every ordered System message must fit. Runtime context and complete image identity, tombstone, and accounting sidecars remain outside the window. Any truncation reports degraded continuity, and the server rejects zero.

Usage

Token usage. All fields are camelCase - there is no total_tokens field.

interface ProviderTokenAccounting {
  readonly provider: string;
  readonly model: string;
  readonly presentedTokens: number;
  readonly convention: string;
  readonly aggregation: string;
}

interface Usage {
  readonly inputTokens: number;
  readonly outputTokens: number;
  readonly cacheCreationTokens?: number;
  readonly cacheReadTokens?: number;
  readonly accounting?: ProviderTokenAccounting;
}

One type serves two different accounts. When present on turn_completed this is per-call usage: inputTokens is the raw provider counter (for Anthropic, uncached input only) and accounting names the resolved provider/model plus the normalized presentedTokens for that call. On RunResult.usage and run_completed it is the session-cumulative total: inputTokens is already the sum of every recorded call’s presentedTokens, it is persisted with the session so it keeps growing across turns, and accounting is absent because a session may span models. Do not sum the cumulative value with anything - take the latest one - and sum accounting.presentedTokens rather than per-call inputTokens. 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.

SessionInfo

Summary returned by client.listSessions().

interface SessionInfo {
  readonly sessionId: string;
  readonly sessionRef?: string;
  readonly createdAt: number;
  readonly updatedAt: number;
  readonly messageCount: number;
  readonly totalTokens?: number;
  readonly isActive: boolean;
  readonly model?: string;
  readonly provider?: string;
  readonly lastAssistantText?: string;
  readonly resolvedCapabilities?: ResolvedModelCapabilities;
  readonly labels: Readonly<Record<string, string>>;
}

Capability

A single runtime capability entry, as returned by client.capabilities.

interface Capability {
  readonly id: string;
  readonly description: string;
  readonly status: string;  // "Available", "DisabledByPolicy", "NotCompiled", etc.
}

Status values may be emitted as externally-tagged Rust enum objects (e.g. { DisabledByPolicy: { ... } }). The SDK normalizes these to the key string automatically.

ContentBlock

Content blocks are used in multimodal prompts and tool results. Both createSession() and session.turn() accept string | ContentBlock[] as the prompt parameter.

type ContentBlock =
  | { type: "text"; text: string }
  | { type: "image"; media_type: string; data: string; source?: "inline" }
  | { type: "image"; media_type: string; source: "blob"; blob_id: string }
  | { type: "video"; media_type: string; duration_ms: number; data: string; source?: "inline" }
  | { type: "video"; media_type: string; duration_ms: number; source: "uri"; uri: string };

Variant	Fields	Description
`text`	`text: string`	Plain text content
`image`	`media_type: string`, `data: string`	Base64-encoded image with MIME type (e.g. `"image/png"`)

// Multimodal prompt example
const session = await client.createSession([
  { type: "text", text: "Describe this image" },
  { type: "image", media_type: "image/png", data: base64Data },
]);

SchemaWarning

Emitted when a structured output response did not fully conform to the requested schema.

interface SchemaWarning {
  readonly provider: string;
  readonly path: string;
  readonly message: string;
}

Skill types

SkillKey

Structured skill identifier.

interface SkillKey {
  readonly sourceUuid: string;
  readonly skillName: string;
}

SkillRef

A skill reference is a structured SkillKey.

type SkillRef = SkillKey;

SkillRuntimeDiagnostics

Runtime diagnostics from the skill subsystem. Present on RunResult.skillDiagnostics when the server emits skill health data.

interface SkillRuntimeDiagnostics {
  readonly sourceHealth: SourceHealthSnapshot;
  readonly quarantined: readonly SkillQuarantineDiagnostic[];
}

interface SourceHealthSnapshot {
  readonly state: string;
  readonly invalidRatio: number;
  readonly invalidCount: number;
  readonly totalCount: number;
  readonly failureStreak: number;
  readonly handshakeFailed: boolean;
}

interface SkillQuarantineDiagnostic {
  readonly sourceUuid: string;
  readonly skillId: string;
  readonly location: string;
  readonly errorCode: string;
  readonly errorClass: string;
  readonly message: string;
  readonly firstSeenUnixSecs: number;
  readonly lastSeenUnixSecs: number;
}

EventStream

EventStream is an AsyncIterable<StreamEvent> returned by createSessionStreaming() and session.stream(). It yields events as the agent runs, then makes the final RunResult available on stream.result. StreamEvent includes AgentEvent and scoped wrappers. Use the exported type guards for direct payloads because UnknownEvent keeps the event union open-ended; the guards do not unwrap scoped events.

class EventStream implements AsyncIterable<StreamEvent> {
  readonly sessionId: string;
  readonly result: RunResult;  // throws if accessed before iteration completes

  [Symbol.asyncIterator](): AsyncGenerator<StreamEvent, void, undefined>;

  /** Consume all events and return the final RunResult. */
  collect(): Promise<RunResult>;

  /** Consume events, accumulate text deltas, return [fullText, result]. */
  collectText(): Promise<[string, RunResult]>;
}

Iterating

import { isTextDelta } from "@rkat/sdk";

const stream = session.stream("Summarise this");
for await (const event of stream) {
  if (isTextDelta(event)) {
    process.stdout.write(event.delta);
  }
}
const result = stream.result;

collect()

Discards all events and returns the final result:

const result = await stream.collect();

collectText()

Accumulates all text_delta events and returns the joined string alongside the result:

const [fullText, result] = await stream.collectText();
console.log(fullText);
console.log("Output tokens:", result.usage.outputTokens);

Typed events

All events are discriminated on the type field (snake_case, matching the wire protocol). All other fields are camelCase.

AgentEvent union

type AgentEvent =
  | RunStartedEvent
  | RunCompletedEvent
  | ExtractionSucceededEvent
  | ExtractionFailedEvent
  | RunFailedEvent
  | TurnStartedEvent
  | TextDeltaEvent
  | TextCompleteEvent
  | ToolCallRequestedEvent
  | ToolResultReceivedEvent
  | TurnCompletedEvent
  | ToolExecutionStartedEvent
  | ToolExecutionCompletedEvent
  | ToolExecutionTimedOutEvent
  | CompactionStartedEvent
  | CompactionCompletedEvent
  | CompactionFailedEvent
  | BudgetWarningEvent
  | RetryingEvent
  | HookStartedEvent
  | HookCompletedEvent
  | HookFailedEvent
  | HookDeniedEvent
  | SkillsResolvedEvent
  | SkillResolutionFailedEvent
  | InteractionCompleteEvent
  | InteractionFailedEvent
  | StreamTruncatedEvent
  | ToolConfigChangedEvent
  | BackgroundJobCompletedEvent
  | LiveChannelClosedEvent
  | TranscriptRewriteCommittedEvent
  | MalformedEvent
  | UnknownEvent;

Event parsing fails closed: a present type outside the generated KNOWN_AGENT_EVENT_TYPES inventory throws a MeerkatError with code UNKNOWN_EVENT_TYPE. An inventory-known type without a handwritten parser case arrives as UnknownEvent, preserving the wire type in event.type and the complete payload as fields on the event. A missing event type or a malformed payload for a handwritten parser case is preserved as MalformedEvent (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, and provider_cache_breakpoints_discarded. See the RPC event reference for their wire contracts. live_channel_closed has a handwritten parser and arrives as a typed LiveChannelClosedEvent: sessionId, channelId, reason and reopenRecommended. It is published once for every committed close of one of the session’s live channels. reason is a LiveChannelCloseReason: client_requested, client_disconnected, provider_closed, error, media_fault, replaced or open_abandoned; any other value is a malformed payload. reopenRecommended is true only for a media_fault whose session may still reopen the channel with its retained context. RunStartedEvent.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. RunFailedEvent accepts the current error_report and derives its errorClass and error display fields from that report. RetryingEvent parses the current wire shape, which carries one typed retry schedule: attempt, maxAttempts, error and delayMs 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. HookFailedEvent.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 object in reason.raw and its original reason code in reason.rawReasonCode; their error display is "unknown hook failure". Known native objects stay unchanged and narrow normally by reason.reason_code, including their typed fields. Inspect fields inside the unknown wrapper’s raw defensively. Use the typed reason instead of parsing the display-only error. The legacy flat error wire remains accepted with reason absent. A present reason is authoritative even when error is also supplied. Malformed required fields in a known cause still produce MalformedEvent with the raw payload preserved, without falling back to the legacy error. request_reasoning_lowered is likewise recognized through the generated inventory and preserved by the raw-event path. hook_launch_refused is recognized through the current generated inventory and preserved by the existing raw-event path, including reason and the exact optional tool_use_id. This mechanical prelaunch fact is separate from a permission denial or a terminal run event. TurnStartedEvent, TextDeltaEvent, TextCompleteEvent, TurnCompletedEvent and RetryingEvent carry an optional assistantMessageId. It equals assistantMessageId 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. RunCompletedEvent.assistantMessageId names the message whose text result repeats. The raw payloads of reasoning_delta, reasoning_complete, server_tool_content and assistant_image_appended carry the same assistant_message_id key. Only a history row carrying the id is the commit: TurnCompletedEvent 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.realtimeOrigin.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.

Session lifecycle events

interface RunStartedEvent   { type: "run_started";   sessionId: string; input: RunInput; identity?: TranscriptMessageIdentity }
interface RunCompletedEvent {
  type: "run_completed";
  sessionId: string;
  result: string;
  structuredOutput?: unknown;
  extractionRequired?: boolean;
  usage: Usage;
  terminalCauseKind?: TurnTerminalCauseKind;
  assistantMessageId?: string;
}
interface ExtractionSucceededEvent {
  type: "extraction_succeeded";
  sessionId: string;
  structuredOutput: unknown;
  schemaWarnings?: readonly SchemaWarning[];
}
interface ExtractionFailedEvent {
  type: "extraction_failed";
  sessionId: string;
  lastOutput: string;
  attempts: number;
  reason: string;
}
interface RunFailedEvent {
  type: "run_failed";
  sessionId: string;
  errorClass: string;
  error: string;
  terminalCauseKind?: TurnTerminalCauseKind;
  errorReport?: AgentErrorReport | null;
}

Turn and LLM events

interface TurnStartedEvent        { type: "turn_started";         turnNumber: number; assistantMessageId?: string }
interface TextDeltaEvent          { type: "text_delta";            delta: string; assistantMessageId?: string }
interface TextCompleteEvent       { type: "text_complete";         content: string; assistantMessageId?: string }
interface ToolCallRequestedEvent  { type: "tool_call_requested";   id: string; name: string; args: ToolCallArguments }
interface ToolResultReceivedEvent { type: "tool_result_received";  id: string; name: string; content: readonly ContentBlock[]; isError?: boolean }
interface TurnCompletedEvent      { type: "turn_completed";        stopReason?: StopReason; usage?: Usage; assistantMessageId?: string }

type StopReason =
  | "end_turn"
  | "tool_use"
  | "max_tokens"
  | "stop_sequence"
  | "content_filter"
  | "cancelled";

Tool execution events

interface ToolExecutionStartedEvent   { type: "tool_execution_started";    id: string; name: string }
interface ToolExecutionCompletedEvent { type: "tool_execution_completed";   id: string; name: string; content: readonly ContentBlock[]; isError?: boolean; durationMs?: number }
interface ToolExecutionTimedOutEvent  { type: "tool_execution_timed_out";   id: string; name: string; timeoutMs: number }

Compaction events

interface CompactionStartedEvent   { type: "compaction_started";   inputTokens: number; estimatedHistoryTokens: number; messageCount: number }
interface CompactionCompletedEvent { type: "compaction_completed";  summaryTokens: number; messagesBefore: number; messagesAfter: number }
// `reason` mirrors the Rust CompactionFailureReason tagged enum ({ kind, ... }).
interface CompactionFailedEvent    { type: "compaction_failed";     reason: Record<string, unknown> }

Budget events

interface BudgetWarningEvent { type: "budget_warning"; budgetType: BudgetType; used: number; limit: number; percent: number }

type BudgetType = "tokens" | "time" | "tool_calls";

Retry events

interface RetryingEvent { type: "retrying"; attempt: number; maxAttempts: number; error: string; delayMs: number; retry?: Record<string, unknown>; assistantMessageId?: string }

Hook events

import type { HookFailureReason } from "@rkat/sdk";
type HookPoint =
  | "run_started" | "run_completed" | "run_failed"
  | "pre_llm_request" | "post_llm_response"
  | "pre_tool_execution" | "post_tool_execution"
  | "turn_boundary";

interface HookStartedEvent        { type: "hook_started";         hookId: string; point: HookPoint }
interface HookCompletedEvent      { type: "hook_completed";        hookId: string; point: HookPoint; durationMs: number }
interface HookFailedEvent         { type: "hook_failed";           hookId: string; point: HookPoint; error: string; reason?: HookFailureReason }
interface HookDeniedEvent         { type: "hook_denied";           hookId: string; point: HookPoint; reasonCode: string; message: string; payload?: unknown }

HookFailureReason and UnknownHookFailureReason are public adapter types. ConfinementRefusal is also exported for the known native confinement causes.

Skill events

interface SkillsResolvedEvent       { type: "skills_resolved";         skills: readonly SkillKey[]; injectionBytes: number }
interface SkillResolutionFailedEvent { type: "skill_resolution_failed"; skillKey?: SkillKey; reason?: SkillResolutionFailureReason }

SkillResolutionFailureReason is a typed union discriminated on reasonType (not_found, capability_unavailable, load, parse, source_uuid_collision, source_uuid_mutation_without_lineage, missing_skill_remaps, remap_without_lineage, unknown_skill_alias, remap_cycle, no_skill_engine, unknown). no_skill_engine carries requested: readonly SkillKey[], the explicit selection that could not resolve because the agent was built without a skill engine. A reasonType this SDK does not know is returned as unknown with rawReasonType set.

Comms events

interface InteractionCompleteEvent { type: "interaction_complete"; interactionId: string; result: string; structuredOutput?: unknown }
interface InteractionFailedEvent   { type: "interaction_failed";   interactionId: string; reason: InteractionFailureReason }

Tool config events

interface ToolConfigChangedEvent { type: "tool_config_changed"; payload: ToolConfigChangedPayload }

// Payload keys intentionally remain wire-shaped (snake_case).
interface ToolConfigChangedPayload {
  operation?: "add" | "remove" | "reload";
  target?: string;
  status_info?: ToolConfigChangeStatus;
  persisted?: boolean;
  applied_at_turn?: number;
}

type ToolConfigChangeStatus =
  | { kind: "boundary_applied"; base_changed: boolean; visible_changed: boolean; revision: number }
  | { kind: "deferred_catalog_delta"; added_hidden_count: number; removed_hidden_count: number; pending_source_count: number }
  | { kind: "warning_failed_closed"; error: string }
  | { kind: "external_tool_delta"; phase: "pending" | "applied" | "draining" | "forced" | "failed"; detail?: string };

Background job events

type BackgroundJobTerminalStatus =
  | "completed"
  | "failed"
  | "aborted"
  | "cancelled"
  | "retired"
  | "terminated";

interface BackgroundJobCompletedEvent {
  type: "background_job_completed";
  jobId: string;
  displayName: string;
  terminalStatus: BackgroundJobTerminalStatus;
  detail: string;
}

terminalStatus is the typed semantic status; detail is the human-readable description.

Stream management

interface StreamTruncatedEvent { type: "stream_truncated"; reason: StreamTruncationReason }

Transcript rewrite events

interface TranscriptRewriteCommittedEvent {
  type: "transcript_rewrite_committed";
  sessionId: string;
  record: Record<string, unknown>;
}

New inventory-known events

The inventory-known rows without handwritten parser cases listed above arrive as UnknownEvent. Inspect event.type and the raw event fields using the RPC event reference; generated wire types describe their payloads even where no ergonomic event interface is exported.

Type guard utilities

The SDK exports type guards for the most commonly used events:

import {
  isTextDelta,
  isTextComplete,
  isTurnCompleted,
  isToolCallRequested,
  isRunCompleted,
  isRunFailed,
} from "@rkat/sdk";

for await (const event of session.stream("prompt")) {
  if (isTextDelta(event)) {
    process.stdout.write(event.delta);  // TypeScript knows event.delta exists
  }
  if (isTurnCompleted(event)) {
    console.log(event.stopReason, event.usage?.inputTokens ?? "unmeasured");
  }
}

Error handling

All errors extend MeerkatError. Catch it as a base class or use the specific subclasses for targeted handling.

import { MeerkatError, CapabilityUnavailableError } from "@rkat/sdk";

try {
  await client.connect();
  const session = await client.createSession("Hello");
  await session.turn("Next");
} catch (err) {
  if (err instanceof CapabilityUnavailableError) {
    console.error("Missing capability:", err.message, err.capabilityHint);
  } else if (err instanceof MeerkatError) {
    console.error(`[${err.code}] ${err.message}`);
  }
} finally {
  await client.close();
}

Error classes

class MeerkatError extends Error {
  readonly code: string;
  readonly details?: unknown;
  readonly capabilityHint?: { capability_id: string; message: string };
}

class CapabilityUnavailableError extends MeerkatError {}
class SessionNotFoundError extends MeerkatError {}
class SkillNotFoundError extends MeerkatError {}

Class	When thrown
`MeerkatError`	Base class for all SDK errors
`CapabilityUnavailableError`	`client.requireCapability()` or `session.invokeSkill()` when the required capability is not available
`SessionNotFoundError`	Server reports that the requested session does not exist
`SkillNotFoundError`	Server reports that a skill reference cannot be resolved

Common error codes

Code	Cause
`NOT_CONNECTED`	Method called before `connect()`
`VERSION_MISMATCH`	Server contract version incompatible with SDK
`CAPABILITY_UNAVAILABLE`	Required capability not enabled in this build
`CLIENT_CLOSED`	Method called after `close()`
`STREAM_NOT_CONSUMED`	`stream.result` accessed before iteration completed
`BINARY_NOT_FOUND`	`rkat-rpc` not found and auto-download failed
`UNKNOWN_EVENT_TYPE`	Streamed event `type` not in the generated known-event inventory

Skills

Both createSession() and session.turn() accept structured skill parameters.

// Preload skills into the system prompt at session creation
const session = await client.createSession("Hello!", {
  preloadSkills: [
    { sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f", skillName: "extraction-email" },
    { sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f", skillName: "formatting-markdown" },
  ],
});

// Inject a skill for a specific turn via session.turn()
const matches = (await client.listSkills()).filter(
  (entry) => entry.is_active && entry.key.skill_name === "extraction-email",
);
const [skill] = matches;
if (!skill || matches.length !== 1) {
  throw new Error("Expected one active extraction-email skill; select a source UUID if ambiguous.");
}
const skillRef = {
  sourceUuid: skill.key.source_uuid,
  skillName: skill.key.skill_name,
};
const result = await session.turn("Extract emails from this text", {
  skillRefs: [skillRef],
});

// Convenience method on Session — wraps turn() with requireCapability check
const result2 = await session.invokeSkill(
  skillRef,
  "Extract emails from this text",
);

Discovery returns generated key.source_uuid / key.skill_name fields, which must be mapped to SkillRef’s camelCase keys. The turn examples require an installed active skill and reject ambiguous names; select the intended source UUID explicitly when multiple sources provide that name.

Version compatibility

import { CONTRACT_VERSION } from "@rkat/sdk";
console.log(CONTRACT_VERSION);  // "0.8.52"

While the major version is 0, minor versions must match exactly between SDK and server.
From 1.0.0 onwards, standard semver applies: major versions must match.

Version checking happens automatically during connect(). A MeerkatError with code VERSION_MISMATCH is thrown if versions are incompatible.

​Imports

​Additional client wrappers

​Core types

​RunResult

​Session

​DeferredSession

​LiveChannel

​Usage

​SessionInfo

​Capability

​ContentBlock

​SchemaWarning

​Skill types

​SkillKey

​SkillRef

​SkillRuntimeDiagnostics

​EventStream

​Iterating

​collect()

​collectText()

​Typed events

​AgentEvent union

​Session lifecycle events

​Turn and LLM events

​Tool execution events

​Compaction events

​Budget events

​Retry events

​Hook events

​Skill events

​Comms events

​Tool config events

​Background job events

​Stream management

​Transcript rewrite events

​New inventory-known events

​Type guard utilities

​Error handling

​Error classes

​Common error codes

​Skills

​Version compatibility

​See also

Imports

Additional client wrappers

Core types

RunResult

Session

DeferredSession

LiveChannel

Usage

SessionInfo

Capability

ContentBlock

SchemaWarning

Skill types

SkillKey

SkillRef

SkillRuntimeDiagnostics

EventStream

Iterating

collect()

collectText()

Typed events

AgentEvent union

Session lifecycle events

Turn and LLM events

Tool execution events

Compaction events

Budget events

Retry events

Hook events

Skill events

Comms events

Tool config events

Background job events

Stream management

Transcript rewrite events

New inventory-known events

Type guard utilities

Error handling

Error classes

Common error codes

Skills

Version compatibility

See also