@aragon-agent/cli 0.5.8 → 0.5.9

package/dist/agent/reducer.d.ts

@@ -13,7 +13,10 @@
 import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agent/core';
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
+import type { FastReview, FastSnapshot } from '../fast/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
+import type { RetryPhase } from './retry-view.js';
+import type { FilePatch } from '../tools/patch.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
 export type Overlay = null | 'settings' | 'model' | 'help' | 'confirm' | 'question' | 'plan';
@@ -40,6 +43,21 @@ export type Entry = {
     streaming: boolean;
     aborted?: boolean;
     usage?: TokenUsage;
+    /**
+     * Epoch ms the turn started reasoning (agent-activity-presentation §3.1.2).
+     * Set by `thinkingStart`, cleared by `streamRestart`.
+     */
+    thinkingStartedAt?: number;
+    /**
+     * Wall-clock reasoning time, SEALED ONCE — at the first text delta, or at
+     * turn/run end for a turn that thought and then called a tool without
+     * emitting any text.
+     *
+     * With thinking hidden this is the only thing the collapsed marker can say
+     * that the user could not otherwise know, which is the whole argument for
+     * having a marker at all (§1.2).
+     */
+    thinkingMs?: number;
 } | {
     id: string;
     kind: 'tool';
@@ -52,6 +70,44 @@ export type Entry = {
     preview?: string;
     durationMs?: number;
     isError?: boolean;
+    /**
+     * The structured file diff (agent-activity-presentation §3.3), or absent.
+     *
+     * IMMUTABLE AND WRITTEN ONCE, by `toolExecEnd`. `ToolCard` is `React.memo`'d
+     * with the DEFAULT comparator, so this object is only free while its
+     * reference is stable — which it is, because the reducer never rebuilds it
+     * and `mapEntry` preserves identity for untouched entries. A future action
+     * that recomputed or normalized a patch would turn that memo boundary into
+     * a no-op WITH NOTHING FAILING (P2-9).
+     *
+     * Needs no clause in `normalizeLoadedEntries` (D-9): the four that exist
+     * are all about a LIVE flag that would never settle, and a patch is settled
+     * by construction.
+     */
+    patch?: FilePatch;
+    /**
+     * The sanitised live tail while the tool runs
+     * (agent-activity-presentation-live §3.3.1). Cleared at settle (D-23), and
+     * cleared again by EVERY path that reaches `status: 'idle'` (D-35).
+     *
+     * REDUCER STATE RATHER THAN A STORE READ DURING RENDER, and that is the
+     * load-bearing decision of the round (D-22): `entryRevision` is what tells
+     * the height cache an entry's rendered output changed, and an entry mutated
+     * outside `ViewState` keeps its revision and freezes at a stale height AND
+     * a stale subtree with nothing anywhere reporting it (I-L3-1).
+     */
+    live?: readonly string[];
+    /**
+     * Monotonic counter -- the revision term for a NON-APPEND mutation (D-22).
+     *
+     * A COUNTER AND NOT `live.length`: a fixed-size tail evicting its oldest
+     * row while appending a new one of the same width leaves the joined length
+     * unchanged, which is exactly the lossy case `virtual-window.ts` says the
+     * reducer cannot produce today and that this round introduces.
+     */
+    liveSeq?: number;
+    /** Epoch ms of the last output row, for the stall row (§3.3.4). */
+    lastOutputAt?: number;
 } | {
     id: string;
     kind: 'notice';
@@ -107,12 +163,85 @@ export type Entry = {
      * card this session produced.
      */
     interrupted?: boolean;
+}
+/**
+ * The turn's retry story (llm-api-retry-backoff §6.4). ONE per turn, REWRITTEN
+ * IN PLACE — ten retries rendered as ten notices would bury the transcript in
+ * the one moment the user most needs it legible.
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
+ *
+ * `phase: 'waiting' | 'retrying'` is normalized away ON LOAD, in
+ * `session/persist.ts`, exactly as the team entry's `active` and the todo
+ * card's `live` are (R-10): `Transcript`'s settled boundary is MONOTONIC, so a
+ * card that never settles never reaches `<Static>` and is re-rendered on every
+ * frame for the rest of the session.
+ */
+ | {
+    id: string;
+    kind: 'retry';
+    /** 1-based retry index of the LATEST attempt this card has seen. */
+    attempt: number;
+    maxRetries: number;
+    errorType: string;
+    message: string;
+    delayMs: number;
+    /** Epoch ms the next attempt fires; the UI ticks against this. */
+    resumeAt?: number;
+    phase: RetryPhase;
+    startedAt: number;
+    /** Filled on settle. */
+    totalRetries?: number;
+    elapsedMs?: number;
+}
+/**
+ * One fast-model review (fast-model-tier §5.4). ONE CARD PER REVIEW, never
+ * rewritten across reviews — a critique is a single event, unlike the todo
+ * card's per-turn checklist.
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
+ *
+ * `live: true` is normalized away ON LOAD, in `session/persist.ts`, next to
+ * `team.active`, `todo.live` and the retry card's phase, and for the identical
+ * reason (C-5): `Transcript`'s settled boundary is MONOTONIC, so an entry that
+ * never settles never reaches `<Static>` and is re-rendered on every frame for
+ * the rest of the session. The reducer never legitimately sees a stale-live
+ * entry — only the file does.
+ */
+ | {
+    id: string;
+    kind: 'fast';
+    /** 1-based within the session, so the card can name itself. */
+    reviewIndex: number;
+    model: string;
+    status: 'running' | 'ok' | 'advice' | 'empty' | 'failed' | 'dropped';
+    /** Present only for `advice`. */
+    text?: string;
+    /** Failure / drop reason, shown as one muted line. */
+    detail?: string;
+    turn: number;
+    durationMs?: number;
+    live: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
     outputTokens: number;
     costUsd: number;
 }
+/**
+ * The ephemeral retry projection held in `ViewState.retry` (§9).
+ *
+ * Only the two IN-FLIGHT phases exist here: once a card settles the projection is
+ * `null`, because the settled card IS the history and a chip that reported a
+ * finished retry would never go away.
+ */
+export interface RetrySnapshot {
+    attempt: number;
+    maxRetries: number;
+    resumeAt?: number;
+    phase: 'waiting' | 'retrying';
+    errorType: string;
+}
 export interface ViewState {
     entries: Entry[];
     status: 'idle' | 'running';
@@ -150,11 +279,32 @@ export interface ViewState {
      * build (AC-24).
      */
     todos: TodoSnapshot | null;
+    /**
+     * The live retry projection, or `null` when nothing is retrying.
+     *
+     * NEVER PERSISTED — `entries` is the history and the settled card is the
+     * record. It drives the status-bar chip and the 1 Hz tick, and it is nulled on
+     * every settle path. Same contract as `team`.
+     */
+    retry: RetrySnapshot | null;
+    /**
+     * The live fast-tier projection, or `null` when the tier is off for this
+     * session (fast-model-tier §5.2).
+     *
+     * NEVER PERSISTED — `entries` is the history and the settled cards are the
+     * record. It drives the status chip and `/fast status`'s totals. `null` is
+     * what leaves an ordinary session's status bar byte-identical (AC-4).
+     */
+    fast: FastSnapshot | null;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
     /** The `kind: 'todo'` entry this turn is writing into. */
     todoEntryId?: string;
+    /** The `kind: 'retry'` entry this turn is writing into. */
+    retryEntryId?: string;
+    /** The `kind: 'fast'` entry the in-flight review is writing into. */
+    fastEntryId?: string;
     streamingId?: string;
     turnProduced: boolean;
     errorNoticed: boolean;
@@ -169,7 +319,24 @@ export interface ViewState {
      */
     droppedEntries: number;
 }
-export declare function initialViewState(): ViewState;
+export interface ViewStateSeed {
+    /** Start with thinking blocks expanded. Defaults to FALSE, the product default. */
+    thinkingVisible?: boolean;
+}
+/**
+ * The initial view state, optionally seeded from config.
+ *
+ * THE DEFAULT IS `false`, NOT `true`, AND THAT IS THE WHOLE SAFETY ARGUMENT
+ * (D-2). There is exactly one production call site — `App`'s `useReducer`, which
+ * passes `cfg.showThinking`. Every other caller is a test. A future call site
+ * that forgets the seed fails CLOSED, toward the product default, rather than
+ * silently restoring the reasoning firehose for one code path with nothing
+ * reporting it.
+ *
+ * The seed is a PARAMETER rather than a post-mount dispatch so that `/resume`
+ * cannot flash a restored thinking block on frame 1.
+ */
+export declare function initialViewState(seed?: ViewStateSeed): ViewState;
 export type ViewAction = {
     type: 'submit';
     text: string;
@@ -207,6 +374,22 @@ export type ViewAction = {
     isError: boolean;
     duration: number;
     preview: string;
+    /** A fully-built, immutable diff, so the reducer stays pure (§3.3.7). */
+    patch?: FilePatch;
+}
+/**
+ * A running tool's live tail (agent-activity-presentation-live §3.3.1).
+ *
+ * `rows` IS THE WHOLE TAIL, not an increment: the store replaces it on every
+ * chunk, which is what lets `mergeDeltas` keep only the last action per
+ * `toolCallId` (D-30). `at` is read in `App`'s listener rather than here, so
+ * this reducer stays pure.
+ */
+ | {
+    type: 'toolOutputDelta';
+    toolCallId: string;
+    rows: readonly string[];
+    at: number;
 } | {
     type: 'turnEnd';
     usage: TokenUsage;
@@ -266,6 +449,54 @@ export type ViewAction = {
     snapshot: TodoSnapshot;
 } | {
     type: 'todoCleared';
+} | {
+    type: 'retryScheduled';
+    attempt: number;
+    maxRetries: number;
+    delayMs: number;
+    resumeAt: number;
+    errorType: string;
+    message: string;
+} | {
+    type: 'retryAttempt';
+    attempt: number;
+    maxRetries: number;
+} | {
+    type: 'streamRestart';
+    discardedToolCallIds: string[];
+}
+/**
+ * The 1 Hz countdown tick. NO STATE OF ITS OWN — it bumps `seq` so the frame
+ * re-renders and the card recomputes `resumeAt - Date.now()`. `App` runs the
+ * interval ONLY while `state.retry?.phase === 'waiting'`, so an idle session has
+ * no timer at all.
+ */
+ | {
+    type: 'retryTick';
+} | {
+    type: 'fastStart';
+    index: number;
+    turn: number;
+    model: string;
+} | {
+    type: 'fastEnd';
+    review: FastReview;
+}
+/**
+ * Review spend.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as `teamUsage`'s is: the
+ * reducer stays pure and cost-table-free, which is the property that makes it
+ * testable — and the fast tier has a DIFFERENT cost table from the lead, so a
+ * reducer that computed its own would have to know about both (§3.6 / R-7).
+ */
+ | {
+    type: 'fastUsage';
+    usage: TokenUsage;
+    costDelta: number;
+} | {
+    type: 'fastTier';
+    snapshot: FastSnapshot;
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;
@@ -284,12 +515,23 @@ export declare const PREVIEW_TRUNCATION_MARK = "...";
  * over-promises how much more is expandable.
  */
 export declare function buildToolPreview(result: ToolResult): string;
+/**
+ * Where a `FilePatch` is collected from on `tool_execution_end`.
+ *
+ * Supplying one makes `reduceEvent` CONSUME-ONCE rather than pure, which is safe
+ * because `App.tsx` calls it exactly once per event and `mergeDeltas` only ever
+ * merges `textDelta` / `thinkingDelta`, never `toolExecEnd`.
+ */
+export interface PatchSource {
+    take(toolCallId: string): FilePatch | undefined;
+}
 /**
  * Map one core `AgentEvent` to view actions. `cost` (the active model's cost
  * table) lets `turn_end` accumulate USD cost; omit it in tests that only assert
- * token totals.
+ * token totals. `patches` is the CLI-local diff side channel (§3.3.7); omitting
+ * it — every existing test, and headless mode — produces byte-identical actions.
  */
-export declare function reduceEvent(event: AgentEvent, cost?: ModelCost): ViewAction[];
+export declare function reduceEvent(event: AgentEvent, cost?: ModelCost, patches?: PatchSource): ViewAction[];
 /** Turn a provider error into a friendly banner, mapping LLMError.errorType. */
 export declare function formatStreamError(error: Error): string;
 export declare function viewReducer(state: ViewState, action: ViewAction): ViewState;