@bridge4dev/runner 0.40.0 → 0.41.0

package/dist/adapters/claude.js

@@ -6,6 +6,7 @@ import { log } from '../log.js';
 import { mcpConfigPath } from '../paths.js';
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, } from './types.js';
+import { clampPercent, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
 // Claude adapter over the Agent SDK. Three live-verified gotchas (plan §2):
 //  1. Bare tool names in `allowedTools` auto-approve BEFORE canUseTool — we
@@ -682,6 +683,93 @@ class ClaudeSession {
         })
             .catch((error) => log.warn('claude: context usage probe failed', { error: String(error) }));
     }
+    /**
+     * Plan windows as `system:init` reported them (#279).
+     *
+     * Kept so `rate_limit_event`, which speaks about ONE window at a time, has
+     * something to update rather than replace: an event about the five-hour
+     * window must not erase what we know about the weekly one.
+     */
+    rateLimitWindows = new Map();
+    ratePlanType = null;
+    rateLimitsAvailable = false;
+    /** A refusal seen since the last turn ended, waiting to be reported with it. */
+    limitBlockPending = false;
+    /** Read the flag and clear it: one refusal marks exactly one turn end. */
+    consumeLimitBlock() {
+        const blocked = this.limitBlockPending;
+        this.limitBlockPending = false;
+        return blocked;
+    }
+    emitRateLimits(blocked = null) {
+        this.emit({
+            type: 'rate_limits',
+            limits: {
+                blocked,
+                available: this.rateLimitsAvailable,
+                planType: this.ratePlanType,
+                measuredAt: new Date().toISOString(),
+                // Ordered by our own key, not by insertion: the popup lists the short
+                // window above the long one, and that must not depend on which one the
+                // CLI happened to mention first.
+                windows: [...this.rateLimitWindows.values()].sort((a, b) => (a.windowMinutes ?? Number.MAX_SAFE_INTEGER) -
+                    (b.windowMinutes ?? Number.MAX_SAFE_INTEGER)),
+            },
+        });
+    }
+    emitRateLimitsFromInit(msg) {
+        const init = msg;
+        this.rateLimitsAvailable = init.rate_limits_available === true;
+        this.ratePlanType = typeof init.subscription_type === 'string' ? init.subscription_type : null;
+        this.rateLimitWindows.clear();
+        const limits = init.rate_limits;
+        if (this.rateLimitsAvailable && limits && typeof limits === 'object') {
+            for (const [name, window] of Object.entries(limits)) {
+                if (!window || typeof window.utilization !== 'number')
+                    continue;
+                const key = rateWindowKey(name);
+                this.rateLimitWindows.set(name, {
+                    key,
+                    windowMinutes: RATE_WINDOW_MINUTES[key] ?? null,
+                    usedPercent: clampPercent(window.utilization),
+                    resetsAt: typeof window.resets_at === 'string' ? window.resets_at : null,
+                });
+            }
+        }
+        this.emitRateLimits();
+    }
+    onRateLimitEvent(msg) {
+        const info = msg.rate_limit_info;
+        if (!info || typeof info !== 'object')
+            return;
+        const utilization = info['utilization'];
+        // `rejected` is the whole subject of #258 and it is worth reporting even
+        // without a percentage: the refusal is the fact, the number is decoration.
+        // `allowed_warning` is NOT a refusal — the turn ran.
+        const refused = info['status'] === 'rejected';
+        if (typeof utilization !== 'number' && !refused)
+            return;
+        // A live event proves there IS a plan: the SDK only emits this for
+        // claude.ai subscriptions. An account that reached `system:init` before
+        // its profile scope resolved would otherwise stay `available: false`.
+        this.rateLimitsAvailable = true;
+        const name = typeof info['rateLimitType'] === 'string' ? info['rateLimitType'] : 'five_hour';
+        const key = rateWindowKey(name);
+        // `resetsAt` here is epoch SECONDS, unlike `resets_at` on init which is
+        // already ISO. Same fact, two encodings, one place that knows it.
+        const resetsAt = typeof info['resetsAt'] === 'number' ? new Date(info['resetsAt'] * 1000).toISOString() : null;
+        if (typeof utilization === 'number') {
+            this.rateLimitWindows.set(name, {
+                key,
+                windowMinutes: RATE_WINDOW_MINUTES[key] ?? null,
+                usedPercent: clampPercent(utilization),
+                resetsAt,
+            });
+        }
+        if (refused)
+            this.limitBlockPending = true;
+        this.emitRateLimits(refused ? { key, resetsAt } : null);
+    }
     /** Fire-and-forget capability refresh — never throws into the caller. */
     refreshCapabilities() {
         if (this.capabilitiesInFlight || this.stopped)
@@ -1792,6 +1880,11 @@ class ClaudeSession {
                             // The live model can differ from what we asked for (alias
                             // resolution, fallback) — refresh the pickers when it does.
                             this.adoptLiveModel(msg.model);
+                            // #279: the plan windows ride along on `system:init`, which is the
+                            // only place they arrive without asking. Emitted even when the
+                            // account has none — «this organization runs on its own key» is an
+                            // answer the popup has to be able to give.
+                            this.emitRateLimitsFromInit(msg);
                         }
                         else if (msg.subtype === 'status') {
                             const status = msg.status;
@@ -1819,6 +1912,14 @@ class ClaudeSession {
                         this.emit({ type: 'notice', level: 'info', text: 'Context cleared (/clear)' });
                         break;
                     }
+                    // #279: the SDK pushes this whenever the numbers move, so the popup
+                    // stays current without us polling anything. It carries ONE window —
+                    // whichever is closest to its ceiling — so it updates that window and
+                    // leaves the others as `system:init` reported them.
+                    case 'rate_limit_event': {
+                        this.onRateLimitEvent(msg);
+                        break;
+                    }
                     case 'assistant': {
                         // Ticket #186. A subagent's own prose is NOT this session's answer.
                         //
@@ -1929,10 +2030,24 @@ class ClaudeSession {
                             // A turn the user stopped is not a failed turn. Reporting it as
                             // one moved the session to FAILED, which is terminal — pressing
                             // Stop cost people the session they meant to keep.
-                            this.emit({ type: 'turn_end', ok: true, ...(aborted ? { aborted: true } : {}) });
+                            this.emit({
+                                type: 'turn_end',
+                                ok: true,
+                                ...(aborted ? { aborted: true } : {}),
+                                // #258: a refused turn can end EITHER way depending on where the
+                                // SDK gave up, so the flag is carried on both branches. The API
+                                // reads it to keep the streak counter honest — a turn that was
+                                // refused is not a turn that ran.
+                                ...(this.consumeLimitBlock() ? { limitBlocked: true } : {}),
+                            });
                         }
                         else {
-                            this.emit({ type: 'turn_end', ok: false, errorMessage: failure });
+                            this.emit({
+                                type: 'turn_end',
+                                ok: false,
+                                errorMessage: failure,
+                                ...(this.consumeLimitBlock() ? { limitBlocked: true } : {}),
+                            });
                         }
                         break;
                     }

package/dist/adapters/codex.js

@@ -6,6 +6,7 @@ import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, str } from './codex-protocol.js';
 import { truncate } from './claude.js';
 import { availableModes, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, } 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';
 // Codex adapter over `codex app-server` (stage C). The normalized AgentEvent
 // contract is unchanged, so the dashboard renders Codex sessions with the same
@@ -23,7 +24,6 @@ const OPT_OUT_NOTIFICATIONS = [
     'item/agentMessage/delta',
     'item/plan/delta',
     'item/commandExecution/outputDelta',
-    'account/rateLimits/updated',
 ];
 /**
  * `on-request` is the only policy that lets the agent ASK.
@@ -1117,6 +1117,14 @@ class CodexSession {
                 }
                 return;
             }
+            // #279. Removed from `OPT_OUT_NOTIFICATIONS` on purpose: it is not a
+            // delta stream — Codex sends it when a turn changes the account's usage,
+            // which is orders of magnitude rarer than the text deltas that list
+            // defends against.
+            case 'account/rateLimits/updated': {
+                this.onRateLimits(params);
+                return;
+            }
             case 'thread/settings/updated': {
                 const collab = asRecord(params['collaborationMode']);
                 const model = str(params['model']);
@@ -1351,6 +1359,82 @@ class CodexSession {
                 return;
         }
     }
+    /**
+     * Codex's plan windows → the shared shape (#279).
+     *
+     * Codex describes a window by its LENGTH (`windowMinutes: 300`) where Claude
+     * names it, and calls them `primary` / `secondary` rather than by duration —
+     * so the position in the snapshot tells us nothing and the minutes tell us
+     * everything. `rate-limits.ts` owns that mapping for every adapter.
+     *
+     * Both spellings are accepted for each field. The app-server bindings are
+     * camelCase, the Rust struct behind them is snake_case, and this adapter has
+     * been bitten before by bindings that understate what the wire actually
+     * carries (see the note at the top of this file). Reading both costs one
+     * `??` and removes a whole class of «works until Codex 0.14» failure.
+     */
+    /** The last snapshot, kept so a refusal can borrow its reset time (#258). */
+    rateLimitWindows = [];
+    ratePlanType = null;
+    onRateLimits(params) {
+        const snapshot = asRecord(params['rateLimits'] ?? params['rate_limits'] ?? params);
+        const windows = [];
+        for (const slot of ['primary', 'secondary']) {
+            const window = asRecord(snapshot[slot]);
+            const usedPercent = num(window['usedPercent'] ?? window['used_percent']);
+            if (usedPercent === undefined)
+                continue;
+            const minutes = num(window['windowMinutes'] ?? window['window_minutes']) ?? null;
+            windows.push({
+                key: rateWindowKeyFromMinutes(minutes),
+                windowMinutes: minutes,
+                usedPercent: clampPercent(usedPercent),
+                resetsAt: str(window['resetsAt'] ?? window['resets_at']) ?? null,
+            });
+        }
+        this.rateLimitWindows = windows.sort((a, b) => (a.windowMinutes ?? Number.MAX_SAFE_INTEGER) - (b.windowMinutes ?? Number.MAX_SAFE_INTEGER));
+        this.ratePlanType = str(snapshot['planType'] ?? snapshot['plan_type']) ?? null;
+        this.emitRateLimits();
+    }
+    emitRateLimits(blocked = null) {
+        // An empty snapshot is «no plan», not «nothing happened»: Codex sends this
+        // for API-key accounts too, and the popup has to be able to say so.
+        this.emit({
+            type: 'rate_limits',
+            limits: {
+                blocked,
+                available: this.rateLimitWindows.length > 0,
+                planType: this.ratePlanType,
+                measuredAt: new Date().toISOString(),
+                windows: this.rateLimitWindows,
+            },
+        });
+    }
+    /**
+     * Was this failure a plan refusal — and if so, when does it lift? (#258)
+     *
+     * Matched on the machine-readable markers Codex carries (`rateLimitReached`,
+     * `usage_limit_reached`, `rate_limit_reached_type`) rather than on the
+     * sentence shown to a human: the wording changes between releases, and #258
+     * asks explicitly that a CLI update must never produce a WRONG wake-up.
+     *
+     * The reset time is taken from the last snapshot's fullest window, not from
+     * the error. If no snapshot has ever arrived, the refusal is still reported —
+     * with `resetsAt: null`, on which the API declines to schedule anything and
+     * calls a human instead. Guessing a time here is the one outcome worth
+     * avoiding: waking early burns a retry and changes nothing.
+     */
+    rateLimitRefusal(error) {
+        const haystack = JSON.stringify(error).toLowerCase();
+        const refused = haystack.includes('ratelimitreached') ||
+            haystack.includes('rate_limit_reached') ||
+            haystack.includes('usage_limit_reached') ||
+            haystack.includes('usagelimitreached');
+        if (!refused)
+            return null;
+        const fullest = this.rateLimitWindows.reduce((worst, window) => worst === null || window.usedPercent > worst.usedPercent ? window : worst, null);
+        return { key: fullest?.key ?? 'other', resetsAt: fullest?.resetsAt ?? null };
+    }
     onTurnCompleted(params) {
         const turn = asRecord(params['turn']);
         const status = str(turn['status']);
@@ -1366,10 +1450,22 @@ class CodexSession {
             return;
         if (status === 'failed') {
             const error = asRecord(turn['error']);
+            // Ticket #258. Codex says «you were refused»; it does NOT have to say
+            // when the refusal lifts, because `account/rateLimits/updated` has been
+            // telling us that all along. So the error only has to be recognised, and
+            // the clock comes from the last snapshot — which also means a change in
+            // the error's wording costs us the auto-pause, never a wrong wake-up.
+            const blocked = this.rateLimitRefusal(error);
+            if (blocked)
+                this.emitRateLimits(blocked);
             this.emit({
                 type: 'turn_end',
                 ok: false,
                 errorMessage: maskString(str(error['message']) ?? 'The Codex turn failed').slice(0, 500),
+                // Without this the session goes FAILED — terminal — and the pause armed
+                // one line earlier would ring into a dead row and throw the person's
+                // queued words away instead of sending them.
+                ...(blocked ? { limitBlocked: true } : {}),
             });
             return;
         }

package/dist/adapters/rate-limits.d.ts

@@ -0,0 +1,40 @@
+import type { AgentRateLimitWindow } from './types.js';
+/**
+ * Plan-window normalisation shared by every adapter (#279, #258).
+ *
+ * It lives in its own file rather than inside one adapter because the two CLIs
+ * describe the same fact in two different vocabularies — Claude names its
+ * windows, Codex measures them in minutes — and the owner intends to add more
+ * providers. One place decides what a window is called, so a third adapter has
+ * a table to join rather than a convention to guess.
+ */
+/** How long each named window is. The dashboard writes its label from this. */
+export declare const RATE_WINDOW_MINUTES: Record<AgentRateLimitWindow['key'], number | null>;
+/**
+ * A provider's own window name → ours.
+ *
+ * Claude has five names for the weekly window (`seven_day`, `seven_day_opus`,
+ * `seven_day_sonnet`, `seven_day_overage_included`, `seven_day_oauth_apps`) and
+ * they are all seven days; `startsWith` keeps a new suffix from silently
+ * becoming `other` on the next SDK release. Anything genuinely unknown stays
+ * `other` — a window we cannot name is still a window worth showing.
+ */
+export declare function rateWindowKey(providerName: string): AgentRateLimitWindow['key'];
+/**
+ * Minutes → our key, for providers that describe a window by its length.
+ *
+ * Exact matches only. «About five hours» is not a five-hour window, and a
+ * provider that reports 360 minutes means something we have no label for yet —
+ * `other` carries its length through and the dashboard says «6 часов» rather
+ * than mislabelling it.
+ */
+export declare function rateWindowKeyFromMinutes(minutes: number | null): AgentRateLimitWindow['key'];
+/**
+ * 0–100, always.
+ *
+ * A percentage out of range is not worth a thrown error — it is worth not
+ * being drawn as a 340%-full ring. NaN and infinities collapse to 0, which
+ * reads as «nothing spent» and is the safe end: it never invents a warning.
+ */
+export declare function clampPercent(value: number): number;
+//# sourceMappingURL=rate-limits.d.ts.map

package/dist/adapters/rate-limits.js

@@ -0,0 +1,59 @@
+/**
+ * Plan-window normalisation shared by every adapter (#279, #258).
+ *
+ * It lives in its own file rather than inside one adapter because the two CLIs
+ * describe the same fact in two different vocabularies — Claude names its
+ * windows, Codex measures them in minutes — and the owner intends to add more
+ * providers. One place decides what a window is called, so a third adapter has
+ * a table to join rather than a convention to guess.
+ */
+/** How long each named window is. The dashboard writes its label from this. */
+export const RATE_WINDOW_MINUTES = {
+    five_hour: 300,
+    seven_day: 10_080,
+    other: null,
+};
+/**
+ * A provider's own window name → ours.
+ *
+ * Claude has five names for the weekly window (`seven_day`, `seven_day_opus`,
+ * `seven_day_sonnet`, `seven_day_overage_included`, `seven_day_oauth_apps`) and
+ * they are all seven days; `startsWith` keeps a new suffix from silently
+ * becoming `other` on the next SDK release. Anything genuinely unknown stays
+ * `other` — a window we cannot name is still a window worth showing.
+ */
+export function rateWindowKey(providerName) {
+    if (providerName === 'five_hour')
+        return 'five_hour';
+    if (providerName.startsWith('seven_day'))
+        return 'seven_day';
+    return 'other';
+}
+/**
+ * Minutes → our key, for providers that describe a window by its length.
+ *
+ * Exact matches only. «About five hours» is not a five-hour window, and a
+ * provider that reports 360 minutes means something we have no label for yet —
+ * `other` carries its length through and the dashboard says «6 часов» rather
+ * than mislabelling it.
+ */
+export function rateWindowKeyFromMinutes(minutes) {
+    if (minutes === RATE_WINDOW_MINUTES.five_hour)
+        return 'five_hour';
+    if (minutes === RATE_WINDOW_MINUTES.seven_day)
+        return 'seven_day';
+    return 'other';
+}
+/**
+ * 0–100, always.
+ *
+ * A percentage out of range is not worth a thrown error — it is worth not
+ * being drawn as a 340%-full ring. NaN and infinities collapse to 0, which
+ * reads as «nothing spent» and is the safe end: it never invents a warning.
+ */
+export function clampPercent(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(100, Math.max(0, value));
+}
+//# sourceMappingURL=rate-limits.js.map

package/dist/adapters/types.d.ts

@@ -135,6 +135,55 @@ export interface AgentTask {
     /** Present only with `agentProgressSummaries`: «Analyzing the auth module». */
     summary?: string;
 }
+/**
+ * One plan window — «31% of the five hours is spent, it resets at 18:50».
+ *
+ * `key` is ours, not either CLI's. Claude names its windows, Codex describes
+ * them by length in minutes, and a third provider will do a third thing; the
+ * dashboard needs one vocabulary to write a label in. `other` is not a failure
+ * — it is a window we have no name for yet, and `windowMinutes` is what lets
+ * the dashboard still say something true about it («7 дней», «30 дней») rather
+ * than dropping it.
+ */
+export interface AgentRateLimitWindow {
+    key: 'five_hour' | 'seven_day' | 'other';
+    /** Length of the window, when the provider states it. */
+    windowMinutes: number | null;
+    /** 0–100. What is SPENT, not what is left — both CLIs report it that way. */
+    usedPercent: number;
+    /** Absolute moment, ISO 8601. Null when the provider did not say. */
+    resetsAt: string | null;
+}
+/**
+ * The account's plan usage, as one snapshot (#279, #258).
+ *
+ * `available: false` is a real answer, not an error: an organization running on
+ * its own API key, Bedrock or Vertex has no plan windows at all, and the popup
+ * must say so rather than draw zeros.
+ */
+export interface AgentRateLimits {
+    available: boolean;
+    /** `max`, `pro`, … exactly as the CLI names it. Null when unknown. */
+    planType: string | null;
+    /** When the snapshot was taken, on the RUNNER's clock, ISO 8601. */
+    measuredAt: string;
+    windows: AgentRateLimitWindow[];
+    /**
+     * Set only when the provider REFUSED a turn — ticket #258.
+     *
+     * The difference from a window at 100% is that this turn did not run: the
+     * words the person sent were not answered, and something has to send them
+     * again. A full window is a warning; this is an event.
+     *
+     * `resetsAt` may be null when the provider refuses without saying when it
+     * will stop — the API then declines to schedule a wake-up rather than guess a
+     * time, because waking early burns the retry for nothing.
+     */
+    blocked: {
+        key: AgentRateLimitWindow['key'];
+        resetsAt: string | null;
+    } | null;
+}
 /** Everything the dashboard needs to render agent controls, live from the agent. */
 export interface AgentCapabilities {
     models: ModelOption[];
@@ -353,6 +402,24 @@ export type AgentEvent = {
     usedTokens: number;
     maxTokens: number;
 }
+/**
+ * How much of the SUBSCRIPTION is left — tickets #279 and #258.
+ *
+ * Deliberately not shaped like either CLI. Claude names its windows
+ * (`five_hour`, `seven_day`), Codex describes them by length
+ * (`window_minutes: 300`), and the owner intends to add further providers
+ * (Gemini) — so the wire form is «a list of windows, each with a percentage
+ * and a reset moment», and every adapter normalises into it. A new provider
+ * adds a branch in its own adapter and nothing else.
+ *
+ * NOT the same thing as `context_usage`: that is how full the model's
+ * context window is for THIS session, this is how much of the account's plan
+ * is spent across every session on the machine.
+ */
+ | {
+    type: 'rate_limits';
+    limits: AgentRateLimits;
+}
 /**
  * Everything running beside the conversation, right now (ticket #113).
  *
@@ -387,6 +454,17 @@ export type AgentEvent = {
      * as work the agent completed.
      */
     aborted?: boolean;
+    /**
+     * The plan refused this turn — it never ran (#258).
+     *
+     * Reported so the supervisor does NOT file the session as FAILED. That
+     * status is terminal, and a terminal session cannot be woken: the pause
+     * we just armed would ring into a dead row, cancel the words the person
+     * had queued and log «the session ended before its pause was up». The
+     * turn genuinely did not succeed, but the session is fine — it is waiting
+     * for a window to open, which is what «waiting» means.
+     */
+    limitBlocked?: boolean;
 } | {
     type: 'error';
     message: string;

package/dist/supervisor.js

@@ -1355,6 +1355,17 @@ export class Supervisor {
                         activeMs: Supervisor.spentMs(running),
                     });
                 }
+                else if (event.limitBlocked) {
+                    // #258. The plan refused this turn — it never ran, so the session has
+                    // not failed at anything: it is waiting for a window to open, and the
+                    // API has just armed a clock to wake it. FAILED is terminal, and a
+                    // terminal session cannot be woken — the pause would ring into a dead
+                    // row and cancel the words the person queued behind it.
+                    this.reportStatus(descriptor.id, descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW', {
+                        costUsd: running.costUsd,
+                        activeMs: Supervisor.spentMs(running),
+                    });
+                }
                 else {
                     this.reportStatus(descriptor.id, 'FAILED', {
                         costUsd: running.costUsd,
@@ -1561,6 +1572,13 @@ export class Supervisor {
                     maxTokens: event.maxTokens,
                 });
                 return;
+            // #279. A LEVEL signal like `agent_tasks`: every frame carries the whole
+            // snapshot, so the API stores what arrived rather than merging, and a
+            // dropped frame costs freshness, never correctness. Account-wide, not
+            // session-wide — the API files it under the SERVER, not this session.
+            case 'rate_limits':
+                this.sendEvent(running, 'rate_limits', { ...event.limits });
+                return;
             case 'agent_tasks':
                 // Ticket #113. A LEVEL signal: every frame carries the whole live set,
                 // so the dashboard replaces rather than reconciles and a dropped frame

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.40.0";
+export declare const RUNNER_VERSION = "0.41.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.40.0';
+export const RUNNER_VERSION = '0.41.0';
 //# sourceMappingURL=version.js.map

package/package.json

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