@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/ui/entries/UserEntry.js

@@ -1,5 +1,21 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Render a user message entry.
+ *
+ * The role glyph, the gutter rail and the inter-entry spacing all belong to
+ * `EntryFrame` now (§4.3), so this component renders content and nothing else.
+ * That is also why it takes no `caps`: it has no glyph of its own left to
+ * degrade.
+ */
+import React from 'react';
 import { Box, Text } from 'ink';
-export function UserEntry({ text, theme }) {
+function UserEntryImpl({ text, theme }) {
     return (_jsx(Box, { flexDirection: "column", children: text.split('\n').map((line, i) => (_jsx(Text, { color: theme.user, bold: i === 0, children: line }, i))) }));
 }
+/**
+ * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).
+ * `mapEntry` already preserves object identity for untouched entries, so the
+ * array props below are stable references on a settled card, and `theme` /
+ * `caps` are `useMemo`d in `App.tsx` (I-L2-1).
+ */
+export const UserEntry = React.memo(UserEntryImpl);

package/dist/ui/exit-snapshot.d.ts

@@ -18,6 +18,13 @@ export interface ExitSnapshot {
     provider: string;
     model: string;
     startedAt: number;
+    /**
+     * Entries the retain ring removed (tui-render-performance L1).
+     *
+     * OPTIONAL so every existing caller and test is unchanged; absent means the
+     * replay says nothing, which is correct for a session that dropped nothing.
+     */
+    droppedEntries?: number;
 }
 /** Called by `App` after every view-state change. Synchronous, side-effect free. */
 export declare function publishExitSnapshot(next: ExitSnapshot): void;

package/dist/ui/glyphs.d.ts

@@ -108,6 +108,15 @@ export interface Glyphs {
     todoPending: string;
     todoActive: string;
     todoDone: string;
+    /**
+     * API retry (llm-api-retry-backoff §6.5). The rail marker on the retry card.
+     *
+     * HERE RATHER THAN IN `RetryCard`, for the reason this file's header gives: a
+     * literal in a component bypasses `pickGlyphs` entirely and shows mojibake on a
+     * legacy console whatever the capability probe said. `glyphs.test.ts`'s static
+     * scan fails the build if either spelling appears anywhere else.
+     */
+    retry: string;
     /**
      * Ink `borderStyle` name for every boxed region (composer, completion popup,
      * overlay frame).

package/dist/ui/glyphs.js

@@ -64,6 +64,7 @@ const UNICODE_GLYPHS = {
     todoPending: '○',
     todoActive: '▸',
     todoDone: '✔',
+    retry: '↻',
     tool: {
         read_file: '▤',
         write_file: '✎',
@@ -125,6 +126,7 @@ const ASCII_GLYPHS = {
     todoPending: '[ ]',
     todoActive: '>',
     todoDone: '[x]',
+    retry: '[r]',
     tool: {
         read_file: '=',
         write_file: '+',

package/dist/ui/layout/AppShell.d.ts

@@ -11,7 +11,6 @@
  */
 import React from 'react';
 import { type RenderMode } from './frame.js';
-import { type FrameGeometry } from './regions.js';
 export interface AppShellProps {
     mode: RenderMode;
     rows: number;
@@ -21,11 +20,10 @@ export interface AppShellProps {
     /**
      * The live subagent roster (team-subagents §6.1), or nothing.
      *
-     * IT RENDERS INSIDE `bottomRef` IN THE FULL-SCREEN BRANCH, and it has to
-     * (I-10): `geometryRef.current.bottom` is MEASURED from that box, and the
-     * wheel router uses it to decide whether a notch belongs to the transcript or
-     * to prompt history. A panel rendered above the measured box would make the
-     * composer band boundary stale the instant a dispatch started.
+     * IT RENDERS IN THE BOTTOM CHROME OF THE FULL-SCREEN BRANCH, above `toast` and
+     * below the viewport: the roster is transient status about the run in progress,
+     * so it belongs with the other transient rows rather than inside the scrolling
+     * transcript, where it would be interleaved with history and scroll away.
      */
     team?: React.ReactNode;
     /**
@@ -36,10 +34,11 @@ export interface AppShellProps {
      * primitive and has no business knowing what a todo is. `team` above already
      * leaks content vocabulary in here; there is no reason to repeat it.
      *
-     * IT MUST NOT BE RENDERED INSIDE `bottomRef` (C-6 / I-4). That box is MEASURED
-     * and the wheel router reads the composer band boundary from it; a column
-     * added there would inflate the measurement and start routing transcript
-     * scrolls into prompt history.
+     * IT MUST BE RENDERED IN THE MIDDLE BAND, BESIDE THE VIEWPORT (C-6 / I-4) —
+     * that is what makes it a rail rather than another row of bottom chrome. Moved
+     * down into the bottom box it would stop being a column beside the transcript
+     * and start eating viewport height, growing and shrinking the transcript every
+     * time the list changed length.
      *
      * The INLINE branch does not include it at all — a structural guarantee rather
      * than a promise that the caller passes `null` (non-goal 4).
@@ -56,21 +55,13 @@ export interface AppShellProps {
      * both on screen showing the same list (I-6). Fullscreen has the rail; that is
      * the whole design.
      *
-     * It sits between `viewport` and `team`, i.e. OUTSIDE the measured box in the
-     * other branch — but inline has no measured box at all (`geometryRef` is set
-     * to `UNMEASURED_GEOMETRY` there), so there is nothing here to invalidate.
+     * It sits between `viewport` and `team`, mirroring where the rail sits in the
+     * other branch: last thing above the bottom chrome, so the strip and the
+     * roster read top-to-bottom in the same order in both modes.
      */
     strip?: React.ReactNode;
     toast: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
-    /**
-     * Where the wheel router reads the composer band boundary from (mouse-wheel
-     * §4.5). Written in a LAYOUT EFFECT to a MUTABLE REF, never to state: the
-     * measurement happens on every commit, and routing it through `setState`
-     * would add a re-render to the streaming path for a value nothing renders
-     * (R-7).
-     */
-    geometryRef?: React.MutableRefObject<FrameGeometry>;
 }
-export declare function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, geometryRef, }: AppShellProps): React.ReactElement;
+export declare function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, }: AppShellProps): React.ReactElement;

package/dist/ui/layout/AppShell.js

@@ -1,44 +1,9 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-/**
- * AppShell (spec §4.3) — the frame that makes R2 true.
- *
- * In `fullscreen` the root box has a FIXED height of `frameHeight(rows)` and the
- * middle viewport is the only `flexGrow` child, so the bottom chrome (toast /
- * composer / status bar) is physically the last thing on the screen from the
- * very first frame — empty session, long session, mid-scroll, overlay open.
- *
- * In `inline` the same children are emitted in the same order with no height
- * constraint, i.e. byte-for-byte the v0.2.0 document-flow behavior.
- */
-import { useLayoutEffect, useRef } from 'react';
-import { Box, measureElement } from 'ink';
+import { Box } from 'ink';
 import { frameHeight } from './frame.js';
-import { UNMEASURED_GEOMETRY } from './regions.js';
-export function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, geometryRef, }) {
-    const bottomRef = useRef(null);
-    // DECLARED ABOVE THE INLINE EARLY RETURN, and it has to stay there: React
-    // keys hooks by call order, and a hook that only runs in one mode changes
-    // that order between modes.
-    //
-    // Ink computes yoga layout in `onRender`, which React runs BEFORE layout
-    // effects, so this reflects the commit that just happened — the same
-    // mechanism `ScrollViewport` already relies on.
-    useLayoutEffect(() => {
-        if (!geometryRef)
-            return;
-        if (mode === 'inline' || !bottomRef.current) {
-            geometryRef.current = UNMEASURED_GEOMETRY;
-            return;
-        }
-        geometryRef.current = {
-            // 1 in the alternate screen — see the note on `FrameGeometry.top`.
-            top: 1,
-            height: frameHeight(rows),
-            bottom: measureElement(bottomRef.current).height,
-        };
-    });
+export function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, }) {
     if (mode === 'inline') {
         return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, strip, team, toast, composer, status] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), rail] }), _jsxs(Box, { ref: bottomRef, flexDirection: "column", flexShrink: 0, children: [team, toast, composer, status] })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), rail] }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [team, toast, composer, status] })] }));
 }

package/dist/ui/layout/MeasuredEntry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * One transcript entry, wrapped so its rendered height reaches the height store
+ * (tui-render-performance L3).
+ *
+ * IT MUST NOT CONSTRAIN HEIGHT. The natural height IS the value being measured;
+ * a `height` prop here would make every entry report back whatever it was told,
+ * and the spacers would encode a fiction.
+ *
+ * Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+ * effects, so the measurement below reflects the commit that just happened —
+ * the same mechanism `ScrollViewport.tsx:87-88` and `AppShell.tsx:100-102`
+ * already document and rely on.
+ */
+import React from 'react';
+import type { HeightKey } from './virtual-window.js';
+export interface MeasuredEntryProps {
+    heightKey: HeightKey;
+    onMeasure: (key: HeightKey, rows: number) => void;
+    children: React.ReactNode;
+}
+export declare function MeasuredEntry({ heightKey, onMeasure, children, }: MeasuredEntryProps): React.ReactElement;

package/dist/ui/layout/MeasuredEntry.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * One transcript entry, wrapped so its rendered height reaches the height store
+ * (tui-render-performance L3).
+ *
+ * IT MUST NOT CONSTRAIN HEIGHT. The natural height IS the value being measured;
+ * a `height` prop here would make every entry report back whatever it was told,
+ * and the spacers would encode a fiction.
+ *
+ * Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+ * effects, so the measurement below reflects the commit that just happened —
+ * the same mechanism `ScrollViewport.tsx:87-88` and `AppShell.tsx:100-102`
+ * already document and rely on.
+ */
+import { useLayoutEffect, useRef } from 'react';
+import { Box, measureElement } from 'ink';
+export function MeasuredEntry({ heightKey, onMeasure, children, }) {
+    const ref = useRef(null);
+    // No dependency array on purpose: the entry's content can change without the
+    // key changing identity in a way this component can see, and `report` is a
+    // no-op when the measurement is unchanged — so an unconditional effect costs
+    // one `getComputedHeight()` read and cannot miss a resize.
+    useLayoutEffect(() => {
+        const node = ref.current;
+        if (!node)
+            return;
+        onMeasure(heightKey, measureElement(node).height);
+    });
+    return (_jsx(Box, { ref: ref, flexDirection: "column", flexShrink: 0, children: children }));
+}

package/dist/ui/layout/ScrollViewport.js

@@ -13,9 +13,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * measure → setState → re-render → measure loop whose convergence is provable
  * but whose frame count is not — expensive inside a 33 ms streaming window.
  */
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { Box, Text, measureElement, useStdout } from 'ink';
 import { pickGlyphs } from '../glyphs.js';
+import { ViewportGeometryContext } from './viewport-geometry.js';
 import { applyScrollTimes, clampScroll, } from './scroll.js';
 import { thumbRange } from './scroll-indicator.js';
 import { MIN_INDICATOR_COLS, ScrollIndicator } from './ScrollIndicator.js';
@@ -81,7 +82,12 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
     // more than the affordance. The routing never reads this flag, which is what
     // keeps the indicator independently revertible (§13-Q3).
     const indicatorVisible = showScrollIndicator && cols >= MIN_INDICATOR_COLS;
-    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Box, { ref: innerRef, flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: children }) }), indicatorVisible && (_jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset), theme: theme, caps: caps }))] }), showHint && (
+    // PUBLISHED, NOT LIFTED (tui-render-performance L3 / §3.3.2). The three
+    // numbers virtualisation needs are already owned here; a `useMemo`d context
+    // value hands them down without adding a second owner or a second measure
+    // pass, which is exactly what this component's header (P1-7) forbids.
+    const geometry = useMemo(() => ({ viewportRows: metrics.viewport, offset, contentRows: metrics.content }), [metrics.viewport, metrics.content, offset]);
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Box, { ref: innerRef, flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: _jsx(ViewportGeometryContext.Provider, { value: geometry, children: children }) }) }), indicatorVisible && (_jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset), theme: theme, caps: caps }))] }), showHint && (
             // Not an overlay — Ink has no absolute positioning or z-index. This takes
             // the viewport's last row, trading one line of content for a hint that
             // cannot drift. Cheaper than stacking with negative margins.

package/dist/ui/layout/viewport-geometry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Viewport geometry, published downward (tui-render-performance L3).
+ *
+ * `ScrollViewport`'s header records (P1-7) why it — and not its parent — owns
+ * the metrics and the scroll offset: holding the offset in two places creates a
+ * measure -> setState -> re-render -> measure loop whose convergence is provable
+ * but whose frame count is not.
+ *
+ * Virtualisation needs those same three numbers one level DOWN, in
+ * `TranscriptList`. So the viewport PUBLISHES rather than lifting: a `useMemo`d
+ * context value, no new state, no second owner, no extra layout pass.
+ */
+export interface ViewportGeometry {
+    /** Visible height of the clipping box, in rows. `0` before the first measure. */
+    viewportRows: number;
+    /** Rows hidden BELOW the viewport (`layout/scroll.ts` semantics; V-4). */
+    offset: number;
+    /** Natural (unclipped) height of the content, in rows. */
+    contentRows: number;
+}
+/**
+ * The default is the UNMEASURED geometry, and consumers must treat it as such:
+ * a `TranscriptList` rendered outside a `ScrollViewport` (inline mode, and every
+ * test that mounts it bare) sees `viewportRows: 0`, which `selectWindow` reads
+ * as "first frame" and answers by pinning the live tail.
+ */
+export declare const ViewportGeometryContext: import("react").Context<ViewportGeometry>;
+export declare function useViewportGeometry(): ViewportGeometry;

package/dist/ui/layout/viewport-geometry.js

@@ -0,0 +1,27 @@
+/**
+ * Viewport geometry, published downward (tui-render-performance L3).
+ *
+ * `ScrollViewport`'s header records (P1-7) why it — and not its parent — owns
+ * the metrics and the scroll offset: holding the offset in two places creates a
+ * measure -> setState -> re-render -> measure loop whose convergence is provable
+ * but whose frame count is not.
+ *
+ * Virtualisation needs those same three numbers one level DOWN, in
+ * `TranscriptList`. So the viewport PUBLISHES rather than lifting: a `useMemo`d
+ * context value, no new state, no second owner, no extra layout pass.
+ */
+import { createContext, useContext } from 'react';
+/**
+ * The default is the UNMEASURED geometry, and consumers must treat it as such:
+ * a `TranscriptList` rendered outside a `ScrollViewport` (inline mode, and every
+ * test that mounts it bare) sees `viewportRows: 0`, which `selectWindow` reads
+ * as "first frame" and answers by pinning the live tail.
+ */
+export const ViewportGeometryContext = createContext({
+    viewportRows: 0,
+    offset: 0,
+    contentRows: 0,
+});
+export function useViewportGeometry() {
+    return useContext(ViewportGeometryContext);
+}

package/dist/ui/layout/virtual-window.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 type { Entry } from '../../agent/reducer.js';
+import type { DensityMode } from '../density.js';
+export declare 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.
+     */
+    readonly overscan: 2;
+    /** Height-cache ceiling (LRU). Four thousand numbers, not four thousand strings. */
+    readonly heightEntries: 4096;
+};
+export type HeightKey = string;
+/**
+ * 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 declare function entryRevision(entry: Entry): string;
+/**
+ * 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 declare function heightKey(entry: Entry, cols: number, expanded: boolean, density: DensityMode, flags?: string): HeightKey;
+/**
+ * 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 declare function estimateEntryRows(entry: Entry, cols: number, density: DensityMode, expanded: boolean, thinkingVisible?: boolean): number;
+export interface WindowSelection {
+    /** First mounted entry, inclusive. */
+    startIndex: number;
+    /** One past the last mounted entry. */
+    endIndex: number;
+    /** Spacer rows above the mounted slice. */
+    leadingRows: number;
+    /** Spacer rows below the mounted slice. */
+    trailingRows: number;
+    /** Sum of every entry height, measured or estimated. */
+    totalRows: number;
+}
+export interface SelectWindowInput {
+    entries: readonly Entry[];
+    /** Measured, else estimated; never 0 for a real entry. */
+    heightOf: (index: number) => number;
+    viewportRows: number;
+    /** Rows hidden BELOW the viewport — the existing `scroll.ts` semantic (V-4). */
+    offset: number;
+    /** `>= 2` (V-2). Lower values are raised rather than honoured. */
+    overscan: number;
+}
+/** Choose which entries to mount, and how tall the two spacers must be. */
+export declare function selectWindow(input: SelectWindowInput): WindowSelection;