@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
@@ -121,6 +121,93 @@ function resolveTodoConfig(flags, env, file) {
         ...(flags.todoFollow !== undefined ? { followThrough: flags.todoFollow } : {}),
     });
 }
+/**
+ * Merge the `retry` section across all four layers (defaults › file › env ›
+ * flags), llm-api-retry-backoff §6.2.
+ *
+ * `!== undefined` ON BOTH FLAGS, and that is the whole point — the rule
+ * `resolveTeamConfig` and `resolveTodoConfig` each state once. Commander
+ * materialises a lone `--no-retry` as `opts.retry = true` when the flag is
+ * ABSENT, so a truthiness check cannot tell `--no-retry` from "not passed"; and
+ * `flags.retryMax` may legitimately be `0`, which a truthiness check would drop
+ * on the floor and replace with the default 10 (R-16).
+ */
+function resolveRetryConfig(flags, env, file) {
+    return clampRetryConfig({
+        ...DEFAULT_CONFIG.retry,
+        ...(file.retry ?? {}),
+        ...(env.retry ?? {}),
+        ...(flags.retry !== undefined ? { enabled: flags.retry } : {}),
+        ...(flags.retryMax !== undefined && flags.retryMax !== ''
+            ? { maxRetries: flags.retryMax }
+            : {}),
+    });
+}
+/**
+ * Merge the `fast` section across all four layers (defaults › file › env ›
+ * flags), fast-model-tier §3.7.
+ *
+ * `!== undefined` ON `flags.fast`, which is the rule `resolveTeamConfig`,
+ * `resolveTodoConfig` and `resolveRetryConfig` each state once (C-9): commander
+ * materialises a lone `--no-fast` as `opts.fast = true` when the flag is absent,
+ * so a truthiness check cannot tell `--no-fast` from "not passed" — and here the
+ * damage would run the other way from usual, silently turning a default-OFF
+ * feature ON for every run that passed no flag at all.
+ *
+ * `--fast-review` maps onto TWO keys, so it is parsed rather than spread: `off`
+ * is `review: false`, a number is `reviewEveryTurns`, and anything else is
+ * ignored (the clamp discipline every other key in this file follows).
+ */
+function resolveFastConfig(flags, env, file) {
+    const reviewFlag = flags.fastReview?.trim().toLowerCase();
+    const reviewPatch = {};
+    if (reviewFlag !== undefined && reviewFlag.length > 0) {
+        if (reviewFlag === 'off') {
+            reviewPatch.review = false;
+        }
+        else {
+            const n = Number.parseInt(reviewFlag, 10);
+            if (Number.isFinite(n) && n > 0)
+                reviewPatch.reviewEveryTurns = n;
+        }
+    }
+    return clampFastConfig({
+        ...DEFAULT_CONFIG.fast,
+        ...(file.fast ?? {}),
+        ...(env.fast ?? {}),
+        ...(flags.fast !== undefined ? { enabled: flags.fast } : {}),
+        ...(flags.fastModel !== undefined && flags.fastModel !== ''
+            ? { model: flags.fastModel }
+            : {}),
+        ...(flags.fastProvider !== undefined && flags.fastProvider !== ''
+            ? { provider: flags.fastProvider }
+            : {}),
+        ...reviewPatch,
+    });
+}
+/**
+ * Merge the `update` section across all four layers (defaults › file › env ›
+ * flags), cli-auto-update §4.2.
+ *
+ * `!== undefined` ON `flags.update`, which is the rule `resolveTeamConfig`,
+ * `resolveTodoConfig`, `resolveRetryConfig` and `resolveFastConfig` each state
+ * once (C-11): commander materialises a lone `--no-update` as
+ * `opts.update = true` when the flag is absent, so a truthiness check cannot
+ * tell `--no-update` from "not passed" — and here that would silently re-enable
+ * a subsystem the user turned off, which is the one direction this feature must
+ * never fail in.
+ *
+ * The flag maps onto `mode` rather than carrying its own key, so there is
+ * exactly one place that says whether the updater runs.
+ */
+function resolveUpdateConfig(flags, env, file) {
+    return clampUpdateConfig({
+        ...DEFAULT_CONFIG.update,
+        ...(file.update ?? {}),
+        ...(env.update ?? {}),
+        ...(flags.update !== undefined ? { mode: flags.update ? 'auto' : 'off' } : {}),
+    });
+}
 /**
  * Resolve the adaptive render governor: flag › env › file › default `true`
  * (tui-render-performance L4).
@@ -223,6 +310,16 @@ export function loadConfig(flags = {}) {
     const model = pick(flags.model, env.partial.model, file.model) ?? DEFAULT_CONFIG.model;
     const baseUrl = pick(flags.baseUrl, env.partial.baseUrl ?? undefined, file.baseUrl ?? undefined);
     const thinkingLevel = clampThinkingLevel(pick(flags.thinking, env.partial.thinkingLevel, file.thinkingLevel), DEFAULT_CONFIG.thinkingLevel);
+    // BESIDE ITS SIBLING, and through the same three layers (§4.1 / P1-2). This is
+    // the ONLY place flags, environment and file are joined, so a key resolved
+    // anywhere else reaches the UI from at most one of them.
+    const showThinking = pick(flags.showThinking, env.partial.showThinking, file.showThinking) ??
+        DEFAULT_CONFIG.showThinking;
+    // THE SAME THREE LAYERS, in the same one place (§4.1). Round 1's P1-2 and the
+    // fast tier's round-2 IF both record the identical failure: a key resolved
+    // anywhere else reaches the UI from at most one of flags, environment and file.
+    const liveToolOutput = pick(flags.liveToolOutput, env.partial.liveToolOutput, file.liveToolOutput) ??
+        DEFAULT_CONFIG.liveToolOutput;
     const maxTokens = resolveMaxTokens(flags, env.partial, file);
     // `clampTheme` is also where the v0.3.0 `dark` name is migrated to `cool`,
     // so reading a legacy config file needs no extra step here (§4.5 / R-4).
@@ -310,6 +407,8 @@ export function loadConfig(flags = {}) {
         model,
         baseUrl,
         thinkingLevel,
+        showThinking,
+        liveToolOutput,
         maxTokens,
         theme,
         reducedMotion,
@@ -350,6 +449,9 @@ export function loadConfig(flags = {}) {
         log: resolveLogConfig(flags, env.partial, file),
         team: resolveTeamConfig(flags, env.partial, file),
         todo: resolveTodoConfig(flags, env.partial, file),
+        retry: resolveRetryConfig(flags, env.partial, file),
+        fast: resolveFastConfig(flags, env.partial, file),
+        update: resolveUpdateConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,
@@ -386,6 +488,10 @@ function recordResolvedConfig(config) {
         idleTimeoutMs: config.idleTimeoutMs,
         historyEnabled: config.historyEnabled,
         logLevel: config.log.level,
+        // Four layers feed this one too, and none of them would otherwise leave a
+        // trace — so "why did my failing call sit there for three minutes" (or
+        // "why did it not retry at all") has an answer after the fact.
+        retry: config.retry.enabled ? config.retry.maxRetries : 'off',
         hasApiKey: Boolean(config.apiKeys[config.provider]),
         configPath: getConfigPath(),
     });

package/dist/config/schema.d.ts

@@ -5,7 +5,7 @@
  * See spec §3.5 (resolution pipeline), §6.1 (config file), and §3.8 (timeout
  * invariant).
  */
-import { type ThinkingLevel } from '@aragon-agent/core';
+import { type RetryPolicy, type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
 import type { FollowThroughMode } from '../todo/types.js';
 /**
@@ -299,12 +299,209 @@ export declare const DEFAULT_TODO_CONFIG: TodoConfig;
  * setting won't stick".
  */
 export declare function clampTodoConfig(raw: unknown): TodoConfig;
+export interface RetryConfig {
+    /**
+     * The user's switch. KEPT SEPARATE FROM `maxRetries: 0` on purpose: `enabled`
+     * survives round-tripping through the settings screen, while `maxRetries: 0` is
+     * what `toRetryPolicy` produces from it. Folding them would make
+     * `/retry off; /retry on` forget the user's chosen count.
+     */
+    enabled: boolean;
+    /** Retries AFTER the initial attempt. `0` is the kill switch, not a typo. */
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    /** Growth factor. THE ONLY FLOAT KEY in this section. */
+    multiplier: number;
+    jitter: boolean;
+    respectRetryAfter: boolean;
+    /** Wall-clock budget from the first failure of one request. */
+    maxElapsedMs: number;
+    /** Allow a restart after content has already streamed to the transcript. */
+    onPartialStream: boolean;
+}
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * `hardMaxRetries` re-exported rather than re-spelled, for the reason
+ * `HARD_MAX_SUBAGENTS` records: the ceiling is enforced in TWO places — here on
+ * the config value, and again by `normalizePolicy` inside the engine — and two
+ * copies of the same 20 is exactly how a hand-edited `config.json` ends up able
+ * to raise a ceiling the mechanism fixed.
+ */
+export declare const HARD_MAX_RETRIES: 20;
+/**
+ * THE single gate for every retry-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those record: hardening only the read path leaves a bad value on
+ * disk that reverts to the default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Three invariants live inside the gate:
+ *
+ *  - `maxDelayMs = max(maxDelayMs, initialDelayMs)` — a ceiling under the floor
+ *    makes the ladder a flat line and the countdown a lie.
+ *  - `multiplier` goes through `clampNumber`, not `clampInt`: `2.5` is a
+ *    legitimate factor and `coercePositiveInt` would floor it to 2.
+ *  - `maxRetries` goes through `clampIntAllowingZero`. THIS IS THE ONE THAT SHIPS
+ *    BROKEN WITHOUT IT (R-16): `clampInt` returns the fallback for `n <= 0`, so
+ *    `clampRetryConfig({ maxRetries: 0 })` would yield 10 — the maximum instead
+ *    of the minimum, silently, for the key that gates the whole feature.
+ *
+ * `maxElapsedMs` intentionally keeps plain `clampInt`: its floor is 10 000, so it
+ * has no `0` to express.
+ */
+export declare function clampRetryConfig(raw: unknown): RetryConfig;
+/**
+ * `RetryConfig` (user intent) -> `RetryPolicy` (engine policy), or `null` for
+ * "the user said no".
+ *
+ * `null` rather than a policy with `maxRetries: 0` because `ProviderRegistry`
+ * short-circuits on a null policy and returns the adapter's iterator DIRECTLY —
+ * an opted-out session is then allocation-identical to a pre-feature build.
+ *
+ * TOTAL, AND IT ACCEPTS A MISSING SECTION. `loadConfig` always supplies one, but
+ * a `CliConfig` built by hand — every controller test in this package does exactly
+ * that, and so would an embedder — legitimately omits it, and a `TypeError` from a
+ * pure translation function is the wrong way to find out. Routing through
+ * `clampRetryConfig` also means an out-of-range hand-built value can never reach
+ * the engine, which is the same "one gate, both directions" rule every other
+ * section in this file follows.
+ */
+export declare function toRetryPolicy(cfg: RetryConfig | undefined): RetryPolicy | null;
+export interface FastConfig {
+    /**
+     * Resolve the tier at all. Defaults to FALSE (R-d).
+     *
+     * OFF IS BYTE-IDENTICAL (I-2): with this false the system prompt, `task`'s
+     * schema, the tool array, the transcript, the status bar and the request
+     * payloads are exactly what a pre-feature build produces.
+     */
+    enabled: boolean;
+    /** `''` INHERITS the main provider — what makes `fast.model` alone a complete
+     *  configuration for the common "same vendor, cheaper model" case. */
+    provider: string;
+    /** The fast model id. Empty means NOT CONFIGURED, never "same as main": that
+     *  distinction is what keeps R-e (opt in to fast == main) from being
+     *  indistinguishable from a typo (D-4). */
+    model: string;
+    /** `''` inherits only when the provider matches — a base URL belongs to one
+     *  API, so a fast tier on a different vendor must not borrow it. */
+    baseUrl: string;
+    /** Applied to fast-tier children and to the review call. Defaults to `'off'`:
+     *  a "fast" model asked to think for 32 768 tokens is not fast (D-13). */
+    thinkingLevel: ThinkingLevel;
+    /** Allow `model: "fast"` on `task`. */
+    delegate: boolean;
+    /** Run the periodic asynchronous review. */
+    review: boolean;
+    /** Completed turns between reviews. */
+    reviewEveryTurns: number;
+    /** Turn frames included in one digest. */
+    reviewContextTurns: number;
+    /** Ceiling on an injected critique, in characters. */
+    reviewMaxChars: number;
+    /**
+     * Reviews STARTED per session, across all runs (fast-model-tier-hardening
+     * §4.1 / W1).
+     *
+     * The one bound on spend the user never asked for. `reviewEveryTurns`
+     * controls the PACE; this controls the TOTAL — and the two are different
+     * questions, because a session is not one run. `reviewsThisRun` is reset by
+     * every user message, so thirty messages buys thirty runs' worth of reviews
+     * with nothing counting across them.
+     *
+     * DENOMINATED IN REVIEWS, NOT CURRENCY (D-H1). The fast tier is by
+     * construction the likeliest place in the product to name a model the static
+     * cost table has never seen, and `buildRuntimeModel` prices exactly those at
+     * zero (C-11) — so a dollar budget would silently never trigger for the
+     * configuration that most needs it. A count is exact for every model, and
+     * because per-review cost is already bounded on both sides (a 4 000-char
+     * digest in, 512 tokens out), `count x bound` is an honest ceiling.
+     */
+    reviewMaxPerSession: number;
+}
+export declare const DEFAULT_FAST_CONFIG: FastConfig;
+/**
+ * THE single gate for every fast-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those four record: hardening only the read path leaves a bad
+ * value on disk that reverts to the default on every launch, which presents to
+ * the user as "my setting won't stick".
+ *
+ * `provider` is CLAMPED TO `''` rather than rejected when it names something
+ * with no adapter. `''` means "inherit the main provider", which is the safe
+ * reading of a typo — and `resolveFastTier` reports `no_adapter` for the case a
+ * user really did configure a dead vendor as the MAIN one.
+ */
+export declare function clampFastConfig(raw: unknown): FastConfig;
+/** `auto` installs; `notify` only reports; `off` disables the subsystem. */
+export declare const UPDATE_MODES: readonly ["auto", "notify", "off"];
+export type UpdateMode = (typeof UPDATE_MODES)[number];
+export declare function isUpdateMode(v: unknown): v is UpdateMode;
+export interface UpdateConfig {
+    /**
+     * Whether the updater installs, merely reports, or does nothing at all.
+     *
+     * DEFAULTS TO `'auto'`, and that is a PRODUCT decision rather than a technical
+     * one: this CLI's users are overwhelmingly on a stale version they did not
+     * choose. The trade it makes — a wider supply-chain window in exchange for
+     * users who are actually on the current release — is stated plainly in the
+     * README (R-1), and `'off'` plus `ARAGON_UPDATE=0` are the documented kill
+     * switches.
+     */
+    mode: UpdateMode;
+    /** Minimum wall-clock between registry checks, MACHINE-WIDE (§3.7). */
+    checkIntervalMs: number;
+    /** `''` = derive: `ARAGON_UPDATE_REGISTRY` › `npm_config_registry` › npmjs. */
+    registry: string;
+    /** The dist-tag to track. */
+    distTag: string;
+}
+export declare const DEFAULT_UPDATE_CONFIG: UpdateConfig;
+/**
+ * THE single gate for every update-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * / `clampRetryConfig` / `clampFastConfig` for the reason all six record:
+ * hardening only the read path leaves a bad value on disk that reverts to the
+ * default on every launch, which presents to the user as "my setting won't
+ * stick".
+ *
+ * `registry` is CLAMPED TO `''` rather than rejected when it is not an
+ * `http(s):` URL. `''` means "derive it" (§3.3), which is the safe reading of a
+ * typo — the alternative is a background timer that throws on a value the user
+ * cannot see it reading.
+ */
+export declare function clampUpdateConfig(raw: unknown): UpdateConfig;
 export interface PersistedConfig {
     version: number;
     provider: string;
     model: string;
     baseUrl: string | null;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Whether the terminal DRAWS the reasoning that came back
+     * (agent-activity-presentation §4.1).
+     *
+     * ADJACENT TO `thinkingLevel` AND DELIBERATELY NAMED DIFFERENTLY: that key is
+     * the effort the provider is asked to SPEND, this one is whether the transcript
+     * shows it. They are one word apart in the config file and must never be
+     * confused, which is why the flag is `--show-thinking` rather than the shorter
+     * `--thinking` the existing key already resembles.
+     */
+    showThinking: boolean;
+    /**
+     * Whether a RUNNING tool card draws a bounded tail of its live output
+     * (agent-activity-presentation-live §4.1).
+     *
+     * DEFAULT `true`, unlike `showThinking` next door (D-28). That key hides
+     * information by default because reasoning is noise most of the time; this one
+     * ADDS the information the requirement asks for, and its cost is bounded by
+     * construction -- eight rows per call, sixteen calls, whatever the command
+     * emits. It exists as a KILL SWITCH, not as an opt-in: "a build's output
+     * redraws the transcript" is exactly the kind of change a user on a slow SSH
+     * link may want off.
+     */
+    liveToolOutput: boolean;
     /**
      * Output token cap.
      *
@@ -353,7 +550,8 @@ export interface PersistedConfig {
     hints: boolean;
     /**
      * Enable SGR mouse reporting in full-screen mode so the wheel scrolls the
-     * region under the pointer (mouse-wheel-region-routing §5.7).
+     * transcript, whatever row the pointer is on (wheel-scrolls-transcript-only
+     * §4.1).
      *
      * A PLAIN BOOLEAN, not a `fullscreen`-style tri-state: there are no
      * heuristics for an explicit `true` to override (D-10).
@@ -373,6 +571,12 @@ export interface PersistedConfig {
     team: TeamConfig;
     /** Todo planning. The FIFTH nested object; scalars only (see TodoConfig). */
     todo: TodoConfig;
+    /** API retry. The SIXTH nested object; scalars only (see RetryConfig). */
+    retry: RetryConfig;
+    /** Fast model tier. The SEVENTH nested object; scalars only (see FastConfig). */
+    fast: FastConfig;
+    /** Auto-update. The EIGHTH nested object; scalars only (see UpdateConfig). */
+    update: UpdateConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -404,6 +608,28 @@ export interface CliConfig {
     model: string;
     baseUrl?: string;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Seeds `ViewState.thinkingVisible` on the first frame (§4.1 / P1-2).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`. `App` reads `cfg.*`,
+     * where `cfg` is a `CliConfig`; a key added to the persisted shape alone would
+     * round-trip through `config set`, appear in `config list` — and never reach
+     * `initialViewState`. `--show-thinking` and `ARAGON_SHOW_THINKING` would parse
+     * and be discarded. Nothing would fail; the setting would simply do nothing.
+     */
+    showThinking: boolean;
+    /**
+     * Whether `AgentController` allocates the live-output store and binds
+     * `recordOutput` (agent-activity-presentation-live §4.1).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason its
+     * neighbour records one comment up: the controller reads `config.*`, where
+     * `config` is a `CliConfig`, so a key added to the persisted shape alone would
+     * round-trip through `config set`, appear in `config list` -- and never reach
+     * the constructor. `--live-tool-output` and `ARAGON_LIVE_TOOL_OUTPUT` would
+     * parse and be discarded, with nothing failing.
+     */
+    liveToolOutput: boolean;
     /** The resolved cap, or `undefined` for AUTO (per-model ceiling, ≤ 64000). */
     maxTokens?: number;
     theme: ThemeName;
@@ -499,6 +725,46 @@ export interface CliConfig {
      * must call `setTodoConfig` as well as persisting (P1-2).
      */
     todo: TodoConfig;
+    /**
+     * Resolved API-retry settings (llm-api-retry-backoff §6.2).
+     *
+     * Unlike `team.enabled` / `todo.enabled` this decides NOTHING at construction
+     * time: the policy lives on the `ProviderRegistry` and `setRetryConfig()`
+     * replaces it live, so `/retry off` takes effect in the running session. That is
+     * why the controller has no `retryRegistered` twin of the two flags above.
+     */
+    retry: RetryConfig;
+    /**
+     * Resolved fast-tier settings (fast-model-tier §4.2).
+     *
+     * `enabled` here decides `fastRegistered` — whether `task`'s schema carries a
+     * `model` property at all — which happens once at construction and can never
+     * be undone (C-2). The live on/off switch `/fast` flips is a separate flag on
+     * `FastWiring`.
+     *
+     * THE OTHER NINE KEYS ARE READ LIVE, and that is not the same statement.
+     * `provider` / `model` / `baseUrl` feed `resolveFastTier`, which is re-run on
+     * every config mutation (§3.2 rule 8 / RV-3) because `''` INHERITS from
+     * `config.provider` / `config.baseUrl` and those are rewritten by `/model`,
+     * `/provider`, `/reload` and the settings screen.
+     */
+    fast: FastConfig;
+    /**
+     * Resolved auto-update settings (cli-auto-update §4.1).
+     *
+     * `mode` here decides whether `runInteractive` CONSTRUCTS the service at all
+     * (§3.8), which is what makes `'off'` byte-identical to a pre-feature build:
+     * no timer, no file read, no socket. The other three keys are read by the
+     * service on every check, so a `/update off` mid-session stops the next one.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `showThinking` and `liveToolOutput` each record above: the gate reads
+     * `cfg.update`, where `cfg` is a `CliConfig`, so a key added to the persisted
+     * shape alone would round-trip through `config set`, appear in `config list` —
+     * and never reach the gate. `--no-update` and `ARAGON_UPDATE=0` would parse
+     * and be discarded, with no compile error and no runtime error.
+     */
+    update: UpdateConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *