@bridge4dev/runner 0.64.1 → 0.65.0

package/dist/adapters/codex-subagents.js

@@ -0,0 +1,569 @@
+import { log } from '../log.js';
+import { asRecord, str } from './codex-protocol.js';
+// Codex's helpers, translated into the one tray every adapter publishes through
+// (ticket #382).
+//
+// The rule «while helpers are working the session is not waiting on a person»
+// is shared and never branches on the agent: the supervisor counts the running
+// rows of `agent_tasks`, and the API and the dashboard read that number through
+// `@devbridge/shared`. Codex was left out at exactly one point – nothing here
+// turned its own events into rows – so its count was always zero and «Waiting»
+// went out over helpers that had another minute of work in front of them.
+//
+// What Codex actually says, measured against codex-cli 0.154.0 on 16.09.2026
+// (models of `multiAgentVersion: v2`; see devreport `codex-background-agents`):
+//
+//  - on the session's OWN thread, one `subAgentActivity` item per event:
+//    `started` when a helper is spawned, `interacted` when words are put in its
+//    mailbox, `interrupted`, and `completed` when its turn ends. The `completed`
+//    one arrives AFTER the parent's turn is over, still carrying that old turn's
+//    id – which is exactly the window the ticket is about;
+//  - `collabAgentToolCall` items carrying `agentsStates`, a map of helper thread
+//    → status. Measured: a `wait` call with an empty map. The tools
+//    (`spawnAgent`, `closeAgent`, …) and the seven statuses are the schema's;
+//  - and the helpers' own threads, on the same connection: their `turn/*`,
+//    `item/*` and status notifications, each tagged with the helper's thread id.
+//    Those are NOT this session's turns (see `CodexSession.onNotification`).
+//
+// There is no LEVEL signal – nothing like Claude's `background_tasks_changed`
+// that states the whole set at once. So the set is kept here from those events,
+// and a snapshot (R16 of plan `critical-tickets-batch`) re-checks it: the full
+// one at the end of every turn (`thread/loaded/list` + `thread/read`, so a lost
+// `started` does not leave a helper uncounted), and a re-read of the helpers
+// believed running once a minute while any of them is (so a lost `completed`
+// does not keep one «running» for ever).
+//
+// What does NOT count: background shell commands (owner's decision D9 – Codex
+// learns nothing when one ends, so there would be nothing to take the count
+// back down with), and the helpers Codex runs for its own housekeeping
+// (review, compaction, memory consolidation), which are not `thread_spawn`.
+/**
+ * The tray's word for a helper. The dashboard draws the robot for any kind with
+ * «agent» in it, and this is the word the Claude SDK already uses for the same
+ * thing – so the row looks the same whichever CLI started it.
+ */
+export const SUBAGENT_TASK_KIND = 'local_agent';
+/** How often the set is re-checked against Codex while a helper is running. */
+export const SUBAGENT_RECONCILE_MS = 60_000;
+/**
+ * How long after a helper became `running` the snapshot may believe an `idle`.
+ *
+ * A thread handed work reports `idle` first and `active` a little later
+ * (measured: 400 ms and 1.3 s after a spawn), so a snapshot landing in that gap
+ * – a parent that spawns and ends its turn at once – would otherwise settle a
+ * helper that has not started yet. A real ending is still caught: by its own
+ * events at once, or by the next tick once this has passed.
+ */
+export const SUBAGENT_SPAWN_GRACE_MS = 30_000;
+/** Codex's `CollabAgentStatus` → the tray. Unknown is «no news», never a guess. */
+export function collabAgentState(status) {
+    switch (status) {
+        case 'pendingInit':
+        case 'running':
+            return 'running';
+        case 'completed':
+        case 'shutdown':
+            return 'done';
+        case 'interrupted':
+        case 'errored':
+        case 'notFound':
+            return 'failed';
+        default:
+            return null;
+    }
+}
+/**
+ * Codex's `SubAgentActivityKind` → the tray. Unknown is «no news».
+ *
+ * `interacted` is deliberately NOT «running»: it is one agent putting words in
+ * another's mailbox, and the CLI's own tool description draws the line —
+ * `followup_task` «gives an existing agent a new task and triggers a turn»,
+ * `send_message` «passes a message to a running agent without triggering a
+ * turn». Both produce this one kind. Measured: a helper reported to the session
+ * with `interacted` and the session's thread started no turn for the next 120
+ * seconds. Read as «working», a message to an agent that has already finished
+ * would put a row back in the tray that nothing takes out again until the
+ * snapshot's grace is over. A re-tasked agent announces itself the honest way,
+ * with its own `turn/started` on its own thread.
+ */
+export function activityState(kind) {
+    switch (kind) {
+        case 'started':
+            return 'running';
+        case 'completed':
+            return 'done';
+        case 'interrupted':
+            return 'failed';
+        default:
+            return null;
+    }
+}
+export function threadReading(raw) {
+    const thread = asRecord(raw);
+    if (!str(thread['id']))
+        return { kind: 'unknown' };
+    // `source` is a plain string for a top-level thread (`vscode`, `cli`…) and an
+    // object only for a helper; `asRecord` reads the string as «no fields».
+    const spawn = asRecord(asRecord(asRecord(thread['source'])['subAgent'])['thread_spawn']);
+    const spawned = Object.keys(spawn).length > 0;
+    return {
+        kind: 'thread',
+        status: str(asRecord(thread['status'])['type']) ?? null,
+        parentThreadId: str(thread['parentThreadId']) ?? str(spawn['parent_thread_id']) ?? null,
+        spawned,
+        nickname: str(thread['agentNickname']) ?? str(spawn['agent_nickname']) ?? null,
+        role: str(thread['agentRole']) ?? str(spawn['agent_role']) ?? null,
+        path: str(spawn['agent_path']) ?? null,
+    };
+}
+/**
+ * A refused `thread/read` or `thread/loaded/list`, classified by what Codex
+ * said. Measured on 0.154.0: an unknown thread is `-32600 thread not loaded:
+ * <id>`, an unknown request is `-32600 Invalid request: unknown variant …` –
+ * the same code, so the sentence decides.
+ */
+export function threadReadingOfError(error) {
+    const record = asRecord(error);
+    const message = str(record['message']) ?? String(error);
+    if (record['name'] === 'RpcTimeoutError')
+        return { kind: 'unknown' };
+    if (record['code'] === -32601 || /unknown variant|method not found/i.test(message)) {
+        return { kind: 'unsupported' };
+    }
+    if (/thread not loaded|invalid thread id|thread not found|no such thread/i.test(message)) {
+        return { kind: 'gone' };
+    }
+    return { kind: 'unknown' };
+}
+/** How long one snapshot request may take. It is metadata only – no turns. */
+const PROBE_TIMEOUT_MS = 15_000;
+export function threadProbeOver(request) {
+    return {
+        async read(threadId) {
+            try {
+                // Metadata only: `includeTurns` stays off. Full-history hydration is
+                // what made `thread/resume` take a minute on a long session (#364).
+                const result = asRecord(await request('thread/read', { threadId }, PROBE_TIMEOUT_MS));
+                return threadReading(result['thread']);
+            }
+            catch (error) {
+                return threadReadingOfError(error);
+            }
+        },
+        async loaded() {
+            try {
+                const result = asRecord(await request('thread/loaded/list', {}, PROBE_TIMEOUT_MS));
+                const data = result['data'];
+                return Array.isArray(data)
+                    ? data.filter((id) => typeof id === 'string' && id.length > 0)
+                    : null;
+            }
+            catch (error) {
+                return threadReadingOfError(error).kind === 'unsupported' ? 'unsupported' : null;
+            }
+        },
+    };
+}
+export class CodexSubagents {
+    opts;
+    helpers = new Map();
+    /** Loaded threads the snapshot already found are not ours to count. */
+    notOurs = new Set();
+    timer = null;
+    reconciling = false;
+    /** A full reconcile asked for while one was running – run once more after it. */
+    reconcileAgain = false;
+    snapshotSupported = true;
+    closed = false;
+    reconcileMs;
+    spawnGraceMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.reconcileMs = opts.reconcileMs ?? SUBAGENT_RECONCILE_MS;
+        this.spawnGraceMs = opts.spawnGraceMs ?? SUBAGENT_SPAWN_GRACE_MS;
+    }
+    /** One of this session's helpers, at any depth. */
+    isHelper(threadId) {
+        return this.helpers.has(threadId);
+    }
+    /**
+     * A collaboration item, on the session's own thread or on a helper's.
+     *
+     * A helper's helpers are this session's too: a spawned agent can spawn, and a
+     * grandchild at work keeps the session just as busy. An item from any other
+     * thread speaks for somebody else and is ignored.
+     */
+    onItem(senderThreadId, item) {
+        if (this.closed)
+            return;
+        if (senderThreadId !== this.opts.ownThreadId() && !this.helpers.has(senderThreadId))
+            return;
+        switch (item['type']) {
+            case 'subAgentActivity': {
+                const target = str(item['agentThreadId']);
+                if (!target)
+                    return;
+                const state = activityState(item['kind']);
+                if (!state) {
+                    // A message to a helper already at work is not news about it, but it
+                    // does carry its path — worth keeping for the row it already has.
+                    if (item['kind'] === 'interacted') {
+                        this.learn(target, { path: str(item['agentPath']) ?? null });
+                    }
+                    return;
+                }
+                this.apply(target, state, { path: str(item['agentPath']) ?? null });
+                return;
+            }
+            case 'collabAgentToolCall': {
+                const states = asRecord(item['agentsStates']);
+                for (const [target, raw] of Object.entries(states)) {
+                    const state = collabAgentState(asRecord(raw)['status']);
+                    if (state)
+                        this.apply(target, state, {});
+                }
+                // What the call did to the agents it names, for a call that finished
+                // and said nothing about them in `agentsStates` – a v1 `spawnAgent`
+                // returns before its agent has reported anything at all.
+                if (item['status'] !== 'completed')
+                    return;
+                const receivers = Array.isArray(item['receiverThreadIds'])
+                    ? item['receiverThreadIds'].filter((id) => typeof id === 'string')
+                    : [];
+                for (const target of receivers) {
+                    if (target in states)
+                        continue;
+                    if (item['tool'] === 'spawnAgent') {
+                        this.apply(target, 'running', { task: str(item['prompt']) ?? null });
+                    }
+                    else if (item['tool'] === 'closeAgent') {
+                        this.apply(target, 'done', {});
+                    }
+                }
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    /**
+     * A helper's own turn started or ended.
+     *
+     * Only for a helper already known: a thread's turn says it is working, not
+     * whose it is, and Codex runs threads of its own (review, compaction) that are
+     * nobody's helpers.
+     */
+    onHelperTurn(threadId, phase, turnStatus) {
+        if (this.closed || !this.helpers.has(threadId))
+            return;
+        if (phase === 'started') {
+            this.apply(threadId, 'running', {});
+            return;
+        }
+        this.apply(threadId, turnStatus === 'failed' || turnStatus === 'interrupted' ? 'failed' : 'done', {});
+    }
+    /** A helper's thread was closed. */
+    onThreadClosed(threadId) {
+        if (this.closed || !this.helpers.has(threadId))
+            return;
+        this.apply(threadId, 'done', {});
+    }
+    /**
+     * The session's turn ended: reset the turn's counters, say what is still
+     * running, then check the set against Codex.
+     *
+     * The frame goes out synchronously, BEFORE the caller emits `turn_end` – the
+     * supervisor decides «is this the person's turn now» on the count it holds at
+     * that moment. The snapshot follows in the background; if it changes the
+     * set, the supervisor re-reports the resting status with the new count.
+     */
+    endTurn() {
+        if (this.closed)
+            return;
+        this.opts.tray.endTurn();
+        void this.reconcile({ everything: true });
+    }
+    close() {
+        this.closed = true;
+        this.stopTimer();
+    }
+    /**
+     * Check the set against Codex (R16).
+     *
+     * `everything` – at the end of a turn: every helper not known to be gone, plus
+     * every loaded thread not classified yet. Otherwise (the minute tick) only
+     * the ones believed running, which is what can go stale.
+     */
+    async reconcile(options) {
+        if (this.closed || !this.snapshotSupported)
+            return;
+        if (this.reconciling) {
+            if (options.everything)
+                this.reconcileAgain = true;
+            return;
+        }
+        this.reconciling = true;
+        try {
+            await this.reconcileOnce(options.everything);
+            while (this.reconcileAgain && !this.gone()) {
+                this.reconcileAgain = false;
+                await this.reconcileOnce(true);
+            }
+        }
+        catch (error) {
+            log.warn('codex: helper snapshot failed', { error: String(error) });
+        }
+        finally {
+            this.reconciling = false;
+            this.reconcileAgain = false;
+        }
+    }
+    gone() {
+        return this.closed || this.opts.isStopped();
+    }
+    async reconcileOnce(everything) {
+        const own = this.opts.ownThreadId();
+        if (!own)
+            return;
+        for (const [threadId, helper] of [...this.helpers]) {
+            if (this.gone() || !this.snapshotSupported)
+                return;
+            if (helper.retired)
+                continue;
+            if (!everything && helper.state !== 'running')
+                continue;
+            const reading = await this.opts.probe.read(threadId);
+            if (this.gone())
+                return;
+            this.absorb(threadId, reading);
+        }
+        if (!everything || !this.snapshotSupported)
+            return;
+        const loaded = await this.opts.probe.loaded();
+        if (this.gone())
+            return;
+        if (loaded === 'unsupported') {
+            this.snapshotSupported = false;
+            return;
+        }
+        if (!loaded)
+            return;
+        for (const threadId of loaded) {
+            if (threadId === own || this.helpers.has(threadId) || this.notOurs.has(threadId))
+                continue;
+            const reading = await this.opts.probe.read(threadId);
+            if (this.gone())
+                return;
+            if (reading.kind === 'unsupported') {
+                this.snapshotSupported = false;
+                return;
+            }
+            if (reading.kind !== 'thread')
+                continue;
+            // Loaded threads come oldest first, so a grandchild is read after the
+            // child that makes it ours.
+            const parent = reading.parentThreadId;
+            const ours = reading.spawned && parent !== null && (parent === own || this.helpers.has(parent));
+            if (!ours) {
+                this.notOurs.add(threadId);
+                continue;
+            }
+            // Ours, and missed. Remembered whatever it is doing, so that its next turn
+            // is counted; a row only if it is working now.
+            this.remember(threadId, {
+                path: reading.path,
+                nickname: reading.nickname,
+                role: reading.role,
+            }).asked = true;
+            if (reading.status === 'active')
+                this.apply(threadId, 'running', {});
+        }
+    }
+    /** What one reading means for a helper already held. */
+    absorb(threadId, reading) {
+        const helper = this.helpers.get(threadId);
+        if (!helper)
+            return;
+        switch (reading.kind) {
+            case 'unsupported':
+                this.snapshotSupported = false;
+                return;
+            case 'unknown':
+                return;
+            case 'gone':
+                helper.retired = true;
+                this.apply(threadId, 'done', {});
+                return;
+            case 'thread':
+                break;
+        }
+        this.learn(threadId, { nickname: reading.nickname, role: reading.role, path: reading.path });
+        switch (reading.status) {
+            case 'active':
+                // Working, and held as finished: a lost `started` / `interacted`.
+                if (helper.state !== 'running')
+                    this.apply(threadId, 'running', {});
+                return;
+            case 'idle':
+                if (helper.state !== 'running')
+                    return;
+                // A thread handed work reports `idle` for a moment before its turn
+                // starts – believed only once that moment is well past.
+                if (Date.now() - helper.runningSince < this.spawnGraceMs)
+                    return;
+                this.apply(threadId, 'done', {});
+                return;
+            case 'notLoaded':
+                helper.retired = true;
+                this.apply(threadId, 'done', {});
+                return;
+            case 'systemError':
+                this.apply(threadId, 'failed', {});
+                return;
+            default:
+                // A status this runner does not know is not news about the helper.
+                return;
+        }
+    }
+    /** The helper's record, created (as finished) if it is new. */
+    remember(threadId, facts) {
+        let helper = this.helpers.get(threadId);
+        if (!helper) {
+            helper = {
+                state: 'done',
+                runningSince: Date.now(),
+                retired: false,
+                asked: false,
+                nickname: null,
+                path: null,
+                role: null,
+                task: null,
+            };
+            this.helpers.set(threadId, helper);
+        }
+        helper.nickname = facts.nickname ?? helper.nickname;
+        helper.path = facts.path ?? helper.path;
+        helper.role = facts.role ?? helper.role;
+        helper.task = facts.task ?? helper.task;
+        return helper;
+    }
+    /**
+     * Move one helper to a state, and publish.
+     *
+     * The session itself is never its own helper: a helper reporting back to its
+     * parent names the PARENT as the agent it «interacted» with
+     * (`agentThreadId` = the session's thread, `agentPath: "/root"`) – measured
+     * on 0.154.0, and counted it would keep the session «busy» for ever.
+     */
+    apply(threadId, state, facts) {
+        if (threadId === this.opts.ownThreadId())
+            return;
+        // Nobody we counted finishing is no news at all.
+        if (state !== 'running' && !this.helpers.has(threadId))
+            return;
+        const helper = this.remember(threadId, facts);
+        const tray = this.opts.tray;
+        if (state === 'running') {
+            helper.retired = false;
+            if (helper.state !== 'running') {
+                // Handed new work after it had finished: a new row, not the old one
+                // coming back – the tray's settling is one-way on purpose.
+                tray.forget(threadId);
+                tray.touch(threadId, { kind: SUBAGENT_TASK_KIND, status: 'running', ...rowFacts(helper) });
+                helper.state = 'running';
+                helper.runningSince = Date.now();
+            }
+            else {
+                tray.touch(threadId, rowFacts(helper));
+            }
+            this.syncLive();
+            if (!helper.asked && !helper.nickname) {
+                helper.asked = true;
+                void this.askName(threadId);
+            }
+            return;
+        }
+        if (helper.state !== 'running')
+            return;
+        helper.state = state;
+        tray.touch(threadId, { status: state });
+        this.syncLive();
+    }
+    /** New facts about a helper, onto its row if it has one. */
+    learn(threadId, facts) {
+        const helper = this.helpers.get(threadId);
+        if (!helper)
+            return;
+        this.remember(threadId, facts);
+        if (helper.state !== 'running' || !this.opts.tray.has(threadId))
+            return;
+        this.opts.tray.touch(threadId, rowFacts(helper));
+        this.opts.tray.publish();
+    }
+    /**
+     * Ask Codex for the helper's name once, right after it appears. The activity
+     * item carries only its path (`/root/a`); the name Codex gives it
+     * («Heisenberg») is what Codex's own interface calls it.
+     */
+    async askName(threadId) {
+        if (!this.snapshotSupported)
+            return;
+        const reading = await this.opts.probe.read(threadId);
+        if (this.gone())
+            return;
+        if (reading.kind === 'unsupported') {
+            this.snapshotSupported = false;
+            return;
+        }
+        if (reading.kind !== 'thread')
+            return;
+        this.learn(threadId, { nickname: reading.nickname, role: reading.role, path: reading.path });
+    }
+    syncLive() {
+        const live = [];
+        for (const [threadId, helper] of this.helpers) {
+            if (helper.state === 'running')
+                live.push(threadId);
+        }
+        this.opts.tray.setLive(live);
+        this.opts.tray.publish();
+        if (live.length > 0)
+            this.startTimer();
+        else
+            this.stopTimer();
+    }
+    startTimer() {
+        if (this.timer || this.closed)
+            return;
+        this.timer = setInterval(() => {
+            void this.reconcile({ everything: false });
+        }, this.reconcileMs);
+        this.timer.unref?.();
+    }
+    stopTimer() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+}
+/** A helper's row, as far as it is known. */
+function rowFacts(helper) {
+    return {
+        title: titleOf(helper.nickname, helper.path),
+        ...(helper.role ? { subagentType: helper.role } : {}),
+        ...(helper.task ? { summary: helper.task } : {}),
+    };
+}
+/**
+ * «Heisenberg · a» – the name Codex gave the helper, and the path the parent
+ * gave it. Either alone when the other is unknown; the path loses its `/root/`
+ * prefix, which every helper of this session shares.
+ */
+function titleOf(nickname, path) {
+    const shortPath = path ? path.replace(/^\/root\/?/, '') || path : null;
+    if (nickname && shortPath)
+        return `${nickname} · ${shortPath}`;
+    return nickname ?? shortPath ?? 'Subagent';
+}
+//# sourceMappingURL=codex-subagents.js.map

package/dist/adapters/codex.d.ts

@@ -33,6 +33,10 @@ export interface CodexAdapterDeps {
      * runner's credential separate.
      */
     authMode?: 'link' | 'own';
+    /** #382: how often live helpers are re-checked against Codex – a test seam. */
+    subagentReconcileMs?: number;
+    /** #382: how long a just-started helper's `idle` is disbelieved – a test seam. */
+    subagentSpawnGraceMs?: number;
 }
 /**
  * Codex's own wording for "the sign-in did not work".