@santori/station 0.0.0-stage → 0.1.2

package/dist/codex.js

@@ -0,0 +1,438 @@
+// Codex threads on this computer, and the two ways into one.
+//
+// Codex gives every shell command it runs `CODEX_THREAD_ID`, and a Codex
+// process holds `<codex home>/thread-writer-locks/<thread>.lock` open while
+// the thread is live. The nearest `codex` above the caller holding that
+// lock is the thread's host:
+//
+// - Terminal Codex: `codex queue --thread <id> --message=<text>` puts the
+//   message in Codex's own queue, first in, first out. The terminal runs
+//   it as a turn when its current one allows.
+// - The Codex app (`codex app-server` under ChatGPT.app): its window
+//   router at `<codex home>/ipc/ipc.sock` asks the window that has the
+//   thread open to start a turn. Only while the thread is idle, so a
+//   message waits for the turn under way to end, as it does in Claude Code.
+//
+// Agent Relay (crates/relay-node/src/relay/codex/) reads Codex the same
+// way; queue.rs, ipc.rs and rollout.rs are what this follows. It also
+// installs a Codex hook to deliver inside a running turn; Station leaves
+// the person's Codex settings alone.
+import { execFile, execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { systemPs } from "./claude.js";
+export const systemHolders = (path) => {
+    try {
+        return execFileSync("lsof", ["-t", path], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env: { ...process.env, PATH: `${process.env.PATH ?? ""}:/usr/sbin:/usr/bin` },
+        })
+            .split("\n")
+            .map((line) => Number(line.trim()))
+            .filter((pid) => Number.isInteger(pid) && pid > 0);
+    }
+    catch {
+        return []; // lsof exits 1 when nobody holds it
+    }
+};
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function codexHome(env = process.env) {
+    return env.CODEX_HOME || join(homedir(), ".codex");
+}
+export const lockPath = (home, thread) => join(home, "thread-writer-locks", `${thread}.lock`);
+/** Which kind of Codex a process is, from its arguments. The Codex app runs
+ * its app-server over stdio. Terminal Codex starts a shared one that listens
+ * on a socket (`app-server --listen unix:// --managed-daemon`) and holds the
+ * thread there; the terminal still takes `codex queue`. */
+export function hostOf(executable, args) {
+    // The arguments also carry a terminal Codex's first prompt, so only the
+    // subcommand counts: the first word that is not a flag or a flag's value.
+    const rest = args.startsWith(executable) ? args.slice(executable.length) : args.replace(/^\S+/, "");
+    const words = rest.trim().split(/\s+/).filter(Boolean);
+    let subcommand;
+    for (let i = 0; i < words.length; i++) {
+        if (words[i].startsWith("-")) {
+            if (VALUE_FLAGS.has(words[i]))
+                i++;
+            continue;
+        }
+        subcommand = words[i];
+        break;
+    }
+    if (subcommand === "app-server")
+        return words.some((word) => word.startsWith("--listen")) ? "terminal" : "app";
+    if (subcommand === "exec" || subcommand === "e")
+        return "exec";
+    return "terminal";
+}
+/** Codex's flags that take a value as the next word. */
+const VALUE_FLAGS = new Set([
+    "-c",
+    "--config",
+    "-s",
+    "--sandbox",
+    "-a",
+    "--ask-for-approval",
+    "-m",
+    "--model",
+    "-p",
+    "--profile",
+    "-C",
+    "--cd",
+    "-i",
+    "--image",
+    "--enable",
+    "--disable",
+    "--remote",
+    "--remote-auth-token-env",
+    "--add-dir",
+    "--local-provider",
+]);
+function describe(home, thread, pid, ps, holders) {
+    const executable = ps(pid, "comm");
+    if (!executable || basename(executable) !== "codex")
+        return null;
+    if (!holders(lockPath(home, thread)).includes(pid))
+        return null;
+    return { thread, pid, procStart: ps(pid, "lstart"), executable, host: hostOf(executable, ps(pid, "args") ?? "") };
+}
+/** The Codex thread this process runs inside: `CODEX_THREAD_ID`, vouched for
+ * by the nearest `codex` above it holding the thread's lock. */
+export function callingThread(home, env = process.env, from = process.ppid, ps = systemPs, holders = systemHolders) {
+    const thread = env.CODEX_THREAD_ID?.trim().toLowerCase();
+    if (!thread || !UUID.test(thread))
+        return null;
+    let pid = from;
+    for (let hops = 0; hops < 64 && pid > 1; hops++) {
+        const executable = ps(pid, "comm");
+        if (executable && basename(executable) === "codex")
+            return describe(home, thread, pid, ps, holders);
+        const parent = Number(ps(pid, "ppid"));
+        if (!Number.isInteger(parent) || parent <= 1 || parent === pid)
+            return null;
+        pid = parent;
+    }
+    return null;
+}
+/** Why `callingThread` found nothing, step by step, for a process Codex
+ * started (it has `CODEX_THREAD_ID`); null when it is not one. */
+export function whyNoThread(home, env = process.env, from = process.ppid, ps = systemPs, holders = systemHolders) {
+    const raw = env.CODEX_THREAD_ID;
+    if (raw === undefined)
+        return null;
+    const thread = raw.trim().toLowerCase();
+    if (!UUID.test(thread))
+        return `CODEX_THREAD_ID is "${raw.slice(0, 60)}", not a thread id.`;
+    const chain = [];
+    let pid = from;
+    for (let hops = 0; hops < 64 && pid > 1; hops++) {
+        const executable = ps(pid, "comm");
+        if (!executable) {
+            chain.push(`${pid} (cannot see it)`);
+            return `Station cannot look at the processes above it (${chain.join(" -> ")}). Codex's sandbox may hide them: run the station command again with full access.`;
+        }
+        chain.push(`${pid} ${basename(executable)}`);
+        if (basename(executable) === "codex") {
+            const holding = holders(lockPath(home, thread));
+            if (!holding.length && !existsSync(lockPath(home, thread)))
+                return `No Codex has thread ${thread} open (no ${lockPath(home, thread)}).`;
+            if (!holding.length)
+                return `Station cannot see who holds ${lockPath(home, thread)}. Codex's sandbox may hide it: run the station command again with full access.`;
+            return `The Codex above this command (${chain.join(" -> ")}) does not hold thread ${thread}; pid ${holding.join(", ")} does.`;
+        }
+        const parent = Number(ps(pid, "ppid"));
+        if (!Number.isInteger(parent) || parent <= 1 || parent === pid)
+            break;
+        pid = parent;
+    }
+    return `No codex process above this command (${chain.join(" -> ")}).`;
+}
+/** The Codex that holds `thread` now; a thread resumed elsewhere is found
+ * again. Null when no Codex has it open. */
+export function liveThread(home, thread, ps = systemPs, holders = systemHolders) {
+    for (const pid of holders(lockPath(home, thread))) {
+        const session = describe(home, thread, pid, ps, () => [pid]);
+        if (session)
+            return session;
+    }
+    return null;
+}
+/** The thread's rollout: `sessions/<yyyy>/<mm>/<dd>/rollout-…-<thread>.jsonl`,
+ * newest day first. */
+export function rolloutPath(home, thread) {
+    const root = join(home, "sessions");
+    const down = (dir) => (existsSync(dir) ? readdirSync(dir).sort().reverse() : []);
+    for (const year of down(root))
+        for (const month of down(join(root, year)))
+            for (const day of down(join(root, year, month))) {
+                const dir = join(root, year, month, day);
+                const name = down(dir).find((file) => file.startsWith("rollout-") && file.endsWith(`-${thread}.jsonl`));
+                if (name)
+                    return join(dir, name);
+            }
+    return null;
+}
+const TAIL_BYTES = 4 * 1024 * 1024;
+/** Whether the rollout's last turn is still open: a `task_started` with no
+ * `task_complete` or `turn_aborted` after it. A turn ends with one of those
+ * near the end of the file, so a tail with neither is a turn still going. */
+export function turnRunning(lines) {
+    let open = null;
+    for (const line of lines) {
+        if (!line.includes('"event_msg"'))
+            continue;
+        let type;
+        try {
+            type = JSON.parse(line).payload?.type;
+        }
+        catch {
+            continue;
+        }
+        if (type === "task_started")
+            open = true;
+        else if (type === "task_complete" || type === "turn_aborted")
+            open = false;
+    }
+    return open ?? true;
+}
+function tailLines(path) {
+    const size = statSync(path).size;
+    const start = Math.max(0, size - TAIL_BYTES);
+    const buffer = Buffer.alloc(size - start);
+    const fd = openSync(path, "r");
+    try {
+        readSync(fd, buffer, 0, buffer.length, start);
+    }
+    finally {
+        closeSync(fd);
+    }
+    const lines = buffer.toString("utf8").split("\n");
+    return start > 0 ? lines.slice(1) : lines;
+}
+/** Whether the thread is between turns. Unknown counts as busy. */
+export function threadIdle(home, thread) {
+    const path = rolloutPath(home, thread);
+    if (!path)
+        return false;
+    try {
+        return !turnRunning(tailLines(path));
+    }
+    catch {
+        return false;
+    }
+}
+/** Codex takes text, tabs and newlines; any other control character could
+ * edit or submit what it is part of. */
+export const MAX_TEXT_BYTES = 14_336;
+const CUT_NOTE = "\n\n[cut short: the rest is in the room]";
+export function cleanText(text) {
+    // eslint-disable-next-line no-control-regex
+    let clean = text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F‎‏‪-‮⁦-⁩]/g, "");
+    if (Buffer.byteLength(clean) > MAX_TEXT_BYTES) {
+        const kept = Buffer.from(clean).subarray(0, MAX_TEXT_BYTES - Buffer.byteLength(CUT_NOTE)).toString("utf8");
+        clean = kept.replace(/�+$/, "") + CUT_NOTE;
+    }
+    return clean;
+}
+// ---- terminal Codex: its own queue ----
+export const queueArgs = (thread, text) => ["queue", "--thread", thread, `--message=${text}`];
+/** Codex prints `Queued message <item> for thread <id>.`; anything else, or
+ * a non-zero exit, queued nothing. */
+export function queued(code, stdout) {
+    return code === 0 && stdout.includes("Queued message ");
+}
+const QUEUE_TIMEOUT_MS = 20_000;
+function queueMessage(home, session, text) {
+    return new Promise((resolve) => {
+        execFile(session.executable, queueArgs(session.thread, text), { timeout: QUEUE_TIMEOUT_MS, env: { ...process.env, CODEX_HOME: home }, maxBuffer: 64 * 1024 }, (error, stdout, stderr) => {
+            if (error && error.killed) {
+                return resolve({ kind: "in-doubt", reason: "codex queue did not finish in time." });
+            }
+            const code = error ? Number(error.code ?? 1) : 0;
+            if (queued(code, String(stdout)))
+                return resolve({ kind: "delivered" });
+            const line = (String(stderr) || String(stdout)).split("\n").map((l) => l.trim()).find(Boolean) ?? `codex exited with code ${code}`;
+            resolve({ kind: "retry", reason: `codex queue: ${line.slice(0, 300)}` });
+        });
+    });
+}
+// ---- the Codex app: its window router ----
+/** The app refuses frames larger than this. */
+export const MAX_FRAME_BYTES = 268_435_456;
+/** A 4-byte little-endian length, then that many bytes of JSON. */
+export function encodeFrame(message) {
+    const payload = Buffer.from(JSON.stringify(message), "utf8");
+    if (!payload.length || payload.length > MAX_FRAME_BYTES)
+        throw new Error("frame size out of range");
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(payload.length, 0);
+    return Buffer.concat([header, payload]);
+}
+/** Splits a byte stream into frames; keeps a partial one for later. */
+export function frameReader() {
+    let pending = Buffer.alloc(0);
+    return (chunk) => {
+        pending = Buffer.concat([pending, chunk]);
+        const out = [];
+        while (pending.length >= 4) {
+            const length = pending.readUInt32LE(0);
+            if (!length || length > MAX_FRAME_BYTES)
+                throw new Error("malformed frame");
+            if (pending.length < 4 + length)
+                break;
+            const body = pending.subarray(4, 4 + length).toString("utf8");
+            pending = pending.subarray(4 + length);
+            try {
+                out.push(JSON.parse(body));
+            }
+            catch {
+                // not JSON: skip it
+            }
+        }
+        return out;
+    };
+}
+/** Method versions the app checks exactly (Agent Relay's, from app build 153). */
+const VERSIONS = { initialize: 0, "thread-owner-discovery": 1, "thread-follower-start-turn": 2 };
+export function ipcRequest(method, params, source, requestId, target, timeoutMs) {
+    return {
+        type: "request",
+        requestId,
+        sourceClientId: source,
+        version: VERSIONS[method],
+        method,
+        params,
+        ...(target ? { targetClientId: target } : {}),
+        ...(timeoutMs ? { timeoutMs } : {}),
+    };
+}
+export function startTurnParams(thread, text, messageId) {
+    return {
+        conversationId: thread,
+        turnStart: {
+            request: { threadId: thread, clientUserMessageId: messageId, input: [{ type: "text", text, text_elements: [] }] },
+            context: {},
+        },
+    };
+}
+/** One connection to the router: send a request, wait for its reply. The
+ * router also asks every client what it can handle; Station says nothing. */
+function routerLink(socketPath) {
+    let socket = null;
+    const waiting = new Map();
+    let closed = false;
+    const read = frameReader();
+    const fail = () => {
+        closed = true;
+        for (const done of waiting.values())
+            done(null);
+        waiting.clear();
+    };
+    const open = () => new Promise((resolve) => {
+        const link = connect(socketPath);
+        socket = link;
+        link.once("connect", () => resolve(true));
+        link.once("error", () => {
+            fail();
+            resolve(false);
+        });
+        link.on("close", fail);
+        link.on("data", (chunk) => {
+            let messages;
+            try {
+                messages = read(chunk);
+            }
+            catch {
+                link.destroy();
+                return;
+            }
+            for (const message of messages) {
+                if (message.type === "client-discovery-request" && message.requestId) {
+                    link.write(encodeFrame({ type: "client-discovery-response", requestId: message.requestId, response: { canHandle: false } }));
+                }
+                else if (message.type === "response" && message.requestId && waiting.has(message.requestId)) {
+                    waiting.get(message.requestId)(message);
+                    waiting.delete(message.requestId);
+                }
+            }
+        });
+    });
+    const request = (method, params, source, waitMs, target, timeoutMs) => new Promise((resolve) => {
+        if (closed || !socket)
+            return resolve(null);
+        const id = randomUUID();
+        const timer = setTimeout(() => {
+            waiting.delete(id);
+            resolve(null);
+        }, waitMs);
+        waiting.set(id, (reply) => {
+            clearTimeout(timer);
+            resolve(reply);
+        });
+        socket.write(encodeFrame(ipcRequest(method, params, source, id, target, timeoutMs)));
+    });
+    const close = () => {
+        socket?.destroy();
+    };
+    return { open, request, close };
+}
+const errorText = (reply) => reply ? (typeof reply.error === "string" ? reply.error : JSON.stringify(reply.error ?? reply.resultType)) : "no answer";
+async function hello(link) {
+    if (!(await link.open()))
+        return { error: "The Codex app is not running." };
+    const reply = await link.request("initialize", { clientType: "station-cli" }, "initializing-client", 5_000);
+    const client = reply?.resultType === "success" ? reply.result?.clientId : undefined;
+    return client ? { client } : { error: `The Codex app did not let Station in: ${errorText(reply)}` };
+}
+/** Asks the window that has the thread open to start a turn with `text`. */
+async function appTurn(home, thread, text, messageId) {
+    const link = routerLink(join(home, "ipc", "ipc.sock"));
+    try {
+        const me = await hello(link);
+        if ("error" in me)
+            return { kind: "retry", reason: me.error };
+        const owner = await link.request("thread-owner-discovery", { hostId: "local", conversationId: thread }, me.client, 12_000);
+        if (owner?.resultType !== "success" || !owner.handledByClientId) {
+            const detail = owner?.error === "no-client-found" ? "" : ` (${errorText(owner)})`;
+            return { kind: "retry", reason: `No Codex window has this chat open.${detail}` };
+        }
+        const started = await link.request("thread-follower-start-turn", startTurnParams(thread, text, messageId), me.client, 32_000, owner.handledByClientId, 30_000);
+        if (!started)
+            return { kind: "in-doubt", reason: "The Codex app did not answer the new turn." };
+        if (started.resultType !== "success")
+            return { kind: "retry", reason: `The Codex app refused the turn: ${errorText(started)}` };
+        return { kind: "delivered" };
+    }
+    finally {
+        link.close();
+    }
+}
+/** Whether the Codex app's router lets Station in, for `station doctor`. */
+export async function appAnswers(home) {
+    const link = routerLink(join(home, "ipc", "ipc.sock"));
+    try {
+        const me = await hello(link);
+        return "error" in me ? me.error : "The Codex app answers.";
+    }
+    finally {
+        link.close();
+    }
+}
+/** Puts `text` into the thread as a new user turn. */
+export async function deliverCodex(home, thread, messageId, text, ps = systemPs, holders = systemHolders) {
+    const session = liveThread(home, thread, ps, holders);
+    if (!session)
+        return { kind: "retry", reason: "No Codex has that thread open." };
+    const clean = cleanText(text);
+    if (session.host === "terminal")
+        return queueMessage(home, session, clean);
+    if (session.host === "exec")
+        return { kind: "retry", reason: "codex exec runs one task and takes no more messages." };
+    if (!threadIdle(home, thread))
+        return { kind: "retry", reason: "Codex is in the middle of a turn." };
+    return appTurn(home, thread, clean, messageId);
+}