@aragon-agent/cli 0.5.2 → 0.5.4

package/dist/config/prompt-history.js

@@ -0,0 +1,332 @@
+/**
+ * The prompts the user submitted, as an append-only JSON Lines file at
+ * `<home>/prompt-history.jsonl` (config-state-separation §4.3).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS IS NOT IN config.json ANY MORE: it used to be a `promptHistory`
+ * array inside the config file, which meant every single submit rewrote the
+ * whole file — API key section included — and left a user who opened
+ * `config.json` to change their model scrolling past their own typing. A
+ * config file holds what the user DECLARED; this holds what they DID.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * APPEND, never read-modify-write. Two `aragon` windows are an ordinary setup,
+ * and `O_APPEND` + one `writeSync` per entry means they interleave instead of
+ * overwriting each other's snapshots. It also means a process killed mid-write
+ * costs one broken line rather than a truncated array that reads back as "your
+ * history is gone" — hence the per-line tolerance in `parseLine`.
+ *
+ * FAILURE POLICY (C2), the same one `skills/usage.ts` documents: every function
+ * here swallows its errors. This is recall convenience; a read-only home
+ * directory must degrade to "no history", never to a CLI that will not start.
+ * The one thing that policy makes dangerous is a MISSING WRITE — it would be
+ * invisible — which is why the write path creates `<home>` first and why a
+ * failed append is logged rather than merely ignored.
+ */
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync, } from 'node:fs';
+import process from 'node:process';
+import { getHomeRoot, getPromptHistoryPath } from './app-paths.js';
+import { PROMPT_HISTORY_CAP } from './schema.js';
+import { getLogger } from '../logging/logger.js';
+export const PROMPT_HISTORY_FILENAME = 'prompt-history.jsonl';
+export const PROMPT_HISTORY_LINE_VERSION = 1;
+/**
+ * Longer submissions are not recorded at all (D-6).
+ *
+ * Storing a TRUNCATED copy would be worse than storing nothing: the user
+ * presses `↑`, gets back something that looks complete, and sends half a
+ * prompt. 16 KiB is far past anything typed by hand.
+ */
+export const PROMPT_ENTRY_MAX_CHARS = 16_384;
+/** Physical lines tolerated before the file is rewritten down to the cap. */
+export const HISTORY_COMPACT_AT_LINES = 400;
+// ---------------------------------------------------------------------------
+// In-memory state
+// ---------------------------------------------------------------------------
+let memory = null;
+let loadedLines = 0;
+let appendedLines = 0;
+/**
+ * Starts `true`, and that initial value is load-bearing (RV-5).
+ *
+ * `loadConfig()` calls `setHistoryEnabled()`, but the startup migration runs
+ * BEFORE any `loadConfig()`. Something has to be true in that window, and
+ * `true` is what the config key itself defaults to. The one case in that window
+ * that must honour an explicit opt-out — importing a legacy `promptHistory` —
+ * reads the value straight off the config file instead of trusting this flag
+ * (see `migrate-state-out-of-config.ts`).
+ */
+let historyEnabled = true;
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+function parseLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        // Unknown versions are skipped rather than coerced: that is what lets a
+        // future field be added without an older CLI reading the file as garbage.
+        if (parsed.v !== PROMPT_HISTORY_LINE_VERSION)
+            return null;
+        if (typeof parsed.text !== 'string' || parsed.text.length === 0)
+            return null;
+        const ts = typeof parsed.ts === 'number' && Number.isFinite(parsed.ts) ? parsed.ts : 0;
+        return { v: PROMPT_HISTORY_LINE_VERSION, ts, text: parsed.text };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read and parse the file. `null` means the read itself failed — distinct from
+ * "no file yet", because compaction must not rewrite a file it could not read.
+ */
+function readFromDisk() {
+    const path = getPromptHistoryPath();
+    if (!existsSync(path))
+        return { entries: [], lines: 0 };
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const entries = [];
+    let lines = 0;
+    for (const line of raw.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        lines += 1;
+        const entry = parseLine(line);
+        if (entry)
+            entries.push(entry);
+    }
+    return { entries, lines };
+}
+/**
+ * Drop repeats, keeping the LAST occurrence, then keep the newest `cap`.
+ *
+ * Oldest-first ordering is the contract `PromptInput` walks with `↑`/`↓`, and
+ * "last occurrence wins" reproduces what the old in-config implementation did
+ * with `filter(p => p !== text)` followed by an append.
+ */
+function dedupeEntries(entries) {
+    const seen = new Set();
+    const reversed = [];
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        if (seen.has(entry.text))
+            continue;
+        seen.add(entry.text);
+        reversed.push(entry);
+    }
+    reversed.reverse();
+    return reversed.slice(-PROMPT_HISTORY_CAP);
+}
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+/**
+ * The recall list: oldest first, de-duplicated, capped. Cached for the life of
+ * the process so `/reload` — which calls `loadConfig()` again — cannot discard
+ * entries added during this session.
+ *
+ * Reads even when `historyEnabled` is false (RV-12): turning recording off
+ * stops new writes, but someone who wants to see what is already stored before
+ * deleting it must not be told "nothing here" while the file still exists.
+ */
+export function loadPromptHistory() {
+    if (memory !== null)
+        return memory;
+    const read = readFromDisk() ?? { entries: [], lines: 0 };
+    memory = dedupeEntries(read.entries).map((entry) => entry.text);
+    loadedLines = read.lines;
+    appendedLines = 0;
+    return memory;
+}
+/** Every entry on disk with its timestamp, newest first. For `history list`. */
+export function listPromptHistory() {
+    const read = readFromDisk();
+    if (!read)
+        return [];
+    return [...read.entries].reverse();
+}
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+/**
+ * Append one line. Returns whether it reached the disk.
+ *
+ * `mkdirSync` IS NOT DEFENSIVE NOISE — deleting it breaks a real user. `<home>`
+ * is created by the logger (only when `log.toFile` is on) or by the first
+ * config write (only when the user changes a setting); someone on a fresh
+ * install who did neither has no directory here, `openSync` throws `ENOENT`,
+ * the swallow below hides it, and their history silently never persists.
+ *
+ * A short-lived descriptor rather than a kept-open one: this is a once-per-
+ * submit write, and a descriptor held for the life of the process would make
+ * `aragon history clear` unable to delete the file on Windows.
+ */
+function appendLine(entry) {
+    try {
+        mkdirSync(getHomeRoot(), { recursive: true });
+        const fd = openSync(getPromptHistoryPath(), 'a', 0o600);
+        try {
+            writeSync(fd, `${JSON.stringify(entry)}\n`);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    }
+    catch (err) {
+        getLogger().warn('history', 'history_append_failed', {
+            reason: err instanceof Error ? err.message : String(err),
+        });
+        return false;
+    }
+}
+/**
+ * Record one submitted prompt and return THE UPDATED LIST.
+ *
+ * The return value is the whole point of the signature (RV-1). `App.tsx` writes
+ * `setPromptHistory(appendPrompt(text))`: the recall list rendered by the
+ * composer is React state, and a module-level array updated in here re-renders
+ * nothing. Drop the return value and `↑` stops recalling what was just
+ * submitted — but only until the next restart, which makes it about as hard to
+ * diagnose as a bug in this area gets.
+ *
+ * Returns the current list unchanged when recording is off, the text is blank,
+ * or the text is oversized, so callers never need a branch.
+ */
+export function appendPrompt(text, now = Date.now()) {
+    const current = loadPromptHistory();
+    if (!historyEnabled)
+        return current;
+    if (text.trim().length === 0)
+        return current;
+    if (text.length > PROMPT_ENTRY_MAX_CHARS) {
+        getLogger().debug('history', 'prompt_history_entry_too_large', {
+            chars: text.length,
+            max: PROMPT_ENTRY_MAX_CHARS,
+        });
+        return current;
+    }
+    memory = [...current.filter((prompt) => prompt !== text), text].slice(-PROMPT_HISTORY_CAP);
+    if (appendLine({ v: PROMPT_HISTORY_LINE_VERSION, ts: now, text })) {
+        appendedLines += 1;
+        if (loadedLines + appendedLines > HISTORY_COMPACT_AT_LINES)
+            compact();
+    }
+    return memory;
+}
+/**
+ * Rewrite the file down to the cap.
+ *
+ * THE RE-READ ON THE FIRST LINE IS THE WHOLE POINT (RV-3). Writing this
+ * process's in-memory array over the file would reintroduce exactly the
+ * multi-instance clobbering that append-only exists to avoid — and not "a few
+ * trailing entries" either, but everything every other instance wrote since
+ * this one last read. A failed read therefore skips compaction entirely: the
+ * file keeps growing and the next append tries again, which is strictly better
+ * than replacing it with a stale snapshot.
+ */
+function compact() {
+    const disk = readFromDisk();
+    if (!disk)
+        return;
+    // Entries this session has but the file does not — normally none, since the
+    // appends above are already on disk. It only matters if a read raced a write.
+    const onDisk = new Set(disk.entries.map((entry) => entry.text));
+    const carried = (memory ?? [])
+        .filter((text) => !onDisk.has(text))
+        .map((text) => ({ v: PROMPT_HISTORY_LINE_VERSION, ts: Date.now(), text }));
+    const kept = dedupeEntries([...disk.entries, ...carried]);
+    const path = getPromptHistoryPath();
+    const tmp = `${path}.tmp-${process.pid}`;
+    try {
+        mkdirSync(getHomeRoot(), { recursive: true });
+        const payload = kept.map((entry) => `${JSON.stringify(entry)}\n`).join('');
+        writeFileSync(tmp, payload, { encoding: 'utf-8', mode: 0o600 });
+        renameSync(tmp, path);
+        // rename does not preserve mode everywhere, and this file holds the user's
+        // prompts verbatim — re-apply it rather than hope (RV-6, as `store.ts` does).
+        if (process.platform !== 'win32')
+            chmodSync(path, 0o600);
+        memory = kept.map((entry) => entry.text);
+        loadedLines = kept.length;
+        appendedLines = 0;
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing further to try; the original file is untouched either way.
+        }
+        getLogger().warn('history', 'history_compact_failed', {
+            reason: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Migration-only: append the texts that are not in the file yet, returning how
+ * many were written.
+ *
+ * Ignores `historyEnabled` on purpose — the caller decides, because it is the
+ * only code that can see an explicit `historyEnabled: false` in the config file
+ * before `loadConfig()` has run (§4.6 step 3).
+ */
+export function importLegacyPromptHistory(entries) {
+    const read = readFromDisk();
+    if (!read)
+        return 0;
+    const known = new Set(read.entries.map((entry) => entry.text));
+    let written = 0;
+    for (const text of entries) {
+        if (typeof text !== 'string')
+            continue;
+        if (text.trim().length === 0)
+            continue;
+        if (text.length > PROMPT_ENTRY_MAX_CHARS)
+            continue;
+        if (known.has(text))
+            continue;
+        if (!appendLine({ v: PROMPT_HISTORY_LINE_VERSION, ts: Date.now(), text }))
+            break;
+        known.add(text);
+        written += 1;
+    }
+    // The cache, if anything already built one, no longer matches the file.
+    if (written > 0)
+        memory = null;
+    return written;
+}
+/** Delete the file and empty the cache. Returns how many entries were removed. */
+export function clearPromptHistory() {
+    const removed = readFromDisk()?.entries.length ?? 0;
+    try {
+        rmSync(getPromptHistoryPath(), { force: true });
+    }
+    catch {
+        // Same policy as every other failure here: a file we could not delete is
+        // not worth an error the user can do nothing about.
+    }
+    memory = [];
+    loadedLines = 0;
+    appendedLines = 0;
+    return removed;
+}
+/** Called once by `loadConfig()` after `historyEnabled` has been resolved. */
+export function setHistoryEnabled(enabled) {
+    historyEnabled = enabled;
+}
+/** Test-only: forget the cache, the line counters and the switch. */
+export function resetPromptHistoryForTests() {
+    memory = null;
+    loadedLines = 0;
+    appendedLines = 0;
+    historyEnabled = true;
+}

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 ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
 /**
  * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
@@ -55,9 +55,13 @@ export declare const DEFAULT_TOOL_TIMEOUT_MS = 180000;
 export declare const IDLE_TIMEOUT_MARGIN_MS = 30000;
 /** Watchdog idle timeout (§3.8) — must stay ≥ toolTimeout so long tools survive. */
 export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
-/** Cap on persisted prompt history / recent-model MRU lists. */
+/**
+ * Cap on the recall list.
+ *
+ * The list itself now lives in `<home>/prompt-history.jsonl`; this constant is
+ * consumed by `config/prompt-history.ts`, not by the UI.
+ */
 export declare const PROMPT_HISTORY_CAP = 100;
-export declare const RECENT_MODELS_CAP = 10;
 /**
  * How many trailing entries the full-screen viewport renders (invariant I-3).
  * Yoga lays out every child even when `overflow: hidden` clips it, so the cost
@@ -190,12 +194,69 @@ export declare const DEFAULT_LOG_CONFIG: LogConfig;
  * but none of it".
  */
 export declare function clampLogConfig(raw: unknown): LogConfig;
+export interface TeamConfig {
+    /** Register the `task` tool at all. Defaults to TRUE (R-b). */
+    enabled: boolean;
+    /** Children per dispatch. Clamped to [1, HARD_MAX_SUBAGENTS] (R-g). */
+    maxSubagents: number;
+    /**
+     * Children in flight at once.
+     *
+     * A SEPARATE KNOB FROM `maxSubagents` on purpose (D-6): provider rate limits
+     * are a different constraint from context economics, and folding them into one
+     * number makes both wrong. Five simultaneous streams against one API key is a
+     * reliable way to collect HTTP 429s, each of which lands in the report as a
+     * failed subagent.
+     */
+    maxConcurrent: number;
+    /** One child's wall clock before its own abort. */
+    subagentTimeoutMs: number;
+    /** The whole dispatch's wall clock. Also the `task` tool-timeout override. */
+    dispatchTimeoutMs: number;
+    /** Runaway-loop cap: turns one child may take before it is stopped. */
+    maxTurnsPerSubagent: number;
+}
+/**
+ * The requirement's ceiling on the fan-out (R-g).
+ *
+ * Re-exported from `TEAM_LIMITS` rather than re-spelled, because it is enforced
+ * in TWO places — here on the config value, and again in
+ * `normalizeSubagentSpecs` on what the model asked for — and two copies of the
+ * same 10 is exactly how a hand-edited `config.json` ends up being able to raise
+ * a ceiling the requirement fixed.
+ */
+export declare const HARD_MAX_SUBAGENTS: 10;
+export declare const DEFAULT_TEAM_CONFIG: TeamConfig;
+/**
+ * THE single gate for every team-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` for the reason those two 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".
+ *
+ * `maxConcurrent` is additionally capped at `maxSubagents`: a pool wider than
+ * the population it draws from is not wrong so much as meaningless, and letting
+ * the two disagree would make the panel's `n/m` readout confusing for no gain.
+ */
+export declare function clampTeamConfig(raw: unknown): TeamConfig;
 export interface PersistedConfig {
     version: number;
     provider: string;
     model: string;
     baseUrl: string | null;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Output token cap.
+     *
+     *   a number — an explicit cap, clamped to `[256, 200000]` on the way in AND
+     *              on the way out, then clamped again at request time down to the
+     *              target model's real ceiling when that ceiling is lower.
+     *   `null`   — AUTO: use each model's own ceiling, never above 64000.
+     *   absent   — the product default, 64000.
+     *
+     * `null` MEANS AUTO. It used to resolve to 64000 by accident (`pick()` skips
+     * `null`), which left the user no way to express "let the model decide".
+     */
     maxTokens: number | null;
     theme: ThemeName;
     /** Replace spinners with a static glyph for calmer, low-motion output. */
@@ -211,8 +272,15 @@ export interface PersistedConfig {
     idleTimeoutMs: number;
     /** provider -> key. Masked in the UI; the file is written 0600 on POSIX. */
     apiKeys: Record<string, string | null>;
-    recentModels: string[];
-    promptHistory: string[];
+    /**
+     * Record submitted prompts to `<home>/prompt-history.jsonl` at all (D-9).
+     *
+     * A real preference, and the reason it belongs here rather than in
+     * `state.json`: the user declares it, and switching it off is a decision they
+     * expect to survive. Command-line only, like `log.redactSecrets` — there is
+     * no settings-screen entry, because it is set once and then forgotten.
+     */
+    historyEnabled: boolean;
     /** Entry spacing: `comfortable` keeps a blank line at turn boundaries (§4.3). */
     density: DensityMode;
     /** Show the composer hint row at all. */
@@ -225,15 +293,6 @@ export interface PersistedConfig {
      * heuristics for an explicit `true` to override (D-10).
      */
     mouse: boolean;
-    /**
-     * Whether the one-time "hold Shift to select text" notice has been shown
-     * (§6.1). Bookkeeping for a one-shot notice, NOT a preference — hence no
-     * flag, no env var and no `config set` key. Giving it a user-facing channel
-     * would invite it to be treated as one.
-     */
-    mouseNoticeSeen: boolean;
-    /** Lifetime submit count driving the progressive-disclosure fade (§4.6). */
-    submitCount: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
     planModeDefault: boolean;
     /** `ask_user` rounds allowed per user turn; clamped to [1, 10]. */
@@ -244,13 +303,40 @@ export interface PersistedConfig {
     skills: SkillsConfig;
     /** Logging settings. The THIRD nested object; scalars only (see LogConfig). */
     log: LogConfig;
+    /** Team mode. The FOURTH nested object; scalars only (see TeamConfig). */
+    team: TeamConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
+/**
+ * Runtime state that used to be stored in `config.json` by mistake
+ * (config-state-separation §4.5). Each one now lives in its own file:
+ * `promptHistory` → `prompt-history.jsonl`, `submitCount` / `mouseNoticeSeen`
+ * → `state.json`, and `recentModels` was dead — nothing ever wrote it.
+ */
+export declare const LEGACY_STATE_KEYS: readonly ["promptHistory", "submitCount", "mouseNoticeSeen", "recentModels"];
+/**
+ * THE single gate that keeps those keys out of `config.json`, and the one thing
+ * in this change that cannot be skipped.
+ *
+ * `loadPersistedConfig()` merges `{ ...DEFAULT_CONFIG, ...partial }` where
+ * `partial` is the raw parse of whatever is on disk. Removing the fields from
+ * the interface therefore removes NOTHING from the file: the keys ride through
+ * the spread and `updatePersistedConfig` writes them straight back. The user
+ * deletes `promptHistory` by hand and watches it grow back.
+ *
+ * Applied on the READ side on purpose, which is what makes it self-healing:
+ * every write goes read-strip-merge-write, so a hand-edited file, a downgrade
+ * to 0.5.x and back, or a half-finished migration all converge on a clean file
+ * at the next write. Same shape as `clampSkillsConfig` / `clampLogConfig` —
+ * one door for both directions.
+ */
+export declare function stripLegacyStateKeys<T extends object>(raw: T): T;
 export interface CliConfig {
     provider: string;
     model: string;
     baseUrl?: string;
     thinkingLevel: ThinkingLevel;
+    /** The resolved cap, or `undefined` for AUTO (per-model ceiling, ≤ 64000). */
     maxTokens?: number;
     theme: ThemeName;
     reducedMotion: boolean;
@@ -274,8 +360,15 @@ export interface CliConfig {
     idleTimeoutMs: number;
     /** provider -> resolved key (config-file key ?? provider env var). */
     apiKeys: Record<string, string | undefined>;
-    recentModels: string[];
-    promptHistory: string[];
+    /**
+     * Whether submitted prompts are recorded (D-9).
+     *
+     * The recall LIST is deliberately not here: its only consumer is one
+     * `useState` seed in `App.tsx`, and carrying it on `CliConfig` would make
+     * every `loadConfig()` — `aragon logs tail` and `aragon skills list`
+     * included — read a file it has no use for (D-4).
+     */
+    historyEnabled: boolean;
     density: DensityMode;
     hints: boolean;
     /**
@@ -283,7 +376,6 @@ export interface CliConfig {
      * only). Resolved by `resolveMouse` in `load.ts`.
      */
     mouse: boolean;
-    submitCount: number;
     /**
      * Whether this session opens in PLAN mode.
      *
@@ -299,6 +391,23 @@ export interface CliConfig {
     skillsRuntime: SkillsRuntimeOptions;
     /** Resolved logging settings; the authoritative input to `Logger.reconfigure`. */
     log: LogConfig;
+    /**
+     * Resolved team-mode settings (team-subagents §3.10).
+     *
+     * `enabled` here decides whether `task` is REGISTERED, which happens once at
+     * construction and can never be undone (§4.5 / D-17). The live on/off switch
+     * `/team` flips is a separate flag on the controller.
+     */
+    team: TeamConfig;
+    /**
+     * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
+     *
+     * Read from `<home>/state.json` rather than the config file. It stays on
+     * `CliConfig` — unlike the recall list — because it is one scalar that is
+     * already plumbed through `controller.getConfig()` / `setSubmitCount()` and
+     * read during render (D-4).
+     */
+    submitCount: number;
     /** Working directory for tools (default `process.cwd()`, overridable). */
     cwd: string;
     /** Whether ANSI color is enabled. */
@@ -310,8 +419,57 @@ export interface CliConfig {
     /** One-shot `--api-key` override; applies to the active provider only. */
     apiKeyOverride?: string;
 }
-/** Coerce an arbitrary value into a positive integer, or `undefined`. */
+/**
+ * Coerce an arbitrary value into a positive integer, or `undefined`.
+ *
+ * Kept because callers outside this feature still use it, and deliberately
+ * WITHOUT the range clamp so its behaviour for in-range values is byte-identical
+ * to what it always was. New code wants `clampMaxTokens`.
+ */
 export declare function coerceMaxTokens(v: unknown): number | undefined;
+/**
+ * The accepted range for an explicit output cap.
+ *
+ * The floor is the engine's: below it a turn cannot produce a usable tool call.
+ * The ceiling is a sanity bound on a hand-edited file, not a model limit — the
+ * real per-model ceiling is applied later, by `resolveOutputTokens`.
+ */
+export declare const MAX_TOKENS_RANGE: {
+    min: number;
+    max: number;
+};
+/** `auto`, an empty string and `0` all mean AUTO — "let the model decide". */
+export declare function isAutoToken(v: unknown): boolean;
+/**
+ * THE single gate for every `maxTokens` read AND write, in the shape
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` already use.
+ *
+ * Both directions on purpose: hardening only the read path leaves a bad value on
+ * disk that reverts to a default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Returns `undefined` for AUTO and for anything unusable — the caller decides
+ * which of the two it was, because they mean different things.
+ */
+export declare function clampMaxTokens(v: unknown): number | undefined;
+/**
+ * Parse text typed into the settings screen, a slash command, or `config set`.
+ *
+ * Distinguishes AUTO from "the user typed nonsense", which `clampMaxTokens`
+ * cannot: both come back as `undefined` there, and treating a typo as AUTO would
+ * silently discard the number the user meant to set.
+ */
+export declare function parseMaxTokensInput(raw: string): {
+    kind: 'auto';
+} | {
+    kind: 'value';
+    value: number;
+    clamped: boolean;
+} | {
+    kind: 'invalid';
+};
+/** The product default, re-exported so the CLI never spells the number itself. */
+export declare const DEFAULT_MAX_TOKENS = 64000;
 /** Coerce a value into a positive integer with a fallback (for timeouts). */
 export declare function coercePositiveInt(v: unknown, fallback: number): number;
 /**