@aragon-agent/cli 0.5.8 → 0.5.10

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,244 @@ 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),
+    };
+}
+// ---------------------------------------------------------------------------
+// Auto-update (cli-auto-update §4.1)
+//
+// The EIGHTH nested section in the persisted config, after `apiKeys`, `skills`,
+// `log`, `team`, `todo`, `retry` and `fast` — and, like all of them, SCALARS
+// ONLY, exactly one level deep. `store.ts` merges these sections BY HAND and
+// that merge is only correct while nesting stays flat (C-5).
+//
+// BOTH OF `store.ts`'s MERGES MUST LEARN ABOUT THIS SECTION, AND THE OMISSION IS
+// SILENT (C-4 / R-10). `config set update.mode notify` sends
+// `{ update: { mode: 'notify' } }`; without the write merge the shallow
+// top-level spread REPLACES the whole section and `checkIntervalMs`, `registry`
+// and `distTag` silently revert on disk. This package has paid for that twice
+// already — `todo` P0-1 and `fast` R-10 — which is why it is written down a
+// third time rather than assumed to be common knowledge.
+//
+// FOUR KEYS AND NO MORE (D-16). `mode` covers on / notify / off; a fifth key
+// (`autoInstall`) would be a second way to say the same thing, and two ways to
+// express one setting is how they end up disagreeing.
+// ---------------------------------------------------------------------------
+/** `auto` installs; `notify` only reports; `off` disables the subsystem. */
+export const UPDATE_MODES = ['auto', 'notify', 'off'];
+export function isUpdateMode(v) {
+    return typeof v === 'string' && UPDATE_MODES.includes(v);
+}
+export const DEFAULT_UPDATE_CONFIG = {
+    mode: 'auto',
+    // FOUR HOURS, in ms. `checkIntervalMs` and not `checkIntervalHours` (D-17):
+    // every other duration in this config is in ms (`toolTimeoutMs`,
+    // `idleTimeoutMs`, `team.dispatchTimeoutMs`, `retry.initialDelayMs`), and one
+    // unit per file is worth more than one shorter number.
+    checkIntervalMs: 14_400_000,
+    registry: '',
+    distTag: 'latest',
+};
+/** 15 minutes to 7 days. The floor is a politeness bound on the registry. */
+const UPDATE_INTERVAL_RANGE = { min: 900_000, max: 604_800_000 };
+/** npm's own dist-tag grammar, loosely: no slashes, no spaces, no `@`. */
+const DIST_TAG_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+/**
+ * THE single gate for every update-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * / `clampRetryConfig` / `clampFastConfig` for the reason all six 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".
+ *
+ * `registry` is CLAMPED TO `''` rather than rejected when it is not an
+ * `http(s):` URL. `''` means "derive it" (§3.3), which is the safe reading of a
+ * typo — the alternative is a background timer that throws on a value the user
+ * cannot see it reading.
+ */
+export function clampUpdateConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const registry = text(src.registry, DEFAULT_UPDATE_CONFIG.registry);
+    const distTag = text(src.distTag, DEFAULT_UPDATE_CONFIG.distTag);
+    return {
+        mode: isUpdateMode(src.mode) ? src.mode : DEFAULT_UPDATE_CONFIG.mode,
+        checkIntervalMs: clampInt(src.checkIntervalMs, DEFAULT_UPDATE_CONFIG.checkIntervalMs, UPDATE_INTERVAL_RANGE),
+        registry: isRegistryUrl(registry) ? registry : DEFAULT_UPDATE_CONFIG.registry,
+        distTag: DIST_TAG_RE.test(distTag) ? distTag : DEFAULT_UPDATE_CONFIG.distTag,
+    };
+}
+function isRegistryUrl(raw) {
+    if (raw.length === 0)
+        return false;
+    try {
+        const url = new URL(raw);
+        // `http:` is accepted for a LAN mirror; nothing else is a registry.
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
 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 +687,21 @@ 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,
+    // And one section later again, for the third time. Without this line a user
+    // whose `config.json` predates auto-update resolves `config.update.mode` to
+    // `undefined`, which is neither `'auto'` nor `'off'` — so the §3.8 gate
+    // (`cfg.update.mode !== 'off'`) would read TRUE and the feature would be on
+    // for a reason nobody could point at.
+    update: DEFAULT_UPDATE_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, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -126,6 +126,19 @@ 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 ?? {}) }),
+        // `update` is the eighth. Same one-level rule, same merge — and the READ
+        // half is what supplies a whole section to every user whose `config.json`
+        // predates auto-update, which is all of them. Without it `config.update.mode`
+        // reads `undefined`, and the §3.8 gate tests `!== 'off'`.
+        update: clampUpdateConfig({ ...DEFAULT_CONFIG.update, ...(partial.update ?? {}) }),
     };
 }
 /**
@@ -177,6 +190,24 @@ 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 ?? {}) }),
+        // The eighth section, and the third time this file records the same trap.
+        // `config set update.mode notify` sends `{ update: { mode: 'notify' } }`;
+        // without this line the shallow top-level spread REPLACES the section,
+        // `checkIntervalMs` / `registry` / `distTag` are written absent, and an
+        // enterprise mirror the user configured last month is gone with no error
+        // anywhere. AC-20 is the assertion that proves both halves exist.
+        update: clampUpdateConfig({ ...current.update, ...(patch.update ?? {}) }),
     };
     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;
+}