@aragon-agent/cli 0.6.29 → 0.6.31

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

@@ -0,0 +1,263 @@
+/**
+ * ScrollbackWriter — the byte contract of native-scroll mode
+ * (tui-native-terminal-scroll §4.3).
+ *
+ * It implements `FrameDiffer`, so `stdout-frame-writer.ts::wrapStdoutForFrames`
+ * binds it to a real stream exactly as it binds the full-screen differ. What it
+ * does differently: the screen is NOT the app's. Settled conversation rows are
+ * printed into the host terminal's own scrollback, and Ink's frame is only a small
+ * LIVE REGION parked directly under the last printed row.
+ *
+ * GEOMETRY IS RELATIVE (D2). A batch is `CUU(H0)` to the top of the previous
+ * region, erase down, print static rows, print the new region, park one row below
+ * it. Nothing in that sequence depends on the terminal's absolute row count, so a
+ * terminal that scrolls underneath it cannot misplace anything.
+ *
+ * THE INVARIANTS THAT FAIL SILENTLY IF DROPPED:
+ *  - I-S4 · every batch parks the cursor at (regionBottom + 1, column 0), the same
+ *    place Ink's `previousLineCount = H + 1` expects, so falling back to a raw Ink
+ *    write is still correct.
+ *  - I-S8 · geometry in doubt (foreign write, unparseable chunk) => `prev = null`
+ *    => next batch is a SEED. Never keep erasing on a stale `H0`.
+ *  - I-S14 · after `finalize` EVERY Ink write is swallowed. Ink's unmount renders
+ *    once more (and a 32 ms trailing throttle call can follow); passed through,
+ *    its `eraseLines(H + 1)` would erase the summary and the end of the
+ *    conversation. With an unknown or sub-2-row terminal the frame is still
+ *    parsed so `prev`/`H0` track Ink's own `previousLineCount`.
+ *  - I-S13 · no emitted row is wider than `cols - 1` (clipped, counted).
+ */
+import { parseInkFrame } from '../frame-parser.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+import { clipLine, diffBytes, estimateReflowRows, finalizeBytes, fullBytes, seedBytes, } from './writer-shapes.js';
+/** `ansiEscapes.clearTerminal` — Ink's tall-frame write. It contains `ESC[3J`. */
+const CLEAR_TERMINAL = '\x1b[2J\x1b[3J\x1b[H';
+export function createScrollbackWriter(o) {
+    const now = o.now ?? Date.now;
+    const maxBatch = SCROLLBACK_LIMITS.maxRowsPerBatch;
+    /** Region lines as written (clipped), or null when the geometry is in doubt. */
+    let prev = null;
+    /** The same lines before clipping, so unchanged rows are not re-measured. */
+    let prevRaw = null;
+    /** Rows between region top and the parked cursor. Tracks Ink's own count. */
+    let regionHeight = 0;
+    /** Whether anything has ever been written (a re-seed then starts on a new line). */
+    let everWritten = false;
+    let seenAnyChunk = false;
+    let finalized = false;
+    let guardTripped = false;
+    let consecutiveGuard = 0;
+    let lastResizeAt = Number.NEGATIVE_INFINITY;
+    let resizePending = false;
+    /** Width the previous region was written at, for the reflow estimate. */
+    let lastWriteCols;
+    let repaintQueued = false;
+    const stats = {
+        framesSeed: 0, framesDiff: 0, framesFull: 0, staticRowsWritten: 0, bytesWritten: 0,
+        fallbacks: 0, guardHits: 0, guardHitsOutsideResize: 0, clippedRows: 0, elidedEntries: 0,
+        resizes: 0, repaints: 0,
+    };
+    const liveCols = () => {
+        const cols = o.cols();
+        return cols !== undefined && Number.isFinite(cols) && cols >= 1 ? Math.floor(cols) : undefined;
+    };
+    const liveRows = () => {
+        const rows = o.rows();
+        return rows !== undefined && Number.isFinite(rows) ? Math.floor(rows) : undefined;
+    };
+    const scheduleRepaint = () => {
+        if (!o.requestRepaint || repaintQueued || finalized)
+            return;
+        repaintQueued = true;
+        // Deferred by the host (setImmediate): this can fire from inside Ink's write.
+        o.requestRepaint();
+    };
+    const invalidate = () => {
+        prev = null;
+        prevRaw = null;
+        resizePending = false;
+    };
+    /** Clip every row to `cols - 1`, reusing the previous result for unchanged rows (I-S13). */
+    const clipRegion = (lines, cols) => {
+        if (cols === undefined)
+            return [...lines];
+        const limit = cols - 1;
+        return lines.map((line, i) => {
+            if (prevRaw && prev && prevRaw[i] === line && prev[i] !== undefined)
+                return prev[i];
+            const result = clipLine(line, limit);
+            if (result.clipped)
+                stats.clippedRows += 1;
+            return result.text;
+        });
+    };
+    const clipStatics = (rows, cols) => {
+        if (cols === undefined || rows.length === 0)
+            return rows;
+        return rows.map((line) => {
+            const result = clipLine(line, cols - 1);
+            if (result.clipped)
+                stats.clippedRows += 1;
+            return result.text;
+        });
+    };
+    /** Rows to move up to reach the region top: the plain height, or a post-resize estimate. */
+    const eraseDistance = (rows, cols) => {
+        if (!resizePending || prev === null || cols === undefined)
+            return regionHeight;
+        const reflowed = estimateReflowRows(prev, cols);
+        return Math.min(Math.max(0, rows - 1), reflowed);
+    };
+    const record = (bytes, shape, statics) => {
+        if (shape === 'seed')
+            stats.framesSeed += 1;
+        else if (shape === 'diff')
+            stats.framesDiff += 1;
+        else if (shape === 'full')
+            stats.framesFull += 1;
+        else
+            stats.repaints += 1;
+        stats.staticRowsWritten += statics;
+        stats.bytesWritten += bytes.length;
+        return bytes;
+    };
+    const afterBatch = (lines, raw, cols) => {
+        prev = lines;
+        prevRaw = raw;
+        regionHeight = lines.length;
+        everWritten = true;
+        resizePending = false;
+        lastWriteCols = cols;
+        // A feed larger than one batch continues on the next tick, region still parked.
+        if (o.drain.pending() > 0) {
+            repaintQueued = false;
+            scheduleRepaint();
+        }
+    };
+    const assemble = (lines, raw, rows, cols) => {
+        const statics = clipStatics(o.drain.takeUpTo(maxBatch), cols);
+        let out;
+        if (prev === null) {
+            out = record(seedBytes({ lines, statics, sync: o.sync, reseed: everWritten }), 'seed', statics.length);
+        }
+        else if (statics.length > 0 || lines.length !== prev.length || o.fullEveryFrame || resizePending) {
+            out = record(fullBytes({ lines, statics, eraseUp: eraseDistance(rows, cols), sync: o.sync }), 'full', statics.length);
+        }
+        else {
+            out = record(diffBytes({ lines, prev, sync: o.sync }), 'diff', 0);
+        }
+        afterBatch(lines, raw, cols);
+        return out;
+    };
+    const swallowTallFrame = () => {
+        stats.guardHits += 1;
+        if (now() - lastResizeAt >= SCROLLBACK_LIMITS.guardResizeGraceMs) {
+            stats.guardHitsOutsideResize += 1;
+            consecutiveGuard += 1;
+            if (consecutiveGuard >= SCROLLBACK_LIMITS.guardTripCount && !guardTripped) {
+                guardTripped = true;
+                o.onGuardTrip?.();
+            }
+        }
+        // Swallow the whole chunk: it would clear the visible screen AND scrollback.
+        return '';
+    };
+    const countFallback = (counted) => {
+        invalidate();
+        if (counted) {
+            stats.fallbacks += 1;
+            if (stats.fallbacks === 1)
+                o.onFirstFallback?.();
+        }
+        return null;
+    };
+    const transform = (chunk) => {
+        if (finalized)
+            return '';
+        if (chunk.startsWith(CLEAR_TERMINAL))
+            return swallowTallFrame();
+        consecutiveGuard = 0;
+        guardTripped = false;
+        const firstChunk = !seenAnyChunk;
+        seenAnyChunk = true;
+        const rows = liveRows();
+        const lines = parseInkFrame(chunk);
+        if (rows === undefined || rows < 2) {
+            // Pass through, but keep `prev`/`H0` in step with Ink's own count (RV-6).
+            if (lines) {
+                prev = lines;
+                prevRaw = lines;
+                regionHeight = lines.length;
+            }
+            return null;
+        }
+        if (lines === null)
+            return countFallback(!firstChunk);
+        if (lines.length + 1 > rows) {
+            // Unreachable by construction (I-S1); never erase on a guess.
+            invalidate();
+            return '';
+        }
+        const cols = liveCols();
+        return assemble(clipRegion(lines, cols), lines, rows, cols);
+    };
+    const repaint = () => {
+        repaintQueued = false;
+        if (finalized || prev === null || prevRaw === null)
+            return '';
+        if (o.drain.pending() === 0 && !resizePending)
+            return '';
+        const rows = liveRows();
+        if (rows === undefined || rows < 2)
+            return '';
+        const cols = liveCols();
+        const lines = prev;
+        const statics = clipStatics(o.drain.takeUpTo(maxBatch), cols);
+        const bytes = fullBytes({ lines, statics, eraseUp: eraseDistance(rows, cols), sync: o.sync });
+        // A repaint is its own counter: `framesFull` counts frames INK produced.
+        record(bytes, 'repaint', statics.length);
+        afterBatch(lines, prevRaw, cols);
+        return bytes;
+    };
+    const finalize = (summary) => {
+        if (finalized)
+            return '';
+        finalized = true;
+        const statics = clipStatics(o.drain.takeAll(), liveCols());
+        // Unknown geometry after a foreign write: no safe erase, start on a fresh line.
+        const eraseUp = prev === null && everWritten ? -1 : eraseDistance(liveRows() ?? 24, liveCols());
+        const bytes = finalizeBytes({ eraseUp, statics, summary });
+        stats.staticRowsWritten += statics.length;
+        stats.bytesWritten += bytes.length;
+        return bytes;
+    };
+    o.drain.onEnqueue = scheduleRepaint;
+    return {
+        transform,
+        repaint,
+        finalize,
+        invalidate,
+        onResize() {
+            stats.resizes += 1;
+            lastResizeAt = now();
+            consecutiveGuard = 0;
+            guardTripped = false;
+            // Keep `prev`: the reflow estimate needs the lines the terminal re-flowed.
+            if (prev !== null && !finalized)
+                resizePending = true;
+        },
+        cursorNeutralWrite() {
+            // OSC 52 and friends move no cell and no cursor (I-S11).
+        },
+        regionRows: () => regionHeight,
+        scrollbackStats: () => ({ ...stats, elidedEntries: o.drain.elided() }),
+        stats: () => ({
+            framesTotal: stats.framesSeed + stats.framesFull + stats.framesDiff,
+            framesDiffed: stats.framesDiff,
+            framesFull: stats.framesSeed + stats.framesFull,
+            linesWritten: stats.staticRowsWritten,
+            bytesWritten: stats.bytesWritten,
+            fallbacks: stats.fallbacks,
+            repaints: stats.repaints,
+        }),
+    };
+}

package/dist/ui/scrollback/settled-boundary.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Settled boundary — which transcript entries may be PRINTED
+ * (tui-native-terminal-scroll §4.4).
+ *
+ * Printed rows live in the host terminal's scrollback and can never be rewritten
+ * ("printed is forever"). So the only entries that may be printed are the ones the
+ * reducer will NEVER write to again. This module derives that from the reducer's
+ * real write set, one exhaustive `switch` per entry kind. Adding an `Entry` kind is
+ * a compile error here (`never`), which is the whole point; widening the write set
+ * of an EXISTING kind is not caught by the compiler, so `agent/reducer.ts` carries
+ * a pointer comment beside the `Entry` union and the unit tests pin each row.
+ *
+ * Three rules that are easy to "simplify" wrongly:
+ *  - A tool is stable only when `done` or `error`. `pending` is NOT stable: the
+ *    card is created at `pending` and `toolCallDelta` keeps rewriting `argsRaw`
+ *    while the model streams its arguments (RV-1).
+ *  - A trailing `Context length exceeded` error notice is NOT stable while a run is
+ *    active: `compactionStart` rewrites it in place into an info notice (RV-4).
+ *  - A non-terminal `service` card is neither printed nor a wall (RV-3). It is
+ *    rewritten for the whole session; the one-row `terminal: true` record the
+ *    reducer appends at the end is an ordinary stable entry and carries the news.
+ */
+import type { Entry } from '../../agent/reducer.js';
+/** Never printed and never a wall: rewritten for the whole session (RV-3). */
+export declare function isExcluded(entry: Entry): boolean;
+/** True when the reducer will never write to `entry` again. */
+export declare function isEntryStable(entry: Entry, runActive: boolean, isTail: boolean): boolean;
+/**
+ * Length of the printable PREFIX of `entries`.
+ *
+ * The first unstable (non-excluded) entry is a wall: everything before it may
+ * print, nothing after it may, which keeps scrollback order equal to conversation
+ * order (I-S3). Excluded entries are skipped, so a long-lived service card never
+ * blocks the conversation behind it.
+ */
+export declare function settledCount(entries: readonly Entry[], runActive: boolean): number;
+/**
+ * Everything printable at shutdown: all entries except those that never settle
+ * (`queued`, non-terminal services). The last answer must not be lost to a
+ * boundary that was waiting for a frame that will never come.
+ */
+export declare function settleAllEntries(entries: readonly Entry[]): Entry[];

package/dist/ui/scrollback/settled-boundary.js

@@ -0,0 +1,106 @@
+/**
+ * Settled boundary — which transcript entries may be PRINTED
+ * (tui-native-terminal-scroll §4.4).
+ *
+ * Printed rows live in the host terminal's scrollback and can never be rewritten
+ * ("printed is forever"). So the only entries that may be printed are the ones the
+ * reducer will NEVER write to again. This module derives that from the reducer's
+ * real write set, one exhaustive `switch` per entry kind. Adding an `Entry` kind is
+ * a compile error here (`never`), which is the whole point; widening the write set
+ * of an EXISTING kind is not caught by the compiler, so `agent/reducer.ts` carries
+ * a pointer comment beside the `Entry` union and the unit tests pin each row.
+ *
+ * Three rules that are easy to "simplify" wrongly:
+ *  - A tool is stable only when `done` or `error`. `pending` is NOT stable: the
+ *    card is created at `pending` and `toolCallDelta` keeps rewriting `argsRaw`
+ *    while the model streams its arguments (RV-1).
+ *  - A trailing `Context length exceeded` error notice is NOT stable while a run is
+ *    active: `compactionStart` rewrites it in place into an info notice (RV-4).
+ *  - A non-terminal `service` card is neither printed nor a wall (RV-3). It is
+ *    rewritten for the whole session; the one-row `terminal: true` record the
+ *    reducer appends at the end is an ordinary stable entry and carries the news.
+ */
+import { CONTEXT_OVERFLOW_NOTICE_PREFIX } from '../../agent/reducer.js';
+/** Kinds the reducer may still rewrite while a run is active, so a tail one is held. */
+const MUTABLE_TAIL_KINDS = new Set([
+    'assistant', 'tool', 'compaction', 'todo', 'team', 'fast', 'retry', 'queued',
+]);
+/** Never printed and never a wall: rewritten for the whole session (RV-3). */
+export function isExcluded(entry) {
+    return entry.kind === 'service' && entry.terminal !== true;
+}
+/** True when the reducer will never write to `entry` again. */
+export function isEntryStable(entry, runActive, isTail) {
+    switch (entry.kind) {
+        case 'user':
+            return true;
+        case 'notice':
+            return !(runActive &&
+                isTail &&
+                entry.level === 'error' &&
+                entry.text.startsWith(CONTEXT_OVERFLOW_NOTICE_PREFIX));
+        case 'assistant':
+            return !entry.streaming;
+        case 'tool':
+            return entry.status === 'done' || entry.status === 'error';
+        case 'compaction':
+            return entry.live !== true;
+        case 'todo':
+            return entry.live === false;
+        case 'team':
+            return entry.active === false;
+        case 'fast':
+            return entry.live === false;
+        case 'retry':
+            return (entry.phase === 'recovered' ||
+                entry.phase === 'exhausted' ||
+                entry.phase === 'interrupted');
+        case 'queued':
+            // Rewritten in place into a `user` entry by the matching receipt.
+            return false;
+        case 'service':
+            // Only the terminal record is ever a candidate; `isExcluded` filters the rest.
+            return entry.terminal === true;
+        default: {
+            const exhaustive = entry;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Length of the printable PREFIX of `entries`.
+ *
+ * The first unstable (non-excluded) entry is a wall: everything before it may
+ * print, nothing after it may, which keeps scrollback order equal to conversation
+ * order (I-S3). Excluded entries are skipped, so a long-lived service card never
+ * blocks the conversation behind it.
+ */
+export function settledCount(entries, runActive) {
+    const last = entries.length - 1;
+    let count = entries.length;
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i];
+        if (isExcluded(entry))
+            continue;
+        if (!isEntryStable(entry, runActive, i === last)) {
+            count = i;
+            break;
+        }
+    }
+    // Hold a mutable TAIL while a run is active, but only a mutable one: a `user` or
+    // `notice` at the tail prints immediately (a submitted message must appear at once).
+    if (runActive && count === entries.length && count > 0) {
+        const tail = entries[last];
+        if (!isExcluded(tail) && MUTABLE_TAIL_KINDS.has(tail.kind))
+            return last;
+    }
+    return count;
+}
+/**
+ * Everything printable at shutdown: all entries except those that never settle
+ * (`queued`, non-terminal services). The last answer must not be lost to a
+ * boundary that was waiting for a frame that will never come.
+ */
+export function settleAllEntries(entries) {
+    return entries.filter((entry) => entry.kind !== 'queued' && !isExcluded(entry));
+}

package/dist/ui/scrollback/use-scrollback-view.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `useScrollbackView` — the promotion pipeline of native-scroll mode
+ * (tui-native-terminal-scroll §4.4 / §6.2).
+ *
+ * `App` calls it ALWAYS (hooks cannot be conditional); `enabled: false` makes every
+ * effect a no-op and keeps `scrollMode: 'app'` byte-identical to the pre-feature
+ * build (I-S9).
+ *
+ * What it does when enabled:
+ *  1. Prints the session header (and the opener for an empty session) once.
+ *  2. On every entries change, promotes each newly SETTLED entry: renders it once
+ *     through the offscreen renderer and enqueues the rows for the writer.
+ *  3. Computes the live-region budget and the streaming preview rows for the shell.
+ *
+ * THE PROMOTION RUNS IN A MICROTASK, NOT IN THE EFFECT. The offscreen renderer is a
+ * second Ink instance, and both instances share one React reconciler. A `rerender`
+ * issued from inside the main tree's commit (a layout effect) is deferred until that
+ * commit finishes, so its frame would not exist when the effect reads it. A
+ * microtask runs after the commit has unwound, where the offscreen render is
+ * synchronous again. Everything the pass needs is read from refs for that reason.
+ *
+ * `printedIds` is the ONLY authority on "already printed" (RV-7). The cursor is just
+ * a hint for where to resume scanning: entries leave the list by retain-ring
+ * trimming AND by reducer deletion (empty settled assistants, abandoned tool
+ * cards), so an id-keyed cursor can dangle, and then the only correct answer is to
+ * rescan and let `printedIds` skip.
+ */
+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';
+import { type ScrollbackBudget } from './budget.js';
+import type { ScrollbackDrain } from './drain.js';
+import type { ScrollbackWriter } from './scrollback-writer.js';
+/** The channel between `cli.tsx` (which owns the stream) and the React tree. */
+export interface ScrollbackBridge {
+    writer: ScrollbackWriter;
+    drain: ScrollbackDrain;
+    /** Installed by `cli.tsx`: schedule `writer.repaint()` soon. */
+    requestFlush: () => void;
+    /**
+     * Installed by the hook on mount (reads the latest entries through a ref).
+     * `restore()` calls it on every exit path; it is idempotent through `printedIds`
+     * and it releases the offscreen renderer when done.
+     */
+    settleAllNow: () => void;
+    /** Installed by `App`; at most `exitSummaryMaxRows` rows. Wrapped in try/catch by the caller. */
+    getSummaryRows: () => readonly string[];
+    /** Installed by `App`: the writer swallowed repeated tall frames (degrade to the placeholder). */
+    onGuardTrip: (() => void) | null;
+}
+export declare function createScrollbackBridge(parts: Pick<ScrollbackBridge, 'writer' | 'drain'> & {
+    requestFlush?: () => void;
+}): ScrollbackBridge;
+export type ScrollbackResetKind = 'clear' | 'restore';
+export interface UseScrollbackViewArgs {
+    /** `scrollMode === 'native'`. */
+    enabled: boolean;
+    bridge: ScrollbackBridge | undefined;
+    entries: readonly Entry[];
+    runActive: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+    density: DensityMode;
+    thinkingVisible: boolean;
+    reducedMotion: boolean;
+    /** Terminal size. */
+    rows: number;
+    cols: number;
+    /** Printed first, once. */
+    headerNode: React.ReactNode;
+    /** Printed after the header for an empty session. */
+    openerNode: React.ReactNode | null;
+    overlayOpen: boolean;
+    draftRows: number;
+    popupRows: number;
+    statusExpanded: boolean;
+    /** Degrade the region to the placeholder (the writer's tall-frame guard tripped). */
+    forceInactive?: boolean;
+}
+export interface ScrollbackView {
+    budget: ScrollbackBudget | null;
+    liveTailLines: string[];
+    /** Print a fresh EXPANDED copy of an entry; false when it cannot be found / rendered. */
+    reprintExpanded(entryId: string): boolean;
+    /** Promote everything printable now (shutdown). */
+    settleAll(): void;
+    /** Called by `App`'s dispatch wrapper BEFORE a reset action reaches the reducer. */
+    notifyReset(kind: ScrollbackResetKind): void;
+}
+export declare function useScrollbackView(args: UseScrollbackViewArgs): ScrollbackView;