@bridge4dev/runner 0.64.1 → 0.65.0

package/dist/adapters/codex.js

@@ -6,6 +6,8 @@ import { RUNNER_VERSION } from '../version.js';
 import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, RpcError, RpcTimeoutError, str, } from './codex-protocol.js';
 import { truncate } from './claude.js';
+import { AgentTaskTray } from './agent-tasks.js';
+import { CodexSubagents, threadProbeOver } from './codex-subagents.js';
 import { availableModes, cardDescription, DIRECT_BRANCH_RULE, folderRuleFor, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { clampPercent, rateWindowKeyFromMinutes } from './rate-limits.js';
 import { answerSummary, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
@@ -182,6 +184,24 @@ const APPROVAL_METHODS = new Set([
     'item/permissions/requestApproval',
     'mcpServer/elicitation/request',
 ]);
+/**
+ * Notifications that concern the whole session whichever thread they name
+ * (#382). Everything else from a thread other than the session's own belongs to
+ * a helper – see `CodexSession.onHelperNotification`.
+ *
+ *  - `serverRequest/resolved`: a helper's approval is shown as an ordinary card,
+ *    and the card has to close when it is answered elsewhere;
+ *  - MCP start-up and the warnings: the helpers share the session's servers and
+ *    configuration, and each distinct sentence is shown once anyway.
+ */
+const SESSION_WIDE = new Set([
+    'serverRequest/resolved',
+    'mcpServer/startupStatus/updated',
+    'configWarning',
+    'warning',
+    'guardianWarning',
+    'deprecationNotice',
+]);
 class CodexSession {
     spec;
     home;
@@ -236,6 +256,15 @@ class CodexSession {
     stopped = false;
     ready = false;
     capabilitiesInFlight = false;
+    /**
+     * Helpers at work beside the conversation (#382) – the same tray, and so the
+     * same «is anybody still working» rule, as the Claude adapter's.
+     */
+    tray = new AgentTaskTray({
+        emit: (event) => this.emit(event),
+        isStopped: () => this.stopped,
+    });
+    subagents;
     events = this.output;
     constructor(spec, home, deps) {
         this.spec = spec;
@@ -272,6 +301,16 @@ class CodexSession {
                 sessionId: spec.sessionId,
                 ...wiring,
             });
+        this.subagents = new CodexSubagents({
+            tray: this.tray,
+            ownThreadId: () => this.threadId,
+            probe: threadProbeOver((method, params, timeoutMs) => this.client.request(method, params, timeoutMs)),
+            isStopped: () => this.stopped,
+            ...(deps.subagentReconcileMs === undefined ? {} : { reconcileMs: deps.subagentReconcileMs }),
+            ...(deps.subagentSpawnGraceMs === undefined
+                ? {}
+                : { spawnGraceMs: deps.subagentSpawnGraceMs }),
+        });
         if (this.modeRefusedAtLaunch) {
             this.notice('warn', MODE_REFUSED_TEXT);
             this.emit({ type: 'settings', mode: this.mode });
@@ -307,6 +346,17 @@ class CodexSession {
                 throw new Error(`codex is using an unexpected CODEX_HOME (${reportedHome ?? 'not reported'}) — refusing to start the session`);
             }
             this.client.notify('initialized', {});
+            // The helper set is per PROCESS (#113, #382): a session relaunched after a
+            // runner restart must not go on showing the helpers of its previous life,
+            // and nothing else would say so until the next one starts or ends.
+            //
+            // Here and not in the constructor, and that is not tidiness: the
+            // supervisor reads the FIRST event of a session as «the process came up»
+            // and calls off the watch for a CLI that never boots (#225). A frame
+            // emitted before a single byte reached the app-server would answer that
+            // watch for every Codex session, on behalf of a process that has said
+            // nothing. This is the first moment the process really has.
+            this.tray.announceEmpty();
             if (this.home.auth === 'missing') {
                 // One repair attempt before telling the user their login is broken: the
                 // credential link can be removed under a running daemon, and putting it
@@ -956,6 +1006,9 @@ class CodexSession {
         if (this.stopped)
             return;
         this.stopped = true;
+        // The helpers go with the process; nothing more is published about them.
+        this.subagents.close();
+        this.tray.close();
         // Release anything the agent is blocked on so the child can exit cleanly —
         // and say in the feed that the runner did it, not the user. A pending card
         // used to gutter out looking like a human decision.
@@ -1262,6 +1315,17 @@ class CodexSession {
     }
     // ─── Notifications ─────────────────────────────────────────────────
     onNotification(method, params) {
+        // #382. One app-server runs the session's thread AND every helper it spawns,
+        // and the helpers' notifications arrive on this same connection tagged with
+        // their own thread id (measured on 0.154.0). Read as ours, a helper's
+        // `turn/completed` ended THIS session's turn while it was still working, its
+        // `turn/started` became the turn a Stop or a steer is aimed at, and its
+        // prose went into the feed as this session's answer.
+        const thread = str(params['threadId']);
+        if (thread && this.threadId && thread !== this.threadId && !SESSION_WIDE.has(method)) {
+            this.onHelperNotification(thread, method, params);
+            return;
+        }
         switch (method) {
             case 'item/started':
             case 'item/updated':
@@ -1417,21 +1481,100 @@ class CodexSession {
                 return;
         }
     }
+    /**
+     * A notification from another thread in this app-server – a helper's, or one
+     * of Codex's own (#382).
+     *
+     * What it may change is the helper count and, while a turn of this session is
+     * running, that turn's «work was done» flags – and nothing else: not the turn
+     * itself, not the feed, not the context meter or the settings on the header,
+     * and not the session's health. A helper's failure is the helper's; the one
+     * exception is the plan limit, which belongs to the account and refuses this
+     * session next. Its tool calls stay
+     * out of the feed too, and that is not tidiness: the supervisor reads any
+     * tool event from a resting session as «the agent is working» (#185), and no
+     * turn of THIS session would ever come to put it back – a helper finishing
+     * does not start one.
+     *
+     * Its items are still remembered: a helper's command that needs a person
+     * arrives as an ordinary approval request, and the card is only readable
+     * because the item behind it is known.
+     */
+    onHelperNotification(thread, method, params) {
+        switch (method) {
+            case 'item/started':
+            case 'item/updated':
+            case 'item/completed': {
+                const item = asRecord(params['item']);
+                this.rememberItem(item);
+                // What a helper does while this session's turn is running is that turn's
+                // work (#252, #257) – the Claude adapter counts a subagent's tool calls
+                // for the same reason: a helper's `git push` is still a push, and a
+                // failed turn that pushed must not be sent again as if nothing happened.
+                if (method === 'item/started' &&
+                    item['type'] === 'commandExecution' &&
+                    this.activeTurnId !== null &&
+                    this.subagents.isHelper(thread)) {
+                    this.noteWork(str(item['command']) ?? '');
+                }
+                this.subagents.onItem(thread, item);
+                return;
+            }
+            case 'turn/started':
+                this.subagents.onHelperTurn(thread, 'started');
+                return;
+            case 'turn/completed': {
+                const turn = asRecord(params['turn']);
+                // A helper refused by the plan limit is this ACCOUNT being refused: the
+                // session's own next turn will be refused too, so the API is told and
+                // the feed says why (#382). Only the announcement — no turn of this
+                // session ended, so there is no ending to mark `limitBlocked`.
+                if (str(turn['status']) === 'failed') {
+                    this.announceRateLimitRefusal(asRecord(turn['error']));
+                }
+                this.subagents.onHelperTurn(thread, 'completed', str(turn['status']));
+                return;
+            }
+            case 'thread/closed':
+                this.subagents.onThreadClosed(thread);
+                return;
+            case 'error':
+                if (params['willRetry'] !== true && this.subagents.isHelper(thread)) {
+                    const detail = asRecord(params['error']);
+                    // The one failure of a helper that is not the helper's own business:
+                    // the plan limit is the account's, and the session is next (#382).
+                    if (!this.announceRateLimitRefusal(detail)) {
+                        log.warn('codex: a helper agent reported an error', {
+                            sessionId: this.spec.sessionId,
+                            message: maskString(str(detail['message']) ?? '').slice(0, 300),
+                        });
+                    }
+                }
+                return;
+            default:
+                return;
+        }
+    }
+    /** Keep an item's last state – approval params alone are too thin. */
+    rememberItem(item) {
+        const id = str(item['id']);
+        if (!id)
+            return;
+        this.items.set(id, item);
+        // Bound the cache: a long session would otherwise hold every item.
+        if (this.items.size > 400) {
+            const oldest = this.items.keys().next().value;
+            if (oldest !== undefined)
+                this.items.delete(oldest);
+        }
+    }
     onItem(method, params) {
         const item = asRecord(params['item']);
         const type = str(item['type']);
         const id = str(item['id']);
         if (!type)
             return;
-        if (id) {
-            this.items.set(id, item);
-            // Bound the cache: a long session would otherwise hold every item.
-            if (this.items.size > 400) {
-                const oldest = this.items.keys().next().value;
-                if (oldest !== undefined)
-                    this.items.delete(oldest);
-            }
-        }
+        this.rememberItem(item);
         const done = method === 'item/completed';
         switch (type) {
             case 'agentMessage': {
@@ -1556,6 +1699,17 @@ class CodexSession {
                 }
                 return;
             }
+            case 'collabAgentToolCall':
+            case 'subAgentActivity': {
+                // #382: helpers starting, being handed work and finishing. Counted, and
+                // deliberately NOT a feed row: a helper's `completed` arrives after this
+                // session's turn is over, and a tool event then would put a resting
+                // session back to «working» with no turn to end it (see
+                // `onHelperNotification`).
+                if (this.threadId)
+                    this.subagents.onItem(this.threadId, item);
+                return;
+            }
             case 'webSearch':
             case 'dynamicToolCall': {
                 if (!done) {
@@ -1741,6 +1895,29 @@ class CodexSession {
      * one turn.
      */
     static LIMIT_SETTLE_MS = 180_000;
+    /**
+     * The plan is spent: tell the API so it can arm its clock, and tell the
+     * person in the feed. Says nothing about whose turn it was.
+     *
+     * Split out of `noteRateLimitRefusal` for the refusals that belong to no turn
+     * of this session at all — a helper's (#382). The block is account-wide: the
+     * same account, the same window, and the next turn of the session will be
+     * refused too. Silence here was a false «your turn» over a plan that had run
+     * out, with nothing in the feed to explain it and no pause armed.
+     */
+    announceRateLimitRefusal(error) {
+        const blocked = this.rateLimitRefusal(error);
+        if (!blocked)
+            return false;
+        this.emitRateLimits(blocked);
+        this.emit({
+            type: 'notice',
+            level: 'warn',
+            text: 'Codex refused the turn: the plan limit is spent' +
+                (blocked.resetsAt ? `, and it lifts at ${describeResetTime(blocked.resetsAt)}.` : '.'),
+        });
+        return true;
+    }
     /**
      * The plan is spent — say so, and keep the session alive to be woken.
      *
@@ -1758,16 +1935,8 @@ class CodexSession {
      * feed of the session this was found on.
      */
     noteRateLimitRefusal(error) {
-        const blocked = this.rateLimitRefusal(error);
-        if (!blocked)
+        if (!this.announceRateLimitRefusal(error))
             return false;
-        this.emitRateLimits(blocked);
-        this.emit({
-            type: 'notice',
-            level: 'warn',
-            text: 'Codex refused the turn: the plan limit is spent' +
-                (blocked.resetsAt ? `, and it lifts at ${describeResetTime(blocked.resetsAt)}.` : '.'),
-        });
         /**
          * The flag is set ONLY while a turn is in flight, and that is not caution.
          *
@@ -1800,6 +1969,7 @@ class CodexSession {
                 // is still working — a steer would be aimed at a turn that has ended,
                 // and the next real turn would look like a turn already in flight.
                 this.activeTurnId = null;
+                this.subagents.endTurn();
                 this.emit({
                     type: 'turn_end',
                     ok: false,
@@ -1864,6 +2034,10 @@ class CodexSession {
             return;
         }
         this.activeTurnId = null;
+        // #382: what is still running, said BEFORE the ending – the supervisor
+        // decides «is this the person's turn» on the count it holds when `turn_end`
+        // arrives.
+        this.subagents.endTurn();
         // A held plan means the turn ended by proposing, not by finishing the work.
         if (this.heldPlan)
             return;
@@ -2310,6 +2484,8 @@ class CodexSession {
     finish() {
         this.stopped = true;
         this.clearLimitSettle();
+        this.subagents.close();
+        this.tray.close();
         this.output.end();
     }
 }

package/dist/supervisor.d.ts

@@ -1076,6 +1076,26 @@ export declare class Supervisor {
      */
     private armCompactionWatchdog;
     private clearCompactionWatchdog;
+    /**
+     * A card that interrupted a RESTING session has been answered: go back to
+     * rest instead of reporting a turn (#382).
+     *
+     * Which card it was does not matter — a Codex helper's approval, a Claude
+     * background subagent's, an ask either of them parked while the session was
+     * already the person's. What matters is that no turn of this session was
+     * running when the card went out, so there is no turn to go back to and
+     * nothing that would end one: on Codex the helper's own ending is explicitly
+     * not the session's, so «Working» stood until somebody typed.
+     *
+     * Only when the burst is over — both card sets empty — because answering one
+     * of three still leaves the session parked on the other two. The frame
+     * carries the background count like every other status report, so the badge
+     * and the Inbox see «resting, with helpers» rather than «your turn».
+     *
+     * Returns true when it handled the resolution, so the callers' «the human
+     * answered, bill again» branches stay out of it.
+     */
+    private restAfterCard;
     /**
      * Record how many subagents are alive, and say so when it matters (#236).
      *

package/dist/supervisor.js

@@ -3404,6 +3404,39 @@ export class Supervisor {
         clearTimeout(running.compactionWatchdog);
         delete running.compactionWatchdog;
     }
+    /**
+     * A card that interrupted a RESTING session has been answered: go back to
+     * rest instead of reporting a turn (#382).
+     *
+     * Which card it was does not matter — a Codex helper's approval, a Claude
+     * background subagent's, an ask either of them parked while the session was
+     * already the person's. What matters is that no turn of this session was
+     * running when the card went out, so there is no turn to go back to and
+     * nothing that would end one: on Codex the helper's own ending is explicitly
+     * not the session's, so «Working» stood until somebody typed.
+     *
+     * Only when the burst is over — both card sets empty — because answering one
+     * of three still leaves the session parked on the other two. The frame
+     * carries the background count like every other status report, so the badge
+     * and the Inbox see «resting, with helpers» rather than «your turn».
+     *
+     * Returns true when it handled the resolution, so the callers' «the human
+     * answered, bill again» branches stay out of it.
+     */
+    restAfterCard(running) {
+        const back = running.restBeforeCard;
+        if (!back)
+            return false;
+        if (running.openPermissions.size > 0 || running.openQuestions.size > 0)
+            return true;
+        // `reportStatus` clears the memory — the status it sends is the newest
+        // truth about this session, whatever it is.
+        this.reportStatus(running.descriptor.id, back, {
+            costUsd: running.costUsd,
+            activeMs: Supervisor.spentMs(running),
+        });
+        return true;
+    }
     /**
      * Record how many subagents are alive, and say so when it matters (#236).
      *
@@ -3817,6 +3850,8 @@ export class Supervisor {
                     source: event.source,
                     reason: event.reason,
                 });
+                if (this.restAfterCard(running))
+                    return;
                 if (event.source === 'user' &&
                     event.allow &&
                     running.lastReported === 'WAITING_PERMISSION') {
@@ -3844,6 +3879,11 @@ export class Supervisor {
                 // is the bug session 7 removed (five of the first twelve prod sessions
                 // died having spent their budget waiting for a human).
                 running.openQuestions.add(event.askId);
+                // #382, the same as a permission card: an ask from work that outlives
+                // the turn finds the session at rest, and the answer must put it back.
+                if (running.lastReported === 'WAITING_INPUT' || running.lastReported === 'REVIEW') {
+                    running.restBeforeCard = running.lastReported;
+                }
                 this.sendEvent(running, 'question', {
                     askId: event.askId,
                     questions: event.questions,
@@ -3872,6 +3912,8 @@ export class Supervisor {
                 // `openQuestions.size` matters: both agents can park several asks at
                 // once, and reporting RUNNING while another card is still waiting would
                 // bill a human's thinking time all over again (QA-106 M4).
+                if (this.restAfterCard(running))
+                    return;
                 if (event.source === 'user' &&
                     running.openQuestions.size === 0 &&
                     running.lastReported === 'WAITING_INPUT') {
@@ -7563,6 +7605,13 @@ export class Supervisor {
             // The API infers WAITING_PERMISSION from the event itself, so this never
             // goes through reportStatus — but the budget clock still has to stop, or
             // an ask-mode session bills every second the human spends reading the card.
+            //
+            // #382: remember what the card interrupted. A card from work that
+            // outlives the turn finds the session at rest, and the answer must put it
+            // back there rather than into a turn nobody is running.
+            if (running.lastReported === 'WAITING_INPUT' || running.lastReported === 'REVIEW') {
+                running.restBeforeCard = running.lastReported;
+            }
             running.lastReported = 'WAITING_PERMISSION';
             this.syncBudgetClock(running);
         }
@@ -7572,6 +7621,8 @@ export class Supervisor {
         const running = this.sessions.get(sessionId);
         if (running) {
             running.lastReported = status;
+            // #382: any status report is newer than the rest a card interrupted.
+            delete running.restBeforeCard;
             // Coming to rest ends the busy period the once-per-turn notices were
             // limited to: the next one is about a new answer and deserves saying.
             if (!Supervisor.MID_TURN_STATUSES.includes(status)) {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.64.1";
+export declare const RUNNER_VERSION = "0.65.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.64.1';
+export const RUNNER_VERSION = '0.65.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.64.1",
+  "version": "0.65.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",