@aragon-agent/cli 0.5.0 → 0.5.1

package/dist/logging/file-sink.js

@@ -0,0 +1,326 @@
+/**
+ * The file sink — a memory queue in front of ONE synchronous append fd.
+ *
+ * WHY NOT `createWriteStream` (design P1-4). Three reasons, each fatal on its
+ * own:
+ *   - a stream's internal buffer is DISCARDED by `process.exit()`, and the
+ *     records still sitting in it during a crash are the ones worth having;
+ *   - an exit-path `appendFileSync` plus a steady-state stream are two writers
+ *     on one file with no defined ordering between them;
+ *   - a stream reports write failures through an async `'error'` event, which
+ *     THROWS when nobody is listening — so "make the log directory read-only"
+ *     would take the whole CLI down instead of degrading.
+ *
+ * With `openSync` + `writeSync` every failure is a synchronous throw one
+ * `try/catch` away, and `flushSync()` and the steady-state flush are literally
+ * the same code path. `O_APPEND` keeps concurrent `aragon` processes from
+ * truncating each other, and one batched `writeSync` stays far below any size
+ * that could tear a line.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, statSync, writeSync, } from 'node:fs';
+import { join } from 'node:path';
+/** Flush triggers: whichever of the two comes first. */
+const FLUSH_AT_RECORDS = 64;
+const FLUSH_INTERVAL_MS = 200;
+/**
+ * Hard queue ceiling. On overflow the NEWEST records are dropped and the head
+ * is kept: in a flood, the oldest lines are the ones that explain how it
+ * started, so discarding them first would throw away the log's whole value at
+ * the moment it finally has some.
+ *
+ * A backstop rather than a working limit — `write()` flushes at
+ * `FLUSH_AT_RECORDS` and the flush is synchronous, so the queue does not
+ * normally grow past that. It stays because the batching threshold is a tuning
+ * knob and an unbounded array behind one is not something to rediscover later.
+ * The drop COUNTER, by contrast, is reached routinely: see `flushSync`, where a
+ * failed write would otherwise discard its batch without a word.
+ */
+const MAX_QUEUED_RECORDS = 5000;
+/** Consecutive write failures after which the sink stops trying (§4.4.6). */
+const MAX_CONSECUTIVE_FAILURES = 3;
+const FILE_PREFIX = 'aragon-';
+const FILE_SUFFIX = '.log';
+/**
+ * `YYYY-MM-DD` in LOCAL time.
+ *
+ * Local, not UTC, and the record timestamps use the same clock deliberately: a
+ * user west of UTC would otherwise find an evening's records filed under the
+ * previous local day and stamped with the next one, which makes "open today's
+ * log" a lie twice over.
+ */
+export function localDateStamp(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/**
+ * Delete the oldest files until at most `maxFiles` remain.
+ *
+ * A STANDALONE STEP, called on three occasions — first write of the process,
+ * midnight roll-over, and size rotation — because retention that only ran
+ * during size rotation would never fire for the many users who never reach
+ * `maxFileBytes`: one file per day, forever, under a setting that says 10.
+ *
+ * Never throws. On Windows another `aragon` process may hold a handle on a file
+ * we would like to remove; that is a reason to skip it, not to fail a write.
+ */
+export function enforceRetention(dir, maxFiles) {
+    try {
+        const files = readdirSync(dir)
+            .filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX))
+            .map((name) => {
+            const full = join(dir, name);
+            try {
+                return { full, mtime: statSync(full).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null)
+            .sort((a, b) => a.mtime - b.mtime);
+        for (const entry of files.slice(0, Math.max(0, files.length - maxFiles))) {
+            try {
+                rmSync(entry.full, { force: true });
+            }
+            catch {
+                // Locked by another instance. Retention is best-effort by design.
+            }
+        }
+    }
+    catch {
+        // Directory does not exist yet, or is unreadable. Nothing to retain.
+    }
+}
+export class FileSink {
+    options;
+    queue = [];
+    dropped = 0;
+    fd = null;
+    currentFile = null;
+    currentDay = '';
+    currentSize = 0;
+    timer = null;
+    failures = 0;
+    failed = false;
+    failureReason;
+    retentionRun = false;
+    constructor(options) {
+        this.options = { ...options };
+    }
+    get disabled() {
+        return this.failed;
+    }
+    get lastError() {
+        return this.failureReason;
+    }
+    /** The file records are going to right now (may not exist until first write). */
+    get currentPath() {
+        if (this.currentFile)
+            return this.currentFile;
+        return join(this.options.dir, `${FILE_PREFIX}${localDateStamp()}${FILE_SUFFIX}`);
+    }
+    /** Enqueue one already-serialised line (including its trailing newline). */
+    write(line) {
+        if (this.failed)
+            return;
+        if (this.queue.length >= MAX_QUEUED_RECORDS) {
+            this.dropped += 1;
+            return;
+        }
+        this.queue.push(line);
+        if (this.queue.length >= FLUSH_AT_RECORDS) {
+            this.flushSync();
+            return;
+        }
+        this.startTimer();
+    }
+    /** Threshold/timer flush. Identical to `flushSync` — see the module header. */
+    flush() {
+        this.flushSync();
+    }
+    /** Idempotent: safe to call from `exit`, a signal handler and a crash handler. */
+    flushSync() {
+        if (this.queue.length === 0 && this.dropped === 0)
+            return;
+        if (this.failed) {
+            this.queue = [];
+            return;
+        }
+        const pending = this.queue.length;
+        const droppedBefore = this.dropped;
+        const batch = this.takeBatch();
+        try {
+            this.prepareTarget(Buffer.byteLength(batch));
+            writeSync(this.fd, batch);
+            this.currentSize += Buffer.byteLength(batch);
+            this.failures = 0;
+        }
+        catch (err) {
+            // The batch is gone — retrying it would need the queue to grow unbounded
+            // behind a directory that may never become writable. But it is ACCOUNTED
+            // FOR: the count (including the notice this batch was carrying) rides
+            // along to the next flush that succeeds. Silently losing records is the
+            // one thing a logger must not do.
+            this.dropped = droppedBefore + pending;
+            this.recordFailure(err);
+        }
+    }
+    close() {
+        this.flushSync();
+        this.stopTimer();
+        this.closeFd();
+    }
+    /**
+     * Apply new settings. Changing the directory closes the current fd so the next
+     * write lazily opens the new one; the sink never eagerly creates a directory
+     * the user may never write a record into.
+     */
+    reconfigure(options) {
+        const dirChanged = options.dir !== this.options.dir;
+        if (dirChanged) {
+            this.flushSync();
+            this.closeFd();
+            this.retentionRun = false;
+        }
+        this.options = { ...this.options, ...options };
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    takeBatch() {
+        const lines = this.queue;
+        this.queue = [];
+        if (this.dropped > 0) {
+            const notice = this.options.formatDropNotice?.(this.dropped);
+            this.dropped = 0;
+            // Appended, not prepended: it describes what happened to the records that
+            // would have followed these, and silence about a drop is unacceptable.
+            if (notice)
+                lines.push(notice);
+        }
+        return lines.join('');
+    }
+    /** Open (or roll) the target file so `incomingBytes` can be appended to it. */
+    prepareTarget(incomingBytes) {
+        const day = localDateStamp();
+        if (this.fd !== null && day !== this.currentDay) {
+            // Midnight: yesterday's file keeps its own name, so there is nothing to
+            // rename — just close it and open today's. Retention runs here because
+            // this is the path a user who never hits `maxFileBytes` takes every day.
+            this.closeFd();
+            this.openTarget(day);
+            enforceRetention(this.options.dir, this.options.maxFiles);
+        }
+        if (this.fd === null) {
+            this.openTarget(day);
+            if (!this.retentionRun) {
+                this.retentionRun = true;
+                enforceRetention(this.options.dir, this.options.maxFiles);
+            }
+        }
+        if (this.currentSize + incomingBytes > this.options.maxFileBytes) {
+            this.rotateBySize(day);
+        }
+    }
+    openTarget(day) {
+        mkdirSync(this.options.dir, { recursive: true, mode: 0o700 });
+        const file = join(this.options.dir, `${FILE_PREFIX}${day}${FILE_SUFFIX}`);
+        this.fd = openSync(file, 'a', 0o600);
+        this.currentFile = file;
+        this.currentDay = day;
+        this.currentSize = existsSync(file) ? statSync(file).size : 0;
+    }
+    /**
+     * flush → close → rename → open → retention, in that order.
+     *
+     * `closeSync` MUST precede `renameSync`: on Windows renaming a file the
+     * process still holds a handle on fails with EPERM. A failed rename is
+     * swallowed and writing continues into the original file — two instances
+     * rotating at once should cost an extra small file, not the log itself.
+     */
+    rotateBySize(day) {
+        const previous = this.currentFile;
+        const index = this.nextRotationIndex(day);
+        const target = join(this.options.dir, `${FILE_PREFIX}${day}.${index}${FILE_SUFFIX}`);
+        this.closeFd();
+        if (previous) {
+            try {
+                renameSync(previous, target);
+            }
+            catch {
+                // Another instance won the race, or holds a handle. Keep writing.
+            }
+        }
+        this.openTarget(day);
+        enforceRetention(this.options.dir, this.options.maxFiles);
+    }
+    /** Highest existing `aragon-<day>.<n>.log` index, plus one. */
+    nextRotationIndex(day) {
+        const prefix = `${FILE_PREFIX}${day}.`;
+        let max = 0;
+        try {
+            for (const name of readdirSync(this.options.dir)) {
+                if (!name.startsWith(prefix) || !name.endsWith(FILE_SUFFIX))
+                    continue;
+                const n = Number.parseInt(name.slice(prefix.length, name.length - FILE_SUFFIX.length), 10);
+                if (Number.isFinite(n) && n > max)
+                    max = n;
+            }
+        }
+        catch {
+            // Unreadable directory: index 1 is as good a guess as any.
+        }
+        return max + 1;
+    }
+    closeFd() {
+        if (this.fd === null)
+            return;
+        try {
+            closeSync(this.fd);
+        }
+        catch {
+            // Already closed by a racing handler; nothing to do.
+        }
+        this.fd = null;
+        this.currentFile = null;
+        this.currentSize = 0;
+    }
+    /**
+     * Logging failure must never become CLI failure, and must never write to the
+     * terminal itself (invariant I-4 — a stray line permanently misaligns the
+     * full-screen frame). The owner is told once through `onFailure`, which routes
+     * to a toast when the TUI is mounted and to stderr when it is not.
+     */
+    recordFailure(err) {
+        this.failures += 1;
+        this.failureReason = err instanceof Error ? err.message : String(err);
+        this.closeFd();
+        if (this.failures < MAX_CONSECUTIVE_FAILURES)
+            return;
+        this.failed = true;
+        this.stopTimer();
+        this.options.onFailure?.(this.failureReason);
+    }
+    startTimer() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.flushSync(), FLUSH_INTERVAL_MS);
+        // Without `unref`, an `aragon --version` that logs one line would be held
+        // open by this timer for 200ms after it had nothing left to do.
+        this.timer.unref?.();
+    }
+    stopTimer() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+}
+/** Exposed for the CLI's `logs` commands, which list the same file family. */
+export function isLogFileName(name) {
+    return name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX);
+}
+/** The log file the CURRENT day would use inside a log directory. */
+export function currentLogFileName(date = new Date()) {
+    return `${FILE_PREFIX}${localDateStamp(date)}${FILE_SUFFIX}`;
+}

package/dist/logging/install.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 { type LogConfig } from '../config/schema.js';
+import { Logger, type LogScope } from './logger.js';
+/**
+ * Hand the screen-restore duty to whoever actually owns the screen.
+ * Called by `runInteractive()`'s full-screen branch and by nobody else.
+ */
+export declare function setScreenRestore(fn: () => void): void;
+/**
+ * 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 declare function setSignalTerminator(fn: (signo: number) => void): void;
+/** Tests only: undo the hook swaps so cases cannot leak into each other. */
+export declare function resetProcessHooksForTest(): void;
+export interface PendingNote {
+    level: 'info' | 'warn' | 'error';
+    scope: LogScope;
+    msg: string;
+    data?: Record<string, unknown>;
+}
+/** The process surface the hooks need, so tests can pass a stub. */
+export interface ProcessHookPort {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    exit(code: number): never;
+    stderr: {
+        write(chunk: string): unknown;
+    };
+}
+export interface InstallLoggingOptions {
+    /** Notes accumulated before a logger existed (migrations, path warnings). */
+    pending?: PendingNote[];
+    /** Injectable for tests; defaults to `process.argv`. */
+    argv?: string[];
+    /** Injectable for tests; defaults to the real `process`. */
+    processPort?: ProcessHookPort;
+}
+/**
+ * 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 declare function resolveBootstrapLogConfig(argv?: string[]): LogConfig;
+/**
+ * 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 declare function installLogging(opts?: InstallLoggingOptions): Logger;
+/**
+ * What `attachAgentEvents` needs from a controller.
+ *
+ * Structural rather than a direct `AgentController` import: it keeps this module
+ * off the controller's dependency graph, and it lets the tests feed the nine
+ * event shapes through a few lines of fake instead of a live agent.
+ */
+export interface AgentEventSource {
+    subscribe(listener: (event: AgentLogEvent) => void): () => void;
+    getConfig(): {
+        provider: string;
+        model: string;
+        thinkingLevel: string;
+    };
+}
+/** The nine members of the core `AgentEvent` union, as this module reads them. */
+export type AgentLogEvent = {
+    type: 'agent_start';
+} | {
+    type: 'agent_end';
+    messages: unknown[];
+} | {
+    type: 'turn_start';
+} | {
+    type: 'turn_end';
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+} | {
+    type: 'message_update';
+    streamEvent?: {
+        type?: string;
+        delta?: unknown;
+    };
+} | {
+    type: 'tool_execution_start';
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+} | {
+    type: 'tool_execution_end';
+    toolName?: string;
+    duration?: number;
+    isError?: boolean;
+    result?: unknown;
+} | {
+    type: 'code_execution_start';
+    language?: string;
+    code?: string;
+} | {
+    type: 'code_execution_end';
+    duration?: number;
+    error?: string;
+    output?: string;
+};
+/**
+ * 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 declare function attachAgentEvents(logger: Logger, controller: AgentEventSource): () => void;