@aragon-agent/cli 0.5.1 → 0.5.3

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

@@ -27,6 +27,8 @@ export interface CliFlags {
     compact?: boolean;
     /** `--hints` ⇒ true, `--no-hints` ⇒ false, absent ⇒ undefined. */
     hints?: boolean;
+    /** `--mouse` ⇒ true, `--no-mouse` ⇒ false, absent ⇒ undefined. */
+    mouse?: boolean;
     /** `--no-skills` ⇒ false. Turns the whole skill subsystem off (§7.5). */
     skills?: boolean;
     /** `--skill <name>` ×N — force Level 2 injection for this run. */
@@ -37,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, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, 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';
@@ -33,6 +36,28 @@ function resolveFullscreen(flags, env, file) {
         return false;
     return undefined;
 }
+/**
+ * Resolve wheel region routing: flag › env › file › default `true`.
+ *
+ * THIS NEEDS ITS OWN RESOLVER; it does not "match every other boolean" in this
+ * file. `hints` is `flags.hints !== undefined ? … : file.hints ?? DEFAULT` and
+ * reads NO ENV AT ALL — copying that line would ship `ARAGON_MOUSE` as
+ * documented-but-dead (P1-9). Only `fullscreen` has an env layer, and only
+ * because `resolveFullscreen` above was written to give it one.
+ *
+ * Unlike `fullscreen` this is a plain boolean rather than a tri-state: there
+ * are no heuristics for an explicit `true` to override, so a persisted `true`
+ * is just a value and not an opinion that has to be told apart from silence.
+ */
+function resolveMouse(flags, env, file) {
+    if (flags.mouse !== undefined)
+        return flags.mouse;
+    if (env.mouse !== undefined)
+        return env.mouse;
+    if (file.mouse !== undefined)
+        return file.mouse;
+    return DEFAULT_CONFIG.mouse;
+}
 /**
  * Resolve whether logs reach a file: flag › env › an explicit `false` in the
  * file › default `true`.
@@ -51,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({
@@ -156,7 +202,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,
@@ -173,11 +224,12 @@ export function loadConfig(flags = {}) {
         toolTimeoutMs,
         idleTimeoutMs,
         apiKeys,
-        recentModels: file.recentModels ?? [],
-        promptHistory: file.promptHistory ?? [],
+        historyEnabled,
         density,
         hints,
-        submitCount: coercePositiveInt(file.submitCount, 0),
+        mouse: resolveMouse(flags, env.partial, file),
+        // From `<home>/state.json`, not the config file — see `ui-state.ts`.
+        submitCount: readSubmitCount(),
         startInPlanMode,
         planModeMaxAskRounds,
         planModeHumanTimeoutMs,
@@ -194,12 +246,43 @@ 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,
+        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;