@cjhyy/code-shell-capability-coding 0.8.0

package/dist/external-runtimes/claude-code/runtime.js

@@ -0,0 +1,168 @@
+/**
+ * Claude Code as a CodeShell Agent Runtime.
+ *
+ * Drives `claude -p --output-format stream-json`, translates the stream into
+ * `StreamEvent`, and wires the loopback MCP bridge so the model can reach
+ * CodeShell tools mid-turn.
+ *
+ * Not an `LLMClientBase` (§6.1): Claude Code brings its own agent loop, tools and
+ * permission layer. This sits beside the Engine.
+ *
+ * One structural difference from Codex worth stating plainly: Codex's app-server
+ * is a long-lived process serving many turns, whereas `claude -p` is **one process
+ * per turn**. Continuity therefore comes from `--resume <sessionId>`, using the id
+ * learned from the first turn's `system/init` line — not from keeping a socket
+ * open. That is why there is no `start()` here: the first `send()` IS the start.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { ClaudeEventTranslator } from "./event-translator.js";
+import { claudeBridgeArgs, CLAUDE_MCP_SERVER_NAME } from "./mcp-config.js";
+import { buildRuntimeSpawnEnv } from "../shared/spawn-env.js";
+export class ClaudeCodeRuntime {
+    options;
+    hooks;
+    kind = "claude-code";
+    log;
+    translator;
+    child;
+    claudeSessionId;
+    closed = false;
+    constructor(options, hooks = {}) {
+        this.options = options;
+        this.hooks = hooks;
+        this.log = options.log ?? (() => { });
+        this.translator = new ClaudeEventTranslator({
+            sessionId: options.businessSessionId,
+            codeshellServerName: options.serverName ?? CLAUDE_MCP_SERVER_NAME,
+        });
+    }
+    /** Claude session id, once the first turn has reported it. Resume key only. */
+    get runtimeSessionId() {
+        return this.claudeSessionId;
+    }
+    /**
+     * 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`.
+     */
+    async send(text) {
+        if (this.closed)
+            throw new Error("ClaudeCodeRuntime is closed");
+        if (this.child)
+            throw new Error("a turn is already running");
+        const wiring = claudeBridgeArgs({
+            bridge: this.options.bridge,
+            exposedToolNames: this.options.exposedToolNames,
+            ...(this.options.serverName ? { serverName: this.options.serverName } : {}),
+        });
+        const args = [
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--include-partial-messages",
+            // stream-json output requires --verbose; without it the CLI refuses.
+            "--verbose",
+            ...(this.options.model ? ["--model", this.options.model] : []),
+            // Continuity across turns: a fresh process per turn means the session id is
+            // the only thread of memory.
+            ...(this.claudeSessionId ? ["--resume", this.claudeSessionId] : []),
+            ...(this.options.extraArgs ?? []),
+            ...wiring.args,
+        ];
+        const child = spawn(this.options.command ?? "claude", args, {
+            cwd: this.options.cwd,
+            env: buildRuntimeSpawnEnv({
+                bridgeToken: {
+                    name: this.options.bridge.tokenEnvVar,
+                    value: this.options.bridge.token,
+                },
+            }),
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: false,
+        });
+        this.child = child;
+        child.stdout.setEncoding("utf8");
+        const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        lines.on("line", (line) => this.onLine(line));
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            const trimmed = chunk.trim();
+            if (trimmed)
+                this.log("claude.stderr", { bytes: trimmed.length });
+        });
+        child.stdin.end(text);
+        const done = new Promise((resolve) => {
+            const finish = () => {
+                lines.close();
+                // Clean up the config file that carried the bearer token.
+                wiring.cleanup();
+                this.child = undefined;
+                resolve();
+            };
+            child.once("exit", finish);
+            child.once("error", (error) => {
+                this.log("claude.spawn_failed", { error: error.message.slice(0, 200) });
+                finish();
+            });
+        });
+        return { done };
+    }
+    onLine(line) {
+        if (!line.trim())
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            // The CLI may print non-JSON diagnostics; one bad line is not fatal.
+            this.log("claude.unparsable_line", { bytes: line.length });
+            return;
+        }
+        for (const event of this.translator.translate(parsed)) {
+            try {
+                this.hooks.onEvent?.(event);
+            }
+            catch (error) {
+                this.log("claude.event_handler_failed", {
+                    error: error instanceof Error ? error.name : "unknown",
+                });
+            }
+        }
+        if (!this.claudeSessionId && this.translator.runtimeSessionId) {
+            this.claudeSessionId = this.translator.runtimeSessionId;
+            this.log("claude.session_started", {
+                businessSessionId: this.options.businessSessionId,
+                runtimeSessionIdPrefix: this.claudeSessionId.slice(0, 8),
+            });
+        }
+    }
+    /**
+     * 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.
+     */
+    async interrupt() {
+        const child = this.child;
+        if (!child)
+            return;
+        child.kill("SIGTERM");
+    }
+    async close() {
+        this.closed = true;
+        await this.interrupt();
+    }
+    /** Start a fresh conversation on the next `send()`, discarding resume state. */
+    resetConversation() {
+        this.claudeSessionId = undefined;
+        this.translator = new ClaudeEventTranslator({
+            sessionId: this.options.businessSessionId,
+            codeshellServerName: this.options.serverName ?? CLAUDE_MCP_SERVER_NAME,
+        });
+    }
+}

package/dist/external-runtimes/codex/app-server-client.d.ts

@@ -0,0 +1,66 @@
+export interface AppServerClientOptions {
+    /** Executable; defaults to `codex` on PATH. */
+    command?: string;
+    /**
+     * Full argv after `command`. Defaults to `["app-server"]`.
+     *
+     * Configurable rather than hardcoded so a test can point the client at a fake
+     * server binary — a client that can only ever launch the real Codex is a client
+     * whose transport rules are untestable without a login.
+     */
+    args?: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Structured log sink. Never receives tokens or full tool arguments. */
+    log?: (event: string, data: Record<string, unknown>) => void;
+}
+export type NotificationHandler = (method: string, params: unknown) => void;
+/**
+ * Answer a server→client request. Returning `undefined` means "not handled",
+ * which the client turns into a JSON-RPC method-not-found reply — the server is
+ * waiting either way.
+ */
+export type ServerRequestHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
+export declare class CodexAppServerClient {
+    private readonly options;
+    private child?;
+    private lines?;
+    private nextId;
+    private readonly pending;
+    private notificationHandler?;
+    private requestHandler?;
+    private closed;
+    private closeReason?;
+    /** Buffer lines that arrive before a handler exists, then drain in order. */
+    private readonly preHandlerLines;
+    private handlersReady;
+    private readonly log;
+    constructor(options?: AppServerClientOptions);
+    /**
+     * Register handlers. MUST be called before {@link start} — see the note on
+     * ordering in the module header.
+     */
+    onNotification(handler: NotificationHandler): void;
+    onServerRequest(handler: ServerRequestHandler): void;
+    /** Spawn the app-server. Handlers must already be registered. */
+    start(): void;
+    private acceptLine;
+    private handleLine;
+    private settle;
+    /**
+     * Fire-and-forget so an awaiting client request never blocks inbound reads —
+     * a server request arriving mid-flight must not deadlock the transport.
+     */
+    private dispatchServerRequest;
+    /**
+     * Send a request. No timeout unless `timeoutMs` is given — see the module
+     * header on why a global timeout is harmful.
+     */
+    request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+    notify(method: string, params?: unknown): void;
+    private write;
+    private failAll;
+    get isClosed(): boolean;
+    /** Graceful stop: stdin EOF (the Rust app-server exits on it), SIGTERM after. */
+    close(): Promise<void>;
+}

package/dist/external-runtimes/codex/app-server-client.js

@@ -0,0 +1,244 @@
+/**
+ * NDJSON JSON-RPC client for `codex app-server`.
+ *
+ * Shapes verified against real `codex-cli 0.145.0` generated bindings; the
+ * ordering and framing rules below are the expensive lessons recorded in the
+ * `makecindy/cindy` reference implementation (design §16), which we read rather
+ * than rediscover:
+ *
+ *  - **Codex's JSON-RPC does NOT send a `jsonrpc` field.** Messages must be
+ *    discriminated by shape alone.
+ *  - **Handlers must be registered before `initialize()`.** The server pushes
+ *    notifications the moment the transport is up; registering afterwards drops
+ *    them. There is no readiness banner — the `initialize` response IS readiness.
+ *  - **A server→client request must always be answered**, even an unknown one, or
+ *    the server blocks waiting.
+ *  - **`request()` has no default timeout.** Per protocol a response may be
+ *    arbitrarily late, and a global timeout manufactures orphan turns: a timed-out
+ *    `turn/start` does NOT mean the server declined to create the turn. Callers
+ *    opt in per call site.
+ *  - **A single malformed line must not kill the session** (the server may emit a
+ *    banner), but an oversized line must, to keep JSON.parse off the hot path.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+/** Cap per NDJSON line. Generous for reasoning text; guards parse latency. */
+const MAX_LINE_BYTES = 16 * 1024 * 1024;
+export class CodexAppServerClient {
+    options;
+    child;
+    lines;
+    nextId = 1;
+    pending = new Map();
+    notificationHandler;
+    requestHandler;
+    closed = false;
+    closeReason;
+    /** Buffer lines that arrive before a handler exists, then drain in order. */
+    preHandlerLines = [];
+    handlersReady = false;
+    log;
+    constructor(options = {}) {
+        this.options = options;
+        this.log = options.log ?? (() => { });
+    }
+    /**
+     * Register handlers. MUST be called before {@link start} — see the note on
+     * ordering in the module header.
+     */
+    onNotification(handler) {
+        this.notificationHandler = handler;
+    }
+    onServerRequest(handler) {
+        this.requestHandler = handler;
+    }
+    /** Spawn the app-server. Handlers must already be registered. */
+    start() {
+        if (this.child)
+            return;
+        const command = this.options.command ?? "codex";
+        const args = [...(this.options.args ?? ["app-server"])];
+        // `shell: false` deliberately: a shell would reintroduce env-injection risk
+        // and make stdio piping unpredictable.
+        this.child = spawn(command, args, {
+            cwd: this.options.cwd,
+            env: this.options.env,
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: false,
+        });
+        this.child.stdout.setEncoding("utf8");
+        this.lines = createInterface({ input: this.child.stdout, crlfDelay: Infinity });
+        this.lines.on("line", (line) => this.acceptLine(line));
+        this.child.stderr.setEncoding("utf8");
+        this.child.stderr.on("data", (chunk) => {
+            const text = chunk.trim();
+            // stderr is not protocol data. Log only a classification: it can carry
+            // model output and must not become an auth-failure oracle either — auth
+            // invalidation is detected ONLY from a correlated JSON-RPC error.
+            // Diagnostic preview only, bounded; stderr is never an auth oracle.
+            if (text)
+                this.log("appserver.stderr", { bytes: text.length, preview: text.slice(0, 300) });
+        });
+        const onGone = (why) => () => this.failAll(why);
+        this.child.on("exit", onGone("app-server exited"));
+        this.child.on("error", onGone("app-server failed to start"));
+        // Handlers are registered by contract before start(); release the buffer.
+        this.handlersReady = true;
+        for (const line of this.preHandlerLines.splice(0))
+            this.handleLine(line);
+    }
+    acceptLine(line) {
+        if (!this.handlersReady) {
+            this.preHandlerLines.push(line);
+            return;
+        }
+        this.handleLine(line);
+    }
+    handleLine(line) {
+        if (line.length > MAX_LINE_BYTES) {
+            // Oversized is a transport failure: parsing it would stall the event loop.
+            this.failAll("app-server sent an oversized line");
+            return;
+        }
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            // One bad line does not kill the session — the server may emit a banner.
+            this.log("appserver.unparsable_line", { bytes: line.length });
+            return;
+        }
+        // Shape-based discrimination: Codex omits the `jsonrpc` field entirely.
+        const hasId = message.id !== undefined && message.id !== null;
+        const method = typeof message.method === "string" ? message.method : undefined;
+        if (hasId && method) {
+            void this.dispatchServerRequest(message.id, method, message.params);
+            return;
+        }
+        if (hasId) {
+            this.settle(message);
+            return;
+        }
+        if (method) {
+            try {
+                this.notificationHandler?.(method, message.params);
+            }
+            catch (error) {
+                // A handler throw must not take down the read loop.
+                this.log("appserver.notification_handler_failed", {
+                    method,
+                    error: error instanceof Error ? error.name : "unknown",
+                });
+            }
+        }
+    }
+    settle(message) {
+        const id = Number(message.id);
+        const entry = this.pending.get(id);
+        if (!entry)
+            return;
+        this.pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        if (message.error !== undefined) {
+            entry.reject(new Error(`app-server error: ${JSON.stringify(message.error).slice(0, 400)}`));
+            return;
+        }
+        entry.resolve(message.result);
+    }
+    /**
+     * Fire-and-forget so an awaiting client request never blocks inbound reads —
+     * a server request arriving mid-flight must not deadlock the transport.
+     */
+    async dispatchServerRequest(id, method, params) {
+        try {
+            const result = this.requestHandler ? await this.requestHandler(method, params) : undefined;
+            if (result === undefined) {
+                // The server is waiting regardless; an unhandled request still gets an
+                // answer rather than a hang.
+                this.write({ id, error: { code: -32601, message: `unhandled: ${method}` } });
+                return;
+            }
+            this.write({ id, result });
+        }
+        catch (error) {
+            this.write({
+                id,
+                error: { code: -32603, message: error instanceof Error ? error.message : "handler failed" },
+            });
+        }
+    }
+    /**
+     * Send a request. No timeout unless `timeoutMs` is given — see the module
+     * header on why a global timeout is harmful.
+     */
+    request(method, params, timeoutMs) {
+        if (this.closed) {
+            return Promise.reject(new Error(this.closeReason ?? "app-server client is closed"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const entry = { resolve, reject };
+            if (timeoutMs !== undefined) {
+                entry.timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`app-server ${method} did not answer within ${timeoutMs}ms. NOTE: the ` +
+                        `request may still have taken effect — a timed-out turn/start does not ` +
+                        `mean the turn was not created.`));
+                }, timeoutMs);
+            }
+            this.pending.set(id, entry);
+            this.write({ id, method, params: params ?? {} });
+        });
+    }
+    notify(method, params) {
+        if (this.closed)
+            return;
+        this.write({ method, params: params ?? {} });
+    }
+    write(payload) {
+        const child = this.child;
+        if (!child || child.stdin.destroyed)
+            return;
+        child.stdin.write(`${JSON.stringify(payload)}\n`);
+    }
+    failAll(reason) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.closeReason = reason;
+        this.log("appserver.closed", { reason });
+        for (const [, entry] of this.pending) {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            entry.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    /** Graceful stop: stdin EOF (the Rust app-server exits on it), SIGTERM after. */
+    async close() {
+        const child = this.child;
+        this.failAll("app-server client closed");
+        this.lines?.close();
+        if (!child)
+            return;
+        try {
+            child.stdin.end();
+        }
+        catch {
+            /* already gone */
+        }
+        const exited = new Promise((resolve) => {
+            if (child.exitCode !== null)
+                return resolve();
+            child.once("exit", () => resolve());
+        });
+        const timer = setTimeout(() => child.kill("SIGTERM"), 2_000);
+        await exited;
+        clearTimeout(timer);
+    }
+}

package/dist/external-runtimes/codex/event-translator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Codex app-server notifications → CodeShell `StreamEvent`.
+ *
+ * Shapes come from the generated bindings of a real codex-cli 0.145.0
+ * (`codex app-server generate-ts`). The ordering rules below are NOT inferred
+ * from the schema — they are the expensive lessons recorded in the
+ * `makecindy/cindy` reference implementation (design §16), which we read rather
+ * than rediscover:
+ *
+ *  - `turn/completed` **can be delivered more than once**. Only the first may
+ *    close the turn.
+ *  - Items **arrive after `turn/completed`**. Clearing the current turn id is not
+ *    enough; a late item would re-open a turn whose completion was already
+ *    consumed, leaving the session permanently "busy".
+ *  - `turn/started` for a turn can arrive **before** the `turn/start` RPC
+ *    response, and so can `turn/completed`. Neither may resurrect a turn that has
+ *    already reached a terminal state.
+ *
+ * Hence: a per-turn tombstone that outlives the turn, for completed AND errored
+ * turns alike. Dropping a stale event is always preferable to reopening a turn.
+ *
+ * §15.2 also applies: a CodeShell Host Tool already emits its own lifecycle
+ * through `ToolExecutor`, so this translator must NOT emit a second tool card for
+ * it. Third-party MCP servers have no CodeShell-side lifecycle and do get cards.
+ */
+import type { StreamEvent } from "@cjhyy/code-shell-core/extension";
+export interface CodexEventTranslatorOptions {
+    /** The ONE Codex thread this translator serves. */
+    threadId: string;
+    /** CodeShell business session id, for correlating logs. */
+    sessionId: string;
+    /** Override the suppressed MCP server name (tests). */
+    codeshellServerName?: string;
+}
+export declare class CodexEventTranslator {
+    private readonly threadId;
+    private readonly codeshellServer;
+    private turnNumber;
+    private activeTurnId;
+    /** Turns that reached a terminal state. Late events for these are dropped. */
+    private readonly finishedTurns;
+    constructor(options: CodexEventTranslatorOptions);
+    /**
+     * Translate one notification. Returns zero or more events — zero is a normal,
+     * common outcome (unknown method, other thread, stale turn), never an error.
+     *
+     * Deliberately total: the app-server is experimental and adds notifications
+     * between versions, so an unrecognised or malformed one must not take a session
+     * down.
+     */
+    translate(notification: unknown): StreamEvent[];
+    /** True when an event belongs to a turn that has already finished. */
+    private isStale;
+    private remember;
+    private onTurnStarted;
+    private onTurnCompleted;
+    private onError;
+    private onAgentDelta;
+    /**
+     * A CodeShell Host Tool call must not produce a card here — `ToolExecutor`
+     * already emits one, and two unsynchronised sources for one operation is
+     * exactly what §15.2 forbids. Only OUR server is suppressed; a third-party MCP
+     * server has no CodeShell-side lifecycle, so dropping it would lose the card.
+     */
+    private isCodeshellHostTool;
+    private onItemStarted;
+    private onItemCompleted;
+}