@bridge4dev/runner 0.47.0 → 0.48.0

package/dist/adapters/codex.js

@@ -1157,10 +1157,13 @@ 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.
+            // #279. Kept out of `OPT_OUT_NOTIFICATIONS` on purpose, but NOT because
+            // it is rare: Codex sends it after every model request, as often as
+            // `thread/tokenUsage/updated` (production count 56 591 against 57 008,
+            // 05.09.2026 – #366). What keeps it off the wire is the supervisor's
+            // level gate, which forwards a snapshot only when it changed, carries a
+            // refusal (`blocked`), or is older than the resend floor. Opting the
+            // notification out here instead would silence the refusal too.
             case 'account/rateLimits/updated': {
                 this.onRateLimits(params);
                 return;

package/dist/levels.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Mirror of the `#region level-events-mirror` block in
+ * `packages/shared/src/constants/realtime.ts` – the DevBridge side is the
+ * source of truth, exactly like `agent-registry.ts` mirrors the agent registry
+ * and `protocol.ts` mirrors the API's wire types.
+ *
+ * Copied rather than imported on purpose: this package is published to npm on
+ * its own and installed by users who have no DevBridge workspace, so a
+ * `@devbridge/shared` import would make the published tarball unresolvable.
+ *
+ * CHECKED: `levels.test.ts` reads both files and compares the region between
+ * the markers character by character. Edit the shared file first, then paste
+ * the region here – nothing but the region, and nothing of the region left out.
+ */
+/**
+ * Level signals on the dev-session stream – frames that carry a whole current
+ * value rather than a step of the conversation (#366).
+ *
+ * `agent_tasks` (#113), `context_usage` and `rate_limits` (#279) are LEVELS:
+ * every frame replaces the previous one, so a dropped frame costs freshness and
+ * never correctness. In production they were 61 % of every Codex session's
+ * rows (57 008 + 56 591 of ~185 000, 05.09.2026) while drawing not one line in
+ * the transcript – and each one re-rendered the whole page. So they are treated
+ * differently at every hop, and this block is the one place that says how:
+ *
+ *  - the runner sends one only when the value moved (the thresholds below);
+ *  - the API publishes it as a META frame (no `id:`) and never stores a row;
+ *  - the dashboard keeps it beside the feed, never in it.
+ *
+ * Mirrored verbatim into `packages/runner/src/levels.ts` – the runner cannot
+ * import this package (it is published to npm on its own). `levels.test.ts`
+ * compares the two regions character by character.
+ */
+export declare const LEVEL_EVENT_TYPES: readonly ["agent_tasks", "context_usage", "rate_limits"];
+/**
+ * A context-meter move smaller than BOTH of these is not worth a frame. The
+ * same pair gates the API's mirror onto the session row, so the ring a reload
+ * draws from the row and the ring the live frame draws agree to the percent.
+ */
+export declare const CONTEXT_USAGE_MIN_DELTA_TOKENS = 2000;
+export declare const CONTEXT_USAGE_MIN_DELTA_RATIO = 0.01;
+/**
+ * An unchanged plan-usage snapshot is re-sent no more often than this. It is
+ * re-sent at all because the limits panel dates its figure by ARRIVAL
+ * («updated 12 min ago»): silence would read as staleness. Three minutes is
+ * the interval the Claude adapter already probes `/usage` at.
+ */
+export declare const RATE_LIMITS_RESEND_INTERVAL_MS: number;
+//# sourceMappingURL=levels.d.ts.map

package/dist/levels.js

@@ -0,0 +1,51 @@
+/**
+ * Mirror of the `#region level-events-mirror` block in
+ * `packages/shared/src/constants/realtime.ts` – the DevBridge side is the
+ * source of truth, exactly like `agent-registry.ts` mirrors the agent registry
+ * and `protocol.ts` mirrors the API's wire types.
+ *
+ * Copied rather than imported on purpose: this package is published to npm on
+ * its own and installed by users who have no DevBridge workspace, so a
+ * `@devbridge/shared` import would make the published tarball unresolvable.
+ *
+ * CHECKED: `levels.test.ts` reads both files and compares the region between
+ * the markers character by character. Edit the shared file first, then paste
+ * the region here – nothing but the region, and nothing of the region left out.
+ */
+// #region level-events-mirror
+/**
+ * Level signals on the dev-session stream – frames that carry a whole current
+ * value rather than a step of the conversation (#366).
+ *
+ * `agent_tasks` (#113), `context_usage` and `rate_limits` (#279) are LEVELS:
+ * every frame replaces the previous one, so a dropped frame costs freshness and
+ * never correctness. In production they were 61 % of every Codex session's
+ * rows (57 008 + 56 591 of ~185 000, 05.09.2026) while drawing not one line in
+ * the transcript – and each one re-rendered the whole page. So they are treated
+ * differently at every hop, and this block is the one place that says how:
+ *
+ *  - the runner sends one only when the value moved (the thresholds below);
+ *  - the API publishes it as a META frame (no `id:`) and never stores a row;
+ *  - the dashboard keeps it beside the feed, never in it.
+ *
+ * Mirrored verbatim into `packages/runner/src/levels.ts` – the runner cannot
+ * import this package (it is published to npm on its own). `levels.test.ts`
+ * compares the two regions character by character.
+ */
+export const LEVEL_EVENT_TYPES = ['agent_tasks', 'context_usage', 'rate_limits'];
+/**
+ * A context-meter move smaller than BOTH of these is not worth a frame. The
+ * same pair gates the API's mirror onto the session row, so the ring a reload
+ * draws from the row and the ring the live frame draws agree to the percent.
+ */
+export const CONTEXT_USAGE_MIN_DELTA_TOKENS = 2_000;
+export const CONTEXT_USAGE_MIN_DELTA_RATIO = 0.01;
+/**
+ * An unchanged plan-usage snapshot is re-sent no more often than this. It is
+ * re-sent at all because the limits panel dates its figure by ARRIVAL
+ * («updated 12 min ago»): silence would read as staleness. Three minutes is
+ * the interval the Claude adapter already probes `/usage` at.
+ */
+export const RATE_LIMITS_RESEND_INTERVAL_MS = 3 * 60 * 1000;
+// #endregion level-events-mirror
+//# sourceMappingURL=levels.js.map

package/dist/supervisor.d.ts

@@ -109,6 +109,13 @@ export interface SupervisorOptions {
      * firing over a working agent (QA-2026-08-16 M-4). Never set in production.
      */
     emptyTurnSettleMs?: number;
+    /**
+     * How long an unchanged plan-usage snapshot is held before it is re-sent
+     * (#366) – a test seam over `RATE_LIMITS_RESEND_INTERVAL_MS`, for the same
+     * reason `emptyTurnSettleMs` exists: the real floor is three minutes and this
+     * suite runs on real timers. Never set in production.
+     */
+    rateLimitsResendMs?: number;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -136,6 +143,7 @@ export declare class Supervisor {
     private static readonly EMPTY_TURN_SETTLE_MS;
     /** The window actually used — the constant, or a test's own shorter one. */
     private readonly emptyTurnSettleMs;
+    private readonly rateLimitsResendMs;
     /** A finished session's journal is kept this long for a late reconnect. */
     private static readonly JOURNAL_TTL_MS;
     /** Backstop: events the API will never accept must not pile up forever. */
@@ -525,6 +533,29 @@ export declare class Supervisor {
      * its timer runs out, and it must end in exactly the way it would have
      * ended immediately. A copy would be two behaviours one edit apart.
      */
+    /**
+     * The level gate for the context meter (#366).
+     *
+     * While a turn is open, a frame goes out only when the meter moved by at
+     * least one of the shared thresholds or the window itself changed; the
+     * newest held-back value is flushed right before `turn_end`, so the ring at
+     * rest is exact. Outside a turn every frame passes – there are only a handful
+     * (process start, a model change, and the Claude adapter's own measurement,
+     * which resolves AFTER `turn_end`), and each one is news.
+     */
+    private forwardContextUsage;
+    /** Send the value the gate was holding, if any – strictly before `turn_end`. */
+    private flushHeldContextUsage;
+    /**
+     * The level gate for plan usage (#366).
+     *
+     * A snapshot goes out when it is the first, when anything but `measuredAt`
+     * changed, when it carries a refusal (#258 – always, even twice in a row), or
+     * when the one last sent is older than the resend floor. The fingerprint is
+     * the whole payload minus the clock, so a field an adapter adds tomorrow is
+     * part of it without anybody remembering to list it here.
+     */
+    private forwardRateLimits;
     private completeTurn;
     /**
      * Move the session to the status a finished turn leaves it in.

package/dist/supervisor.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { log } from './log.js';
+import { CONTEXT_USAGE_MIN_DELTA_RATIO, CONTEXT_USAGE_MIN_DELTA_TOKENS, RATE_LIMITS_RESEND_INTERVAL_MS, } from './levels.js';
 import { claimAutoResume, clearAutoResume, pruneAutoResume } from './auto-resume.js';
 import { classifyFailure, isRepeatOfSameFailure, MAX_RETRIES_PER_SESSION, retryDelayMs, } from './adapters/error-policy.js';
 import { evaluateRecipeCommand, maskSecrets, maskString } from './policy.js';
@@ -58,6 +59,16 @@ function gitPolicyOf(descriptor) {
             : {}),
     };
 }
+function freshLevels() {
+    return {
+        contextSent: null,
+        contextHeld: null,
+        contextPassNext: false,
+        limitsSent: null,
+        sent: 0,
+        dropped: 0,
+    };
+}
 const LAUNCH_REFUSED = { ok: false, reason: 'refused' };
 export class Supervisor {
     ws;
@@ -85,6 +96,7 @@ export class Supervisor {
     static EMPTY_TURN_SETTLE_MS = 25_000;
     /** The window actually used — the constant, or a test's own shorter one. */
     emptyTurnSettleMs;
+    rateLimitsResendMs;
     /** A finished session's journal is kept this long for a late reconnect. */
     static JOURNAL_TTL_MS = 72 * 3_600_000;
     /** Backstop: events the API will never accept must not pile up forever. */
@@ -135,6 +147,7 @@ export class Supervisor {
         this.opts = opts;
         this.journals = opts.journals ?? new JournalStore();
         this.emptyTurnSettleMs = opts.emptyTurnSettleMs ?? Supervisor.EMPTY_TURN_SETTLE_MS;
+        this.rateLimitsResendMs = opts.rateLimitsResendMs ?? RATE_LIMITS_RESEND_INTERVAL_MS;
         this.verify = new VerifyRunner({
             enabled: opts.verifyEnabled !== false,
             onReport: (report) => {
@@ -743,6 +756,7 @@ export class Supervisor {
             lastReported: descriptor.status,
             costUsd: descriptor.costUsd,
             costBaseUsd: descriptor.costUsd,
+            levels: freshLevels(),
             stopRequested: false,
             parkRequested: false,
             pendingMessages: [],
@@ -1697,12 +1711,101 @@ export class Supervisor {
      * its timer runs out, and it must end in exactly the way it would have
      * ended immediately. A copy would be two behaviours one edit apart.
      */
+    /**
+     * The level gate for the context meter (#366).
+     *
+     * While a turn is open, a frame goes out only when the meter moved by at
+     * least one of the shared thresholds or the window itself changed; the
+     * newest held-back value is flushed right before `turn_end`, so the ring at
+     * rest is exact. Outside a turn every frame passes – there are only a handful
+     * (process start, a model change, and the Claude adapter's own measurement,
+     * which resolves AFTER `turn_end`), and each one is news.
+     */
+    forwardContextUsage(running, usedTokens, maxTokens) {
+        const levels = running.levels;
+        const frame = { usedTokens, maxTokens };
+        const last = levels.contextSent;
+        const turnOpen = running.lastReported === 'RUNNING';
+        const moved = last === null ? Number.POSITIVE_INFINITY : Math.abs(usedTokens - last.usedTokens);
+        const pass = last === null ||
+            last.maxTokens !== maxTokens ||
+            levels.contextPassNext ||
+            !turnOpen ||
+            moved >= CONTEXT_USAGE_MIN_DELTA_TOKENS ||
+            moved / maxTokens >= CONTEXT_USAGE_MIN_DELTA_RATIO;
+        // Only the newest value is worth keeping; whatever it replaces is gone.
+        if (levels.contextHeld !== null)
+            levels.dropped += 1;
+        if (!pass) {
+            levels.contextHeld = frame;
+            return;
+        }
+        levels.contextHeld = null;
+        levels.contextPassNext = false;
+        levels.contextSent = frame;
+        levels.sent += 1;
+        this.sendEvent(running, 'context_usage', frame);
+    }
+    /** Send the value the gate was holding, if any – strictly before `turn_end`. */
+    flushHeldContextUsage(running) {
+        const levels = running.levels;
+        const held = levels.contextHeld;
+        if (held === null)
+            return;
+        levels.contextHeld = null;
+        // A held value identical to the last one sent is not news – flushing it
+        // would add a frame to every turn and give back half the saving.
+        const sent = levels.contextSent;
+        if (sent !== null && sent.usedTokens === held.usedTokens && sent.maxTokens === held.maxTokens) {
+            return;
+        }
+        levels.contextSent = held;
+        levels.sent += 1;
+        this.sendEvent(running, 'context_usage', held);
+    }
+    /**
+     * The level gate for plan usage (#366).
+     *
+     * A snapshot goes out when it is the first, when anything but `measuredAt`
+     * changed, when it carries a refusal (#258 – always, even twice in a row), or
+     * when the one last sent is older than the resend floor. The fingerprint is
+     * the whole payload minus the clock, so a field an adapter adds tomorrow is
+     * part of it without anybody remembering to list it here.
+     */
+    forwardRateLimits(running, limits) {
+        const levels = running.levels;
+        const print = JSON.stringify({ ...limits, measuredAt: undefined });
+        const now = Date.now();
+        const last = levels.limitsSent;
+        const pass = last === null ||
+            Boolean(limits.blocked) ||
+            last.print !== print ||
+            now - last.at >= this.rateLimitsResendMs;
+        if (!pass) {
+            levels.dropped += 1;
+            return;
+        }
+        levels.limitsSent = { print, at: now };
+        levels.sent += 1;
+        this.sendEvent(running, 'rate_limits', { ...limits });
+    }
     completeTurn(running, descriptor, event) {
+        // #366: the ring at rest must be exact – the value the gate held back
+        // during the turn goes out first, so it is older than `turn_end` by seq.
+        this.flushHeldContextUsage(running);
         this.sendEvent(running, 'turn_end', {
             ok: event.ok,
             errorMessage: event.errorMessage,
             ...(event.aborted ? { aborted: true } : {}),
         });
+        // …and whatever the adapter measures once the turn is over (Claude does,
+        // asynchronously) is news, not a step of the same turn.
+        running.levels.contextPassNext = true;
+        log.info('supervisor: levels', {
+            sessionId: descriptor.id,
+            sent: running.levels.sent,
+            dropped: running.levels.dropped,
+        });
         // The session is already on its way out with a status that MEANS
         // something — a spent budget, a Stop, a teardown. A turn ending inside
         // that window is a consequence of it, and letting the line below
@@ -2221,17 +2324,17 @@ export class Supervisor {
                 });
                 return;
             case 'context_usage':
-                this.sendEvent(running, 'context_usage', {
-                    usedTokens: event.usedTokens,
-                    maxTokens: event.maxTokens,
-                });
+                // #366. A LEVEL: only a value that moved is worth a frame. The gate
+                // decides before `sendEvent`, so a dropped frame never spends a seq.
+                this.forwardContextUsage(running, event.usedTokens, 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
+            // snapshot, so the API keeps 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.
+            // #366: gated the same way as the context meter, see `forwardRateLimits`.
             case 'rate_limits':
-                this.sendEvent(running, 'rate_limits', { ...event.limits });
+                this.forwardRateLimits(running, event.limits);
                 return;
             case 'agent_tasks': {
                 // Ticket #113. A LEVEL signal: every frame carries the whole live set,
@@ -3444,6 +3547,7 @@ export class Supervisor {
                         lastReported: descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT',
                         costUsd: descriptor.costUsd,
                         costBaseUsd: descriptor.costUsd,
+                        levels: freshLevels(),
                         stopRequested: false,
                         parkRequested: false,
                         pendingMessages: [],

package/dist/version.d.ts

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

package/package.json

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