nexting-cc-bridge 0.8.3

package/dist/engine/codex-adapter.js

@@ -0,0 +1,593 @@
+// Verified against codex 0.138.0 app-server protocol (generate-json-schema).
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import { expandCodexPrompt } from "../codex-prompts.js";
+/** Classify a parsed JSON-RPC "lite" object (no jsonrpc field). */
+export function classifyRpc(o) {
+    if (!o || typeof o !== "object")
+        return "unknown";
+    const r = o;
+    if ("id" in r && ("result" in r || "error" in r))
+        return "response";
+    if ("id" in r && "method" in r)
+        return "server_request";
+    if ("method" in r && !("id" in r))
+        return "notification";
+    return "unknown";
+}
+// ---------------------------------------------------------------------------
+// Binary resolver
+// ---------------------------------------------------------------------------
+/** Resolve the `codex` binary by absolute path (launchd PATH is minimal). */
+export function resolveCodexBin() {
+    const home = os.homedir();
+    const candidates = [
+        process.env.NEXTING_CODEX_BIN,
+        path.join(home, ".npm-global/bin/codex"),
+        path.join(home, ".local/bin/codex"),
+        "/opt/homebrew/bin/codex",
+        "/usr/local/bin/codex",
+    ].filter((p) => !!p);
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c))
+                return c;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    return "codex";
+}
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+/** TUI substrings the Codex CLI prints while a turn is running (best-effort —
+ * casing has varied across codex versions; the probe matches case-insensitively,
+ * so these collapse, but both observed spellings are kept for documentation). */
+export const CODEX_RUNNING_MARKERS = ["esc to interrupt", "Esc to interrupt"];
+/** Per-session stateful adapter for `codex app-server` JSON-RPC over stdio. */
+export function createCodexAdapter() {
+    let threadId = null;
+    let resumeId;
+    let nextId = 0;
+    let nextQueueId = 0;
+    let eventSink = null;
+    // Fix 1: guard against re-firing handshake on any future response with userAgent
+    let handshakeDone = false;
+    // Fix 2: buffer user turns sent before threadId is known
+    let io = null;
+    const pendingTurns = [];
+    // True once a turn/start has been sent and until Codex completes that turn.
+    // This includes the short window before the app-server emits turn/started.
+    let turnBusy = false;
+    let activeTurnId = null;
+    const queuedFollowUps = [];
+    // Codex-owned "current activity" latch that drives the phone's state bar
+    // (`activity_status` → iOS `CodexSessionModel.activityState`). We emit a frame
+    // ONLY when the phase transitions, so a burst of same-phase events (e.g. many
+    // text deltas) never spams identical frames. iOS falls back to transcript-tail
+    // inference only when no activity_status frame has arrived.
+    let activityPhase = null;
+    function id() {
+        return nextId++;
+    }
+    function line(obj) {
+        return JSON.stringify(obj) + "\n";
+    }
+    function queueItem(text) {
+        nextQueueId += 1;
+        return {
+            id: `q${nextQueueId}`,
+            text,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    function emitQueueStatus() {
+        eventSink?.({
+            type: "event",
+            kind: "queue_status",
+            payload: {
+                items: queuedFollowUps.map((item, index) => ({
+                    id: item.id,
+                    text: item.text,
+                    createdAt: item.createdAt,
+                    position: index,
+                })),
+                activeTurnId,
+                canSteer: activeTurnId != null,
+            },
+        });
+    }
+    // Fix 2: shared helper so encodeUserTurn and the flush path produce identical lines
+    function buildTurnLine(content) {
+        return line({
+            id: id(),
+            method: "turn/start",
+            params: {
+                threadId,
+                input: [{ type: "text", text: content }],
+            },
+        });
+    }
+    function buildSteerLine(content) {
+        return line({
+            id: id(),
+            method: "turn/steer",
+            params: {
+                threadId,
+                expectedTurnId: activeTurnId,
+                input: [{ type: "text", text: content }],
+            },
+        });
+    }
+    function buildBusyTurnLine(content) {
+        turnBusy = true;
+        return buildTurnLine(content);
+    }
+    function writeBusyTurn(content) {
+        if (!io)
+            return;
+        io.write(buildBusyTurnLine(content));
+    }
+    function drainOneQueuedFollowUp() {
+        if (!io || threadId === null || queuedFollowUps.length === 0)
+            return false;
+        const next = queuedFollowUps.shift();
+        if (next == null)
+            return false;
+        emitQueueStatus();
+        writeBusyTurn(next.text);
+        return true;
+    }
+    function itemText(item) {
+        const content = item.content;
+        if (typeof content === "string")
+            return content;
+        if (!Array.isArray(content))
+            return "";
+        return content
+            .map((block) => {
+            if (typeof block === "string")
+                return block;
+            if (!block || typeof block !== "object")
+                return "";
+            const b = block;
+            return typeof b.text === "string" ? b.text : "";
+        })
+            .join("");
+    }
+    function isoFromMs(value) {
+        return typeof value === "number" && Number.isFinite(value)
+            ? new Date(value).toISOString()
+            : undefined;
+    }
+    function fileChangePayload(item) {
+        return {
+            id: item.id,
+            changes: Array.isArray(item.changes) ? item.changes : [],
+            status: item.status,
+        };
+    }
+    /** Emit an `activity_status` frame iff the phase changed since the last one.
+     * `extra` carries phase-specific context (search `summary`, edit `count`). */
+    function activityFrame(phase, extra = {}) {
+        if (activityPhase === phase)
+            return [];
+        activityPhase = phase;
+        return [
+            {
+                type: "event",
+                kind: "activity_status",
+                payload: { phase, active: phase !== "idle", ...extra },
+            },
+        ];
+    }
+    /** Map a commandExecution's actions to an activity phase + summary. Codex's
+     * exploring commands (search/read/listFiles) drive the "searching" phase; a
+     * search action also surfaces its query as the bar summary. */
+    function commandActivity(item) {
+        const actions = Array.isArray(item.commandActions)
+            ? item.commandActions
+            : [];
+        const search = actions.find((a) => a && a.type === "search");
+        const exploring = search != null ||
+            actions.some((a) => a && (a.type === "read" || a.type === "listFiles"));
+        if (!exploring)
+            return activityFrame("working");
+        const summary = typeof search?.query === "string" ? search.query : undefined;
+        return activityFrame("searching", summary ? { summary } : {});
+    }
+    return {
+        runningMarkers: CODEX_RUNNING_MARKERS,
+        setEventSink(sink) {
+            eventSink = sink;
+        },
+        editQueuedTurn(itemId, text) {
+            const trimmed = text.trim();
+            if (!trimmed)
+                return false;
+            const item = queuedFollowUps.find((q) => q.id === itemId);
+            if (!item)
+                return false;
+            item.text = trimmed;
+            emitQueueStatus();
+            return true;
+        },
+        deleteQueuedTurn(itemId) {
+            const index = queuedFollowUps.findIndex((q) => q.id === itemId);
+            if (index < 0)
+                return false;
+            queuedFollowUps.splice(index, 1);
+            emitQueueStatus();
+            return true;
+        },
+        closeQueue() {
+            if (queuedFollowUps.length === 0)
+                return false;
+            queuedFollowUps.length = 0;
+            emitQueueStatus();
+            return true;
+        },
+        steerQueuedTurn(itemId) {
+            if (threadId === null || activeTurnId === null) {
+                emitQueueStatus();
+                return "";
+            }
+            const index = queuedFollowUps.findIndex((q) => q.id === itemId);
+            if (index < 0) {
+                emitQueueStatus();
+                return "";
+            }
+            const [item] = queuedFollowUps.splice(index, 1);
+            emitQueueStatus();
+            return buildSteerLine(item.text);
+        },
+        command(_resumeSessionId, _ctx) {
+            // codex app-server is always the same command; resuming is done via
+            // thread/resume inside the JSON-RPC handshake, not via CLI flags. The
+            // device-tool MCP server is configured out-of-band in ~/.codex/config.toml
+            // (written by mcp-config.ts before spawn), so mcpConfigPath is unused here.
+            return { bin: resolveCodexBin(), args: ["app-server"] };
+        },
+        start(ioArg, resumeSessionId) {
+            io = ioArg;
+            resumeId = resumeSessionId;
+            // If resuming, set threadId immediately so encodeUserTurn works even
+            // before thread/started arrives.
+            if (resumeSessionId) {
+                threadId = resumeSessionId;
+            }
+            // Send the initialize request — the handshake continues from translate()
+            // once the server responds, keeping ordering guarantees.
+            io.write(line({
+                id: id(),
+                method: "initialize",
+                params: {
+                    clientInfo: {
+                        name: "pinclaw-codex-bridge",
+                        title: "Nexting",
+                        version: "0.1.0",
+                    },
+                },
+            }));
+        },
+        translate(parsed, ioArg) {
+            const kind = classifyRpc(parsed);
+            const o = parsed;
+            // ---- terminal engine errors (surface, never drop) ----
+            // Codex reports request failures in two shapes that would otherwise be
+            // swallowed: an error RESPONSE ({id, error}) AND — the one that bit us — a
+            // TOP-LEVEL id-less {error} frame (e.g. "no rollout found for thread id …"
+            // when resuming a thread whose rollout was never written). classifyRpc tags
+            // the latter "unknown", so without this it is dropped at the function tail
+            // → the phone spins "working" forever with no feedback. Surface both as a
+            // result_error so the UI clears and shows a real message. (Retryable stream
+            // hiccups use the {method:"error",params.willRetry} NOTIFICATION path below;
+            // those carry no top-level `error`, so kind==="notification" is excluded.)
+            if (kind !== "notification") {
+                const errObj = o.error;
+                if (errObj && typeof errObj === "object") {
+                    const msg = typeof errObj.message === "string"
+                        ? errObj.message
+                        : "Codex 引擎返回错误";
+                    const detail = typeof errObj.additionalDetails === "string"
+                        ? errObj.additionalDetails
+                        : undefined;
+                    return [
+                        {
+                            type: "event",
+                            kind: "result_error",
+                            payload: { errors: [detail ? `${msg}: ${detail}` : msg] },
+                        },
+                    ];
+                }
+            }
+            // ---- initialize RESPONSE ----
+            if (kind === "response") {
+                const result = o.result;
+                // Fix 1: only fire the handshake continuation once, even if a future
+                // response happens to carry a userAgent field.
+                if (result && typeof result.userAgent === "string" && !handshakeDone) {
+                    handshakeDone = true;
+                    // Handshake step 3: send "initialized" notification
+                    ioArg.write(line({ method: "initialized" }));
+                    // Handshake step 4: start or resume the thread
+                    if (resumeId) {
+                        ioArg.write(line({
+                            id: id(),
+                            method: "thread/resume",
+                            params: {
+                                threadId: resumeId,
+                                approvalPolicy: "never",
+                            },
+                        }));
+                    }
+                    else {
+                        ioArg.write(line({
+                            id: id(),
+                            method: "thread/start",
+                            params: {
+                                approvalPolicy: "never",
+                            },
+                        }));
+                    }
+                    // Fix 3: clear resumeId so a defensive second start() can't reuse stale state
+                    resumeId = undefined;
+                }
+                // All other responses (e.g. turn/start ACK) are ignored.
+                return [];
+            }
+            // ---- notifications ----
+            if (kind === "notification") {
+                const method = o.method;
+                const params = (o.params ?? {});
+                switch (method) {
+                    case "thread/started": {
+                        const thread = params.thread;
+                        threadId = thread.id;
+                        // Fix 2: flush the first turn that was enqueued before threadId
+                        // arrived. Any extra phone sends become Codex follow-ups, not
+                        // concurrent turn/start requests.
+                        const firstPending = pendingTurns.shift();
+                        if (firstPending != null)
+                            writeBusyTurn(firstPending);
+                        queuedFollowUps.push(...pendingTurns.map(queueItem));
+                        pendingTurns.length = 0;
+                        if (queuedFollowUps.length > 0)
+                            emitQueueStatus();
+                        return [
+                            {
+                                type: "event",
+                                kind: "system_init",
+                                payload: {
+                                    session_id: thread.id,
+                                    cwd: thread.cwd,
+                                },
+                            },
+                        ];
+                    }
+                    case "turn/started": {
+                        turnBusy = true;
+                        const turn = params.turn;
+                        activeTurnId = typeof turn?.id === "string" ? turn.id : null;
+                        emitQueueStatus();
+                        return [
+                            ...activityFrame("working"),
+                            { type: "event", kind: "status", payload: { state: "running" } },
+                        ];
+                    }
+                    case "turn/completed": {
+                        activeTurnId = null;
+                        const drained = drainOneQueuedFollowUp();
+                        if (!drained)
+                            turnBusy = false;
+                        emitQueueStatus();
+                        // status idle first (legacy), then the activity bar clears.
+                        return [
+                            { type: "event", kind: "status", payload: { state: "idle" } },
+                            ...activityFrame("idle"),
+                        ];
+                    }
+                    case "item/agentMessage/delta": {
+                        const delta = params.delta;
+                        return [
+                            ...activityFrame("writing"),
+                            {
+                                type: "event",
+                                kind: "stream_text_delta",
+                                payload: { index: 0, text: delta },
+                            },
+                        ];
+                    }
+                    case "item/reasoning/textDelta":
+                    case "item/reasoning/summaryTextDelta": {
+                        const delta = params.delta;
+                        return [
+                            ...activityFrame("thinking"),
+                            {
+                                type: "event",
+                                kind: "stream_thinking_delta",
+                                payload: { index: 0, text: delta },
+                            },
+                        ];
+                    }
+                    case "item/completed": {
+                        const item = params.item;
+                        if (item.type === "userMessage") {
+                            const text = itemText(item);
+                            if (!text)
+                                return [];
+                            return [
+                                {
+                                    type: "event",
+                                    kind: "user",
+                                    payload: {
+                                        uuid: item.id,
+                                        text,
+                                        timestamp: isoFromMs(params.completedAtMs),
+                                    },
+                                },
+                            ];
+                        }
+                        if (item.type === "agentMessage") {
+                            return [
+                                {
+                                    type: "event",
+                                    kind: "assistant",
+                                    payload: {
+                                        uuid: item.id,
+                                        index: 0,
+                                        text: item.text,
+                                    },
+                                },
+                            ];
+                        }
+                        if (item.type === "commandExecution") {
+                            const exitCode = item.exitCode;
+                            return [
+                                {
+                                    type: "event",
+                                    kind: "tool_result",
+                                    payload: {
+                                        tool_use_id: item.id,
+                                        content: item.aggregatedOutput,
+                                        is_error: exitCode !== 0 && exitCode != null,
+                                    },
+                                },
+                            ];
+                        }
+                        if (item.type === "fileChange") {
+                            return [
+                                {
+                                    type: "event",
+                                    kind: "file_change",
+                                    payload: fileChangePayload(item),
+                                },
+                            ];
+                        }
+                        return [];
+                    }
+                    case "item/started": {
+                        const item = params.item;
+                        if (item.type === "commandExecution") {
+                            const commandActions = Array.isArray(item.commandActions)
+                                ? item.commandActions
+                                : [];
+                            return [
+                                ...commandActivity(item),
+                                {
+                                    type: "event",
+                                    kind: "tool_use",
+                                    payload: {
+                                        id: item.id,
+                                        name: "shell",
+                                        input: { command: item.command },
+                                        commandActions,
+                                        commandSource: item.source,
+                                    },
+                                },
+                            ];
+                        }
+                        if (item.type === "fileChange") {
+                            const changes = Array.isArray(item.changes) ? item.changes : [];
+                            return [
+                                ...activityFrame("editing", { count: changes.length }),
+                                {
+                                    type: "event",
+                                    kind: "file_change",
+                                    payload: fileChangePayload(item),
+                                },
+                            ];
+                        }
+                        return [];
+                    }
+                    case "item/fileChange/patchUpdated": {
+                        const changes = Array.isArray(params.changes) ? params.changes : [];
+                        return [
+                            ...activityFrame("editing", { count: changes.length }),
+                            {
+                                type: "event",
+                                kind: "file_change",
+                                payload: {
+                                    id: params.itemId,
+                                    changes,
+                                    status: "inProgress",
+                                },
+                            },
+                        ];
+                    }
+                    case "error": {
+                        const willRetry = params.willRetry;
+                        if (willRetry)
+                            return []; // engine will retry; don't disrupt the phone
+                        const err = params.error;
+                        const msg = err.message;
+                        const detail = err.additionalDetails;
+                        const full = detail ? `${msg}: ${detail}` : msg;
+                        return [
+                            {
+                                type: "event",
+                                kind: "result_error",
+                                payload: { errors: [full] },
+                            },
+                        ];
+                    }
+                    // MCP server startup status: not surfaced to the phone, but logged to
+                    // stderr so a failed pinclaw-device proxy launch is debuggable in the
+                    // codex-bridge.err.log (stdout is the JSON-RPC channel — never log there).
+                    case "mcpServer/startupStatus/updated": {
+                        try {
+                            process.stderr.write(`[codex-adapter] mcpServer/startupStatus: ${JSON.stringify(params)}\n`);
+                        }
+                        catch {
+                            /* logging must never break translate */
+                        }
+                        return [];
+                    }
+                    // Ignored notifications
+                    case "remoteControl/status/changed":
+                    case "thread/status/changed":
+                    case "warning":
+                    default:
+                        return [];
+                }
+            }
+            // server_request and unknown: ignore
+            return [];
+        },
+        encodeUserTurn(content) {
+            // Custom prompts ("/name args") are a TUI feature the app-server does
+            // NOT expand — substitute the prompt body here so phone sends behave
+            // like the Codex terminal. Non-matching text passes through untouched.
+            content = expandCodexPrompt(content);
+            // Fix 2: if threadId is not yet known, buffer the turn and return an
+            // empty string (a harmless noop write to stdin); it will be flushed
+            // in the thread/started handler.
+            if (threadId === null) {
+                pendingTurns.push(content);
+                return "";
+            }
+            // Codex App does not accept a second same-thread turn/start while a turn
+            // is active. Match the desktop app's end-of-turn follow-up queue instead
+            // of leaking Claude Code's immediate-send semantics into Codex.
+            if (turnBusy) {
+                queuedFollowUps.push(queueItem(content));
+                emitQueueStatus();
+                return "";
+            }
+            return buildBusyTurnLine(content);
+        },
+        encodeAnswer(_controlRequestId, _updatedInput) {
+            // v1 runs app-server with approvalPolicy:"never", so approval server_requests never arrive.
+            // If approvalPolicy ever changes, implement real tool-approval encoding here instead of this noop.
+            return line({ method: "noop" });
+        },
+        encodeDeny(_controlRequestId, _message) {
+            // v1 runs app-server with approvalPolicy:"never", so approval server_requests never arrive.
+            // If approvalPolicy ever changes, implement real tool-approval encoding here instead of this noop.
+            return line({ method: "noop" });
+        },
+    };
+}