excaliagent 0.2.0 → 0.4.0

package/dist/server/sources/codex-live.js

@@ -0,0 +1,279 @@
+// Which Codex threads are running, and in which process. Codex has no session
+// registry like Claude's; what it has (verified on 0.163.0, Linux):
+//
+// - `<codexHome>/thread-writer-locks/<thread id>.lock`: created and flock()ed
+//   by whoever has the thread loaded, unlocked and deleted when it is unloaded.
+//   Crashes leave the file but release the lock, so only a *held* lock counts:
+//   the holder is found in /proc/locks by inode and confirmed through
+//   /proc/<pid>/fd.
+// - The interactive TUI (`codex`, `codex resume <id>`) does not hold it: it
+//   talks to a shared app-server daemon (`codex app-server ... --managed-daemon`,
+//   one per Codex home) that loads the thread. The daemon keeps a thread loaded
+//   for `thread_unload_delay_secs` (default 30 min) after its last client left,
+//   so a held lock alone does not mean someone is looking at it.
+// - `codex exec` loads its thread in-process and holds the lock itself.
+//
+// So a thread held by a non-daemon codex process is live in that process. A
+// thread held by the daemon is live only when a TUI process claims it: by its
+// argv (`resume <id>`), else by working directory, among threads loaded after
+// that TUI started (a thread loaded earlier belongs to another, maybe closed,
+// TUI; a fresh TUI's own thread appears ~1.4 s after it): one with a rollout
+// if any, else its earliest new thread (with auto-review on, the daemon loads
+// a second, reviewer thread right after the conversation, which never gets a
+// rollout unless it reviews something).
+// Daemon threads no TUI claims are lingering, i.e. dormant. Only the first two
+// (in-process holder, `resume <id>`) are exact; a working-directory claim is a
+// guess, so such a session cannot be stopped from the board. Pure matching
+// lives in `assignLive`; the /proc reading around it is Linux-only and takes a
+// proc root, so tests read a synthetic tree.
+import { readdir, readFile, readlink, realpath, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { createProcessTable } from "../desktop/process-table.js";
+import { CODEX_ID, uuidV7Ms } from "./codex-rollout.js";
+import { bootTime, startedAt } from "./proc.js";
+/** A Codex executable: argv[0] or exe named `codex`, or the npm shim (`node …/codex.js`). */
+export function looksLikeCodex(argv, exe) {
+    const names = [argv?.[0], exe].filter((n) => !!n).map((n) => basename(n));
+    if (names.some((n) => n === "codex" || n === "codex.exe"))
+        return true;
+    const script = argv?.[1] ? basename(argv[1]) : "";
+    return names.some((n) => /^node(\.exe)?$/.test(n)) && (script === "codex" || script === "codex.js");
+}
+// Options that take a value, so the next word is not the subcommand.
+const VALUE_FLAGS = new Set([
+    "-c", "--config", "-m", "--model", "-p", "--profile", "-s", "--sandbox", "-a", "--ask-for-approval",
+    "-C", "--cd", "-i", "--image", "--add-dir", "--enable", "--disable", "--local-provider", "--remote",
+    "--remote-auth-token-env",
+]);
+// Subcommands that are not an interactive session (the TUI is `codex [PROMPT]`, `resume`, `fork`).
+const NOT_TUI = new Set([
+    "agents", "exec", "e", "review", "login", "logout", "mcp", "plugin", "app-server", "remote-control",
+    "completion", "update", "doctor", "sandbox", "debug", "apply", "a", "queue", "archive", "delete",
+    "migrate-rollouts", "unarchive", "cloud", "exec-server", "features", "help", "mcp-server",
+]);
+/** The words after the program (and after the script, for the npm shim). */
+function args(argv) {
+    const shim = /^node(\.exe)?$/.test(basename(argv[0] ?? ""));
+    return argv.slice(shim ? 2 : 1);
+}
+/** First positional word: the subcommand, a prompt, or undefined. */
+export function codexSubcommand(argv) {
+    const a = args(argv);
+    for (let i = 0; i < a.length; i++) {
+        const w = a[i];
+        if (w === "--")
+            return a[i + 1];
+        if (w.startsWith("-")) {
+            if (VALUE_FLAGS.has(w))
+                i++;
+            continue;
+        }
+        return w;
+    }
+    return undefined;
+}
+export const isDaemon = (argv) => codexSubcommand(argv) === "app-server";
+/**
+ * An interactive Codex TUI process. Codex also runs its own binary as helpers
+ * (verified on 0.163.0: `codex-linux-sandbox ...` around every sandboxed
+ * command, once under bwrap, with the repo as cwd); those have another
+ * argv[0] (`codex-linux-sandbox`, `apply_patch`) or a `--codex-run-as-*`
+ * argv[1], and are not TUIs.
+ */
+export const isTui = (argv) => {
+    const shim = /^node(\.exe)?$/.test(basename(argv[0] ?? ""));
+    const name = basename((shim ? argv[1] : argv[0]) ?? "");
+    if (!(shim ? name === "codex" || name === "codex.js" : name === "codex" || name === "codex.exe"))
+        return false;
+    if (args(argv)[0]?.startsWith("--codex-run-as-"))
+        return false;
+    const sub = codexSubcommand(argv);
+    return sub === undefined || !NOT_TUI.has(sub);
+};
+/** `codex resume <id>` / `codex fork <id>`: the thread named on the command line. */
+export function argvThreadId(argv) {
+    const a = args(argv);
+    const sub = codexSubcommand(argv);
+    if (sub !== "resume")
+        return undefined; // a fork gets a new id
+    const rest = a.slice(a.indexOf(sub) + 1);
+    return rest.find((w) => CODEX_ID.test(w))?.toLowerCase();
+}
+/**
+ * Pure: which held threads are live, and where. `threadCwd` gives a thread's
+ * start cwd (from its rollout; undefined before the first message is written).
+ * `isUser` says whether a thread may be claimed by a TUI (not a sub-agent etc.).
+ * `threadActivity` gives the epoch ms of a thread's last rollout activity, and
+ * is undefined exactly when it has no rollout (default: when it has no cwd).
+ * Deterministic: the same locks and processes give the same answer in any order.
+ */
+export function assignLive(locks, procs, threadCwd, isUser = () => true, threadActivity = (id) => (threadCwd(id) === undefined ? undefined : 0)) {
+    const byPid = new Map(procs.map((p) => [p.pid, p]));
+    const out = [];
+    const daemonHeld = [];
+    for (const l of locks) {
+        const holder = byPid.get(l.pid);
+        if (!holder)
+            continue;
+        if (isDaemon(holder.argv))
+            daemonHeld.push(l);
+        else
+            out.push({ threadId: l.threadId, pid: l.pid, exact: true });
+    }
+    // TUIs; the npm shim and the native binary below it count once (the outer one).
+    const codexPids = new Set(procs.map((p) => p.pid));
+    const tuis = procs
+        .filter((p) => !isDaemon(p.argv) && isTui(p.argv) && !codexPids.has(p.ppid))
+        .filter((p) => !out.some((t) => t.pid === p.pid))
+        // Newest first: a later TUI is more likely on the newest thread of a directory,
+        // and what it leaves (its reviewer, say) is reserved before older TUIs choose.
+        .sort((a, b) => b.startedAt - a.startedAt || b.pid - a.pid);
+    const free = new Set(daemonHeld.filter((l) => isUser(l.threadId)).map((l) => l.threadId));
+    const loaded = new Map(daemonHeld.map((l) => [l.threadId, l.loadedAt]));
+    const created = (id) => uuidV7Ms(id) ?? loaded.get(id);
+    // Earliest created first; a tie goes to the smaller id, never to scan order.
+    const earlier = (a, b) => created(a) - created(b) || (a < b ? -1 : a > b ? 1 : 0);
+    /** Free threads `t` can have opened: from its directory (or no rollout yet), loaded after it started. */
+    const candidates = (t) => [...free]
+        .filter((id) => {
+        const cwd = threadCwd(id);
+        if (cwd !== undefined && cwd !== t.cwd)
+            return false;
+        const rollout = threadActivity(id) !== undefined;
+        // `codex resume` (its picker) only ever opens a thread with a rollout.
+        if (!rollout && codexSubcommand(t.argv) === "resume")
+            return false;
+        // Loaded after it started (else another TUI's, lingering), and, with no
+        // rollout yet (nobody can resume such a thread), created after it
+        // started. startedAt is never late (btime is whole seconds, rounded
+        // down), so its own thread always passes.
+        if (t.startedAt > 0 && (loaded.get(id) < t.startedAt || (!rollout && created(id) < t.startedAt)))
+            return false;
+        return true;
+    })
+        .sort(earlier);
+    // Threads loaded after a TUI started that it did not take (its reviewer, say):
+    // no other TUI may take them either, unless one is that TUI's own earliest.
+    const reserved = new Set();
+    const claimed = new Set();
+    for (const t of tuis) {
+        const id = argvThreadId(t.argv);
+        // A TUI that names its thread never guesses another one, even if that one is taken.
+        if (id)
+            claimed.add(t.pid);
+        if (id && free.has(id)) {
+            free.delete(id);
+            out.push({ threadId: id, pid: t.pid, exact: true, ...(t.cwd ? { cwd: t.cwd } : {}) });
+        }
+    }
+    for (const t of tuis)
+        if (claimed.has(t.pid) && t.cwd)
+            for (const id of candidates(t))
+                reserved.add(id);
+    for (const t of tuis) {
+        if (claimed.has(t.pid) || !t.cwd)
+            continue;
+        const mine = candidates(t);
+        const allowed = mine.filter((id, i) => i === 0 || !reserved.has(id));
+        for (const id of mine)
+            reserved.add(id);
+        // A thread with a rollout wins (the newest activity, then the newest load,
+        // then the larger id); else the earliest new thread: the conversation, not
+        // the auto-review thread the daemon loads just after it.
+        const withRollout = allowed.filter((id) => threadActivity(id) !== undefined);
+        const best = withRollout.length
+            ? withRollout.reduce((a, b) => {
+                const d = threadActivity(b) - threadActivity(a) || loaded.get(b) - loaded.get(a);
+                return d > 0 || (d === 0 && b > a) ? b : a;
+            })
+            : allowed[0];
+        if (best === undefined)
+            continue;
+        free.delete(best);
+        out.push({ threadId: best, pid: t.pid, cwd: t.cwd, exact: false });
+    }
+    return out;
+}
+/** `/proc/locks` → inode → pids holding (not waiting for) a lock on it. */
+export function parseProcLocks(text) {
+    const out = new Map();
+    for (const line of text.split("\n")) {
+        const f = line.trim().split(/\s+/);
+        if (f.length < 6 || f[1] === "->")
+            continue;
+        const pid = Number(f[4]);
+        const inode = Number(f[5].split(":")[2]);
+        if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(inode))
+            continue;
+        out.set(inode, [...(out.get(inode) ?? []), pid]);
+    }
+    return out;
+}
+/**
+ * Reads the held thread locks under `lockDir`, their holders and, only when a
+ * daemon holds one, the Codex TUI processes that may be showing it. No lock
+ * file → nothing else is read. Undefined when /proc/locks is not readable (not
+ * Linux): liveness unknown.
+ */
+export async function scanCodexProcesses(lockDir, procRoot = "/proc") {
+    const locksText = await readFile(join(procRoot, "locks"), "utf8").catch(() => undefined);
+    if (locksText === undefined)
+        return undefined;
+    lockDir = await realpath(lockDir).catch(() => lockDir);
+    const files = (await readdir(lockDir).catch(() => [])).filter((f) => f.endsWith(".lock") && CODEX_ID.test(f.slice(0, -5)));
+    if (!files.length)
+        return { locks: [], procs: [] };
+    const table = createProcessTable({ platform: "linux", procRoot });
+    const btime = await bootTime(procRoot);
+    const procs = new Map();
+    const proc = async (pid, ppid) => {
+        const known = procs.get(pid);
+        if (known !== undefined)
+            return known ?? undefined;
+        const [argv, exe] = await Promise.all([table.argv(pid), table.exe(pid)]);
+        if (!argv || !looksLikeCodex(argv, exe)) {
+            procs.set(pid, null);
+            return undefined;
+        }
+        const [cwd, parent, started] = await Promise.all([
+            readlink(join(procRoot, String(pid), "cwd")).catch(() => undefined),
+            ppid ?? table.parent(pid),
+            startedAt(procRoot, pid, btime),
+        ]);
+        const p = { pid, ppid: parent ?? 0, argv, startedAt: started, ...(cwd ? { cwd } : {}) };
+        procs.set(pid, p);
+        return p;
+    };
+    const fds = async (pid) => {
+        const dir = join(procRoot, String(pid), "fd");
+        const names = await readdir(dir).catch(() => []);
+        return new Set((await Promise.all(names.map((n) => readlink(join(dir, n)).catch(() => "")))).filter(Boolean));
+    };
+    const holders = parseProcLocks(locksText);
+    const fdCache = new Map();
+    const locks = [];
+    for (const f of files) {
+        const path = join(lockDir, f);
+        const st = await stat(path).catch(() => undefined);
+        if (!st)
+            continue;
+        for (const pid of holders.get(st.ino) ?? []) {
+            if (!(await proc(pid)))
+                continue;
+            if (!fdCache.has(pid))
+                fdCache.set(pid, await fds(pid));
+            if (!fdCache.get(pid).has(path))
+                continue;
+            locks.push({ threadId: f.slice(0, -5).toLowerCase(), pid, loadedAt: st.birthtimeMs || st.ctimeMs });
+            break;
+        }
+    }
+    if (locks.some((l) => isDaemon(procs.get(l.pid).argv))) {
+        for (const p of await table.list()) {
+            // Cheap filter before reading argv: the native binary, or a node shim.
+            if (/codex|node|MainThread/i.test(p.comm))
+                await proc(p.pid, p.ppid);
+        }
+    }
+    return { locks, procs: [...procs.values()].filter((p) => p !== null) };
+}

package/dist/server/sources/codex-rollout.js

@@ -0,0 +1,154 @@
+// Codex rollouts: <codexHome>/sessions/YYYY/MM/DD/rollout-<local time>-<thread id>.jsonl
+// (old ones may be compressed to `.jsonl.zst`). Folded incrementally; only
+// metadata is kept, plus the first user message (cut short) as the fallback
+// title, which is what Codex itself shows in its resume picker.
+// Formats: docs/design.md "Codex data".
+import { readFile, stat } from "node:fs/promises";
+import { JsonlScanner } from "./jsonl.js";
+export const TITLE_MAX = 120;
+const USER_MESSAGE_BEGIN = "## My request for Codex:";
+const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
+const TS = /^\{"timestamp":"([^"]+)"/;
+// Cheap prefilter on the line; the parsed type is still checked.
+const INTERESTING = /"type":"(?:session_meta|task_started|turn_started|task_complete|turn_complete|turn_aborted|user_message|UserMessage)"/;
+function short(text) {
+    const i = text.indexOf(USER_MESSAGE_BEGIN);
+    const t = (i >= 0 ? text.slice(i + USER_MESSAGE_BEGIN.length) : text).replace(/\s+/g, " ").trim();
+    if (!t)
+        return undefined;
+    const chars = [...t];
+    return chars.length <= TITLE_MAX ? t : chars.slice(0, TITLE_MAX - 1).join("") + "…";
+}
+/** Text of an item_completed UserMessage (paginated history) or a legacy user_message event. */
+function userText(p) {
+    if (p.type === "user_message")
+        return str(p.message);
+    const item = p.item;
+    if (p.type !== "item_completed" || item?.type !== "UserMessage" || !Array.isArray(item.content))
+        return undefined;
+    const parts = item.content
+        .map((c) => (c && typeof c === "object" && c.type === "text" ? str(c.text) : undefined))
+        .filter((t) => t !== undefined);
+    return parts.length ? parts.join(" ") : undefined;
+}
+export function applyRolloutLine(acc, o) {
+    const p = o.payload;
+    if (!p || typeof p !== "object" || Array.isArray(p))
+        return;
+    const payload = p;
+    if (o.type === "session_meta") {
+        // A forked thread's file starts with its own meta; later metas (if any) do not override it.
+        if (acc.id)
+            return;
+        acc.id = str(payload.id);
+        acc.cwd = str(payload.cwd);
+        acc.branch = str(payload.git?.branch);
+        acc.source = payload.source;
+        acc.threadSource = str(payload.thread_source);
+        acc.parentThreadId = str(payload.parent_thread_id);
+        return;
+    }
+    if (o.type !== "event_msg")
+        return;
+    switch (payload.type) {
+        case "task_started":
+        case "turn_started":
+            acc.turnOpen = true;
+            return;
+        case "task_complete":
+        case "turn_complete":
+        case "turn_aborted":
+            acc.turnOpen = false;
+            return;
+    }
+    if (acc.firstUserMessage === undefined) {
+        const text = userText(payload);
+        if (text !== undefined)
+            acc.firstUserMessage = short(text);
+    }
+}
+const fold = {
+    empty: () => ({ turnOpen: false, lastTimestamp: 0 }),
+    raw(acc, line) {
+        const m = TS.exec(line);
+        const t = m ? Date.parse(m[1]) : NaN;
+        if (Number.isFinite(t) && t > acc.lastTimestamp)
+            acc.lastTimestamp = t;
+    },
+    interesting: (line) => INTERESTING.test(line),
+    apply: applyRolloutLine,
+    snapshot: (acc) => ({ ...acc }),
+};
+export class RolloutScanner extends JsonlScanner {
+    constructor(opts = {}) {
+        super(fold, { ...opts, noun: "Codex rollout" });
+    }
+}
+/** Thread ids are UUIDs (v7 in practice). */
+export const CODEX_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Creation time of a UUIDv7 (its first 48 bits, epoch ms), else undefined. */
+export function uuidV7Ms(id) {
+    if (id[14] !== "7")
+        return undefined;
+    const ms = parseInt(id.slice(0, 8) + id.slice(9, 13), 16);
+    return Number.isFinite(ms) ? ms : undefined;
+}
+/**
+ * `rollout-2026-10-20T14-07-46-<uuid>.jsonl[.zst]`; a reverted thread's file
+ * appends `_<rollout id>` to the thread id. Returns the thread id.
+ */
+export function rolloutThreadId(name) {
+    const m = /^rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-([0-9a-f-]{36})(?:_[0-9a-f-]{36})?\.jsonl(?:\.zst)?$/i.exec(name);
+    return m && CODEX_ID.test(m[1]) ? m[1].toLowerCase() : undefined;
+}
+/** Only threads a person started (not sub-agents, reviews, `codex exec` or MCP runs) go into the picker. */
+export function isUserThread(r) {
+    if (r.parentThreadId)
+        return false;
+    if (r.threadSource !== undefined && r.threadSource !== "user")
+        return false;
+    if (r.source !== undefined && typeof r.source !== "string")
+        return false;
+    return r.source !== "exec" && r.source !== "mcp";
+}
+/**
+ * `<codexHome>/session_index.jsonl`: `{"id","thread_name","updated_at"}` per
+ * line, appended on every rename; the last entry for an id wins. Re-read only
+ * when its size or mtime changes.
+ */
+export class SessionIndex {
+    key = "";
+    names = new Map();
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async read() {
+        const st = await stat(this.path).catch(() => undefined);
+        const key = st ? `${st.size}:${st.mtimeMs}` : "";
+        if (key === this.key)
+            return this.names;
+        const names = new Map();
+        const text = st ? await readFile(this.path, "utf8").catch(() => "") : "";
+        for (const line of text.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const o = JSON.parse(line);
+                if (typeof o.id !== "string")
+                    continue;
+                const name = typeof o.thread_name === "string" ? o.thread_name.trim() : "";
+                if (name)
+                    names.set(o.id.toLowerCase(), name);
+                else
+                    names.delete(o.id.toLowerCase());
+            }
+            catch {
+                // a torn last line while Codex appends; the next read gets it
+            }
+        }
+        this.key = key;
+        this.names = names;
+        return names;
+    }
+}