@rkat/sdk 0.4.13 → 0.5.0

package/dist/client.js

@@ -29,10 +29,11 @@ import { chmodSync, existsSync, mkdirSync, unlinkSync, writeFileSync, } from "no
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline";
+import { Buffer } from "node:buffer";
 import { MeerkatError, CapabilityUnavailableError } from "./generated/errors.js";
 import { CONTRACT_VERSION, } from "./generated/types.js";
 import { DeferredSession, Session } from "./session.js";
-import { Mob } from "./mob.js";
+import { Mob, } from "./mob.js";
 import { parseCoreEvent } from "./events.js";
 import { EventStream, AsyncQueue } from "./streaming.js";
 import { EventSubscription } from "./subscription.js";
@@ -347,6 +348,14 @@ export class MeerkatClient {
         }
         return this.request("skills/inspect", params);
     }
+    async getBlob(blobId) {
+        const result = await this.request("blob/get", { blob_id: blobId });
+        return {
+            blobId: String(result.blob_id ?? blobId),
+            mediaType: String(result.media_type ?? ""),
+            dataBase64: String(result.data ?? ""),
+        };
+    }
     async listMobPrefabs() {
         const result = await this.request("mob/prefabs", {});
         return result.prefabs ?? [];
@@ -401,6 +410,10 @@ export class MeerkatClient {
             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)
@@ -409,6 +422,10 @@ export class MeerkatClient {
             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)
@@ -434,19 +451,169 @@ export class MeerkatClient {
         await this.request("mob/retire", { mob_id: mobId, meerkat_id: meerkatId });
     }
     async respawnMobMember(mobId, meerkatId, initialMessage) {
-        await this.request("mob/respawn", { mob_id: mobId, meerkat_id: meerkatId, initial_message: initialMessage });
+        const result = await this.request("mob/respawn", {
+            mob_id: mobId,
+            meerkat_id: meerkatId,
+            initial_message: initialMessage,
+        });
+        const status = String(result.status ?? "completed");
+        const rawFailed = Array.isArray(result.failed_peer_ids)
+            ? result.failed_peer_ids
+            : [];
+        const receipt = result.receipt;
+        if (!receipt || typeof receipt !== "object") {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/respawn response: missing receipt");
+        }
+        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,
+            },
+            failedPeerIds: rawFailed.map((peerId) => String(peerId)),
+        };
+    }
+    async forceCancelMobMember(mobId, meerkatId) {
+        await this.request("mob/force_cancel", { mob_id: mobId, meerkat_id: meerkatId });
+    }
+    async mobMemberStatus(mobId, meerkatId) {
+        const result = await this.request("mob/member_status", { mob_id: mobId, meerkat_id: meerkatId });
+        const rawConnectivity = result.peer_connectivity && typeof result.peer_connectivity === "object"
+            ? result.peer_connectivity
+            : undefined;
+        return {
+            status: String(result.status ?? "unknown"),
+            outputPreview: result.output_preview != null ? String(result.output_preview) : undefined,
+            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,
+            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 waitMobKickoff(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_kickoff", params);
+        const members = Array.isArray(result.members) ? result.members : [];
+        return members.map((entry) => {
+            const member = entry && typeof entry === "object" ? entry : {};
+            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"),
+                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,
+                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 wireMobMembers(mobId, a, b) {
-        await this.request("mob/wire", { mob_id: mobId, a, b });
+    async wait_mob_kickoff(mobId, options) {
+        return this.waitMobKickoff(mobId, options);
     }
-    async unwireMobMembers(mobId, a, b) {
-        await this.request("mob/unwire", { mob_id: mobId, a, b });
+    async spawnMobHelper(mobId, prompt, options) {
+        const result = await this.request("mob/spawn_helper", {
+            mob_id: mobId,
+            prompt,
+            meerkat_id: options?.meerkatId,
+            profile_name: options?.profileName,
+            runtime_mode: options?.runtimeMode,
+            backend: options?.backend,
+        });
+        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,
+        };
+    }
+    async forkMobHelper(mobId, sourceMemberId, prompt, options) {
+        const result = await this.request("mob/fork_helper", {
+            mob_id: mobId,
+            source_member_id: sourceMemberId,
+            prompt,
+            meerkat_id: options?.meerkatId,
+            profile_name: options?.profileName,
+            fork_context: options?.forkContext,
+            runtime_mode: options?.runtimeMode,
+            backend: options?.backend,
+        });
+        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,
+        };
+    }
+    async wireMobMembers(mobId, member, peer) {
+        const payload = typeof peer === "string"
+            ? { member, peer: { local: peer } }
+            : { member, peer };
+        await this.request("mob/wire", { mob_id: mobId, ...payload });
+    }
+    async unwireMobMembers(mobId, member, peer) {
+        const payload = typeof peer === "string"
+            ? { member, peer: { local: peer } }
+            : { member, peer };
+        await this.request("mob/unwire", { mob_id: mobId, ...payload });
     }
     async mobLifecycle(mobId, action) {
         await this.request("mob/lifecycle", { mob_id: mobId, action });
     }
-    async sendMobMessage(mobId, meerkatId, message) {
-        await this.request("mob/send", { mob_id: mobId, meerkat_id: meerkatId, message });
+    async sendMobMemberContent(mobId, meerkatId, content, options) {
+        const result = await this.request("mob/send", {
+            mob_id: mobId,
+            meerkat_id: meerkatId,
+            content,
+            handling_mode: options?.handlingMode ?? "queue",
+            render_metadata: options?.renderMetadata,
+        });
+        const sessionId = result.session_id;
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mob/send response: missing session_id");
+        }
+        return {
+            memberId: String(result.member_id ?? meerkatId),
+            sessionId,
+            handlingMode: String(result.handling_mode ?? options?.handlingMode ?? "queue"),
+        };
     }
     async appendMobSystemContext(mobId, meerkatId, text, options) {
         return this.request("mob/append_system_context", {
@@ -547,8 +714,8 @@ export class MeerkatClient {
                 blocked_tools: options.flowToolOverlay.blockedTools,
             };
         }
-        if (options?.hostMode != null)
-            params.host_mode = options.hostMode;
+        if (options?.keepAlive != null)
+            params.keep_alive = options.keepAlive;
         if (options?.model)
             params.model = options.model;
         if (options?.provider)
@@ -623,6 +790,52 @@ 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");
+        }
+        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;
+    }
+    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");
+        }
+        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");
+        }
+        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");
+        }
+        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))
+            : [];
+    }
     // -- Transport ----------------------------------------------------------
     handleLine(line) {
         let data;
@@ -643,7 +856,8 @@ export class MeerkatClient {
                 this.pendingRequests.delete(data.id);
                 const error = data.error;
                 if (error) {
-                    pending.reject(new MeerkatError(String(error.code ?? "UNKNOWN"), String(error.message ?? "Unknown error")));
+                    const normalized = MeerkatClient.parseRpcErrorPayload(error);
+                    pending.reject(new MeerkatError(normalized.code, normalized.message, normalized.details));
                 }
                 else {
                     pending.resolve((data.result ?? {}));
@@ -657,7 +871,7 @@ export class MeerkatClient {
                 const streamId = String(params.stream_id ?? "");
                 const queue = this.streamQueues.get(streamId);
                 const rawEvent = (params.event ?? params);
-                // Preserve scope fields when present (sub-agent / mob-member scoped events).
+                // Preserve scope fields when present (delegated-branch / mob-member scoped events).
                 const scopeId = params.scope_id;
                 const scopePath = params.scope_path;
                 const event = scopeId != null || scopePath != null
@@ -702,6 +916,38 @@ export class MeerkatClient {
             }
         }
     }
+    static parseRpcErrorPayload(error) {
+        const rawData = error.data;
+        if (typeof rawData === "object" && rawData !== null) {
+            const parsed = rawData;
+            return {
+                code: String(parsed.code ?? error.code ?? "UNKNOWN"),
+                message: String(parsed.message ?? error.message ?? "Unknown error"),
+                details: parsed.details ?? parsed.reason ?? rawData,
+            };
+        }
+        const rawMessage = error.message;
+        if (typeof rawMessage === "string") {
+            try {
+                const parsed = JSON.parse(rawMessage);
+                if (parsed && typeof parsed === "object") {
+                    return {
+                        code: String(parsed.code ?? error.code ?? "UNKNOWN"),
+                        message: String(parsed.message ?? rawMessage),
+                        details: parsed.details ?? parsed.reason ?? error.data,
+                    };
+                }
+            }
+            catch {
+                // Fall back to the outer JSON-RPC error payload.
+            }
+        }
+        return {
+            code: String(error.code ?? "UNKNOWN"),
+            message: String(rawMessage ?? "Unknown error"),
+            details: error.data,
+        };
+    }
     request(method, params) {
         if (!this.process?.stdin) {
             throw new MeerkatError("NOT_CONNECTED", "Client not connected");
@@ -829,7 +1075,7 @@ export class MeerkatClient {
             : [];
         return {
             role: String(data.role ?? ""),
-            content: data.content != null ? String(data.content) : undefined,
+            content: data.content != null ? MeerkatClient.parseContentInput(data.content) : undefined,
             toolCalls: rawToolCalls.map((toolCall) => ({
                 id: String(toolCall.id ?? ""),
                 name: String(toolCall.name ?? ""),
@@ -839,11 +1085,43 @@ export class MeerkatClient {
             blocks: rawBlocks.map((block) => MeerkatClient.parseSessionAssistantBlock(block)),
             results: rawResults.map((result) => ({
                 toolUseId: String(result.tool_use_id ?? ""),
-                content: String(result.content ?? ""),
+                content: MeerkatClient.parseContentInput(result.content),
                 isError: Boolean(result.is_error ?? false),
             })),
         };
     }
+    static parseContentInput(value) {
+        if (Array.isArray(value)) {
+            return value
+                .filter((item) => typeof item === "object" && item !== null)
+                .map((block) => MeerkatClient.parseContentBlock(block));
+        }
+        return String(value ?? "");
+    }
+    static parseContentBlock(data) {
+        const type = String(data.type ?? "");
+        if (type === "text") {
+            return { type: "text", text: String(data.text ?? "") };
+        }
+        if (type === "image") {
+            const source = String(data.source ?? "inline");
+            if (source === "blob") {
+                return {
+                    type: "image",
+                    media_type: String(data.media_type ?? ""),
+                    source: "blob",
+                    blob_id: String(data.blob_id ?? ""),
+                };
+            }
+            return {
+                type: "image",
+                media_type: String(data.media_type ?? ""),
+                source: "inline",
+                data: String(data.data ?? ""),
+            };
+        }
+        return { type: "text", text: "" };
+    }
     static parseSessionAssistantBlock(data) {
         const blockData = data.data ?? {};
         return {
@@ -928,32 +1206,30 @@ export class MeerkatClient {
             params.system_prompt = options.systemPrompt;
         if (options.maxTokens)
             params.max_tokens = options.maxTokens;
-        if (options.outputSchema)
+        if (options.outputSchema != null)
             params.output_schema = options.outputSchema;
-        if (options.structuredOutputRetries != null && options.structuredOutputRetries !== 2) {
+        if (options.structuredOutputRetries != null) {
             params.structured_output_retries = options.structuredOutputRetries;
         }
-        if (options.hooksOverride)
+        if (options.hooksOverride != null)
             params.hooks_override = options.hooksOverride;
-        if (options.enableBuiltins)
-            params.enable_builtins = true;
-        if (options.enableShell)
-            params.enable_shell = true;
-        if (options.enableSubagents)
-            params.enable_subagents = true;
-        if (options.enableMemory)
-            params.enable_memory = true;
-        if (options.enableMob)
-            params.enable_mob = true;
-        if (options.hostMode)
-            params.host_mode = true;
+        if (options.enableBuiltins != null)
+            params.enable_builtins = options.enableBuiltins;
+        if (options.enableShell != null)
+            params.enable_shell = options.enableShell;
+        if (options.enableMemory != null)
+            params.enable_memory = options.enableMemory;
+        if (options.enableMob != null)
+            params.enable_mob = options.enableMob;
+        if (options.keepAlive != null)
+            params.keep_alive = options.keepAlive;
         if (options.commsName)
             params.comms_name = options.commsName;
         if (options.peerMeta != null)
             params.peer_meta = options.peerMeta;
         if (options.budgetLimits != null)
             params.budget_limits = options.budgetLimits;
-        if (options.providerParams)
+        if (options.providerParams != null)
             params.provider_params = options.providerParams;
         if (options.preloadSkills != null)
             params.preload_skills = options.preloadSkills;
@@ -1024,7 +1300,8 @@ export class MeerkatClient {
     }
     static async runCommand(command, args) {
         return new Promise((resolve, reject) => {
-            const proc = spawn(command, args, { stdio: ["ignore", "inherit", "pipe"] });
+            const options = { stdio: ["ignore", "inherit", "pipe"] };
+            const proc = spawn(command, args, options);
             let stderr = "";
             proc.stderr?.on("data", (chunk) => { stderr += String(chunk); });
             proc.on("error", (error) => { reject(error); });