@cjhyy/code-shell-capability-coding 0.8.0

package/dist/external-runtimes/codex/event-translator.js

@@ -0,0 +1,187 @@
+/** MCP server name CodeShell advertises its own tools under. */
+const CODESHELL_MCP_SERVER = "codeshell_tools";
+/** Cap on remembered finished turns — a session is long-lived, the set is not. */
+const MAX_TOMBSTONES = 256;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+/**
+ * Map a Codex turn status onto a CodeShell `TerminalReason`.
+ *
+ * `interrupted` must not become `completed`: a stopped turn that reports success
+ * makes downstream notifications ("done!") actively wrong.
+ */
+function terminalReasonFor(status) {
+    switch (status) {
+        case "interrupted":
+        case "cancelled":
+            return "aborted_streaming";
+        case "failed":
+            return "model_error";
+        default:
+            return "completed";
+    }
+}
+export class CodexEventTranslator {
+    threadId;
+    codeshellServer;
+    turnNumber = 0;
+    activeTurnId;
+    /** Turns that reached a terminal state. Late events for these are dropped. */
+    finishedTurns = new Set();
+    constructor(options) {
+        this.threadId = options.threadId;
+        this.codeshellServer = options.codeshellServerName ?? CODESHELL_MCP_SERVER;
+    }
+    /**
+     * 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) {
+        const envelope = asRecord(notification);
+        if (!envelope)
+            return [];
+        const method = str(envelope.method);
+        const params = asRecord(envelope.params);
+        if (!method || !params)
+            return [];
+        // Thread scoping. `thread/started` is the documented exception: it carries
+        // the id at `params.thread.id` rather than the usual top-level field.
+        const nestedThread = asRecord(params.thread);
+        const threadId = str(params.threadId) ?? str(nestedThread?.id);
+        if (threadId && threadId !== this.threadId)
+            return [];
+        switch (method) {
+            case "turn/started":
+                return this.onTurnStarted(params);
+            case "turn/completed":
+                return this.onTurnCompleted(params);
+            case "error":
+                return this.onError(params);
+            case "item/agentMessage/delta":
+                return this.onAgentDelta(params);
+            case "item/started":
+                return this.onItemStarted(params);
+            case "item/completed":
+                return this.onItemCompleted(params);
+            default:
+                // Everything else (token usage, rate limits, plan updates, MCP status…)
+                // is either handled elsewhere or deliberately not surfaced.
+                return [];
+        }
+    }
+    /** True when an event belongs to a turn that has already finished. */
+    isStale(turnId) {
+        if (!turnId)
+            return false;
+        if (this.finishedTurns.has(turnId))
+            return true;
+        // A turn id we have never seen, while another turn is live, is a straggler
+        // from a superseded turn — not an implicit new turn.
+        return this.activeTurnId !== undefined && turnId !== this.activeTurnId;
+    }
+    remember(turnId) {
+        this.finishedTurns.add(turnId);
+        if (this.finishedTurns.size > MAX_TOMBSTONES) {
+            const oldest = this.finishedTurns.values().next().value;
+            if (oldest !== undefined)
+                this.finishedTurns.delete(oldest);
+        }
+    }
+    onTurnStarted(params) {
+        const turn = asRecord(params.turn);
+        const turnId = str(turn?.id) ?? str(params.turnId);
+        // A `turn/started` for an already-finished turn is an orphan (its RPC failed
+        // and the daemon created the turn anyway, or completion beat it here). It
+        // must not reactivate the session.
+        if (turnId && this.finishedTurns.has(turnId))
+            return [];
+        this.activeTurnId = turnId;
+        this.turnNumber += 1;
+        return [{ type: "stream_request_start", turnNumber: this.turnNumber }];
+    }
+    onTurnCompleted(params) {
+        const turn = asRecord(params.turn);
+        const turnId = str(turn?.id) ?? str(params.turnId);
+        // Duplicate delivery is expected; only the first completion closes the turn.
+        if (turnId && this.finishedTurns.has(turnId))
+            return [];
+        if (turnId)
+            this.remember(turnId);
+        this.activeTurnId = undefined;
+        return [{ type: "turn_complete", reason: terminalReasonFor(str(turn?.status)) }];
+    }
+    onError(params) {
+        // A retryable error is not terminal. Reporting completion here would close
+        // the turn in the UI while Codex is still working on it — and 401 retries in
+        // particular fire about once a second, so this would also storm.
+        if (params.willRetry === true)
+            return [];
+        const turnId = str(params.turnId);
+        if (turnId && this.finishedTurns.has(turnId))
+            return [];
+        if (turnId)
+            this.remember(turnId);
+        this.activeTurnId = undefined;
+        return [{ type: "turn_complete", reason: "model_error" }];
+    }
+    onAgentDelta(params) {
+        if (this.isStale(str(params.turnId)))
+            return [];
+        const delta = str(params.delta);
+        return delta ? [{ type: "text_delta", text: delta }] : [];
+    }
+    /**
+     * 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.
+     */
+    isCodeshellHostTool(item) {
+        if (!item)
+            return false;
+        if (str(item.type) !== "mcpToolCall")
+            return false;
+        return str(item.server) === this.codeshellServer;
+    }
+    onItemStarted(params) {
+        if (this.isStale(str(params.turnId)))
+            return [];
+        const item = asRecord(params.item);
+        const id = str(item?.id);
+        const type = str(item?.type);
+        if (!item || !id || !type)
+            return [];
+        if (this.isCodeshellHostTool(item))
+            return [];
+        const { id: _id, type: _type, ...args } = item;
+        return [{ type: "tool_use_start", toolCall: { id, toolName: type, args } }];
+    }
+    onItemCompleted(params) {
+        if (this.isStale(str(params.turnId)))
+            return [];
+        const item = asRecord(params.item);
+        const id = str(item?.id);
+        const type = str(item?.type);
+        if (!item || !id || !type)
+            return [];
+        if (this.isCodeshellHostTool(item))
+            return [];
+        const output = str(item.aggregatedOutput) ?? str(item.output) ?? str(item.text) ?? str(item.result);
+        return [
+            {
+                type: "tool_result",
+                result: { id, toolName: type, ...(output !== undefined ? { result: output } : {}) },
+            },
+        ];
+    }
+}

package/dist/external-runtimes/codex/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Codex-specific pieces. The transport, the session store and the spawn env are
+ * shared with Claude Code (see `../shared/`) — both runtimes speak HTTP MCP with
+ * a bearer token, so there is one bridge implementation, not two.
+ */
+export { CodexEventTranslator } from "./event-translator.js";
+export type { CodexEventTranslatorOptions } from "./event-translator.js";

package/dist/external-runtimes/codex/index.js

@@ -0,0 +1,6 @@
+/**
+ * Codex-specific pieces. The transport, the session store and the spawn env are
+ * shared with Claude Code (see `../shared/`) — both runtimes speak HTTP MCP with
+ * a bearer token, so there is one bridge implementation, not two.
+ */
+export { CodexEventTranslator } from "./event-translator.js";

package/dist/external-runtimes/codex/runtime.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Codex as a CodeShell Agent Runtime.
+ *
+ * This is the piece that makes Codex usable as an execution backend rather than
+ * just a caller of CodeShell tools: it owns the app-server process, starts a
+ * thread, runs turns, translates notifications into `StreamEvent`, and wires the
+ * loopback MCP bridge so the model can reach CodeShell tools mid-turn.
+ *
+ * Deliberately NOT an `LLMClientBase` (§6.1, §22.1): Codex brings its own agent
+ * loop, tools, session and approval protocol. Wrapping it as a model client would
+ * nest two agent loops. This sits beside the Engine, not inside it.
+ *
+ * Timeouts follow §13.3's ordering and Cindy's measurements: the client has no
+ * global timeout (a late response is protocol-legal, and a global timeout
+ * manufactures orphan turns), so only the calls where hanging is worse than
+ * failing opt in.
+ */
+import type { StreamEvent } from "@cjhyy/code-shell-core/extension";
+import { type AppServerClientOptions } from "./app-server-client.js";
+import { type McpBridgeHandle } from "../shared/mcp-bridge.js";
+export interface CodexRuntimeOptions {
+    cwd: string;
+    /** CodeShell business session id — the authorization subject, never the thread id. */
+    businessSessionId: string;
+    /** Loopback MCP bridge the model reaches CodeShell tools through. */
+    bridge: McpBridgeHandle;
+    /**
+     * MCP server name CodeShell's tools are advertised under. Used to decide which
+     * approval elicitations are ours to accept — a name mismatch means the request
+     * belongs to some other server and must be declined.
+     */
+    bridgeServerName?: string;
+    model?: string;
+    /** Codex sandbox mode. Kebab-case per protocol (`workspace-write`, …). */
+    sandbox?: string;
+    /** Codex approval policy. Also kebab-case. */
+    approvalPolicy?: string;
+    client?: AppServerClientOptions;
+    log?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface CodexTurnHandle {
+    /** Codex turn id, once known. */
+    readonly turnId: string | undefined;
+    /** Resolves when the turn reaches a terminal state. */
+    readonly done: Promise<void>;
+}
+/**
+ * How the host answers Codex's own approval requests for its NATIVE tools.
+ *
+ * CodeShell Host Tools are NOT routed here — they go through the MCP bridge and
+ * are authorized by `ToolExecutor` (§10.3/§11.4). Answering native approvals here
+ * as well is what keeps a single operation from being approved twice.
+ */
+export type NativeApprovalDecision = "accept" | "acceptForSession" | "decline" | "cancel";
+export interface CodexRuntimeHooks {
+    onEvent?: (event: StreamEvent) => void;
+    /** Called for Codex's native tool approvals. Defaults to `decline`. */
+    onNativeApproval?: (request: {
+        method: string;
+        params: unknown;
+    }) => Promise<NativeApprovalDecision> | NativeApprovalDecision;
+}
+export declare class CodexRuntime {
+    private readonly options;
+    private readonly hooks;
+    readonly kind: "codex";
+    private readonly client;
+    private readonly log;
+    private translator?;
+    private threadId?;
+    private started;
+    private activeTurn?;
+    constructor(options: CodexRuntimeOptions, hooks?: CodexRuntimeHooks);
+    /** Codex thread id, once the thread exists. Protocol routing only — never the
+     *  authorization subject (§8.1). */
+    get runtimeSessionId(): string | undefined;
+    /**
+     * Spawn the app-server, handshake, and open a thread.
+     *
+     * Handler registration happens BEFORE `start()`: the server pushes
+     * notifications as soon as the transport is up, and registering later drops
+     * them (there is no readiness banner — the `initialize` reply is readiness).
+     */
+    start(): Promise<void>;
+    /**
+     * Run one turn. Resolves when the turn is terminal.
+     *
+     * A `turn/start` that times out does NOT mean the turn was not created — the
+     * daemon may have accepted it and lost the response. The translator's
+     * tombstones are what keep a late `turn/started` from reactivating a session
+     * that already reported terminal.
+     */
+    send(text: string): Promise<CodexTurnHandle>;
+    /**
+     * Interrupt the active turn.
+     *
+     * Bounded on purpose: a hung app-server would otherwise leave this RPC pending
+     * forever, which silently defeats a stop request. Note what interrupt does NOT
+     * do — it cannot retract side effects already dispatched, so it promises only
+     * that no further step starts (§13.3).
+     */
+    interrupt(): Promise<void>;
+    close(): Promise<void>;
+    private onNotification;
+    /**
+     * Codex's native-tool approvals. CodeShell Host Tools never arrive here —
+     * they come in over the MCP bridge and are authorized by `ToolExecutor`, which
+     * is precisely how the same operation avoids being approved twice.
+     *
+     * Default is `decline`: an unanswered or unknown approval must not become an
+     * implicit yes.
+     */
+    private onServerRequest;
+    /**
+     * Accept an approval elicitation for CodeShell's own MCP server, and only that.
+     *
+     * This is the §10.3/§11.4 "no double approval" rule in practice: the call is
+     * about to reach `SessionToolHost` → `ToolExecutor`, which applies the exposure
+     * allowlist, the permission rules and the approval backend. Asking the user here
+     * as well would prompt twice for one operation; declining here would make
+     * CodeShell tools permanently unreachable.
+     *
+     * Everything else is declined. An elicitation from a THIRD-PARTY MCP server, or
+     * one whose kind we do not recognise, is not ours to consent to — and a blanket
+     * accept here would hand the runtime a yes for any server it can name.
+     */
+    private answerMcpElicitation;
+}

package/dist/external-runtimes/codex/runtime.js

@@ -0,0 +1,216 @@
+import { CodexAppServerClient } from "./app-server-client.js";
+import { CodexEventTranslator } from "./event-translator.js";
+import { buildRuntimeSpawnEnv } from "../shared/spawn-env.js";
+import { codexBridgeConfigArgs } from "../shared/mcp-bridge.js";
+/** A thread/start or turn/start that hangs is worse than one that fails. */
+const CRITICAL_RPC_TIMEOUT_MS = 60_000;
+/** Interrupt is a fail-safe; an unbounded wait silently defeats it. */
+const INTERRUPT_TIMEOUT_MS = 10_000;
+export class CodexRuntime {
+    options;
+    hooks;
+    kind = "codex";
+    client;
+    log;
+    translator;
+    threadId;
+    started = false;
+    activeTurn;
+    constructor(options, hooks = {}) {
+        this.options = options;
+        this.hooks = hooks;
+        this.log = options.log ?? (() => { });
+        this.client = new CodexAppServerClient({
+            ...options.client,
+            cwd: options.cwd,
+            // Loopback must bypass any HTTP proxy, or Codex's Rust MCP client routes
+            // 127.0.0.1 through it and every tool call dies as UnexpectedContentType.
+            env: buildRuntimeSpawnEnv({
+                base: options.client?.env,
+                bridgeToken: { name: options.bridge.tokenEnvVar, value: options.bridge.token },
+            }),
+            // Point the thread at the bridge. The token travels by env var, not argv.
+            args: [...(options.client?.args ?? ["app-server"]), ...codexBridgeConfigArgs(options.bridge)],
+            log: this.log,
+        });
+    }
+    /** Codex thread id, once the thread exists. Protocol routing only — never the
+     *  authorization subject (§8.1). */
+    get runtimeSessionId() {
+        return this.threadId;
+    }
+    /**
+     * Spawn the app-server, handshake, and open a thread.
+     *
+     * Handler registration happens BEFORE `start()`: the server pushes
+     * notifications as soon as the transport is up, and registering later drops
+     * them (there is no readiness banner — the `initialize` reply is readiness).
+     */
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.client.onNotification((method, params) => this.onNotification(method, params));
+        this.client.onServerRequest((method, params) => this.onServerRequest(method, params));
+        this.client.start();
+        await this.client.request("initialize", {
+            clientInfo: { name: "codeshell", title: "CodeShell", version: "1" },
+            capabilities: { experimentalApi: true },
+        }, CRITICAL_RPC_TIMEOUT_MS);
+        const thread = (await this.client.request("thread/start", {
+            cwd: this.options.cwd,
+            ...(this.options.model ? { model: this.options.model } : {}),
+            ...(this.options.sandbox ? { sandbox: this.options.sandbox } : {}),
+            ...(this.options.approvalPolicy ? { approvalPolicy: this.options.approvalPolicy } : {}),
+        }, CRITICAL_RPC_TIMEOUT_MS));
+        const threadId = thread?.thread?.id;
+        if (!threadId)
+            throw new Error("thread/start returned no thread id");
+        this.threadId = threadId;
+        this.translator = new CodexEventTranslator({
+            threadId,
+            sessionId: this.options.businessSessionId,
+        });
+        this.log("runtime.thread_started", {
+            businessSessionId: this.options.businessSessionId,
+            threadIdPrefix: threadId.slice(0, 8),
+        });
+    }
+    /**
+     * Run one turn. Resolves when the turn is terminal.
+     *
+     * A `turn/start` that times out does NOT mean the turn was not created — the
+     * daemon may have accepted it and lost the response. The translator's
+     * tombstones are what keep a late `turn/started` from reactivating a session
+     * that already reported terminal.
+     */
+    async send(text) {
+        if (!this.threadId)
+            throw new Error("CodexRuntime.send() before start()");
+        let resolveDone;
+        const done = new Promise((resolve) => (resolveDone = resolve));
+        this.activeTurn = { resolve: resolveDone };
+        const response = (await this.client.request("turn/start", {
+            threadId: this.threadId,
+            // `text_elements` is required by the protocol even when empty.
+            input: [{ type: "text", text, text_elements: [] }],
+        }, CRITICAL_RPC_TIMEOUT_MS));
+        const turnId = response?.turn?.id;
+        if (this.activeTurn)
+            this.activeTurn.id = turnId;
+        return {
+            get turnId() {
+                return turnId;
+            },
+            done,
+        };
+    }
+    /**
+     * Interrupt the active turn.
+     *
+     * Bounded on purpose: a hung app-server would otherwise leave this RPC pending
+     * forever, which silently defeats a stop request. Note what interrupt does NOT
+     * do — it cannot retract side effects already dispatched, so it promises only
+     * that no further step starts (§13.3).
+     */
+    async interrupt() {
+        const turnId = this.activeTurn?.id;
+        if (!this.threadId || !turnId)
+            return;
+        try {
+            await this.client.request("turn/interrupt", { threadId: this.threadId, turnId }, INTERRUPT_TIMEOUT_MS);
+        }
+        catch (error) {
+            // Surface rather than swallow: a stop the user asked for that did not land
+            // must not look like it did.
+            this.log("runtime.interrupt_failed", {
+                error: error instanceof Error ? error.message.slice(0, 200) : "unknown",
+            });
+            throw error;
+        }
+    }
+    async close() {
+        // Settle any waiter first, so a close during a live turn cannot leave the
+        // caller awaiting forever (§13.4).
+        this.activeTurn?.resolve();
+        this.activeTurn = undefined;
+        await this.client.close();
+    }
+    onNotification(method, params) {
+        const events = this.translator?.translate({ method, params }) ?? [];
+        for (const event of events) {
+            try {
+                this.hooks.onEvent?.(event);
+            }
+            catch (error) {
+                this.log("runtime.event_handler_failed", {
+                    error: error instanceof Error ? error.name : "unknown",
+                });
+            }
+            if (event.type === "turn_complete") {
+                this.activeTurn?.resolve();
+                this.activeTurn = undefined;
+            }
+        }
+    }
+    /**
+     * Codex's native-tool approvals. CodeShell Host Tools never arrive here —
+     * they come in over the MCP bridge and are authorized by `ToolExecutor`, which
+     * is precisely how the same operation avoids being approved twice.
+     *
+     * Default is `decline`: an unanswered or unknown approval must not become an
+     * implicit yes.
+     */
+    async onServerRequest(method, params) {
+        // Codex asks for approval of OUR OWN MCP server's tools through
+        // `mcpServer/elicitation/request`, NOT through `item/permissions/requestApproval`.
+        // Measured: leaving it unhandled makes the app-server log
+        // `unhandled: mcpServer/elicitation/request` and the model report the tool call
+        // as "rejected" — so the reverse channel silently never fires. The distinguishing
+        // marker is `_meta.codex_approval_kind === "mcp_tool_call"`.
+        if (method === "mcpServer/elicitation/request") {
+            return this.answerMcpElicitation(params);
+        }
+        if (!method.includes("requestApproval")) {
+            // Some other server request (user input, …). Leave unhandled so the client
+            // answers method-not-found rather than inventing consent.
+            return undefined;
+        }
+        const decision = this.hooks.onNativeApproval
+            ? await this.hooks.onNativeApproval({ method, params })
+            : "decline";
+        this.log("runtime.native_approval", { method, decision });
+        return { decision };
+    }
+    /**
+     * Accept an approval elicitation for CodeShell's own MCP server, and only that.
+     *
+     * This is the §10.3/§11.4 "no double approval" rule in practice: the call is
+     * about to reach `SessionToolHost` → `ToolExecutor`, which applies the exposure
+     * allowlist, the permission rules and the approval backend. Asking the user here
+     * as well would prompt twice for one operation; declining here would make
+     * CodeShell tools permanently unreachable.
+     *
+     * Everything else is declined. An elicitation from a THIRD-PARTY MCP server, or
+     * one whose kind we do not recognise, is not ours to consent to — and a blanket
+     * accept here would hand the runtime a yes for any server it can name.
+     */
+    answerMcpElicitation(params) {
+        const record = params && typeof params === "object" ? params : {};
+        const meta = record._meta && typeof record._meta === "object"
+            ? record._meta
+            : {};
+        const kind = typeof meta.codex_approval_kind === "string" ? meta.codex_approval_kind : undefined;
+        const server = typeof record.serverName === "string" ? record.serverName : undefined;
+        const expected = this.options.bridgeServerName ?? "codeshell_tools";
+        const ours = kind === "mcp_tool_call" && server === expected;
+        this.log("runtime.mcp_elicitation", {
+            kind,
+            serverName: server,
+            decision: ours ? "accept" : "decline",
+        });
+        // `content`/`_meta` null: no form input, and no session-level persistence —
+        // each call is authorized on its own merits by ToolExecutor.
+        return { action: ours ? "accept" : "decline", content: null, _meta: null };
+    }
+}

package/dist/external-runtimes/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * External Agent Runtimes: driving Claude Code / Codex as execution backends and
+ * letting them call CodeShell tools back through one loopback MCP bridge.
+ *
+ * The reverse tool channel is runtime-AGNOSTIC (`shared/`). That was not the
+ * original plan — the design assumed Claude Code would need an in-process MCP
+ * server via `@anthropic-ai/claude-agent-sdk`. It turns out `claude --mcp-config`
+ * accepts an HTTP MCP server with an `Authorization` header, exactly as Codex
+ * does, so both runtimes share one transport and CodeShell takes on no new
+ * dependency. Verified end-to-end against real `codex-cli 0.145.0` and real
+ * `claude 2.1.220` — see `docs/todo/evidence/`.
+ *
+ * The one real difference: Codex injects a per-call `_meta.threadId`, so a single
+ * bridge can serve many concurrent threads. Claude Code sends no equivalent, so
+ * its bridge is pinned to one session and the PORT is the attribution.
+ */
+export { CODEX_MCP_TOKEN_ENV_VAR, codexBridgeConfigArgs, startLoopbackMcpBridge, threadIdFromMeta, } from "./shared/mcp-bridge.js";
+export type { BridgeToolHost, McpBridgeHandle, McpBridgeOptions } from "./shared/mcp-bridge.js";
+export { SessionContextStore } from "./shared/session-context-store.js";
+export type { ResolveRequest, SessionContextResult, SessionContextMissReason, ToolHostRef, } from "./shared/session-context-store.js";
+export { buildRuntimeSpawnEnv } from "./shared/spawn-env.js";
+export type { RuntimeSpawnEnvOptions } from "./shared/spawn-env.js";
+export { CodexEventTranslator } from "./codex/event-translator.js";
+export { CodexAppServerClient } from "./codex/app-server-client.js";
+export type { AppServerClientOptions } from "./codex/app-server-client.js";
+export { CodexRuntime } from "./codex/runtime.js";
+export type { CodexRuntimeOptions, CodexRuntimeHooks, CodexTurnHandle, NativeApprovalDecision, } from "./codex/runtime.js";
+export { buildClaudeMcpConfig, claudeAllowedToolNames, claudeBridgeArgs, CLAUDE_MCP_SERVER_NAME, } from "./claude-code/mcp-config.js";
+export type { ClaudeMcpConfigOptions, ClaudeMcpConfigFile } from "./claude-code/mcp-config.js";
+export { writeClaudeMcpConfigFile } from "./claude-code/mcp-config.js";
+export { ClaudeEventTranslator } from "./claude-code/event-translator.js";
+export type { ClaudeEventTranslatorOptions } from "./claude-code/event-translator.js";
+export { ClaudeCodeRuntime } from "./claude-code/runtime.js";
+export type { ClaudeRuntimeOptions, ClaudeRuntimeHooks, ClaudeTurnHandle, } from "./claude-code/runtime.js";
+export type { CodexEventTranslatorOptions } from "./codex/event-translator.js";
+export { startExternalRuntimeSession } from "./session-factory.js";
+export type { ExternalRuntimeKind, ExternalRuntimeSession, ExternalRuntimeSessionOptions, } from "./session-factory.js";

package/dist/external-runtimes/index.js

@@ -0,0 +1,27 @@
+/**
+ * External Agent Runtimes: driving Claude Code / Codex as execution backends and
+ * letting them call CodeShell tools back through one loopback MCP bridge.
+ *
+ * The reverse tool channel is runtime-AGNOSTIC (`shared/`). That was not the
+ * original plan — the design assumed Claude Code would need an in-process MCP
+ * server via `@anthropic-ai/claude-agent-sdk`. It turns out `claude --mcp-config`
+ * accepts an HTTP MCP server with an `Authorization` header, exactly as Codex
+ * does, so both runtimes share one transport and CodeShell takes on no new
+ * dependency. Verified end-to-end against real `codex-cli 0.145.0` and real
+ * `claude 2.1.220` — see `docs/todo/evidence/`.
+ *
+ * The one real difference: Codex injects a per-call `_meta.threadId`, so a single
+ * bridge can serve many concurrent threads. Claude Code sends no equivalent, so
+ * its bridge is pinned to one session and the PORT is the attribution.
+ */
+export { CODEX_MCP_TOKEN_ENV_VAR, codexBridgeConfigArgs, startLoopbackMcpBridge, threadIdFromMeta, } from "./shared/mcp-bridge.js";
+export { SessionContextStore } from "./shared/session-context-store.js";
+export { buildRuntimeSpawnEnv } from "./shared/spawn-env.js";
+export { CodexEventTranslator } from "./codex/event-translator.js";
+export { CodexAppServerClient } from "./codex/app-server-client.js";
+export { CodexRuntime } from "./codex/runtime.js";
+export { buildClaudeMcpConfig, claudeAllowedToolNames, claudeBridgeArgs, CLAUDE_MCP_SERVER_NAME, } from "./claude-code/mcp-config.js";
+export { writeClaudeMcpConfigFile } from "./claude-code/mcp-config.js";
+export { ClaudeEventTranslator } from "./claude-code/event-translator.js";
+export { ClaudeCodeRuntime } from "./claude-code/runtime.js";
+export { startExternalRuntimeSession } from "./session-factory.js";