@cjhyy/code-shell-capability-coding 0.8.0

package/dist/external-runtimes/session-factory.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The composition root for an external-runtime session.
+ *
+ * Until now every piece existed but nothing assembled them, so
+ * `createSessionToolHost` had no production caller. That absence is exactly how a
+ * real security defect slipped in earlier (an untrusted project could
+ * self-authorize, because no caller was passing `projectTrusted`) — an options
+ * object with no real caller is an options object nobody has had to get right.
+ * This module is that caller.
+ *
+ * It owns the assembly order, which is not arbitrary:
+ *
+ *  1. bridge first — it mints the token and port the runtime will be told about;
+ *  2. host second — it needs the exposure policy and the permission inputs;
+ *  3. register the session in the store BEFORE the runtime starts, so a tool call
+ *     on the runtime's very first turn can already be routed (§13.1);
+ *  4. runtime last.
+ *
+ * Teardown reverses it, and unregisters before disposing the host so a late
+ * request finds nothing rather than a disposed host (§13.4).
+ */
+import type { PermissionRule, ToolDefinition } from "@cjhyy/code-shell-core/extension";
+import { createSessionToolHost, type ExternalToolExposurePolicy, type ToolVisibilityInputs } from "@cjhyy/code-shell-core/extension";
+import { type CodexRuntimeHooks, type CodexRuntimeOptions } from "./codex/runtime.js";
+import { type ClaudeRuntimeHooks } from "./claude-code/runtime.js";
+export type ExternalRuntimeKind = "codex" | "claude-code";
+/**
+ * Everything the host must decide. Deliberately no defaults for the
+ * security-relevant fields: see `CreateSessionToolHostOptions`, where the same
+ * rule is enforced and tested. A default here would reintroduce the fail-open
+ * shape one layer up.
+ */
+export interface ExternalRuntimeSessionOptions {
+    kind: ExternalRuntimeKind;
+    cwd: string;
+    businessSessionId: string;
+    /** Registry holding the tools that may be exposed. */
+    registry: Parameters<typeof createSessionToolHost>[0]["registry"];
+    permissionMode: Parameters<typeof createSessionToolHost>[0]["permissionMode"];
+    presetRules: readonly PermissionRule[];
+    /** Whether the user has trusted the project at `cwd`. No default — §12.2. */
+    projectTrusted: boolean;
+    planMode: boolean;
+    visibility: ToolVisibilityInputs;
+    /**
+     * Tool exposure. Defaults to the reviewed first-phase allowlist rather than to
+     * "everything", so forgetting it cannot silently widen the surface.
+     */
+    exposure?: ExternalToolExposurePolicy;
+    approvalBackend?: Parameters<typeof createSessionToolHost>[0]["approvalBackend"];
+    /** Host seams the tools need (panels, browser, askUser, …). */
+    contextOverrides?: Parameters<typeof createSessionToolHost>[0]["contextOverrides"];
+    settingsScope?: Parameters<typeof createSessionToolHost>[0]["settingsScope"];
+    model?: string;
+    /** Codex only. Kebab-case per protocol. */
+    sandbox?: string;
+    /** Codex only. Kebab-case per protocol. */
+    approvalPolicy?: string;
+    /** Claude Code only: extra CLI args. */
+    claudeExtraArgs?: readonly string[];
+    /**
+     * Override how the runtime process is launched (Codex: app-server client
+     * options; Claude: the `claude` binary). Exists so the assembly can be tested
+     * against a fake runtime — a composition root that can only be exercised with a
+     * logged-in binary is a composition root nobody tests.
+     */
+    codexClient?: CodexRuntimeOptions["client"];
+    claudeCommand?: string;
+    hooks?: CodexRuntimeHooks & ClaudeRuntimeHooks;
+    log?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface ExternalRuntimeSession {
+    readonly kind: ExternalRuntimeKind;
+    readonly businessSessionId: string;
+    /** Runtime-side id (Codex thread / Claude session). Resume + routing only. */
+    readonly runtimeSessionId: string | undefined;
+    /** Tools actually exposed, after the allowlist and visibility guards. */
+    listTools(): readonly ToolDefinition[];
+    send(text: string): Promise<{
+        done: Promise<void>;
+    }>;
+    interrupt(): Promise<void>;
+    /** Reverses the assembly order; safe to call more than once. */
+    close(): Promise<void>;
+}
+/**
+ * Assemble and start an external-runtime session.
+ *
+ * The bridge is pinned to this one session for BOTH runtimes. Codex could share
+ * one bridge across threads (it sends `_meta.threadId`), but its first
+ * `tools/list` arrives before the thread exists and therefore cannot be routed —
+ * measured, and when Codex does not re-list, the tool stays invisible for the
+ * whole session. Claude Code sends no thread identity at all. One bridge per
+ * session makes the port the attribution and removes both problems; §22.7's cost
+ * (an extra port per session) is the price.
+ */
+export declare function startExternalRuntimeSession(options: ExternalRuntimeSessionOptions): Promise<ExternalRuntimeSession>;

package/dist/external-runtimes/session-factory.js

@@ -0,0 +1,110 @@
+import { createSessionToolHost, FIRST_PHASE_EXPOSURE, } from "@cjhyy/code-shell-core/extension";
+import { startLoopbackMcpBridge, } from "./shared/mcp-bridge.js";
+import { SessionContextStore } from "./shared/session-context-store.js";
+import { CodexRuntime } from "./codex/runtime.js";
+import { ClaudeCodeRuntime } from "./claude-code/runtime.js";
+/**
+ * Assemble and start an external-runtime session.
+ *
+ * The bridge is pinned to this one session for BOTH runtimes. Codex could share
+ * one bridge across threads (it sends `_meta.threadId`), but its first
+ * `tools/list` arrives before the thread exists and therefore cannot be routed —
+ * measured, and when Codex does not re-list, the tool stays invisible for the
+ * whole session. Claude Code sends no thread identity at all. One bridge per
+ * session makes the port the attribution and removes both problems; §22.7's cost
+ * (an extra port per session) is the price.
+ */
+export async function startExternalRuntimeSession(options) {
+    const log = options.log ?? (() => { });
+    const exposure = options.exposure ?? FIRST_PHASE_EXPOSURE;
+    const pinnedThreadId = `codeshell-${options.businessSessionId}`;
+    // 1. Bridge — mints the port and token the runtime is configured with.
+    const store = new SessionContextStore();
+    const bridge = await startLoopbackMcpBridge({
+        store,
+        singleSessionThreadId: pinnedThreadId,
+        log,
+    });
+    let host;
+    let runtime;
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        // Unregister BEFORE disposing: a late request must find nothing rather than a
+        // disposed host (§13.4).
+        store.unregister(pinnedThreadId);
+        await runtime?.close();
+        await host?.dispose();
+        await bridge.close();
+    };
+    try {
+        // 2. Host — the authorization boundary for every tool call the runtime makes.
+        host = createSessionToolHost({
+            businessSessionId: options.businessSessionId,
+            cwd: options.cwd,
+            registry: options.registry,
+            permissionMode: options.permissionMode,
+            presetRules: options.presetRules,
+            projectTrusted: options.projectTrusted,
+            planMode: options.planMode,
+            exposure,
+            visibility: options.visibility,
+            ...(options.approvalBackend ? { approvalBackend: options.approvalBackend } : {}),
+            ...(options.contextOverrides ? { contextOverrides: options.contextOverrides } : {}),
+            ...(options.settingsScope ? { settingsScope: options.settingsScope } : {}),
+        });
+        // 3. Register before the runtime starts, so a tool call on the very first
+        //    turn is already routable (§13.1).
+        store.register(pinnedThreadId, host);
+        // 4. Runtime.
+        const exposedToolNames = host.listTools().map((definition) => definition.name);
+        if (options.kind === "codex") {
+            const codex = new CodexRuntime({
+                cwd: options.cwd,
+                businessSessionId: options.businessSessionId,
+                bridge,
+                ...(options.model ? { model: options.model } : {}),
+                ...(options.sandbox ? { sandbox: options.sandbox } : {}),
+                ...(options.approvalPolicy ? { approvalPolicy: options.approvalPolicy } : {}),
+                ...(options.codexClient ? { client: options.codexClient } : {}),
+                log,
+            }, options.hooks ?? {});
+            await codex.start();
+            runtime = codex;
+        }
+        else {
+            runtime = new ClaudeCodeRuntime({
+                cwd: options.cwd,
+                businessSessionId: options.businessSessionId,
+                bridge,
+                exposedToolNames,
+                ...(options.model ? { model: options.model } : {}),
+                ...(options.claudeExtraArgs ? { extraArgs: options.claudeExtraArgs } : {}),
+                ...(options.claudeCommand ? { command: options.claudeCommand } : {}),
+                log,
+            }, options.hooks ?? {});
+            // Claude Code is one process per turn; the first send() is the start.
+        }
+    }
+    catch (error) {
+        // A runtime that failed to start must not leave an orphaned bridge holding a
+        // port and a live token (§13.1).
+        await close();
+        throw error;
+    }
+    const activeHost = host;
+    const activeRuntime = runtime;
+    return {
+        kind: options.kind,
+        businessSessionId: options.businessSessionId,
+        get runtimeSessionId() {
+            return activeRuntime.runtimeSessionId;
+        },
+        listTools: () => activeHost.listTools(),
+        send: (text) => activeRuntime.send(text),
+        interrupt: () => activeRuntime.interrupt(),
+        close,
+    };
+}

package/dist/external-runtimes/shared/mcp-bridge.d.ts

@@ -0,0 +1,66 @@
+import type { SessionContextStore } from "./session-context-store.js";
+/** What the bridge needs of a session tool host. Structural, so this module
+ *  does not depend on core's concrete implementation. */
+export interface BridgeToolHost {
+    readonly businessSessionId: string;
+    listTools(): readonly {
+        name: string;
+        description: string;
+        inputSchema: unknown;
+    }[];
+    execute(call: {
+        id: string;
+        name: string;
+        input: unknown;
+    }): Promise<{
+        result?: string;
+        error?: string;
+        isError?: boolean;
+    }>;
+}
+export interface McpBridgeOptions {
+    store: SessionContextStore<BridgeToolHost>;
+    /** Logical MCP server name Codex is configured with. */
+    serverName?: string;
+    /**
+     * Bind this bridge to exactly ONE session, for runtimes that do not send a
+     * per-call thread identity.
+     *
+     * Codex injects `_meta.threadId`, which is what lets one shared bridge serve
+     * many threads safely. Claude Code sends no equivalent — so for it the binding
+     * has to be the PORT: one bridge, one session, and whatever arrives on this
+     * socket belongs to that session by construction.
+     *
+     * This is not the "guess the foreground session" fallback that §11.3 and §22.5
+     * forbid. The distinction is that nothing is being inferred: a request cannot
+     * be misattributed, because there is only one possible attribution and it was
+     * fixed before the port was opened. The cost is that a shared bridge is no
+     * longer possible for such a runtime — which is exactly the §22.7 trade-off,
+     * accepted here per-runtime rather than globally.
+     */
+    singleSessionThreadId?: string;
+    /** Cap on a single request body. Prevents an oversized init/call. */
+    maxBodyBytes?: number;
+    /**
+     * Structured log sink. Deliberately narrow: §12.4 forbids logging the bearer
+     * token, full tool arguments, or full results, so only classifications and
+     * identifiers get through here.
+     */
+    log?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface McpBridgeHandle {
+    /** `http://127.0.0.1:<port>/mcp` — pass to Codex as `mcp_servers.<n>.url`. */
+    readonly url: string;
+    /** Value for the env var named by `mcp_servers.<n>.bearer_token_env_var`. */
+    readonly token: string;
+    readonly tokenEnvVar: string;
+    close(): Promise<void>;
+}
+export declare const CODEX_MCP_TOKEN_ENV_VAR = "CODESHELL_CODEX_MCP_TOKEN";
+export declare function threadIdFromMeta(params: unknown): string | undefined;
+export declare function startLoopbackMcpBridge(options: McpBridgeOptions): Promise<McpBridgeHandle>;
+/**
+ * Codex CLI config flags that point a thread at this bridge. The token travels
+ * by environment variable, never in argv (§12.2).
+ */
+export declare function codexBridgeConfigArgs(handle: McpBridgeHandle, serverName?: string): string[];

package/dist/external-runtimes/shared/mcp-bridge.js

@@ -0,0 +1,365 @@
+/**
+ * Loopback HTTP MCP bridge: the reverse channel a Codex thread uses to call
+ * CodeShell tools (§11.2).
+ *
+ * Shape and constraints are not guesswork — they were established against a real
+ * `codex-cli 0.145.0` (probes in `docs/todo/evidence/`):
+ *
+ *  - Codex sends `accept: text/event-stream, application/json`. Answering with a
+ *    plain JSON body makes it report `user cancelled MCP tool call` — a
+ *    thoroughly misleading error that reads like a user refusal but is a
+ *    transport mismatch. So: reply as SSE whenever the client will take it.
+ *  - Thread identity arrives in the JSON-RPC body as `_meta.threadId` (and
+ *    `_meta["x-codex-turn-metadata"].thread_id`), NOT in any HTTP header. The
+ *    only headers present are `mcp-protocol-version`, `accept`, `authorization`.
+ *  - `bearer_token_env_var` is a real, shipping Codex config surface, so the
+ *    token goes through the environment and never onto a command line.
+ *
+ * Everything the model controls — tool name, arguments, call ordering — is
+ * untrusted. Session identity is bound out of band via the thread context store.
+ */
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+const MCP_PATH = "/mcp";
+const DEFAULT_MAX_BODY = 1024 * 1024;
+export const CODEX_MCP_TOKEN_ENV_VAR = "CODESHELL_CODEX_MCP_TOKEN";
+/** Loopback only. A bridge that answers off-host would expose CodeShell tools
+ *  to the network; §11.2 requires 127.0.0.1 / ::1 and nothing else. */
+function isLoopback(req) {
+    const address = req.socket.remoteAddress ?? "";
+    return (address === "127.0.0.1" ||
+        address === "::1" ||
+        address === "::ffff:127.0.0.1" ||
+        address.startsWith("127."));
+}
+export function threadIdFromMeta(params) {
+    if (!params || typeof params !== "object")
+        return undefined;
+    const meta = params._meta;
+    if (!meta || typeof meta !== "object")
+        return undefined;
+    const direct = meta.threadId;
+    if (typeof direct === "string" && direct)
+        return direct;
+    const turn = meta["x-codex-turn-metadata"];
+    if (turn && typeof turn === "object") {
+        const nested = turn.thread_id;
+        if (typeof nested === "string" && nested)
+            return nested;
+    }
+    return undefined;
+}
+function turnIdFromMeta(params) {
+    if (!params || typeof params !== "object")
+        return undefined;
+    const meta = params._meta;
+    if (!meta || typeof meta !== "object")
+        return undefined;
+    const turn = meta["x-codex-turn-metadata"];
+    if (turn && typeof turn === "object") {
+        const id = turn.turn_id;
+        if (typeof id === "string" && id)
+            return id;
+    }
+    return undefined;
+}
+/** Model-facing text for a routing refusal. Says what happened without leaking
+ *  which other sessions exist. */
+function missMessage(reason) {
+    switch (reason) {
+        case "missing_thread_id":
+            return "Refused: this tool call carried no thread identity, so it cannot be attributed to a session.";
+        case "unknown_thread":
+            return "Refused: this thread is not registered with the CodeShell host.";
+        case "stale_generation":
+            return "Refused: this thread belongs to a previous host generation and is no longer valid.";
+        case "ambiguous_thread":
+            return "Refused: a single batch may not span multiple threads.";
+    }
+}
+export async function startLoopbackMcpBridge(options) {
+    const token = randomBytes(32).toString("hex");
+    const maxBody = options.maxBodyBytes ?? DEFAULT_MAX_BODY;
+    const serverName = options.serverName ?? "codeshell_tools";
+    const log = options.log ?? (() => { });
+    const store = options.store;
+    // Treat "" as unset explicitly. `??` only guards null/undefined, so an empty
+    // string would silently fall back to caller-supplied `_meta` — restoring exactly
+    // the caller-steered routing the pin exists to remove.
+    const pinnedThreadId = options.singleSessionThreadId || undefined;
+    if (options.singleSessionThreadId !== undefined && !pinnedThreadId) {
+        throw new Error("singleSessionThreadId must be a non-empty string when provided.");
+    }
+    /**
+     * Thread identity for a request. When the bridge is pinned to one session the
+     * pin wins outright — a runtime that sends no `_meta.threadId` must not be able
+     * to steer routing by supplying one either.
+     */
+    const threadIdFor = (params) => pinnedThreadId ?? threadIdFromMeta(params);
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((error) => {
+            log("bridge.handler_failed", { error: error instanceof Error ? error.name : "unknown" });
+            if (!res.headersSent)
+                res.writeHead(500);
+            res.end();
+        });
+    });
+    async function handle(req, res) {
+        if (!isLoopback(req)) {
+            log("bridge.rejected", { reason: "non_loopback" });
+            res.writeHead(403).end();
+            return;
+        }
+        if (req.url !== MCP_PATH) {
+            res.writeHead(404).end();
+            return;
+        }
+        // POST only. A GET with a valid token used to return 202, which is both
+        // misleading (MCP Streamable HTTP reserves GET for opening an SSE stream,
+        // which this bridge does not offer) and the natural shape for a
+        // browser-originated probe.
+        if (req.method !== "POST") {
+            log("bridge.rejected", { reason: "method_not_allowed", method: req.method });
+            res.writeHead(405, { allow: "POST" }).end();
+            return;
+        }
+        // Constant-shape check; the token never reaches the log.
+        if (req.headers.authorization !== `Bearer ${token}`) {
+            log("bridge.rejected", { reason: "unauthorized" });
+            res.writeHead(401).end();
+            return;
+        }
+        const body = await readBody(req, maxBody);
+        if (body === null) {
+            log("bridge.rejected", { reason: "body_too_large" });
+            res.writeHead(413).end();
+            return;
+        }
+        if (body === "") {
+            res.writeHead(202).end();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            log("bridge.rejected", { reason: "malformed_json" });
+            res.writeHead(400).end();
+            return;
+        }
+        // JSON-RPC allows an array (batch). Left unhandled, a batch fell through
+        // every branch below and got `{result:{}}` with HTTP 200 — no host reached,
+        // so it failed closed, but it failed SILENTLY and told the client it had
+        // succeeded. Refuse it explicitly and say why.
+        //
+        // Batches are not supported at all rather than resolved per item: a mixed
+        // batch would touch two sessions on the strength of one authorization
+        // (§11.3), and `store.resolveBatch()` exists for the day batching is added.
+        if (Array.isArray(parsed)) {
+            const threadIds = parsed.map((entry) => threadIdFor(entry?.params));
+            const batch = store.resolveBatch(threadIds, store.generation);
+            const reason = batch.ok ? "batch_unsupported" : batch.reason;
+            log("bridge.rejected", { reason, itemCount: parsed.length });
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(JSON.stringify({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32600,
+                    message: batch.ok || batch.reason === "ambiguous_thread"
+                        ? "Batched requests are not supported by this bridge."
+                        : missMessage(batch.reason),
+                },
+            }));
+            return;
+        }
+        if (!parsed || typeof parsed !== "object") {
+            log("bridge.rejected", { reason: "not_an_object" });
+            res.writeHead(400).end();
+            return;
+        }
+        const message = parsed;
+        const reply = (result) => {
+            // `id` must always be present: JSON.stringify drops an undefined value,
+            // and a reply with no id is spec-invalid and uncorrelatable.
+            const payload = JSON.stringify({
+                jsonrpc: "2.0",
+                id: message.id ?? null,
+                result,
+            });
+            // SSE when the client accepts it — see the module header; a plain JSON body
+            // makes Codex report the call as user-cancelled.
+            if (String(req.headers.accept ?? "").includes("text/event-stream")) {
+                res.writeHead(200, {
+                    "content-type": "text/event-stream",
+                    "cache-control": "no-cache",
+                    connection: "keep-alive",
+                });
+                res.write(`event: message\ndata: ${payload}\n\n`);
+                res.end();
+                return;
+            }
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(payload);
+        };
+        if (message.method === "initialize") {
+            reply({
+                protocolVersion: message.params?.protocolVersion ??
+                    "2025-06-18",
+                capabilities: { tools: {} },
+                serverInfo: { name: serverName, version: "1" },
+            });
+            return;
+        }
+        if (typeof message.method === "string" && message.method.startsWith("notifications/")) {
+            res.writeHead(202).end();
+            return;
+        }
+        if (message.method === "tools/list") {
+            const resolved = store.resolve({
+                threadId: threadIdFor(message.params),
+                generation: store.generation,
+            });
+            if (!resolved.ok) {
+                // Advertise nothing rather than guessing whose tools to show. A wrong
+                // guess here would leak one session's surface into another's prompt.
+                //
+                // Observed against real codex-cli 0.145.0: the FIRST `tools/list` of a
+                // run carries no `_meta.threadId` at all — the thread does not exist yet —
+                // so on a SHARED bridge it necessarily lands here.
+                //
+                // An earlier note here claimed Codex reliably re-issues `tools/list` once
+                // the thread exists. That was wrong: it does so only sometimes, and when
+                // it does not, the tool is invisible for the entire session (measured
+                // both ways on the same binary). Do not depend on the retry.
+                //
+                // The supported fix is `singleSessionThreadId`: one bridge per session,
+                // where the port is the attribution, so the pre-thread `tools/list`
+                // resolves. §22.7's trade-off, taken per-runtime. A shared bridge remains
+                // correct for a runtime that identifies every call — it just cannot
+                // advertise tools before the first thread exists.
+                log("bridge.tools_list_refused", { reason: resolved.reason });
+                reply({ tools: [] });
+                return;
+            }
+            const tools = resolved.host.listTools().map((definition) => ({
+                name: definition.name,
+                description: definition.description,
+                inputSchema: definition.inputSchema,
+            }));
+            log("bridge.tools_list", {
+                businessSessionId: resolved.host.businessSessionId,
+                count: tools.length,
+            });
+            reply({ tools });
+            return;
+        }
+        if (message.method === "tools/call") {
+            const params = message.params;
+            const threadId = threadIdFor(message.params);
+            const resolved = store.resolve({ threadId, generation: store.generation });
+            if (!resolved.ok) {
+                log("bridge.call_refused", {
+                    reason: resolved.reason,
+                    threadIdPrefix: threadId?.slice(0, 8),
+                });
+                reply({ content: [{ type: "text", text: missMessage(resolved.reason) }], isError: true });
+                return;
+            }
+            const name = typeof params?.name === "string" ? params.name : "";
+            const started = Date.now();
+            // The host is the authorization boundary; the bridge only routes.
+            const outcome = await resolved.host.execute({
+                id: turnIdFromMeta(message.params) ?? `mcp-${randomBytes(6).toString("hex")}`,
+                name,
+                input: params?.arguments ?? {},
+            });
+            log("bridge.call", {
+                businessSessionId: resolved.host.businessSessionId,
+                threadIdPrefix: threadId?.slice(0, 8),
+                toolName: name,
+                resultStatus: outcome.isError ? "error" : "ok",
+                durationMs: Date.now() - started,
+            });
+            reply({
+                content: [{ type: "text", text: String(outcome.result ?? outcome.error ?? "") }],
+                isError: Boolean(outcome.isError),
+            });
+            return;
+        }
+        reply({});
+    }
+    // Streamable HTTP is a long-lived SSE stream. Node's default 5s keep-alive
+    // severs the Codex connection mid-session; `headersTimeout` must stay >=
+    // keepAliveTimeout, and 0 means unlimited for both. A Codex MCP request can
+    // also be genuinely large (base64 images), so the per-request clock is off too
+    // — body size is bounded explicitly in readBody() instead.
+    //
+    // Credit where due: this is one of two latent bugs found by reading the
+    // `makecindy/cindy` reference implementation (§16). Without it the bridge
+    // works in a fast test and drops out after five seconds in real use.
+    server.keepAliveTimeout = 0;
+    server.headersTimeout = 0;
+    server.requestTimeout = 0;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // Resolve only once actually listening: a caller that hands the url to a
+        // spawned Codex before the socket is up gets a connection refused.
+        server.listen(0, "127.0.0.1", () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const { port } = server.address();
+    return {
+        url: `http://127.0.0.1:${port}${MCP_PATH}`,
+        token,
+        tokenEnvVar: CODEX_MCP_TOKEN_ENV_VAR,
+        async close() {
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+async function readBody(req, limit) {
+    return await new Promise((resolve) => {
+        let size = 0;
+        const chunks = [];
+        let aborted = false;
+        req.on("data", (chunk) => {
+            if (aborted)
+                return;
+            size += chunk.length;
+            if (size > limit) {
+                // Stop accumulating, but do NOT destroy the socket: the caller still has
+                // to send 413. Tearing the connection down here surfaces as ECONNRESET,
+                // which tells the client nothing about what went wrong.
+                aborted = true;
+                req.pause();
+                resolve(null);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!aborted)
+                resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+        req.on("error", () => {
+            if (!aborted)
+                resolve("");
+        });
+    });
+}
+/**
+ * Codex CLI config flags that point a thread at this bridge. The token travels
+ * by environment variable, never in argv (§12.2).
+ */
+export function codexBridgeConfigArgs(handle, serverName = "codeshell_tools") {
+    return [
+        "-c",
+        `mcp_servers.${serverName}.url="${handle.url}"`,
+        "-c",
+        `mcp_servers.${serverName}.bearer_token_env_var="${handle.tokenEnvVar}"`,
+    ];
+}