@cjhyy/code-shell-capability-coding 0.8.0

package/dist/external-runtimes/claude-code/event-translator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Claude Code `--output-format stream-json` → CodeShell `StreamEvent`.
+ *
+ * Shapes measured against real `claude 2.1.220`, not inferred. The stream is a
+ * mix of two vocabularies:
+ *
+ *  - CodeShell-ish envelopes: `system` (with `subtype: "init"`), `assistant`,
+ *    `user` (carrying tool results), `result`, `rate_limit_event`.
+ *  - Raw Anthropic streaming events under `type: "stream_event"` →
+ *    `event.type: message_start | content_block_start | content_block_delta | …`.
+ *
+ * Tool lifecycle comes from the RAW events, because only they carry the tool id
+ * at `content_block.id`. Text likewise: `assistant` repeats the whole message, so
+ * translating both it and the deltas would double every character.
+ *
+ * §15.2 still applies: a CodeShell Host Tool already emits its own lifecycle
+ * through `ToolExecutor`, so a `mcp__codeshell_tools__*` tool_use must NOT get a
+ * second card here. Claude namespaces MCP tools with that prefix, which is what
+ * makes the distinction reliable.
+ */
+import type { StreamEvent } from "@cjhyy/code-shell-core/extension";
+export interface ClaudeEventTranslatorOptions {
+    /** CodeShell business session id, for correlating logs. */
+    sessionId: string;
+    /** MCP server name whose tool cards this translator suppresses. */
+    codeshellServerName?: string;
+}
+export declare class ClaudeEventTranslator {
+    private readonly options;
+    private readonly codeshellServer;
+    private turnNumber;
+    private sessionStarted;
+    private terminal;
+    /** Accumulates `input_json_delta` per tool block so args land as one object. */
+    private readonly toolInput;
+    constructor(options: ClaudeEventTranslatorOptions);
+    /** Claude session id, learned from the `system/init` line. */
+    runtimeSessionId?: string;
+    /**
+     * Translate one NDJSON line. Zero events is a normal outcome (housekeeping,
+     * unknown type). Deliberately total: an unrecognised or malformed line must not
+     * take the session down.
+     */
+    translate(line: unknown): StreamEvent[];
+    private onSystem;
+    private onStreamEvent;
+    /** The most recently opened tool block — deltas belong to it. */
+    private currentTool;
+    private flushToolArgs;
+    /** Tool results arrive as a `user` message carrying `tool_result` blocks. */
+    private onUser;
+    private onResult;
+    private isCodeshellHostTool;
+}

package/dist/external-runtimes/claude-code/event-translator.js

@@ -0,0 +1,201 @@
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+/**
+ * Map Claude's terminal reason onto CodeShell's.
+ *
+ * `error_max_turns` is distinct from a model error: reporting the wrong one sends
+ * a reader looking for an outage that never happened.
+ */
+function terminalReasonFor(subtype, isError) {
+    if (subtype === "error_max_turns")
+        return "max_turns";
+    if (subtype === "error_during_execution" || isError)
+        return "model_error";
+    return "completed";
+}
+export class ClaudeEventTranslator {
+    options;
+    codeshellServer;
+    turnNumber = 0;
+    sessionStarted = false;
+    terminal = false;
+    /** Accumulates `input_json_delta` per tool block so args land as one object. */
+    toolInput = new Map();
+    constructor(options) {
+        this.options = options;
+        this.codeshellServer = options.codeshellServerName ?? "codeshell_tools";
+    }
+    /** Claude session id, learned from the `system/init` line. */
+    runtimeSessionId;
+    /**
+     * Translate one NDJSON line. Zero events is a normal outcome (housekeeping,
+     * unknown type). Deliberately total: an unrecognised or malformed line must not
+     * take the session down.
+     */
+    translate(line) {
+        const message = asRecord(line);
+        if (!message)
+            return [];
+        switch (str(message.type)) {
+            case "system":
+                return this.onSystem(message);
+            case "stream_event":
+                return this.onStreamEvent(message);
+            case "user":
+                return this.onUser(message);
+            case "result":
+                return this.onResult(message);
+            default:
+                // `assistant` is deliberately ignored: it repeats the full message text,
+                // which the content_block deltas have already delivered. Translating both
+                // would double every character.
+                return [];
+        }
+    }
+    onSystem(message) {
+        if (str(message.subtype) !== "init")
+            return [];
+        const sessionId = str(message.session_id);
+        if (sessionId)
+            this.runtimeSessionId = sessionId;
+        if (this.sessionStarted)
+            return [];
+        this.sessionStarted = true;
+        // promptTokens is unknown at init; the field is required, and 0 is honest
+        // here rather than a guess.
+        return sessionId ? [{ type: "session_started", sessionId, promptTokens: 0 }] : [];
+    }
+    onStreamEvent(message) {
+        const event = asRecord(message.event);
+        const type = str(event?.type);
+        if (!event || !type)
+            return [];
+        if (type === "message_start") {
+            this.turnNumber += 1;
+            return [{ type: "stream_request_start", turnNumber: this.turnNumber }];
+        }
+        if (type === "content_block_start") {
+            const block = asRecord(event.content_block);
+            if (str(block?.type) !== "tool_use")
+                return [];
+            const id = str(block?.id);
+            const name = str(block?.name);
+            if (!id || !name)
+                return [];
+            // Track it even when suppressed, so its input deltas do not leak into the
+            // next block's arguments.
+            this.toolInput.set(id, { name, json: "" });
+            if (this.isCodeshellHostTool(name))
+                return [];
+            return [{ type: "tool_use_start", toolCall: { id, toolName: name, args: {} } }];
+        }
+        if (type === "content_block_delta") {
+            const delta = asRecord(event.delta);
+            const deltaType = str(delta?.type);
+            if (deltaType === "text_delta") {
+                const text = str(delta?.text);
+                return text ? [{ type: "text_delta", text }] : [];
+            }
+            if (deltaType === "input_json_delta") {
+                // Arguments stream as JSON fragments; buffer and emit once complete.
+                const partial = typeof delta?.partial_json === "string" ? delta.partial_json : "";
+                const pending = this.currentTool();
+                if (pending)
+                    pending.json += partial;
+                return [];
+            }
+            return [];
+        }
+        if (type === "content_block_stop") {
+            return this.flushToolArgs();
+        }
+        return [];
+    }
+    /** The most recently opened tool block — deltas belong to it. */
+    currentTool() {
+        let last;
+        for (const value of this.toolInput.values())
+            last = value;
+        return last;
+    }
+    flushToolArgs() {
+        const entries = [...this.toolInput.entries()];
+        const latest = entries.at(-1);
+        if (!latest)
+            return [];
+        const [id, pending] = latest;
+        if (this.isCodeshellHostTool(pending.name))
+            return [];
+        if (!pending.json)
+            return [];
+        let args;
+        try {
+            const parsed = JSON.parse(pending.json);
+            args = asRecord(parsed) ?? {};
+        }
+        catch {
+            // A truncated fragment is not worth failing a turn over; the tool_use_start
+            // already told the UI which tool is running.
+            return [];
+        }
+        return [{ type: "tool_use_args_delta", toolCallId: id, args }];
+    }
+    /** Tool results arrive as a `user` message carrying `tool_result` blocks. */
+    onUser(message) {
+        const inner = asRecord(message.message);
+        const content = Array.isArray(inner?.content) ? inner.content : [];
+        const events = [];
+        for (const raw of content) {
+            const block = asRecord(raw);
+            if (str(block?.type) !== "tool_result")
+                continue;
+            const id = str(block?.tool_use_id);
+            if (!id)
+                continue;
+            const known = this.toolInput.get(id);
+            // Suppress the CodeShell side; ToolExecutor already reported this call.
+            if (known && this.isCodeshellHostTool(known.name))
+                continue;
+            const text = typeof block?.content === "string"
+                ? block.content
+                : Array.isArray(block?.content)
+                    ? block.content
+                        .map((part) => str(asRecord(part)?.text) ?? "")
+                        .filter(Boolean)
+                        .join("\n")
+                    : undefined;
+            events.push({
+                type: "tool_result",
+                result: {
+                    id,
+                    toolName: known?.name ?? "unknown",
+                    ...(text !== undefined ? { result: text } : {}),
+                    ...(block?.is_error === true ? { isError: true } : {}),
+                },
+            });
+        }
+        return events;
+    }
+    onResult(message) {
+        // `result` is the single terminal line. Guard against a duplicate closing the
+        // turn twice — the same hazard Codex has with turn/completed.
+        if (this.terminal)
+            return [];
+        this.terminal = true;
+        return [
+            {
+                type: "turn_complete",
+                reason: terminalReasonFor(str(message.subtype), message.is_error === true),
+            },
+        ];
+    }
+    isCodeshellHostTool(toolName) {
+        return toolName.startsWith(`mcp__${this.codeshellServer}__`);
+    }
+}

package/dist/external-runtimes/claude-code/mcp-config.d.ts

@@ -0,0 +1,84 @@
+import type { McpBridgeHandle } from "../shared/mcp-bridge.js";
+/** Logical MCP server name; also the `mcp__<server>__<tool>` prefix. */
+export declare const CLAUDE_MCP_SERVER_NAME = "codeshell_tools";
+export interface ClaudeMcpConfigOptions {
+    bridge: McpBridgeHandle;
+    serverName?: string;
+}
+/**
+ * The `--mcp-config` payload as an inline JSON string.
+ *
+ * Prefer {@link writeClaudeMcpConfigFile} for anything that spawns a real
+ * process: an inline config puts the bearer token in `argv`, where `ps auxww`
+ * exposes it to every local user (measured on macOS — argv is not restricted to
+ * the owning uid). The bridge's only authentication IS that token, so leaking it
+ * hands another local process full session authority.
+ *
+ * Kept exported because it is the right shape for tests and for callers that hold
+ * no token (a config pointing at an already-authenticated transport).
+ */
+export declare function buildClaudeMcpConfig(options: ClaudeMcpConfigOptions): string;
+export interface ClaudeMcpConfigFile {
+    /** Path to pass to `--mcp-config`. */
+    path: string;
+    /** Remove the file and its directory. Call when the session ends. */
+    cleanup(): void;
+}
+/**
+ * Write the config to a mode-0600 temp file so the token never enters `argv`.
+ *
+ * `--mcp-config` documents "JSON files or strings", and a file works identically
+ * — verified by capturing the resulting handshake, which carries the same
+ * `Authorization` header. This is per-invocation and unlinked on cleanup, so it
+ * does NOT touch the user's own `~/.claude.json`; the goal was never "avoid all
+ * files", it was "avoid mutating persistent user config".
+ */
+export declare function writeClaudeMcpConfigFile(options: ClaudeMcpConfigOptions): ClaudeMcpConfigFile;
+/**
+ * Fully-qualified tool names for `--allowed-tools`.
+ *
+ * **`--allowed-tools` is a GRANT, not a filter.** Measured against real
+ * `claude 2.1.220`: `--allowed-tools Write` lets the model write a file with no
+ * approval prompt, while omitting the flag blocks the same request; and naming
+ * only `Read` does not disable `Write`. It is purely additive — the CLI pairs it
+ * with `--disallowedTools`, which is the deny half.
+ *
+ * An earlier version of this comment claimed the flag "does NOT widen anything".
+ * That was inverted, and the inversion is the dangerous part: a reader who
+ * believes the flag cannot widen has no reason to check what goes into it.
+ *
+ * Safety therefore rests on ONE property, enforced below rather than assumed:
+ * every emitted name is `mcp__<server>__<tool>`, which routes to CodeShell's own
+ * `ToolExecutor` and exposure policy. A bare `Bash` or `Write` reaching this list
+ * would grant the untrusted runtime an unapproved built-in tool, and the exposure
+ * allowlist would not help — it governs the MCP surface, not Claude Code's own
+ * tools.
+ *
+ * Note what is NOT done here: auto-prefixing. Turning `"Bash"` into
+ * `mcp__codeshell_tools__Bash` would make every input "valid" and defeat the
+ * check — the first version of this function did exactly that. A CodeShell tool
+ * name is a plain identifier, so it must be a plain identifier, and anything that
+ * looks like a built-in-tool pattern (`Bash(git *)`, `*`) or is already qualified
+ * for a different server is a programming error.
+ */
+export declare function claudeAllowedToolNames(toolNames: Iterable<string>, serverName?: string): string[];
+/**
+ * CLI args wiring a `claude -p` invocation to the bridge.
+ *
+ * Uses a 0600 file for the config (token out of `argv`) and passes
+ * `--strict-mcp-config` so the bridge is the session's ONLY tool channel.
+ * Without that flag Claude Code also loads every MCP server from the user's
+ * `~/.claude.json` and project config — servers the user approved for their own
+ * interactive use, not for an agent CodeShell spawns on their behalf, and which
+ * sit entirely outside CodeShell's exposure policy and `ToolExecutor`.
+ *
+ * The caller owns `cleanup()`; run it when the session ends.
+ */
+export declare function claudeBridgeArgs(options: {
+    bridge: McpBridgeHandle;
+    exposedToolNames: Iterable<string>;
+    serverName?: string;
+}): {
+    args: string[];
+    cleanup(): void;
+};

package/dist/external-runtimes/claude-code/mcp-config.js

@@ -0,0 +1,175 @@
+/**
+ * Wiring Claude Code to the loopback MCP bridge.
+ *
+ * The design (§10.2) assumed this would need `@anthropic-ai/claude-agent-sdk` and
+ * an in-process MCP server — a second transport alongside Codex's HTTP one.
+ * It does not. `claude --mcp-config` accepts an HTTP MCP server with an
+ * `Authorization` header, exactly as Codex does, so both runtimes share one bridge
+ * and CodeShell takes on no new dependency. Verified against real `claude 2.1.220`
+ * (`docs/todo/evidence/e2e-claude-product-bridge.mjs`).
+ *
+ * Two behaviours worth knowing, both observed:
+ *
+ *  - Claude Code sends **no per-call thread identity**. Its bridge must therefore
+ *    be pinned to one session (`singleSessionThreadId`), making the port the
+ *    attribution. That is a real constraint, not a shortcut — see
+ *    `McpBridgeOptions.singleSessionThreadId`.
+ *  - It opens with a `GET` (probing for an SSE stream) which the bridge answers
+ *    405. Harmless: it falls back to POST immediately.
+ */
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Logical MCP server name; also the `mcp__<server>__<tool>` prefix. */
+export const CLAUDE_MCP_SERVER_NAME = "codeshell_tools";
+/** `mcp__<server>__<tool>` — the only shape that may reach `--allowed-tools`. */
+const MCP_TOOL_NAME = /^mcp__[a-z0-9_]+__[A-Za-z0-9_]+$/;
+/**
+ * Claude Code's own built-in tools. They share the plain-identifier shape with
+ * CodeShell tool names, so shape validation alone cannot separate them — and
+ * pre-approving one of these grants the untrusted runtime an unapproved built-in.
+ * Over-inclusive on purpose: a false positive is a loud error at a call site, a
+ * false negative is a silent capability grant.
+ */
+const CLAUDE_BUILTIN_TOOL_NAMES = new Set([
+    "Agent",
+    "Bash",
+    "BashOutput",
+    "Edit",
+    "ExitPlanMode",
+    "Glob",
+    "Grep",
+    "KillShell",
+    "NotebookEdit",
+    "Read",
+    "Task",
+    "TodoWrite",
+    "WebFetch",
+    "WebSearch",
+    "Write",
+]);
+/**
+ * The `--mcp-config` payload as an inline JSON string.
+ *
+ * Prefer {@link writeClaudeMcpConfigFile} for anything that spawns a real
+ * process: an inline config puts the bearer token in `argv`, where `ps auxww`
+ * exposes it to every local user (measured on macOS — argv is not restricted to
+ * the owning uid). The bridge's only authentication IS that token, so leaking it
+ * hands another local process full session authority.
+ *
+ * Kept exported because it is the right shape for tests and for callers that hold
+ * no token (a config pointing at an already-authenticated transport).
+ */
+export function buildClaudeMcpConfig(options) {
+    const serverName = options.serverName ?? CLAUDE_MCP_SERVER_NAME;
+    return JSON.stringify({
+        mcpServers: {
+            [serverName]: {
+                type: "http",
+                url: options.bridge.url,
+                headers: { Authorization: `Bearer ${options.bridge.token}` },
+            },
+        },
+    });
+}
+/**
+ * Write the config to a mode-0600 temp file so the token never enters `argv`.
+ *
+ * `--mcp-config` documents "JSON files or strings", and a file works identically
+ * — verified by capturing the resulting handshake, which carries the same
+ * `Authorization` header. This is per-invocation and unlinked on cleanup, so it
+ * does NOT touch the user's own `~/.claude.json`; the goal was never "avoid all
+ * files", it was "avoid mutating persistent user config".
+ */
+export function writeClaudeMcpConfigFile(options) {
+    const dir = mkdtempSync(join(tmpdir(), "codeshell-mcp-"));
+    const path = join(dir, "mcp-config.json");
+    writeFileSync(path, buildClaudeMcpConfig(options), { mode: 0o600 });
+    // Set explicitly as well: writeFileSync's mode is subject to umask.
+    chmodSync(path, 0o600);
+    return {
+        path,
+        cleanup: () => rmSync(dir, { recursive: true, force: true }),
+    };
+}
+/**
+ * Fully-qualified tool names for `--allowed-tools`.
+ *
+ * **`--allowed-tools` is a GRANT, not a filter.** Measured against real
+ * `claude 2.1.220`: `--allowed-tools Write` lets the model write a file with no
+ * approval prompt, while omitting the flag blocks the same request; and naming
+ * only `Read` does not disable `Write`. It is purely additive — the CLI pairs it
+ * with `--disallowedTools`, which is the deny half.
+ *
+ * An earlier version of this comment claimed the flag "does NOT widen anything".
+ * That was inverted, and the inversion is the dangerous part: a reader who
+ * believes the flag cannot widen has no reason to check what goes into it.
+ *
+ * Safety therefore rests on ONE property, enforced below rather than assumed:
+ * every emitted name is `mcp__<server>__<tool>`, which routes to CodeShell's own
+ * `ToolExecutor` and exposure policy. A bare `Bash` or `Write` reaching this list
+ * would grant the untrusted runtime an unapproved built-in tool, and the exposure
+ * allowlist would not help — it governs the MCP surface, not Claude Code's own
+ * tools.
+ *
+ * Note what is NOT done here: auto-prefixing. Turning `"Bash"` into
+ * `mcp__codeshell_tools__Bash` would make every input "valid" and defeat the
+ * check — the first version of this function did exactly that. A CodeShell tool
+ * name is a plain identifier, so it must be a plain identifier, and anything that
+ * looks like a built-in-tool pattern (`Bash(git *)`, `*`) or is already qualified
+ * for a different server is a programming error.
+ */
+export function claudeAllowedToolNames(toolNames, serverName = CLAUDE_MCP_SERVER_NAME) {
+    const reject = (name, why) => {
+        throw new Error(`Refusing to pre-approve '${name}': ${why}. --allowed-tools is a GRANT, and ` +
+            `only mcp__${serverName}__<tool> names route through CodeShell's ToolExecutor.`);
+    };
+    return [...toolNames].map((name) => {
+        // A CodeShell tool name, e.g. "Panel". Nothing else is accepted.
+        if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name)) {
+            return reject(name, "not a plain CodeShell tool name");
+        }
+        // An already-qualified name would let a caller pre-approve a tool on a
+        // DIFFERENT MCP server — outside CodeShell's exposure policy entirely. The
+        // qualifying is this function's job, not the caller's. (Checked separately
+        // from the shape test above: `mcp__other__Thing` is a valid identifier.)
+        if (name.startsWith("mcp__")) {
+            return reject(name, "already qualified — pass a plain CodeShell tool name");
+        }
+        // Claude Code's own built-ins share the identifier shape, so shape alone is
+        // not enough — these must never be pre-approved through this path.
+        if (CLAUDE_BUILTIN_TOOL_NAMES.has(name)) {
+            return reject(name, "this is a Claude Code built-in tool, not a CodeShell tool");
+        }
+        const qualified = `mcp__${serverName}__${name}`;
+        if (!MCP_TOOL_NAME.test(qualified))
+            return reject(name, "does not qualify as an MCP tool name");
+        return qualified;
+    });
+}
+/**
+ * CLI args wiring a `claude -p` invocation to the bridge.
+ *
+ * Uses a 0600 file for the config (token out of `argv`) and passes
+ * `--strict-mcp-config` so the bridge is the session's ONLY tool channel.
+ * Without that flag Claude Code also loads every MCP server from the user's
+ * `~/.claude.json` and project config — servers the user approved for their own
+ * interactive use, not for an agent CodeShell spawns on their behalf, and which
+ * sit entirely outside CodeShell's exposure policy and `ToolExecutor`.
+ *
+ * The caller owns `cleanup()`; run it when the session ends.
+ */
+export function claudeBridgeArgs(options) {
+    const serverName = options.serverName ?? CLAUDE_MCP_SERVER_NAME;
+    const config = writeClaudeMcpConfigFile({ bridge: options.bridge, serverName });
+    return {
+        args: [
+            "--mcp-config",
+            config.path,
+            "--strict-mcp-config",
+            "--allowed-tools",
+            claudeAllowedToolNames(options.exposedToolNames, serverName).join(","),
+        ],
+        cleanup: config.cleanup,
+    };
+}

package/dist/external-runtimes/claude-code/runtime.d.ts

@@ -0,0 +1,56 @@
+import type { StreamEvent } from "@cjhyy/code-shell-core/extension";
+import type { McpBridgeHandle } from "../shared/mcp-bridge.js";
+export interface ClaudeRuntimeOptions {
+    cwd: string;
+    /** CodeShell business session id — the authorization subject. */
+    businessSessionId: string;
+    bridge: McpBridgeHandle;
+    /** CodeShell tool names the bridge exposes, for `--allowed-tools`. */
+    exposedToolNames: readonly string[];
+    /** Executable; defaults to `claude` on PATH. */
+    command?: string;
+    /** Extra args, inserted before the runtime's own. */
+    extraArgs?: readonly string[];
+    model?: string;
+    serverName?: string;
+    log?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface ClaudeRuntimeHooks {
+    onEvent?: (event: StreamEvent) => void;
+}
+export interface ClaudeTurnHandle {
+    readonly done: Promise<void>;
+}
+export declare class ClaudeCodeRuntime {
+    private readonly options;
+    private readonly hooks;
+    readonly kind: "claude-code";
+    private readonly log;
+    private translator;
+    private child?;
+    private claudeSessionId?;
+    private closed;
+    constructor(options: ClaudeRuntimeOptions, hooks?: ClaudeRuntimeHooks);
+    /** Claude session id, once the first turn has reported it. Resume key only. */
+    get runtimeSessionId(): string | undefined;
+    /**
+     * Run one turn. Resolves when the process exits, which is also when the turn is
+     * terminal — `claude -p` is one process per turn.
+     *
+     * The prompt goes on **stdin**, not argv: `--mcp-config` is variadic, so a
+     * positional prompt after it is swallowed as another config value (measured),
+     * and a prompt on the command line would also be visible in `ps`.
+     */
+    send(text: string): Promise<ClaudeTurnHandle>;
+    private onLine;
+    /**
+     * Interrupt the active turn.
+     *
+     * `claude -p` has no interrupt RPC, so this is a signal. As with Codex, it
+     * cannot retract side effects already dispatched — it only stops further steps.
+     */
+    interrupt(): Promise<void>;
+    close(): Promise<void>;
+    /** Start a fresh conversation on the next `send()`, discarding resume state. */
+    resetConversation(): void;
+}