@sagentlab/navarch-runtime 0.1.116 → 0.1.118

package/dist/muse-mcp-bridge.cjs

@@ -0,0 +1,167 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridgeMuseMcp = bridgeMuseMcp;
+exports.main = main;
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = __importDefault(require("node:path"));
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * A tools-only MCP transport bridge. Muse receives only this executable and
+ * an expiring task-owned file path. Credentials never enter MSP commands or
+ * Muse's durable journal. No new listener, OAuth flow or persistent grant.
+ */
+async function bridgeMuseMcp(downstream, upstream) {
+    let initializeId;
+    let ending = false;
+    let failed = false;
+    let finish;
+    const done = new Promise((resolve) => { finish = resolve; });
+    const close = async () => {
+        if (ending)
+            return;
+        ending = true;
+        await Promise.allSettled([upstream.close(), downstream.close()]);
+        finish();
+    };
+    const fail = () => {
+        if (ending)
+            return;
+        failed = true;
+        // Upstream errors can contain endpoints, headers or provider response
+        // bodies. Never forward/log them to Muse or its retained transcript.
+        process.stderr.write("Navarch MCP bridge connection failed.\n");
+        void close();
+    };
+    const reject = (message, target) => {
+        if ("id" in message)
+            void target.send({ jsonrpc: "2.0", id: message.id, error: { code: -32601, message: "This Navarch bridge supports tools only" } }).catch(fail);
+    };
+    downstream.onmessage = (message) => {
+        if (!("method" in message)) {
+            reject(message, downstream);
+            return;
+        }
+        if (!["initialize", "notifications/initialized", "notifications/cancelled", "ping", "tools/list", "tools/call"].includes(message.method)) {
+            reject(message, downstream);
+            return;
+        }
+        if (message.method === "initialize" && "id" in message) {
+            initializeId = message.id;
+            // Do not advertise sampling, elicitation, roots, or any other route for
+            // an upstream server to ask the unattended model to approve something.
+            message = { ...message, params: { ...message.params, capabilities: {} } };
+        }
+        void upstream.send(message).catch(fail);
+    };
+    upstream.onmessage = (message) => {
+        let outgoing = message;
+        if ("method" in message && "id" in message) {
+            reject(message, upstream);
+            return;
+        }
+        if ("method" in message && !["notifications/tools/list_changed", "notifications/progress", "notifications/cancelled"].includes(message.method))
+            return;
+        if ("error" in message) {
+            outgoing = { jsonrpc: "2.0", id: message.id, error: { code: message.error.code, message: "Navarch MCP upstream request failed" } };
+        }
+        if ("result" in message && message.id === initializeId) {
+            const result = object(message.result);
+            if (!result || typeof result.protocolVersion !== "string") {
+                fail();
+                return;
+            }
+            const http = upstream;
+            http.setProtocolVersion?.(result.protocolVersion);
+            outgoing = { ...message, result: { ...result, capabilities: { ...(object(result.capabilities)?.tools ? { tools: object(result.capabilities).tools } : {}) } } };
+        }
+        void downstream.send(outgoing).catch(fail);
+    };
+    upstream.onerror = fail;
+    downstream.onerror = fail;
+    upstream.onclose = () => { void close(); };
+    downstream.onclose = () => { void close(); };
+    const onEnd = () => { void close(); };
+    process.stdin.once("end", onEnd);
+    process.once("SIGTERM", onEnd);
+    process.once("SIGINT", onEnd);
+    try {
+        await upstream.start();
+        await downstream.start();
+        await done;
+        if (failed)
+            throw new Error("Navarch MCP bridge connection failed");
+    }
+    finally {
+        await close();
+        process.stdin.removeListener("end", onEnd);
+        process.removeListener("SIGTERM", onEnd);
+        process.removeListener("SIGINT", onEnd);
+    }
+}
+async function main(args = process.argv.slice(2)) {
+    try {
+        const [configPath, name, digest] = args;
+        if (!configPath || !node_path_1.default.isAbsolute(configPath) || !name || !digest || !/^[a-f0-9]{64}$/.test(digest) || args.length !== 3)
+            throw new Error("Invalid bridge arguments");
+        const directory = await (0, promises_1.stat)(node_path_1.default.dirname(configPath));
+        if (!directory.isDirectory() || (directory.mode & 0o077) !== 0)
+            throw new Error("Non-private bridge directory");
+        const file = await (0, promises_1.open)(configPath, node_fs_1.constants.O_RDONLY | (node_fs_1.constants.O_NOFOLLOW ?? 0));
+        let content;
+        try {
+            const metadata = await file.stat();
+            if (!metadata.isFile() || (metadata.mode & 0o077) !== 0 || metadata.size > 1024 * 1024)
+                throw new Error("Non-private bridge file");
+            content = await file.readFile("utf8");
+        }
+        finally {
+            await file.close();
+        }
+        // Bind the transport/endpoint/headers to the exact configuration chosen
+        // by Navarch. A later file replacement cannot redirect a credential.
+        if ((0, node_crypto_1.createHash)("sha256").update(content).digest("hex") !== digest)
+            throw new Error("Bridge configuration changed");
+        const source = object(JSON.parse(content));
+        const server = object(source?.[name]);
+        if (!server)
+            throw new Error("Missing MCP server");
+        const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+        let upstream;
+        if (server.transport === "streamableHttp" && typeof server.url === "string") {
+            const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+            const endpoint = new URL(server.url);
+            if (!["http:", "https:"].includes(endpoint.protocol) || endpoint.username || endpoint.password)
+                throw new Error("Invalid MCP URL");
+            upstream = new StreamableHTTPClientTransport(endpoint, {
+                requestInit: { headers: server.headers },
+                // The SDK's SSE GET path does not inherit requestInit.redirect.
+                // Enforce the exact authorized endpoint for every HTTP method.
+                fetch: (input, init) => {
+                    const url = new URL(input);
+                    if (url.href !== endpoint.href)
+                        return Promise.reject(new Error("MCP endpoint changed"));
+                    return fetch(input, { ...init, redirect: "error" });
+                },
+            });
+        }
+        else if (server.transport === "stdio" && typeof server.command === "string") {
+            const { StdioClientTransport, getDefaultEnvironment } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+            upstream = new StdioClientTransport({ command: server.command, args: server.args,
+                env: { ...getDefaultEnvironment(), ...server.env }, stderr: "ignore" });
+        }
+        else
+            throw new Error("Unsupported MCP transport");
+        await bridgeMuseMcp(new StdioServerTransport(), upstream);
+    }
+    catch {
+        process.stderr.write("Navarch MCP bridge could not start; check its task-owned configuration and installed runtime.\n");
+        process.exitCode = 1;
+    }
+}

package/dist/session.cjs

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSession = runSession;
 exports.toEnvMap = toEnvMap;
+const muse_cjs_1 = require("./adapters/muse.cjs");
 const node_path_1 = __importDefault(require("node:path"));
 const node_perf_hooks_1 = require("node:perf_hooks");
 const node_fs_1 = require("node:fs");
@@ -50,7 +51,7 @@ function resolveSessionExecution(config, claimed) {
         model: runtime === "codex" ? "gpt-6-astra"
             : runtime === "pi-local" ? "qwen3.8-flash-next-iq2_xs"
                 : runtime === "gemini" ? "auto"
-                    : runtime === "antigravity" || runtime === "opencode" || runtime === "acp" || runtime === "qoder" ? "default"
+                    : runtime === "antigravity" || runtime === "opencode" || runtime === "acp" || runtime === "qoder" || runtime === "muse" ? "default"
                         : "claude-opus-5-5",
         reasoning_effort: "medium",
     };
@@ -447,7 +448,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         if (!config.mcpConfigPath && config.sandboxMode === "host"
             && ["build", "verify", "qa"].includes(task.task_type)
             && task.required_capabilities?.includes("browser-use")
-            && ["codex", "claude-code", "antigravity", "opencode", "acp"].includes(runtime)) {
+            && ["codex", "claude-code", "antigravity", "opencode", "acp", "muse"].includes(runtime)) {
             browserEvidence = await (0, browser_evidence_cjs_1.startBrowserEvidence)({
                 apiBase: api.getBaseUrl(), machineToken: api.getToken() ?? "", leaseId,
                 isActive: () => !leaseLost && !sessionClosing && !deps.shutdownSignal?.aborted,
@@ -533,6 +534,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         let deliveryCorrectionRetries = 0;
         let deliveredPullRequest = false;
         let antigravityResume;
+        let museSessionId;
         while (true) {
             // Guidance can arrive while the worktree/sandbox is being prepared.
             // It is already included in deliveredGuidance, so clear the pending
@@ -563,6 +565,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 : await (0, adapter_watchdog_cjs_1.runWithActivityWatchdog)(adapter, {
                     prompt: runPrompt,
                     mcpConfigPath,
+                    mcpMetadataDir: workDir,
                     bin,
                     extraArgs,
                     model: execution.model,
@@ -573,6 +576,8 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     codexGuardArgs,
                     antigravityHostGuard: runtime === "antigravity" && config.sandboxMode === "host" && config.worktreeGuard,
                     antigravityResume,
+                    museHostGuard: config.sandboxMode === "host" && config.worktreeGuard,
+                    resumeSessionId: runtime === "muse" ? museSessionId : undefined,
                     opencodeHostGuard: runtime === "opencode" && config.sandboxMode === "host" && config.worktreeGuard,
                     // ACP requires an absolute session cwd. Docker mounts the worktree at
                     // this same absolute path, while the other Docker adapters ignore cwd.
@@ -596,6 +601,8 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 executionReport = { ...executionReport, model: turnResult.model };
             }
             antigravityResume = turnResult.antigravityResume;
+            if (runtime === "muse")
+                museSessionId = turnResult.agentSessionId;
             attempts.push(turnResult);
             liveStdout = "";
             liveTranscript.markDirty();
@@ -626,14 +633,25 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 log.warn(`session ${leaseId} stopped without completion because its lease is no longer active.`);
                 return sessionOutcome;
             }
-            if (!capacityLimit && !authFailure && !leaseLost && !turnResult.timedOut && pendingGuidance.length > 0)
+            if (!capacityLimit && !authFailure && !leaseLost && !turnResult.timedOut && pendingGuidance.length > 0) {
+                // Muse cancellation kills the whole task-owned container. Guidance
+                // still holds the lease, so restart that SAME container and restore
+                // its tmpfs environment before the next turn; never launch into a
+                // stopped sandbox or substitute an unisolated host process.
+                if (runtime === "muse" && sandbox && turnResult.killedByLeaseLoss) {
+                    const restarted = await sandbox_cjs_1.nodeCommandRunner.run("docker", ["start", sandbox.name], { timeoutMs: 10_000 });
+                    if (restarted.code !== 0)
+                        throw new Error("Could not restart the task-owned Muse sandbox after guidance.");
+                    await sandbox.injectEnv(sessionEnv);
+                }
                 continue;
+            }
             const result = {
                 ...turnResult,
-                tokensIn: sumReportedUsage(attempts, "tokensIn"),
-                tokensOut: sumReportedUsage(attempts, "tokensOut"),
-                cacheHitTokensIn: sumReportedUsage(attempts, "cacheHitTokensIn"),
-                costUsd: sumReportedUsage(attempts, "costUsd"),
+                tokensIn: sumReportedUsage(attempts, "tokensIn", runtime === "muse"),
+                tokensOut: sumReportedUsage(attempts, "tokensOut", runtime === "muse"),
+                cacheHitTokensIn: sumReportedUsage(attempts, "cacheHitTokensIn", runtime === "muse"),
+                costUsd: runtime === "muse" ? (0, muse_cjs_1.sumMuseSessionCost)(attempts) : sumReportedUsage(attempts, "costUsd"),
             };
             const mapping = (0, exit_conditions_cjs_1.mapExitCondition)({
                 ...result,
@@ -947,6 +965,8 @@ function adapterCommand(config, runtime) {
             return { bin: config.piBin, extraArgs: config.piExtraArgs };
         case "qoder":
             return { bin: config.qoderBin, extraArgs: config.qoderExtraArgs };
+        case "muse":
+            return { bin: config.museBin, extraArgs: config.museExtraArgs };
     }
 }
 /**
@@ -964,7 +984,9 @@ function cacheSplitFields(tokensIn, cacheHitTokensIn) {
     const hit = Math.min(cacheHitTokensIn, tokensIn);
     return { cache_hit_input_tokens: hit, cache_miss_input_tokens: tokensIn - hit };
 }
-function sumReportedUsage(attempts, key) {
+function sumReportedUsage(attempts, key, requireComplete = false) {
+    if (requireComplete && attempts.some((attempt) => attempt[key] === undefined))
+        return undefined;
     const reported = attempts.flatMap((attempt) => {
         const value = attempt[key];
         return value === undefined ? [] : [value];

package/node_modules/@muse-code/sdk/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@muse-code/sdk/README.md

@@ -0,0 +1,88 @@
+# `@muse-code/sdk`
+
+The TypeScript SDK for Muse Code: a typed Node client for driving a Muse Code
+agent over the Muse Session Protocol (MSP).
+
+- Spawn a `muse serve` host, open and resume sessions, and send turns.
+- Stream a turn's items and text deltas as async iterators; await the turn's
+  server-authored outcome.
+- Answer tool-approval requests with a handler you register — or register
+  none and run under the server's own default-deny.
+- A client-side fold keeps a live, typed view of the session — items, session
+  state, pending commands — with gap recovery after dropped deliveries and
+  safe same-command retry that can never double-submit.
+
+**Zero runtime dependencies**: pure TypeScript over the Node standard
+library. The MSP wire declarations are bundled into the package, so nothing
+else is needed to typecheck against it.
+
+## Install
+
+```sh
+npm install @muse-code/sdk
+npm install -D @types/node   # required for TypeScript consumers
+```
+
+Node 20 or newer. `@types/node` is declared as an **optional peer
+dependency**: a JavaScript consumer needs nothing, while a TypeScript
+consumer installs it explicitly — without it the declarations that name
+`ChildProcess`, `Readable` and friends do not resolve.
+
+You also need the Muse Code CLI: a `muse` binary on `PATH`, or an explicit
+path passed at spawn time.
+
+**This package versions in lockstep with Muse Code**: the SDK version is the
+Muse Code release it ships with — `@muse-code/sdk X.Y.Z` pairs with Muse Code
+`X.Y.Z`. The stable MSP surface follows the product's compatibility posture:
+evolution is additive, and a breaking change follows a documented deprecation
+and changelog path. Surfaces marked experimental (`x-msp-openness`)
+may change or be removed with a changelog entry and no deprecation window. Pin an
+exact version, and read the changelog before moving off it.
+
+## Use
+
+```ts
+import { MuseClient } from "@muse-code/sdk";
+
+const client = await MuseClient.spawn({
+  museBin: "muse",
+  args: ["serve"],
+  clientInfo: { name: "my-app", version: "1.0.0" },
+});
+
+const session = await client.startSession({ workspaceRoot: process.cwd() });
+
+const turn = await session.sendUserTurn({
+  input: [{ type: "text", text: "Summarize this repository." }],
+});
+for await (const item of turn.items()) console.log(item);
+await turn.completed;
+
+await client.close();
+```
+
+`turn.items()` replays what the session already holds before its live tail;
+`turn.deltas()` is live-only. `turn.completed` settles on every exit, so an
+awaited turn can never hang on a session that ended without an answer.
+
+To approve tool use programmatically, register a handler on the session;
+approval choices are server-minted, and a decision the request never offered
+is refused and reported rather than sent:
+
+```ts
+session.onApproval(async (request) => ({
+  choiceId: request.availableChoices[0].choiceId,
+}));
+```
+
+Status: developer preview. The facade — spawn, session open/resume, turns,
+approvals, and recovery after dropped deliveries — is complete and covered by
+the conformance suites in the source repository.
+
+## Documentation
+
+- Guides, cookbook recipes, and the protocol reference:
+  <https://meta-models.github.io/muse-code-sdk/>
+- TypeScript API reference:
+  <https://meta-models.github.io/muse-code-sdk/next/generated/sdk/>
+- Source and issues: <https://github.com/meta-models/muse-code-sdk>

package/node_modules/@muse-code/sdk/dist/src/connection/connection.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Duplex-agnostic MSP NDJSON connection (spec 14990 FR-012/014/015/016).
+ *
+ * The transport supplies decoded UTF-8 chunks. Chunks may be empty and may
+ * split anywhere — including mid surrogate pair: the byte accounting below
+ * reconciles split pairs (FR-012(a)), so transports need not align chunks
+ * to character boundaries. The Node child-process binding — which sets
+ * stdout's encoding before implementing this interface — is one
+ * well-behaved transport, not the general guarantee.
+ */
+import type { ErrorKind, ErrorObject, Notification, Request, RequestId } from "../msp.js";
+/**
+ * The two-way text stream a `Connection` speaks MSP over.
+ *
+ * Implement it to run the protocol over any duplex channel: yield decoded
+ * UTF-8 chunks on `incoming` and accept outgoing frames through `write`.
+ * Chunks may be empty and may split anywhere — even mid surrogate pair — the
+ * connection reassembles them. If your transport decodes bytes itself, use a
+ * streaming decoder: a multi-byte character split across two byte chunks and
+ * decoded separately becomes a replacement character before the connection
+ * ever sees it. The SDK's spawned child-process stdio binding sets the stream
+ * encoding, so it is safe, and is one ready-made implementation.
+ */
+export interface DuplexTransport {
+    readonly incoming: AsyncIterable<string>;
+    write(chunk: string): Promise<void>;
+    /**
+     * `flushed` settles once every frame the connection had accepted when
+     * `close()` was called has been HANDED to `write()` — submission, not
+     * completion. A process-owning transport waits for it inside its own
+     * shutdown budget before ending the peer's input, so a frame still queued
+     * on a microtask is not dropped; it is never GATED by it, because
+     * completion is exactly what a wedged peer withholds. Optional and
+     * additive: a transport that ignores it behaves as before.
+     */
+    close?(flushed?: Promise<void>): void | Promise<void>;
+}
+/**
+ * Module-private friend seam (never on the package barrel, like spawn.ts's
+ * `ownedTransport`): the submission tail a process-owning transport adopts as
+ * its DEFAULT `flushed`, so a close routed around this class — e.g. the
+ * public `child.close()` — gets the same step 0 (PR #22819 round 4).
+ */
+export declare const submissionTail: unique symbol;
+/**
+ * Module-private friend seam, like {@link submissionTail}: a request whose
+ * promise also yields the exact response frame it settled on, so a caller
+ * that refuses a successful result (the handshake's schema-fingerprint
+ * check) can put the whole refused frame on `ProtocolError.line`, the same
+ * value every other refusal carries (#50588 review).
+ */
+export declare const requestWithFrame: unique symbol;
+/** What {@link requestWithFrame} resolves with: the result and its wire line. */
+export interface FramedResult {
+    readonly result: Record<string, unknown>;
+    readonly line: string;
+}
+/**
+ * Tuning knobs for a `Connection`. Every option is optional: the defaults
+ * suit a spawned host, so most applications never pass this at all.
+ */
+export interface ConnectionOptions {
+    readonly frameLimitBytes?: number;
+    readonly mintCommandId?: () => string;
+    /** Injectable for deterministic transcript clients; values must be unique in flight. */
+    readonly mintRequestId?: () => RequestId;
+}
+/**
+ * Per-command overrides for `Connection.command`: pin a command id so a
+ * reconnect can replay the same logical command, cap the attempt count, or
+ * supply your own retry delay.
+ */
+export interface CommandOptions {
+    /** Reuse this id for a reconnect/replay of the same logical command. */
+    readonly commandId?: string;
+    /** Total attempts, including the first. */
+    readonly maxAttempts?: number;
+    /** Injectable so deterministic tests do not sleep. */
+    readonly retryDelay?: (attempt: number, error: MspError) => Promise<void>;
+}
+/** Handles one server-initiated request and resolves with the result to send back. */
+export type ServerRequestHandler = (request: Request) => Promise<Record<string, unknown>>;
+/** Receives every server notification, in arrival order. */
+export type NotificationHandler = (notification: Notification) => void;
+/** Receives each framing or correlation violation the connection detects on its inbound stream. */
+export type ProtocolErrorHandler = (error: ProtocolError) => void;
+/** The one typed error family consumers branch on (INV-012). */
+export declare class MspError extends Error {
+    readonly code: number;
+    readonly kind: ErrorKind;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly retryable: boolean | undefined;
+    constructor(error: ErrorObject);
+}
+/** A local framing/correlation violation, never a server-authored MSP error. */
+export declare class ProtocolError extends Error {
+    /**
+     * The inbound frame (wire line) the violation was detected on, when there
+     * is one — the whole line, e.g. the response a pending request refused;
+     * an oversized frame is cut to the frame limit. Absent for local state
+     * errors (closed connection, EOF) that no frame caused.
+     */
+    readonly line: string | undefined;
+    constructor(message: string, line?: string);
+}
+/** Create the SDK-owned UUIDv7 command-id source for a connection/client. */
+export declare function createUuidV7Mint(): () => string;
+/**
+ * One MSP connection over newline-delimited JSON.
+ *
+ * The connection sends your requests and commands, correlates their
+ * responses, enforces the frame-size limit, and hands inbound notifications
+ * and server requests to the handlers you register. It is transport-agnostic:
+ * pair it with any `DuplexTransport`. Most applications never build one
+ * directly — `MuseClient.spawn` or `spawnMspConnection` does it for you;
+ * reach for a bare `Connection` when you need the raw notification feed or
+ * your own transport.
+ */
+export declare class Connection {
+    #private;
+    constructor(transport: DuplexTransport, options?: ConnectionOptions);
+    get closed(): Promise<void>;
+    /** See {@link submissionTail}. */
+    [submissionTail](): Promise<void>;
+    request(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** See {@link requestWithFrame}. */
+    [requestWithFrame](method: string, params?: Record<string, unknown>): Promise<FramedResult>;
+    /**
+     * Take one id from THIS connection's single `commandId` minter (INV-013).
+     *
+     * Exposed for the callers that need the id BEFORE the ack: `sendUserTurn`
+     * records its optimistic SS4.13 entry under it, and an entry created only on
+     * the ack is invisible for exactly the window it exists to cover. The
+     * alternative was a facade-side mint, which is the second minter INV-013
+     * forbids — delegating here keeps the single-minter property intact and
+     * preserves the injected `mintCommandId` seam for deterministic transcripts.
+     *
+     * Pair it with `command(..., { commandId })`, which reuses the id instead of
+     * minting a second one.
+     */
+    mintCommandId(): string;
+    notify(method: string, params?: Record<string, unknown>): void;
+    onServerRequest(handler: ServerRequestHandler): void;
+    onNotification(handler: NotificationHandler): void;
+    onProtocolError(handler: ProtocolErrorHandler): void;
+    flush(): Promise<void>;
+    command(method: string, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}