@aragon-agent/cli 0.5.6 → 0.5.8

package/dist/ui/layout/virtual-window.js

@@ -0,0 +1,204 @@
+/**
+ * Viewport virtualisation maths (tui-render-performance L3 / R1). Pure,
+ * React-free, unit-tested.
+ *
+ * THE STRUCTURAL FIX. Ink's `renderNodeToOutput` has no early-out for clipped
+ * subtrees: for every `ink-text` node it runs `squashTextNodes`, `widestLine`
+ * and possibly `wrapText` — all O(chars) — and `Output.get()` then evaluates
+ * `widestLine` a SECOND time before it is allowed to skip an out-of-clip
+ * operation. A clipped 50 000-character entry therefore costs two full string
+ * scans per frame and buys nothing. Bounding the ENTRY COUNT (`transcriptWindow`)
+ * never bounded that, because one entry can be fifty thousand lines.
+ *
+ * So entries outside the visible band are not mounted at all. They are replaced
+ * by two spacer boxes whose heights come from a height cache, which makes the
+ * per-frame cost O(visible rows) instead of O(characters ever produced).
+ *
+ * V-4 — `offset` counts rows FROM THE BOTTOM (`layout/scroll.ts:1-13`), and that
+ * is what makes virtualisation safe here for free: a height correction on an
+ * entry ABOVE the viewport changes the content height and therefore
+ * `overflowLines`, while `offset` — and hence what the user is looking at — is
+ * unchanged. No scroll-anchoring compensation pass is required. Do NOT
+ * "simplify" `offset` to count from the top.
+ */
+import { GUTTER_WIDTH } from './Gutter.js';
+export const VIRTUAL_LIMITS = {
+    /**
+     * Entries kept mounted on each side of the visible band.
+     *
+     * V-2 — must stay `>= 2`, so a one-row scroll can never expose an entry whose
+     * height has never been measured at the very edge of the viewport.
+     */
+    overscan: 2,
+    /** Height-cache ceiling (LRU). Four thousand numbers, not four thousand strings. */
+    heightEntries: 4096,
+};
+/**
+ * A cheap content version: it changes exactly when the rendered content does.
+ *
+ * DERIVED, NEVER HASHED. Hashing a 256 KiB string once per entry per frame would
+ * recreate the very cost this module exists to remove, so every field below is
+ * an O(1) read of a length or a scalar.
+ *
+ * I-L3-1 — this must change whenever the rendered output changes. The only lossy
+ * case is a same-LENGTH text replacement, which the reducer cannot produce: all
+ * text fields are append-only (`appendBounded` only ever elides the middle,
+ * which changes the length). A future NON-APPEND mutation MUST extend the
+ * revision, or the entry freezes at a stale height AND a stale rendered subtree
+ * with nothing anywhere reporting it. `virtual-window.test.ts` enumerates every
+ * kind against every mutating action.
+ */
+export function entryRevision(entry) {
+    switch (entry.kind) {
+        case 'user':
+            return 'u';
+        case 'notice':
+            return 'n';
+        case 'assistant':
+            return `a${entry.text.length}.${entry.thinking?.length ?? 0}.${entry.streaming ? 1 : 0}.${entry.aborted ? 1 : 0}`;
+        case 'tool':
+            return `t${entry.status}.${entry.argsRaw.length}.${entry.preview?.length ?? 0}.${entry.durationMs ?? -1}`;
+        case 'team':
+            return `m${entry.active ? 1 : 0}.${entry.runs.length}.${entry.runs
+                .map((r) => r.phase[0])
+                .join('')}.${entry.runs.reduce((acc, r) => acc + r.toolCalls, 0)}`;
+        case 'todo':
+            return `d${entry.live ? 1 : 0}.${entry.doneCount}.${entry.total}.${entry.items.length}`;
+        default:
+            return 'x';
+    }
+}
+/**
+ * The height-cache key.
+ *
+ * V-5 — `cols` is part of the key, so a resize invalidates every entry. The
+ * frame after a resize renders from estimates and re-measures lazily: one
+ * reflow, no crash, no stale layout.
+ *
+ * `flags` carries the render-affecting switches that are neither per-entry nor
+ * part of `density` — today only `thinkingVisible` (Ctrl+T). It is a parameter
+ * rather than a fifth positional scalar so a future switch costs one character
+ * at the call site instead of a signature change at four.
+ */
+export function heightKey(entry, cols, expanded, density, flags = '') {
+    return `${entry.id}|${entryRevision(entry)}|${cols}|${expanded ? 1 : 0}|${density}|${flags}`;
+}
+/** Rows a string occupies at `usable` columns, wrapping included. At least 1. */
+function wrappedRows(text, usable) {
+    const width = Math.max(1, usable);
+    let rows = 0;
+    let lineLen = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            rows += Math.max(1, Math.ceil(lineLen / width));
+            lineLen = 0;
+        }
+        else {
+            lineLen += 1;
+        }
+    }
+    return rows + Math.max(1, Math.ceil(lineLen / width));
+}
+/** Collapsed preview rows in `ToolCard`; duplicated as a NUMBER, not imported. */
+const TOOL_COLLAPSED_LINES = 8;
+/**
+ * Pure UPPER-BOUND estimate of an entry's height, used until a real measurement
+ * exists.
+ *
+ * Upper bound rather than best guess, and deliberately so: an over-estimate
+ * makes the scroll position slightly conservative and self-corrects the frame
+ * after the entry is measured, while an under-estimate can put the newest output
+ * off the bottom of a viewport the user believes is pinned.
+ */
+export function estimateEntryRows(entry, cols, density, expanded) {
+    const usable = Math.max(1, cols - GUTTER_WIDTH);
+    // `separationRows` needs the PRECEDING entry, which a per-entry estimate does
+    // not have. One row is its maximum, so charging it unconditionally keeps this
+    // an upper bound (`compact` never spends it at all).
+    const separation = density === 'comfortable' ? 1 : 0;
+    switch (entry.kind) {
+        case 'user':
+            return separation + wrappedRows(entry.text, usable);
+        case 'notice':
+            return separation + wrappedRows(entry.text, usable);
+        case 'assistant': {
+            const thinking = entry.thinking ? 1 + wrappedRows(entry.thinking, usable) : 0;
+            const body = entry.text.length > 0 ? wrappedRows(entry.text, usable) : 1;
+            return separation + thinking + body + (entry.aborted ? 1 : 0);
+        }
+        case 'tool': {
+            if (!entry.preview || (entry.status !== 'done' && entry.status !== 'error')) {
+                return separation + 1;
+            }
+            const lines = wrappedRows(entry.preview, usable);
+            const shown = expanded ? lines : Math.min(lines, TOOL_COLLAPSED_LINES);
+            // header + body + the `+N lines (Ctrl+O)` / `(Ctrl+O to collapse)` footer
+            return separation + 1 + shown + 1;
+        }
+        case 'team':
+            return separation + 1 + entry.runs.length + (expanded ? entry.runs.length * 3 + 1 : 1);
+        case 'todo':
+            return separation + 1 + entry.items.length;
+        default:
+            return separation + 1;
+    }
+}
+/** Choose which entries to mount, and how tall the two spacers must be. */
+export function selectWindow(input) {
+    const { entries, heightOf } = input;
+    const n = entries.length;
+    if (n === 0) {
+        return { startIndex: 0, endIndex: 0, leadingRows: 0, trailingRows: 0, totalRows: 0 };
+    }
+    const heights = new Array(n);
+    let totalRows = 0;
+    for (let i = 0; i < n; i += 1) {
+        const h = heightOf(i);
+        const rows = Number.isFinite(h) && h > 0 ? Math.floor(h) : 1;
+        heights[i] = rows;
+        totalRows += rows;
+    }
+    // A viewport of 0 is the FIRST FRAME, before `measureElement` has run. Falling
+    // back to 1 keeps the live tail mounted through it, so the first paint is real
+    // content rather than a blank rectangle that only fills in on the second.
+    const viewport = Math.max(1, Math.floor(input.viewportRows) || 0);
+    const offset = Math.max(0, Math.floor(input.offset) || 0);
+    const overscan = Math.max(VIRTUAL_LIMITS.overscan, Math.floor(input.overscan) || 0);
+    const bottom = totalRows - offset;
+    const top = bottom - viewport;
+    let start = n - 1;
+    let acc = 0;
+    for (let i = 0; i < n; i += 1) {
+        const next = acc + heights[i];
+        if (next > top) {
+            start = i;
+            break;
+        }
+        acc = next;
+    }
+    let end = n;
+    acc = 0;
+    for (let i = 0; i < n; i += 1) {
+        if (acc >= bottom) {
+            end = i;
+            break;
+        }
+        acc += heights[i];
+    }
+    start = Math.max(0, start - overscan);
+    end = Math.min(n, end + overscan);
+    // V-3 — while pinned, the LAST entry is always inside the window, whatever its
+    // height. The live tail must be real content and never a spacer, or a
+    // streaming answer renders as a growing blank rectangle.
+    if (offset <= 0)
+        end = n;
+    if (end <= start)
+        end = Math.min(n, start + 1);
+    let leadingRows = 0;
+    for (let i = 0; i < start; i += 1)
+        leadingRows += heights[i];
+    let trailingRows = 0;
+    for (let i = end; i < n; i += 1)
+        trailingRows += heights[i];
+    return { startIndex: start, endIndex: end, leadingRows, trailingRows, totalRows };
+}

package/dist/ui/live-clamp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Live-region clamp for INLINE render mode (tui-render-performance L5 / R6).
+ *
+ * Inline mode has no fixed frame, so nothing kept its live (non-`<Static>`)
+ * region shorter than the terminal. When one live entry grew taller than
+ * `stdout.rows`, Ink took the branch at `ink.js:118-123`:
+ *
+ *     if (outputHeight >= this.options.stdout.rows) {
+ *       stdout.write(clearTerminal + this.fullStaticOutput + output);
+ *     }
+ *
+ * `fullStaticOutput` accumulates EVERY `<Static>` frame of the whole session and
+ * is never trimmed, so once that branch is taken it is taken on every subsequent
+ * frame — bypassing both the `output !== lastOutput` dedupe and `throttledLog` —
+ * and the terminal receives the entire session history thirty times a second.
+ * That is a genuine hard freeze, and it is reachable today by any inline user
+ * (`--no-fullscreen`, `TERM=dumb`, CI, a short or narrow terminal) whose model
+ * writes a long answer.
+ *
+ * I-L5-1 — keeping the live region strictly below `stdout.rows` makes that
+ * branch UNREACHABLE, which is the inline analogue of `frame.ts`'s
+ * `frameHeight(r) < r` and deserves the same standing. We cannot bound Ink's
+ * `fullStaticOutput` growth (it is private and append-only); preventing the
+ * branch that WRITES it is the entire mitigation, and nothing about the memory
+ * it holds is fixed by this module.
+ *
+ * Nothing is lost, only deferred: when the entry settles it moves into
+ * `<Static>` and is printed in full.
+ */
+export interface LiveClamp {
+    text: string;
+    /** Rows dropped off the FRONT. `0` means the text was returned untouched. */
+    hiddenRows: number;
+}
+/**
+ * Keep the LAST `maxRows` rows of `text`; report how many were dropped.
+ *
+ * Rows, not wrapped display lines: this runs per frame on a streaming entry, and
+ * a wrap-aware count would need the column width and a second full scan of a
+ * string this function exists to avoid scanning twice.
+ */
+export declare function clampLiveText(text: string, maxRows: number): LiveClamp;

package/dist/ui/live-clamp.js

@@ -0,0 +1,74 @@
+/**
+ * Live-region clamp for INLINE render mode (tui-render-performance L5 / R6).
+ *
+ * Inline mode has no fixed frame, so nothing kept its live (non-`<Static>`)
+ * region shorter than the terminal. When one live entry grew taller than
+ * `stdout.rows`, Ink took the branch at `ink.js:118-123`:
+ *
+ *     if (outputHeight >= this.options.stdout.rows) {
+ *       stdout.write(clearTerminal + this.fullStaticOutput + output);
+ *     }
+ *
+ * `fullStaticOutput` accumulates EVERY `<Static>` frame of the whole session and
+ * is never trimmed, so once that branch is taken it is taken on every subsequent
+ * frame — bypassing both the `output !== lastOutput` dedupe and `throttledLog` —
+ * and the terminal receives the entire session history thirty times a second.
+ * That is a genuine hard freeze, and it is reachable today by any inline user
+ * (`--no-fullscreen`, `TERM=dumb`, CI, a short or narrow terminal) whose model
+ * writes a long answer.
+ *
+ * I-L5-1 — keeping the live region strictly below `stdout.rows` makes that
+ * branch UNREACHABLE, which is the inline analogue of `frame.ts`'s
+ * `frameHeight(r) < r` and deserves the same standing. We cannot bound Ink's
+ * `fullStaticOutput` growth (it is private and append-only); preventing the
+ * branch that WRITES it is the entire mitigation, and nothing about the memory
+ * it holds is fixed by this module.
+ *
+ * Nothing is lost, only deferred: when the entry settles it moves into
+ * `<Static>` and is printed in full.
+ */
+/**
+ * Keep the LAST `maxRows` rows of `text`; report how many were dropped.
+ *
+ * Rows, not wrapped display lines: this runs per frame on a streaming entry, and
+ * a wrap-aware count would need the column width and a second full scan of a
+ * string this function exists to avoid scanning twice.
+ */
+export function clampLiveText(text, maxRows) {
+    if (!Number.isFinite(maxRows) || maxRows <= 0)
+        return { text: '', hiddenRows: rowCount(text) };
+    const keep = Math.floor(maxRows);
+    // Cheap reject: a string with fewer than `keep` newlines cannot have more than
+    // `keep` rows, and this is the path every ordinary entry takes.
+    let newlines = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            newlines += 1;
+    }
+    if (newlines + 1 <= keep)
+        return { text, hiddenRows: 0 };
+    // Walk back from the end to the `keep`-th newline rather than splitting the
+    // whole string: the point of the clamp is to stop touching the head at all.
+    let cut = text.length;
+    let seen = 0;
+    for (let i = text.length - 1; i >= 0; i -= 1) {
+        if (text.charCodeAt(i) === 10) {
+            seen += 1;
+            if (seen === keep) {
+                cut = i + 1;
+                break;
+            }
+        }
+    }
+    return { text: text.slice(cut), hiddenRows: newlines + 1 - keep };
+}
+function rowCount(text) {
+    if (text.length === 0)
+        return 0;
+    let n = 1;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            n += 1;
+    }
+    return n;
+}

package/dist/ui/markdown-blocks.d.ts

@@ -15,11 +15,13 @@ export interface HeadingBlock {
 export interface RuleBlock {
     kind: 'rule';
 }
+/** Column alignment carried by a table's `|---|:--:|` divider row. */
+export type Align = 'left' | 'right' | 'center';
 export interface TableBlock {
     kind: 'table';
     /** Already column-aligned; render as plain monospace rows. */
     rows: string[][];
-    align: ('left' | 'right' | 'center')[];
+    align: Align[];
 }
 export declare function parseHeading(line: string): HeadingBlock | null;
 export declare function isRule(line: string): boolean;
@@ -34,6 +36,28 @@ export declare function tableAlignments(dividerLine: string): TableBlock['align'
  * on any realistic terminal.
  */
 export declare function formatTable(rows: string[][], align: TableBlock['align']): string[];
+/**
+ * One parsed top-level block.
+ *
+ * `line` is deliberately UNPARSED: heading / rule / quote / bullet detection is
+ * a handful of regexes over one short string and is done at render time, where
+ * the theme and the glyph set live. Caching a themed element instead would make
+ * `/theme` a no-op until the cache evicted (K-5).
+ */
+export type MdBlock = {
+    kind: 'code';
+    code: string;
+    lang: string;
+} | {
+    kind: 'table';
+    rows: string[][];
+    align: Align[];
+} | {
+    kind: 'line';
+    text: string;
+};
+/** Split a document into fenced code, pipe tables, and everything else. */
+export declare function parseMarkdownBlocks(text: string): MdBlock[];
 export type InlineSpan = {
     kind: 'text';
     text: string;

package/dist/ui/markdown-blocks.js

@@ -73,6 +73,49 @@ export function formatTable(rows, align) {
         .join('  ')
         .trimEnd());
 }
+/** A fence line: ```` ```lang ```` or a bare ```` ``` ````. */
+const FENCE_RE = /^```(\w*)\s*$/;
+/** Split a document into fenced code, pipe tables, and everything else. */
+export function parseMarkdownBlocks(text) {
+    const lines = text.split('\n');
+    const blocks = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        const fence = FENCE_RE.exec(line.trim());
+        if (fence) {
+            const lang = fence[1] || '';
+            const codeLines = [];
+            i += 1;
+            while (i < lines.length && !FENCE_RE.test((lines[i] ?? '').trim())) {
+                codeLines.push(lines[i] ?? '');
+                i += 1;
+            }
+            i += 1; // skip the closing fence
+            blocks.push({ kind: 'code', code: codeLines.join('\n'), lang });
+            continue;
+        }
+        // A pipe row followed by a divider row starts a table; consume the run.
+        const headerCells = parseTableRow(line);
+        if (headerCells && i + 1 < lines.length && isTableDivider(lines[i + 1] ?? '')) {
+            const align = tableAlignments(lines[i + 1] ?? '');
+            const rows = [headerCells];
+            i += 2;
+            while (i < lines.length) {
+                const cells = parseTableRow(lines[i] ?? '');
+                if (!cells)
+                    break;
+                rows.push(cells);
+                i += 1;
+            }
+            blocks.push({ kind: 'table', rows, align });
+            continue;
+        }
+        blocks.push({ kind: 'line', text: line });
+        i += 1;
+    }
+    return blocks;
+}
 const CODE_RE = /`[^`]+`/g;
 const EMPHASIS_RE = /(\*\*[^*]+\*\*|~~[^~]+~~|\*[^*]+\*)/g;
 /**

package/dist/ui/render-cache.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Render caches (tui-render-performance L2 / R2 + R3).
+ *
+ * Ink has no output caching: every frame re-walks the whole mounted tree,
+ * re-measures every text node and re-serialises the frame. The two most
+ * expensive PURE computations in that walk were being redone from scratch on
+ * every one of them:
+ *
+ *   - `cli-highlight`'s `highlight()` ran INSIDE `CodeBlock`'s render body, so a
+ *     200-line fenced block was a complete highlight.js tokenise, 30 times a
+ *     second, for as long as it stayed mounted;
+ *   - `Markdown` re-split and re-regexed the whole answer into one React element
+ *     per line on every render.
+ *
+ * Everything cached here is a function of its INPUT STRING ALONE. Theme and
+ * glyphs are applied at render time and are never cached, because a themed
+ * React element in a cache makes `/theme` a no-op until the entry evicts (K-5) —
+ * exactly the class of silent bug this package writes comments to avoid.
+ *
+ * Caches are MODULE-LEVEL on purpose: settled transcript text is identical
+ * across component instances and across mount/unmount cycles, so per-instance
+ * caches would miss precisely when a scroll brings an old entry back.
+ */
+import { type MdBlock } from './markdown-blocks.js';
+import { type Glyphs } from './glyphs.js';
+import type { TermCapabilities } from './capabilities.js';
+export declare const RENDER_CACHE_LIMITS: {
+    readonly highlightEntries: 128;
+    readonly highlightBytes: number;
+    /**
+     * Above this, skip highlighting entirely.
+     *
+     * highlight.js is superlinear in the length of a single block, and a
+     * multi-megabyte "code block" is almost always a pasted log rather than
+     * source. Rendering it plain costs the user nothing they would have been able
+     * to read; tokenising it costs the whole frame budget.
+     */
+    readonly highlightMaxChars: 20000;
+    readonly markdownEntries: 256;
+    readonly markdownBytes: number;
+    readonly linesEntries: 512;
+};
+export interface RenderCacheStats {
+    markdownEntries: number;
+    markdownBytes: number;
+    highlightEntries: number;
+    highlightBytes: number;
+    lineEntries: number;
+    hits: number;
+    misses: number;
+}
+/**
+ * Syntax-highlight `code`, memoised on `(lang, code)`.
+ *
+ * `cli-highlight` emits chalk-level ANSI that does not depend on `theme.*`, so
+ * unlike a rendered element this string IS safe to cache across a `/theme`
+ * switch — the same property it has had since before this cache existed.
+ */
+export declare function highlightCached(code: string, lang: string): string;
+/** Parse a markdown document into blocks, memoised on the whole text. */
+export declare function parseMarkdownCached(text: string): MdBlock[];
+/**
+ * `text.split('\n')`, memoised.
+ *
+ * READ-ONLY BY CONTRACT. The returned array is shared with every other holder of
+ * the same string, so a caller that sorts or splices it in place corrupts an
+ * unrelated card. The `readonly string[]` return type is the enforcement.
+ */
+export declare function splitLinesCached(text: string): readonly string[];
+/**
+ * The glyph set for a terminal.
+ *
+ * `pickGlyphs` already returns one of two module constants, so this adds no
+ * caching of its own — it exists so that every render-layer memoisation the
+ * transcript depends on is reachable from one module, and so the components can
+ * stop calling `pickGlyphs` once per entry per frame through six import paths.
+ */
+export declare function glyphsFor(caps: TermCapabilities): Glyphs;
+/** Drop everything. `/perf reset`, and the test suite between cases. */
+export declare function clearRenderCaches(): void;
+export declare function renderCacheStats(): RenderCacheStats;