@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/fast/limits.js

@@ -0,0 +1,98 @@
+/**
+ * FAST_LIMITS — the single authority on every bound the fast tier enforces
+ * (fast-model-tier §5.5).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte. The
+ * regex there is a hardcoded directory list, which is why adding this tree and
+ * adding `fast` to that list are the SAME change (C-4 / AC-27) - a scanner that
+ * silently stops scanning is worse than no scanner.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE - the distinction
+ * `TEAM_LIMITS` and `TODO_LIMITS` both state:
+ *
+ *  - The entries below are STRUCTURAL. They describe what a review call, a
+ *    digest and a card can physically carry. A user has no business tuning them.
+ *  - The ten `fast.*` keys in `config/schema.ts` are POLICY: which model, how
+ *    often, how long a critique may be. Those are clamped, persisted and
+ *    user-facing.
+ *
+ * `reviewMaxChars` therefore lives in the CONFIG and not here: it is the one
+ * number whose right value depends on how much of their own context the user is
+ * willing to spend on advice. `reviewOutputTokens` stays here because 512 tokens
+ * is a bound on a protocol, not a preference.
+ */
+export const FAST_LIMITS = {
+    /**
+     * The flat input cost of one review (D-6 / R-2).
+     *
+     * THIS NUMBER IS THE WHOLE ECONOMIC ARGUMENT. The reviewer builds its own
+     * bounded frame ring and never reads `agent.state.messages`, which after four
+     * 60 KB file reads carries 240 KB of file bodies; shipping that to the "cheap"
+     * model would make a review cost MORE than the turn it is reviewing.
+     */
+    digestMaxChars: 4_000,
+    /** The user's request for the run, clamped. Without it the reviewer is asked
+     *  whether work is on track without being told what the track is. */
+    goalChars: 500,
+    /** Per-frame assistant-text tail. Rolling, clipped on every append. */
+    turnTailChars: 600,
+    /** Per picked tool argument. Mirrors `TEAM_LIMITS.activityArgChars`. */
+    toolArgChars: 120,
+    /** Frames kept per run. `>=` the max of `reviewContextTurns`, with slack. */
+    maxFramesRetained: 12,
+    /** Hard cap on the review's own output. */
+    reviewOutputTokens: 512,
+    /**
+     * Wall-clock budget for ONE review call INCLUDING RETRIES (D-H11).
+     *
+     * THE BUDGET HAS TWO TERMS AND ONLY ONE OF THEM SHRANK. Round 1 set 30 s as
+     * IF-3's fallback: `ProviderRegistry.complete()` routed through a retrying
+     * `stream()` with `maxRetries: 10`, so the budget covered
+     * `attempts x (call + backoff)`. Round 2 gives the reviewer its own
+     * `maxRetries: 1` registry (`wiring.ts`), which collapses that term to about
+     * one call plus a one-second backoff - but it does nothing at all to the
+     * other term, THE FAST MODEL'S OWN GENERATION LATENCY. The review asks for up
+     * to `reviewOutputTokens` from a `digestMaxChars` prompt, and the tier is by
+     * construction pointed at the cheapest endpoint the user has: the population
+     * where a 15-25 s completion is ordinary rather than pathological.
+     *
+     * SO THIS IS 20 000 AND NOT 12 000. A timeout IS a strike (see `runReview`),
+     * and `maxConsecutiveFailures` is 3, so a 12 s bound would convert "slow but
+     * healthy provider" into a tier that self-disables for the session and
+     * reports itself as MISCONFIGURED - the one register D-24 reserves for faults
+     * that never self-heal, spent on one that does. 20 s keeps a margin over a
+     * slow completion and still cuts a stuck review's occupancy of the
+     * single-flight slot by a third. Lower it only with a measured p99, which
+     * `manual-test.md` row 6 exists to produce.
+     */
+    reviewTimeoutMs: 20_000,
+    /** Reviews STARTED per run. A 40-turn run at cadence 5 would otherwise buy 8
+     *  critiques the lead increasingly ignores. */
+    maxReviewsPerRun: 6,
+    /** Consecutive NON-TRANSIENT failures before the reviewer self-disables. */
+    maxConsecutiveFailures: 3,
+    /**
+     * A critique waiting for its injection window goes stale (RV-12).
+     *
+     * The window is not guaranteed to be prompt: one `task` dispatch is a single
+     * tool call that can run for `team.dispatchTimeoutMs`, so a critique triggered
+     * just before one arrives at the far side describing a state five children
+     * have since rewritten. Advice that is merely late is worse than no advice,
+     * because the lead cannot tell that it is late.
+     */
+    pendingMaxAgeMs: 120_000,
+    /** ... or is overtaken by the run itself, in turns. */
+    pendingMaxTurnsBehind: 2,
+    /** Rows the transcript card renders before eliding. */
+    cardTextRows: 4,
+    /** Below this many columns the status chip drops (D-20's treatment, not
+     *  `agentMode`'s - the guaranteed reporting surface is `/fast status`). */
+    statusCompactCols: 100,
+};
+/**
+ * Bumped whenever the wording of `<fast_tier>` or the review system prompt
+ * changes, so a behaviour report can be tied to a block revision with one grep -
+ * exactly what `TEAM_BLOCK_VERSION` and `TODO_BLOCK_VERSION` are for.
+ */
+export const FAST_BLOCK_VERSION = 'v1-2026-07';

package/dist/fast/prompt.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The prompt text the fast tier adds (fast-model-tier §4.6).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope, and these
+ * strings also reach a model that may be running in a `cmd.exe` terminal.
+ *
+ * `<fast_tier>` IS SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what
+ * preserves invariant I-2: with the tier off the prompt is BYTE-IDENTICAL to the
+ * pre-feature output for a fixed tool array. An unconditional guidance line here
+ * would quietly break `--no-fast`, `--no-team`, `--no-skills` and `--no-todo`
+ * all at once.
+ *
+ * `FAST_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { FAST_BLOCK_VERSION } from './limits.js';
+export { FAST_BLOCK_VERSION };
+export interface FastBlockParams {
+    /** The resolved fast model id, interpolated so the prompt never names a model
+     *  the tier will not actually use (§3.9 / RV-3). */
+    model: string;
+    /** `fast.delegate` — whether `model: "fast"` is honoured on `task`. */
+    delegate: boolean;
+    /** `fast.review` — whether `<fast_review>` blocks can appear at all. */
+    review: boolean;
+}
+/**
+ * The lead's `<fast_tier>` block. Under 1100 characters on purpose: it is paid
+ * for on EVERY turn of every fast-enabled session, so anything that does not
+ * change a delegation decision does not belong in it (R-11).
+ *
+ * EACH PARAGRAPH IS PRESENT ONLY WHEN ITS CAPABILITY IS. `fast.delegate: false,
+ * fast.review: true` advertises only the review, because telling a model about a
+ * `model: "fast"` field that the normalizer will downgrade every time is how you
+ * get a model that keeps asking for something it can never have.
+ *
+ * Returns `''` when neither capability is live, which the splice treats as "no
+ * block" and which keeps the byte-identity branch intact.
+ */
+export declare function buildFastBlock(params: FastBlockParams): string;
+export interface ReviewSystemPromptParams {
+    /** `fast.reviewMaxChars` — quoted so the model and the clamp agree. */
+    maxChars: number;
+}
+/**
+ * The reviewer's own system prompt.
+ *
+ * IT ASKS FOR AN EXACT STRING when there is nothing to say (`OK - on track.`)
+ * and `normalizeCritique` still matches it with a NORMALIZED REGEX rather than
+ * equality (D-17). The two are not redundant: the prompt makes compliance the
+ * likely outcome, the regex makes non-compliance harmless.
+ *
+ * NO TOOLS ARE OFFERED AND NONE ARE MENTIONED (D-11). A tool-using reviewer
+ * would be a second agent editing the same working tree with none of the gates
+ * the lead's tools carry.
+ */
+export declare function buildReviewSystemPrompt(params: ReviewSystemPromptParams): string;
+export interface ReviewInjectionParams {
+    turn: number;
+    model: string;
+    text: string;
+}
+/**
+ * The block that is actually steered into the run.
+ *
+ * THE ATTRIBUTES ARE NOT DECORATION. Steering delivers this in the `user` role
+ * (`agent-loop.ts:129`), so the wrapper is the only thing distinguishing an
+ * automated critique from something the human typed - and it is also what makes
+ * the residual case in §3.5.4a (a stranded block the reviewer may not clear)
+ * self-identifying if it ever does surface.
+ */
+export declare function renderReviewInjection(params: ReviewInjectionParams): string;

package/dist/fast/prompt.js

@@ -0,0 +1,94 @@
+/**
+ * The prompt text the fast tier adds (fast-model-tier §4.6).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope, and these
+ * strings also reach a model that may be running in a `cmd.exe` terminal.
+ *
+ * `<fast_tier>` IS SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what
+ * preserves invariant I-2: with the tier off the prompt is BYTE-IDENTICAL to the
+ * pre-feature output for a fixed tool array. An unconditional guidance line here
+ * would quietly break `--no-fast`, `--no-team`, `--no-skills` and `--no-todo`
+ * all at once.
+ *
+ * `FAST_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { FAST_BLOCK_VERSION } from './limits.js';
+export { FAST_BLOCK_VERSION };
+/**
+ * The lead's `<fast_tier>` block. Under 1100 characters on purpose: it is paid
+ * for on EVERY turn of every fast-enabled session, so anything that does not
+ * change a delegation decision does not belong in it (R-11).
+ *
+ * EACH PARAGRAPH IS PRESENT ONLY WHEN ITS CAPABILITY IS. `fast.delegate: false,
+ * fast.review: true` advertises only the review, because telling a model about a
+ * `model: "fast"` field that the normalizer will downgrade every time is how you
+ * get a model that keeps asking for something it can never have.
+ *
+ * Returns `''` when neither capability is live, which the splice treats as "no
+ * block" and which keeps the byte-identity branch intact.
+ */
+export function buildFastBlock(params) {
+    if (!params.delegate && !params.review)
+        return '';
+    const lines = [
+        '<fast_tier>',
+        `A second, cheaper model is available in this session (${params.model}).`,
+    ];
+    if (params.delegate) {
+        lines.push('', 'Delegation: pass model:"fast" to a task subagent whose work is mechanical and', 'high-volume - reading or searching many files, summarizing long command output,', 'applying the same small edit in several places. Keep model:"main" (the default)', 'for design decisions, tricky debugging, and anything that has to be right the', 'first time. A fast subagent has the same tools and the same permissions as any', 'other; only the model differs.');
+    }
+    if (params.review) {
+        lines.push('', 'Reviews: every few turns a <fast_review> block may appear in the conversation.', 'It is an automated second opinion from the fast model - NOT a message from the', 'user. Treat it as advice: act on it when it is right, say so briefly and carry', 'on when it is not, and never ask the user to confirm it.');
+    }
+    lines.push('</fast_tier>');
+    return lines.join('\n');
+}
+/**
+ * The reviewer's own system prompt.
+ *
+ * IT ASKS FOR AN EXACT STRING when there is nothing to say (`OK - on track.`)
+ * and `normalizeCritique` still matches it with a NORMALIZED REGEX rather than
+ * equality (D-17). The two are not redundant: the prompt makes compliance the
+ * likely outcome, the regex makes non-compliance harmless.
+ *
+ * NO TOOLS ARE OFFERED AND NONE ARE MENTIONED (D-11). A tool-using reviewer
+ * would be a second agent editing the same working tree with none of the gates
+ * the lead's tools carry.
+ */
+export function buildReviewSystemPrompt(params) {
+    const max = Math.max(1, Math.floor(params.maxChars) || 1);
+    return [
+        'You are a fast reviewer watching another agent work. You see a short digest of',
+        'its recent turns: the goal, the tools it called, and the tail of what it said.',
+        '',
+        'Answer ONE question: is this run still on track for the goal?',
+        '',
+        `If it is, reply with EXACTLY: OK - on track.`,
+        'If it is not, reply with plain prose naming the single most useful correction -',
+        `at most ${max} characters, no preamble, no code fences, no lists, no headings.`,
+        '',
+        'Things worth saying: repeated edits with no verification, a failing tool call',
+        'that was ignored, work that has drifted from the goal, an obvious cheaper route.',
+        'Things not worth saying: style opinions, praise, restating what the agent did.',
+        '',
+        'You cannot run tools and you are not talking to the user. You are advising the',
+        'agent, and it will decide.',
+    ].join('\n');
+}
+/**
+ * The block that is actually steered into the run.
+ *
+ * THE ATTRIBUTES ARE NOT DECORATION. Steering delivers this in the `user` role
+ * (`agent-loop.ts:129`), so the wrapper is the only thing distinguishing an
+ * automated critique from something the human typed - and it is also what makes
+ * the residual case in §3.5.4a (a stranded block the reviewer may not clear)
+ * self-identifying if it ever does surface.
+ */
+export function renderReviewInjection(params) {
+    return [
+        `<fast_review turn="${params.turn}" model="${params.model}">`,
+        params.text,
+        '</fast_review>',
+    ].join('\n');
+}

package/dist/fast/resolve.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `resolveFastTier` — THE single authority on whether a fast tier exists and
+ * what it points at (fast-model-tier §3.2).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * EVERY CONSUMER READS THE TIER THROUGH THIS FUNCTION AND NOWHERE ELSE - the
+ * controller, the subagent factory, the reviewer, `/fast`, the settings screen
+ * and the status bar. Four call sites recomputing "is fast usable?" from raw
+ * config keys is exactly how a UI ends up showing a chip for a tier that refuses
+ * every call.
+ *
+ * IT IS ALSO RE-RUN ON EVERY CONFIG MUTATION, NOT ONCE (rule 8 / RV-3). Rules 2
+ * and 6 make `fast.provider: ''` and `fast.baseUrl: ''` INHERIT from
+ * `config.provider` / `config.baseUrl`, and rule 5 reads `apiKeys`. All of those
+ * are live: `/model`, `/provider`, the settings screen's save, `/reload` and a
+ * one-shot key edit each rewrite one of them mid-session. A tier resolved once
+ * at construction is a tier that can be describing a provider the session no
+ * longer uses.
+ */
+import { type CliConfig } from '../config/schema.js';
+import type { FastTier } from './types.js';
+/**
+ * Resolve the fast tier from the CURRENT config.
+ *
+ * @param config The live effective config. Read fresh; never snapshot it.
+ * @param hasKey `AgentController.hasApiKey`, which already resolves the
+ *   config-file key, the provider environment variable and the one-shot
+ *   `--api-key` override. Injected rather than reimplemented, because a second
+ *   key resolver is a second answer to "why does it say no key?".
+ */
+export declare function resolveFastTier(config: CliConfig, hasKey: (providerId: string) => boolean): FastTier;
+/**
+ * The one-line notice for a tier the user switched on that cannot resolve, or
+ * `null` when there is nothing worth saying.
+ *
+ * `disabled` returns `null` - the tier being off because the user left it off is
+ * not news. The other three are CONFIGURATION MISTAKES that are otherwise
+ * completely invisible: nothing else in the session would ever mention them.
+ */
+export declare function describeFastTierProblem(tier: FastTier, provider: string): string | null;
+/** The provider a tier resolution was about, for the notice above. */
+export declare function fastProviderOf(config: CliConfig): string;

package/dist/fast/resolve.js

@@ -0,0 +1,105 @@
+/**
+ * `resolveFastTier` — THE single authority on whether a fast tier exists and
+ * what it points at (fast-model-tier §3.2).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * EVERY CONSUMER READS THE TIER THROUGH THIS FUNCTION AND NOWHERE ELSE - the
+ * controller, the subagent factory, the reviewer, `/fast`, the settings screen
+ * and the status bar. Four call sites recomputing "is fast usable?" from raw
+ * config keys is exactly how a UI ends up showing a chip for a tier that refuses
+ * every call.
+ *
+ * IT IS ALSO RE-RUN ON EVERY CONFIG MUTATION, NOT ONCE (rule 8 / RV-3). Rules 2
+ * and 6 make `fast.provider: ''` and `fast.baseUrl: ''` INHERIT from
+ * `config.provider` / `config.baseUrl`, and rule 5 reads `apiKeys`. All of those
+ * are live: `/model`, `/provider`, the settings screen's save, `/reload` and a
+ * one-shot key edit each rewrite one of them mid-session. A tier resolved once
+ * at construction is a tier that can be describing a provider the session no
+ * longer uses.
+ */
+import { isAdapterProvider } from '../config/schema.js';
+/**
+ * Resolve the fast tier from the CURRENT config.
+ *
+ * @param config The live effective config. Read fresh; never snapshot it.
+ * @param hasKey `AgentController.hasApiKey`, which already resolves the
+ *   config-file key, the provider environment variable and the one-shot
+ *   `--api-key` override. Injected rather than reimplemented, because a second
+ *   key resolver is a second answer to "why does it say no key?".
+ */
+export function resolveFastTier(config, hasKey) {
+    const fast = config.fast;
+    // 1. The switch.
+    if (!fast || fast.enabled !== true)
+        return { ok: false, reason: 'disabled' };
+    // 2. An empty provider INHERITS the main one. This is what makes `fast.model`
+    //    alone a complete configuration for the overwhelmingly common case ("same
+    //    vendor, cheaper model").
+    const provider = fast.provider.trim().length > 0 ? fast.provider.trim() : config.provider;
+    // 3. An empty model is NOT CONFIGURED, and deliberately does not inherit
+    //    (D-4). Silently falling back to the main model would make R-e - opting in
+    //    to fast == main, which is legal - indistinguishable from a typo.
+    const modelId = fast.model.trim();
+    if (modelId.length === 0)
+        return { ok: false, reason: 'no_model' };
+    // 4 / 5. Both are reported separately because they send the user to two
+    //        different settings.
+    if (!isAdapterProvider(provider))
+        return { ok: false, reason: 'no_adapter' };
+    if (!hasKey(provider))
+        return { ok: false, reason: 'no_key' };
+    // 6. A fast tier on the SAME provider inherits the session's base URL: a user
+    //    pointing the CLI at a gateway means both models, not one. A fast tier on
+    //    a DIFFERENT provider does not, because that base URL belongs to another
+    //    API and would be an immediate 404.
+    const explicitBaseUrl = fast.baseUrl.trim();
+    const baseUrl = explicitBaseUrl.length > 0
+        ? explicitBaseUrl
+        : provider === config.provider
+            ? config.baseUrl
+            : undefined;
+    const ref = {
+        providerId: provider,
+        modelId,
+        ...(baseUrl ? { baseUrl } : {}),
+    };
+    return {
+        ok: true,
+        ref,
+        thinkingLevel: fast.thinkingLevel,
+        // 7. DISPLAY ONLY, and no branch anywhere may read it (R-13). "The two tiers
+        //    resolve to the same model, so skip the work" is the tempting
+        //    optimization that silently turns R-e into a no-op: the user is allowed
+        //    to choose it, and the cost of the review is real either way.
+        sameAsMain: provider === config.provider && modelId === config.model,
+    };
+}
+/**
+ * The one-line notice for a tier the user switched on that cannot resolve, or
+ * `null` when there is nothing worth saying.
+ *
+ * `disabled` returns `null` - the tier being off because the user left it off is
+ * not news. The other three are CONFIGURATION MISTAKES that are otherwise
+ * completely invisible: nothing else in the session would ever mention them.
+ */
+export function describeFastTierProblem(tier, provider) {
+    if (tier.ok)
+        return null;
+    switch (tier.reason) {
+        case 'no_model':
+            return 'fast.enabled is on but fast.model is empty - the fast tier is off. ' +
+                'Set it with /fast model <id>.';
+        case 'no_adapter':
+            return `Provider "${provider}" has no adapter - the fast tier is off.`;
+        case 'no_key':
+            return `No API key for ${provider} - the fast tier is off.`;
+        default:
+            return null;
+    }
+}
+/** The provider a tier resolution was about, for the notice above. */
+export function fastProviderOf(config) {
+    const explicit = config.fast?.provider.trim() ?? '';
+    return explicit.length > 0 ? explicit : config.provider;
+}

package/dist/fast/review-call.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The bounded review call (fast-model-tier §3.5.3, extracted here by
+ * fast-model-tier-hardening W3).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THIS MODULE DOES NOT OWN AN `AbortController`, AND THAT IS A P0 PROHIBITION
+ * RATHER THAN AN OVERSIGHT (RV-H1 / AC-H16). Encapsulating a controller with the
+ * call it aborts is correct everywhere else in this codebase, which is exactly
+ * why it has to be forbidden in writing here:
+ *
+ *   - `callAbort` and `callAbortReason` are SHARED MUTABLE STATE between the
+ *     call and the lifecycle. The call arms them and reads the reason in its
+ *     catch; `cancelCall()` — reached from `abort()`, `endRun()` and
+ *     `dispose()` — stamps `'cancelled'` BEFORE aborting.
+ *   - Once the controller is private to this module, that stamp becomes
+ *     impossible, every cancelled review falls into the failure branch, and each
+ *     one scores a strike. Three ordinary runs then self-disable the tier for the
+ *     rest of the session behind a warn quoting an internal stream message.
+ *   - It cannot be recovered at the catch: the retry layer returns SILENTLY on
+ *     abort (`retry.ts` G3, deliberately — a user Esc must not be blamed on the
+ *     network), so a cancellation and a timeout arrive as byte-identical bare
+ *     `Error`s carrying no `errorType`.
+ *
+ * ROUND 1 SHIPPED THAT DEFECT AND FIXED IT AS IF-7. So this module RECEIVES the
+ * signal and a timeout callback, and returns an outcome. It does not create,
+ * own, or classify the abort. `fast-reviewer.test.ts`'s cancellation cases are
+ * the behavioural guard; they were written before this file existed.
+ */
+import type { AssistantMessage, LLMRequest, ModelRef, TokenUsage } from '@aragon-agent/core';
+/** The assistant text of a completion, or `''` for a tool-only answer. */
+export declare function assistantText(message: AssistantMessage | undefined): string;
+export declare function errorText(err: unknown): string;
+/** Whether a failure is the provider being busy rather than the tier being wrong. */
+export declare function classifyReviewFailure(err: unknown): {
+    errorType: string;
+    transient: boolean;
+};
+/**
+ * The review's spend.
+ *
+ * OPTIONAL BY DECLARATION (RV-11). All three adapters populate `usage` before
+ * yielding `done`, but the field is `usage?` on `AssistantMessage`, and
+ * `computeCost(undefined, cost)` is a NaN that reaches the status bar and stays
+ * there for the session.
+ */
+export declare function usageOf(message: AssistantMessage | undefined): {
+    usage: TokenUsage;
+    missing: boolean;
+};
+export declare function accumulateUsage(total: TokenUsage, next: TokenUsage): TokenUsage;
+export interface ReviewRequestParams {
+    ref: ModelRef;
+    apiKey: string;
+    digest: string;
+    /** `fast.reviewMaxChars` — the ceiling the system prompt states. */
+    reviewMaxChars: number;
+    /** Created and owned by `reviewer.ts`; forwarded into `withRetry` from there. */
+    signal: AbortSignal;
+    now: number;
+}
+/**
+ * The request one review sends. NO TOOLS, no thinking, one bounded user message.
+ */
+export declare function buildReviewRequest(params: ReviewRequestParams): LLMRequest;
+export interface ReviewCallParams extends ReviewRequestParams {
+    complete(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
+    /**
+     * Fired when `reviewTimeoutMs` elapses.
+     *
+     * THE CALLER ABORTS, NOT THIS MODULE. `reviewer.ts` implements this as "stamp
+     * `callAbortReason = 'timeout'`, then abort", which is what keeps a timeout
+     * (a strike) distinguishable from a cancellation (not a strike) once the retry
+     * layer has flattened both into the same bare `Error` — see the file header.
+     */
+    onTimeout(): void;
+}
+export type ReviewCallOutcome = {
+    ok: true;
+    message: AssistantMessage;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * Send one review and bound it in time.
+ *
+ * THE TIMEOUT IS AUTHORITATIVE OVER THE RETRY LAYER'S SLEEP, and that is not
+ * automatic (RV-H12). The fast registry spreads `DEFAULT_RETRY_POLICY`, so it
+ * inherits `respectRetryAfter: true`, and a `Retry-After` is applied with
+ * `Math.max` AFTER the `maxDelayMs` clamp (`retry.ts:316-324`) — one honoured
+ * retry may therefore ask to sleep up to the 60 s `retryAfterCeilingMs`. Two
+ * inherited properties stop that from pinning the single-flight slot for a
+ * minute: `defaultSleep` resolves on either the timer or the signal's `abort`
+ * (`retry.ts:417-427`, guard G2), and the `signal` this request carries is
+ * forwarded into `withRetry` by `ProviderRegistry.stream()`. A change to either
+ * is a change to this design.
+ */
+export declare function runReviewCall(params: ReviewCallParams): Promise<ReviewCallOutcome>;

package/dist/fast/review-call.js

@@ -0,0 +1,130 @@
+/**
+ * The bounded review call (fast-model-tier §3.5.3, extracted here by
+ * fast-model-tier-hardening W3).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THIS MODULE DOES NOT OWN AN `AbortController`, AND THAT IS A P0 PROHIBITION
+ * RATHER THAN AN OVERSIGHT (RV-H1 / AC-H16). Encapsulating a controller with the
+ * call it aborts is correct everywhere else in this codebase, which is exactly
+ * why it has to be forbidden in writing here:
+ *
+ *   - `callAbort` and `callAbortReason` are SHARED MUTABLE STATE between the
+ *     call and the lifecycle. The call arms them and reads the reason in its
+ *     catch; `cancelCall()` — reached from `abort()`, `endRun()` and
+ *     `dispose()` — stamps `'cancelled'` BEFORE aborting.
+ *   - Once the controller is private to this module, that stamp becomes
+ *     impossible, every cancelled review falls into the failure branch, and each
+ *     one scores a strike. Three ordinary runs then self-disable the tier for the
+ *     rest of the session behind a warn quoting an internal stream message.
+ *   - It cannot be recovered at the catch: the retry layer returns SILENTLY on
+ *     abort (`retry.ts` G3, deliberately — a user Esc must not be blamed on the
+ *     network), so a cancellation and a timeout arrive as byte-identical bare
+ *     `Error`s carrying no `errorType`.
+ *
+ * ROUND 1 SHIPPED THAT DEFECT AND FIXED IT AS IF-7. So this module RECEIVES the
+ * signal and a timeout callback, and returns an outcome. It does not create,
+ * own, or classify the abort. `fast-reviewer.test.ts`'s cancellation cases are
+ * the behavioural guard; they were written before this file existed.
+ */
+import { FAST_LIMITS } from './limits.js';
+import { buildReviewSystemPrompt } from './prompt.js';
+/**
+ * The two `LLMErrorType`s the retry layer classifies as retryable.
+ *
+ * THESE ARE TRANSIENT AND DO NOT COUNT AS STRIKES (D-24 / R-17). Self-disabling
+ * exists for a MISCONFIGURED tier - a wrong model id, a dead gateway, a key with
+ * no access - because that is the case a user must be told about, since it will
+ * never fix itself. A fast provider that is merely busy for ninety seconds is
+ * the opposite. This matters MORE since round 2 gave the reviewer a fail-fast
+ * registry (W2): fewer retries means transients surface more often, so the
+ * strike counter must keep ignoring them or the fail-fast policy would cause the
+ * self-disable round 1 worked to prevent.
+ */
+const TRANSIENT_ERROR_TYPES = new Set(['rate_limit', 'overloaded']);
+/** The assistant text of a completion, or `''` for a tool-only answer. */
+export function assistantText(message) {
+    if (!message || !Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('')
+        .trim();
+}
+export function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Whether a failure is the provider being busy rather than the tier being wrong. */
+export function classifyReviewFailure(err) {
+    const raw = err?.errorType;
+    const errorType = typeof raw === 'string' ? raw : 'unknown';
+    return { errorType, transient: TRANSIENT_ERROR_TYPES.has(errorType) };
+}
+/**
+ * The review's spend.
+ *
+ * OPTIONAL BY DECLARATION (RV-11). All three adapters populate `usage` before
+ * yielding `done`, but the field is `usage?` on `AssistantMessage`, and
+ * `computeCost(undefined, cost)` is a NaN that reaches the status bar and stays
+ * there for the session.
+ */
+export function usageOf(message) {
+    const usage = message?.usage;
+    return {
+        usage: usage ?? { inputTokens: 0, outputTokens: 0 },
+        missing: usage === undefined,
+    };
+}
+export function accumulateUsage(total, next) {
+    return {
+        inputTokens: total.inputTokens + next.inputTokens,
+        outputTokens: total.outputTokens + next.outputTokens,
+    };
+}
+/**
+ * The request one review sends. NO TOOLS, no thinking, one bounded user message.
+ */
+export function buildReviewRequest(params) {
+    return {
+        model: params.ref.modelId,
+        ...(params.ref.baseUrl ? { baseUrl: params.ref.baseUrl } : {}),
+        apiKey: params.apiKey,
+        systemPrompt: buildReviewSystemPrompt({ maxChars: params.reviewMaxChars }),
+        messages: [{ role: 'user', content: params.digest, timestamp: params.now }],
+        maxTokens: FAST_LIMITS.reviewOutputTokens,
+        // PAIRED WITH `temperature: 0` ON PURPOSE: the Anthropic adapter deletes
+        // `temperature` whenever a thinking budget is set (`anthropic.ts:395-402`),
+        // so these two are one choice and not two.
+        thinkingLevel: 'off',
+        temperature: 0,
+        signal: params.signal,
+    };
+}
+/**
+ * Send one review and bound it in time.
+ *
+ * THE TIMEOUT IS AUTHORITATIVE OVER THE RETRY LAYER'S SLEEP, and that is not
+ * automatic (RV-H12). The fast registry spreads `DEFAULT_RETRY_POLICY`, so it
+ * inherits `respectRetryAfter: true`, and a `Retry-After` is applied with
+ * `Math.max` AFTER the `maxDelayMs` clamp (`retry.ts:316-324`) — one honoured
+ * retry may therefore ask to sleep up to the 60 s `retryAfterCeilingMs`. Two
+ * inherited properties stop that from pinning the single-flight slot for a
+ * minute: `defaultSleep` resolves on either the timer or the signal's `abort`
+ * (`retry.ts:417-427`, guard G2), and the `signal` this request carries is
+ * forwarded into `withRetry` by `ProviderRegistry.stream()`. A change to either
+ * is a change to this design.
+ */
+export async function runReviewCall(params) {
+    const timer = setTimeout(params.onTimeout, FAST_LIMITS.reviewTimeoutMs);
+    try {
+        const message = await params.complete(params.ref.providerId, buildReviewRequest(params));
+        return { ok: true, message };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}