@aragon-agent/cli 0.5.8 → 0.5.9

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);
+    }
+}

package/dist/fast/reviewer.d.ts

@@ -0,0 +1,248 @@
+/**
+ * FastReviewer — the periodic asynchronous review (fast-model-tier §3.5).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THE ENTIRE CLASS IS SHAPED AROUND *WHEN* IT IS ALLOWED TO SPEAK.
+ * `Agent.steer()` pushes onto a queue that `runAgentLoop` drains at three
+ * places, and only one of them is safe:
+ *
+ *   1  top of the loop, before the LLM call (`agent-loop.ts:126`) - pushed as a
+ *      `user` message, conversation shape stays valid. SAFE.
+ *   2  after the LLM call, before tool execution (`:199`) - `continue`, leaving
+ *      the assistant's `tool_use` blocks with no `tool_result`. Anthropic then
+ *      rejects the NEXT request with HTTP 400. HARD FAILURE.
+ *   3  between two tool executions (`:214`) - every remaining call in the batch
+ *      is replaced with "Tool execution skipped due to steering interrupt."
+ *      SILENTLY DESTRUCTIVE.
+ *
+ * For a human pressing Enter mid-run, 2 and 3 are the DESIRED semantics. For an
+ * unrequested background critique they are a defect generator whose symptoms
+ * (an HTTP 400 about tool_result ids; work silently deleted) point nowhere near
+ * the reviewer. So this class calls `steer()` from EXACTLY ONE PLACE: inside the
+ * synchronous listener for the `tool_execution_end` that brings the batch to
+ * zero. `Agent.emit()` runs listeners synchronously inside the loop
+ * (`agent.ts:340`), the batch is finished, and the next `hasSteering()` the loop
+ * evaluates is therefore checkpoint 1 (AC-20).
+ *
+ * AND STEERING IS NOT DELIVERY (§3.5.4a / RV-1 / D-19). `steer()` only enqueues;
+ * `runLoopWithLifecycle`'s `finally` never clears the queues (`agent.ts:410`);
+ * and the loop emits the batch's last `tool_execution_end` (`:249`) BEFORE it
+ * re-tests the abort signal (`:271`). So an Esc landing inside the final tool's
+ * `await` yields exactly the interleaving where the reviewer steers, the loop
+ * breaks, and the block resurfaces in the user's NEXT conversation wearing the
+ * user's role. Two guards close it:
+ *
+ *   guard 1  do not steer into a REQUESTED abort (`isAbortRequested`).
+ *   guard 2  prove delivery. `awaitingDrain` is set on steer and cleared at the
+ *            next `turn_start` - the loop cannot reach `turn_start` (`:136`)
+ *            without having passed checkpoint 1 (`:126`), so `turn_start` IS the
+ *            receipt. Still true at `agent_end` means the block was stranded.
+ *
+ * Guard 2 exists because the idle watchdog calls `Agent.abort()` DIRECTLY
+ * (`watchdog.ts:15-17`), where no controller-level flag can see it (D-20) - and
+ * the watchdog fires precisely on the long quiet runs where a review is most
+ * likely to be pending.
+ *
+ * A future refactor that moves `steer()` into the `complete()` callback will
+ * look tidier and will reintroduce all of the above.
+ *
+ * WHAT WAS SPLIT OUT, AND WHAT DELIBERATELY WAS NOT (hardening W3 / §3.3).
+ * The turn-frame ring moved to `frames.ts` and the bounded call to
+ * `review-call.ts`, both leaves. THE PROTOCOL STAYED HERE, WHOLE: the two drain
+ * guards above (AC-H11) and the call-cancellation stamping - `callAbort`,
+ * `callAbortReason`, `cancelCall()` and the one `new AbortController()`
+ * (AC-H16). A split that puts half of either behind a module boundary is a
+ * "simplification" that reopens a P0, and in the cancellation case it is round
+ * 1's IF-7 verbatim; `review-call.ts`'s header states why.
+ */
+import type { AgentEvent, AssistantMessage, LLMRequest, TokenUsage } from '@aragon-agent/core';
+import type { FastConfig } from '../config/schema.js';
+import type { NoticeLevel } from '../agent/reducer.js';
+import type { FastEvent, FastTier } from './types.js';
+/**
+ * Everything the reviewer needs from the rest of the world.
+ *
+ * ALL INJECTED, so `fast-reviewer.test.ts` can replay a scripted `AgentEvent`
+ * sequence against a stub `complete` and assert the injection window without a
+ * network, a terminal or an `Agent` (§8.1).
+ */
+export interface FastReviewerDeps {
+    /** The LEAD agent's event stream, through `AgentController` (C-7). */
+    subscribe(listener: (event: AgentEvent) => void): () => void;
+    /**
+     * `ProviderRegistry.complete` — bound since round 2 to `FastWiring`'s OWN
+     * fail-fast registry, not to the lead's (W2 / §3.2). Nothing in this file
+     * knows that, which is the whole reason the dep is injected.
+     */
+    complete(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
+    /** `AgentController.steer` - the ONLY writer of the queue besides the user. */
+    steer(text: string): void;
+    isRunning(): boolean;
+    /** Guard 1: `AgentController.abort()` sets this synchronously BEFORE
+     *  `agent.abort()`, so the reviewer can see an Esc that has not landed yet. */
+    isAbortRequested(): boolean;
+    /** Guard 2: user messages queued since the last `turn_start`. `0` is what
+     *  makes `clearAllQueues()` provably safe (D-21). */
+    userSteerCount(): number;
+    clearAllQueues(): void;
+    /** Re-read at EVERY use, never snapshot (RV-3). */
+    getTier(): FastTier;
+    getConfig(): FastConfig;
+    /** `FastWiring.available()` - the live predicate of §3.3. */
+    available(): boolean;
+    getApiKey(providerId: string): string | undefined;
+    emit(event: FastEvent): void;
+    notify(level: NoticeLevel, text: string): void;
+    /** Injected clock. A test that reads the wall clock fails on a slow machine
+     *  and nowhere else - the reason `TodoStore` and `TeamPanel` take one. */
+    now?: () => number;
+}
+export declare class FastReviewer {
+    private readonly deps;
+    /** Scope `fast` since round 2 (W4): an unrequested background call is not one
+     *  of the LEAD's records, and a support reader filtering `agent` wants those. */
+    private readonly log;
+    private readonly now;
+    private unsubscribe;
+    private disposed;
+    private runId;
+    /** The turn-frame ring (`frames.ts`). Owns `turns`, the open frame and the
+     *  outstanding-call counter; decides nothing. */
+    private readonly ring;
+    private inFlight;
+    private pending;
+    private reviewsThisRun;
+    /** Set on steer, cleared at the next `turn_start`. Guard 2's receipt. */
+    private awaitingDrain;
+    private awaitingReviewIndex;
+    /** The run's own abort channel for an in-flight `complete()`. */
+    private callAbort;
+    /**
+     * WHY the in-flight call was aborted - RECORDED here because it cannot be
+     * recovered from the error: a timeout and a cancellation go through the same
+     * `controller.abort()` and arrive as byte-identical bare `Error`s. The full
+     * argument, and the prohibition it implies for `review-call.ts`, is in that
+     * file's header; this field and `cancelCall()` are the halves it protects.
+     */
+    private callAbortReason;
+    private goal;
+    /**
+     * Reviews STARTED this session. NEVER RESET (§3.1.1).
+     *
+     * This is BOTH the status line's numerator and the session budget's left-hand
+     * side, on purpose: a parallel `reviewsThisSession` would be a second answer
+     * to one question, and the first time the two drifted the product would print
+     * `12/40` while suppressing at a number nobody can see.
+     */
+    private reviewIndex;
+    /** The limit at which exhaustion was last announced; `-1` = not announced.
+     *  Keyed on the LIMIT, not on a boolean, so raising the budget re-arms the
+     *  notice without a second latch to keep in sync (§3.1.3). */
+    private budgetAnnouncedAt;
+    private consecutiveFailures;
+    private selfDisabled;
+    private usage;
+    constructor(deps: FastReviewerDeps);
+    /** The user's request for this run, captured in `AgentController.prompt()`. */
+    setGoal(text: string): void;
+    /** Reviews STARTED this session, for `/fast status` and `FastSnapshot`. */
+    reviewCount(): number;
+    /** The live session budget, read from config so `/fast budget <n>` takes
+     *  effect on the next sealed frame with no restart. */
+    budgetLimit(): number;
+    /** Carried on the snapshot rather than re-derived by callers (RV-H10). */
+    isBudgetReached(): boolean;
+    sessionUsage(): TokenUsage;
+    isReviewInFlight(): boolean;
+    /**
+     * `AgentController.abort()`.
+     *
+     * Aborts the in-flight call and drops `pending`. It MUST NOT clear
+     * `awaitingDrain`: that flag is guard 2's receipt and is resolved only at
+     * `turn_start` (delivered) or `agent_end` (stranded).
+     */
+    abort(): void;
+    /**
+     * Cancel an in-flight review because nobody wants the answer any more.
+     *
+     * A CANCELLATION IS NOT A FAILURE (§3.5.5). The three callers - `endRun()`
+     * (the run finished first), `abort()` (Esc) and `dispose()` - all mean "never
+     * mind", and none of them is evidence of a MISCONFIGURED tier, which is the
+     * only thing self-disable exists for (D-18 / D-24). Scoring them as strikes
+     * silently killed the reviewer for the rest of a session over three ordinary
+     * runs - the common shape, since a turn that answers without tools ends the
+     * run - behind a warn quoting an internal stream message (IF-7).
+     *
+     * THE STAMP MUST HAPPEN HERE, BEFORE THE ABORT, AND THE CONTROLLER MUST STAY
+     * REACHABLE FROM THIS METHOD (AC-H16).
+     */
+    private cancelCall;
+    /** Idempotent. Unsubscribes as well as aborting. */
+    dispose(): void;
+    private onAgentEvent;
+    private beginRun;
+    private onTurnStart;
+    private onToolEnd;
+    private endRun;
+    /**
+     * Remove a block that was steered and never delivered.
+     *
+     * THE ASYMMETRY IS DELIBERATE (D-21): the reviewer may always destroy its own
+     * message and may NEVER destroy the user's. `Agent` exposes no way to remove
+     * one entry - only `clearAllQueues()` - so removal is permitted only while the
+     * reviewer can PROVE it owns the whole queue, which `userSteerCount() === 0`
+     * establishes: `AgentController.steer()` is the only other writer in the
+     * package and the counter resets at every `turn_start`.
+     *
+     * With a user steer queued it clears NOTHING and warns. The residue is
+     * bounded, rare, labelled by its own `<fast_review turn model>` wrapper, and -
+     * unlike v1 - reported.
+     */
+    private recoverStranded;
+    /** Whether another review could still be STARTED this run. */
+    private canReviewAgain;
+    private maybeStartReview;
+    /**
+     * Say it once per limit value, and say what is NOT affected.
+     *
+     * `info`, NOT `warn` (D-H6): D-24 reserves the alarming register for a
+     * MISCONFIGURED tier, because that is the case that never fixes itself. A
+     * budget reached is the system working as configured, and warning here would
+     * train the user to ignore the register that matters.
+     *
+     * NEITHER `consecutiveFailures` NOR `selfDisabled` IS TOUCHED. A budget stop
+     * is neither a success that clears the strike counter nor a failure that
+     * raises it - the exact distinction IF-7 was filed for, applied to a second
+     * cause. And the reviewer is not broken: it must revive the moment the budget
+     * rises, which `budgetLimit()` reading live config is what delivers.
+     *
+     * NO TRANSCRIPT CARD, and that is a correctness requirement rather than a
+     * styling choice (§3.1.3). R-8 ("it did nothing" is never the observable
+     * outcome) governs a review that STARTED; every such path emits a `FastReview`
+     * carrying an `index`, and indices come from `this.reviewIndex += 1`. Minting
+     * one here would advance the very counter `/fast status` renders as the
+     * numerator, so the first suppression would display `41/40`.
+     */
+    private announceBudgetReached;
+    private currentModelId;
+    private runReview;
+    /**
+     * A review nobody is waiting for any more.
+     *
+     * It still has to produce a TERMINAL card. `review_start` already put a
+     * `running` entry in the transcript, and `Transcript`'s settled boundary is
+     * monotonic (C-5) - an entry that never settles is re-rendered on every frame
+     * for the rest of the session. "It did nothing" is also never allowed to be
+     * the observable outcome (R-8).
+     *
+     * `consecutiveFailures` is left EXACTLY as it was: a cancellation is neither a
+     * success that clears the count nor a failure that raises it.
+     */
+    private onReviewCancelled;
+    private onReviewAnswer;
+    private onReviewFailure;
+    private maybeInject;
+    private dropPending;
+    private emitReview;
+}