@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/agent/retry-view.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Retry presentation — pure, React-free, unit-tested (llm-api-retry-backoff
+ * §6.5 / §6.6).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`). Every non-ASCII character in the rendered line comes from
+ * the `Glyphs` set the caller passes in, never from a literal here.
+ *
+ * The COUNTDOWN is derived from `resumeAt`, an absolute instant, and never from
+ * `delayMs`. Core deliberately sends the instant rather than a tick stream, so
+ * the clock belongs to whoever renders — and a card that recomputed from
+ * `delayMs` would freeze at the announced number the moment a frame was skipped.
+ */
+import type { Glyphs } from '../ui/glyphs.js';
+/**
+ * Presentation bounds. NAMED `RETRY_UI`, NOT `RETRY_LIMITS_UI`: core's
+ * `RETRY_LIMITS` bounds what the mechanism can physically do, this is a column
+ * breakpoint, and a name that read as its sibling would invite the next reader to
+ * look here for the missing keys.
+ */
+export declare const RETRY_UI: {
+    /** Below this many columns the status-bar chip degrades to `[r3]`. */
+    readonly statusCompactCols: 100;
+};
+/** The five phases of the one card a turn gets. */
+export type RetryPhase = 'waiting' | 'retrying' | 'recovered' | 'exhausted' | 'interrupted';
+/** The shape `formatRetryLine` reads — the `kind: 'retry'` entry, structurally. */
+export interface RetryLineInput {
+    attempt: number;
+    maxRetries: number;
+    errorType: string;
+    phase: RetryPhase;
+    resumeAt?: number;
+    totalRetries?: number;
+    elapsedMs?: number;
+}
+/**
+ * Whole seconds until `resumeAt`, floored at 0.
+ *
+ * `Math.ceil` rather than `round`: a countdown that shows `0s` for half a second
+ * before firing reads as a stall, and showing `1s` for slightly too long does
+ * not.
+ */
+export declare function secondsLeft(resumeAt: number | undefined, now: number): number;
+/**
+ * A short headline for a provider failure.
+ *
+ * Deliberately shorter than `formatStreamError`'s: that one is a standalone
+ * notice and has to explain what to do, while this shares one line with a
+ * counter and a countdown. Derived from `errorType` ONLY — nothing here parses
+ * the provider's message, because a human-facing sentence must never become a
+ * machine-readable contract (the rule `SubagentRun.retryable` records).
+ */
+export declare function retryHeadline(errorType: string): string;
+/**
+ * The card's single line, WITHOUT the rail glyph — `EntryView` supplies that, the
+ * same way it does for every other entry kind.
+ *
+ * `now` is a parameter rather than a `Date.now()` call so the function stays pure
+ * and the render can be asserted without a clock.
+ */
+export declare function formatRetryLine(entry: RetryLineInput, glyphs: Glyphs, now: number): string;
+/** The status-bar chip text: full at width, `[r3]` when the row is tight. */
+export declare function formatRetryChip(active: {
+    attempt: number;
+    max: number;
+    secondsLeft: number;
+}, cols: number): string;

package/dist/agent/retry-view.js

@@ -0,0 +1,95 @@
+/**
+ * Retry presentation — pure, React-free, unit-tested (llm-api-retry-backoff
+ * §6.5 / §6.6).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`). Every non-ASCII character in the rendered line comes from
+ * the `Glyphs` set the caller passes in, never from a literal here.
+ *
+ * The COUNTDOWN is derived from `resumeAt`, an absolute instant, and never from
+ * `delayMs`. Core deliberately sends the instant rather than a tick stream, so
+ * the clock belongs to whoever renders — and a card that recomputed from
+ * `delayMs` would freeze at the announced number the moment a frame was skipped.
+ */
+import { formatDuration } from './usage.js';
+/**
+ * Presentation bounds. NAMED `RETRY_UI`, NOT `RETRY_LIMITS_UI`: core's
+ * `RETRY_LIMITS` bounds what the mechanism can physically do, this is a column
+ * breakpoint, and a name that read as its sibling would invite the next reader to
+ * look here for the missing keys.
+ */
+export const RETRY_UI = {
+    /** Below this many columns the status-bar chip degrades to `[r3]`. */
+    statusCompactCols: 100,
+};
+/**
+ * Whole seconds until `resumeAt`, floored at 0.
+ *
+ * `Math.ceil` rather than `round`: a countdown that shows `0s` for half a second
+ * before firing reads as a stall, and showing `1s` for slightly too long does
+ * not.
+ */
+export function secondsLeft(resumeAt, now) {
+    if (resumeAt === undefined)
+        return 0;
+    return Math.max(0, Math.ceil((resumeAt - now) / 1000));
+}
+/**
+ * A short headline for a provider failure.
+ *
+ * Deliberately shorter than `formatStreamError`'s: that one is a standalone
+ * notice and has to explain what to do, while this shares one line with a
+ * counter and a countdown. Derived from `errorType` ONLY — nothing here parses
+ * the provider's message, because a human-facing sentence must never become a
+ * machine-readable contract (the rule `SubagentRun.retryable` records).
+ */
+export function retryHeadline(errorType) {
+    switch (errorType) {
+        case 'rate_limit':
+            return 'Rate limited by the provider';
+        case 'overloaded':
+            return 'Provider overloaded';
+        case 'server_error':
+            return 'Provider error';
+        case 'network_error':
+            return 'Network error reaching the provider';
+        case 'timeout':
+            return 'The request timed out';
+        default:
+            return 'Provider call failed';
+    }
+}
+function plural(n) {
+    return n === 1 ? 'retry' : 'retries';
+}
+/**
+ * The card's single line, WITHOUT the rail glyph — `EntryView` supplies that, the
+ * same way it does for every other entry kind.
+ *
+ * `now` is a parameter rather than a `Date.now()` call so the function stays pure
+ * and the render can be asserted without a clock.
+ */
+export function formatRetryLine(entry, glyphs, now) {
+    const dot = ` ${glyphs.midDot} `;
+    const counter = `retry ${entry.attempt}/${entry.maxRetries}`;
+    const settled = entry.totalRetries ?? entry.attempt;
+    switch (entry.phase) {
+        case 'waiting':
+            return `${retryHeadline(entry.errorType)}${dot}${counter} in ${secondsLeft(entry.resumeAt, now)}s`;
+        case 'retrying':
+            return `${retryHeadline(entry.errorType)}${dot}${counter} ${glyphs.ellipsis}`;
+        case 'recovered':
+            return `recovered after ${settled} ${plural(settled)}${entry.elapsedMs === undefined ? '' : `${dot}${formatDuration(entry.elapsedMs)}`}`;
+        case 'exhausted':
+            return `${retryHeadline(entry.errorType)}${dot}gave up after ${settled} ${plural(settled)}${entry.elapsedMs === undefined ? '' : `${dot}${formatDuration(entry.elapsedMs)}`}`;
+        case 'interrupted':
+            return `interrupted after ${settled} ${plural(settled)}`;
+    }
+}
+/** The status-bar chip text: full at width, `[r3]` when the row is tight. */
+export function formatRetryChip(active, cols) {
+    if (cols >= RETRY_UI.statusCompactCols) {
+        return `retry ${active.attempt}/${active.max} ${active.secondsLeft}s`;
+    }
+    return `[r${active.attempt}]`;
+}

package/dist/agent/system-prompt.d.ts

@@ -61,6 +61,17 @@ export interface SystemPromptParams {
      * (and `--no-todo`) produce the pre-todo prompt BYTE FOR BYTE.
      */
     todoBlock?: string;
+    /**
+     * The rendered `<fast_tier>` block, or `''` (fast-model-tier §3.8).
+     *
+     * Spliced conditionally exactly as `skillsBlock`, the plan block, `teamBlock`
+     * and `todoBlock` are, which is what keeps I-2 true: `fast.enabled: false`
+     * (and `--no-fast`) produce the pre-feature prompt BYTE FOR BYTE.
+     *
+     * A CHILD'S PROMPT NEVER CARRIES IT: children cannot delegate and are not
+     * reviewed, so `buildSubagentBlock`'s caller leaves this unset.
+     */
+    fastBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -40,6 +40,7 @@ export function buildSystemPrompt(params) {
     const teamBlock = params.teamBlock ?? '';
     const subagentBlock = params.subagentBlock ?? '';
     const todoBlock = params.todoBlock ?? '';
+    const fastBlock = params.fastBlock ?? '';
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
         'You help the user accomplish software-engineering tasks by reasoning step by step and using the provided tools.',
@@ -56,6 +57,7 @@ export function buildSystemPrompt(params) {
         ...(teamBlock ? ['', teamBlock] : []),
         ...(subagentBlock ? ['', subagentBlock] : []),
         ...(todoBlock ? ['', todoBlock] : []),
+        ...(fastBlock ? ['', fastBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

package/dist/cli.js

@@ -23,11 +23,11 @@ import { formatMigrationNotice, migrateLegacyState } from './config/migrate-lega
 import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
 import { migrateStateOutOfConfig } from './config/migrate-state-out-of-config.js';
 import { runHistoryCommand } from './config/history-commands.js';
-import { LOG_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, applyLogConfigSet, applyTeamConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+import { FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -73,6 +73,14 @@ function toFlags(opts) {
         exitTranscript: opts.exitTranscript,
         compact: opts.compact,
         hints: opts.hints,
+        // Without this line the flag never reaches `CliFlags` and `--show-thinking`
+        // is inert -- the failure the `mouse` note below records (P1-2).
+        showThinking: opts.showThinking,
+        // And again for the live tail, one feature later. The pair is declared in
+        // both directions below because `liveToolOutput` is PERSISTED and defaults
+        // to `true`: a lone `--no-live-tool-output` would make commander default
+        // `opts.liveToolOutput` to `true`, which is indistinguishable from silence.
+        liveToolOutput: opts.liveToolOutput,
         // Without this line the flag never reaches `CliFlags` and `--no-mouse` is
         // inert — a failure with no compile error and no runtime error (P1-2).
         mouse: opts.mouse,
@@ -97,11 +105,32 @@ function toFlags(opts) {
         // C-9). A value flag is no less inert than a boolean one when this line is
         // missing.
         todoFollow: opts.todoFollow,
+        // Site three of three for `--retry` / `--retry-max` — five features, same
+        // trap (`mouse` P1-2, `team` P1-4, `todo` C-9, render L4, now retry). A flag
+        // needs the `.option()` declaration below, a field on `CliFlags`, AND a line
+        // here; miss this one and the flag is inert with no compile or runtime error.
+        retry: opts.retry,
+        retryMax: opts.retryMax,
+        // Site three of three for the four `--fast*` flags — SIX features, one trap
+        // (`mouse` P1-2, `team` P1-4, `todo` C-9, render L4, retry, now fast). It
+        // bites hardest here: the tier is OFF by default, so a missing line would
+        // make `--fast` a flag that reports nothing and does nothing.
+        fast: opts.fast,
+        fastModel: opts.fastModel,
+        fastProvider: opts.fastProvider,
+        fastReview: opts.fastReview,
         // `--verbose` is just a shorthand for `--log-level debug`; an explicit
         // `--log-level` still wins, so the two can be combined without surprise.
         logLevel: opts.logLevel ?? (opts.verbose ? 'debug' : undefined),
         logFile: opts.logFile,
         logDir: opts.logDir,
+        // Site three of three for the render-performance flags. A flag needs the
+        // `.option()` declaration below, a field on `CliFlags`, AND a line here;
+        // miss this one and it is inert with no compile error and no runtime error
+        // (`mouse` P1-2, `team` P1-4, `todo` C-9 -- four features, same trap).
+        transcriptRetain: opts.transcriptRetain,
+        renderGovernor: opts.renderGovernor,
+        maxRenderInterval: opts.maxRenderInterval,
     };
 }
 // ---------------------------------------------------------------------------
@@ -239,6 +268,10 @@ function runInteractive(flags, extras = {}) {
             provider: snapshot.provider,
             model: snapshot.model,
             elapsedMs: Date.now() - snapshot.startedAt,
+            // Names what the retain ring removed, so a long session's replay never
+            // starts mid-conversation without saying why (tui-render-performance
+            // L1 / K-6).
+            ...(snapshot.droppedEntries ? { droppedEntries: snapshot.droppedEntries } : {}),
         }));
     };
     if (mode === 'fullscreen') {
@@ -393,10 +426,22 @@ const CONFIG_SET_KEYS = new Set([
     'fullscreen',
     'exitTranscript',
     'transcriptWindow',
+    // tui-render-performance L1 / L4. Listed here AND cased in the switch
+    // below: a key present here but absent there falls through, writes
+    // nothing, and still prints `Set <key> = <value>` (P1-2).
+    'transcriptRetain',
+    'renderGovernor',
+    'maxRenderIntervalMs',
     // Without these two, `density` and `hints` would be settable only as one-shot
     // flags and never persist -- inconsistent with every other config field.
     'density',
     'hints',
+    // agent-activity-presentation §4.1. Listed here AND cased in the switch below,
+    // for the reason `transcriptRetain` records above.
+    'showThinking',
+    // agent-activity-presentation-live §4.1. Listed here AND cased in the switch
+    // below, for the reason `transcriptRetain` and `showThinking` both record.
+    'liveToolOutput',
     // MEMBERSHIP HERE ONLY DECIDES THAT THE KEY IS NOT REJECTED. The `switch`
     // below is what builds the patch, and a key present here but absent there
     // falls through every case, writes nothing, and still prints
@@ -422,6 +467,10 @@ const CONFIG_SET_KEYS = new Set([
     // ceiling, and a key listed here but forgotten there writes nothing while
     // still printing `Set team.enabled = false`.
     ...TEAM_CONFIG_SET_KEYS,
+    // `retry.*` keys are handled by `applyRetryConfigSet`, same reasoning again.
+    ...RETRY_CONFIG_SET_KEYS,
+    // `fast.*` keys are handled by `applyFastConfigSet`, same reasoning again.
+    ...FAST_CONFIG_SET_KEYS,
 ]);
 /**
  * `aragon config set maxTokens <n|auto|default>`.
@@ -476,6 +525,27 @@ function runConfigSet(key, value) {
         process.stdout.write(`Set ${key} = ${String(merged.team[field])}\n`);
         return;
     }
+    const retryPatch = applyRetryConfigSet(key, value);
+    if (retryPatch) {
+        // Echoed from the STORED value for the same reason `team.*` is, and it matters
+        // more here: `config set retry.maxRetries 0` used to be the value that
+        // silently became 10, so reporting the input would have hidden the bug rather
+        // than the fix (R-16).
+        const merged = updatePersistedConfig(retryPatch);
+        const field = key.slice('retry.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.retry[field])}\n`);
+        return;
+    }
+    const fastPatch = applyFastConfigSet(key, value);
+    if (fastPatch) {
+        // Echoed from the STORED value, so `config set fast.reviewEveryTurns 400`
+        // prints the clamped 50 rather than reporting a number that was never
+        // written (AC-13) — the rule `team.*` and `retry.*` each state above.
+        const merged = updatePersistedConfig(fastPatch);
+        const field = key.slice('fast.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.fast[field])}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -509,11 +579,26 @@ function runConfigSet(key, value) {
             patch.exitTranscript = value === 'true' || value === '1';
             break;
         case 'transcriptWindow':
-            patch.transcriptWindow = clampTranscriptWindow(value, 300);
+            patch.transcriptWindow = clampTranscriptWindow(value, DEFAULT_TRANSCRIPT_WINDOW);
+            break;
+        case 'transcriptRetain':
+            patch.transcriptRetain = clampTranscriptRetain(value, DEFAULT_TRANSCRIPT_RETAIN);
+            break;
+        case 'renderGovernor':
+            patch.renderGovernor = value === 'true' || value === '1';
+            break;
+        case 'maxRenderIntervalMs':
+            patch.maxRenderIntervalMs = clampMaxRenderInterval(value, DEFAULT_MAX_RENDER_INTERVAL_MS);
             break;
         case 'density':
             patch.density = clampDensity(value, 'comfortable');
             break;
+        case 'showThinking':
+            patch.showThinking = value === 'true' || value === '1';
+            break;
+        case 'liveToolOutput':
+            patch.liveToolOutput = value === 'true' || value === '1';
+            break;
         case 'hints':
             patch.hints = value === 'true' || value === '1';
             break;
@@ -607,7 +692,16 @@ function buildProgram() {
         .option('--hints', 'Always show the composer hint row')
         .option('--no-hints', 'Hide the composer hint row')
         // Positive form first, same tri-state reason as `--fullscreen` above.
-        .option('--mouse', 'Wheel scrolls the region under the pointer (full-screen mode)')
+        .option('--show-thinking', 'Show the reasoning blocks the model returns')
+        .option('--no-show-thinking', 'Hide reasoning blocks (the default)')
+        // Positive form first, same tri-state reason as `--fullscreen` above. The
+        // pair matters more here than for its neighbour because this key defaults to
+        // ON: a lone negative form would let commander synthesize `true` and
+        // overwrite a stored `false` on every run that passed no flag at all.
+        .option('--live-tool-output', 'Show a running command output tail (the default)')
+        .option('--no-live-tool-output', 'Keep a running tool card to one line')
+        // Positive form first, same tri-state reason as `--fullscreen` above.
+        .option('--mouse', 'Wheel scrolls the transcript (full-screen mode)')
         .option('--no-mouse', 'Leave the mouse to the terminal (the wheel does nothing)')
         // Declaring `--fullscreen` BEFORE `--no-fullscreen` keeps the default
         // `undefined` instead of `true`, which is what makes the tri-state work:
@@ -641,6 +735,22 @@ function buildProgram() {
         // passed, so `!== undefined` in `resolveTodoConfig` already distinguishes it
         // from silence. An unrecognized mode is clamped to `notify`, not rejected.
         .option('--todo-follow <mode>', 'What to do when a run ends with unfinished steps: notify (default) | auto | off')
+        // BOTH FORMS, positive first, for the reason recorded five times above:
+        // `retry.enabled` is PERSISTED, so a lone `--no-retry` would make commander
+        // default `opts.retry` to `true` and silently overwrite a stored `false`.
+        .option('--retry', 'Retry failed provider calls with backoff (the default)')
+        .option('--no-retry', 'Do not retry a failed provider call (fail on the first error)')
+        .option('--retry-max <n>', 'Retries after the first attempt for this run (0-20; 0 = off)')
+        // BOTH FORMS, positive first, for the reason recorded six times above — and
+        // with the polarity reversed from every other pair here: `fast.enabled`
+        // defaults to FALSE, so a lone `--fast` would be indistinguishable from
+        // silence and the off-by-default guarantee (R-d) would rest on a commander
+        // detail rather than on the config layer.
+        .option('--fast', 'Enable the fast model tier for this session')
+        .option('--no-fast', 'Disable the fast model tier (the default)')
+        .option('--fast-model <id>', 'The fast model id (implies nothing about --fast)')
+        .option('--fast-provider <id>', 'Provider for the fast model (default: the main provider)')
+        .option('--fast-review <n|off>', 'Turns between automatic fast reviews, or "off"')
         .option('--no-skills', 'Disable the skill system entirely (no catalog, no skill tools)')
         .option('--skill <name>', 'Force-load a skill at Level 2 for this run (repeatable)', (value, previous = []) => [...previous, value])
         .option('--skills-yes', 'Approve skill installs for this run (CI / headless)')
@@ -654,6 +764,14 @@ function buildProgram() {
         // No short form: `-v` is already `--version`.
         .option('--verbose', 'Shorthand for --log-level debug')
         .option('--log-dir <dir>', 'Absolute log directory for this run')
+        // Render performance (tui-render-performance §5.2). `--render-governor` is
+        // declared BEFORE its negative form for the tri-state reason recorded four
+        // times above: `renderGovernor` is persisted, so negative-only would default
+        // `opts.renderGovernor` to `true` and silently overwrite a stored `false`.
+        .option('--transcript-retain <n>', 'Entries kept in memory (200-20000, default 1000)')
+        .option('--render-governor', 'Adapt the frame interval under load (the default)')
+        .option('--no-render-governor', 'Pin the frame interval at 33ms however expensive a frame is')
+        .option('--max-render-interval <ms>', 'Governor ceiling in ms (33-1000, default 320)')
         .option('--no-color', 'Disable ANSI color')
         .option('--quiet', '(print mode) suppress tool/usage lines on stderr')
         .action(async (prompt, opts) => {

package/dist/commands/builtins.d.ts

@@ -1,7 +1,7 @@
 /**
  * Built-in slash commands (spec §5.2):
  * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
- * /resume /copy /exit (/quit).
+ * /resume /copy /exit (/quit), plus the /team, /fast and /todo subsystems.
  */
 import { CommandRegistry } from './registry.js';
 export declare function registerBuiltinCommands(registry: CommandRegistry): void;