@rkat/sdk 0.3.4 → 0.4.1

package/dist/client.js

@@ -1,25 +1,640 @@
 /**
- * Meerkat client — spawns rkat-rpc subprocess and communicates via JSON-RPC.
+ * Meerkat client — spawns rkat-rpc and communicates via JSON-RPC.
+ *
+ * @example
+ * ```ts
+ * import { MeerkatClient } from "@rkat/sdk";
+ *
+ * const client = new MeerkatClient();
+ * await client.connect();
+ *
+ * const session = await client.createSession("Hello!");
+ * console.log(session.text);
+ *
+ * const result = await session.turn("Tell me more");
+ * console.log(result.text);
+ *
+ * for await (const event of session.stream("Explain in detail")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ *
+ * await session.archive();
+ * await client.close();
+ * ```
  */
 import { spawn } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, unlinkSync, writeFileSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline";
-import { MeerkatError } from "./generated/errors.js";
-import { CONTRACT_VERSION } from "./generated/types.js";
+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";
 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);
+/**
+ * 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.
+ */
+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 skillRefsToWire(refs) {
+    if (!refs)
+        return undefined;
+    return refs.map(normalizeSkillRef);
+}
 export class MeerkatClient {
     process = null;
     requestId = 0;
-    capabilities = null;
+    _capabilities = [];
     rkatPath;
     pendingRequests = new Map();
+    eventQueues = new Map();
+    commsStreamQueues = new Map();
+    pendingStreamQueue = null;
+    pendingStreamRequestId = null;
+    unmatchedStreamBuffer = new Map();
+    rl = null;
     constructor(rkatPath = "rkat-rpc") {
         this.rkatPath = rkatPath;
     }
+    // -- Connection ---------------------------------------------------------
+    async connect(options) {
+        if (options?.realmId && options?.isolated) {
+            throw new MeerkatError("INVALID_ARGS", "realmId and isolated cannot both be set");
+        }
+        const resolved = await MeerkatClient.resolveBinaryPath(this.rkatPath);
+        this.rkatPath = resolved.command;
+        const args = MeerkatClient.buildArgs(resolved.useLegacySubcommand, options);
+        if (resolved.useLegacySubcommand && args.length > 1) {
+            throw new MeerkatError("LEGACY_BINARY_UNSUPPORTED", "Realm/context options require the standalone rkat-rpc binary. Install rkat-rpc and retry.");
+        }
+        this.process = spawn(this.rkatPath, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.rl = createInterface({ input: this.process.stdout });
+        this.rl.on("line", (line) => this.handleLine(line));
+        // Handshake
+        const initResult = await this.request("initialize", {});
+        const serverVersion = String(initResult.contract_version ?? "");
+        if (!MeerkatClient.checkVersionCompatible(serverVersion, CONTRACT_VERSION)) {
+            throw new MeerkatError("VERSION_MISMATCH", `Server version ${serverVersion} incompatible with SDK ${CONTRACT_VERSION}`);
+        }
+        // Fetch capabilities
+        const capsResult = await this.request("capabilities/get", {});
+        const rawCaps = capsResult.capabilities ?? [];
+        this._capabilities = rawCaps.map((cap) => ({
+            id: String(cap.id ?? ""),
+            description: String(cap.description ?? ""),
+            status: MeerkatClient.normalizeStatus(cap.status),
+        }));
+        return this;
+    }
+    async close() {
+        if (this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+        if (this.process) {
+            this.process.kill();
+            this.process = null;
+        }
+        for (const [, pending] of this.pendingRequests) {
+            pending.reject(new MeerkatError("CLIENT_CLOSED", "Client closed"));
+        }
+        this.pendingRequests.clear();
+        for (const [, queue] of this.eventQueues) {
+            queue.put(null);
+        }
+        this.eventQueues.clear();
+        for (const [, queue] of this.commsStreamQueues) {
+            queue.put(null);
+        }
+        this.commsStreamQueues.clear();
+        if (this.pendingStreamQueue) {
+            this.pendingStreamQueue.put(null);
+            this.pendingStreamQueue = null;
+            this.pendingStreamRequestId = null;
+            this.unmatchedStreamBuffer.clear();
+        }
+    }
+    // -- Session lifecycle --------------------------------------------------
+    /**
+     * Create a new session, run the first turn, and return a {@link Session}.
+     *
+     * @example
+     * ```ts
+     * const session = await client.createSession("Summarise this project", {
+     *   model: "claude-sonnet-4-5",
+     * });
+     * console.log(session.text);
+     * ```
+     */
+    async createSession(prompt, options) {
+        const params = MeerkatClient.buildCreateParams(prompt, options);
+        const raw = await this.request("session/create", params);
+        const result = MeerkatClient.parseRunResult(raw);
+        return new Session(this, result);
+    }
+    /**
+     * Create a new session and stream typed events from the first turn.
+     *
+     * Returns an {@link EventStream} `AsyncIterable<AgentEvent>`.
+     */
+    createSessionStreaming(prompt, options) {
+        if (!this.process?.stdin) {
+            throw new MeerkatError("NOT_CONNECTED", "Client not connected");
+        }
+        const params = MeerkatClient.buildCreateParams(prompt, options);
+        this.requestId++;
+        const requestId = this.requestId;
+        if (this.pendingStreamQueue) {
+            throw new MeerkatError("INVALID_STATE", "Only one createSessionStreaming request can be pending at a time");
+        }
+        const queue = new AsyncQueue();
+        this.pendingStreamQueue = queue;
+        this.pendingStreamRequestId = requestId;
+        const responsePromise = this.registerRequest(requestId);
+        // When response arrives, bind the queue to the session_id
+        const wrappedPromise = responsePromise.then((result) => {
+            const sid = String(result.session_id ?? "");
+            if (sid) {
+                const buffered = this.unmatchedStreamBuffer.get(sid) ?? [];
+                for (const evt of buffered) {
+                    queue.put(evt);
+                }
+                this.unmatchedStreamBuffer.delete(sid);
+                this.eventQueues.set(sid, queue);
+            }
+            this.pendingStreamQueue = null;
+            this.pendingStreamRequestId = null;
+            this.unmatchedStreamBuffer.clear();
+            return result;
+        });
+        const rpcRequest = { jsonrpc: "2.0", id: requestId, method: "session/create", params };
+        this.process.stdin.write(JSON.stringify(rpcRequest) + "\n");
+        return new EventStream({
+            sessionId: "",
+            eventQueue: queue,
+            responsePromise: wrappedPromise,
+            parseResult: MeerkatClient.parseRunResult,
+        });
+    }
+    // -- Session queries ----------------------------------------------------
+    async listSessions() {
+        const result = await this.request("session/list", {});
+        const sessions = result.sessions ?? [];
+        return sessions.map((s) => ({
+            sessionId: String(s.session_id ?? ""),
+            sessionRef: s.session_ref != null ? String(s.session_ref) : undefined,
+            createdAt: String(s.created_at ?? ""),
+            updatedAt: String(s.updated_at ?? ""),
+            messageCount: Number(s.message_count ?? 0),
+            totalTokens: Number(s.total_tokens ?? 0),
+            isActive: Boolean(s.is_active),
+        }));
+    }
+    async readSession(sessionId) {
+        return this.request("session/read", { session_id: sessionId });
+    }
+    // -- Capabilities -------------------------------------------------------
+    get capabilities() {
+        return this._capabilities;
+    }
+    hasCapability(capabilityId) {
+        return this._capabilities.some((c) => c.id === capabilityId && c.status === "Available");
+    }
+    requireCapability(capabilityId) {
+        if (!this.hasCapability(capabilityId)) {
+            throw new CapabilityUnavailableError("CAPABILITY_UNAVAILABLE", `Capability '${capabilityId}' is not available`);
+        }
+    }
+    // -- Config -------------------------------------------------------------
+    async getConfig() {
+        return this.request("config/get", {});
+    }
+    async setConfig(config, options) {
+        const params = { config };
+        if (options?.expectedGeneration !== undefined) {
+            params.expected_generation = options.expectedGeneration;
+        }
+        return this.request("config/set", params);
+    }
+    async patchConfig(patch, options) {
+        const params = { patch };
+        if (options?.expectedGeneration !== undefined) {
+            params.expected_generation = options.expectedGeneration;
+        }
+        return this.request("config/patch", params);
+    }
+    async mcpAdd(params) {
+        const raw = await this.request("mcp/add", params);
+        return MeerkatClient.parseMcpLiveOpResponse(raw);
+    }
+    async mcpRemove(params) {
+        const raw = await this.request("mcp/remove", params);
+        return MeerkatClient.parseMcpLiveOpResponse(raw);
+    }
+    async mcpReload(params) {
+        const raw = await this.request("mcp/reload", params);
+        return MeerkatClient.parseMcpLiveOpResponse(raw);
+    }
+    // snake_case aliases for parity with other SDKs/surfaces
+    async mcp_add(params) {
+        return this.mcpAdd(params);
+    }
+    async mcp_remove(params) {
+        return this.mcpRemove(params);
+    }
+    async mcp_reload(params) {
+        return this.mcpReload(params);
+    }
+    // -- Skills ---------------------------------------------------------------
+    async listSkills() {
+        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 listMobPrefabs() {
+        const result = await this.request("mob/prefabs", {});
+        return result.prefabs ?? [];
+    }
+    async list_mob_prefabs() {
+        return this.listMobPrefabs();
+    }
+    async listMobTools() {
+        const result = await this.request("mob/tools", {});
+        return result.tools ?? [];
+    }
+    async callMobTool(name, argumentsPayload) {
+        return this.request("mob/call", {
+            name,
+            arguments: argumentsPayload ?? {},
+        });
+    }
+    // -- Internal methods used by Session -----------------------------------
+    /** @internal */
+    async _startTurn(sessionId, prompt, options) {
+        const params = { session_id: sessionId, prompt };
+        const wireRefs = skillRefsToWire(options?.skillRefs);
+        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,
+                blocked_tools: options.flowToolOverlay.blockedTools,
+            };
+        }
+        const raw = await this.request("turn/start", params);
+        return MeerkatClient.parseRunResult(raw);
+    }
+    /** @internal */
+    _startTurnStreaming(sessionId, prompt, options, session) {
+        if (!this.process?.stdin) {
+            throw new MeerkatError("NOT_CONNECTED", "Client not connected");
+        }
+        this.requestId++;
+        const requestId = this.requestId;
+        const queue = new AsyncQueue();
+        this.eventQueues.set(sessionId, queue);
+        const responsePromise = this.registerRequest(requestId);
+        const params = { session_id: sessionId, prompt };
+        const wireRefs = skillRefsToWire(options?.skillRefs);
+        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,
+                blocked_tools: options.flowToolOverlay.blockedTools,
+            };
+        }
+        const rpcRequest = { jsonrpc: "2.0", id: requestId, method: "turn/start", params };
+        this.process.stdin.write(JSON.stringify(rpcRequest) + "\n");
+        return new EventStream({
+            sessionId,
+            eventQueue: queue,
+            responsePromise,
+            parseResult: MeerkatClient.parseRunResult,
+            session,
+        });
+    }
+    /** @internal */
+    async _interrupt(sessionId) {
+        await this.request("turn/interrupt", { session_id: sessionId });
+    }
+    /** @internal */
+    async _archive(sessionId) {
+        await this.request("session/archive", { session_id: sessionId });
+    }
+    /** @internal */
+    async _send(sessionId, command) {
+        return this.send(sessionId, command);
+    }
+    /** @internal */
+    async _peers(sessionId) {
+        return this.peers(sessionId);
+    }
+    async send(sessionId, command) {
+        return this.request("comms/send", { session_id: sessionId, ...command });
+    }
+    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;
+        try {
+            data = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if ("id" in data && typeof data.id === "number") {
+            const pending = this.pendingRequests.get(data.id);
+            if (pending) {
+                this.pendingRequests.delete(data.id);
+                const error = data.error;
+                if (error) {
+                    pending.reject(new MeerkatError(String(error.code ?? "UNKNOWN"), String(error.message ?? "Unknown error")));
+                }
+                else {
+                    pending.resolve((data.result ?? {}));
+                }
+            }
+        }
+        else if ("method" in data) {
+            if (data.method === "comms/stream_event") {
+                const params = (data.params ?? {});
+                const streamId = String(params.stream_id ?? "");
+                const queue = this.commsStreamQueues.get(streamId);
+                if (queue) {
+                    queue.put(params);
+                }
+                return;
+            }
+            const params = (data.params ?? {});
+            const sessionId = String(params.session_id ?? "");
+            const event = params.event;
+            if (event) {
+                const queue = this.eventQueues.get(sessionId);
+                if (queue) {
+                    queue.put(event);
+                }
+                else if (this.pendingStreamQueue) {
+                    const buffered = this.unmatchedStreamBuffer.get(sessionId) ?? [];
+                    buffered.push(event);
+                    this.unmatchedStreamBuffer.set(sessionId, buffered);
+                }
+            }
+        }
+    }
+    request(method, params) {
+        if (!this.process?.stdin) {
+            throw new MeerkatError("NOT_CONNECTED", "Client not connected");
+        }
+        this.requestId++;
+        const id = this.requestId;
+        const rpcRequest = { jsonrpc: "2.0", id, method, params };
+        const promise = this.registerRequest(id);
+        this.process.stdin.write(JSON.stringify(rpcRequest) + "\n");
+        return promise;
+    }
+    registerRequest(id) {
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, { resolve, reject });
+        });
+    }
+    // -- Static helpers -----------------------------------------------------
+    static normalizeStatus(raw) {
+        if (typeof raw === "string")
+            return raw;
+        if (typeof raw === "object" && raw !== null) {
+            // Rust can emit externally-tagged enums for status:
+            // { DisabledByPolicy: { description: "..." } }
+            return Object.keys(raw)[0] ?? "Unknown";
+        }
+        return String(raw);
+    }
+    static parseSkillDiagnostics(raw) {
+        if (!raw || typeof raw !== "object")
+            return undefined;
+        const data = raw;
+        const sourceHealthRaw = data.source_health;
+        const rawQuarantined = Array.isArray(data.quarantined)
+            ? data.quarantined
+            : [];
+        const quarantined = rawQuarantined
+            .filter((item) => typeof item === "object" && item !== null)
+            .map((item) => ({
+            sourceUuid: String(item.source_uuid ?? ""),
+            skillId: String(item.skill_id ?? ""),
+            location: String(item.location ?? ""),
+            errorCode: String(item.error_code ?? ""),
+            errorClass: String(item.error_class ?? ""),
+            message: String(item.message ?? ""),
+            firstSeenUnixSecs: Number(item.first_seen_unix_secs ?? 0),
+            lastSeenUnixSecs: Number(item.last_seen_unix_secs ?? 0),
+        }));
+        return {
+            sourceHealth: {
+                state: String(sourceHealthRaw?.state ?? ""),
+                invalidRatio: Number(sourceHealthRaw?.invalid_ratio ?? 0),
+                invalidCount: Number(sourceHealthRaw?.invalid_count ?? 0),
+                totalCount: Number(sourceHealthRaw?.total_count ?? 0),
+                failureStreak: Number(sourceHealthRaw?.failure_streak ?? 0),
+                handshakeFailed: Boolean(sourceHealthRaw?.handshake_failed ?? false),
+            },
+            quarantined,
+        };
+    }
+    static checkVersionCompatible(server, client) {
+        try {
+            const s = server.split(".").map(Number);
+            const c = client.split(".").map(Number);
+            if (s[0] === 0 && c[0] === 0)
+                return s[1] === c[1];
+            return s[0] === c[0];
+        }
+        catch {
+            return false;
+        }
+    }
+    static parseRunResult(data) {
+        const usageRaw = data.usage;
+        const usage = {
+            inputTokens: Number(usageRaw?.input_tokens ?? 0),
+            outputTokens: Number(usageRaw?.output_tokens ?? 0),
+            cacheCreationTokens: usageRaw?.cache_creation_tokens != null
+                ? Number(usageRaw.cache_creation_tokens)
+                : undefined,
+            cacheReadTokens: usageRaw?.cache_read_tokens != null
+                ? Number(usageRaw.cache_read_tokens)
+                : undefined,
+        };
+        const rawWarnings = data.schema_warnings;
+        const schemaWarnings = rawWarnings?.map((w) => ({
+            provider: String(w.provider ?? ""),
+            path: String(w.path ?? ""),
+            message: String(w.message ?? ""),
+        }));
+        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),
+            usage,
+            structuredOutput: data.structured_output,
+            schemaWarnings,
+            skillDiagnostics: MeerkatClient.parseSkillDiagnostics(data.skill_diagnostics),
+        };
+    }
+    static parseMcpLiveOpResponse(raw) {
+        const sessionId = raw.session_id;
+        const operation = raw.operation;
+        const status = raw.status;
+        const persisted = raw.persisted;
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mcp response: missing session_id");
+        }
+        if (operation !== "add" && operation !== "remove" && operation !== "reload") {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mcp response: invalid operation");
+        }
+        if (typeof status !== "string" || status.length === 0) {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mcp response: missing status");
+        }
+        if (typeof persisted !== "boolean") {
+            throw new MeerkatError("INVALID_RESPONSE", "Invalid mcp response: persisted must be boolean");
+        }
+        return raw;
+    }
+    static buildCreateParams(prompt, options) {
+        const params = { prompt };
+        if (!options)
+            return params;
+        if (options.model)
+            params.model = options.model;
+        if (options.provider)
+            params.provider = options.provider;
+        if (options.systemPrompt)
+            params.system_prompt = options.systemPrompt;
+        if (options.maxTokens)
+            params.max_tokens = options.maxTokens;
+        if (options.outputSchema)
+            params.output_schema = options.outputSchema;
+        if (options.structuredOutputRetries != null && options.structuredOutputRetries !== 2) {
+            params.structured_output_retries = options.structuredOutputRetries;
+        }
+        if (options.hooksOverride)
+            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.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)
+            params.provider_params = options.providerParams;
+        if (options.preloadSkills != null)
+            params.preload_skills = options.preloadSkills;
+        const wireRefs = skillRefsToWire(options.skillRefs);
+        if (wireRefs)
+            params.skill_refs = wireRefs;
+        if (options.skillReferences != null)
+            params.skill_references = options.skillReferences;
+        return params;
+    }
+    // -- Binary resolution --------------------------------------------------
     static commandPath(command) {
         if (path.isAbsolute(command)) {
             return existsSync(command) ? command : null;
@@ -59,39 +674,20 @@ export class MeerkatClient {
         const architecture = os.arch();
         if (process.platform === "darwin") {
             if (architecture === "arm64") {
-                return {
-                    target: "aarch64-apple-darwin",
-                    archiveExt: "tar.gz",
-                    binaryName: "rkat-rpc",
-                };
+                return { target: "aarch64-apple-darwin", archiveExt: "tar.gz", binaryName: "rkat-rpc" };
             }
-            throw new MeerkatError("UNSUPPORTED_PLATFORM", `Unsupported macOS architecture '${architecture}'. Only Apple Silicon (arm64) is supported.`);
+            throw new MeerkatError("UNSUPPORTED_PLATFORM", `Unsupported macOS architecture '${architecture}'.`);
         }
         if (process.platform === "linux") {
-            if (architecture === "x64") {
-                return {
-                    target: "x86_64-unknown-linux-gnu",
-                    archiveExt: "tar.gz",
-                    binaryName: "rkat-rpc",
-                };
-            }
-            if (architecture === "arm64") {
-                return {
-                    target: "aarch64-unknown-linux-gnu",
-                    archiveExt: "tar.gz",
-                    binaryName: "rkat-rpc",
-                };
-            }
+            if (architecture === "x64")
+                return { target: "x86_64-unknown-linux-gnu", archiveExt: "tar.gz", binaryName: "rkat-rpc" };
+            if (architecture === "arm64")
+                return { target: "aarch64-unknown-linux-gnu", archiveExt: "tar.gz", binaryName: "rkat-rpc" };
             throw new MeerkatError("UNSUPPORTED_PLATFORM", `Unsupported Linux architecture '${architecture}'.`);
         }
         if (process.platform === "win32") {
-            if (architecture === "x64") {
-                return {
-                    target: "x86_64-pc-windows-msvc",
-                    archiveExt: "zip",
-                    binaryName: "rkat-rpc.exe",
-                };
-            }
+            if (architecture === "x64")
+                return { target: "x86_64-pc-windows-msvc", archiveExt: "zip", binaryName: "rkat-rpc.exe" };
             throw new MeerkatError("UNSUPPORTED_PLATFORM", `Unsupported Windows architecture '${architecture}'.`);
         }
         throw new MeerkatError("UNSUPPORTED_PLATFORM", `Unsupported platform '${process.platform}'.`);
@@ -100,12 +696,8 @@ export class MeerkatClient {
         return new Promise((resolve, reject) => {
             const proc = spawn(command, args, { stdio: ["ignore", "inherit", "pipe"] });
             let stderr = "";
-            proc.stderr?.on("data", (chunk) => {
-                stderr += String(chunk);
-            });
-            proc.on("error", (error) => {
-                reject(error);
-            });
+            proc.stderr?.on("data", (chunk) => { stderr += String(chunk); });
+            proc.on("error", (error) => { reject(error); });
             proc.on("close", (code) => {
                 if (code === 0) {
                     resolve();
@@ -118,12 +710,10 @@ export class MeerkatClient {
     static async extractZip(archivePath, destinationDir) {
         try {
             await MeerkatClient.runCommand("tar", ["-xf", archivePath, "-C", destinationDir]);
-            return;
         }
-        catch (error) {
+        catch {
             await MeerkatClient.runCommand("powershell", [
-                "-NoProfile",
-                "-Command",
+                "-NoProfile", "-Command",
                 `Expand-Archive -LiteralPath '${archivePath.replaceAll("'", "''")}' -DestinationPath '${destinationDir.replaceAll("'", "''")}' -Force`,
             ]);
         }
@@ -136,9 +726,8 @@ export class MeerkatClient {
         const baseDir = path.join(MEERKAT_BINARY_CACHE_ROOT, `v${version}`, target);
         mkdirSync(baseDir, { recursive: true });
         const cached = path.join(baseDir, binaryName);
-        if (existsSync(cached)) {
+        if (existsSync(cached))
             return cached;
-        }
         const response = await fetch(url);
         if (!response.ok) {
             throw new MeerkatError("BINARY_DOWNLOAD_FAILED", `Failed to download binary from ${url} (HTTP ${response.status})`);
@@ -163,9 +752,8 @@ export class MeerkatClient {
             }
             catch { /* best-effort cleanup */ }
         }
-        if (process.platform !== "win32") {
+        if (process.platform !== "win32")
             chmodSync(cached, 0o755);
-        }
         return cached;
     }
     static async resolveBinaryPath(requestedPath) {
@@ -173,293 +761,54 @@ export class MeerkatClient {
         if (overridden) {
             const candidate = MeerkatClient.resolveCandidatePath(overridden);
             if (!candidate) {
-                throw new MeerkatError("BINARY_NOT_FOUND", `Binary not found at MEERKAT_BIN_PATH='${overridden}'. Set it to a valid executable.`);
+                throw new MeerkatError("BINARY_NOT_FOUND", `Binary not found at MEERKAT_BIN_PATH='${overridden}'.`);
             }
-            return {
-                command: candidate,
-                useLegacySubcommand: path.basename(candidate) === "rkat",
-            };
+            return { command: candidate, useLegacySubcommand: path.basename(candidate) === "rkat" };
         }
         if (requestedPath !== "rkat-rpc") {
             const candidate = MeerkatClient.resolveCandidatePath(requestedPath);
             if (!candidate) {
-                throw new MeerkatError("BINARY_NOT_FOUND", `Binary not found at '${requestedPath}'. Set rkatPath to a valid path or use MEERKAT_BIN_PATH.`);
+                throw new MeerkatError("BINARY_NOT_FOUND", `Binary not found at '${requestedPath}'.`);
             }
-            return {
-                command: candidate,
-                useLegacySubcommand: path.basename(candidate) === "rkat",
-            };
+            return { command: candidate, useLegacySubcommand: path.basename(candidate) === "rkat" };
         }
         const defaultBinary = MeerkatClient.commandPath("rkat-rpc");
-        if (defaultBinary) {
-            return {
-                command: defaultBinary,
-                useLegacySubcommand: false,
-            };
-        }
+        if (defaultBinary)
+            return { command: defaultBinary, useLegacySubcommand: false };
         try {
             const downloaded = await MeerkatClient.ensureDownloadedBinary();
             return { command: downloaded, useLegacySubcommand: false };
         }
         catch (error) {
             const legacy = MeerkatClient.commandPath("rkat");
-            if (legacy) {
+            if (legacy)
                 return { command: legacy, useLegacySubcommand: true };
-            }
             if (error instanceof MeerkatError)
                 throw error;
             throw new MeerkatError("BINARY_NOT_FOUND", `Could not find '${MEERKAT_RELEASE_BINARY}' and auto-download failed.`);
         }
     }
-    async connect(options) {
-        if (options?.realmId && options?.isolated) {
-            throw new MeerkatError("INVALID_ARGS", "realmId and isolated cannot both be set");
-        }
-        const resolved = await MeerkatClient.resolveBinaryPath(this.rkatPath);
-        this.rkatPath = resolved.command;
+    static buildArgs(legacy, options) {
+        if (legacy)
+            return ["rpc"];
+        if (!options)
+            return [];
         const args = [];
-        const legacyRequiresNewBinary = Boolean(options?.isolated ||
-            options?.realmId ||
-            options?.instanceId ||
-            options?.realmBackend ||
-            options?.stateRoot ||
-            options?.contextRoot ||
-            options?.userConfigRoot);
-        if (resolved.useLegacySubcommand) {
-            if (legacyRequiresNewBinary) {
-                throw new MeerkatError("LEGACY_BINARY_UNSUPPORTED", "Realm/context options require the standalone rkat-rpc binary. Install rkat-rpc and retry.");
-            }
-            args.push("rpc");
-        }
-        else {
-            if (options?.isolated) {
-                args.push("--isolated");
-            }
-            if (options?.realmId) {
-                args.push("--realm", options.realmId);
-            }
-            if (options?.instanceId) {
-                args.push("--instance", options.instanceId);
-            }
-            if (options?.realmBackend) {
-                args.push("--realm-backend", options.realmBackend);
-            }
-            if (options?.stateRoot) {
-                args.push("--state-root", options.stateRoot);
-            }
-            if (options?.contextRoot) {
-                args.push("--context-root", options.contextRoot);
-            }
-            if (options?.userConfigRoot) {
-                args.push("--user-config-root", options.userConfigRoot);
-            }
-        }
-        this.process = spawn(this.rkatPath, args, {
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        const rl = createInterface({ input: this.process.stdout });
-        rl.on("line", (line) => {
-            try {
-                const response = JSON.parse(line);
-                if ("id" in response &&
-                    typeof response.id === "number" &&
-                    this.pendingRequests.has(response.id)) {
-                    const pending = this.pendingRequests.get(response.id);
-                    this.pendingRequests.delete(response.id);
-                    const error = response.error;
-                    if (error) {
-                        pending.reject(new MeerkatError(String(error.code ?? "UNKNOWN"), String(error.message ?? "Unknown error")));
-                    }
-                    else {
-                        pending.resolve(response.result ?? {});
-                    }
-                }
-            }
-            catch {
-                // Ignore non-JSON lines
-            }
-        });
-        // Initialize
-        const initResult = (await this.request("initialize", {}));
-        const serverVersion = String(initResult.contract_version ?? "");
-        if (!this.checkVersionCompatible(serverVersion, CONTRACT_VERSION)) {
-            throw new MeerkatError("VERSION_MISMATCH", `Server version ${serverVersion} incompatible with SDK ${CONTRACT_VERSION}`);
-        }
-        // Fetch capabilities
-        const capsResult = (await this.request("capabilities/get", {}));
-        this.capabilities = {
-            contract_version: String(capsResult.contract_version ?? ""),
-            capabilities: (capsResult.capabilities ?? []).map((cap) => ({
-                id: String(cap.id ?? ""),
-                description: String(cap.description ?? ""),
-                status: MeerkatClient.normalizeStatus(cap.status),
-            })),
-        };
-        return this;
-    }
-    async close() {
-        if (this.process) {
-            this.process.kill();
-            this.process = null;
-        }
-    }
-    async createSession(params) {
-        const result = (await this.request("session/create", params));
-        return this.parseRunResult(result);
-    }
-    async startTurn(sessionId, prompt, options) {
-        const result = (await this.request("turn/start", {
-            session_id: sessionId,
-            prompt,
-            ...options,
-        }));
-        return this.parseRunResult(result);
-    }
-    async interrupt(sessionId) {
-        await this.request("turn/interrupt", { session_id: sessionId });
-    }
-    async listSessions() {
-        const result = (await this.request("session/list", {}));
-        return result.sessions ?? [];
-    }
-    async readSession(sessionId) {
-        return (await this.request("session/read", {
-            session_id: sessionId,
-        }));
-    }
-    async archiveSession(sessionId) {
-        await this.request("session/archive", { session_id: sessionId });
-    }
-    async getCapabilities() {
-        if (this.capabilities)
-            return this.capabilities;
-        const result = (await this.request("capabilities/get", {}));
-        return {
-            contract_version: String(result.contract_version ?? ""),
-            capabilities: [],
-        };
-    }
-    hasCapability(capabilityId) {
-        if (!this.capabilities)
-            return false;
-        return this.capabilities.capabilities.some((c) => c.id === capabilityId && c.status === "Available");
-    }
-    requireCapability(capabilityId) {
-        if (!this.hasCapability(capabilityId)) {
-            throw new MeerkatError("CAPABILITY_UNAVAILABLE", `Capability '${capabilityId}' is not available`);
-        }
-    }
-    // --- Config ---
-    async getConfig() {
-        return (await this.request("config/get", {}));
-    }
-    async setConfig(config) {
-        await this.request("config/set", config);
-    }
-    async patchConfig(patch) {
-        return (await this.request("config/patch", patch));
-    }
-    /**
-     * Send a canonical comms command to a session.
-     *
-     * @param sessionId - Target session ID
-     * @param command - Command fields (kind, to, body, intent, params, etc.)
-     * @returns Receipt info on success
-     */
-    async send(sessionId, command) {
-        return (await this.request("comms/send", {
-            session_id: sessionId,
-            ...command,
-        }));
-    }
-    /**
-     * Send a command and open a stream in one call.
-     *
-     * @param sessionId - Target session ID
-     * @param command - Command fields (kind, to, body, etc.)
-     * @returns Receipt and stream info
-     */
-    async sendAndStream(sessionId, command) {
-        return (await this.request("comms/send", {
-            session_id: sessionId,
-            stream: "reserve_interaction",
-            ...command,
-        }));
-    }
-    /**
-     * List peers visible to a session's comms runtime.
-     *
-     * @param sessionId - Target session ID
-     * @returns Object with `{ peers: [...] }`
-     */
-    async peers(sessionId) {
-        return (await this.request("comms/peers", {
-            session_id: sessionId,
-        }));
-    }
-    // --- Internal ---
-    /**
-     * Normalize a CapabilityStatus from the wire.
-     * Available is the string "Available", but other variants are
-     * externally-tagged objects like {"DisabledByPolicy": {"description": "..."}}.
-     * We normalize to the variant name string.
-     */
-    static normalizeStatus(raw) {
-        if (typeof raw === "string")
-            return raw;
-        if (typeof raw === "object" && raw !== null) {
-            const keys = Object.keys(raw);
-            return keys[0] ?? "Unknown";
-        }
-        return String(raw);
-    }
-    request(method, params) {
-        if (!this.process?.stdin) {
-            throw new MeerkatError("NOT_CONNECTED", "Client not connected");
-        }
-        this.requestId++;
-        const id = this.requestId;
-        const request = {
-            jsonrpc: "2.0",
-            id,
-            method,
-            params,
-        };
-        return new Promise((resolve, reject) => {
-            this.pendingRequests.set(id, { resolve, reject });
-            this.process.stdin.write(JSON.stringify(request) + "\n");
-        });
-    }
-    checkVersionCompatible(server, client) {
-        try {
-            const s = server.split(".").map(Number);
-            const c = client.split(".").map(Number);
-            if (s[0] === 0 && c[0] === 0)
-                return s[1] === c[1];
-            return s[0] === c[0];
-        }
-        catch {
-            return false;
-        }
-    }
-    parseRunResult(data) {
-        const usage = data.usage;
-        return {
-            session_id: String(data.session_id ?? ""),
-            session_ref: data.session_ref == null ? undefined : String(data.session_ref),
-            text: String(data.text ?? ""),
-            turns: Number(data.turns ?? 0),
-            tool_calls: Number(data.tool_calls ?? 0),
-            usage: {
-                input_tokens: Number(usage?.input_tokens ?? 0),
-                output_tokens: Number(usage?.output_tokens ?? 0),
-                total_tokens: Number(usage?.total_tokens ?? 0),
-                cache_creation_tokens: usage?.cache_creation_tokens,
-                cache_read_tokens: usage?.cache_read_tokens,
-            },
-            structured_output: data.structured_output,
-            schema_warnings: data.schema_warnings,
-        };
+        if (options.isolated)
+            args.push("--isolated");
+        if (options.realmId)
+            args.push("--realm", options.realmId);
+        if (options.instanceId)
+            args.push("--instance", options.instanceId);
+        if (options.realmBackend)
+            args.push("--realm-backend", options.realmBackend);
+        if (options.stateRoot)
+            args.push("--state-root", options.stateRoot);
+        if (options.contextRoot)
+            args.push("--context-root", options.contextRoot);
+        if (options.userConfigRoot)
+            args.push("--user-config-root", options.userConfigRoot);
+        return args;
     }
 }
 //# sourceMappingURL=client.js.map