@bridge4dev/runner 0.41.1 → 0.42.1

package/dist/adapters/claude-usage.d.ts

@@ -0,0 +1,34 @@
+import type { AgentRateLimitWindow } from './types.js';
+export interface UsageRow {
+    key: 'five_hour' | 'seven_day';
+    /** «Weekly · Fable» for a per-model row; absent for the plain ones. */
+    label: string | null;
+    percent: number;
+}
+/**
+ * Every percentage `/usage` printed, in the order it printed them.
+ *
+ * The per-model weekly rows («Current week (Fable): 0% used») are kept rather
+ * than dropped — owner's call, 2026-08-15: on a plan where one model has its
+ * own weekly allowance, «50% of the week» is only half the answer.
+ *
+ * Deliberately forgiving: a line we cannot read is skipped, never thrown over.
+ */
+export declare function parseUsageText(text: string): UsageRow[];
+/**
+ * Merge fresh percentages into the windows we already know about.
+ *
+ * The RESET TIME is never taken from here — whatever the event said stays. A
+ * window the event has not mentioned yet is created so the first probe is not
+ * wasted, with no clock on it until the event supplies one.
+ */
+export declare function applyUsagePercentages(windows: AgentRateLimitWindow[], rows: UsageRow[]): AgentRateLimitWindow[];
+/**
+ * Run `/usage` in a throwaway process and return what it printed.
+ *
+ * `--output-format text` rather than the stream: we want the rendering, and the
+ * JSON wrapper would only have to be unwrapped again. Never throws — a probe
+ * that fails is a percentage we do not show, not a session that breaks.
+ */
+export declare function probeUsageText(binary: string, cwd: string, timeoutMs?: number): Promise<string | null>;
+//# sourceMappingURL=claude-usage.d.ts.map

package/dist/adapters/claude-usage.js

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { log } from '../log.js';
+/**
+ * How much of the plan is spent — read from the CLI's own `/usage` (#279).
+ *
+ * The machine-readable event (`rate_limit_event`) is the source of truth for
+ * WHEN a window resets, and the auto-pause clock is built on it alone. What it
+ * almost never carries is the PERCENTAGE, and that is the number the owner
+ * actually asked to see. `/usage` has it.
+ *
+ * Two things make this worth doing despite being text:
+ *
+ *  - it is FREE. Probed 2026-08-15: `total_cost_usd: 0`, `num_turns: 0`,
+ *    0 input and 0 output tokens, ~3.7s. It is a local command, not a request —
+ *    measuring the limit does not spend it.
+ *  - it can only ever affect a NUMBER ON A SCREEN. The reset time we schedule a
+ *    wake-up from never comes from here, so a wording change in a future CLI
+ *    costs us the percentage and nothing else. That is the exact failure #258
+ *    refused to accept for the clock, and the exact risk it is fine to take for
+ *    a label.
+ *
+ * The text, as of 2026-08-15:
+ *
+ *   Current session: 63% used · resets Aug 15, 10:39pm (Europe/Berlin)
+ *   Current week (all models): 50% used · resets Aug 19, 3:59pm (Europe/Berlin)
+ *   Current week (Fable): 0% used
+ */
+/** «Current session» is the five-hour window; every «Current week» is a weekly one. */
+const SESSION_LINE = /current session:\s*(\d+(?:\.\d+)?)%\s*used/i;
+const WEEK_LINE = /current week(?:\s*\(([^)]+)\))?:\s*(\d+(?:\.\d+)?)%\s*used/gi;
+const clamp = (raw) => {
+    if (raw === undefined)
+        return null;
+    const value = Number(raw);
+    return Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : null;
+};
+/**
+ * Every percentage `/usage` printed, in the order it printed them.
+ *
+ * The per-model weekly rows («Current week (Fable): 0% used») are kept rather
+ * than dropped — owner's call, 2026-08-15: on a plan where one model has its
+ * own weekly allowance, «50% of the week» is only half the answer.
+ *
+ * Deliberately forgiving: a line we cannot read is skipped, never thrown over.
+ */
+export function parseUsageText(text) {
+    const rows = [];
+    const session = clamp(SESSION_LINE.exec(text)?.[1]);
+    if (session !== null)
+        rows.push({ key: 'five_hour', label: null, percent: session });
+    WEEK_LINE.lastIndex = 0;
+    for (let match = WEEK_LINE.exec(text); match !== null; match = WEEK_LINE.exec(text)) {
+        const percent = clamp(match[2]);
+        if (percent === null)
+            continue;
+        const scope = (match[1] ?? '').trim();
+        // «all models» IS the weekly window; anything else is that model's own.
+        const isAll = scope === '' || /^all models$/i.test(scope);
+        rows.push({ key: 'seven_day', label: isAll ? null : `Weekly · ${scope}`, percent });
+    }
+    return rows;
+}
+/**
+ * Merge fresh percentages into the windows we already know about.
+ *
+ * The RESET TIME is never taken from here — whatever the event said stays. A
+ * window the event has not mentioned yet is created so the first probe is not
+ * wasted, with no clock on it until the event supplies one.
+ */
+export function applyUsagePercentages(windows, rows) {
+    // Keyed by window AND label: a per-model weekly row is its own line, not an
+    // overwrite of the plan-wide one.
+    const id = (window) => `${window.key}:${window.label ?? ''}`;
+    const merged = new Map(windows.map((window) => [id(window), { ...window }]));
+    for (const row of rows) {
+        const key = `${row.key}:${row.label ?? ''}`;
+        const existing = merged.get(key);
+        merged.set(key, {
+            key: row.key,
+            windowMinutes: existing?.windowMinutes ?? (row.key === 'five_hour' ? 300 : 10_080),
+            usedPercent: row.percent,
+            // The clock stays whatever the machine-readable event said — this file
+            // never sets it, so a wording change here can never move a wake-up.
+            resetsAt: existing?.resetsAt ?? null,
+            ...(existing?.status ? { status: existing.status } : {}),
+            ...(row.label ? { label: row.label } : {}),
+        });
+    }
+    return [...merged.values()].sort((a, b) => (a.windowMinutes ?? Number.MAX_SAFE_INTEGER) - (b.windowMinutes ?? Number.MAX_SAFE_INTEGER) ||
+        (a.label ?? '').localeCompare(b.label ?? ''));
+}
+/**
+ * Run `/usage` in a throwaway process and return what it printed.
+ *
+ * `--output-format text` rather than the stream: we want the rendering, and the
+ * JSON wrapper would only have to be unwrapped again. Never throws — a probe
+ * that fails is a percentage we do not show, not a session that breaks.
+ */
+export function probeUsageText(binary, cwd, timeoutMs = 20_000) {
+    return new Promise((resolve) => {
+        execFile(binary, ['-p', '/usage', '--output-format', 'text'], { cwd, timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+            if (error) {
+                log.debug('claude: /usage probe failed', { error: String(error) });
+                resolve(null);
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+//# sourceMappingURL=claude-usage.js.map

package/dist/adapters/claude.js

@@ -7,6 +7,10 @@ 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 { applyUsagePercentages, parseUsageText, probeUsageText } from './claude-usage.js';
+import { claudeCliPath } from '../agent-binary.js';
+/** How often `/usage` may be read. Free, but still a process. */
+const USAGE_PROBE_INTERVAL_MS = 3 * 60 * 1000;
 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
@@ -695,6 +699,55 @@ class ClaudeSession {
     rateLimitsAvailable = false;
     /** A refusal seen since the last turn ended, waiting to be reported with it. */
     limitBlockPending = false;
+    /** When `/usage` was last read, so a busy session does not spawn a process a second. */
+    usageProbedAt = 0;
+    /**
+     * The one key the window map is written under, from every source.
+     *
+     * Live 2026-08-15: the event wrote under the provider's raw name
+     * (`five_hour`) while the `/usage` merge wrote under `five_hour:` — so the
+     * same window arrived twice, once with the clock and once with the number,
+     * and the panel drew both rows. One scheme, one row.
+     */
+    static windowKey(key, label) {
+        return `${key}:${label ?? ''}`;
+    }
+    /**
+     * Read the percentages out of the CLI's own `/usage` (#279).
+     *
+     * Fire-and-forget, throttled, and free — a local command, not a request
+     * (probe 2026-08-15: zero tokens, zero turns, zero dollars). The live event
+     * gives us the clock and almost never the number; this gives the number and
+     * never touches the clock.
+     */
+    refreshUsage() {
+        if (this.stopped)
+            return;
+        if (this.usageProbedAt !== 0 && Date.now() - this.usageProbedAt < USAGE_PROBE_INTERVAL_MS) {
+            return;
+        }
+        const binary = claudeCliPath();
+        if (!binary)
+            return;
+        this.usageProbedAt = Date.now();
+        void probeUsageText(binary, this.spec.cwd)
+            .then((text) => {
+            if (!text || this.stopped)
+                return;
+            const rows = parseUsageText(text);
+            if (rows.length === 0)
+                return;
+            // A percentage proves a plan as surely as the event does.
+            this.rateLimitsAvailable = true;
+            const merged = applyUsagePercentages([...this.rateLimitWindows.values()], rows);
+            this.rateLimitWindows.clear();
+            for (const window of merged) {
+                this.rateLimitWindows.set(ClaudeSession.windowKey(window.key, window.label), window);
+            }
+            this.emitRateLimits();
+        })
+            .catch((error) => log.debug('claude: usage probe failed', { error: String(error) }));
+    }
     /** Read the flag and clear it: one refusal marks exactly one turn end. */
     consumeLimitBlock() {
         const blocked = this.limitBlockPending;
@@ -738,7 +791,7 @@ class ClaudeSession {
                 if (!window || typeof window.utilization !== 'number')
                     continue;
                 const key = rateWindowKey(name);
-                this.rateLimitWindows.set(name, {
+                this.rateLimitWindows.set(ClaudeSession.windowKey(key), {
                     key,
                     windowMinutes: RATE_WINDOW_MINUTES[key] ?? null,
                     usedPercent: clampPercent(window.utilization),
@@ -775,8 +828,8 @@ class ClaudeSession {
         // Keep whatever the previous event said about the percentage: the field
         // comes and goes between events about the same window, and dropping it on
         // the next silent one would make a number that was true flicker away.
-        const known = this.rateLimitWindows.get(name);
-        this.rateLimitWindows.set(name, {
+        const known = this.rateLimitWindows.get(ClaudeSession.windowKey(key));
+        this.rateLimitWindows.set(ClaudeSession.windowKey(key), {
             key,
             windowMinutes: RATE_WINDOW_MINUTES[key] ?? null,
             usedPercent: typeof utilization === 'number' ? clampPercent(utilization) : (known?.usedPercent ?? null),
@@ -1902,6 +1955,8 @@ class ClaudeSession {
                             // account has none — «this organization runs on its own key» is an
                             // answer the popup has to be able to give.
                             this.emitRateLimitsFromInit(msg);
+                            // #279: the percentages the event does not carry.
+                            this.refreshUsage();
                         }
                         else if (msg.subtype === 'status') {
                             const status = msg.status;
@@ -2057,6 +2112,9 @@ class ClaudeSession {
                                 // refused is not a turn that ran.
                                 ...(this.consumeLimitBlock() ? { limitBlocked: true } : {}),
                             });
+                            // #279: a turn just moved the plan, so the percentages are worth
+                            // re-reading — throttled inside, and free either way.
+                            this.refreshUsage();
                         }
                         else {
                             this.emit({
@@ -2065,6 +2123,7 @@ class ClaudeSession {
                                 errorMessage: failure,
                                 ...(this.consumeLimitBlock() ? { limitBlocked: true } : {}),
                             });
+                            this.refreshUsage();
                         }
                         break;
                     }

package/dist/adapters/codex.js

@@ -1385,8 +1385,22 @@ class CodexSession {
             if (usedPercent === undefined)
                 continue;
             const minutes = num(window['windowMinutes'] ?? window['window_minutes']) ?? null;
+            // Live 2026-08-15: Codex sent a percentage with NO length, so the label
+            // fell back to «Limit window» — true but useless. The slot itself carries
+            // the answer on every ChatGPT plan: `primary` is the short window,
+            // `secondary` the weekly one. Used only when the minutes are missing, so
+            // a provider that does state them still wins.
+            // Only when the length is ABSENT. A stated length we do not recognise is
+            // information — 43 200 minutes is a monthly window, and calling it «5
+            // hours» because it arrived first would be worse than admitting we have
+            // no name for it.
+            const key = minutes === null
+                ? slot === 'primary'
+                    ? 'five_hour'
+                    : 'seven_day'
+                : rateWindowKeyFromMinutes(minutes);
             windows.push({
-                key: rateWindowKeyFromMinutes(minutes),
+                key,
                 windowMinutes: minutes,
                 usedPercent: clampPercent(usedPercent),
                 resetsAt: str(window['resetsAt'] ?? window['resets_at']) ?? null,

package/dist/adapters/types.d.ts

@@ -162,6 +162,11 @@ export interface AgentRateLimitWindow {
     resetsAt: string | null;
     /** `allowed` · `allowed_warning` · `rejected`, when the provider says. */
     status?: string | null;
+    /**
+     * What to call this row when our own vocabulary is not enough — «Weekly ·
+     * Fable» for a model with its own weekly allowance (owner's call, #279).
+     */
+    label?: string | null;
 }
 /**
  * The account's plan usage, as one snapshot (#279, #258).

package/dist/version.d.ts

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

package/package.json

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