@mclawnet/codex-adapter 0.1.0

package/dist/codex-adapter.js

@@ -0,0 +1,911 @@
+import { execSync, spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { buildCodexSpawnArgs, cleanupBriefingFile } from "./codex-spawn-args.js";
+import { createLogger, preview } from "@mclawnet/logger";
+import { JsonRpcClient } from "./json-rpc-client.js";
+import { buildApprovalReply, parseApprovalRequest, } from "./permission-mapper.js";
+import { mapCodexFrame } from "./output-mapper.js";
+import { CODEX_MODELS, CODEX_MODES } from "./catalog.js";
+import { detectCodexInstall } from "./detect.js";
+const log = createLogger({ module: "codex-adapter" });
+const isWin = platform() === "win32";
+/**
+ * Resolve the codex CLI binary the same way claude-adapter resolves claude:
+ * use the OS lookup tool (where/which), fall back to known install paths.
+ *
+ * Without this, Windows users hit two failure modes:
+ *   1. `spawn("codex", ...)` fails because Windows `CreateProcess` does NOT
+ *      consult PATHEXT — only cmd.exe does — so a bare "codex" never finds
+ *      the npm-installed `codex.cmd` / `codex.exe` shim.
+ *   2. Even if cmd.exe is on the way, post-CVE-2024-27980 Node refuses to
+ *      spawn `.cmd` / `.bat` without `shell: true`.
+ */
+function resolveCodexBin(explicit) {
+    if (explicit && explicit !== "codex")
+        return explicit;
+    const names = isWin ? ["codex.exe", "codex.cmd", "codex.bat"] : ["codex"];
+    const whichCmd = isWin ? "where" : "which";
+    for (const name of names) {
+        try {
+            const found = execSync(`${whichCmd} ${name}`, {
+                encoding: "utf-8",
+                // 1.5s is plenty for `where`/`which` on a healthy machine; the old
+                // 5s × 3 worst-case (15s blocking event loop) showed up on slow
+                // domain-joined Windows hosts / network-PATH setups.
+                timeout: 1500,
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim().split(/\r?\n/)[0];
+            if (found && existsSync(found))
+                return found;
+        }
+        catch {
+            /* not in PATH */
+        }
+    }
+    const home = homedir();
+    const fallbacks = isWin
+        ? [
+            join(home, "AppData", "Roaming", "npm", "codex.cmd"),
+            join(home, "AppData", "Roaming", "npm", "codex.exe"),
+            join(home, ".cargo", "bin", "codex.exe"),
+            join(home, ".local", "bin", "codex.exe"),
+        ]
+        : [
+            join(home, ".cargo", "bin", "codex"),
+            join(home, ".local", "bin", "codex"),
+            "/opt/homebrew/bin/codex",
+            "/usr/local/bin/codex",
+        ];
+    for (const p of fallbacks) {
+        if (existsSync(p))
+            return p;
+    }
+    return isWin ? "codex.cmd" : "codex";
+}
+/**
+ * Module-level cache for the resolved codex binary. Without this, every
+ * CodexAdapter instance (created per-session by the agent's adapter factory)
+ * pays the `where`/`which` cost again. On a Windows host where `where`
+ * times out (slow PATH, network drive, AV scan), 3 lookups × 1.5s would
+ * stall agent startup for every spawn.
+ *
+ * Cache is keyed on the override string so explicit per-instance overrides
+ * (e.g. tests) bypass the shared cache.
+ */
+const resolvedCodexBinCache = new Map();
+let resolveCodexBinCallCount = 0;
+function getResolvedCodexBin(explicit) {
+    const key = explicit ?? "";
+    const hit = resolvedCodexBinCache.get(key);
+    if (hit)
+        return hit;
+    resolveCodexBinCallCount++;
+    const resolved = resolveCodexBin(explicit);
+    resolvedCodexBinCache.set(key, resolved);
+    return resolved;
+}
+/** Test-only: clear the resolved-bin cache between cases. */
+export function __resetResolvedCodexBinCache() {
+    resolvedCodexBinCache.clear();
+    resolveCodexBinCallCount = 0;
+}
+/** Test-only: how many times resolveCodexBin actually ran (i.e. cache misses). */
+export function __getResolveCodexBinCallCount() {
+    return resolveCodexBinCallCount;
+}
+/**
+ * Resolve how to spawn codex without invoking cmd.exe on Windows.
+ *
+ * codex.cmd is an npm shim that dispatches to the real Rust .exe (or in
+ * some installs, a node-shimmed cli.js). Spawning the .cmd directly:
+ *   - requires `shell: true` post-CVE-2024-27980, which would also have to
+ *     deal with cmd.exe's 8191-char command-line cap.
+ *   - drops the child's stdio attachment in subtle ways through cmd.exe.
+ *
+ * So we parse the shim and spawn the underlying .exe (or `node cli.js`)
+ * directly. Mirrors claude-adapter's resolveSpawnTarget pattern.
+ */
+export function resolveSpawnTarget(codexBin) {
+    // Re-read platform per call (instead of using the module-level `isWin`
+    // constant) so tests can flip `process.platform` to exercise Windows
+    // paths from a macOS / Linux CI. Mirrors claude-adapter's pattern.
+    const isWindows = platform() === "win32";
+    if (!isWindows || !codexBin.toLowerCase().endsWith(".cmd")) {
+        return { command: codexBin, prefixArgs: [] };
+    }
+    try {
+        const cmdContent = readFileSync(codexBin, "utf-8");
+        // codex shim typically points at a sibling .exe: e.g.
+        //   "%~dp0\node_modules\@openai\codex\bin\codex.exe" %*
+        const exeMatch = cmdContent.match(/(?:%~?dp0%?)[\\/](.+?\.exe)/i);
+        if (exeMatch) {
+            const relParts = exeMatch[1].split(/[\\/]/);
+            const exePath = join(dirname(codexBin), ...relParts);
+            if (existsSync(exePath))
+                return { command: exePath, prefixArgs: [] };
+        }
+        // Fallback: npm-style `node cli.js` shim.
+        const jsMatch = cmdContent.match(/(?:%~?dp0%?)[\\/](.+?\.js)/i);
+        if (jsMatch) {
+            const relParts = jsMatch[1].split(/[\\/]/);
+            const cliJsPath = join(dirname(codexBin), ...relParts);
+            if (existsSync(cliJsPath)) {
+                return { command: process.execPath, prefixArgs: [cliJsPath] };
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    // Last resort: invoke through cmd.exe. Loses the 8191-char cap protection
+    // but at least the process gets spawned. Args are short for codex so this
+    // is unlikely to bite.
+    return { command: codexBin, prefixArgs: [] };
+}
+const CLAWNET_CLIENT_INFO = {
+    name: "clawnet",
+    version: "0.1.0",
+    title: "ClawNet Agent",
+};
+/**
+ * Cap on the per-process `assistantTextSeen` map. Bounds memory growth
+ * from interrupted agentMessage items that never fire `item/completed`
+ * (a single very long session would otherwise leak forever now that
+ * `turn/completed` no longer wholesale-clears — see the comment on that
+ * branch in `handleNotification`).
+ *
+ * A single codex turn typically produces 1-2 agentMessage items; 64
+ * comfortably covers extreme cases without making eviction reachable
+ * during normal use. If the cap is exceeded, the OLDEST untouched entry
+ * is dropped (FIFO); a subsequent matching `item/completed` for that
+ * itemId would then see an empty accumulator and emit the full text,
+ * producing at most one duplicated message instead of an unbounded leak.
+ */
+const ASSISTANT_TEXT_SEEN_MAX = 64;
+/**
+ * Per-process state wrapper. Holds the JSON-RPC client + pending approval
+ * resolvers so `respondToPermission` can find the right server-initiated
+ * request id to reply to.
+ */
+export class CodexProcess extends EventEmitter {
+    id;
+    workDir;
+    pid;
+    proc;
+    killed = false;
+    /** callId → JSON-RPC server-request id we still owe a result to. */
+    pendingApprovals = new Map();
+    /** callId → originating wire family (drives v2/legacy/mcp reply shape). */
+    approvalMethods = new Map();
+    /** Monotonic counter for approval resolver keys. */
+    nextResolverKey = 1;
+    /** Resolver registered by the rpc client for each pending approval. */
+    approvalResolvers = new Map();
+    rpc;
+    backendSessionId;
+    /**
+     * Thread id to resume on agent restart. When set, handshake() sends
+     * `thread/resume { threadId }` instead of `thread/start { cwd }`.
+     * Set from SpawnOptions.resumeId in CodexAdapter.spawn(). Must NOT be
+     * passed as `--resume` CLI flag — app-server rejects it.
+     */
+    resumeId;
+    /** True once `initialize` round-trip + `thread/start` (or `thread/resume`) have completed. */
+    handshakeComplete = false;
+    /** Inputs queued by send() while the handshake is still in flight. */
+    pendingInputs = [];
+    /**
+     * Per-itemId accumulator of assistant text already emitted via
+     * `item/agentMessage/delta` chunks. Consulted on `item/completed` with
+     * `item.type === "agentMessage"` to decide what (if anything) of the
+     * completed payload still needs to be emitted. Without this, codex
+     * delivers the same assistant text twice (deltas + final) and the UI
+     * renders "Hello worldHello world".
+     *
+     * Entries are cleared per item when the matching `item/completed` fires.
+     * We do NOT clear the whole map on `turn/completed`: codex's wire
+     * doesn't strictly guarantee that every item/completed precedes its
+     * parent turn/completed, and a trailing item/completed against an empty
+     * accumulator would re-emit the full text (reactivating the bug). To
+     * cap unbounded growth from interrupted turns that never fire
+     * completed, the map is size-bounded with FIFO eviction; in practice a
+     * single turn produces 1-2 agentMessage items so the cap is generous.
+     */
+    assistantTextSeen = new Map();
+    /** Temp file for briefing injection; cleaned up on kill(). */
+    briefingFile;
+    /**
+     * Set by CodexAdapter.spawn() so handshake() can surface real process-exit
+     * info if the codex CLI died (e.g. arg parse error). Without this, a dead
+     * process leads to a generic "handshake timeout" instead of the actual
+     * "error: unexpected argument …" stderr message.
+     *
+     * Default returns (null, "") for tests that construct CodexProcess
+     * directly without going through spawn() (e.g. attachRpc mock pipes).
+     * spawn() overrides these with real getters wired to the child process.
+     */
+    getExitInfo = () => null;
+    getStderr = () => "";
+    /** Allocate a resolver key. Monotonic; never reused. */
+    allocResolverKey() {
+        return this.nextResolverKey++;
+    }
+    constructor(sessionId, workDir, proc) {
+        super();
+        this.id = sessionId;
+        this.workDir = workDir;
+        this.proc = proc;
+        this.pid = proc?.pid;
+    }
+    async kill() {
+        this.killed = true;
+        // Drain any pending approval bookkeeping so long-running hubs don't leak
+        // entries on aborted sessions. Resolve any outstanding RPC promise with a
+        // "cancel"-equivalent so callers awaiting `respondToPermission` never hang.
+        for (const [, resolver] of this.approvalResolvers) {
+            try {
+                resolver({ decision: "abort" });
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.pendingApprovals.clear();
+        this.approvalMethods.clear();
+        this.approvalResolvers.clear();
+        this.pendingInputs.length = 0;
+        this.assistantTextSeen.clear();
+        if (this.briefingFile) {
+            cleanupBriefingFile(this.briefingFile);
+            this.briefingFile = undefined;
+        }
+        if (this.proc && !this.proc.killed) {
+            try {
+                this.proc.kill("SIGTERM");
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    isAlive() {
+        if (this.killed)
+            return false;
+        if (!this.proc)
+            return true;
+        return !this.proc.killed && this.proc.exitCode === null;
+    }
+}
+/**
+ * CodexAdapter — BackendAdapter wrapping `codex app-server --listen stdio://`.
+ *
+ * M3.S3 scope: spawn/stop/send/onOutput plus the permission flow
+ * (`onPermissionRequest` / `respondToPermission`). Resume + token-budget +
+ * MCP plumbing land in follow-up slices.
+ */
+export class CodexAdapter {
+    type = "codex";
+    codexBin;
+    handshakeTimeoutMs;
+    detect;
+    constructor(options) {
+        this.codexBin = getResolvedCodexBin(options?.codexBin);
+        // Precedence: explicit constructor option > env var > 15s default. The
+        // env var (CLAWNET_CODEX_HANDSHAKE_TIMEOUT_MS) is the escape hatch for
+        // slow CI / cold-start machines where 15s isn't enough and the user
+        // can't easily inject a CodexAdapterOptions override.
+        const envTimeout = Number(process.env.CLAWNET_CODEX_HANDSHAKE_TIMEOUT_MS);
+        this.handshakeTimeoutMs =
+            options?.handshakeTimeoutMs ??
+                (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : 15000);
+        this.detect = options?.detect ?? detectCodexInstall;
+    }
+    async spawn(options) {
+        let cwd = options.workDir || process.cwd();
+        if (!existsSync(cwd))
+            cwd = homedir();
+        // Build args with MCP + briefing injection
+        const mcpServer = this.buildMcpServerConfig(options);
+        const { args, briefingFile, modeSource } = buildCodexSpawnArgs({
+            sessionId: options.sessionId,
+            resumeId: options.resumeId,
+            systemPrompt: options.systemPrompt,
+            mcpServer,
+            sandbox: options.sandbox,
+            model: options.model,
+            mode: options.mode,
+        });
+        if (options.mode && modeSource !== "options.mode") {
+            log.warn({ sessionId: options.sessionId, requestedMode: options.mode, modeSource }, "codex: invalid options.mode ignored, falling back");
+        }
+        log.info({ sessionId: options.sessionId, bin: this.codexBin, args, cwd, resumeId: options.resumeId }, "codex spawn: forking app-server");
+        const { command, prefixArgs } = resolveSpawnTarget(this.codexBin);
+        if (command !== this.codexBin) {
+            log.info({ sessionId: options.sessionId, bin: this.codexBin, spawnCmd: command, prefixArgs }, "codex spawn: using resolved shim target (windows .cmd bypass)");
+        }
+        const proc = spawn(command, [...prefixArgs, ...args], {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...(options.env ?? {}) },
+            windowsHide: true,
+        });
+        // Capture exit state into a closure so handshake() can surface it if
+        // initialize / thread RPC times out. Without this guard a dead codex
+        // (e.g. CLI arg parse error → ~600ms after spawn) would leave the
+        // adapter waiting handshakeTimeoutMs (default 15s) with a generic
+        // "handshake timeout" message. With it, we report exit code + stderr.
+        const stderrChunks = [];
+        proc.stderr?.on("data", (chunk) => {
+            const text = chunk.toString("utf8").trim();
+            if (text) {
+                stderrChunks.push(text);
+                log.warn({ sessionId: options.sessionId, stderr: text }, "codex stderr");
+            }
+        });
+        let exitInfo = null;
+        // cp is built AFTER this Promise resolves, so capture a thunk and resolve
+        // it lazily. proc.on("exit") needs to re-emit on cp so the BackendAdapter
+        // contract's onExit/onError subscribers (session-manager) actually fire —
+        // without this re-emit, codex crashes silently never reach the swarm
+        // coordinator's handleRoleCrashed path and the queen stays unaware.
+        let createdCp;
+        // Shared emit helper: invoked both from the proc.on("exit") handler and
+        // the late-fire safety branch below. Centralizes the "emit exit + maybe
+        // emit error with stderr" contract so future changes can't drift.
+        const emitProcessExit = (cp, code, signal) => {
+            try {
+                cp.emit("exit", code);
+            }
+            catch { /* listener threw */ }
+            const isClean = code === 0 || signal === "SIGTERM";
+            if (isClean)
+                return;
+            // Surface stderr via "error" so the agent's onSessionError handler
+            // can include the real failure cause (e.g. "error: unexpected
+            // argument", codex auth missing) instead of a bare "exit code=1".
+            const stderr = stderrChunks.join("\n").trim().slice(0, 800);
+            const detail = stderr ? ` — stderr: ${stderr}` : "";
+            try {
+                cp.emit("error", new Error(`codex process exited (code=${code ?? "null"}, signal=${signal ?? "null"})${detail}`));
+            }
+            catch { /* listener threw */ }
+        };
+        proc.on("exit", (code, signal) => {
+            const isClean = code === 0 || signal === "SIGTERM";
+            const level = isClean ? "debug" : "warn";
+            log[level]({ sessionId: options.sessionId, code, signal }, "codex process exited");
+            if (!exitInfo)
+                exitInfo = { code, signal };
+            const cpRef = createdCp;
+            if (!cpRef)
+                return;
+            emitProcessExit(cpRef, code, signal);
+        });
+        await new Promise((resolve, reject) => {
+            const t = setTimeout(() => resolve(), 2000);
+            proc.on("error", (err) => {
+                clearTimeout(t);
+                reject(new Error(`Failed to spawn codex CLI: ${err.message}`));
+            });
+            proc.on("spawn", () => {
+                clearTimeout(t);
+                log.debug({ sessionId: options.sessionId, pid: proc.pid }, "codex spawn: process started");
+                resolve();
+            });
+        });
+        const cp = new CodexProcess(options.sessionId, cwd, proc);
+        cp.briefingFile = briefingFile;
+        cp.resumeId = options.resumeId;
+        // Expose process-exit signal to handshake so a timeout can report the
+        // real cause instead of a generic "timeout".
+        cp.getExitInfo = () => exitInfo;
+        cp.getStderr = () => stderrChunks.join("\n").slice(0, 800);
+        createdCp = cp;
+        // Late-fire safety: if the process exited BEFORE we got here (cp wasn't
+        // assigned yet so the proc.on("exit") path skipped the re-emit), surface
+        // it now via the same channel. setImmediate defers until session-manager
+        // has had a chance to subscribe (which happens synchronously after our
+        // returned cp lands).
+        if (exitInfo) {
+            const { code, signal } = exitInfo;
+            setImmediate(() => emitProcessExit(cp, code, signal));
+        }
+        this.wireRpc(cp);
+        return cp;
+    }
+    buildMcpServerConfig(options) {
+        // Resolve clawnet-mcp-server path. The package's "exports" map is a
+        // closed whitelist (only "." and "./package.json" are exported, plus
+        // "./server"). Resolving `@mclawnet/mcp-server/dist/server.js` directly
+        // throws ERR_PACKAGE_PATH_NOT_EXPORTED on modern Node, which is why
+        // packaged-release Windows hosts saw "not resolvable" while the dev
+        // monorepo path silently worked.
+        //
+        // Strategy: try the supported subpath export first ("./server"), then
+        // resolve via package.json + join, then fall back to the legacy direct
+        // path (still useful when "./server" isn't published yet but a hub
+        // installs an older mcp-server release), then dev-monorepo fallback.
+        let serverPath;
+        const require = createRequire(import.meta.url);
+        const tryResolve = (specifier) => {
+            try {
+                const p = require.resolve(specifier);
+                return p && existsSync(p) ? p : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        serverPath = tryResolve("@mclawnet/mcp-server/server");
+        if (!serverPath) {
+            try {
+                const pkgPath = require.resolve("@mclawnet/mcp-server/package.json");
+                const candidate = join(dirname(pkgPath), "dist", "server.js");
+                if (existsSync(candidate))
+                    serverPath = candidate;
+            }
+            catch {
+                /* not installed */
+            }
+        }
+        if (!serverPath) {
+            serverPath = tryResolve("@mclawnet/mcp-server/dist/server.js");
+        }
+        if (!serverPath) {
+            const devPath = join(import.meta.dirname ?? __dirname, "../../mcp-server/dist/server.js");
+            if (existsSync(devPath))
+                serverPath = devPath;
+        }
+        if (!serverPath) {
+            log.warn({ pkg: "@mclawnet/mcp-server" }, "codex: clawnet-mcp-server not resolvable, codex role will lack MCP tools");
+            return undefined;
+        }
+        log.debug({ serverPath }, "codex: resolved clawnet-mcp-server path");
+        const env = {};
+        if (options.workDir)
+            env.CLAWNET_WORK_DIR = options.workDir;
+        // mcp-server's server.ts:28 explicitly documents: CLAWNET_HOME is the
+        // user home (NO `.clawnet` suffix) — the server appends `.clawnet`
+        // itself via projectRoot(). Passing `~/.clawnet` here would yield
+        // `~/.clawnet/.clawnet/...` (double append) and break inbox/task layout.
+        const home = process.env.CLAWNET_HOME ?? homedir();
+        env.CLAWNET_HOME = home;
+        return { command: "node", args: [serverPath], env };
+    }
+    /**
+     * Bind a CodexProcess to a JSON-RPC duplex. Public so tests can inject a
+     * mocked stdin/stdout pair without spawning a real subprocess.
+     *
+     * Drives the v2 handshake automatically: `initialize` → `thread/start`.
+     * Once `thread/start` resolves, `cp.backendSessionId` is set and a
+     * `session_started` event fires so the agent's hub bridge can persist it.
+     */
+    attachRpc(cp, stdin, stdout) {
+        const rpc = new JsonRpcClient({
+            stdin: stdin,
+            stdout: stdout,
+            onRequest: (method, params) => this.handleServerRequest(cp, method, params),
+            onNotification: (method, params) => this.handleNotification(cp, method, params),
+            onMalformedLine: (line, err) => log.warn({ sessionId: cp.id, err: err.message, linePreview: line.slice(0, 200) }, "codex stdout: non-JSON line ignored"),
+        });
+        cp.rpc = rpc;
+        void this.handshake(cp);
+    }
+    async handshake(cp) {
+        if (!cp.rpc)
+            return;
+        const rpc = cp.rpc;
+        const resumeId = cp.resumeId;
+        log.info({ sessionId: cp.id, workDir: cp.workDir, resumeId }, "codex handshake: start");
+        // Wrap the whole handshake in a timeout so a dead codex process (e.g.
+        // killed by `--resume` CLI parse error, segfault, etc.) doesn't leave
+        // pendingInputs queued forever. Without this guard the swarm silently
+        // stalls — the user sees no error, just nothing happens.
+        //
+        // raceSettled is declared up here (before the IIFE) so the handshake
+        // success path can also check it. If timeout/death wins the race,
+        // handshakeAttempt may still complete later — without this guard it
+        // would mutate cp.backendSessionId, emit session_started, and flush
+        // pendingInputs against a process the caller already considers dead.
+        let raceSettled = false;
+        const handshakeAttempt = (async () => {
+            await rpc.request("initialize", { clientInfo: CLAWNET_CLIENT_INFO });
+            log.info({ sessionId: cp.id }, "codex handshake: initialize ok");
+            // Branch on resumeId — `codex app-server` rejects `--resume` CLI flag,
+            // so resume MUST happen at the JSON-RPC layer via `thread/resume`.
+            // `thread/start` on a resumed codex returns a NEW threadId (losing
+            // conversation continuity), which is why we have to branch here.
+            let threadId;
+            if (resumeId) {
+                const resumed = (await rpc.request("thread/resume", { threadId: resumeId }));
+                // Don't silently fall back to the input resumeId — if codex ever
+                // migrates the thread id (the protocol allows it) we'd persist a
+                // stale id and break the next restart. Treat absent thread id as a
+                // protocol error so the caller sees it and can re-spawn fresh.
+                threadId = resumed?.thread?.id ?? resumed?.threadId;
+            }
+            else {
+                // v2 `thread/start` returns { thread: { id, sessionId, ... }, ... }.
+                // The resumable identifier is `thread.id` — `sessionId` here is the
+                // tree-id shared by forked threads, not what `thread/resume` wants.
+                const started = (await rpc.request("thread/start", { cwd: cp.workDir }));
+                threadId = started?.thread?.id ?? started?.threadId;
+            }
+            if (!threadId) {
+                throw new Error(`codex handshake: ${resumeId ? "thread/resume" : "thread/start"} returned no threadId`);
+            }
+            // Race lost (timeout/death already won) → don't mutate state, don't
+            // emit session_started, don't flush queued inputs. The handshake
+            // error has already been reported via cp.emit("error") in the
+            // catch-block below.
+            if (raceSettled) {
+                log.warn({ sessionId: cp.id, threadId }, "codex handshake resolved AFTER race already lost — discarding result");
+                return;
+            }
+            cp.backendSessionId = threadId;
+            cp.handshakeComplete = true;
+            log.info({ sessionId: cp.id, threadId, queuedInputs: cp.pendingInputs.length }, "codex handshake: complete, flushing queued inputs");
+            cp.emit("session_started", { backendSessionId: threadId });
+            // Flush any inputs that arrived while the handshake was in flight.
+            const queued = cp.pendingInputs.splice(0);
+            for (const input of queued) {
+                this.dispatchTurn(cp, input);
+            }
+        })();
+        // Attach a no-op catch so handshakeAttempt rejecting AFTER losing the
+        // race (timeout or death already won) doesn't bubble as an unhandled
+        // promise rejection — node --unhandled-rejections=strict would crash.
+        // The real error already surfaced via cp.emit("error") above.
+        handshakeAttempt.catch(() => { });
+        let timeoutHandle;
+        let exitPollHandle;
+        // raceSettled is checked by the death-poll loop and the handshake
+        // success path. clearTimeout in finally{} alone is insufficient:
+        // poll() may be mid-execution when finally runs, scheduling the next
+        // setTimeout before clear; the success path could likewise resolve a
+        // late RPC after the race has been decided.
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+                reject(new Error(`codex handshake timeout after ${this.handshakeTimeoutMs}ms (process may have died)`));
+            }, this.handshakeTimeoutMs);
+        });
+        // Process-death detector: poll exitInfo every 100ms; if codex exits
+        // mid-handshake (e.g. CLI parse error), reject early with the real
+        // stderr instead of waiting handshakeTimeoutMs (15s default) for the
+        // generic timeout message.
+        const deathPromise = new Promise((_, reject) => {
+            const poll = () => {
+                if (raceSettled)
+                    return; // race already over — stop recursing
+                const exit = cp.getExitInfo();
+                if (exit) {
+                    const stderr = cp.getStderr();
+                    reject(new Error(`codex process died during handshake ` +
+                        `(code=${exit.code}, signal=${exit.signal}). ` +
+                        `stderr: ${stderr || "(empty)"}`));
+                    return;
+                }
+                exitPollHandle = setTimeout(poll, 100);
+            };
+            poll();
+        });
+        try {
+            await Promise.race([handshakeAttempt, timeoutPromise, deathPromise]);
+        }
+        catch (err) {
+            log.error({ err, sessionId: cp.id }, "codex v2 handshake failed");
+            cp.emit("error", err);
+        }
+        finally {
+            raceSettled = true;
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (exitPollHandle)
+                clearTimeout(exitPollHandle);
+        }
+    }
+    wireRpc(cp) {
+        const proc = cp.proc;
+        if (proc?.stdin && proc?.stdout) {
+            this.attachRpc(cp, proc.stdin, proc.stdout);
+        }
+    }
+    handleServerRequest(cp, method, params) {
+        const parsed = parseApprovalRequest(method, params);
+        if (!parsed) {
+            log.warn({ method }, "codex server-request: unrecognized method");
+            return Promise.resolve({ decision: "denied" });
+        }
+        const { req, wireFamily } = parsed;
+        return new Promise((resolve) => {
+            const resolverKey = cp.allocResolverKey();
+            cp.pendingApprovals.set(req.callId, resolverKey);
+            cp.approvalMethods.set(req.callId, wireFamily);
+            cp.approvalResolvers.set(resolverKey, (reply) => {
+                resolve(reply);
+            });
+            cp.emit("permission_request", req);
+        });
+    }
+    handleNotification(cp, method, params) {
+        // v2 thread lifecycle
+        if (method === "thread/started") {
+            // codex emits this as a *notification* during normal turns too; the
+            // primary session_started signal comes from thread/start's RPC result
+            // (see handshake()). Suppress the duplicate here so onSessionStarted
+            // listeners only fire once.
+            return;
+        }
+        if (method === "error") {
+            // codex `error` notifications carry the real failure cause (e.g.
+            // "Missing environment variable: COPILOT_API_KEY", upstream provider
+            // failure). Before this branch existed they degraded to {kind:"raw"} →
+            // normalize-backend-output dropped them silently → swarm coordinator
+            // never learned the role had failed → queen kept nudging a dead
+            // worker. Promote to cp.emit("error") so session-manager.onError →
+            // onSessionError fires.
+            const p = (params ?? {});
+            const message = p.error?.message ?? "codex emitted unspecified error";
+            log.warn({ sessionId: cp.id, params }, "codex error notification");
+            cp.emit("error", new Error(`codex: ${message}`));
+            // willRetry:false is codex saying "this turn is dead, no retry". Kill
+            // the process so proc.on("exit") fires → session-manager.onSessionExit
+            // → swarmCoordinator.handleRoleCrashed flips the role to crashed and
+            // wakes the queen. Leaving it alive would burn an idle process and
+            // continue queen nudge loops.
+            if (p.willRetry === false) {
+                void cp.kill().catch((err) => {
+                    log.warn({ err, sessionId: cp.id }, "kill after fatal codex error failed");
+                });
+            }
+            return;
+        }
+        if (method === "thread/status/changed") {
+            // Codex pairs systemError status with an `error` notification that
+            // carries willRetry. We forward the status as onError so the swarm
+            // sees the failure signal immediately, but defer the kill decision to
+            // the paired `error` frame (it has the willRetry bit). Other status
+            // transitions (active, idle, running, …) are benign lifecycle events
+            // — silently consume them, otherwise mapCodexFrame would degrade them
+            // to {kind:"raw"} and spam log.warn for every normal turn.
+            const p = (params ?? {});
+            if (p.status?.type === "systemError") {
+                log.warn({ sessionId: cp.id, params }, "codex thread systemError");
+                cp.emit("error", new Error("codex: thread entered systemError"));
+            }
+            return;
+        }
+        if (method === "turn/completed" || method === "thread/turnComplete" || method === "turn/complete") {
+            log.info({ sessionId: cp.id, method }, "codex turn complete");
+            // Token usage is delivered via the separate
+            // `thread/tokenUsageUpdated` notification — the `turn` payload here
+            // does NOT carry a `usage` field per the v2 schema.
+            cp.emit("turn_complete", {
+                backendSessionId: cp.backendSessionId,
+            });
+            // Intentionally do NOT clear cp.assistantTextSeen here. A trailing
+            // item/completed (channel reorder, codex internal buffering) against
+            // an empty accumulator would re-emit the full agentMessage text and
+            // bring back the original duplication bug. Unbounded growth from
+            // interrupted turns that never fire item/completed is bounded by
+            // ASSISTANT_TEXT_SEEN_MAX + FIFO eviction in the delta branch below.
+            return;
+        }
+        if (method === "turn/started") {
+            log.info({ sessionId: cp.id }, "codex turn started");
+            return;
+        }
+        // Dedupe assistant text: codex streams chunks via
+        // `item/agentMessage/delta` AND then re-sends the same full text via
+        // `item/completed{ item.type: "agentMessage" }`. Without dedupe the UI
+        // events-reducer (which appends every `text` event to the open message)
+        // renders the message twice.
+        //
+        // Strategy: accumulate per-itemId delta text; on completed-agentMessage
+        // emit only the suffix the deltas didn't already cover. delta is treated
+        // as an optional streaming hint; completed is the source of truth.
+        if (method === "item/agentMessage/delta") {
+            const p = (params ?? {});
+            if (typeof p.itemId === "string" && typeof p.delta === "string") {
+                const prev = cp.assistantTextSeen.get(p.itemId) ?? "";
+                // FIFO eviction guard: cap the map so an interrupted turn that
+                // never fires item/completed for an open agentMessage can't leak
+                // unbounded entries over a long-lived session. Map iteration is
+                // insertion order, so deleting the first key drops the oldest.
+                // Only check size when inserting a NEW key — updates of an
+                // existing key don't grow the map.
+                if (!cp.assistantTextSeen.has(p.itemId) &&
+                    cp.assistantTextSeen.size >= ASSISTANT_TEXT_SEEN_MAX) {
+                    const oldest = cp.assistantTextSeen.keys().next().value;
+                    if (oldest !== undefined)
+                        cp.assistantTextSeen.delete(oldest);
+                }
+                cp.assistantTextSeen.set(p.itemId, prev + p.delta);
+            }
+            else {
+                // Telemetry: surface protocol drift instead of silently degrading
+                // to "no dedupe → full text duplicate" on the matching completed.
+                log.warn({ sessionId: cp.id, params: p }, "codex agentMessage delta: missing itemId/delta — dedupe will not apply to this item");
+            }
+            // Fall through to mapper, which emits {kind:"assistant_text", text:delta}.
+        }
+        else if (method === "item/completed") {
+            const p = (params ?? {});
+            const item = p.item;
+            if (item?.type === "agentMessage") {
+                // Always short-circuit for agentMessage — never fall through to
+                // mapper. Mapper has no per-itemId delta history and would re-emit
+                // the full text against an empty accumulator, reactivating the
+                // duplication bug under protocol drift (e.g. codex changes itemId
+                // type).
+                if (typeof item.id !== "string" || typeof item.text !== "string") {
+                    log.warn({ sessionId: cp.id, item }, "codex agentMessage completed: malformed item.id/text — dropping to avoid duplicate emission");
+                    return;
+                }
+                const seen = cp.assistantTextSeen.get(item.id) ?? "";
+                cp.assistantTextSeen.delete(item.id);
+                const full = item.text;
+                let suffix;
+                if (full === seen) {
+                    // Deltas already covered the full text — drop the redundant frame.
+                    return;
+                }
+                else if (seen.length > 0 && full.startsWith(seen)) {
+                    // Deltas covered a prefix; emit only what's left.
+                    suffix = full.slice(seen.length);
+                }
+                else {
+                    // No deltas seen (resume / cached / short-circuit) OR the final
+                    // text diverges from the streamed prefix (codex revised the
+                    // response). In both cases the full completed text is the source
+                    // of truth; emitting it preserves correctness even if the UI ends
+                    // up showing both the partial draft and the final answer.
+                    suffix = full;
+                    if (seen.length > 0) {
+                        log.warn({ sessionId: cp.id, itemId: item.id, seenLen: seen.length, fullLen: full.length }, "codex agentMessage: completed text diverges from accumulated deltas — emitting full");
+                    }
+                }
+                if (suffix.length === 0)
+                    return;
+                const out = { kind: "assistant_text", text: suffix };
+                this.logBackendOutput(cp.id, method, out);
+                cp.emit("output", out);
+                return;
+            }
+            // Non-agentMessage item/completed (commandExecution, fileChange,
+            // mcpToolCall, …) — fall through to mapper.
+        }
+        const out = mapCodexFrame({ method, params });
+        this.logBackendOutput(cp.id, method, out);
+        cp.emit("output", out);
+    }
+    /**
+     * Selective notification logging. The previous catch-all `log.debug("codex
+     * notification")` fired for every streaming `item/agentMessage/delta` chunk
+     * (many per turn), drowning the actually useful events. Instead, log only
+     * structural events at INFO and surface unrecognised methods as WARN so the
+     * `{kind:"raw"}` degradation isn't silent.
+     */
+    logBackendOutput(sessionId, method, out) {
+        // Streaming text deltas — too high-frequency to log per-chunk.
+        if (method === "item/agentMessage/delta")
+            return;
+        // Other token-usage / progress notifications without a structural meaning.
+        if (method === "thread/tokenUsageUpdated")
+            return;
+        switch (out.kind) {
+            case "tool_use":
+                log.info({ sessionId, callId: out.callId, tool: out.toolName, input: preview(out.input, 120) }, "codex tool_use");
+                return;
+            case "tool_result":
+                log.info({ sessionId, callId: out.callId, isError: out.isError, output: preview(out.output, 120) }, "codex tool_result");
+                return;
+            case "assistant_text":
+                log.debug({ sessionId, len: out.text.length, text: preview(out.text, 120) }, "codex assistant_text");
+                return;
+            case "raw":
+                log.warn({ sessionId, method, payload: preview(out.payload, 200) }, "codex unhandled frame");
+                return;
+        }
+    }
+    async stop(process) {
+        await process.kill();
+    }
+    send(process, input) {
+        if (!(process instanceof CodexProcess)) {
+            log.warn({ sessionId: process?.id, len: input.length }, "codex send: not a CodexProcess — input dropped");
+            return;
+        }
+        if (!process.rpc) {
+            log.warn({ sessionId: process.id, len: input.length }, "codex send: no rpc — input dropped");
+            return;
+        }
+        if (!process.backendSessionId) {
+            // Handshake still in flight: queue the input and let `handshake()`
+            // flush it once `thread/start` resolves. This avoids silent drops when
+            // a hub author moves from claude-adapter (no handshake) to codex.
+            process.pendingInputs.push(input);
+            log.info({ sessionId: process.id, queueDepth: process.pendingInputs.length, len: input.length }, "codex send: handshake pending, queued");
+            return;
+        }
+        log.info({ sessionId: process.id, threadId: process.backendSessionId, len: input.length }, "codex send: dispatching turn/start");
+        this.dispatchTurn(process, input);
+    }
+    dispatchTurn(process, input) {
+        if (!process.rpc || !process.backendSessionId)
+            return;
+        // codex v2: turn/start is a *request* (server returns a result when the
+        // turn is queued). We fire-and-forget here because the agent loop reacts
+        // to async `turn/completed` / `item/...` notifications, not to the
+        // request's result envelope.
+        void process.rpc
+            .request("turn/start", {
+            threadId: process.backendSessionId,
+            input: [{ type: "text", text: input }],
+        })
+            .then(() => {
+            log.info({ sessionId: process.id, threadId: process.backendSessionId }, "codex turn/start: accepted by server");
+        })
+            .catch((err) => {
+            log.warn({ err, sessionId: process.id }, "turn/start failed");
+            process.emit("error", err);
+        });
+    }
+    onOutput(process, handler) {
+        if (process instanceof CodexProcess)
+            process.on("output", handler);
+    }
+    onPermissionRequest(process, handler) {
+        if (process instanceof CodexProcess)
+            process.on("permission_request", handler);
+    }
+    async respondToPermission(process, decision) {
+        if (!(process instanceof CodexProcess))
+            return;
+        const key = process.pendingApprovals.get(decision.callId);
+        if (key === undefined) {
+            log.warn({ callId: decision.callId }, "respondToPermission: no pending approval");
+            return;
+        }
+        const family = process.approvalMethods.get(decision.callId) ?? "legacy";
+        const resolver = process.approvalResolvers.get(key);
+        process.pendingApprovals.delete(decision.callId);
+        process.approvalMethods.delete(decision.callId);
+        process.approvalResolvers.delete(key);
+        const reply = buildApprovalReply(family, decision.decision);
+        resolver?.(reply);
+    }
+    onTurnComplete(process, handler) {
+        if (process instanceof CodexProcess)
+            process.on("turn_complete", handler);
+    }
+    onSessionStarted(process, handler) {
+        if (process instanceof CodexProcess)
+            process.on("session_started", handler);
+    }
+    onError(process, handler) {
+        if (process instanceof CodexProcess)
+            process.on("error", handler);
+    }
+    onExit(process, handler) {
+        if (process instanceof CodexProcess)
+            process.on("exit", handler);
+    }
+    async getManifest() {
+        const det = await this.detect();
+        return {
+            kind: "codex",
+            installed: det.installed,
+            binaryPath: det.binaryPath,
+            version: det.version,
+            unavailableReason: det.reason,
+            models: det.installed ? CODEX_MODELS : [],
+            modes: det.installed ? CODEX_MODES : [],
+        };
+    }
+}
+//# sourceMappingURL=codex-adapter.js.map