@aragon-agent/cli 0.5.2 → 0.5.4

package/dist/config/env.js

@@ -5,8 +5,9 @@
  *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
  *     GEMINI_API_KEY.
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
- *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN,
- *     ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
+ *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
+ *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never
@@ -18,7 +19,7 @@ import process from 'node:process';
 import dotenv from 'dotenv';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
 import { clampLogLevel } from '../logging/levels.js';
-import { clampTheme, clampThinkingLevel, coerceMaxTokens, } from './schema.js';
+import { clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, } from './schema.js';
 /**
  * Load a project `.env` from the given directory into `process.env` (existing
  * process env wins — dotenv never overrides already-set variables).
@@ -58,9 +59,20 @@ export function readEnvConfig() {
     if (process.env.ARAGON_THINKING) {
         partial.thinkingLevel = clampThinkingLevel(process.env.ARAGON_THINKING.trim(), 'off');
     }
-    if (process.env.ARAGON_MAX_TOKENS) {
-        const mt = coerceMaxTokens(process.env.ARAGON_MAX_TOKENS);
-        partial.maxTokens = mt ?? null;
+    // `auto` / `0` mean AUTO (`null`); a number is clamped to the accepted range.
+    // Anything else is LEFT ABSENT rather than written as `null`: a typo here used
+    // to become AUTO and silently discard the number in the config file under it,
+    // which is the opposite of what the user asked for.
+    const maxTokens = process.env.ARAGON_MAX_TOKENS?.trim();
+    if (maxTokens !== undefined && maxTokens.length > 0) {
+        if (isAutoToken(maxTokens)) {
+            partial.maxTokens = null;
+        }
+        else {
+            const clamped = clampMaxTokens(maxTokens);
+            if (clamped !== undefined)
+                partial.maxTokens = clamped;
+        }
     }
     if (process.env.ARAGON_THEME) {
         partial.theme = clampTheme(process.env.ARAGON_THEME.trim(), 'auto');
@@ -96,6 +108,32 @@ export function readEnvConfig() {
             enabled: !(skills === '0' || skills === 'false' || skills === 'off' || skills === 'no'),
         };
     }
+    // ARAGON_TEAM=0 turns team mode off; ARAGON_TEAM_MAX=<n> overrides the fan-out
+    // width. Parsed by the POSITIVE list, exactly as ARAGON_FULLSCREEN /
+    // ARAGON_MOUSE / ARAGON_PLAN are — NOT by `envBool` below, which uses a
+    // negative list. The two readers disagree on `ARAGON_TEAM=disable`, and the
+    // documented-but-dead outcome of copying the wrong one is what `load.ts`
+    // records for `ARAGON_MOUSE`.
+    const team = process.env.ARAGON_TEAM?.trim().toLowerCase();
+    const teamMax = process.env.ARAGON_TEAM_MAX?.trim();
+    if ((team !== undefined && team.length > 0) || (teamMax !== undefined && teamMax.length > 0)) {
+        const section = {};
+        if (team !== undefined && team.length > 0) {
+            section.enabled = team === '1' || team === 'true' || team === 'on' || team === 'yes';
+        }
+        if (teamMax !== undefined && teamMax.length > 0) {
+            const parsed = Number.parseInt(teamMax, 10);
+            // Left ABSENT when unparseable rather than written as a default, so the
+            // config file can still win. A resolved default here would make the env
+            // var look permanently supplied.
+            if (Number.isFinite(parsed) && parsed > 0)
+                section.maxSubagents = parsed;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it — the
+        // same contract `partial.skills` and `partial.log` rely on.
+        if (Object.keys(section).length > 0)
+            partial.team = section;
+    }
     const log = readEnvLogConfig();
     if (log)
         partial.log = log;

package/dist/config/history-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `aragon history path | list | clear` — the prompt history's operations
+ * surface (config-state-separation §5.5).
+ *
+ * Exit codes follow the existing convention: 0 success · 1 run-time failure ·
+ * 2 usage error.
+ *
+ * EXEMPT from the "every subcommand records one info line" rule, for the same
+ * reason `logging/cli-commands.ts` is: recording a line opens today's log file,
+ * and a command whose job is to delete the user's data should not be creating
+ * files as a side effect of announcing itself.
+ */
+export interface HistoryCliOptions {
+    /** `-n <N>` — entries printed by `list` (default 20). */
+    lines?: string;
+    json?: boolean;
+    /** Required by `clear`; without it the command refuses. */
+    yes?: boolean;
+}
+export declare function runHistoryCommand(subcommand: string, opts: HistoryCliOptions): number;

package/dist/config/history-commands.js

@@ -0,0 +1,71 @@
+/**
+ * `aragon history path | list | clear` — the prompt history's operations
+ * surface (config-state-separation §5.5).
+ *
+ * Exit codes follow the existing convention: 0 success · 1 run-time failure ·
+ * 2 usage error.
+ *
+ * EXEMPT from the "every subcommand records one info line" rule, for the same
+ * reason `logging/cli-commands.ts` is: recording a line opens today's log file,
+ * and a command whose job is to delete the user's data should not be creating
+ * files as a side effect of announcing itself.
+ */
+import { existsSync } from 'node:fs';
+import process from 'node:process';
+import { getPromptHistoryPath } from './app-paths.js';
+import { clearPromptHistory, listPromptHistory } from './prompt-history.js';
+const EXIT_OK = 0;
+const EXIT_USAGE = 2;
+const DEFAULT_LIST_ENTRIES = 20;
+export function runHistoryCommand(subcommand, opts) {
+    switch (subcommand) {
+        case 'path':
+            return runPath();
+        case 'list':
+            return runList(opts);
+        case 'clear':
+            return runClear(opts);
+        default:
+            process.stderr.write(`Unknown history subcommand "${subcommand}". Try: path | list | clear.\n`);
+            return EXIT_USAGE;
+    }
+}
+function runPath() {
+    const path = getPromptHistoryPath();
+    process.stdout.write(`${path}\n`);
+    if (!existsSync(path))
+        process.stdout.write('(no history recorded yet)\n');
+    // The file holds prompts verbatim — the one thing to say out loud before
+    // someone attaches it to a bug report or copies it to another machine.
+    process.stdout.write('entries are stored verbatim; clear them with: aragon history clear --yes\n');
+    return EXIT_OK;
+}
+function runList(opts) {
+    const entries = listPromptHistory();
+    if (entries.length === 0) {
+        process.stdout.write('No prompt history recorded.\n');
+        return EXIT_OK;
+    }
+    const parsed = Number.parseInt(opts.lines ?? '', 10);
+    const wanted = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LIST_ENTRIES;
+    const shown = entries.slice(0, wanted);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(shown, null, 2)}\n`);
+        return EXIT_OK;
+    }
+    for (const entry of shown) {
+        // Newlines would break the one-entry-per-line reading this output invites.
+        const text = entry.text.replace(/\r?\n/g, ' ');
+        process.stdout.write(`${new Date(entry.ts).toISOString()}  ${text}\n`);
+    }
+    return EXIT_OK;
+}
+function runClear(opts) {
+    if (!opts.yes) {
+        process.stderr.write('Refusing to delete the prompt history without --yes.\n');
+        return EXIT_USAGE;
+    }
+    const removed = clearPromptHistory();
+    process.stdout.write(`Removed ${removed} entries.\n`);
+    return EXIT_OK;
+}

package/dist/config/load.d.ts

@@ -39,6 +39,19 @@ export interface CliFlags {
     skillToolPolicy?: string;
     /** `--plan` ⇒ true, `--no-plan` ⇒ false, absent ⇒ undefined (plan-mode §4.4). */
     plan?: boolean;
+    /**
+     * `--team` ⇒ true, `--no-team` ⇒ false, absent ⇒ undefined (team-subagents §4.4).
+     *
+     * BOTH commander forms must be declared and this field must be carried through
+     * `toFlags`, or the flag is inert with no compile error and no runtime error —
+     * the failure `cli.tsx` already records in its own words for `--no-mouse`
+     * (P1-4). Declaring only the negative form additionally makes commander
+     * default `opts.team` to `true`, at which point the flag is indistinguishable
+     * from its own default and silently overrides `config.json` on EVERY run.
+     */
+    team?: boolean;
+    /** `--team-max <n>` — override `team.maxSubagents` for this run (still clamped). */
+    teamMax?: string | number;
     /** `--log-level <lv>` — this run only, never persisted. */
     logLevel?: string;
     /** `--log-file` ⇒ true, `--no-log-file` ⇒ false, absent ⇒ undefined. */

package/dist/config/load.js

@@ -6,9 +6,12 @@
  * 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, clampTheme, clampThinkingLevel, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTheme, clampThinkingLevel, clampMaxTokens, 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';
+import { setHistoryEnabled } from './prompt-history.js';
+import { readSubmitCount } from './ui-state.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret, registerSecretsFrom } from '../logging/secret-registry.js';
 import { detectCapabilities } from '../ui/capabilities.js';
@@ -73,6 +76,27 @@ function resolveLogToFile(flags, env, file) {
         return false;
     return true;
 }
+/**
+ * Merge the `team` section across all four layers (defaults › file › env ›
+ * flags), team-subagents §3.10.
+ *
+ * `flags.team !== undefined` rather than a truthiness check, and that is the
+ * whole point (P1-4): a truthiness check cannot tell `--no-team` from "not
+ * passed", so `--no-team` would resolve to the config file's value and the off
+ * switch would not be off. `--no-skills` gets away with a one-directional test
+ * only because nothing ever needs to distinguish `--skills` from silence.
+ */
+function resolveTeamConfig(flags, env, file) {
+    return clampTeamConfig({
+        ...DEFAULT_CONFIG.team,
+        ...(file.team ?? {}),
+        ...(env.team ?? {}),
+        ...(flags.team !== undefined ? { enabled: flags.team } : {}),
+        ...(flags.teamMax !== undefined && flags.teamMax !== ''
+            ? { maxSubagents: flags.teamMax }
+            : {}),
+    });
+}
 /** Merge the `log` section across all four layers (defaults › file › env › flags). */
 function resolveLogConfig(flags, env, file) {
     const merged = clampLogConfig({
@@ -94,6 +118,44 @@ function pick(...vals) {
     }
     return undefined;
 }
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/**
+ * Resolve the output cap: flag › env › file › default, where an EXPLICIT `null`
+ * at any layer means AUTO (`undefined` — let the resolver pick per model).
+ *
+ * THIS CANNOT USE `pick()`, and that is the whole point. `pick` skips `null`, so
+ * a config file holding `"maxTokens": null` silently resolves to 64000 and AUTO
+ * is unreachable through every supported write path. Detecting it needs an
+ * own-property test, not a truthiness test — `null` is exactly the value we are
+ * looking for.
+ *
+ * An unparseable layer falls through to the next one rather than becoming AUTO:
+ * a typo in `ARAGON_MAX_TOKENS` must not silently discard the number in the
+ * config file underneath it.
+ */
+function resolveMaxTokens(flags, env, file) {
+    const layers = [
+        { name: '--max-tokens', value: flags.maxTokens },
+        { name: 'ARAGON_MAX_TOKENS', value: hasOwn(env, 'maxTokens') ? env.maxTokens : undefined },
+        { name: 'config.json maxTokens', value: hasOwn(file, 'maxTokens') ? file.maxTokens : undefined },
+    ];
+    for (const layer of layers) {
+        if (layer.value === undefined)
+            continue; // this layer said nothing
+        if (layer.value === null || isAutoToken(layer.value))
+            return undefined; // AUTO
+        const n = clampMaxTokens(layer.value);
+        if (n !== undefined)
+            return n;
+        getLogger().warn('config', 'max_tokens_unusable', {
+            source: layer.name,
+            value: String(layer.value),
+        });
+    }
+    return DEFAULT_CONFIG.maxTokens ?? undefined;
+}
 /**
  * Resolve the effective config by merging all layers, then derive the runtime
  * (non-persisted) fields and enforce the timeout invariant.
@@ -118,7 +180,7 @@ 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);
-    const maxTokens = coerceMaxTokens(pick(flags.maxTokens, env.partial.maxTokens, file.maxTokens));
+    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).
     const theme = clampTheme(pick(flags.theme, env.partial.theme, file.theme), DEFAULT_CONFIG.theme);
@@ -178,7 +240,12 @@ export function loadConfig(flags = {}) {
     // Detect terminal capabilities once; force monochrome when color is disabled.
     const caps = detectCapabilities(process.env, process.stdout);
     const colorLevel = color ? caps.colorLevel : 0;
-    return {
+    // No flag and no env var: a privacy switch you set once, not a per-run knob.
+    const historyEnabled = file.historyEnabled ?? DEFAULT_CONFIG.historyEnabled;
+    // The prompt-history store is a module-level singleton, so the resolved value
+    // has to be pushed into it — this is the ONLY place that happens.
+    setHistoryEnabled(historyEnabled);
+    const config = {
         provider,
         model,
         baseUrl,
@@ -195,12 +262,12 @@ export function loadConfig(flags = {}) {
         toolTimeoutMs,
         idleTimeoutMs,
         apiKeys,
-        recentModels: file.recentModels ?? [],
-        promptHistory: file.promptHistory ?? [],
+        historyEnabled,
         density,
         hints,
         mouse: resolveMouse(flags, env.partial, file),
-        submitCount: coercePositiveInt(file.submitCount, 0),
+        // From `<home>/state.json`, not the config file — see `ui-state.ts`.
+        submitCount: readSubmitCount(),
         startInPlanMode,
         planModeMaxAskRounds,
         planModeHumanTimeoutMs,
@@ -217,12 +284,46 @@ export function loadConfig(flags = {}) {
                 : {}),
         },
         log: resolveLogConfig(flags, env.partial, file),
+        team: resolveTeamConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,
         unicode: caps.unicode,
         apiKeyOverride: flags.apiKey && flags.apiKey.trim().length > 0 ? flags.apiKey.trim() : undefined,
     };
+    recordResolvedConfig(config);
+    return config;
+}
+/**
+ * One record naming the values this run actually resolved to.
+ *
+ * "I changed the model in config.json and it still uses the old one" was, until
+ * this line existed, unanswerable after the fact: four layers feed this
+ * function and none of them left a trace. Now the answer is in the log next to
+ * the path the values came from.
+ *
+ * NO SECRET VALUES — only whether a key was found. `logging/redact.ts` would
+ * catch one anyway, but a record that never carries the secret does not depend
+ * on that backstop being configured.
+ */
+function recordResolvedConfig(config) {
+    getLogger().info('config', 'config_loaded', {
+        provider: config.provider,
+        model: config.model,
+        baseUrl: config.baseUrl,
+        thinkingLevel: config.thinkingLevel,
+        // Four layers feed this one and none of them used to leave a trace, so
+        // "why is my output truncated" was unanswerable after the fact.
+        maxTokens: config.maxTokens ?? 'auto',
+        theme: config.theme,
+        fullscreen: config.fullscreen,
+        toolTimeoutMs: config.toolTimeoutMs,
+        idleTimeoutMs: config.idleTimeoutMs,
+        historyEnabled: config.historyEnabled,
+        logLevel: config.log.level,
+        hasApiKey: Boolean(config.apiKeys[config.provider]),
+        configPath: getConfigPath(),
+    });
 }
 /**
  * Build the `getApiKey(providerId)` resolver the core `Agent` consumes.

package/dist/config/migrate-state-out-of-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One-shot move of the four runtime-state keys out of `config.json`
+ * (config-state-separation §4.6).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: the schema change alone would strip `promptHistory`,
+ * `submitCount` and `mouseNoticeSeen` from an existing user's config file on
+ * the first write after upgrading, with nowhere for the values to go. That is
+ * the only path in this feature that can actually LOSE data, which is why the
+ * strip and this migration must ship together.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * THE IDEMPOTENCE KEY IS THE SOURCE DATA — "are those keys still in
+ * config.json" — not a breadcrumb and not "does prompt-history.jsonl exist".
+ * Same reasoning as `migrate-home.ts`: a breadcrumb written before a failed
+ * step makes a half-finished migration skip itself forever. Keyed on the source,
+ * a failure simply retries next launch, and the two import functions are
+ * written so that retrying imports nothing twice.
+ *
+ * NEVER THROWS (C3) and never prints (D-8). The user sees no difference —
+ * history still recalls, the counter still counts — so a line on stderr would
+ * be noise, and `aragon config home` names the new files for anyone curious.
+ */
+export interface StateMigrationResult {
+    /** The keys actually carried out of the file, e.g. `['promptHistory']`. */
+    moved: string[];
+    /** History entries imported, for the log record. */
+    promptEntries: number;
+    /** Returned rather than thrown (C3). */
+    error?: string;
+}
+export declare function migrateStateOutOfConfig(): StateMigrationResult;

package/dist/config/migrate-state-out-of-config.js

@@ -0,0 +1,85 @@
+/**
+ * One-shot move of the four runtime-state keys out of `config.json`
+ * (config-state-separation §4.6).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: the schema change alone would strip `promptHistory`,
+ * `submitCount` and `mouseNoticeSeen` from an existing user's config file on
+ * the first write after upgrading, with nowhere for the values to go. That is
+ * the only path in this feature that can actually LOSE data, which is why the
+ * strip and this migration must ship together.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * THE IDEMPOTENCE KEY IS THE SOURCE DATA — "are those keys still in
+ * config.json" — not a breadcrumb and not "does prompt-history.jsonl exist".
+ * Same reasoning as `migrate-home.ts`: a breadcrumb written before a failed
+ * step makes a half-finished migration skip itself forever. Keyed on the source,
+ * a failure simply retries next launch, and the two import functions are
+ * written so that retrying imports nothing twice.
+ *
+ * NEVER THROWS (C3) and never prints (D-8). The user sees no difference —
+ * history still recalls, the counter still counts — so a line on stderr would
+ * be noise, and `aragon config home` names the new files for anyone curious.
+ */
+import { readConfigFile, updatePersistedConfig } from './store.js';
+import { importLegacyPromptHistory } from './prompt-history.js';
+import { importLegacyUiState } from './ui-state.js';
+import { LEGACY_STATE_KEYS } from './schema.js';
+import { getLogger } from '../logging/logger.js';
+export function migrateStateOutOfConfig() {
+    const result = { moved: [], promptEntries: 0 };
+    try {
+        const { config } = readConfigFile();
+        // A missing file has nothing to move; an UNPARSEABLE one must be left
+        // exactly as it is, or the user's chance to fix their typo is gone.
+        if (!config)
+            return result;
+        const legacy = config;
+        const present = LEGACY_STATE_KEYS.filter((key) => legacy[key] !== undefined);
+        if (present.length === 0)
+            return result;
+        result.promptEntries = importHistory(legacy);
+        importCounters(legacy);
+        // An empty patch still goes read-strip-merge-write, so this is what makes
+        // the legacy keys leave the file — `stripLegacyStateKeys` does the work.
+        updatePersistedConfig({});
+        result.moved = [...present];
+        getLogger().info('migrate', 'migrate_state_split', {
+            moved: result.moved,
+            promptEntries: result.promptEntries,
+        });
+        return result;
+    }
+    catch (err) {
+        return { moved: [], promptEntries: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Import the recall list, unless the user turned recording off.
+ *
+ * THE `historyEnabled` CHECK IS NOT REDUNDANT with the one inside
+ * `appendPrompt`. This runs before any `loadConfig()`, so the module-level
+ * switch is still at its `true` default; the only place the user's real answer
+ * exists at this moment is the config object read above. The path that makes it
+ * matter: upgrade, switch recording off, downgrade to 0.5.x (which writes
+ * `promptHistory` back into config.json), upgrade again. Without this, prompts
+ * the user explicitly refused to have recorded get copied into the new file.
+ */
+function importHistory(legacy) {
+    if (!Array.isArray(legacy.promptHistory) || legacy.promptHistory.length === 0)
+        return 0;
+    if (legacy.historyEnabled === false)
+        return 0;
+    const entries = legacy.promptHistory.filter((item) => typeof item === 'string');
+    return importLegacyPromptHistory(entries);
+}
+function importCounters(legacy) {
+    const patch = {};
+    if (typeof legacy.submitCount === 'number')
+        patch.submitCount = legacy.submitCount;
+    if (typeof legacy.mouseNoticeSeen === 'boolean')
+        patch.mouseNoticeSeen = legacy.mouseNoticeSeen;
+    if (Object.keys(patch).length === 0)
+        return;
+    importLegacyUiState(patch);
+}

package/dist/config/prompt-history.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+export declare const PROMPT_HISTORY_FILENAME = "prompt-history.jsonl";
+export declare 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 declare const PROMPT_ENTRY_MAX_CHARS = 16384;
+/** Physical lines tolerated before the file is rewritten down to the cap. */
+export declare const HISTORY_COMPACT_AT_LINES = 400;
+export interface PromptHistoryEntry {
+    /** Line schema version. Lines with any other value are skipped, not fatal. */
+    v: number;
+    /** `Date.now()` at submit time. */
+    ts: number;
+    /** The prompt verbatim — never redacted (D-5). */
+    text: string;
+}
+/**
+ * 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 declare function loadPromptHistory(): string[];
+/** Every entry on disk with its timestamp, newest first. For `history list`. */
+export declare function listPromptHistory(): PromptHistoryEntry[];
+/**
+ * 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 declare function appendPrompt(text: string, now?: number): string[];
+/**
+ * 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 declare function importLegacyPromptHistory(entries: string[]): number;
+/** Delete the file and empty the cache. Returns how many entries were removed. */
+export declare function clearPromptHistory(): number;
+/** Called once by `loadConfig()` after `historyEnabled` has been resolved. */
+export declare function setHistoryEnabled(enabled: boolean): void;
+/** Test-only: forget the cache, the line counters and the switch. */
+export declare function resetPromptHistoryForTests(): void;