@rkat/sdk 0.5.2 → 0.6.0

package/dist/client.js

@@ -25,9 +25,11 @@
  * ```
  */
 import { spawn } from "node:child_process";
+import { once } from "node:events";
 import { chmodSync, existsSync, mkdirSync, unlinkSync, writeFileSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { createInterface } from "node:readline";
 import { Buffer } from "node:buffer";
 import { MeerkatError, CapabilityUnavailableError } from "./generated/errors.js";
@@ -40,31 +42,143 @@ import { EventSubscription } from "./subscription.js";
 const MEERKAT_REPO = "lukacf/meerkat";
 const MEERKAT_RELEASE_BINARY = "rkat-rpc";
 const MEERKAT_BINARY_CACHE_ROOT = path.join(os.homedir(), ".cache", "meerkat", "bin", MEERKAT_RELEASE_BINARY);
+const MOB_SPAWN_MANY_FAILURE_CAUSES = new Set([
+    "profile_not_found",
+    "member_not_found",
+    "member_already_exists",
+    "not_externally_addressable",
+    "invalid_transition",
+    "wiring_error",
+    "bridge_command_rejected",
+    "member_restore_failed",
+    "kickoff_wait_timed_out",
+    "ready_wait_timed_out",
+    "definition_error",
+    "flow_not_found",
+    "flow_failed",
+    "run_not_found",
+    "run_canceled",
+    "flow_turn_timed_out",
+    "frame_depth_limit_exceeded",
+    "frame_atomic_persistence_unavailable",
+    "spec_revision_conflict",
+    "schema_validation",
+    "insufficient_targets",
+    "topology_violation",
+    "bridge_delivery_rejected",
+    "supervisor_escalation",
+    "unsupported_for_mode",
+    "reset_barrier",
+    "storage_error",
+    "session_error",
+    "comms_error",
+    "callback_pending",
+    "stale_fence_token",
+    "stale_event_cursor",
+    "work_not_found",
+    "internal",
+]);
+function isMobSpawnManyFailureCause(value) {
+    return typeof value === "string" && MOB_SPAWN_MANY_FAILURE_CAUSES.has(value);
+}
 /**
- * Normalize a SkillRef to the wire format { source_uuid, skill_name }.
- *
- * SkillKey objects are converted from camelCase to snake_case.
- * Legacy strings are parsed and emit a console warning.
+ * Normalize a structured SkillRef to the bare SkillKey wire format.
  */
-function normalizeSkillRef(ref) {
-    if (typeof ref !== "string") {
-        return { source_uuid: ref.sourceUuid, skill_name: ref.skillName };
-    }
-    const value = ref.startsWith("/") ? ref.slice(1) : ref;
-    const [sourceUuid, ...rest] = value.split("/");
-    if (!sourceUuid || rest.length === 0) {
-        throw new Error(`Invalid skill reference '${ref}'. Expected '<source_uuid>/<skill_name>'.`);
-    }
-    console.warn(`[meerkat-sdk] legacy skill reference '${ref}' is deprecated; pass { sourceUuid, skillName } instead.`);
-    return { source_uuid: sourceUuid, skill_name: rest.join("/") };
+function normalizeSkillKey(ref) {
+    if (ref === null ||
+        typeof ref !== "object" ||
+        typeof ref.sourceUuid !== "string" ||
+        typeof ref.skillName !== "string") {
+        throw new Error("Skill references must be SkillKey objects");
+    }
+    return { source_uuid: ref.sourceUuid, skill_name: ref.skillName };
 }
-function skillRefsToWire(refs) {
+function skillKeysToWire(refs) {
     if (!refs)
         return undefined;
-    return refs.map(normalizeSkillRef);
+    return refs.map(normalizeSkillKey);
+}
+function skillRefsToWire(refs) {
+    const keys = skillKeysToWire(refs);
+    return keys?.map((key) => ({ kind: "structured", ...key }));
+}
+function setIfDefined(payload, key, value) {
+    if (value !== undefined) {
+        payload[key] = value;
+    }
+}
+function mobSpawnPayload(mobId, spec) {
+    const payload = {
+        mob_id: mobId,
+        profile: spec.profile,
+        agent_identity: spec.agentIdentity,
+    };
+    setIfDefined(payload, "initial_message", spec.initialMessage);
+    setIfDefined(payload, "runtime_mode", spec.runtimeMode);
+    setIfDefined(payload, "backend", spec.backend);
+    setIfDefined(payload, "labels", spec.labels);
+    setIfDefined(payload, "context", spec.context);
+    setIfDefined(payload, "additional_instructions", spec.additionalInstructions);
+    setIfDefined(payload, "binding", spec.binding);
+    setIfDefined(payload, "shell_env", spec.shellEnv);
+    setIfDefined(payload, "auto_wire_parent", spec.autoWireParent);
+    setIfDefined(payload, "launch_mode", spec.launchMode);
+    setIfDefined(payload, "tool_access_policy", spec.toolAccessPolicy);
+    setIfDefined(payload, "budget_split_policy", spec.budgetSplitPolicy);
+    setIfDefined(payload, "inherited_tool_filter", spec.inheritedToolFilter);
+    setIfDefined(payload, "override_profile", spec.overrideProfile);
+    setIfDefined(payload, "auth_binding", spec.authBinding);
+    return payload;
+}
+function mobSpawnManySpecPayload(spec) {
+    const payload = {
+        profile: spec.profile,
+        agent_identity: spec.agentIdentity,
+    };
+    setIfDefined(payload, "initial_message", spec.initialMessage);
+    setIfDefined(payload, "runtime_mode", spec.runtimeMode);
+    setIfDefined(payload, "backend", spec.backend);
+    setIfDefined(payload, "labels", spec.labels);
+    setIfDefined(payload, "context", spec.context);
+    setIfDefined(payload, "additional_instructions", spec.additionalInstructions);
+    setIfDefined(payload, "auth_binding", spec.authBinding);
+    return payload;
+}
+function mobTurnStartPayload(mobId, agentIdentity, prompt, options) {
+    const payload = {
+        mob_id: mobId,
+        agent_identity: agentIdentity,
+        prompt: typeof prompt === "string"
+            ? prompt
+            : prompt.map((block) => ({ ...block })),
+    };
+    const wireRefs = skillRefsToWire(options?.skillRefs);
+    if (wireRefs) {
+        payload.skill_refs = wireRefs;
+    }
+    if (options?.flowToolOverlay) {
+        payload.flow_tool_overlay = {
+            allowed_tools: options.flowToolOverlay.allowedTools,
+            blocked_tools: options.flowToolOverlay.blockedTools,
+        };
+    }
+    setIfDefined(payload, "additional_instructions", options?.additionalInstructions);
+    setIfDefined(payload, "keep_alive", options?.keepAlive);
+    setIfDefined(payload, "model", options?.model);
+    setIfDefined(payload, "provider", options?.provider);
+    setIfDefined(payload, "max_tokens", options?.maxTokens);
+    setIfDefined(payload, "system_prompt", options?.systemPrompt);
+    setIfDefined(payload, "output_schema", options?.outputSchema);
+    setIfDefined(payload, "structured_output_retries", options?.structuredOutputRetries);
+    setIfDefined(payload, "provider_params", options?.providerParams);
+    setIfDefined(payload, "clear_provider_params", options?.clearProviderParams);
+    setIfDefined(payload, "auth_binding", options?.authBinding);
+    setIfDefined(payload, "clear_auth_binding", options?.clearAuthBinding);
+    return payload;
 }
 export class MeerkatClient {
     process = null;
+    processStderr = "";
     requestId = 0;
     _capabilities = [];
     _methods = new Set();
@@ -118,6 +232,31 @@ export class MeerkatClient {
         this.process = spawn(this.rkatPath, args, {
             stdio: ["pipe", "pipe", "pipe"],
         });
+        const child = this.process;
+        this.processStderr = "";
+        child.stderr?.on("data", (chunk) => {
+            this.processStderr = (this.processStderr + String(chunk)).slice(-8192);
+        });
+        child.once("error", (error) => {
+            if (this.process === child) {
+                this.process = null;
+                this.rejectPendingRequests(new MeerkatError("PROCESS_ERROR", `Failed to start ${this.rkatPath}: ${error.message}`));
+                this.closeQueues();
+            }
+        });
+        child.once("close", (code, signal) => {
+            const expectedClose = this.process !== child;
+            if (this.process === child) {
+                this.process = null;
+                this.rl?.close();
+                this.rl = null;
+            }
+            if (!expectedClose) {
+                const suffix = this.processStderr.trim() ? `: ${this.processStderr.trim()}` : "";
+                this.rejectPendingRequests(new MeerkatError("PROCESS_EXITED", `${this.rkatPath} exited before replying (code ${code ?? "null"}, signal ${signal ?? "null"})${suffix}`));
+                this.closeQueues();
+            }
+        });
         this.rl = createInterface({ input: this.process.stdout });
         this.rl.on("line", (line) => this.handleLine(line));
         // Handshake
@@ -153,14 +292,32 @@ export class MeerkatClient {
             this.rl.close();
             this.rl = null;
         }
-        if (this.process) {
-            this.process.kill();
-            this.process = null;
+        const process = this.process;
+        this.process = null;
+        if (process) {
+            process.stdin?.end();
+            const closed = once(process, "close").catch(() => []);
+            process.kill();
+            const timeout = delay(5000).then(() => "timeout");
+            const outcome = await Promise.race([closed, timeout]);
+            if (outcome === "timeout" && process.exitCode == null && process.signalCode == null) {
+                process.kill("SIGKILL");
+                await closed.catch(() => { });
+            }
+            process.stdin?.destroy();
+            process.stdout?.destroy();
+            process.stderr?.destroy();
         }
+        this.rejectPendingRequests(new MeerkatError("CLIENT_CLOSED", "Client closed"));
+        this.closeQueues();
+    }
+    rejectPendingRequests(reason) {
         for (const [, pending] of this.pendingRequests) {
-            pending.reject(new MeerkatError("CLIENT_CLOSED", "Client closed"));
+            pending.reject(reason);
         }
         this.pendingRequests.clear();
+    }
+    closeQueues() {
         for (const [, queue] of this.eventQueues) {
             queue.put(null);
         }
@@ -251,6 +408,22 @@ export class MeerkatClient {
         const raw = await this.request("session/create", params);
         return new DeferredSession(this, String(raw.session_id ?? ""), raw.session_ref != null ? String(raw.session_ref) : undefined);
     }
+    async askHelp(question, options) {
+        const params = { question };
+        if (options?.prompt !== undefined)
+            params.prompt = options.prompt;
+        if (options?.executionMode !== undefined) {
+            params.execution_mode = options.executionMode;
+        }
+        if (options?.model !== undefined)
+            params.model = options.model;
+        if (options?.provider !== undefined)
+            params.provider = options.provider;
+        if (options?.maxTokens !== undefined)
+            params.max_tokens = options.maxTokens;
+        const raw = await this.request("help/ask", params);
+        return MeerkatClient.parseRunResult(raw);
+    }
     // -- Session queries ----------------------------------------------------
     async listSessions(options) {
         const params = {};
@@ -268,13 +441,31 @@ export class MeerkatClient {
         const raw = await this.request("session/read", { session_id: sessionId });
         return MeerkatClient.parseSessionInfo(raw);
     }
-    async sendExternalEvent(sessionId, payload, options) {
-        const params = { session_id: sessionId, payload };
-        if (options?.source !== undefined) {
-            params.source = options.source;
+    async sendExternalEvent(sessionId, eventType, payload, options) {
+        const params = {
+            session_id: sessionId,
+            kind: "generic_json",
+            event_type: eventType,
+            payload,
+        };
+        if (options?.blocks !== undefined) {
+            params.blocks = options.blocks;
         }
         return this.request("session/external_event", params);
     }
+    async sendPeerResponseTerminal(sessionId, peerId, requestId, status, result, options) {
+        const params = {
+            session_id: sessionId,
+            peer_id: peerId,
+            request_id: requestId,
+            status,
+            result,
+        };
+        if (options?.displayName !== undefined) {
+            params.display_name = options.displayName;
+        }
+        return this.request("session/peer_response_terminal", params);
+    }
     async injectContext(sessionId, text, options) {
         const params = { session_id: sessionId, text };
         if (options?.source !== undefined) {
@@ -361,13 +552,6 @@ export class MeerkatClient {
         const result = await this.request("skills/list", {});
         return result.skills ?? [];
     }
-    async inspectSkill(id, options) {
-        const params = { id };
-        if (options?.source !== undefined) {
-            params.source = options.source;
-        }
-        return this.request("skills/inspect", params);
-    }
     async getBlob(blobId) {
         const result = await this.request("blob/get", { blob_id: blobId });
         return {
@@ -376,6 +560,45 @@ export class MeerkatClient {
             dataBase64: String(result.data ?? ""),
         };
     }
+    async getRuntimeHostInfo() {
+        return this.request("runtime/host_info", {});
+    }
+    async getRuntimeHostCapabilities() {
+        return this.request("runtime/capabilities", {});
+    }
+    async getRuntimeHostHealth() {
+        return this.request("runtime/health", {});
+    }
+    async requestApproval(params) {
+        return this.request("approval/request", params);
+    }
+    async listApprovals(params = {}) {
+        return this.request("approval/list", params);
+    }
+    async getApproval(params) {
+        return this.request("approval/get", params);
+    }
+    async decideApproval(params) {
+        return this.request("approval/decide", params);
+    }
+    async listArtifacts(params = {}) {
+        return this.request("artifact/list", params);
+    }
+    async getArtifact(params) {
+        return this.request("artifact/get", params);
+    }
+    async downloadArtifact(params) {
+        return this.request("artifact/download", params);
+    }
+    async latestEventCursor(params) {
+        return this.request("events/latest_cursor", params);
+    }
+    async listEventsSince(params) {
+        return this.request("events/list_since", params);
+    }
+    async eventSnapshot(params) {
+        return this.request("events/snapshot", params);
+    }
     async getModelsCatalog() {
         const result = await this.request("models/catalog", {});
         return MeerkatClient.parseModelsCatalog(result);
@@ -472,110 +695,167 @@ export class MeerkatClient {
         const status = typeof rawStatus === "string"
             ? rawStatus
             : (typeof rawStatus === "object" && rawStatus !== null
-                ? String(Object.keys(rawStatus)[0] ?? "unknown")
-                : String(rawStatus ?? "unknown"));
+                ? Object.keys(rawStatus)[0]
+                : undefined);
+        if (!status) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/status response: missing status");
+        }
         return { mobId: String(result.mob_id ?? mobId), status };
     }
     async listMobMembers(mobId) {
         const result = await this.request("mob/members", { mob_id: mobId });
         const members = result.members ?? [];
-        return members.map((member) => ({
-            meerkatId: String(member.meerkat_id ?? member.meerkatId ?? ""),
-            profile: String(member.profile_name ?? member.profile ?? ""),
-            memberRef: member.member_ref,
-            peerId: member.peer_id != null ? String(member.peer_id) : undefined,
-            externalPeerSpecs: member.external_peer_specs && typeof member.external_peer_specs === "object"
-                ? Object.fromEntries(Object.entries(member.external_peer_specs).map(([key, value]) => [key, (value ?? {})]))
-                : undefined,
-            runtimeMode: member.runtime_mode != null ? String(member.runtime_mode) : undefined,
-            state: member.state != null ? String(member.state) : undefined,
-            wiredTo: Array.isArray(member.wired_to)
-                ? member.wired_to.map((peer) => String(peer))
-                : undefined,
-            labels: member.labels && typeof member.labels === 'object'
-                ? Object.fromEntries(Object.entries(member.labels).map(([key, value]) => [key, String(value)]))
-                : undefined,
-            status: member.status != null ? String(member.status) : undefined,
-            error: member.error != null ? String(member.error) : undefined,
-            isFinal: member.is_final != null ? Boolean(member.is_final) : undefined,
-            currentSessionId: member.current_session_id != null ? String(member.current_session_id) : undefined,
-            sessionId: member.member_ref && typeof member.member_ref === 'object'
-                ? member.member_ref.session_id != null
-                    ? String(member.member_ref.session_id)
-                    : undefined
-                : undefined,
-        }));
+        return members.map((member) => {
+            const agentIdentity = String(member.agent_identity ?? "");
+            const memberRef = typeof member.member_ref === "string" && member.member_ref.length > 0
+                ? member.member_ref
+                : undefined;
+            if (!agentIdentity || !memberRef) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/members response: missing identity-native member fields");
+            }
+            return {
+                agentIdentity,
+                memberRef,
+                profile: String(member.profile_name ?? member.profile ?? member.role ?? ""),
+                peerId: member.peer_id != null ? String(member.peer_id) : undefined,
+                externalPeerSpecs: member.external_peer_specs && typeof member.external_peer_specs === "object"
+                    ? Object.fromEntries(Object.entries(member.external_peer_specs).map(([key, value]) => [key, (value ?? {})]))
+                    : undefined,
+                runtimeMode: member.runtime_mode != null ? String(member.runtime_mode) : undefined,
+                state: member.state != null ? String(member.state) : undefined,
+                wiredTo: Array.isArray(member.wired_to)
+                    ? member.wired_to.map((peer) => String(peer))
+                    : undefined,
+                labels: member.labels && typeof member.labels === "object"
+                    ? Object.fromEntries(Object.entries(member.labels).map(([key, value]) => [key, String(value)]))
+                    : undefined,
+                status: member.status != null ? String(member.status) : undefined,
+                error: member.error != null ? String(member.error) : undefined,
+                isFinal: member.is_final != null ? Boolean(member.is_final) : undefined,
+            };
+        });
     }
-    async sendMobMemberContent(mobId, meerkatId, content, options) {
+    async sendMobMemberContent(mobId, agentIdentity, content, options) {
         const result = await this.request("mob/member_send", {
             mob_id: mobId,
-            meerkat_id: meerkatId,
+            agent_identity: agentIdentity,
             content,
             handling_mode: options?.handlingMode,
             render_metadata: options?.renderMetadata,
         });
-        const sessionId = result.session_id;
-        if (typeof sessionId !== "string" || sessionId.length === 0) {
-            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/member_send response: missing session_id");
+        const memberRef = typeof result.member_ref === "string" && result.member_ref.length > 0
+            ? result.member_ref
+            : undefined;
+        if (!memberRef) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/member_send response: missing member_ref");
         }
         return {
-            memberId: typeof result.member_id === "string" && result.member_id.length > 0
-                ? result.member_id
-                : meerkatId,
-            sessionId,
+            agentIdentity: typeof result.agent_identity === "string" && result.agent_identity.length > 0
+                ? result.agent_identity
+                : agentIdentity,
+            memberRef,
             handlingMode: result.handling_mode === "steer" || result.handling_mode === "queue"
                 ? result.handling_mode
                 : (options?.handlingMode ?? "queue"),
         };
     }
     async spawnMobMember(mobId, options) {
-        return this.request("mob/spawn", {
-            mob_id: mobId,
-            profile: options.profile,
-            meerkat_id: options.meerkatId,
-            initial_message: options.initialMessage,
-            runtime_mode: options.runtimeMode,
-            backend: options.backend,
-            resume_session_id: options.resumeSessionId,
-            labels: options.labels,
-            context: options.context,
-            additional_instructions: options.additionalInstructions,
-        });
+        const result = await this.request("mob/spawn", mobSpawnPayload(mobId, options));
+        const memberRef = typeof result.member_ref === "string" && result.member_ref.length > 0
+            ? result.member_ref
+            : undefined;
+        if (!memberRef) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn response: missing member_ref");
+        }
+        return {
+            mobId: String(result.mob_id ?? mobId),
+            agentIdentity: typeof result.agent_identity === "string" && result.agent_identity.length > 0
+                ? result.agent_identity
+                : options.agentIdentity,
+            memberRef,
+        };
     }
     async spawnMobMembers(mobId, specs) {
         const result = await this.request("mob/spawn_many", {
             mob_id: mobId,
-            specs: specs.map((spec) => ({
-                profile: spec.profile,
-                meerkat_id: spec.meerkatId,
-                initial_message: spec.initialMessage,
-                runtime_mode: spec.runtimeMode,
-                backend: spec.backend,
-                resume_session_id: spec.resumeSessionId,
-                labels: spec.labels,
-                context: spec.context,
-                additional_instructions: spec.additionalInstructions,
-            })),
+            specs: specs.map(mobSpawnManySpecPayload),
+        });
+        if (!Array.isArray(result.results)) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: results must be a list");
+        }
+        const entries = result.results;
+        return entries.map((entry) => {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: malformed result entry");
+            }
+            const record = entry;
+            const entryKeys = Object.keys(record);
+            if (entryKeys.some((key) => key !== "status" && key !== "result") ||
+                "ok" in record ||
+                "error" in record ||
+                "agent_identity" in record ||
+                "member_ref" in record) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: legacy result carrier fields are not allowed");
+            }
+            const status = record.status;
+            const rawResult = record.result;
+            if (status !== "spawned" && status !== "failed") {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: invalid result status");
+            }
+            if (!rawResult || typeof rawResult !== "object" || Array.isArray(rawResult)) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: missing result payload");
+            }
+            const resultRecord = rawResult;
+            if (status === "spawned") {
+                if (Object.keys(resultRecord).some((key) => key !== "agent_identity" && key !== "member_ref")) {
+                    throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: spawned result has unknown fields");
+                }
+                const agentIdentity = resultRecord.agent_identity;
+                const memberRef = resultRecord.member_ref;
+                if (typeof agentIdentity !== "string" || agentIdentity.length === 0) {
+                    throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: spawned result missing agent_identity");
+                }
+                if (typeof memberRef !== "string" || memberRef.length === 0) {
+                    throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: spawned result missing member_ref");
+                }
+                return {
+                    status,
+                    result: {
+                        agent_identity: agentIdentity,
+                        member_ref: memberRef,
+                    },
+                };
+            }
+            if (Object.keys(resultRecord).some((key) => key !== "cause" && key !== "message")) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: failed result has unknown fields");
+            }
+            const cause = resultRecord.cause;
+            if (!isMobSpawnManyFailureCause(cause)) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: failed result has invalid cause");
+            }
+            const message = resultRecord.message;
+            if (typeof message !== "string" || message.length === 0) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_many response: failed result missing message");
+            }
+            return {
+                status,
+                result: {
+                    cause,
+                    message,
+                },
+            };
         });
-        const entries = Array.isArray(result.results)
-            ? result.results
-            : [];
-        return entries.map((entry) => ({
-            ok: Boolean(entry.ok),
-            memberRef: entry.member_ref && typeof entry.member_ref === "object"
-                ? entry.member_ref
-                : undefined,
-            sessionId: entry.session_id != null ? String(entry.session_id) : undefined,
-            error: entry.error != null ? String(entry.error) : undefined,
-        }));
     }
-    async retireMobMember(mobId, meerkatId) {
-        await this.request("mob/retire", { mob_id: mobId, meerkat_id: meerkatId });
+    async retireMobMember(mobId, agentIdentity) {
+        await this.request("mob/retire", {
+            mob_id: mobId,
+            agent_identity: agentIdentity,
+        });
     }
-    async respawnMobMember(mobId, meerkatId, initialMessage) {
+    async respawnMobMember(mobId, agentIdentity, initialMessage) {
         const result = await this.request("mob/respawn", {
             mob_id: mobId,
-            meerkat_id: meerkatId,
+            agent_identity: agentIdentity,
             initial_message: initialMessage,
         });
         const status = String(result.status ?? "completed");
@@ -586,21 +866,35 @@ export class MeerkatClient {
         if (!receipt || typeof receipt !== "object") {
             throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/respawn response: missing receipt");
         }
+        const memberRef = typeof receipt.member_ref === "string" && receipt.member_ref.length > 0
+            ? receipt.member_ref
+            : undefined;
+        if (!memberRef) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/respawn response: receipt missing member_ref");
+        }
         return {
             status: status === "topology_restore_failed" ? "topology_restore_failed" : "completed",
             receipt: {
-                memberId: String(receipt.member_id ?? meerkatId),
-                oldSessionId: receipt.old_session_id != null ? String(receipt.old_session_id) : undefined,
-                newSessionId: receipt.new_session_id != null ? String(receipt.new_session_id) : undefined,
+                agentIdentity: receipt.identity != null ? String(receipt.identity) : agentIdentity,
+                memberRef,
             },
             failedPeerIds: rawFailed.map((peerId) => String(peerId)),
         };
     }
-    async forceCancelMobMember(mobId, meerkatId) {
-        await this.request("mob/force_cancel", { mob_id: mobId, meerkat_id: meerkatId });
+    async forceCancelMobMember(mobId, agentIdentity) {
+        await this.request("mob/force_cancel", {
+            mob_id: mobId,
+            agent_identity: agentIdentity,
+        });
     }
-    async mobMemberStatus(mobId, meerkatId) {
-        const result = await this.request("mob/member_status", { mob_id: mobId, meerkat_id: meerkatId });
+    async mobTurnStart(mobId, agentIdentity, prompt, options) {
+        return await this.request("mob/turn_start", mobTurnStartPayload(mobId, agentIdentity, prompt, options));
+    }
+    async mobMemberStatus(mobId, agentIdentity) {
+        const result = await this.request("mob/member_status", {
+            mob_id: mobId,
+            agent_identity: agentIdentity,
+        });
         const rawConnectivity = result.peer_connectivity && typeof result.peer_connectivity === "object"
             ? result.peer_connectivity
             : undefined;
@@ -610,7 +904,9 @@ export class MeerkatClient {
             error: result.error != null ? String(result.error) : undefined,
             tokensUsed: Number(result.tokens_used ?? 0),
             isFinal: Boolean(result.is_final),
-            currentSessionId: result.current_session_id != null ? String(result.current_session_id) : undefined,
+            liveAttachmentStatus: typeof result.realtime_attachment_status === "string"
+                ? result.realtime_attachment_status
+                : undefined,
             peerConnectivity: rawConnectivity
                 ? {
                     reachablePeerCount: Number(rawConnectivity.reachable_peer_count ?? 0),
@@ -626,8 +922,94 @@ export class MeerkatClient {
                         : [],
                 }
                 : undefined,
+            currentSessionId: typeof result.current_session_id === "string" && result.current_session_id.length > 0
+                ? result.current_session_id
+                : undefined,
+        };
+    }
+    /**
+     * Point-in-time aggregate of a mob's status plus its member list.
+     * Wraps the `mob/snapshot` RPC (DELETE_ME C2).
+     */
+    async mobSnapshot(mobId) {
+        const result = await this.request("mob/snapshot", { mob_id: mobId });
+        return {
+            mobId: String(result.mob_id ?? mobId),
+            status: String(result.status ?? "unknown"),
+            members: Array.isArray(result.members) ? result.members : [],
+        };
+    }
+    /**
+     * Destroy a mob and surface the structured `MobDestroyReport`.
+     * Wraps the `mob/destroy` RPC (DELETE_ME C3). Unlike `mob/lifecycle`
+     * with `action: "destroy"`, this dedicated endpoint has a predictable
+     * response shape that does not require branching on an action string.
+     */
+    async mobDestroy(mobId) {
+        const result = await this.request("mob/destroy", { mob_id: mobId });
+        const report = result.destroy_report && typeof result.destroy_report === "object"
+            ? result.destroy_report
+            : {};
+        return {
+            mobId: String(result.mob_id ?? mobId),
+            ok: Boolean(result.ok ?? false),
+            destroyReport: report,
+        };
+    }
+    /**
+     * Rotate the supervisor bridge for all members of a mob.
+     * Wraps the `mob/rotate_supervisor` RPC (DELETE_ME C10). Returns the
+     * full `SupervisorRotationReport` so operators can inspect per-member
+     * rotation outcomes instead of getting a bare `ok: true`.
+     */
+    async mobRotateSupervisor(mobId) {
+        const result = await this.request("mob/rotate_supervisor", { mob_id: mobId });
+        return result;
+    }
+    /**
+     * Submit a unit of work to a mob member through the work lane.
+     * Wraps the `mob/submit_work` RPC (DELETE_ME C4). Work lane was
+     * Rust-only prior to this; `origin` is `"external"` for
+     * user-originated turns and `"internal"` for mob-orchestration work.
+     * When `workRef` is omitted the server generates a fresh UUID.
+     */
+    async mobSubmitWork(args) {
+        const params = {
+            member_ref: args.memberRef,
+            content: args.content,
+            origin: args.origin ?? "external",
+        };
+        if (args.workRef !== undefined) {
+            params.work_ref = args.workRef;
+        }
+        const result = await this.request("mob/submit_work", params);
+        return {
+            mobId: String(result.mob_id ?? ""),
+            workRef: String(result.work_ref ?? ""),
+            memberRef: String(result.member_ref ?? args.memberRef),
         };
     }
+    /**
+     * Cancel a previously submitted unit of work.
+     * Wraps the `mob/cancel_work` RPC (DELETE_ME C4).
+     */
+    async mobCancelWork(mobId, workRef) {
+        const result = await this.request("mob/cancel_work", {
+            mob_id: mobId,
+            work_ref: workRef,
+        });
+        return { ok: Boolean(result.ok ?? false) };
+    }
+    /**
+     * Cancel all in-flight work for a specific mob member.
+     * Wraps the `mob/cancel_all_work` RPC (DELETE_ME C4).
+     */
+    async mobCancelAllWork(args) {
+        const result = await this.request("mob/cancel_all_work", {
+            member_ref: args.memberRef,
+        });
+        return { ok: Boolean(result.ok ?? false) };
+    }
     async waitMobKickoff(mobId, options) {
         const params = { mob_id: mobId };
         if (options?.memberIds !== undefined) {
@@ -640,17 +1022,70 @@ export class MeerkatClient {
         const members = Array.isArray(result.members) ? result.members : [];
         return members.map((entry) => {
             const member = entry && typeof entry === "object" ? entry : {};
+            const agentIdentity = String(member.agent_identity ?? "");
+            if (!agentIdentity) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/wait_kickoff response: member missing agent_identity");
+            }
+            const status = MeerkatClient.requireStringField(member, "status", "Invalid mob/wait_kickoff response");
+            const tokensUsed = MeerkatClient.requireNumberField(member, "tokens_used", "Invalid mob/wait_kickoff response");
+            const isFinal = MeerkatClient.requireBooleanField(member, "is_final", "Invalid mob/wait_kickoff response");
+            const rawConnectivity = member.peer_connectivity && typeof member.peer_connectivity === "object"
+                ? member.peer_connectivity
+                : undefined;
+            return {
+                agentIdentity,
+                status,
+                outputPreview: member.output_preview != null ? String(member.output_preview) : undefined,
+                error: member.error != null ? String(member.error) : undefined,
+                tokensUsed,
+                isFinal,
+                peerConnectivity: rawConnectivity
+                    ? {
+                        reachablePeerCount: Number(rawConnectivity.reachable_peer_count ?? 0),
+                        unknownPeerCount: Number(rawConnectivity.unknown_peer_count ?? 0),
+                        unreachablePeers: Array.isArray(rawConnectivity.unreachable_peers)
+                            ? rawConnectivity.unreachable_peers.map((peer) => {
+                                const rawPeer = peer && typeof peer === "object" ? peer : {};
+                                return {
+                                    peer: String(rawPeer.peer ?? ""),
+                                    reason: rawPeer.reason != null ? String(rawPeer.reason) : undefined,
+                                };
+                            })
+                            : [],
+                    }
+                    : undefined,
+            };
+        });
+    }
+    async waitMobReady(mobId, options) {
+        const params = { mob_id: mobId };
+        if (options?.memberIds !== undefined) {
+            params.member_ids = options.memberIds;
+        }
+        if (options?.timeoutMs !== undefined) {
+            params.timeout_ms = options.timeoutMs;
+        }
+        const result = await this.request("mob/wait_ready", params);
+        const members = Array.isArray(result.members) ? result.members : [];
+        return members.map((entry) => {
+            const member = entry && typeof entry === "object" ? entry : {};
+            const agentIdentity = String(member.agent_identity ?? "");
+            if (!agentIdentity) {
+                throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/wait_ready response: member missing agent_identity");
+            }
+            const status = MeerkatClient.requireStringField(member, "status", "Invalid mob/wait_ready response");
+            const tokensUsed = MeerkatClient.requireNumberField(member, "tokens_used", "Invalid mob/wait_ready response");
+            const isFinal = MeerkatClient.requireBooleanField(member, "is_final", "Invalid mob/wait_ready response");
             const rawConnectivity = member.peer_connectivity && typeof member.peer_connectivity === "object"
                 ? member.peer_connectivity
                 : undefined;
             return {
-                meerkatId: String(member.meerkat_id ?? ""),
-                status: String(member.status ?? "unknown"),
+                agentIdentity,
+                status,
                 outputPreview: member.output_preview != null ? String(member.output_preview) : undefined,
                 error: member.error != null ? String(member.error) : undefined,
-                tokensUsed: Number(member.tokens_used ?? 0),
-                isFinal: Boolean(member.is_final),
-                currentSessionId: member.current_session_id != null ? String(member.current_session_id) : undefined,
+                tokensUsed,
+                isFinal,
                 peerConnectivity: rawConnectivity
                     ? {
                         reachablePeerCount: Number(rawConnectivity.reachable_peer_count ?? 0),
@@ -672,20 +1107,36 @@ export class MeerkatClient {
     async wait_mob_kickoff(mobId, options) {
         return this.waitMobKickoff(mobId, options);
     }
+    async wait_mob_ready(mobId, options) {
+        return this.waitMobReady(mobId, options);
+    }
     async spawnMobHelper(mobId, prompt, options) {
         const roleName = options?.roleName ?? options?.profileName;
         const result = await this.request("mob/spawn_helper", {
             mob_id: mobId,
             prompt,
-            meerkat_id: options?.meerkatId,
+            agent_identity: options?.agentIdentity,
             role_name: roleName,
             runtime_mode: options?.runtimeMode,
             backend: options?.backend,
         });
+        const resultIdentity = typeof result.agent_identity === "string" && result.agent_identity.length > 0
+            ? result.agent_identity
+            : options?.agentIdentity;
+        if (!resultIdentity) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_helper response: missing agent identity");
+        }
+        const memberRef = typeof result.member_ref === "string" && result.member_ref.length > 0
+            ? result.member_ref
+            : undefined;
+        if (!memberRef) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/spawn_helper response: missing member_ref");
+        }
         return {
             output: result.output != null ? String(result.output) : undefined,
             tokensUsed: Number(result.tokens_used ?? 0),
-            sessionId: result.session_id != null ? String(result.session_id) : undefined,
+            agentIdentity: resultIdentity,
+            memberRef,
         };
     }
     async forkMobHelper(mobId, sourceMemberId, prompt, options) {
@@ -694,16 +1145,29 @@ export class MeerkatClient {
             mob_id: mobId,
             source_member_id: sourceMemberId,
             prompt,
-            meerkat_id: options?.meerkatId,
+            agent_identity: options?.agentIdentity,
             role_name: roleName,
             fork_context: options?.forkContext,
             runtime_mode: options?.runtimeMode,
             backend: options?.backend,
         });
+        const resultIdentity = typeof result.agent_identity === "string" && result.agent_identity.length > 0
+            ? result.agent_identity
+            : options?.agentIdentity;
+        if (!resultIdentity) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/fork_helper response: missing agent identity");
+        }
+        const memberRef = typeof result.member_ref === "string" && result.member_ref.length > 0
+            ? result.member_ref
+            : undefined;
+        if (!memberRef) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/fork_helper response: missing member_ref");
+        }
         return {
             output: result.output != null ? String(result.output) : undefined,
             tokensUsed: Number(result.tokens_used ?? 0),
-            sessionId: result.session_id != null ? String(result.session_id) : undefined,
+            agentIdentity: resultIdentity,
+            memberRef,
         };
     }
     async wireMobMembers(mobId, member, peer) {
@@ -721,10 +1185,10 @@ export class MeerkatClient {
     async mobLifecycle(mobId, action) {
         await this.request("mob/lifecycle", { mob_id: mobId, action });
     }
-    async appendMobSystemContext(mobId, meerkatId, text, options) {
+    async appendMobSystemContext(mobId, agentIdentity, text, options) {
         return this.request("mob/append_system_context", {
             mob_id: mobId,
-            meerkat_id: meerkatId,
+            agent_identity: agentIdentity,
             text,
             source: options?.source,
             idempotency_key: options?.idempotencyKey,
@@ -744,6 +1208,9 @@ export class MeerkatClient {
             : [];
         return { events };
     }
+    async mobIngressInteraction(params) {
+        return this.request("mob/ingress_interaction", params);
+    }
     async createMobProfile(name, profile) {
         const raw = await this.request("mob/profile/create", {
             name,
@@ -798,8 +1265,8 @@ export class MeerkatClient {
     async subscribeMobEvents(mobId) {
         return this.openEventSubscription("mob/stream_open", { mob_id: mobId }, "mob/stream_close", MeerkatClient.parseAttributedMobEvent);
     }
-    async subscribeMobMemberEvents(mobId, meerkatId) {
-        return this.openEventSubscription("mob/stream_open", { mob_id: mobId, member_id: meerkatId }, "mob/stream_close", MeerkatClient.parseAgentEventEnvelope);
+    async subscribeMobMemberEvents(mobId, agentIdentity) {
+        return this.openEventSubscription("mob/stream_open", { mob_id: mobId, agent_identity: agentIdentity }, "mob/stream_close", MeerkatClient.parseAgentEventEnvelope);
     }
     async openEventSubscription(openMethod, params, closeMethod, parse) {
         const result = this.process?.stdin
@@ -838,14 +1305,59 @@ export class MeerkatClient {
         });
     }
     static parseAgentEventEnvelope(raw) {
+        const eventId = MeerkatClient.parseOptionalString(raw.event_id ?? raw.eventId);
+        const source = MeerkatClient.parseEventSourceIdentity(raw.source);
+        const sourceId = MeerkatClient.parseOptionalString(raw.source_id ?? raw.sourceId);
+        const seq = MeerkatClient.parseOptionalNumber(raw.seq);
+        const timestampMs = MeerkatClient.parseOptionalNumber(raw.timestamp_ms ?? raw.timestampMs);
+        const payloadRaw = raw.payload;
+        const payload = payloadRaw && typeof payloadRaw === "object"
+            ? parseCoreEvent(payloadRaw)
+            : undefined;
         return {
-            eventId: String(raw.event_id ?? raw.eventId ?? ""),
-            sourceId: String(raw.source_id ?? raw.sourceId ?? ""),
-            seq: Number(raw.seq ?? 0),
-            timestampMs: Number(raw.timestamp_ms ?? raw.timestampMs ?? 0),
-            payload: parseCoreEvent((raw.payload ?? {})),
+            ...(eventId != null ? { eventId } : {}),
+            ...(source != null ? { source } : {}),
+            ...(sourceId != null ? { sourceId } : {}),
+            ...(seq != null ? { seq } : {}),
+            ...(timestampMs != null ? { timestampMs } : {}),
+            ...(payload ? { payload } : {}),
         };
     }
+    static parseEventSourceIdentity(raw) {
+        if (!raw || typeof raw !== "object") {
+            return undefined;
+        }
+        const record = raw;
+        const type = MeerkatClient.parseOptionalString(record.type);
+        switch (type) {
+            case "session": {
+                const sessionId = MeerkatClient.parseOptionalString(record.session_id ?? record.sessionId);
+                return sessionId != null ? { type: "session", sessionId } : undefined;
+            }
+            case "runtime": {
+                const runtimeId = MeerkatClient.parseOptionalString(record.runtime_id ?? record.runtimeId);
+                return runtimeId != null ? { type: "runtime", runtimeId } : undefined;
+            }
+            case "interaction": {
+                const interactionId = MeerkatClient.parseOptionalString(record.interaction_id ?? record.interactionId);
+                return interactionId != null ? { type: "interaction", interactionId } : undefined;
+            }
+            case "callback":
+                return { type: "callback" };
+            case "external": {
+                const sourceId = MeerkatClient.parseOptionalString(record.source_id ?? record.sourceId);
+                return sourceId != null ? { type: "external", sourceId } : undefined;
+            }
+            default:
+                return undefined;
+        }
+    }
+    static parseOptionalString(raw) {
+        return typeof raw === "string" ? raw : undefined;
+    }
+    static parseOptionalNumber(raw) {
+        return typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+    }
     static parseAttributedMobEvent(raw) {
         return {
             source: String(raw.source ?? ""),
@@ -861,9 +1373,6 @@ export class MeerkatClient {
         if (wireRefs) {
             params.skill_refs = wireRefs;
         }
-        if (options?.skillReferences) {
-            params.skill_references = options.skillReferences;
-        }
         if (options?.flowToolOverlay) {
             params.flow_tool_overlay = {
                 allowed_tools: options.flowToolOverlay.allowedTools,
@@ -908,9 +1417,6 @@ export class MeerkatClient {
         if (wireRefs) {
             params.skill_refs = wireRefs;
         }
-        if (options?.skillReferences) {
-            params.skill_references = options.skillReferences;
-        }
         if (options?.flowToolOverlay) {
             params.flow_tool_overlay = {
                 allowed_tools: options.flowToolOverlay.allowedTools,
@@ -955,6 +1461,51 @@ export class MeerkatClient {
     async _archive(sessionId) {
         await this.request("session/archive", { session_id: sessionId });
     }
+    static retiredRuntimeSessionControlError() {
+        return new MeerkatError("METHOD_NOT_FOUND", "Retired runtime session control methods are no longer supported by the public RPC surface.");
+    }
+    /**
+     * @internal
+     * @deprecated Retired runtime/session control RPC method; always fails before transport.
+     */
+    async _runtimeStatus(_params) {
+        throw MeerkatClient.retiredRuntimeSessionControlError();
+    }
+    /**
+     * @internal
+     * @deprecated Retired runtime/session control RPC method; always fails before transport.
+     */
+    async _runtimeSubmit(_params) {
+        throw MeerkatClient.retiredRuntimeSessionControlError();
+    }
+    /**
+     * @internal
+     * @deprecated Retired runtime/session control RPC method; always fails before transport.
+     */
+    async _runtimeSubmission(_params) {
+        throw MeerkatClient.retiredRuntimeSessionControlError();
+    }
+    /**
+     * @internal
+     * @deprecated Retired runtime/session control RPC method; always fails before transport.
+     */
+    async _runtimeSubmissions(_params) {
+        throw MeerkatClient.retiredRuntimeSessionControlError();
+    }
+    /**
+     * @internal
+     * @deprecated Retired runtime/session control RPC method; always fails before transport.
+     */
+    async _runtimeRetire(_params) {
+        throw MeerkatClient.retiredRuntimeSessionControlError();
+    }
+    /**
+     * @internal
+     * @deprecated Retired runtime/session control RPC method; always fails before transport.
+     */
+    async _runtimeReset(_params) {
+        throw MeerkatClient.retiredRuntimeSessionControlError();
+    }
     /** @internal */
     async _send(sessionId, command) {
         return this.send(sessionId, command);
@@ -963,6 +1514,11 @@ export class MeerkatClient {
     async _peers(sessionId) {
         return this.peers(sessionId);
     }
+    /**
+     * Send a typed comms command. Invalid discriminators (`source`, `stream`,
+     * `handling_mode`, `status`) are rejected at the server's typed-serde
+     * boundary.
+     */
     async send(sessionId, command) {
         const result = await this.request("comms/send", { session_id: sessionId, ...command });
         return MeerkatClient.parseCommsSendReceipt(result);
@@ -970,51 +1526,126 @@ export class MeerkatClient {
     async peers(sessionId) {
         return this.request("comms/peers", { session_id: sessionId });
     }
-    async runtimeState(sessionId) {
-        const result = await this.request("runtime/state", { session_id: sessionId });
-        if (typeof result.state !== "string" || result.state.length === 0) {
-            throw new MeerkatError("INVALID_RESPONSE", "Invalid runtime/state response: missing state");
+    async runtimeRealtimeAttachmentStatus(sessionId) {
+        const result = await this.request("session/realtime_attachment_status", {
+            session_id: sessionId,
+        });
+        if (typeof result.status !== "string" || result.status.length === 0) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid session/realtime_attachment_status response: missing status");
         }
         return result;
     }
-    async runtimeAccept(sessionId, input) {
-        const result = await this.request("runtime/accept", { session_id: sessionId, input });
-        if (typeof result.outcome_type !== "string" || result.outcome_type.length === 0) {
-            throw new MeerkatError("INVALID_RESPONSE", "Invalid runtime/accept response: missing outcome_type");
-        }
-        return result;
+    /** Idempotent spawn: spawns or returns the existing member entry. */
+    async mobEnsureMember(mobId, spec) {
+        return await this.request("mob/ensure_member", {
+            mob_id: mobId,
+            spec,
+        });
     }
-    async runtimeRetire(sessionId) {
-        const result = await this.request("runtime/retire", { session_id: sessionId });
-        if (typeof result.inputs_abandoned !== "number") {
-            throw new MeerkatError("INVALID_RESPONSE", "Invalid runtime/retire response: missing inputs_abandoned");
+    /** Declarative reconcile: converge roster to the desired spec list. */
+    async mobReconcile(mobId, desired, options) {
+        const params = { mob_id: mobId, desired };
+        if (options !== undefined)
+            params.options = options;
+        return await this.request("mob/reconcile", params);
+    }
+    /** Label-filtered member listing. */
+    async mobListMembersMatching(mobId, filter) {
+        return await this.request("mob/list_members_matching", {
+            mob_id: mobId,
+            filter,
+        });
+    }
+    async realtimeOpenInfo(request) {
+        const result = await this.request("realtime/open_info", request);
+        if (typeof result.ws_url !== "string" || result.ws_url.length === 0) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid realtime/open_info response: missing ws_url");
         }
         return result;
     }
-    async runtimeReset(sessionId) {
-        const result = await this.request("runtime/reset", { session_id: sessionId });
-        if (typeof result.inputs_abandoned !== "number") {
-            throw new MeerkatError("INVALID_RESPONSE", "Invalid runtime/reset response: missing inputs_abandoned");
+    async realtimeStatus(params) {
+        const result = await this.request("realtime/status", params);
+        if (typeof result.status !== "object" || result.status === null) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid realtime/status response: missing status");
         }
         return result;
     }
-    async inputState(sessionId, inputId) {
-        const result = await this.request("input/state", { session_id: sessionId, input_id: inputId });
-        if (result === null) {
-            return null;
-        }
-        if (typeof result !== "object" || result === null) {
-            throw new MeerkatError("INVALID_RESPONSE", "Invalid input/state response: expected object or null");
+    async realtimeCapabilities(params) {
+        const result = await this.request("realtime/capabilities", params);
+        if (typeof result.capabilities !== "object" || result.capabilities === null) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid realtime/capabilities response: missing capabilities");
         }
         return result;
     }
-    async inputList(sessionId) {
-        const result = (await this.request("input/list", {
-            session_id: sessionId,
-        }));
-        return Array.isArray(result.input_ids)
-            ? result.input_ids.map((inputId) => String(inputId))
-            : [];
+    // -- Auth + realm (Phase 4d) --------------------------------------------
+    //
+    // These wrappers cover the RPC catalog's auth/* and realm/* methods.
+    // Write-side methods (auth/profile/create, delete, login/start,
+    // login/complete, login/device_start, logout) are currently server-stubbed
+    // with typed INVALID_REQUEST pointing to the CLI; the wrappers surface
+    // whatever the server returns so they stay honest about the state.
+    async realmList() {
+        return this.request("realm/list", {});
+    }
+    async realmGet(realmId) {
+        return this.request("realm/get", { realm_id: realmId });
+    }
+    async authProfileList(realmId) {
+        return this.request("auth/profile/list", { realm_id: realmId });
+    }
+    async authProfileGet(realmId, bindingId, profileId) {
+        const params = {
+            realm_id: realmId,
+            binding_id: bindingId,
+        };
+        if (profileId)
+            params.profile_id = profileId;
+        return this.request("auth/profile/get", params);
+    }
+    async authProfileCreate(params) {
+        return this.request("auth/profile/create", params);
+    }
+    async authProfileDelete(realmId, bindingId, profileId) {
+        const params = {
+            realm_id: realmId,
+            binding_id: bindingId,
+        };
+        if (profileId)
+            params.profile_id = profileId;
+        return this.request("auth/profile/delete", params);
+    }
+    async authLoginStart(params) {
+        return this.request("auth/login/start", params);
+    }
+    async authLoginComplete(params) {
+        return this.request("auth/login/complete", params);
+    }
+    async authLoginDeviceStart(params) {
+        return this.request("auth/login/device_start", params);
+    }
+    async authLoginDeviceComplete(params) {
+        return this.request("auth/login/device_complete", params);
+    }
+    async authLoginProvisionApiKey(params) {
+        return this.request("auth/login/provision_api_key", params);
+    }
+    async authStatusGet(realmId, bindingId, profileId) {
+        const params = {
+            realm_id: realmId,
+            binding_id: bindingId,
+        };
+        if (profileId !== undefined)
+            params.profile_id = profileId;
+        return this.request("auth/status/get", params);
+    }
+    async authLogout(realmId, bindingId, profileId) {
+        const params = {
+            realm_id: realmId,
+            binding_id: bindingId,
+        };
+        if (profileId !== undefined)
+            params.profile_id = profileId;
+        return this.request("auth/logout", params);
     }
     // -- Transport ----------------------------------------------------------
     handleLine(line) {
@@ -1155,6 +1786,33 @@ export class MeerkatClient {
         }
         return String(raw);
     }
+    static requireRecord(raw, field, context) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new MeerkatError("INVALID_RESPONSE", `${context}: missing ${field}`);
+        }
+        return raw;
+    }
+    static requireStringField(raw, field, context) {
+        const value = raw[field];
+        if (typeof value !== "string" || value.length === 0) {
+            throw new MeerkatError("INVALID_RESPONSE", `${context}: missing ${field}`);
+        }
+        return value;
+    }
+    static requireNumberField(raw, field, context, displayField = field) {
+        const value = raw[field];
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw new MeerkatError("INVALID_RESPONSE", `${context}: ${displayField} must be number`);
+        }
+        return value;
+    }
+    static requireBooleanField(raw, field, context) {
+        const value = raw[field];
+        if (typeof value !== "boolean") {
+            throw new MeerkatError("INVALID_RESPONSE", `${context}: ${field} must be boolean`);
+        }
+        return value;
+    }
     static parseSkillDiagnostics(raw) {
         if (!raw || typeof raw !== "object")
             return undefined;
@@ -1200,15 +1858,16 @@ export class MeerkatClient {
         }
     }
     static parseRunResult(data) {
-        const usageRaw = data.usage;
+        const context = "Invalid run result";
+        const usageRaw = MeerkatClient.requireRecord(data.usage, "usage", context);
         const usage = {
-            inputTokens: Number(usageRaw?.input_tokens ?? 0),
-            outputTokens: Number(usageRaw?.output_tokens ?? 0),
+            inputTokens: MeerkatClient.requireNumberField(usageRaw, "input_tokens", context, "usage.input_tokens"),
+            outputTokens: MeerkatClient.requireNumberField(usageRaw, "output_tokens", context, "usage.output_tokens"),
             cacheCreationTokens: usageRaw?.cache_creation_tokens != null
-                ? Number(usageRaw.cache_creation_tokens)
+                ? MeerkatClient.requireNumberField(usageRaw, "cache_creation_tokens", context, "usage.cache_creation_tokens")
                 : undefined,
             cacheReadTokens: usageRaw?.cache_read_tokens != null
-                ? Number(usageRaw.cache_read_tokens)
+                ? MeerkatClient.requireNumberField(usageRaw, "cache_read_tokens", context, "usage.cache_read_tokens")
                 : undefined,
         };
         const rawWarnings = data.schema_warnings;
@@ -1217,14 +1876,26 @@ export class MeerkatClient {
             path: String(w.path ?? ""),
             message: String(w.message ?? ""),
         }));
+        const rawExtractionError = data.extraction_error;
+        const extractionError = rawExtractionError && typeof rawExtractionError === "object"
+            ? {
+                lastOutput: String(rawExtractionError.last_output ?? ""),
+                attempts: MeerkatClient.requireNumberField(rawExtractionError, "attempts", context, "extraction_error.attempts"),
+                reason: String(rawExtractionError.reason ?? ""),
+            }
+            : undefined;
         return {
             sessionId: String(data.session_id ?? ""),
             sessionRef: data.session_ref != null ? String(data.session_ref) : undefined,
             text: String(data.text ?? ""),
-            turns: Number(data.turns ?? 0),
-            toolCalls: Number(data.tool_calls ?? 0),
+            turns: MeerkatClient.requireNumberField(data, "turns", context),
+            toolCalls: MeerkatClient.requireNumberField(data, "tool_calls", context),
             usage,
+            terminalCauseKind: typeof data.terminal_cause_kind === "string"
+                ? data.terminal_cause_kind
+                : undefined,
             structuredOutput: data.structured_output,
+            extractionError,
             schemaWarnings,
             skillDiagnostics: MeerkatClient.parseSkillDiagnostics(data.skill_diagnostics),
         };
@@ -1487,6 +2158,7 @@ export class MeerkatClient {
             : [];
         return {
             role,
+            createdAt: String(data.created_at ?? ""),
             content: contentValue != null ? MeerkatClient.parseContentInput(contentValue) : undefined,
             toolCalls: rawToolCalls.map((toolCall) => ({
                 id: String(toolCall.id ?? ""),
@@ -1545,12 +2217,22 @@ export class MeerkatClient {
     }
     static parseSessionAssistantBlock(data) {
         const blockData = data.data ?? {};
+        const blobRef = blockData.blob_ref;
+        const revisedPrompt = blockData.revised_prompt != null && typeof blockData.revised_prompt === "object"
+            ? blockData.revised_prompt
+            : undefined;
         return {
             blockType: String(data.block_type ?? ""),
             text: blockData.text != null ? String(blockData.text) : undefined,
             id: blockData.id != null ? String(blockData.id) : undefined,
             name: blockData.name != null ? String(blockData.name) : undefined,
             args: blockData.args,
+            imageId: blockData.image_id != null ? String(blockData.image_id) : undefined,
+            blobId: blobRef?.blob_id != null ? String(blobRef.blob_id) : undefined,
+            mediaType: blockData.media_type != null ? String(blockData.media_type) : undefined,
+            width: blockData.width != null ? Number(blockData.width) : undefined,
+            height: blockData.height != null ? Number(blockData.height) : undefined,
+            revisedPrompt,
             meta: blockData.meta,
         };
     }
@@ -1652,13 +2334,12 @@ export class MeerkatClient {
             params.budget_limits = options.budgetLimits;
         if (options.providerParams != null)
             params.provider_params = options.providerParams;
-        if (options.preloadSkills != null)
-            params.preload_skills = options.preloadSkills;
+        if (options.preloadSkills != null) {
+            params.preload_skills = skillKeysToWire(options.preloadSkills);
+        }
         const wireRefs = skillRefsToWire(options.skillRefs);
         if (wireRefs)
             params.skill_refs = wireRefs;
-        if (options.skillReferences != null)
-            params.skill_references = options.skillReferences;
         if (options.labels != null)
             params.labels = options.labels;
         if (options.additionalInstructions != null) {
@@ -1830,9 +2511,9 @@ export class MeerkatClient {
     static buildArgs(legacy, options) {
         if (legacy)
             return ["rpc"];
+        const args = ["--realtime-ws", "127.0.0.1:0"];
         if (!options)
-            return [];
-        const args = [];
+            return args;
         if (options.isolated)
             args.push("--isolated");
         if (options.realmId)