@aragon-agent/cli 0.5.6 → 0.5.9

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