@aragon-agent/cli 0.5.8 → 0.5.9

package/dist/config/schema.js

@@ -6,7 +6,7 @@
  * invariant).
  */
 import { isAbsolute } from 'node:path';
-import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, } from '@aragon-agent/core';
+import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_RETRY_POLICY, MIN_MAX_OUTPUT_TOKENS, RETRY_LIMITS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
 import { TEAM_LIMITS } from '../team/limits.js';
 // ---------------------------------------------------------------------------
@@ -213,6 +213,46 @@ function clampInt(v, fallback, range) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(range.max, Math.max(range.min, n));
 }
+/**
+ * `clampInt` for a key whose range legitimately includes ZERO.
+ *
+ * `clampInt` delegates to `coercePositiveInt`, which returns the FALLBACK for
+ * `n <= 0` — so a range whose floor is `0` cannot express `0` through it, and the
+ * value silently becomes the default. That trap is invisible at the call site and
+ * is what `retry.maxRetries` needs this helper for: `0` is that key's documented
+ * floor and its kill switch, and four documented controls send it
+ * (`/retry max 0`, `--retry-max 0`, `ARAGON_RETRY_MAX=0`,
+ * `aragon config set retry.maxRetries 0`). Through `clampInt` all four would set
+ * the MAXIMUM instead of the minimum, with no error anywhere.
+ *
+ * Own coercion: `Number.parseInt`, reject only non-finite and negative, then
+ * floor and clamp.
+ */
+function clampIntAllowingZero(v, fallback, range) {
+    if (v === null || v === undefined || v === '')
+        return clampToRange(fallback, range);
+    const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
+    if (!Number.isFinite(n) || n < 0)
+        return clampToRange(fallback, range);
+    return clampToRange(Math.floor(n), range);
+}
+/**
+ * `clampInt` for a key that is legitimately a FLOAT.
+ *
+ * `coercePositiveInt` floors, and `2.5` is a legitimate backoff factor — the same
+ * coercion trap `clampIntAllowingZero` above closes for `0`, one type over.
+ */
+function clampNumber(v, fallback, range) {
+    if (v === null || v === undefined || v === '')
+        return clampToRange(fallback, range);
+    const n = typeof v === 'number' ? v : Number.parseFloat(String(v));
+    if (!Number.isFinite(n))
+        return clampToRange(fallback, range);
+    return clampToRange(n, range);
+}
+function clampToRange(n, range) {
+    return Math.min(range.max, Math.max(range.min, n));
+}
 function stringArray(v, fallback) {
     if (!Array.isArray(v))
         return fallback;
@@ -380,12 +420,169 @@ export function clampTodoConfig(raw) {
         followThrough: followMode(src.followThrough, DEFAULT_TODO_CONFIG.followThrough),
     };
 }
+export const DEFAULT_RETRY_CONFIG = {
+    enabled: true,
+    maxRetries: DEFAULT_RETRY_POLICY.maxRetries,
+    initialDelayMs: DEFAULT_RETRY_POLICY.initialDelayMs,
+    maxDelayMs: DEFAULT_RETRY_POLICY.maxDelayMs,
+    multiplier: DEFAULT_RETRY_POLICY.multiplier,
+    jitter: DEFAULT_RETRY_POLICY.jitter,
+    respectRetryAfter: DEFAULT_RETRY_POLICY.respectRetryAfter,
+    maxElapsedMs: DEFAULT_RETRY_POLICY.maxElapsedMs,
+    onPartialStream: DEFAULT_RETRY_POLICY.onPartialStream,
+};
+/**
+ * `hardMaxRetries` re-exported rather than re-spelled, for the reason
+ * `HARD_MAX_SUBAGENTS` records: the ceiling is enforced in TWO places — here on
+ * the config value, and again by `normalizePolicy` inside the engine — and two
+ * copies of the same 20 is exactly how a hand-edited `config.json` ends up able
+ * to raise a ceiling the mechanism fixed.
+ */
+export const HARD_MAX_RETRIES = RETRY_LIMITS.hardMaxRetries;
+/** FLOOR 0 — and `clampIntAllowingZero` is what makes that reachable. */
+const RETRY_MAX_RANGE = { min: 0, max: HARD_MAX_RETRIES };
+const RETRY_INITIAL_DELAY_RANGE = { min: 100, max: 30_000 };
+const RETRY_MAX_DELAY_RANGE = { min: 1000, max: RETRY_LIMITS.absoluteMaxDelayMs };
+const RETRY_MULTIPLIER_RANGE = { min: 1, max: 5 };
+const RETRY_ELAPSED_RANGE = { min: 10_000, max: 1_800_000 };
+/**
+ * THE single gate for every retry-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those record: hardening only the read path leaves a bad value on
+ * disk that reverts to the default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Three invariants live inside the gate:
+ *
+ *  - `maxDelayMs = max(maxDelayMs, initialDelayMs)` — a ceiling under the floor
+ *    makes the ladder a flat line and the countdown a lie.
+ *  - `multiplier` goes through `clampNumber`, not `clampInt`: `2.5` is a
+ *    legitimate factor and `coercePositiveInt` would floor it to 2.
+ *  - `maxRetries` goes through `clampIntAllowingZero`. THIS IS THE ONE THAT SHIPS
+ *    BROKEN WITHOUT IT (R-16): `clampInt` returns the fallback for `n <= 0`, so
+ *    `clampRetryConfig({ maxRetries: 0 })` would yield 10 — the maximum instead
+ *    of the minimum, silently, for the key that gates the whole feature.
+ *
+ * `maxElapsedMs` intentionally keeps plain `clampInt`: its floor is 10 000, so it
+ * has no `0` to express.
+ */
+export function clampRetryConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const initialDelayMs = clampInt(src.initialDelayMs, DEFAULT_RETRY_CONFIG.initialDelayMs, RETRY_INITIAL_DELAY_RANGE);
+    const maxDelayMs = Math.max(initialDelayMs, clampInt(src.maxDelayMs, DEFAULT_RETRY_CONFIG.maxDelayMs, RETRY_MAX_DELAY_RANGE));
+    return {
+        enabled: bool(src.enabled, DEFAULT_RETRY_CONFIG.enabled),
+        maxRetries: clampIntAllowingZero(src.maxRetries, DEFAULT_RETRY_CONFIG.maxRetries, RETRY_MAX_RANGE),
+        initialDelayMs,
+        maxDelayMs,
+        multiplier: clampNumber(src.multiplier, DEFAULT_RETRY_CONFIG.multiplier, RETRY_MULTIPLIER_RANGE),
+        jitter: bool(src.jitter, DEFAULT_RETRY_CONFIG.jitter),
+        respectRetryAfter: bool(src.respectRetryAfter, DEFAULT_RETRY_CONFIG.respectRetryAfter),
+        maxElapsedMs: clampInt(src.maxElapsedMs, DEFAULT_RETRY_CONFIG.maxElapsedMs, RETRY_ELAPSED_RANGE),
+        onPartialStream: bool(src.onPartialStream, DEFAULT_RETRY_CONFIG.onPartialStream),
+    };
+}
+/**
+ * `RetryConfig` (user intent) -> `RetryPolicy` (engine policy), or `null` for
+ * "the user said no".
+ *
+ * `null` rather than a policy with `maxRetries: 0` because `ProviderRegistry`
+ * short-circuits on a null policy and returns the adapter's iterator DIRECTLY —
+ * an opted-out session is then allocation-identical to a pre-feature build.
+ *
+ * TOTAL, AND IT ACCEPTS A MISSING SECTION. `loadConfig` always supplies one, but
+ * a `CliConfig` built by hand — every controller test in this package does exactly
+ * that, and so would an embedder — legitimately omits it, and a `TypeError` from a
+ * pure translation function is the wrong way to find out. Routing through
+ * `clampRetryConfig` also means an out-of-range hand-built value can never reach
+ * the engine, which is the same "one gate, both directions" rule every other
+ * section in this file follows.
+ */
+export function toRetryPolicy(cfg) {
+    const safe = clampRetryConfig(cfg);
+    if (!safe.enabled || safe.maxRetries <= 0)
+        return null;
+    return {
+        maxRetries: safe.maxRetries,
+        initialDelayMs: safe.initialDelayMs,
+        maxDelayMs: safe.maxDelayMs,
+        multiplier: safe.multiplier,
+        jitter: safe.jitter,
+        respectRetryAfter: safe.respectRetryAfter,
+        maxElapsedMs: safe.maxElapsedMs,
+        onPartialStream: safe.onPartialStream,
+    };
+}
+export const DEFAULT_FAST_CONFIG = {
+    // R-d, and the one default in this file that is a REQUIREMENT rather than a
+    // judgement: a feature that silently spends money on a second provider is not
+    // a default (D-3).
+    enabled: false,
+    provider: '',
+    model: '',
+    baseUrl: '',
+    thinkingLevel: 'off',
+    delegate: true,
+    review: true,
+    reviewEveryTurns: 5,
+    reviewContextTurns: 3,
+    reviewMaxChars: 280,
+    // 40 is roughly 200 reviewed turns at the default cadence: comfortably past a
+    // full working session, short of a runaway (D-H2).
+    reviewMaxPerSession: 40,
+};
+const REVIEW_EVERY_RANGE = { min: 1, max: 50 };
+const REVIEW_CONTEXT_RANGE = { min: 1, max: 10 };
+const REVIEW_CHARS_RANGE = { min: 80, max: 600 };
+/** No "unlimited" sentinel: a magic `0` reads as "disabled" to the next person
+ *  who meets it, and 500 is already past any session a human sits through. */
+const REVIEW_SESSION_RANGE = { min: 1, max: 500 };
+/** Trim a string field, falling back when the value is not a string at all. */
+function text(v, fallback) {
+    return typeof v === 'string' ? v.trim() : fallback;
+}
+/**
+ * THE single gate for every fast-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those four record: hardening only the read path leaves a bad
+ * value on disk that reverts to the default on every launch, which presents to
+ * the user as "my setting won't stick".
+ *
+ * `provider` is CLAMPED TO `''` rather than rejected when it names something
+ * with no adapter. `''` means "inherit the main provider", which is the safe
+ * reading of a typo — and `resolveFastTier` reports `no_adapter` for the case a
+ * user really did configure a dead vendor as the MAIN one.
+ */
+export function clampFastConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const provider = text(src.provider, DEFAULT_FAST_CONFIG.provider);
+    return {
+        enabled: bool(src.enabled, DEFAULT_FAST_CONFIG.enabled),
+        provider: provider.length === 0 || isAdapterProvider(provider) ? provider : '',
+        model: text(src.model, DEFAULT_FAST_CONFIG.model),
+        baseUrl: text(src.baseUrl, DEFAULT_FAST_CONFIG.baseUrl),
+        thinkingLevel: clampThinkingLevel(src.thinkingLevel, DEFAULT_FAST_CONFIG.thinkingLevel),
+        delegate: bool(src.delegate, DEFAULT_FAST_CONFIG.delegate),
+        review: bool(src.review, DEFAULT_FAST_CONFIG.review),
+        reviewEveryTurns: clampInt(src.reviewEveryTurns, DEFAULT_FAST_CONFIG.reviewEveryTurns, REVIEW_EVERY_RANGE),
+        reviewContextTurns: clampInt(src.reviewContextTurns, DEFAULT_FAST_CONFIG.reviewContextTurns, REVIEW_CONTEXT_RANGE),
+        reviewMaxChars: clampInt(src.reviewMaxChars, DEFAULT_FAST_CONFIG.reviewMaxChars, REVIEW_CHARS_RANGE),
+        reviewMaxPerSession: clampInt(src.reviewMaxPerSession, DEFAULT_FAST_CONFIG.reviewMaxPerSession, REVIEW_SESSION_RANGE),
+    };
+}
 export const DEFAULT_CONFIG = {
     version: CONFIG_VERSION,
     provider: 'anthropic',
     model: DEFAULT_MODEL,
     baseUrl: null,
     thinkingLevel: 'off',
+    // Off by default — the product default this whole round exists to establish
+    // (D-1). One config key restores the old behaviour permanently.
+    showThinking: false,
+    // ON by default (D-28), and the OPPOSITE of the key above it on purpose: this
+    // one shows work that is otherwise invisible for the whole duration of the
+    // most expensive thing the agent does.
+    liveToolOutput: true,
     // The engine owns this number; spelling it here again is how the CLI and the
     // provider adapters end up disagreeing about what "the default" is.
     maxTokens: DEFAULT_MAX_OUTPUT_TOKENS,
@@ -415,6 +612,15 @@ export const DEFAULT_CONFIG = {
     // `todo` key at all, so this line is as required as the two merges in
     // `store.ts` (P0-1).
     todo: DEFAULT_TODO_CONFIG,
+    // Same requirement one section later: without this line a user with no `retry`
+    // key resolves `config.retry` to `undefined` and `toRetryPolicy` throws.
+    retry: DEFAULT_RETRY_CONFIG,
+    // And one section later again: the load path's first spread is what supplies
+    // `fast` to a user whose `config.json` predates this feature, which is every
+    // existing user. Without it `config.fast.enabled` reads `undefined`, which is
+    // falsy and so LOOKS correct — right up until `/fast on` writes a section that
+    // has no other keys in it (P0-1's shape, one feature later).
+    fast: DEFAULT_FAST_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -14,7 +14,7 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampMaxTokens, clampSkillsConfig, clampTeamConfig, clampTodoConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -126,6 +126,14 @@ export function loadPersistedConfig() {
         // the READ half of the pair that keeps `/todo panel off` from silently
         // unregistering the tool on the next launch (P0-1 / AC-35).
         todo: clampTodoConfig({ ...DEFAULT_CONFIG.todo, ...(partial.todo ?? {}) }),
+        // `retry` is the sixth. The READ half: without it a config file with no
+        // `retry` key yields `undefined` and `toRetryPolicy` throws on the value it
+        // is handed (R-9 / AC-20).
+        retry: clampRetryConfig({ ...DEFAULT_CONFIG.retry, ...(partial.retry ?? {}) }),
+        // `fast` is the seventh. Same one-level rule, same merge — and this is the
+        // READ half of the pair that keeps `/fast review 8` from silently switching
+        // the whole tier off on the next launch (C-3 / R-10).
+        fast: clampFastConfig({ ...DEFAULT_CONFIG.fast, ...(partial.fast ?? {}) }),
     };
 }
 /**
@@ -177,6 +185,17 @@ export function updatePersistedConfig(patch) {
         // spread turns into "turning the panel off silently unregisters the tool",
         // permanently, from the next launch onward, with nothing anywhere saying so.
         todo: clampTodoConfig({ ...current.todo, ...(patch.todo ?? {}) }),
+        // The sixth section. `/retry max 5` sends `{ retry: { maxRetries: 5 } }`,
+        // which a shallow spread turns into "changing the retry count silently
+        // reverted `respectRetryAfter` and `jitter`" (R-9 / AC-19).
+        retry: clampRetryConfig({ ...current.retry, ...(patch.retry ?? {}) }),
+        // The seventh section, and THE WRITE HALF IS THE ONE THAT BITES (R-10).
+        // `/fast review 8` sends `{ fast: { reviewEveryTurns: 8 } }`; without this
+        // line the shallow top-level spread REPLACES the section, `enabled` is
+        // written absent, and the tier the user configured yesterday is gone
+        // tomorrow with no error anywhere. This package has paid for that once
+        // already, in `todo` (P0-1).
+        fast: clampFastConfig({ ...current.fast, ...(patch.fast ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/fast/critique.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `normalizeCritique` — turn whatever the fast model wrote into one of three
+ * outcomes (fast-model-tier §3.5.3). PURE: no I/O, no state.
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ */
+/**
+ * What a review amounted to.
+ *
+ * `ok` and `empty` are NOT INJECTED (D-16). They still produce a transcript
+ * entry and a log record, so the user can see the harness is alive, but the lead
+ * pays no context for the message "nothing to say".
+ */
+export type Critique = {
+    kind: 'ok';
+} | {
+    kind: 'advice';
+    text: string;
+} | {
+    kind: 'empty';
+};
+/**
+ * THE ON-TRACK TEST IS A NORMALIZED REGEX, NEVER STRING EQUALITY (D-17).
+ *
+ * The system prompt asks for the exact string `OK - on track.`, and models
+ * mostly comply - but one that writes `Ok, on track` would, under an equality
+ * test, be classified as ADVICE and injected into the main context on every
+ * cycle, forever, saying nothing. That is worse than having no reviewer: it is a
+ * permanent context tax that looks like the feature working.
+ *
+ * So: trim, lowercase, drop trailing punctuation, then `/^ok\b.*on track/`.
+ * `'OK, but the tests are failing'` still classifies as advice, because it does
+ * not say "on track".
+ */
+export declare function isOnTrack(text: string): boolean;
+/**
+ * Normalize and classify one raw review answer.
+ *
+ * @param raw      Whatever the model returned.
+ * @param maxChars `fast.reviewMaxChars` — the ceiling the user chose on how much
+ *                 of their own context a critique may spend.
+ */
+export declare function normalizeCritique(raw: string, maxChars: number): Critique;

package/dist/fast/critique.js

@@ -0,0 +1,62 @@
+/**
+ * `normalizeCritique` — turn whatever the fast model wrote into one of three
+ * outcomes (fast-model-tier §3.5.3). PURE: no I/O, no state.
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ */
+/** Strip a fenced code block wrapper the model may have put around its prose. */
+function stripFences(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('```'))
+        return trimmed;
+    const withoutOpen = trimmed.replace(/^```[a-zA-Z0-9_-]*\s*\r?\n?/, '');
+    return withoutOpen.replace(/\r?\n?```\s*$/, '').trim();
+}
+/**
+ * THE ON-TRACK TEST IS A NORMALIZED REGEX, NEVER STRING EQUALITY (D-17).
+ *
+ * The system prompt asks for the exact string `OK - on track.`, and models
+ * mostly comply - but one that writes `Ok, on track` would, under an equality
+ * test, be classified as ADVICE and injected into the main context on every
+ * cycle, forever, saying nothing. That is worse than having no reviewer: it is a
+ * permanent context tax that looks like the feature working.
+ *
+ * So: trim, lowercase, drop trailing punctuation, then `/^ok\b.*on track/`.
+ * `'OK, but the tests are failing'` still classifies as advice, because it does
+ * not say "on track".
+ */
+export function isOnTrack(text) {
+    const normalized = text
+        .trim()
+        .toLowerCase()
+        .replace(/[.!\s]+$/, '')
+        .replace(/\s+/g, ' ');
+    return /^ok\b.*on track/.test(normalized);
+}
+/**
+ * Normalize and classify one raw review answer.
+ *
+ * @param raw      Whatever the model returned.
+ * @param maxChars `fast.reviewMaxChars` — the ceiling the user chose on how much
+ *                 of their own context a critique may spend.
+ */
+export function normalizeCritique(raw, maxChars) {
+    const stripped = stripFences(raw ?? '');
+    // Whitespace is collapsed BEFORE the length test: a model that answers with
+    // four blank lines and a sentence must not spend its budget on the blanks.
+    const collapsed = stripped.replace(/\s+/g, ' ').trim();
+    if (collapsed.length === 0)
+        return { kind: 'empty' };
+    if (isOnTrack(collapsed))
+        return { kind: 'ok' };
+    const limit = Math.max(1, Math.floor(maxChars) || 1);
+    if (collapsed.length <= limit)
+        return { kind: 'advice', text: collapsed };
+    // Clamp on a word boundary when one is close enough that the sentence still
+    // reads; otherwise a hard cut, because a critique is prose and a mid-word
+    // truncation is what makes advice look like corruption.
+    const cut = collapsed.slice(0, limit);
+    const space = cut.lastIndexOf(' ');
+    const text = space > limit * 0.6 ? cut.slice(0, space) : cut;
+    return { kind: 'advice', text };
+}

package/dist/fast/digest.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `buildReviewDigest` — the bounded text one review is asked about
+ * (fast-model-tier §3.5.2). PURE: no I/O, no clock, no state.
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THE REVIEWER NEVER READS `agent.state.messages`, AND THAT IS THE SINGLE MOST
+ * IMPORTANT ECONOMIC DECISION IN THE FEATURE (D-6 / R-2). That history holds
+ * whole file bodies: a session that has read four 60 KB files carries 240 KB of
+ * them. Shipping it to the "cheap" model to ask whether the run is on track
+ * would make a review cost MORE than the main-model turn it is reviewing - the
+ * exact inversion this feature exists to prevent. The digest is bounded at
+ * `FAST_LIMITS.digestMaxChars` BY CONSTRUCTION, so a review's input cost is flat
+ * regardless of session length.
+ *
+ * Anyone tempted to "just pass the messages, the model has the context anyway"
+ * is about to turn a 400-token call into a 60 000-token one, and nothing in the
+ * UI would show it except the bill.
+ */
+import type { TurnFrame } from './types.js';
+export interface ReviewDigestParams {
+    /** The reviewer's ring buffer, oldest first. */
+    frames: TurnFrame[];
+    /** The user's request for this run, already clamped by the caller. */
+    goal: string;
+    /** `fast.reviewContextTurns` — how many SEALED frames to include. */
+    contextTurns: number;
+}
+/**
+ * Build the digest.
+ *
+ * SEALED FRAMES ONLY (RV-2 / D-22). The turn being reviewed is sealed by
+ * definition - sealing is what triggered the review - so the window is the
+ * newest `contextTurns` sealed frames, and a frame that is still accumulating is
+ * never half-rendered into a prompt.
+ *
+ * NEWEST FRAMES SURVIVE THE BOUND. When the assembled text exceeds
+ * `digestMaxChars` the OLDEST frame is dropped and the document is rebuilt,
+ * because the reviewer's question is about what just happened. Trimming from the
+ * tail would hand it the beginning of a run and ask about the end of one.
+ */
+export declare function buildReviewDigest(params: ReviewDigestParams): string;

package/dist/fast/digest.js

@@ -0,0 +1,85 @@
+/**
+ * `buildReviewDigest` — the bounded text one review is asked about
+ * (fast-model-tier §3.5.2). PURE: no I/O, no clock, no state.
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THE REVIEWER NEVER READS `agent.state.messages`, AND THAT IS THE SINGLE MOST
+ * IMPORTANT ECONOMIC DECISION IN THE FEATURE (D-6 / R-2). That history holds
+ * whole file bodies: a session that has read four 60 KB files carries 240 KB of
+ * them. Shipping it to the "cheap" model to ask whether the run is on track
+ * would make a review cost MORE than the main-model turn it is reviewing - the
+ * exact inversion this feature exists to prevent. The digest is bounded at
+ * `FAST_LIMITS.digestMaxChars` BY CONSTRUCTION, so a review's input cost is flat
+ * regardless of session length.
+ *
+ * Anyone tempted to "just pass the messages, the model has the context anyway"
+ * is about to turn a 400-token call into a 60 000-token one, and nothing in the
+ * UI would show it except the bill.
+ */
+import { FAST_LIMITS } from './limits.js';
+/** Clip to `maxChars` on a word boundary when one is close enough to matter. */
+function clip(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const cut = text.slice(0, maxChars);
+    const space = cut.lastIndexOf(' ');
+    return space > maxChars * 0.6 ? cut.slice(0, space) : cut;
+}
+/** One tool as the digest names it: `read_file(src/app.ts) 12ms`. */
+function renderTool(tool) {
+    const arg = tool.arg ? `(${clip(tool.arg, FAST_LIMITS.toolArgChars)})` : '';
+    const failed = tool.isError ? ' FAILED' : '';
+    const ms = tool.ms === undefined ? '' : ` ${Math.round(tool.ms)}ms`;
+    return `${tool.name}${arg}${failed}${ms}`;
+}
+function renderFrame(frame) {
+    const lines = [`Turn ${frame.index}:`];
+    if (frame.tools.length > 0) {
+        lines.push(`  tools: ${frame.tools.map(renderTool).join(', ')}`);
+    }
+    else {
+        lines.push('  tools: (none)');
+    }
+    if (frame.error)
+        lines.push(`  error: ${clip(frame.error, 200)}`);
+    const tail = frame.textTail.trim();
+    if (tail.length > 0)
+        lines.push(`  said: ${clip(tail, FAST_LIMITS.turnTailChars)}`);
+    return lines;
+}
+/**
+ * Build the digest.
+ *
+ * SEALED FRAMES ONLY (RV-2 / D-22). The turn being reviewed is sealed by
+ * definition - sealing is what triggered the review - so the window is the
+ * newest `contextTurns` sealed frames, and a frame that is still accumulating is
+ * never half-rendered into a prompt.
+ *
+ * NEWEST FRAMES SURVIVE THE BOUND. When the assembled text exceeds
+ * `digestMaxChars` the OLDEST frame is dropped and the document is rebuilt,
+ * because the reviewer's question is about what just happened. Trimming from the
+ * tail would hand it the beginning of a run and ask about the end of one.
+ */
+export function buildReviewDigest(params) {
+    const sealed = params.frames.filter((f) => f.sealed);
+    const want = Math.max(1, Math.floor(params.contextTurns) || 1);
+    let window = sealed.slice(-want);
+    const goal = clip(params.goal.trim(), FAST_LIMITS.goalChars);
+    const assemble = (frames) => [
+        `Goal: ${goal.length > 0 ? goal : '(not captured)'}`,
+        '',
+        ...frames.flatMap(renderFrame),
+    ].join('\n');
+    let out = assemble(window);
+    while (out.length > FAST_LIMITS.digestMaxChars && window.length > 1) {
+        window = window.slice(1);
+        out = assemble(window);
+    }
+    // A single frame can still be over budget on its own (a 600-char tail plus
+    // twelve tools), so the hard clamp is unconditional. It is a CEILING, not the
+    // trimming strategy: the loop above is what decides WHAT is lost.
+    return out.length > FAST_LIMITS.digestMaxChars
+        ? out.slice(0, FAST_LIMITS.digestMaxChars)
+        : out;
+}

package/dist/fast/frames.d.ts

@@ -0,0 +1,99 @@
+/**
+ * TurnFrameRing — the reviewer's bounded record of what the lead just did
+ * (fast-model-tier §3.5.1, extracted here by fast-model-tier-hardening W3).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THIS IS THE `data` HALF OF THE SPLIT, AND IT IS A LEAF ON PURPOSE. `reviewer.ts`
+ * was at 871 of the repo's 1 000-line cap before round 2 added a budget to it, so
+ * the ring and the transport moved out. The split line is drawn along data and
+ * transport BECAUSE BOTH ARE LEAVES: the protocol — the two drain guards and the
+ * call-cancellation stamping — stays whole in `reviewer.ts`, where a module
+ * boundary through it would reopen a P0 (§3.3 / AC-H11 / AC-H16).
+ *
+ * WHAT THIS CLASS OWNS: the open frame, the retired ring, the outstanding-call
+ * counter and the tool-argument map. WHAT IT DECIDES: nothing. It reports that a
+ * batch has emptied; the caller decides what that means.
+ */
+import type { AssistantMessage, StreamEvent } from '@aragon-agent/core';
+import type { TurnFrame } from './types.js';
+export interface TurnFrameRingDeps {
+    /**
+     * Whether a frame can still be consumed by a review this run.
+     *
+     * A PREDICATE, NOT A BOOLEAN, and read inside `recordDelta` rather than at its
+     * call site: this runs on every `text_delta` of every turn, and evaluating the
+     * caller's gate eagerly would move a config read onto the hottest path in the
+     * package for the deltas that are discarded by type anyway.
+     */
+    canRecord(): boolean;
+}
+export declare class TurnFrameRing {
+    private readonly deps;
+    private retained;
+    private open;
+    /**
+     * Tool calls still to run in the current batch.
+     *
+     * ASSIGNED at `turn_end`, NEVER CARRIED ACROSS TURNS (RV-7), and the
+     * difference is not cosmetic. Two paths end a batch without emitting a
+     * `tool_execution_end` for every call: checkpoint 2 skips the whole batch
+     * (`agent-loop.ts:199-207`) and an abort breaks out mid-batch (`:211`). A
+     * counter that only ever decremented would sit permanently above zero after
+     * either, and the injection window would never open again for the rest of the
+     * run. Re-assigning at each `turn_end` makes both cases self-heal on the next
+     * turn, which is correct: those batches genuinely had no window.
+     */
+    private outstanding;
+    private completedTurns;
+    /** Tool args captured at `tool_execution_start`, keyed by call id. */
+    private readonly toolArgs;
+    constructor(deps: TurnFrameRingDeps);
+    /** Completed turns of the CURRENT run — the cadence and staleness clock. */
+    get turns(): number;
+    /** Always 0 at the injection window; logged there as the assertion, recorded. */
+    get outstandingCalls(): number;
+    /** The ring, oldest first. `buildReviewDigest` filters it for sealed frames. */
+    frames(): TurnFrame[];
+    /** `agent_start`. */
+    reset(): void;
+    /** `agent_end` — the ring survives for a late answer; the open frame does not. */
+    endRun(): void;
+    /** `turn_start`. */
+    beginTurn(): void;
+    /**
+     * The frame recorder.
+     *
+     * GATED ON `text_delta` AS AN ALLOW-TEST, NEVER A DENY-LIST (RV-10 / R-16).
+     * `agent-loop.ts:170` forwards EVERY stream event through `message_update` -
+     * `text_delta`, `thinking_delta`, `tool_call_delta`, `done`, and (as of
+     * `llm-api-retry-backoff`) `retry_scheduled` / `retry_attempt` - so this is a
+     * synchronous listener on the hottest path in the package. A deny-list would
+     * have silently started recording the two new members the moment they shipped.
+     *
+     * The remaining conditions are economic rather than structural: after the last
+     * permitted review of a run there is nothing left that can consume a frame.
+     */
+    recordDelta(streamEvent: StreamEvent): void;
+    /** `tool_execution_start`. */
+    noteToolArgs(toolCallId: string, args: unknown): void;
+    /** `turn_end`. A turn with NO tool calls ends the run, so its frame seals here. */
+    endTurn(message: AssistantMessage): void;
+    /**
+     * `tool_execution_end`. Returns whether this call EMPTIED the batch — which is
+     * both the sealing point (§3.5.1) and the one injection window (§3.5.4). The
+     * ring reports the fact; `reviewer.ts` owns what follows from it.
+     */
+    endTool(toolCallId: string, toolName: string, isError: boolean, duration: number): boolean;
+    /**
+     * Seal the open frame and retire it into the ring.
+     *
+     * A REVIEW IS TRIGGERED ON SEALING, NOT AT `turn_end` (RV-2 / D-22).
+     * `turn_end` fires at `agent-loop.ts:188`, BEFORE any tool runs, while
+     * `TurnFrame.tools` carries `isError` and `ms` - fields that exist only once
+     * `tool_execution_end` has been emitted (`:249-256`). Triggering there meant
+     * the newest frame of every digest was structurally missing the single fact a
+     * reviewer most needs: whether the batch it is reviewing just failed.
+     */
+    seal(): void;
+}