@rkat/sdk 0.4.5 → 0.4.7

package/dist/client.js

@@ -31,8 +31,11 @@ import path from "node:path";
 import { createInterface } from "node:readline";
 import { MeerkatError, CapabilityUnavailableError } from "./generated/errors.js";
 import { CONTRACT_VERSION, } from "./generated/types.js";
-import { Session } from "./session.js";
-import { CommsEventStream, EventStream, AsyncQueue } from "./streaming.js";
+import { DeferredSession, Session } from "./session.js";
+import { Mob } from "./mob.js";
+import { parseCoreEvent } from "./events.js";
+import { EventStream, AsyncQueue } from "./streaming.js";
+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);
@@ -63,17 +66,43 @@ export class MeerkatClient {
     process = null;
     requestId = 0;
     _capabilities = [];
+    _methods = new Set();
     rkatPath;
     pendingRequests = new Map();
     eventQueues = new Map();
-    commsStreamQueues = new Map();
+    streamQueues = new Map();
     pendingStreamQueue = null;
     pendingStreamRequestId = null;
     unmatchedStreamBuffer = new Map();
+    unmatchedStandaloneStreamBuffer = new Map();
+    unmatchedStandaloneStreamEnd = new Map();
+    streamTerminalOutcomes = new Map();
     rl = null;
+    toolHandlers = new Map();
     constructor(rkatPath = "rkat-rpc") {
         this.rkatPath = rkatPath;
     }
+    /**
+     * Register a callback tool handler.
+     *
+     * @example
+     * ```ts
+     * client.registerTool("search", "Search the web", { type: "object" }, async (args) => {
+     *   return `Results for ${args.q}`;
+     * });
+     * ```
+     */
+    registerTool(name, description, inputSchema, handler) {
+        this.toolHandlers.set(name, { description, inputSchema, handler });
+        // If already connected, register the new tool with the server immediately.
+        if (this.process?.stdin) {
+            this.request("tools/register", {
+                tools: [{ name, description, input_schema: inputSchema }],
+            }).catch(() => {
+                // Best-effort: tool registration may fail if connection is closing.
+            });
+        }
+    }
     // -- Connection ---------------------------------------------------------
     async connect(options) {
         if (options?.realmId && options?.isolated) {
@@ -96,6 +125,9 @@ export class MeerkatClient {
         if (!MeerkatClient.checkVersionCompatible(serverVersion, CONTRACT_VERSION)) {
             throw new MeerkatError("VERSION_MISMATCH", `Server version ${serverVersion} incompatible with SDK ${CONTRACT_VERSION}`);
         }
+        this._methods = new Set(Array.isArray(initResult.methods)
+            ? initResult.methods.map((method) => String(method))
+            : []);
         // Fetch capabilities
         const capsResult = await this.request("capabilities/get", {});
         const rawCaps = capsResult.capabilities ?? [];
@@ -104,6 +136,15 @@ export class MeerkatClient {
             description: String(cap.description ?? ""),
             status: MeerkatClient.normalizeStatus(cap.status),
         }));
+        // Register callback tools if any were declared.
+        if (this.toolHandlers.size > 0) {
+            const tools = Array.from(this.toolHandlers.entries()).map(([name, { description, inputSchema }]) => ({
+                name,
+                description,
+                input_schema: inputSchema,
+            }));
+            await this.request("tools/register", { tools });
+        }
         return this;
     }
     async close() {
@@ -123,10 +164,11 @@ export class MeerkatClient {
             queue.put(null);
         }
         this.eventQueues.clear();
-        for (const [, queue] of this.commsStreamQueues) {
+        for (const [, queue] of this.streamQueues) {
             queue.put(null);
         }
-        this.commsStreamQueues.clear();
+        this.streamQueues.clear();
+        this.streamTerminalOutcomes.clear();
         if (this.pendingStreamQueue) {
             this.pendingStreamQueue.put(null);
             this.pendingStreamQueue = null;
@@ -196,6 +238,18 @@ export class MeerkatClient {
             parseResult: MeerkatClient.parseRunResult,
         });
     }
+    /**
+     * Create a new session without running the first turn.
+     *
+     * Returns a {@link DeferredSession} whose `startTurn()` executes the first
+     * turn with optional per-turn overrides.
+     */
+    async createDeferredSession(prompt, options) {
+        const params = MeerkatClient.buildCreateParams(prompt, options);
+        params.initial_turn = "deferred";
+        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);
+    }
     // -- Session queries ----------------------------------------------------
     async listSessions() {
         const result = await this.request("session/list", {});
@@ -213,11 +267,27 @@ export class MeerkatClient {
     async readSession(sessionId) {
         return this.request("session/read", { session_id: sessionId });
     }
+    async readSessionHistory(sessionId, options) {
+        const params = {
+            session_id: sessionId,
+            offset: options?.offset ?? 0,
+        };
+        if (options?.limit !== undefined) {
+            params.limit = options.limit;
+        }
+        const raw = await this.request("session/history", params);
+        return MeerkatClient.parseSessionHistory(raw);
+    }
     // -- Capabilities -------------------------------------------------------
     get capabilities() {
         return this._capabilities;
     }
     hasCapability(capabilityId) {
+        if (capabilityId === "mob") {
+            return (this._methods.has("mob/create")
+                || this._methods.has("mob/list")
+                || this._methods.has("mob/call"));
+        }
         return this._capabilities.some((c) => c.id === capabilityId && c.status === "Available");
     }
     requireCapability(capabilityId) {
@@ -294,6 +364,172 @@ export class MeerkatClient {
             arguments: argumentsPayload ?? {},
         });
     }
+    async subscribeSessionEvents(sessionId) {
+        return this.openEventSubscription("session/stream_open", { session_id: sessionId }, "session/stream_close", MeerkatClient.parseAgentEventEnvelope);
+    }
+    async createMob(options) {
+        this.requireCapability("mob");
+        const result = await this.request("mob/create", options);
+        return new Mob(this, String(result.mob_id ?? ""));
+    }
+    mob(mobId) {
+        return new Mob(this, mobId);
+    }
+    async listMobs() {
+        this.requireCapability("mob");
+        const result = await this.request("mob/list", {});
+        const mobs = result.mobs ?? [];
+        return mobs.map((mob) => ({
+            mobId: String(mob.mob_id ?? mob.mobId ?? ""),
+            status: String(mob.status ?? ""),
+        }));
+    }
+    async mobStatus(mobId) {
+        const result = await this.request("mob/status", { mob_id: mobId });
+        const rawStatus = result.status;
+        const status = typeof rawStatus === "string"
+            ? rawStatus
+            : (typeof rawStatus === "object" && rawStatus !== null
+                ? String(Object.keys(rawStatus)[0] ?? "unknown")
+                : String(rawStatus ?? "unknown"));
+        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,
+            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,
+            sessionId: member.member_ref && typeof member.member_ref === 'object'
+                ? member.member_ref.session_id != null
+                    ? String(member.member_ref.session_id)
+                    : undefined
+                : undefined,
+        }));
+    }
+    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,
+        });
+    }
+    async retireMobMember(mobId, meerkatId) {
+        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 });
+    }
+    async wireMobMembers(mobId, a, b) {
+        await this.request("mob/wire", { mob_id: mobId, a, b });
+    }
+    async unwireMobMembers(mobId, a, b) {
+        await this.request("mob/unwire", { mob_id: mobId, a, b });
+    }
+    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 appendMobSystemContext(mobId, meerkatId, text, options) {
+        return this.request("mob/append_system_context", {
+            mob_id: mobId,
+            meerkat_id: meerkatId,
+            text,
+            source: options?.source,
+            idempotency_key: options?.idempotencyKey,
+        });
+    }
+    async listMobFlows(mobId) {
+        const result = await this.request("mob/flows", { mob_id: mobId });
+        return result.flows ?? [];
+    }
+    async runMobFlow(mobId, flowId, params = {}) {
+        const result = await this.request("mob/flow_run", { mob_id: mobId, flow_id: flowId, params });
+        return String(result.run_id ?? "");
+    }
+    async getMobFlowStatus(mobId, runId) {
+        const result = await this.request("mob/flow_status", { mob_id: mobId, run_id: runId });
+        return result.run == null ? null : { run: result.run };
+    }
+    async cancelMobFlow(mobId, runId) {
+        await this.request("mob/flow_cancel", { mob_id: mobId, run_id: runId });
+    }
+    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 openEventSubscription(openMethod, params, closeMethod, parse) {
+        const result = this.process?.stdin
+            ? await (async () => {
+                this.requestId++;
+                const requestId = this.requestId;
+                const responsePromise = this.registerRequest(requestId);
+                const rpcRequest = { jsonrpc: "2.0", id: requestId, method: openMethod, params };
+                this.process.stdin.write(JSON.stringify(rpcRequest) + "\n");
+                return responsePromise;
+            })()
+            : await this.request(openMethod, params);
+        const streamId = String(result.stream_id ?? "");
+        if (!streamId) {
+            throw new MeerkatError("INVALID_RESPONSE", `${openMethod} did not return stream_id`);
+        }
+        const queue = new AsyncQueue();
+        this.streamQueues.set(streamId, queue);
+        const buffered = this.unmatchedStandaloneStreamBuffer.get(streamId) ?? [];
+        for (const event of buffered) {
+            queue.put(event);
+        }
+        this.unmatchedStandaloneStreamBuffer.delete(streamId);
+        if (this.unmatchedStandaloneStreamEnd.delete(streamId)) {
+            queue.put(null);
+        }
+        return new EventSubscription({
+            streamId,
+            queue,
+            closeRemote: async (id) => {
+                this.streamQueues.delete(id);
+                await this.request(closeMethod, { stream_id: id });
+            },
+            parseEvent: parse,
+            getTerminalOutcome: () => this.streamTerminalOutcomes.get(streamId),
+        });
+    }
+    static parseAgentEventEnvelope(raw) {
+        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 ?? {})),
+        };
+    }
+    static parseAttributedMobEvent(raw) {
+        return {
+            source: String(raw.source ?? ""),
+            profile: String(raw.profile ?? ""),
+            envelope: MeerkatClient.parseAgentEventEnvelope((raw.envelope ?? {})),
+        };
+    }
     // -- Internal methods used by Session -----------------------------------
     /** @internal */
     async _startTurn(sessionId, prompt, options) {
@@ -311,6 +547,23 @@ export class MeerkatClient {
                 blocked_tools: options.flowToolOverlay.blockedTools,
             };
         }
+        if (options?.hostMode != null)
+            params.host_mode = options.hostMode;
+        if (options?.model)
+            params.model = options.model;
+        if (options?.provider)
+            params.provider = options.provider;
+        if (options?.maxTokens)
+            params.max_tokens = options.maxTokens;
+        if (options?.systemPrompt)
+            params.system_prompt = options.systemPrompt;
+        if (options?.outputSchema)
+            params.output_schema = options.outputSchema;
+        if (options?.structuredOutputRetries != null) {
+            params.structured_output_retries = options.structuredOutputRetries;
+        }
+        if (options?.providerParams)
+            params.provider_params = options.providerParams;
         const raw = await this.request("turn/start", params);
         return MeerkatClient.parseRunResult(raw);
     }
@@ -370,54 +623,6 @@ export class MeerkatClient {
     async peers(sessionId) {
         return this.request("comms/peers", { session_id: sessionId });
     }
-    async openCommsStream(sessionId, options) {
-        const scope = options?.scope ?? "session";
-        const params = { session_id: sessionId, scope };
-        if (options?.interactionId) {
-            params.interaction_id = options.interactionId;
-        }
-        const opened = await this.request("comms/stream_open", params);
-        const streamId = String(opened.stream_id ?? "");
-        if (!streamId) {
-            throw new MeerkatError("INVALID_RESPONSE", "Missing stream_id in comms/stream_open response");
-        }
-        const queue = new AsyncQueue();
-        this.commsStreamQueues.set(streamId, queue);
-        return new CommsEventStream({
-            streamId,
-            eventQueue: queue,
-            onClose: async (id) => {
-                await this.request("comms/stream_close", { stream_id: id });
-                const q = this.commsStreamQueues.get(id);
-                if (q) {
-                    q.put(null);
-                }
-                this.commsStreamQueues.delete(id);
-            },
-        });
-    }
-    async open_comms_stream(sessionId, options) {
-        return this.openCommsStream(sessionId, options);
-    }
-    async sendAndStream(sessionId, command) {
-        const receipt = await this.send(sessionId, command);
-        const interactionId = String(receipt.interaction_id ?? "");
-        const streamReserved = Boolean(receipt.stream_reserved ?? false);
-        if (!interactionId) {
-            throw new MeerkatError("INVALID_RESPONSE", "comms/send response missing interaction_id for sendAndStream");
-        }
-        if (!streamReserved) {
-            throw new MeerkatError("INVALID_RESPONSE", "comms/send response did not reserve stream for sendAndStream");
-        }
-        const stream = await this.openCommsStream(sessionId, {
-            scope: "interaction",
-            interactionId,
-        });
-        return { receipt, stream };
-    }
-    async send_and_stream(sessionId, command) {
-        return this.sendAndStream(sessionId, command);
-    }
     // -- Transport ----------------------------------------------------------
     handleLine(line) {
         let data;
@@ -427,6 +632,11 @@ export class MeerkatClient {
         catch {
             return;
         }
+        // Server→client callback request (has both id and method).
+        if ("id" in data && "method" in data) {
+            this.handleCallbackRequest(data);
+            return;
+        }
         if ("id" in data && typeof data.id === "number") {
             const pending = this.pendingRequests.get(data.id);
             if (pending) {
@@ -441,16 +651,42 @@ export class MeerkatClient {
             }
         }
         else if ("method" in data) {
-            if (data.method === "comms/stream_event") {
-                const params = (data.params ?? {});
+            const method = String(data.method ?? "");
+            const params = (data.params ?? {});
+            if (method === "session/stream_event" || method === "mob/stream_event") {
+                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).
+                const scopeId = params.scope_id;
+                const scopePath = params.scope_path;
+                const event = scopeId != null || scopePath != null
+                    ? { event: rawEvent, scope_id: scopeId, scope_path: scopePath }
+                    : rawEvent;
+                if (queue && event) {
+                    queue.put(event);
+                }
+                else if (streamId && event) {
+                    const buffered = this.unmatchedStandaloneStreamBuffer.get(streamId) ?? [];
+                    buffered.push(event);
+                    this.unmatchedStandaloneStreamBuffer.set(streamId, buffered);
+                }
+                return;
+            }
+            if (method === "session/stream_end" || method === "mob/stream_end") {
                 const streamId = String(params.stream_id ?? "");
-                const queue = this.commsStreamQueues.get(streamId);
+                if (streamId) {
+                    this.streamTerminalOutcomes.set(streamId, params);
+                }
+                const queue = this.streamQueues.get(streamId);
                 if (queue) {
-                    queue.put(params);
+                    queue.put(null);
+                }
+                else if (streamId) {
+                    this.unmatchedStandaloneStreamEnd.set(streamId, params);
                 }
                 return;
             }
-            const params = (data.params ?? {});
             const sessionId = String(params.session_id ?? "");
             const event = params.event;
             if (event) {
@@ -567,6 +803,58 @@ export class MeerkatClient {
             skillDiagnostics: MeerkatClient.parseSkillDiagnostics(data.skill_diagnostics),
         };
     }
+    static parseSessionHistory(data) {
+        const rawMessages = Array.isArray(data.messages)
+            ? data.messages
+            : [];
+        return {
+            sessionId: String(data.session_id ?? ""),
+            sessionRef: data.session_ref != null ? String(data.session_ref) : undefined,
+            messageCount: Number(data.message_count ?? 0),
+            offset: Number(data.offset ?? 0),
+            limit: data.limit != null ? Number(data.limit) : undefined,
+            hasMore: Boolean(data.has_more ?? false),
+            messages: rawMessages.map((message) => MeerkatClient.parseSessionMessage(message)),
+        };
+    }
+    static parseSessionMessage(data) {
+        const rawToolCalls = Array.isArray(data.tool_calls)
+            ? data.tool_calls
+            : [];
+        const rawBlocks = Array.isArray(data.blocks)
+            ? data.blocks
+            : [];
+        const rawResults = Array.isArray(data.results)
+            ? data.results
+            : [];
+        return {
+            role: String(data.role ?? ""),
+            content: data.content != null ? String(data.content) : undefined,
+            toolCalls: rawToolCalls.map((toolCall) => ({
+                id: String(toolCall.id ?? ""),
+                name: String(toolCall.name ?? ""),
+                args: toolCall.args,
+            })),
+            stopReason: data.stop_reason != null ? String(data.stop_reason) : undefined,
+            blocks: rawBlocks.map((block) => MeerkatClient.parseSessionAssistantBlock(block)),
+            results: rawResults.map((result) => ({
+                toolUseId: String(result.tool_use_id ?? ""),
+                content: String(result.content ?? ""),
+                isError: Boolean(result.is_error ?? false),
+            })),
+        };
+    }
+    static parseSessionAssistantBlock(data) {
+        const blockData = data.data ?? {};
+        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,
+            meta: blockData.meta,
+        };
+    }
     static parseMcpLiveOpResponse(raw) {
         const sessionId = raw.session_id;
         const operation = raw.operation;
@@ -586,6 +874,48 @@ export class MeerkatClient {
         }
         return raw;
     }
+    handleCallbackRequest(data) {
+        const requestId = data.id;
+        const method = String(data.method ?? "");
+        const params = (data.params ?? {});
+        if (method === "tool/execute") {
+            const toolName = String(params.name ?? "");
+            const handler = this.toolHandlers.get(toolName);
+            if (handler) {
+                const args = (params.arguments ?? {});
+                handler
+                    .handler(args)
+                    .then((content) => {
+                    this.writeCallbackResponse(requestId, { content, is_error: false });
+                })
+                    .catch((err) => {
+                    this.writeCallbackResponse(requestId, {
+                        content: `Tool error: ${err}`,
+                        is_error: true,
+                    });
+                });
+            }
+            else {
+                this.writeCallbackResponse(requestId, {
+                    content: `Unknown tool: ${toolName}`,
+                    is_error: true,
+                });
+            }
+        }
+        else {
+            // Unknown callback method.
+            const response = {
+                jsonrpc: "2.0",
+                id: requestId,
+                error: { code: -32601, message: `Method not supported: ${method}` },
+            };
+            this.process?.stdin?.write(JSON.stringify(response) + "\n");
+        }
+    }
+    writeCallbackResponse(requestId, result) {
+        const response = { jsonrpc: "2.0", id: requestId, result };
+        this.process?.stdin?.write(JSON.stringify(response) + "\n");
+    }
     static buildCreateParams(prompt, options) {
         const params = { prompt };
         if (!options)