@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/ui/scrollback/exit-summary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Exit summary for native-scroll mode (tui-native-terminal-scroll §4.8 / D9).
+ *
+ * The conversation is already in the terminal's scrollback, so exit does NOT replay
+ * it (that would print every message twice). It prints at most four short lines and
+ * leaves the cursor on a fresh line.
+ *
+ * PURE and ASCII-safe: glyphs come from `pickGlyphs`, and the figures come from the
+ * same `formatSessionStats` the full-screen replay uses.
+ */
+import type { Entry, UsageTotal } from '../../agent/reducer.js';
+import type { Glyphs } from '../glyphs.js';
+export interface ExitSummaryInput {
+    entries: readonly Entry[];
+    usageTotal: UsageTotal;
+    provider: string;
+    model: string;
+    elapsedMs: number;
+    /** The session id, when this process has one worth resuming. */
+    sessionId?: string;
+    glyphs: Pick<Glyphs, 'midDot' | 'arrowUp' | 'arrowDown'>;
+}
+export declare function buildExitSummary(input: ExitSummaryInput): string[];

package/dist/ui/scrollback/exit-summary.js

@@ -0,0 +1,25 @@
+/**
+ * Exit summary for native-scroll mode (tui-native-terminal-scroll §4.8 / D9).
+ *
+ * The conversation is already in the terminal's scrollback, so exit does NOT replay
+ * it (that would print every message twice). It prints at most four short lines and
+ * leaves the cursor on a fresh line.
+ *
+ * PURE and ASCII-safe: glyphs come from `pickGlyphs`, and the figures come from the
+ * same `formatSessionStats` the full-screen replay uses.
+ */
+import { formatDuration } from '../../agent/usage.js';
+import { formatSessionStats } from '../transcript-text.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+export function buildExitSummary(input) {
+    const { glyphs: g } = input;
+    const stats = formatSessionStats(input.entries, input.usageTotal, g);
+    const rows = [
+        ['Session ended', `${input.provider}:${input.model}`, formatDuration(Math.max(0, input.elapsedMs))]
+            .join(` ${g.midDot} `),
+        [stats.turns, stats.tokens, stats.cost].join(` ${g.midDot} `),
+    ];
+    if (input.sessionId)
+        rows.push(`Resume: aragon --resume ${input.sessionId}`);
+    return rows.slice(0, SCROLLBACK_LIMITS.exitSummaryMaxRows);
+}

package/dist/ui/scrollback/limits.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Structural limits of native-scroll mode (tui-native-terminal-scroll §4.3-§4.6).
+ *
+ * Structural caps live here; tunable policy lives in `config/schema.ts`. None of
+ * these is a user preference: each one bounds a failure (a runaway write, a live
+ * region that eats the screen) rather than expressing a taste.
+ */
+export declare const SCROLLBACK_LIMITS: {
+    /** Pending static entries the drain holds before folding the oldest into a marker. */
+    readonly feedCapacity: 32;
+    /** Rows one entry may print; the rest is replaced by one ASCII notice row. */
+    readonly maxRowsPerEntry: 400;
+    /** Static rows per `stdout.write`; larger feeds are split into consecutive batches. */
+    readonly maxRowsPerBatch: 2000;
+    /** tall-frame swallows within this window after a resize are expected and uncounted. */
+    readonly guardResizeGraceMs: 250;
+    /** Consecutive out-of-resize tall frames that degrade the app to the placeholder. */
+    readonly guardTripCount: 3;
+    /** Session summary rows printed on exit. */
+    readonly exitSummaryMaxRows: 4;
+    /** Streaming preview rows, absolute cap. */
+    readonly maxLiveTailRows: 12;
+    /** ... and as a share of the terminal height. */
+    readonly liveTailRowShare: 0.4;
+    /**
+     * Live-region `EntryView` instances per frame (release-gate-and-native-panels §6.5).
+     *
+     * A STRUCTURAL CAP of the same kind as `maxLiveTailRows`: a screenful is at most 12
+     * rows plus 4 component instances, so the band costs the same order of magnitude as
+     * the full-screen live tail and the render governor and every `memo` boundary keep
+     * working. Raising it makes the per-frame cost grow linearly with no windowing.
+     */
+    readonly liveTailMaxEntries: 4;
+    /**
+     * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
+     *
+     * The `+ 1` is not decoration - the rail takes its rows from the same pool as one
+     * preview row, and a band that seats the rail but no preview loses the streaming
+     * answer entirely (band.ts step 3 / AC-12).
+     */
+    readonly railBandMinRows: 4;
+    /**
+     * How long the cursor-position probe waits for `ESC[<row>;<col>R`.
+     *
+     * A STRUCTURAL CAP, not a preference (tui-bottom-anchored-live-region §4.4): it
+     * bounds "how much startup latency a terminal that does not answer may cost". The
+     * round trip is under 5 ms locally and under 60 ms over SSH, so 150 ms is
+     * generous, and the probe runs once per session — never per frame, never per
+     * keystroke. Anything longer and a terminal without CPR support would pay it on
+     * every launch.
+     */
+    readonly anchorProbeTimeoutMs: 150;
+    /**
+     * Settle window before re-measuring the cursor after a resize.
+     *
+     * A STRUCTURAL CAP for the same reason: a drag fires dozens of resize events, and
+     * one CPR per event would both flood the input channel and make the region jitter.
+     * 200 ms is below the point a user perceives as "the input box is stuck".
+     */
+    readonly anchorReprobeDelayMs: 200;
+    /**
+     * Structural ceiling on the height of a STARTING canvas.
+     *
+     * It bounds the bytes a batch may write and the rows the content cache may hold on
+     * an extreme terminal (`rows` 3000). Two limits on how it may be applied, both
+     * arithmetic rather than taste:
+     *  - the rows a canvas leaves unused do not disappear, they stay above it as the
+     *    permanent region, so a smaller starting canvas never loses content;
+     *  - it must NEVER clip a live canvas. A canvas that has overflowed and scrolled
+     *    grows to `rows - 1`, and shrinking one back would make the next erase reach
+     *    above its own top: host output erased, every visible row printed twice.
+     */
+    readonly maxCanvasRows: 200;
+};

package/dist/ui/scrollback/limits.js

@@ -0,0 +1,74 @@
+/**
+ * Structural limits of native-scroll mode (tui-native-terminal-scroll §4.3-§4.6).
+ *
+ * Structural caps live here; tunable policy lives in `config/schema.ts`. None of
+ * these is a user preference: each one bounds a failure (a runaway write, a live
+ * region that eats the screen) rather than expressing a taste.
+ */
+export const SCROLLBACK_LIMITS = {
+    /** Pending static entries the drain holds before folding the oldest into a marker. */
+    feedCapacity: 32,
+    /** Rows one entry may print; the rest is replaced by one ASCII notice row. */
+    maxRowsPerEntry: 400,
+    /** Static rows per `stdout.write`; larger feeds are split into consecutive batches. */
+    maxRowsPerBatch: 2000,
+    /** tall-frame swallows within this window after a resize are expected and uncounted. */
+    guardResizeGraceMs: 250,
+    /** Consecutive out-of-resize tall frames that degrade the app to the placeholder. */
+    guardTripCount: 3,
+    /** Session summary rows printed on exit. */
+    exitSummaryMaxRows: 4,
+    /** Streaming preview rows, absolute cap. */
+    maxLiveTailRows: 12,
+    /** ... and as a share of the terminal height. */
+    liveTailRowShare: 0.4,
+    /**
+     * Live-region `EntryView` instances per frame (release-gate-and-native-panels §6.5).
+     *
+     * A STRUCTURAL CAP of the same kind as `maxLiveTailRows`: a screenful is at most 12
+     * rows plus 4 component instances, so the band costs the same order of magnitude as
+     * the full-screen live tail and the render governor and every `memo` boundary keep
+     * working. Raising it makes the per-frame cost grow linearly with no windowing.
+     */
+    liveTailMaxEntries: 4,
+    /**
+     * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
+     *
+     * The `+ 1` is not decoration - the rail takes its rows from the same pool as one
+     * preview row, and a band that seats the rail but no preview loses the streaming
+     * answer entirely (band.ts step 3 / AC-12).
+     */
+    railBandMinRows: 4,
+    /**
+     * How long the cursor-position probe waits for `ESC[<row>;<col>R`.
+     *
+     * A STRUCTURAL CAP, not a preference (tui-bottom-anchored-live-region §4.4): it
+     * bounds "how much startup latency a terminal that does not answer may cost". The
+     * round trip is under 5 ms locally and under 60 ms over SSH, so 150 ms is
+     * generous, and the probe runs once per session — never per frame, never per
+     * keystroke. Anything longer and a terminal without CPR support would pay it on
+     * every launch.
+     */
+    anchorProbeTimeoutMs: 150,
+    /**
+     * Settle window before re-measuring the cursor after a resize.
+     *
+     * A STRUCTURAL CAP for the same reason: a drag fires dozens of resize events, and
+     * one CPR per event would both flood the input channel and make the region jitter.
+     * 200 ms is below the point a user perceives as "the input box is stuck".
+     */
+    anchorReprobeDelayMs: 200,
+    /**
+     * Structural ceiling on the height of a STARTING canvas.
+     *
+     * It bounds the bytes a batch may write and the rows the content cache may hold on
+     * an extreme terminal (`rows` 3000). Two limits on how it may be applied, both
+     * arithmetic rather than taste:
+     *  - the rows a canvas leaves unused do not disappear, they stay above it as the
+     *    permanent region, so a smaller starting canvas never loses content;
+     *  - it must NEVER clip a live canvas. A canvas that has overflowed and scrolled
+     *    grows to `rows - 1`, and shrinking one back would make the next erase reach
+     *    above its own top: host output erased, every visible row printed twice.
+     */
+    maxCanvasRows: 200,
+};

package/dist/ui/scrollback/live-preview.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Streaming preview rows for the native-scroll live region
+ * (tui-native-terminal-scroll §4.6).
+ *
+ * Entries that are not yet final cannot be printed, but the user must still see the
+ * answer arrive. This builds a few PLAIN-TEXT rows from the unsettled tail of the
+ * transcript; the shell colours them uniformly (`theme.muted`). The preview is a
+ * visual buffer only: when an entry settles it is printed in its real, formatted
+ * shape and the preview rows disappear (the "settle jump", documented in the README).
+ *
+ * PURE: no Ink, no theme, no I/O. Every returned row fits `cols` display columns.
+ */
+import type { Entry } from '../../agent/reducer.js';
+export interface LivePreviewInput {
+    /** `entries.slice(settledCount)` — may include excluded entries; they are skipped. */
+    unsettled: readonly Entry[];
+    /** Content width (`cols - 1`). */
+    cols: number;
+    /** Rows granted by the budget. */
+    rows: number;
+    thinkingVisible: boolean;
+}
+/** The last `rows` preview rows, oldest first. `[]` when `rows <= 0`. */
+export declare function buildLivePreview(input: LivePreviewInput): string[];
+/** How many preview rows the unsettled entries would like, before budget clamping. */
+export declare function wantedPreviewRows(input: Omit<LivePreviewInput, 'rows'>, cap: number): number;

package/dist/ui/scrollback/live-preview.js

@@ -0,0 +1,106 @@
+/**
+ * Streaming preview rows for the native-scroll live region
+ * (tui-native-terminal-scroll §4.6).
+ *
+ * Entries that are not yet final cannot be printed, but the user must still see the
+ * answer arrive. This builds a few PLAIN-TEXT rows from the unsettled tail of the
+ * transcript; the shell colours them uniformly (`theme.muted`). The preview is a
+ * visual buffer only: when an entry settles it is printed in its real, formatted
+ * shape and the preview rows disappear (the "settle jump", documented in the README).
+ *
+ * PURE: no Ink, no theme, no I/O. Every returned row fits `cols` display columns.
+ */
+import { clampLiveText } from '../live-clamp.js';
+import { wrapToRows } from '../layout/wrap-rows.js';
+import { isExcluded } from './settled-boundary.js';
+import { clipLine } from './writer-shapes.js';
+const MAX_TEAM_RUN_ROWS = 3;
+const TOOL_LIVE_ROWS = 6;
+function firstLine(text) {
+    const line = text.split('\n').find((candidate) => candidate.trim().length > 0);
+    return (line ?? '').trim();
+}
+function fit(text, cols) {
+    return clipLine(text, Math.max(1, cols)).text;
+}
+function assistantRows(entry, cols, rows, thinkingVisible) {
+    const out = [];
+    const thinking = (entry.thinking ?? '').trim();
+    if (entry.text.trim().length === 0) {
+        if (thinking.length > 0 && thinkingVisible) {
+            const last = thinking.split('\n').filter((line) => line.trim().length > 0).pop() ?? '';
+            out.push(fit(`thinking: ${last.trim()}`, cols));
+        }
+        else if (entry.streaming) {
+            out.push('thinking...');
+        }
+        return out;
+    }
+    const clamped = clampLiveText(entry.text, rows * 2);
+    out.push(...wrapToRows(clamped.text, cols).map((row) => fit(row, cols)));
+    return out;
+}
+function toolRows(entry, cols) {
+    const head = entry.label && entry.label.length > 0 ? entry.label : entry.name;
+    const out = [fit(`${entry.status === 'running' ? '>' : '.'} ${head}`, cols)];
+    const live = (entry.live ?? []).slice(-TOOL_LIVE_ROWS);
+    for (const row of live)
+        out.push(fit(`  ${row}`, cols));
+    return out;
+}
+function teamRows(entry, cols) {
+    const running = entry.runs.filter((run) => !['queued', 'done', 'failed', 'aborted'].includes(run.phase)).length;
+    const out = [fit(`Team: ${running}/${entry.runs.length} running`, cols)];
+    for (const run of entry.runs.slice(0, MAX_TEAM_RUN_ROWS)) {
+        out.push(fit(`  ${run.label} ${run.phase}`, cols));
+    }
+    return out;
+}
+function entryRows(entry, input) {
+    const { cols, rows, thinkingVisible } = input;
+    switch (entry.kind) {
+        case 'assistant':
+            return assistantRows(entry, cols, rows, thinkingVisible);
+        case 'tool':
+            return toolRows(entry, cols);
+        case 'team':
+            return teamRows(entry, cols);
+        case 'todo':
+            return [fit(`Todo: ${entry.doneCount}/${entry.total}`, cols)];
+        case 'compaction':
+            return [fit(`Compacting context...`, cols)];
+        case 'retry':
+            return [fit(`Retrying (${entry.attempt}/${entry.maxRetries})...`, cols)];
+        case 'fast':
+            return [fit(`Fast review ${entry.reviewIndex}...`, cols)];
+        case 'queued':
+            return [fit(`Queued: ${firstLine(entry.text)}`, cols)];
+        case 'user':
+            return [fit(`> ${firstLine(entry.text)}`, cols)];
+        case 'notice':
+            return [fit(firstLine(entry.text), cols)];
+        case 'service':
+            return [];
+        default: {
+            const exhaustive = entry;
+            return exhaustive;
+        }
+    }
+}
+/** The last `rows` preview rows, oldest first. `[]` when `rows <= 0`. */
+export function buildLivePreview(input) {
+    const rows = Math.floor(input.rows);
+    if (rows <= 0)
+        return [];
+    const all = [];
+    for (const entry of input.unsettled) {
+        if (isExcluded(entry))
+            continue;
+        all.push(...entryRows(entry, input));
+    }
+    return all.slice(-rows);
+}
+/** How many preview rows the unsettled entries would like, before budget clamping. */
+export function wantedPreviewRows(input, cap) {
+    return buildLivePreview({ ...input, rows: cap }).length;
+}

package/dist/ui/scrollback/renderer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Offscreen entry renderer (tui-native-terminal-scroll §4.5 / D4).
+ *
+ * Settled entries are rendered ONCE, to ANSI text, by a resident Ink instance that
+ * writes to a fake stdout (`debug: true`: Ink then emits the complete layout in one
+ * write per render and never touches log-update). The resulting rows go to the feed
+ * and are printed; they are never mounted in the live React tree, so the per-frame
+ * render cost stays proportional to what is on screen, not to the session length.
+ *
+ * Failure isolation (I-S12): one entry that throws while rendering degrades to a
+ * single placeholder row. It must never block the queue or take the session down.
+ */
+import React from 'react';
+import type { Entry } from '../../agent/reducer.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { DensityMode } from '../density.js';
+import type { Theme } from '../theme.js';
+export interface EntryRenderOptions {
+    theme: Theme;
+    caps: TermCapabilities;
+    density: DensityMode;
+    thinkingVisible: boolean;
+    reducedMotion: boolean;
+}
+export interface EntryRenderer {
+    /** Rows for one entry at `cols` columns; `[]` when it renders as nothing. */
+    renderEntry(entry: Entry, prev: Entry | undefined, cols: number, expanded?: boolean): string[];
+    /** Rows for an arbitrary node (the startup header and opener). */
+    renderNode(node: React.ReactNode, cols: number): string[];
+    /** Options for LATER renders; already printed rows never change. */
+    setOptions(partial: Partial<EntryRenderOptions>): void;
+    stats(): {
+        elidedRows: number;
+        failures: number;
+    };
+    dispose(): void;
+}
+export declare function createEntryRenderer(initial: EntryRenderOptions): EntryRenderer;

package/dist/ui/scrollback/renderer.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Offscreen entry renderer (tui-native-terminal-scroll §4.5 / D4).
+ *
+ * Settled entries are rendered ONCE, to ANSI text, by a resident Ink instance that
+ * writes to a fake stdout (`debug: true`: Ink then emits the complete layout in one
+ * write per render and never touches log-update). The resulting rows go to the feed
+ * and are printed; they are never mounted in the live React tree, so the per-frame
+ * render cost stays proportional to what is on screen, not to the session length.
+ *
+ * Failure isolation (I-S12): one entry that throws while rendering degrades to a
+ * single placeholder row. It must never block the queue or take the session down.
+ */
+import React from 'react';
+import { EventEmitter } from 'node:events';
+import { Box, render } from 'ink';
+import { EntryView } from '../Transcript.js';
+import { getLogger } from '../../logging/logger.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+/**
+ * Catches a throwing entry INSIDE the offscreen tree.
+ *
+ * Without it Ink's own boundary would print an error overview into the frame (which
+ * would then be printed into the user's scrollback, forever) and unmount the
+ * instance, so every later entry would fail too. With it the failure is a flag the
+ * caller reads synchronously and the instance stays healthy (I-S12).
+ */
+class RenderGuard extends React.Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        this.props.failure.error = error;
+    }
+    render() {
+        return this.state.failed ? null : this.props.children;
+    }
+}
+const NO_FAILURE = Symbol('no-failure');
+function createOffscreen(cols) {
+    const last = { value: null };
+    const stdout = Object.assign(new EventEmitter(), {
+        columns: cols,
+        rows: 1000,
+        isTTY: false,
+        write(chunk) {
+            last.value = chunk;
+            return true;
+        },
+    });
+    const stdin = Object.assign(new EventEmitter(), {
+        isTTY: false,
+        setEncoding() { },
+        resume() { },
+        pause() { },
+        ref() { },
+        unref() { },
+    });
+    const instance = render(null, {
+        stdout, stdin, stderr: stdout, debug: true, exitOnCtrlC: false, patchConsole: false,
+    });
+    // A rejected exit promise nobody awaits is an unhandled rejection.
+    void instance.waitUntilExit().catch(() => undefined);
+    return { cols, stdout, stdin, instance, last, failure: { error: NO_FAILURE } };
+}
+/** A function, so the compiler does not narrow the mutable `last` box to `null`. */
+function readFrame(target) {
+    return target.last.value;
+}
+function trimTrailingBlank(rows) {
+    let end = rows.length;
+    while (end > 0 && rows[end - 1].trim().length === 0)
+        end -= 1;
+    return end === rows.length ? rows : rows.slice(0, end);
+}
+export function createEntryRenderer(initial) {
+    let options = initial;
+    let offscreen = null;
+    let elidedRows = 0;
+    let failures = 0;
+    let guardKey = 0;
+    const dispose = () => {
+        if (!offscreen)
+            return;
+        const current = offscreen;
+        offscreen = null;
+        try {
+            current.instance.unmount();
+            current.instance.cleanup();
+        }
+        catch {
+            // Tearing down a fake stream must never throw into an exit path.
+        }
+    };
+    /** Ink reads `columns` once, at creation, so a width change rebuilds the instance. */
+    const ensure = (cols) => {
+        if (offscreen && offscreen.cols === cols)
+            return offscreen;
+        dispose();
+        offscreen = createOffscreen(cols);
+        return offscreen;
+    };
+    const capRows = (rows) => {
+        const cap = SCROLLBACK_LIMITS.maxRowsPerEntry;
+        if (rows.length <= cap)
+            return rows;
+        const hidden = rows.length - (cap - 1);
+        elidedRows += hidden;
+        return [...rows.slice(0, cap - 1), `[+${hidden} rows not printed - scrollback entry cap]`];
+    };
+    const renderNode = (node, cols) => {
+        const target = ensure(Math.max(1, Math.floor(cols)));
+        target.last.value = null;
+        target.failure.error = NO_FAILURE;
+        guardKey += 1;
+        target.instance.rerender(_jsx(Box, { flexDirection: "column", width: target.cols, children: _jsx(RenderGuard, { failure: target.failure, children: node }, guardKey) }));
+        const frame = readFrame(target);
+        const failure = target.failure.error;
+        target.instance.rerender(null);
+        if (failure !== NO_FAILURE)
+            throw failure;
+        if (frame === null)
+            throw new Error('offscreen Ink instance produced no frame');
+        return capRows(trimTrailingBlank(frame.split('\n')));
+    };
+    const failureRow = (label) => {
+        failures += 1;
+        return [`[aragon] ${label} could not be rendered`];
+    };
+    return {
+        renderEntry(entry, prev, cols, expanded = false) {
+            try {
+                return renderNode(_jsx(EntryView, { entry: entry, prev: prev, expanded: expanded, thinkingVisible: options.thinkingVisible, reducedMotion: options.reducedMotion, density: options.density, theme: options.theme, caps: options.caps }), cols);
+            }
+            catch (error) {
+                getLogger().warn('cli', 'entry_render_failed', {
+                    id: entry.id, kind: entry.kind, error: String(error),
+                });
+                return failureRow(`entry ${entry.id} (${entry.kind})`);
+            }
+        },
+        renderNode(node, cols) {
+            try {
+                return renderNode(node, cols);
+            }
+            catch (error) {
+                getLogger().warn('cli', 'node_render_failed', { error: String(error) });
+                return failureRow('startup banner');
+            }
+        },
+        setOptions(partial) {
+            options = { ...options, ...partial };
+        },
+        stats: () => ({ elidedRows, failures }),
+        dispose,
+    };
+}