@aragon-agent/cli 0.4.3 → 0.5.1

package/dist/logging/install.js

@@ -0,0 +1,302 @@
+/**
+ * Assembly: bootstrap level resolution, replay of what happened before the
+ * logger existed, ownership of the four process hooks, and the agent-event
+ * mapping.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * SINGLE-OWNER MODEL — the part that is easiest to get wrong and hardest to
+ * notice, because getting it wrong still compiles and still passes a smoke test.
+ *
+ *   The logger owns FLUSHING and never owns EXITING.
+ *   The screen owns RESTORING and never owns FLUSHING.
+ *
+ * All four hooks below change Node's default behaviour merely by existing:
+ *
+ *   `uncaughtException`  — registering a listener REPLACES Node's "print the
+ *       stack and exit". `main().catch()` in `cli.tsx` is not that hook; it is a
+ *       promise chain's catch and only ever sees rejections of that one chain.
+ *       So there is no prior behaviour to inherit: without an explicit
+ *       `process.exit(1)` here, an exception thrown inside an Ink render
+ *       callback or a timer stops terminating the process. In full-screen that
+ *       means the alternate screen is never restored and Ink keeps drawing onto
+ *       a broken controller — the user's only way out is `reset`.
+ *
+ *   `unhandledRejection` — Node 18 defaults to `--unhandled-rejections=throw`.
+ *       Adding a listener suppresses it, turning a crash into a silent hang.
+ *
+ *   `SIGINT` / `SIGTERM` / `SIGHUP` — the handlers in `runInteractive()` exist
+ *       ONLY in its full-screen branch, so inline mode, `-p`, and every
+ *       subcommand had no handler at all and took Node's default termination,
+ *       which does not run `'exit'` listeners: the whole queue was lost. But a
+ *       signal listener registered here runs BEFORE the one `runInteractive`
+ *       would add (EventEmitter order), and merely having one stops Node from
+ *       terminating — so it must exit itself, and would then beat the screen
+ *       restore. Hence: this module flushes and then calls a REPLACEABLE
+ *       terminator. The default is a bare exit, which covers headless and every
+ *       subcommand; the full-screen branch swaps in one that restores first.
+ * ══════════════════════════════════════════════════════════════════════════
+ */
+import process from 'node:process';
+import { getHomeResolutionWarning } from '../config/app-paths.js';
+import { readConfigFile } from '../config/store.js';
+import { clampLogConfig } from '../config/schema.js';
+import { clampLogLevel } from './levels.js';
+import { Logger, setActiveLogger } from './logger.js';
+import { registerSecretsFrom } from './secret-registry.js';
+/** POSIX signal numbers for the `128 + signo` exit-code convention. */
+const SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1 };
+let screenRestore = () => { };
+/**
+ * `null` means "use the default", which is a bare exit through the same process
+ * port the hooks were installed on. Holding the default here as a closure over
+ * the global `process` instead would make it a second exit channel — invisible
+ * to anything that injected a port, which is exactly the sort of divergence
+ * these hooks must not have.
+ */
+let signalTerminator = null;
+/**
+ * Hand the screen-restore duty to whoever actually owns the screen.
+ * Called by `runInteractive()`'s full-screen branch and by nobody else.
+ */
+export function setScreenRestore(fn) {
+    screenRestore = fn;
+}
+/**
+ * Replace what a signal does after the flush. The default (a bare
+ * `exit(128 + signo)`) is correct for headless, inline and every subcommand;
+ * full-screen substitutes one that restores the terminal first.
+ */
+export function setSignalTerminator(fn) {
+    signalTerminator = fn;
+}
+/** Tests only: undo the hook swaps so cases cannot leak into each other. */
+export function resetProcessHooksForTest() {
+    screenRestore = () => { };
+    signalTerminator = null;
+}
+/**
+ * Resolve the BOOTSTRAP level.
+ *
+ * Inputs are only `process.env`, the config file, and a deliberately tiny argv
+ * scan. Not commander (it has not parsed yet) and not `.env` (`loadDotenv()`
+ * runs inside `loadConfig()`, much later). This level covers exactly the window
+ * before `loadConfig()` — migrations, path warnings, an early crash — after
+ * which `Logger.reconfigure()` installs the authoritative one.
+ *
+ * The duplication with `loadConfig()` is intentional and cheap. The alternative
+ * is to install the logger after config resolution, which would leave precisely
+ * the events that are hardest to debug with nowhere to be recorded.
+ */
+export function resolveBootstrapLogConfig(argv = process.argv) {
+    const file = readConfigFile().config ?? {};
+    const base = clampLogConfig({
+        ...(file.log ?? {}),
+        ...(process.env.ARAGON_LOG_LEVEL ? { level: process.env.ARAGON_LOG_LEVEL } : {}),
+        ...(process.env.ARAGON_LOG_DIR ? { dir: process.env.ARAGON_LOG_DIR } : {}),
+    });
+    const scanned = scanLoggingArgv(argv);
+    const toFile = scanned.toFile ?? readEnvToFile() ?? (file.log?.toFile === false ? false : true);
+    return clampLogConfig({
+        ...base,
+        ...(scanned.level ? { level: scanned.level } : {}),
+        ...(scanned.dir ? { dir: scanned.dir } : {}),
+        toFile,
+    });
+}
+function readEnvToFile() {
+    const raw = process.env.ARAGON_LOG_FILE?.trim().toLowerCase();
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    return !(raw === '0' || raw === 'false' || raw === 'off' || raw === 'no');
+}
+/**
+ * The minimal hand scan of argv.
+ *
+ * `-vv` is NOT accepted, and must not be added: `-v` is already `--version`
+ * (`cli.tsx`), so commander would reject `-vv` as an unknown option before this
+ * level was ever used. A flag that internal docs promise and the parser refuses
+ * is worse than no flag.
+ */
+function scanLoggingArgv(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--verbose')
+            out.level = 'debug';
+        else if (arg === '--no-log-file')
+            out.toFile = false;
+        else if (arg === '--log-file')
+            out.toFile = true;
+        else if (arg === '--log-level')
+            out.level = clampLogLevel(argv[i + 1], 'info');
+        else if (arg.startsWith('--log-level='))
+            out.level = clampLogLevel(arg.slice(12), 'info');
+        else if (arg === '--log-dir')
+            out.dir = argv[i + 1];
+        else if (arg.startsWith('--log-dir='))
+            out.dir = arg.slice(10);
+    }
+    return out;
+}
+/**
+ * Build the logger, replay what came before it, and take ownership of the four
+ * process hooks. Returns the logger, which is also installed as the singleton.
+ */
+export function installLogging(opts = {}) {
+    const port = opts.processPort ?? process;
+    const logger = new Logger(resolveBootstrapLogConfig(opts.argv));
+    setActiveLogger(logger);
+    // Registration site 1 (§4.4.3): whatever the config file already holds. Sites
+    // 2, 3, 4 and 5 add the env, the merged view plus `--api-key`, the settings
+    // screen, and every persisted write respectively.
+    registerSecretsFrom(readConfigFile().config?.apiKeys ?? undefined);
+    const warning = getHomeResolutionWarning();
+    if (warning)
+        logger.warn('cli', 'home_resolution_fallback', { reason: warning });
+    for (const note of opts.pending ?? []) {
+        logger[note.level](note.scope, note.msg, note.data);
+    }
+    installProcessHooks(logger, port);
+    return logger;
+}
+function installProcessHooks(logger, port) {
+    port.on('uncaughtException', (err) => {
+        handleFatal(logger, port, 'uncaught_exception', err);
+    });
+    port.on('unhandledRejection', (reason) => {
+        handleFatal(logger, port, 'unhandled_rejection', reason);
+    });
+    // Normal exit. Only synchronous work is possible here, and the whole write
+    // path is synchronous precisely so this can be one line.
+    port.on('exit', () => {
+        logger.flushSync();
+    });
+    for (const [name, signo] of Object.entries(SIGNAL_NUMBERS)) {
+        port.on(name, () => {
+            logger.flushSync();
+            // Exiting is NOT optional here: merely having a signal listener stops Node
+            // from terminating by default, so skipping this would turn Ctrl+C into
+            // "nothing happens" for every path that has not replaced the terminator.
+            if (signalTerminator) {
+                signalTerminator(signo);
+                return;
+            }
+            port.exit(128 + signo);
+        });
+    }
+}
+/**
+ * The crash path, in an order that is not negotiable:
+ *
+ *   record -> flush -> restore the screen -> write the stack -> EXIT
+ *
+ * Restoring before writing matters: a stack printed into the alternate screen
+ * disappears together with it. Exiting at all matters more — see the module
+ * header. A failure inside logging must not stop the last two steps, so the
+ * first two are wrapped.
+ */
+function handleFatal(logger, port, msg, err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    try {
+        logger.error('cli', msg, { message: error.message, stack: error.stack });
+        logger.flushSync();
+    }
+    catch {
+        // Logging must never be the reason a crash fails to surface.
+    }
+    screenRestore();
+    port.stderr.write(`${error.stack ?? error.message}\n`);
+    return port.exit(1);
+}
+/** Trim user content to the configured preview budget (debug only). */
+function preview(value, limit) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value) ?? '';
+    return text.length > limit ? `${text.slice(0, limit)}…` : text;
+}
+/**
+ * Subscribe to the agent's events and record them.
+ *
+ * Returns the unsubscribe function `controller.subscribe()` gives back.
+ *
+ * `message_update` fires thousands of times per answer, so it is `trace`-only
+ * AND records no content — a `debug` run would otherwise write a log larger
+ * than the conversation. The turn timer is a closure variable rather than
+ * module state because `turn_end` carries `{message, usage}` and NO duration,
+ * so the elapsed time has to be measured here; module state would let one test
+ * (or a future second controller) read another's clock.
+ */
+export function attachAgentEvents(logger, controller) {
+    let turnStartedAt = 0;
+    return controller.subscribe((event) => {
+        switch (event.type) {
+            case 'agent_start': {
+                // The event itself carries no fields; the three the reader wants are
+                // the controller's current configuration.
+                const cfg = controller.getConfig();
+                logger.info('agent', 'run_start', {
+                    provider: cfg.provider,
+                    model: cfg.model,
+                    thinking: cfg.thinkingLevel,
+                });
+                break;
+            }
+            case 'turn_start':
+                turnStartedAt = Date.now();
+                logger.debug('agent', 'turn_start');
+                break;
+            case 'turn_end':
+                logger.info('agent', 'turn_end', {
+                    in: event.usage?.inputTokens ?? 0,
+                    out: event.usage?.outputTokens ?? 0,
+                    ms: turnStartedAt > 0 ? Date.now() - turnStartedAt : 0,
+                });
+                break;
+            case 'message_update':
+                logger.trace('agent', 'stream', {
+                    type: event.streamEvent?.type ?? 'unknown',
+                    // The SIZE of the increment, never the increment. It is what makes a
+                    // trace log usable for "where did the time go" without turning it
+                    // into a second copy of the conversation.
+                    delta: typeof event.streamEvent?.delta === 'string'
+                        ? event.streamEvent.delta.length
+                        : undefined,
+                });
+                break;
+            case 'tool_execution_start':
+                logger.debug('tool', 'tool_start', {
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    ...(logger.isEnabled('debug') ? { args: preview(event.args, logger.previewChars) } : {}),
+                });
+                break;
+            case 'tool_execution_end':
+                logger.info('tool', 'tool_end', {
+                    toolName: event.toolName,
+                    ms: event.duration ?? 0,
+                    isError: event.isError === true,
+                    ...(logger.isEnabled('debug')
+                        ? { result: preview(event.result, logger.previewChars) }
+                        : {}),
+                });
+                break;
+            case 'code_execution_start':
+                logger.debug('tool', 'code_start', {
+                    language: event.language,
+                    ...(logger.isEnabled('debug') ? { code: preview(event.code, logger.previewChars) } : {}),
+                });
+                break;
+            case 'code_execution_end':
+                logger.info('tool', 'code_end', {
+                    ms: event.duration ?? 0,
+                    isError: Boolean(event.error),
+                    ...(logger.isEnabled('debug')
+                        ? { output: preview(event.output, logger.previewChars) }
+                        : {}),
+                });
+                break;
+            case 'agent_end':
+                logger.info('agent', 'run_end', { messages: event.messages?.length ?? 0 });
+                break;
+        }
+    });
+}

package/dist/logging/levels.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Log levels — the ordering, the names, and the two coercion helpers.
+ *
+ * Kept in its own module because it is the one piece of the logging subsystem
+ * the config layer (`schema.ts`) and the settings screen need, and neither
+ * should have to pull in a file sink to learn what "debug" is called.
+ *
+ * PRIVACY IS PART OF THE LADDER, not a side effect of it:
+ *
+ *   error  crashes, failed requests, config write/parse failures
+ *   warn   degraded migrations, clamped values, dropped records
+ *   info   lifecycle, config writes, turn boundaries + token counts, tool
+ *          names and durations — NO conversation content at all
+ *   debug  the above plus prompts / replies / tool args truncated to
+ *          `previewChars`
+ *   trace  full message bodies, full tool arguments and output
+ *
+ * `info` is the default precisely so that "send me your log" is a safe thing to
+ * ask a user. `debug` and above are not, and the README says so.
+ */
+export declare const LOG_LEVELS: {
+    readonly silent: 0;
+    readonly error: 10;
+    readonly warn: 20;
+    readonly info: 30;
+    readonly debug: 40;
+    readonly trace: 50;
+};
+export type LogLevelName = keyof typeof LOG_LEVELS;
+export declare const LOG_LEVEL_NAMES: readonly LogLevelName[];
+export declare function isLogLevel(v: unknown): v is LogLevelName;
+/**
+ * Coerce anything into a level, falling back rather than throwing.
+ *
+ * Same discipline as `clampTheme` / `clampThinkingLevel`: a nonsense value in
+ * the config file must not stop the CLI from starting.
+ */
+export declare function clampLogLevel(v: unknown, fallback: LogLevelName): LogLevelName;
+/** True when a record at `level` should be emitted under `threshold`. */
+export declare function isLevelEnabled(level: LogLevelName, threshold: LogLevelName): boolean;

package/dist/logging/levels.js

@@ -0,0 +1,59 @@
+/**
+ * Log levels — the ordering, the names, and the two coercion helpers.
+ *
+ * Kept in its own module because it is the one piece of the logging subsystem
+ * the config layer (`schema.ts`) and the settings screen need, and neither
+ * should have to pull in a file sink to learn what "debug" is called.
+ *
+ * PRIVACY IS PART OF THE LADDER, not a side effect of it:
+ *
+ *   error  crashes, failed requests, config write/parse failures
+ *   warn   degraded migrations, clamped values, dropped records
+ *   info   lifecycle, config writes, turn boundaries + token counts, tool
+ *          names and durations — NO conversation content at all
+ *   debug  the above plus prompts / replies / tool args truncated to
+ *          `previewChars`
+ *   trace  full message bodies, full tool arguments and output
+ *
+ * `info` is the default precisely so that "send me your log" is a safe thing to
+ * ask a user. `debug` and above are not, and the README says so.
+ */
+export const LOG_LEVELS = {
+    silent: 0,
+    error: 10,
+    warn: 20,
+    info: 30,
+    debug: 40,
+    trace: 50,
+};
+export const LOG_LEVEL_NAMES = [
+    'silent',
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'trace',
+];
+export function isLogLevel(v) {
+    return typeof v === 'string' && Object.prototype.hasOwnProperty.call(LOG_LEVELS, v);
+}
+/**
+ * Coerce anything into a level, falling back rather than throwing.
+ *
+ * Same discipline as `clampTheme` / `clampThinkingLevel`: a nonsense value in
+ * the config file must not stop the CLI from starting.
+ */
+export function clampLogLevel(v, fallback) {
+    if (isLogLevel(v))
+        return v;
+    if (typeof v === 'string' && isLogLevel(v.trim().toLowerCase())) {
+        return v.trim().toLowerCase();
+    }
+    return fallback;
+}
+/** True when a record at `level` should be emitted under `threshold`. */
+export function isLevelEnabled(level, threshold) {
+    if (threshold === 'silent')
+        return false;
+    return LOG_LEVELS[level] <= LOG_LEVELS[threshold];
+}

package/dist/logging/logger.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The logger: level filtering, record shape, redaction, and the module-level
+ * singleton every other file reaches through `getLogger()`.
+ *
+ * WIRE FORMAT — one `JSON.stringify(record)` per line, UTF-8, no BOM:
+ *
+ *   {"ts":"2026-07-27T12:11:02.913+08:00","lv":"info","sid":"7f3a91c2",
+ *    "pid":24188,"scope":"agent","msg":"turn_end",
+ *    "data":{"provider":"anthropic","in":1284,"out":377,"ms":4210}}
+ *
+ * THE SHORT KEYS ARE DELIBERATE AND MUST NOT BE "FIXED". The package's clean-code
+ * guide forbids names like `data`, and rightly so for TypeScript identifiers.
+ * These are not identifiers: they are the on-disk contract, repeated on every
+ * line of a file that reaches megabytes, and already parsed by whatever `jq`
+ * one-liner a user has written. Renaming them breaks every existing log and
+ * every existing script for a readability gain nobody experiences. Variable and
+ * function names in this file get no such exemption.
+ *
+ * `sid` and `pid` both exist because several `aragon` processes append to the
+ * same day's file: `sid` separates their interleaved lines, and `pid` is what
+ * still matches up with what the OS recorded after a crash.
+ */
+import type { LogConfig } from '../config/schema.js';
+import { type LogLevelName } from './levels.js';
+/** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log';
+export interface LogRecord {
+    ts: string;
+    lv: LogLevelName;
+    sid: string;
+    pid: number;
+    scope: LogScope;
+    msg: string;
+    data?: Record<string, unknown>;
+}
+export interface ScopedLogger {
+    error(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+    trace(msg: string, data?: Record<string, unknown>): void;
+}
+/**
+ * ISO 8601 with the LOCAL offset, matching the local date in the file name.
+ * `toISOString()` would put an evening record west of UTC into the next day
+ * while the file it lands in is named for the previous one.
+ */
+export declare function localIsoTimestamp(date?: Date): string;
+export declare class Logger {
+    private config;
+    private sink;
+    private readonly sid;
+    private failureHandler;
+    constructor(config?: LogConfig);
+    error(scope: LogScope, msg: string, data?: Record<string, unknown>): void;
+    warn(scope: LogScope, msg: string, data?: Record<string, unknown>): void;
+    info(scope: LogScope, msg: string, data?: Record<string, unknown>): void;
+    debug(scope: LogScope, msg: string, data?: Record<string, unknown>): void;
+    trace(scope: LogScope, msg: string, data?: Record<string, unknown>): void;
+    child(scope: LogScope): ScopedLogger;
+    /** Whether a record at `level` would be written — lets callers skip the work. */
+    isEnabled(level: LogLevelName): boolean;
+    /** Truncation budget for user content at `debug`. `trace` ignores it. */
+    get previewChars(): number;
+    get level(): LogLevelName;
+    setLevel(level: LogLevelName): void;
+    /**
+     * THE authoritative-level hand-off (§4.4.5).
+     *
+     * `installLogging()` resolves a bootstrap level from `process.env`, the config
+     * file and a tiny argv scan, because it has to run before commander exists and
+     * before `loadDotenv()`. That bootstrap level covers migrations and early
+     * crashes and nothing else. Once `loadConfig()` has produced the real answer,
+     * every path calls this exactly once. Without it the fully-resolved level —
+     * including anything from `.env` — would simply never take effect.
+     *
+     * Idempotent, and safe after writing has already begun.
+     */
+    reconfigure(config: LogConfig): void;
+    /** Registered by whoever owns a user-visible channel (toast, or stderr). */
+    onFailure(cb: (reason: string) => void): void;
+    /** Idempotent; `exit`, the signal hook and the crash hooks all call it. */
+    flushSync(): void;
+    /**
+     * Where records are going, for `aragon logs path`.
+     *
+     * Answers with a FILE path even before the sink has been created — the
+     * question is "where would I look?", and a bare directory is not that answer.
+     */
+    currentLogPath(): string;
+    get sinkError(): string | undefined;
+    get sinkDisabled(): boolean;
+    /** Closes the fd so a caller may delete the files (`aragon logs clear`). */
+    closeSink(): void;
+    private emit;
+    private resolveDir;
+    private sinkOptions;
+    /**
+     * Created on the FIRST record that actually passes the filters, never in
+     * `installLogging()`. `aragon --version`, `aragon config path` and anyone
+     * running with `--no-log-file` must not leave an empty directory behind.
+     */
+    private ensureSink;
+    private renderDropNotice;
+}
+export declare function getLogger(): Logger;
+/** Called by `installLogging()`; not part of the general API. */
+export declare function setActiveLogger(logger: Logger): void;
+/** Tests only — returns the singleton to its pre-install state. */
+export declare function resetLoggerForTest(): void;