@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/ui/scrollback/writer-shapes.js

@@ -0,0 +1,159 @@
+/**
+ * Byte shapes of the native-scroll writer (tui-native-terminal-scroll §4.3 /
+ * Appendix A). Stateless string assembly only — the state machine that decides
+ * WHICH shape to emit lives in `scrollback-writer.ts`.
+ *
+ * THE WHITELIST (I-S5 / I-S6). Every byte produced here is drawn from: SGR, CUU,
+ * CUD, CR, CRLF, ED0, EL0, DEC 2026 and DECTCEM. There is no absolute CUP, no
+ * scroll region, no `CSI S/T`, no `ED2/ED3`. Relative addressing is what makes the
+ * geometry independent of the terminal scrolling underneath it (spec appendix B).
+ *
+ * Each row is `SGR0 · text · SGR0`: the leading reset stops one row's style leaking
+ * into the next, and the trailing one stops a background-colour-erase terminal from
+ * painting the following ED0/EL0 in the row's last colour.
+ */
+import stringWidth from 'string-width';
+import stripAnsi from 'strip-ansi';
+const CSI = '\x1b[';
+export const SGR0 = `${CSI}0m`;
+const ED0 = `${CSI}J`;
+const EL0 = `${CSI}K`;
+const SYNC_BEGIN = `${CSI}?2026h`;
+const SYNC_END = `${CSI}?2026l`;
+const SHOW_CURSOR = `${CSI}?25h`;
+const OSC8_CLOSE = '\x1b]8;;\x07';
+const up = (n) => (n > 0 ? `${CSI}${n}A` : '');
+const down = (n) => (n > 0 ? `${CSI}${n}B` : '');
+const row = (text) => SGR0 + text + SGR0 + '\r\n';
+const rows = (list) => list.map(row).join('');
+const wrapSync = (payload, sync) => sync ? SYNC_BEGIN + payload + SYNC_END : payload;
+/** First write of a session: the cursor is already on a fresh line at column 0. */
+export function seedBytes(input) {
+    const lead = input.reseed ? '\r\n' : '';
+    return wrapSync(lead + '\r' + SGR0 + rows(input.statics) + rows(input.lines), input.sync);
+}
+/**
+ * CUD(n): move down n rows WITHOUT writing a single cell.
+ *
+ * This is how the canvas spends its `gap` (D3). A blank row that is never written
+ * cannot be pushed into the scrollback by a later overflow, which is the whole
+ * reason the gap is not a run of `\r\n` (I-B3). The sequence is already whitelisted
+ * (`diffBytes` uses it to step between changed rows); this is the same CUD used to
+ * skip empty space instead.
+ */
+export function skipRows(rows) {
+    return down(Math.max(0, Math.floor(Number.isFinite(rows) ? rows : 0)));
+}
+/**
+ * First canvas batch (or the first one after a reset): the screen below the cursor
+ * is assumed empty, so there is nothing to erase — only `[gap][content][region]` to
+ * write, ending with the cursor parked on the last row.
+ */
+export function canvasSeedBytes(input) {
+    const lead = input.reseed ? '\r\n' : '';
+    const skip = skipRows(input.downToTop) + skipRows(input.gap);
+    return wrapSync(lead + '\r' + SGR0 + skip + rows(input.held) + rows(input.lines), input.sync);
+}
+/**
+ * Redraw the whole canvas: erase the previous one, then write `[gap][content][region]`.
+ *
+ * ORDER IS SEMANTICS: `ED0`, then the gap, then the content, then the region. Moving
+ * the gap after the content puts the blank space back between the reply and the
+ * composer, which is the exact defect this feature fixes (M1 in the spec).
+ *
+ * `held` is the FULL content sequence, not the part that will still be on screen: the
+ * rows that do not fit are supposed to leave through the bottom, and the terminal can
+ * only scroll away what it was given.
+ */
+export function canvasBytes(input) {
+    return wrapSync(up(input.eraseUp) + '\r' + SGR0 + ED0 + skipRows(input.gap) +
+        rows(input.held) + rows(input.lines), input.sync);
+}
+/** Erase exactly the previous live region, print static rows, redraw the region. */
+export function fullBytes(input) {
+    return wrapSync(up(input.eraseUp) + '\r' + SGR0 + ED0 + rows(input.statics) + rows(input.lines), input.sync);
+}
+/**
+ * Fill the screen down to the LAST row before the first batch (D4 rung 2 / §4.3).
+ *
+ * This is the fallback for a terminal that never answers `ESC[6n`: from any row, a
+ * run of `rows - 1` line feeds is guaranteed to leave the cursor on the bottom row
+ * (extra feeds only scroll, which is why the count is the caller's business). It is
+ * written ONCE, before anything else, so the rows it scrolls away are the host's old
+ * output — which is still in the scrollback — and never this session's content.
+ *
+ * The argument is the NUMBER OF LINE FEEDS, not the terminal height: `cli.tsx` passes
+ * `rows - 1`. Naming it after the height instead made the caller subtract twice and
+ * left the cursor one row short of the bottom.
+ */
+export function fillBytes(count) {
+    return '\r\n'.repeat(Math.max(0, Math.floor(count)));
+}
+/** Same height, no static rows: rewrite only the rows that changed. `''` if none did. */
+export function diffBytes(input) {
+    const { lines, prev } = input;
+    const height = lines.length;
+    let out = '';
+    let cursor = -1;
+    for (let i = 0; i < height; i += 1) {
+        if (lines[i] === prev[i])
+            continue;
+        // Paint, THEN clear the tail: never ESC[2K first, which would blank the row
+        // the user is looking at for the instant between the two writes.
+        out += (cursor < 0 ? up(height - i) : down(i - cursor)) + '\r' + SGR0 + lines[i] + SGR0 + EL0;
+        cursor = i;
+    }
+    if (cursor < 0)
+        return '';
+    // Park on the row below the region, column 0 (I-S4).
+    return wrapSync(out + down(height - cursor) + '\r', input.sync);
+}
+/**
+ * Exit: erase the live region, flush leftover static rows, print the summary.
+ * `eraseUp < 0` means the geometry is unknown (a foreign write intervened), in
+ * which case the only safe move is to start on a fresh line and erase nothing.
+ */
+export function finalizeBytes(input) {
+    const head = input.eraseUp < 0 ? '\r\n' : up(input.eraseUp) + '\r' + SGR0 + ED0;
+    return head + rows(input.statics) + rows(input.summary) + SHOW_CURSOR;
+}
+const ESCAPE = /(\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\))/;
+const segmenter = typeof Intl !== 'undefined' && 'Segmenter' in Intl
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : null;
+function graphemes(text) {
+    return segmenter ? Array.from(segmenter.segment(text), (part) => part.segment) : Array.from(text);
+}
+/**
+ * Cut a row to `maxCols` DISPLAY columns (I-S13), keeping SGR / OSC 8 intact.
+ *
+ * Returns the input unchanged (same reference) when it already fits, which is the
+ * overwhelmingly common case. Width is measured the way Ink measures it
+ * (`string-width` over the ANSI-stripped text): that is the number Ink used to
+ * wrap, so a disagreement with the terminal is the only way a row can exceed it.
+ */
+export function clipLine(line, maxCols) {
+    if (maxCols < 1)
+        return { text: '', clipped: line.length > 0 };
+    if (stringWidth(stripAnsi(line)) <= maxCols)
+        return { text: line, clipped: false };
+    let out = '';
+    let width = 0;
+    let linkOpen = false;
+    for (const part of line.split(ESCAPE)) {
+        if (part.startsWith('\x1b')) {
+            out += part;
+            if (part.startsWith('\x1b]8;'))
+                linkOpen = !/^\x1b\]8;[^;]*;(?:\x07|\x1b\\)$/.test(part);
+            continue;
+        }
+        for (const glyph of graphemes(part)) {
+            const glyphWidth = stringWidth(glyph);
+            if (width + glyphWidth > maxCols)
+                return { text: out + SGR0 + (linkOpen ? OSC8_CLOSE : ''), clipped: true };
+            out += glyph;
+            width += glyphWidth;
+        }
+    }
+    return { text: out, clipped: false };
+}

package/dist/ui/stdout-frame-writer.js

@@ -97,7 +97,14 @@ export function wrapStdoutForFrames(stdout, differ) {
         }
         return writeReal(out, encoding, cb);
     };
-    const onResize = () => differ.invalidate();
+    // Optional differ hooks keep the full-screen path byte-identical: a differ that
+    // does not implement them is invalidated exactly as before.
+    const onResize = () => {
+        if (differ.onResize)
+            differ.onResize();
+        else
+            differ.invalidate();
+    };
     stdout.on('resize', onResize);
     let disposed = false;
     const proxy = new Proxy(stdout, {
@@ -130,7 +137,10 @@ export function wrapStdoutForFrames(stdout, differ) {
             return true;
         },
         writeForeign(text) {
-            differ.invalidate();
+            if (differ.cursorNeutralWrite)
+                differ.cursorNeutralWrite();
+            else
+                differ.invalidate();
             if (disposed || text.length === 0)
                 return;
             writeReal(text);

package/dist/ui/terminal-plan.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Terminal plan — the ONE decision point for how the interactive TUI occupies the
+ * terminal (tui-native-terminal-scroll §4.1 / D10).
+ *
+ * `cli.tsx::runInteractive` used to derive `wantMouse`, `mouseOn`, `wantSelect`,
+ * `pasteOn` and `enhancedKeysOn` inline, each with its own comment about why the
+ * others must agree. Adding a second screen mode multiplies that surface, so the
+ * agreement is computed here, once, and the call site only READS the result.
+ *
+ * PURE: no I/O, no `process` access, so every row of the rules below is a table
+ * test with plain literals.
+ *
+ * I-S9 · `app` reproduces the pre-feature expressions term for term. The
+ * regression test diffs this function against a verbatim copy of those
+ * expressions, because "the same by inspection" is how mouse and paste drifted
+ * apart the last time.
+ */
+import type { ScrollMode } from '../config/schema.js';
+export type { ScrollMode } from '../config/schema.js';
+export interface TerminalPlanInput {
+    /** The resolved `scrollMode` config value. */
+    scrollMode: ScrollMode;
+    configMouse: boolean;
+    configMouseSelect: boolean;
+    configPaste: boolean;
+    configKeyboardEnhancement: boolean;
+    configDiffRender: boolean;
+    stdinIsTTY: boolean;
+    stdoutIsTTY: boolean;
+    platform: NodeJS.Platform;
+    /** Measured on win32 (`forceVtInputForThisConsole`); irrelevant elsewhere. */
+    vtInputSupported: boolean;
+}
+export interface TerminalPlan {
+    scrollMode: ScrollMode;
+    /** `app`: enter the alternate screen. `native`: never. */
+    altScreen: boolean;
+    /** Whether the terminal is asked for SGR mouse reports (and a mouse filter is wanted). */
+    mouseReporting: boolean;
+    /** Application-drawn drag selection. Always `false` in native mode (the terminal selects). */
+    dragSelect: boolean;
+    bracketedPaste: boolean;
+    enhancedKeys: boolean;
+    /**
+     * Which frame writer fronts Ink's stdout. `native` ALWAYS needs the scrollback
+     * writer, even with `diffRender` off: static rows are injected through it.
+     */
+    differ: 'fullscreen' | 'scrollback' | 'none';
+    /** Native + `diffRender:false` — every frame rewrites the whole live region. */
+    fullEveryFrame: boolean;
+}
+export declare function resolveTerminalPlan(input: TerminalPlanInput): TerminalPlan;

package/dist/ui/terminal-plan.js

@@ -0,0 +1,49 @@
+/**
+ * Terminal plan — the ONE decision point for how the interactive TUI occupies the
+ * terminal (tui-native-terminal-scroll §4.1 / D10).
+ *
+ * `cli.tsx::runInteractive` used to derive `wantMouse`, `mouseOn`, `wantSelect`,
+ * `pasteOn` and `enhancedKeysOn` inline, each with its own comment about why the
+ * others must agree. Adding a second screen mode multiplies that surface, so the
+ * agreement is computed here, once, and the call site only READS the result.
+ *
+ * PURE: no I/O, no `process` access, so every row of the rules below is a table
+ * test with plain literals.
+ *
+ * I-S9 · `app` reproduces the pre-feature expressions term for term. The
+ * regression test diffs this function against a verbatim copy of those
+ * expressions, because "the same by inspection" is how mouse and paste drifted
+ * apart the last time.
+ */
+export function resolveTerminalPlan(input) {
+    const bothTty = input.stdinIsTTY && input.stdoutIsTTY;
+    // Paste and keyboard enhancement ride the stdin filter and say nothing about
+    // scrolling, so the two modes agree on them (rule 3).
+    const bracketedPaste = input.configPaste && input.stdinIsTTY;
+    const enhancedKeys = input.configKeyboardEnhancement &&
+        input.stdinIsTTY &&
+        (input.platform !== 'win32' || input.vtInputSupported);
+    if (input.scrollMode === 'native') {
+        return {
+            scrollMode: 'native',
+            altScreen: false,
+            mouseReporting: false,
+            dragSelect: false,
+            bracketedPaste,
+            enhancedKeys,
+            differ: 'scrollback',
+            fullEveryFrame: !input.configDiffRender,
+        };
+    }
+    const mouseReporting = input.configMouse && bothTty && input.vtInputSupported;
+    return {
+        scrollMode: 'app',
+        altScreen: true,
+        mouseReporting,
+        dragSelect: mouseReporting && input.configMouseSelect,
+        bracketedPaste,
+        enhancedKeys,
+        differ: input.configDiffRender ? 'fullscreen' : 'none',
+        fullEveryFrame: false,
+    };
+}

package/dist/ui/transcript-text.d.ts

@@ -26,5 +26,16 @@ export interface TranscriptTextOptions {
      */
     droppedEntries?: number;
 }
+/**
+ * The three figures every session summary carries: turns, tokens, cost.
+ *
+ * One implementation for the exit replay and the native-scroll exit summary
+ * (tui-native-terminal-scroll §4.8), so the two can never disagree.
+ */
+export declare function formatSessionStats(entries: readonly Entry[], usageTotal: UsageTotal, g: Pick<Glyphs, 'arrowUp' | 'arrowDown'>): {
+    turns: string;
+    tokens: string;
+    cost: string;
+};
 /** Render the whole session (summary line + entries) as plain text. */
 export declare function renderTranscriptText(entries: Entry[], opts: TranscriptTextOptions): string;

package/dist/ui/transcript-text.js

@@ -198,21 +198,35 @@ function renderEntry(entry, glyphs) {
             return [];
     }
 }
-/** Render the whole session (summary line + entries) as plain text. */
-export function renderTranscriptText(entries, opts) {
+/**
+ * The three figures every session summary carries: turns, tokens, cost.
+ *
+ * One implementation for the exit replay and the native-scroll exit summary
+ * (tui-native-terminal-scroll §4.8), so the two can never disagree.
+ */
+export function formatSessionStats(entries, usageTotal, g) {
     const turns = entries.filter((e) => e.kind === 'user').length;
-    const g = opts.glyphs;
     // THE SAME PROMPT-SIDE TOTAL THE STATUS BAR SHOWS (context-usage-gauge-accuracy
     // §3.6). This line is what a user compares against the bar they were watching a
     // second earlier, so a different unit here would look like the exit summary
     // losing tokens.
-    const tokens = `${formatTokens(promptTokensOf(opts.usageTotal))}${g.arrowUp} ${formatTokens(opts.usageTotal.outputTokens)}${g.arrowDown}`;
+    const tokens = `${formatTokens(promptTokensOf(usageTotal))}${g.arrowUp} ${formatTokens(usageTotal.outputTokens)}${g.arrowDown}`;
+    return {
+        turns: `${turns} ${turns === 1 ? 'turn' : 'turns'}`,
+        tokens,
+        cost: formatCost(usageTotal.costUsd),
+    };
+}
+/** Render the whole session (summary line + entries) as plain text. */
+export function renderTranscriptText(entries, opts) {
+    const g = opts.glyphs;
+    const stats = formatSessionStats(entries, opts.usageTotal, g);
     const summary = [
         'aragon',
         `${opts.provider}:${opts.model}`,
-        `${turns} ${turns === 1 ? 'turn' : 'turns'}`,
-        tokens,
-        formatCost(opts.usageTotal.costUsd),
+        stats.turns,
+        stats.tokens,
+        stats.cost,
         formatDuration(Math.max(0, opts.elapsedMs)),
     ].join(` ${g.midDot} `);
     const max = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;

package/dist/ui/use-startup-notices.d.ts

@@ -53,6 +53,17 @@ export interface RetainNoticeOptions {
     requested: number;
     resolved: number;
 }
+/**
+ * The revision of the native-scroll notice a user must have seen for it to stay
+ * quiet (`state.json::scrollModeNoticeVersion`). BUMP IT WHENEVER THE ADVICE
+ * CHANGES, never for a rewording (tui-native-terminal-scroll D12).
+ */
+export declare const SCROLL_MODE_NOTICE_VERSION = 1;
+export declare function scrollModeNoticeText(): string;
+export interface ScrollModeNoticeOptions {
+    /** Record that `SCROLL_MODE_NOTICE_VERSION` was shown (`state.json`). */
+    onSeen: () => void;
+}
 export interface MouseNoticeOptions {
     /**
      * Whether reporting is ACTUALLY in effect: a filter was installed AND the
@@ -98,4 +109,4 @@ export interface VtInputNoticeOptions {
      */
     onSeen: () => void;
 }
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions, vtInputNotice?: VtInputNoticeOptions): void;
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions, vtInputNotice?: VtInputNoticeOptions, scrollModeNotice?: ScrollModeNoticeOptions): void;

package/dist/ui/use-startup-notices.js

@@ -14,7 +14,7 @@
 import { useEffect, useRef } from 'react';
 import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
 import { readConfigFile } from '../config/store.js';
-import { getMouseNoticeVersion, getVtInputNoticeVersion } from '../config/ui-state.js';
+import { getMouseNoticeVersion, getScrollModeNoticeVersion, getVtInputNoticeVersion, } from '../config/ui-state.js';
 import { getLogger } from '../logging/logger.js';
 /**
  * The revision of the mouse notice a user must have seen for it to stay quiet
@@ -93,7 +93,17 @@ export function vtInputDeadNotice(nodeVersion) {
         `as a PLAIN TAB - ${cost}${toggle}, and Shift+Up / Shift+Down to scroll. ` +
         'Node 22.17.0+ (or 24.2.0+) restores both.');
 }
-export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNotice) {
+/**
+ * The revision of the native-scroll notice a user must have seen for it to stay
+ * quiet (`state.json::scrollModeNoticeVersion`). BUMP IT WHENEVER THE ADVICE
+ * CHANGES, never for a rewording (tui-native-terminal-scroll D12).
+ */
+export const SCROLL_MODE_NOTICE_VERSION = 1;
+export function scrollModeNoticeText() {
+    return ('Scrolling now uses your terminal: wheel, scrollbar, selection and search all work as ' +
+        'usual. Prefer the old full-screen view? Run: aragon config set scrollMode app');
+}
+export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNotice, scrollModeNotice) {
     // The sink gives up after repeated write failures (a read-only log directory,
     // a full disk). Silently logging nothing is exactly the state a user must not
     // discover later, from an empty file, while trying to explain a bug.
@@ -167,6 +177,22 @@ export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNo
         });
         vtNoticeRef.current?.onSeen();
     }, [vtNodeVersion, dispatch]);
+    // The one-shot native-scroll notice (D12): a default-behaviour change has to be
+    // discoverable and reversible. `>=`, like the notices above: a state file written
+    // by a newer build has already told this user.
+    const scrollNoticeRef = useRef(scrollModeNotice);
+    scrollNoticeRef.current = scrollModeNotice;
+    const scrollNoticeWanted = scrollModeNotice !== undefined;
+    const scrollNoticeShown = useRef(false);
+    useEffect(() => {
+        if (!scrollNoticeWanted || scrollNoticeShown.current)
+            return;
+        if (getScrollModeNoticeVersion() >= SCROLL_MODE_NOTICE_VERSION)
+            return;
+        scrollNoticeShown.current = true;
+        dispatch({ type: 'notice', level: 'info', text: scrollModeNoticeText() });
+        scrollNoticeRef.current?.onSeen();
+    }, [scrollNoticeWanted, dispatch]);
     // A `warn` notice rather than a toast: it is about a value the user typed, so
     // it belongs in the transcript where it can be scrolled back to, not in a row
     // that expires. DEPENDS ON THE TWO SCALARS, never on the options object —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.29",
+  "version": "0.6.32",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.41",
+    "@aragon-agent/core": "^0.2.44",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",
@@ -76,6 +76,6 @@
     "@types/react": "^18.3.0",
     "ink-testing-library": "^4.0.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "vitest": "4.1.9"
   }
 }