@bridge4dev/runner 0.63.0 → 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/checkpoints.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
+import { cleanGitEnv } from './environment.js';
 import { checkpointsDir } from './paths.js';
 import { EMPTY_TREE_SHA } from './gitops.js';
 import { isSecretPath } from './policy.js';
@@ -90,7 +91,7 @@ async function gitIn(cwd, ...args) {
         // The project's own environment must not leak in: a GIT_INDEX_FILE or
         // GIT_DIR inherited from a parent process would silently retarget every
         // command below at the wrong repository.
-        env: cleanEnv(),
+        env: cleanGitEnv(),
     });
     return stdout.replace(/\n$/, '');
 }
@@ -107,7 +108,7 @@ async function gitStore(store, worktreePath, indexFile, ...args) {
         timeout: GIT_TIMEOUT_MS,
         maxBuffer: 32 * 1024 * 1024,
         env: {
-            ...cleanEnv(),
+            ...cleanGitEnv(),
             GIT_DIR: store,
             GIT_WORK_TREE: worktreePath,
             GIT_INDEX_FILE: indexFile,
@@ -119,22 +120,13 @@ async function gitStore(store, worktreePath, indexFile, ...args) {
     });
     return stdout.replace(/\n$/, '');
 }
-function cleanEnv() {
-    const env = { ...process.env };
-    delete env['GIT_DIR'];
-    delete env['GIT_WORK_TREE'];
-    delete env['GIT_INDEX_FILE'];
-    delete env['GIT_OBJECT_DIRECTORY'];
-    delete env['GIT_ALTERNATE_OBJECT_DIRECTORIES'];
-    return env;
-}
 async function ensureStore(worktreePath) {
     const { store, objectDir } = await storeFor(worktreePath);
     if (!fs.existsSync(store)) {
         fs.mkdirSync(path.dirname(store), { recursive: true, mode: 0o700 });
         await execFileAsync('git', ['init', '--quiet', '--bare', store], {
             timeout: GIT_TIMEOUT_MS,
-            env: cleanEnv(),
+            env: cleanGitEnv(),
         });
         fs.chmodSync(store, 0o700);
     }
@@ -326,7 +318,7 @@ async function gitRefs(store, ...args) {
     const { stdout } = await execFileAsync('git', [...GIT_GLOBAL_ARGS, '--git-dir', store, ...args], {
         timeout: GIT_TIMEOUT_MS,
         maxBuffer: 32 * 1024 * 1024,
-        env: cleanEnv(),
+        env: cleanGitEnv(),
     });
     return stdout.replace(/\n$/, '');
 }

package/dist/environment.d.ts

@@ -20,6 +20,21 @@ export interface RunnerIdentity {
     isRoot: boolean;
 }
 export declare function runnerIdentity(): RunnerIdentity;
+/**
+ * The environment git must be run in, with the caller's own repository scrubbed
+ * out of it.
+ *
+ * A `GIT_DIR` or `GIT_INDEX_FILE` inherited from a parent process silently
+ * retargets every git command at a DIFFERENT repository — the runner is started
+ * by systemd, but a session's agent is not, and neither is a test. The restore
+ * points have run this way since #126; #417 needs the same guarantee for a much
+ * blunter reason: `git init` under an inherited `GIT_DIR` initialises somewhere
+ * else entirely and reports success.
+ *
+ * Here rather than in `checkpoints.ts`, where it was written, because it is now
+ * the answer to «how does this package run git» and has two callers.
+ */
+export declare function cleanGitEnv(): NodeJS.ProcessEnv;
 export interface PathAccess {
     path: string;
     exists: boolean;

package/dist/environment.js

@@ -19,6 +19,29 @@ export function runnerIdentity() {
     }
     return { user, uid, gid, home: os.homedir(), isRoot: uid === 0 };
 }
+/**
+ * The environment git must be run in, with the caller's own repository scrubbed
+ * out of it.
+ *
+ * A `GIT_DIR` or `GIT_INDEX_FILE` inherited from a parent process silently
+ * retargets every git command at a DIFFERENT repository — the runner is started
+ * by systemd, but a session's agent is not, and neither is a test. The restore
+ * points have run this way since #126; #417 needs the same guarantee for a much
+ * blunter reason: `git init` under an inherited `GIT_DIR` initialises somewhere
+ * else entirely and reports success.
+ *
+ * Here rather than in `checkpoints.ts`, where it was written, because it is now
+ * the answer to «how does this package run git» and has two callers.
+ */
+export function cleanGitEnv() {
+    const env = { ...process.env };
+    delete env['GIT_DIR'];
+    delete env['GIT_WORK_TREE'];
+    delete env['GIT_INDEX_FILE'];
+    delete env['GIT_OBJECT_DIRECTORY'];
+    delete env['GIT_ALTERNATE_OBJECT_DIRECTORIES'];
+    return env;
+}
 /** As root every access check passes, which is true and worth saying out loud. */
 function canAccess(target, mode) {
     try {

package/dist/git.d.ts

@@ -106,6 +106,42 @@ export interface PathValidation {
  * '/opt/ids'». That sentence is true and unactionable.
  */
 export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
+/**
+ * What became of «create this folder and put git in it» (#417).
+ *
+ * `created` and `exists` are separate answers on purpose: a folder that was
+ * already there is not a failure — the wizard simply goes on and binds it —
+ * while `created: false, exists: false` is never a success.
+ */
+export interface ProjectDirInit {
+    ok: boolean;
+    /** This call made the directory. */
+    created: boolean;
+    /** There was already a directory at this path when we looked. */
+    exists: boolean;
+    /** The branch the new repository is on, read back rather than assumed. */
+    branch?: string;
+    error?: string;
+}
+/**
+ * Create the project folder and initialise git in it, from the binding window
+ * (#417).
+ *
+ * Two things and no more: ONE directory — the last segment of the path, never a
+ * chain of parents — and `git init` with `main` as the branch. No first commit:
+ * an empty repository is a legitimate state (#137, and the runner has known how
+ * to work in one since 0.63.0), while an «Initial commit» nobody asked for is
+ * the thing that makes `git pull` from an existing remote refuse with
+ * «unrelated histories» later on.
+ *
+ * Its own refusal list, because `validateWorkspacePath` has none to share: that
+ * function asks «can the runner work here», which is a question about
+ * permissions, and every answer it gives is about reaching, reading and writing.
+ * «Should anything be created here at all» is a different question and this is
+ * the only place that asks it. The API cannot ask it either — it sees the
+ * runner's verdict and nothing of the machine — so the list lives here.
+ */
+export declare function initProjectDir(target: string): Promise<ProjectDirInit>;
 /**
  * The repository's main branch, read locally (ADR 0004).
  *