@sentropic/h2a-runtime 0.98.6 → 0.98.7-rc.2

package/dist/claude-code-cli-runner.js

@@ -0,0 +1,659 @@
+/**
+ * Claude Code CLI Runner: executes the official `claude` CLI (resolved
+ * from `PATH` at each attempt) with NDJSON streaming, strict isolation,
+ * process reaping, credential read-back, and static error handling.
+ * No version pin, no digest fingerprint, no attestation: no other seat
+ * carries such machinery, and none is claimed here.
+ */
+import { spawn } from "node:child_process";
+import { delimiter, isAbsolute, join } from "node:path";
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { buildIsolatedEnvironment, cleanClaudeRunSandbox, createClaudeRunSandbox, recordChildPidInSandbox, verifyCredentialNotRewritten, } from "./claude-code-cli-isolation.js";
+import { checkTokenTtlAdmission, reapProcessTree, sweepOrphanSandboxes, } from "./claude-code-cli-lifecycle.js";
+/**
+ * Returns true for a regular file with the execute bit set. A directory or
+ * a non-executable file named `claude` earlier on PATH must never mask the
+ * real CLI (the failure would otherwise surface only at spawn).
+ */
+function isExecutableRegularFile(candidate) {
+    try {
+        accessSync(candidate, constants.X_OK);
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the official `claude` CLI from `PATH` (Linux-first; Windows
+ * resolves `claude` and `claude.exe` only — `.cmd`/`.bat` shims are
+ * excluded because spawn launches without a shell). Returns the first
+ * absolute regular executable candidate, or undefined when none is found.
+ * Never throws, never executes anything.
+ */
+export function resolveClaudeBinaryFromPath(env = process.env) {
+    const pathValue = env.PATH ?? "";
+    if (!pathValue)
+        return undefined;
+    const extensions = process.platform === "win32" ? ["", ".exe"] : [""];
+    for (const dir of pathValue.split(delimiter)) {
+        if (!dir || !isAbsolute(dir))
+            continue;
+        for (const extension of extensions) {
+            const candidate = join(dir, `claude${extension}`);
+            try {
+                if (isExecutableRegularFile(candidate))
+                    return candidate;
+            }
+            catch {
+                // Unreadable directory entry: try the next candidate.
+            }
+        }
+    }
+    return undefined;
+}
+export const DEFAULT_MAX_FRAME_BYTES = 65536; // 64 KiB
+export const DEFAULT_MAX_TOTAL_BYTES = 10 * 1024 * 1024; // 10 MiB
+export const DEFAULT_RUN_DEADLINE_MS = 120_000; // 2 minutes
+/**
+ * Strict allowlist of typed tool identifiers permitted for the CLI --tools flag.
+ * Caller-provided tool names are never passed to --tools.
+ */
+export const ALLOWED_TYPED_TOOL_IDENTIFIERS = [];
+/**
+ * Known built-in tools of the Claude CLI. Callers cannot request these names.
+ */
+export const BUILTIN_CLI_TOOLS = new Set([
+    "Bash",
+    "BashOutput",
+    "Edit",
+    "MultiEdit",
+    "Read",
+    "Write",
+    "Glob",
+    "Grep",
+    "WebFetch",
+    "WebSearch",
+    "Agent",
+    "Skill",
+    "TodoWrite",
+    "NotebookEdit",
+    "KillShell",
+    "ExitPlanMode",
+]);
+/**
+ * Top-level NDJSON frame types emitted by the official CLI stream-json
+ * output that are known transport or lifecycle events and should not be failed as unknown.
+ */
+export const KNOWN_IGNORED_TOP_LEVEL_TYPES = new Set([
+    "system",
+    "rate_limit_event",
+    "tool_use_summary",
+    "user",
+    "auth_status",
+    "keep_alive",
+    "control_request",
+]);
+export class OfficialClaudeCodeCliRunner {
+    binaryPath;
+    capabilities;
+    maxFrameBytes;
+    maxTotalBytes;
+    timeoutMs;
+    spawnFn;
+    now;
+    sandboxRootDir;
+    allowedCliTools;
+    killProcessTreeFn;
+    reapProcessTreeFn;
+    constructor(options = {}) {
+        this.binaryPath = options.binaryPath ?? "";
+        this.capabilities = options.capabilities;
+        this.maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
+        this.maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_RUN_DEADLINE_MS;
+        this.spawnFn = options.spawnFn ?? spawn;
+        this.now = options.now ?? Date.now;
+        this.sandboxRootDir = options.sandboxRootDir;
+        this.allowedCliTools = options.allowedCliTools;
+        this.killProcessTreeFn = options.killProcessTreeFn;
+        this.reapProcessTreeFn = options.reapProcessTreeFn;
+    }
+    /**
+     * Resolve the spawn candidate: the explicit override when set,
+     * otherwise the official `claude` CLI from `PATH` (re-resolved at each
+     * attempt, so a later CLI install is picked up without a restart).
+     * Generic spawn safety only — absolute resolved path, regular executable
+     * file, supported protocol. No version pin, no fingerprint, no attestation.
+     */
+    resolveBinary() {
+        const candidate = this.binaryPath || resolveClaudeBinaryFromPath() || "";
+        if (!candidate || !isAbsolute(candidate)) {
+            throw new Error("Claude CLI candidate unqualified: official claude CLI not found on PATH");
+        }
+        if (!existsSync(candidate)) {
+            throw new Error("Claude CLI candidate unqualified: binary does not exist");
+        }
+        if (!isExecutableRegularFile(candidate)) {
+            throw new Error("Claude CLI candidate unqualified: binary not executable");
+        }
+        return candidate;
+    }
+    /**
+     * Refuse to spawn unless the candidate resolves and the mesh protocol
+     * matches. Anything less is refused before spawn.
+     */
+    qualifyBinary() {
+        this.resolveBinary();
+        if (!this.capabilities || this.capabilities.protocol !== "claude-code-stream-json-v1") {
+            throw new Error("Claude CLI candidate unqualified: unsupported protocol");
+        }
+    }
+    run(input) {
+        const runController = new AbortController();
+        const abortHandler = () => runController.abort();
+        input.signal.addEventListener("abort", abortHandler, { once: true });
+        const runState = { earlyClosed: false };
+        const gen = this.runInternal(input, runController, abortHandler, runState);
+        const iterator = {
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+            next() {
+                return gen.next();
+            },
+            return(val) {
+                runState.earlyClosed = true;
+                runController.abort();
+                return gen.return(val);
+            },
+            throw(err) {
+                runState.earlyClosed = true;
+                runController.abort();
+                return gen.throw(err);
+            },
+        };
+        return iterator;
+    }
+    async *runInternal(input, runController, abortHandler, runState) {
+        // 1. Candidate qualification preflight
+        this.qualifyBinary();
+        // Caller abort before any work: refuse without spawning.
+        if (input.signal.aborted || runController.signal.aborted) {
+            yield { type: "error" };
+            return;
+        }
+        // Tool preflight: requests with tools are refused because caller tools would be silently
+        // ignored without client-side tool transport (local MCP qualification).
+        if (input.request.tools && input.request.tools.length > 0) {
+            for (const t of input.request.tools) {
+                if (BUILTIN_CLI_TOOLS.has(t.name)) {
+                    throw new Error("Claude seat spawn refused: built-in tool names cannot be requested by caller");
+                }
+            }
+            throw new Error("Claude seat spawn refused: requests with tools are rejected (client tool transport is not available; tools would be ignored)");
+        }
+        // Orphan sweep at each runner start (brief invariant 6): stale dead
+        // runs are reaped before a new sandbox is created. Best-effort: a
+        // sweep failure never blocks the run.
+        try {
+            const sweepResult = await sweepOrphanSandboxes(this.sandboxRootDir, {
+                onUnprovenChild: (unproven) => {
+                    process.stderr.write(`[claude-orphan-sweep] unproven child ${unproven.childPid} in ${unproven.runDir} skipped: ${unproven.reason}\n`);
+                },
+            });
+            if (sweepResult.skippedUnprovenChild) {
+                process.stderr.write(`[claude-orphan-sweep] skipped ${sweepResult.skippedUnprovenChild} unproven child process(es)\n`);
+            }
+        }
+        catch {
+            // Sweep is hygiene, not admission.
+        }
+        // 2. Admission and TTL checks
+        const admission = checkTokenTtlAdmission(input.access.expiresAt, this.now());
+        if (!admission.admitted) {
+            yield { type: "error" };
+            return;
+        }
+        // 3. Create isolated sandbox
+        const binaryPath = this.resolveBinary();
+        const sandbox = createClaudeRunSandbox({
+            access: input.access,
+            ...(this.sandboxRootDir ? { rootDir: this.sandboxRootDir } : {}),
+        });
+        const env = buildIsolatedEnvironment(sandbox, process.env, {
+            binaryPath,
+        });
+        // 4. Construct candidate arguments. No --include-partial-messages:
+        // partial stream_event deltas would duplicate the final assistant
+        // message text. The parser still accepts stream_event envelopes
+        // defensively, but steady state carries each text once via assistant
+        // message.content[].
+        let toolsArg = "";
+        if (this.allowedCliTools && this.allowedCliTools.length > 0) {
+            const allowed = this.allowedCliTools.filter((t) => ALLOWED_TYPED_TOOL_IDENTIFIERS.includes(t));
+            toolsArg = allowed.join(",");
+        }
+        const args = [
+            "-p",
+            "--input-format", "stream-json",
+            "--output-format", "stream-json",
+            "--verbose",
+            "--no-session-persistence",
+            "--setting-sources", "",
+            "--settings", sandbox.settingsPath,
+            "--strict-mcp-config",
+            "--mcp-config", sandbox.mcpConfigPath,
+            "--tools", toolsArg,
+            "--disable-slash-commands",
+            "--permission-mode", "dontAsk",
+            "--model", input.request.modelId,
+        ];
+        let childPid = 0;
+        let terminalResultEmitted = false;
+        let streamFailed = false;
+        let onRunAbort = null;
+        // Check for abort that fired during preflight, sweep, or sandbox creation
+        if (input.signal.aborted || runController.signal.aborted) {
+            runController.abort();
+            try {
+                cleanClaudeRunSandbox(sandbox);
+            }
+            catch { }
+            yield { type: "error" };
+            return;
+        }
+        let timeoutTimer = null;
+        if (this.timeoutMs > 0 && Number.isFinite(this.timeoutMs)) {
+            timeoutTimer = setTimeout(() => {
+                runController.abort();
+            }, this.timeoutMs);
+        }
+        try {
+            const child = this.spawnFn(binaryPath, args, {
+                cwd: sandbox.cwdDir,
+                env,
+                stdio: ["pipe", "pipe", "pipe"],
+                detached: true,
+            });
+            childPid = child.pid ?? 0;
+            if (!childPid) {
+                yield { type: "error" };
+                return;
+            }
+            recordChildPidInSandbox(sandbox, childPid);
+            // Drain stderr so a verbose child can never block on a full pipe.
+            // Stderr is bounded and never forwarded to the caller.
+            let stderrBytes = 0;
+            child.stderr?.on("data", (chunk) => {
+                stderrBytes += chunk.length;
+                if (stderrBytes > this.maxTotalBytes) {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        // Already dead; reaping below settles the run.
+                    }
+                }
+            });
+            const queue = [];
+            let notifyNext = null;
+            const pushQueue = (item) => {
+                queue.push(item);
+                if (notifyNext) {
+                    const fn = notifyNext;
+                    notifyNext = null;
+                    fn();
+                }
+            };
+            // Abort, deadline, and early-close must end work even while a read is
+            // pending: kill the whole child tree and wake the consumer loop.
+            const killChildTree = () => {
+                if (this.killProcessTreeFn && childPid > 0) {
+                    this.killProcessTreeFn(childPid, "SIGKILL");
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        // Already dead
+                    }
+                    return;
+                }
+                if (childPid > 0) {
+                    try {
+                        process.kill(-childPid, "SIGKILL");
+                        return;
+                    }
+                    catch {
+                        // Not our group leader (mocks) or already dead: fall through.
+                    }
+                }
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // Already dead; reaping below settles the run.
+                }
+            };
+            onRunAbort = () => {
+                killChildTree();
+                if (notifyNext) {
+                    const wake = notifyNext;
+                    notifyNext = null;
+                    wake();
+                }
+            };
+            runController.signal.addEventListener("abort", onRunAbort);
+            // Stream request NDJSON onto stdin: one stream-json line per message
+            // ({type:"user",message:{role,content}}), the documented --input-format
+            // stream-json shape (binary shows message.role user + content; the
+            // assistant leg is symmetric). Never argv, never env.
+            for (const message of input.request.messages) {
+                const role = message.role === "assistant" ? "assistant" : "user";
+                child.stdin?.write(JSON.stringify({ type: role, message: { role, content: message.content } }) + "\n");
+            }
+            child.stdin?.end();
+            // Read stdout stream
+            let stdoutBuffer = "";
+            let totalBytesReceived = 0;
+            let pendingResult = null;
+            let terminalSeen = false;
+            let toolUseSeen = false;
+            const partialToolInputs = new Map();
+            const blockKinds = new Map();
+            // Frame shapes of the official CLI --output-format stream-json
+            // (verified statically against the local binary: stream_event x72 with
+            // content_block_start/delta/stop and message_start/delta/stop inner
+            // events, assistant frames carrying message.content[], result frames
+            // carrying subtype/is_error/usage/total_cost_usd; no live call made).
+            // Unknown top-level types, second terminals, and post-terminal frames
+            // are refused: an invented shape is never silently accepted.
+            const failFrame = () => {
+                streamFailed = true;
+                pushQueue({ event: { type: "error" } });
+            };
+            const parseAssistantMessage = (message) => {
+                if (!message || typeof message !== "object")
+                    return failFrame();
+                const content = message.content;
+                if (!Array.isArray(content))
+                    return failFrame();
+                for (const block of content) {
+                    if (!block || typeof block !== "object")
+                        return failFrame();
+                    const typed = block;
+                    if (typed.type === "text" && typeof typed.text === "string") {
+                        if (typed.text)
+                            pushQueue({ event: { type: "text_delta", text: typed.text } });
+                    }
+                    else if (typed.type === "tool_use" &&
+                        typeof typed.id === "string" &&
+                        typeof typed.name === "string") {
+                        toolUseSeen = true;
+                        pushQueue({
+                            event: { type: "tool_use", id: typed.id, name: typed.name, input: typed.input ?? {} },
+                        });
+                    }
+                    else if (typed.type === "thinking" || typed.type === "redacted_thinking") {
+                        // Reasoning traces are never forwarded.
+                    }
+                    else {
+                        return failFrame();
+                    }
+                }
+            };
+            const parseStreamEvent = (event) => {
+                if (!event || typeof event !== "object")
+                    return failFrame();
+                const inner = event;
+                if (inner.type === "content_block_delta") {
+                    const delta = inner.delta;
+                    const index = typeof inner.index === "number" ? inner.index : -1;
+                    if (!delta || typeof delta.type !== "string")
+                        return;
+                    if (delta.type === "text_delta" && typeof delta.text === "string") {
+                        if (delta.text)
+                            pushQueue({ event: { type: "text_delta", text: delta.text } });
+                    }
+                    else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
+                        const slot = partialToolInputs.get(index);
+                        if (slot)
+                            slot.json += delta.partial_json;
+                    }
+                    // thinking/signature/citation deltas are hints only; the terminal
+                    // result frame governs the outcome.
+                }
+                else if (inner.type === "content_block_start") {
+                    const block = inner.content_block;
+                    const index = typeof inner.index === "number" ? inner.index : -1;
+                    if (!block || typeof block.type !== "string" || index < 0)
+                        return;
+                    blockKinds.set(index, block.type);
+                    if (block.type === "tool_use" &&
+                        typeof block.id === "string" &&
+                        typeof block.name === "string") {
+                        partialToolInputs.set(index, { id: block.id, name: block.name, json: "" });
+                    }
+                }
+                else if (inner.type === "content_block_stop") {
+                    const index = typeof inner.index === "number" ? inner.index : -1;
+                    const slot = index >= 0 ? partialToolInputs.get(index) : undefined;
+                    if (slot) {
+                        partialToolInputs.delete(index);
+                        // Empty streamed input means no partials were observed (partials
+                        // stay off at this seam): the assistant message carries the
+                        // complete block, so nothing is emitted here.
+                        if (slot.json) {
+                            let parsed;
+                            try {
+                                parsed = JSON.parse(slot.json);
+                            }
+                            catch {
+                                return failFrame();
+                            }
+                            toolUseSeen = true;
+                            pushQueue({ event: { type: "tool_use", id: slot.id, name: slot.name, input: parsed } });
+                        }
+                    }
+                    if (index >= 0)
+                        blockKinds.delete(index);
+                }
+                else if (inner.type === "message_start" ||
+                    inner.type === "message_delta" ||
+                    inner.type === "message_stop") {
+                    // Transport bookkeeping (incremental usage lives here); the
+                    // terminal result frame carries the canonical outcome.
+                }
+                // Unknown inner SSE events are ignored: they are hints, never the
+                // terminal contract. Unknown TOP-LEVEL types are refused below.
+            };
+            const parseResult = (frame) => {
+                if (terminalSeen)
+                    return failFrame();
+                terminalSeen = true;
+                if (frame.subtype !== "success" || frame.is_error === true) {
+                    return failFrame();
+                }
+                let usage;
+                if (frame.usage !== undefined) {
+                    const raw = frame.usage;
+                    if (!raw || typeof raw !== "object")
+                        return failFrame();
+                    usage = {};
+                    if (typeof raw.input_tokens === "number")
+                        usage.inputTokens = raw.input_tokens;
+                    if (typeof raw.output_tokens === "number")
+                        usage.outputTokens = raw.output_tokens;
+                    if (Object.keys(usage).length === 0)
+                        return failFrame();
+                }
+                // Stage pending terminal result: emitted only on exit agreement.
+                pendingResult = {
+                    type: "result",
+                    finishReason: toolUseSeen ? "tool_calls" : "stop",
+                    ...(usage ? { usage } : {}),
+                };
+            };
+            const parseLine = (line) => {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    return;
+                let frame;
+                try {
+                    frame = JSON.parse(trimmed);
+                }
+                catch {
+                    // Malformed frame rejects
+                    failFrame();
+                    return;
+                }
+                if (!frame || typeof frame !== "object") {
+                    failFrame();
+                    return;
+                }
+                const typed = frame;
+                if (terminalSeen) {
+                    // No frame of any kind is legal after the terminal result.
+                    failFrame();
+                    return;
+                }
+                if (KNOWN_IGNORED_TOP_LEVEL_TYPES.has(typed.type)) {
+                    // Known lifecycle/transport frames: accepted as valid, not forwarded.
+                    return;
+                }
+                else if (typed.type === "assistant") {
+                    parseAssistantMessage(typed.message);
+                }
+                else if (typed.type === "stream_event") {
+                    parseStreamEvent(typed.event);
+                }
+                else if (typed.type === "result") {
+                    parseResult(typed);
+                }
+                else if (typed.type === "error") {
+                    failFrame();
+                }
+                else {
+                    // Unknown top-level frame (including invented delta shapes): refuse.
+                    failFrame();
+                }
+            };
+            child.stdout?.on("data", (chunk) => {
+                totalBytesReceived += chunk.length;
+                if (totalBytesReceived > this.maxTotalBytes) {
+                    streamFailed = true;
+                    pushQueue({ event: { type: "error" } });
+                    child.kill("SIGKILL");
+                    return;
+                }
+                stdoutBuffer += chunk.toString("utf8");
+                const lines = stdoutBuffer.split("\n");
+                stdoutBuffer = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (Buffer.byteLength(line, "utf8") > this.maxFrameBytes) {
+                        streamFailed = true;
+                        pushQueue({ event: { type: "error" } });
+                        child.kill("SIGKILL");
+                        return;
+                    }
+                    parseLine(line);
+                }
+            });
+            child.on("error", () => {
+                streamFailed = true;
+                pushQueue({ event: { type: "error" } });
+            });
+            child.on("close", async (exitCode) => {
+                if (stdoutBuffer.trim()) {
+                    parseLine(stdoutBuffer);
+                }
+                // Verify exit agreement, credential integrity, and reap process tree
+                const credentialIntact = verifyCredentialNotRewritten(sandbox, input.access);
+                let cleanupOk = true;
+                if (childPid > 0) {
+                    if (this.reapProcessTreeFn) {
+                        await this.reapProcessTreeFn(childPid, "SIGTERM", 50);
+                    }
+                    else {
+                        await reapProcessTree(childPid, "SIGTERM", 50);
+                    }
+                }
+                try {
+                    cleanClaudeRunSandbox(sandbox);
+                }
+                catch {
+                    cleanupOk = false;
+                }
+                const exitAgreement = exitCode === 0 && !streamFailed && pendingResult !== null && cleanupOk;
+                if (exitAgreement && credentialIntact && pendingResult) {
+                    pushQueue({ event: pendingResult });
+                    terminalResultEmitted = true;
+                }
+                else if (!terminalResultEmitted && !streamFailed) {
+                    pushQueue({ event: { type: "error" } });
+                }
+                pushQueue({ done: true });
+            });
+            // Consumer generator loop
+            while (true) {
+                if (runState.earlyClosed) {
+                    return;
+                }
+                if (runController.signal.aborted) {
+                    yield { type: "error" };
+                    return;
+                }
+                if (queue.length === 0) {
+                    await new Promise((r) => {
+                        notifyNext = r;
+                        // Abort may fire between the check above and this wait.
+                        if (runController.signal.aborted || runState.earlyClosed) {
+                            notifyNext = null;
+                            r();
+                        }
+                    });
+                }
+                while (queue.length > 0) {
+                    const item = queue.shift();
+                    if ("done" in item) {
+                        return;
+                    }
+                    if ("event" in item) {
+                        yield item.event;
+                        if (item.event.type === "result" || item.event.type === "error") {
+                            return;
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            if (timeoutTimer) {
+                clearTimeout(timeoutTimer);
+            }
+            input.signal.removeEventListener("abort", abortHandler);
+            if (onRunAbort) {
+                runController.signal.removeEventListener("abort", onRunAbort);
+            }
+            runController.abort();
+            if (childPid > 0) {
+                if (this.killProcessTreeFn) {
+                    this.killProcessTreeFn(childPid, "SIGKILL");
+                }
+                if (this.reapProcessTreeFn) {
+                    await this.reapProcessTreeFn(childPid, "SIGKILL", 50);
+                }
+                else {
+                    await reapProcessTree(childPid, "SIGKILL", 50);
+                }
+            }
+            try {
+                cleanClaudeRunSandbox(sandbox);
+            }
+            catch {
+                // Terminal outcome already decided in the close handler; retry is best-effort.
+            }
+        }
+    }
+}
+//# sourceMappingURL=claude-code-cli-runner.js.map