@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/tools/terminal-output.js

@@ -0,0 +1,198 @@
+/**
+ * Raw child-process output to terminal-safe rows (agent-activity-presentation-live
+ * L2 / §3.2).
+ *
+ * NOTHING ELSE IN THIS TREE STRIPS ANSI (E-13). `renderBash` hands each line to
+ * `<Text>` unmodified (`ui/entries/ToolPreview.tsx:180`), and that survives only
+ * because the settled preview is printed ONCE, after the command has stopped
+ * writing. Redraw the same text every frame while the child is still emitting
+ * `\r`-rewritten progress bars and `\x1b[A` cursor moves and it stops being
+ * survivable: the terminal honours cursor motion Ink does not know it emitted,
+ * and `wrappedRows` measures escape bytes as if they were columns.
+ *
+ * So this module is the boundary. It runs ONCE, inside the store's `append`
+ * (§3.1.1), and every reader downstream is already safe.
+ *
+ * Pure, ASCII-only, React-free, Ink-free, and TOTAL: `sanitizeChunk` never
+ * throws, for any input including lone surrogates, NUL bytes, a chunk consisting
+ * solely of `\x1b`, and a 4 MB chunk containing no `\n` at all.
+ *
+ * D-27 — IT STRIPS, IT DOES NOT INTERPRET. Keeping colour would mean validating
+ * it (an unterminated SGR leaks its attribute into the rest of the frame), and
+ * interpreting cursor motion would mean owning a screen buffer. Neither is a
+ * presentation round's job.
+ */
+/** Columns a live row may occupy before it is clipped. */
+export const LIVE_ROW_MAX_CHARS = 200;
+/** Tab stop width, matching every terminal's default. */
+export const TAB_WIDTH = 8;
+/**
+ * The in-progress line's ceiling before it is flushed as a row (§3.2 step 7).
+ *
+ * AFTER STEP 4 THIS IS A RARE PATH RATHER THAN THE PROGRESS-BAR PATH (D-33). A
+ * `\r`-rewritten bar collapses to one row however many times it is redrawn, so
+ * reaching 400 characters with no `\n` requires a line that is genuinely that
+ * long -- `cat` on a minified bundle. Without the bound the carry is an
+ * unbounded accumulator.
+ */
+export const CARRY_MAX_CHARS = LIVE_ROW_MAX_CHARS * 2;
+/**
+ * Appended to a row clipped at `LIVE_ROW_MAX_CHARS`.
+ *
+ * SPELLED HERE RATHER THAN IMPORTED from `agent/reducer.ts`, the rule
+ * `patch.ts:95-103` already states for the identical string: `tools/` keeps no
+ * runtime dependency on the view model for three characters, and
+ * `terminal-output.test.ts` asserts the spellings are equal so the pair cannot
+ * drift silently.
+ */
+export const TRUNCATION_MARK = '...';
+/**
+ * How far back a trailing incomplete escape may start.
+ *
+ * A chunk can split mid-escape, and the next chunk completes it -- so the tail
+ * of an unfinished sequence must survive in the carry rather than being stripped
+ * down to its visible remainder (`\x1b[` would otherwise render as a bare `[`).
+ * The lookback is bounded because an "escape" that has run for 64 characters
+ * without a final byte is not an escape, it is a byte that happened to be 0x1b,
+ * and holding it forever would pin the carry.
+ */
+const MAX_PARTIAL_ESCAPE = 64;
+/** CSI: `\x1b[` params intermediates final. */
+const CSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+/** OSC: `\x1b]` ... terminated by BEL or ST. */
+const OSC = /\x1b\][\s\S]*?(?:\x07|\x1b\\)/g;
+/** The two-byte forms: `\x1b` followed by one character. */
+const ESC_PAIR = /\x1b[\s\S]/g;
+/** C1, plus every C0 control except `\t` `\n` `\r`. */
+const CONTROLS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+/**
+ * Remove every escape sequence and control byte except `\t` `\n` `\r`.
+ *
+ * Exported for the tests, and used by `toDisplayRow` as the second line of
+ * defence over a carry that ends mid-escape.
+ */
+export function stripAnsi(text) {
+    return text.replace(CSI, '').replace(OSC, '').replace(ESC_PAIR, '').replace(CONTROLS, '');
+}
+/**
+ * Index at which a trailing INCOMPLETE escape begins, or `-1`.
+ *
+ * Only the last `\x1b` can be incomplete: anything before it is either a
+ * complete sequence (the regexes above consume it) or a stray byte the control
+ * strip removes.
+ */
+function partialEscapeStart(text) {
+    const at = text.lastIndexOf('\x1b');
+    if (at === -1 || text.length - at > MAX_PARTIAL_ESCAPE)
+        return -1;
+    const rest = text.slice(at);
+    // A lone ESC at the very end: the next chunk decides what it is.
+    if (rest.length === 1)
+        return at;
+    // An opened CSI/OSC is incomplete exactly when its own regex does not match
+    // from here -- `\x1b[1;3` has no final byte yet, `\x1b]0;title` no terminator.
+    if (rest[1] === '[')
+        return /^\x1b\[[0-?]*[ -/]*[@-~]/.test(rest) ? -1 : at;
+    if (rest[1] === ']')
+        return /^\x1b\][\s\S]*?(?:\x07|\x1b\\)/.test(rest) ? -1 : at;
+    // Any other two-byte form is already complete.
+    return -1;
+}
+/**
+ * Apply `\r` as the LINE REWRITE it is (§3.2 step 4 / D-33).
+ *
+ * A piece containing `\r` is a sequence of overwrites, so the later segment
+ * replaces the earlier one's PREFIX and anything the earlier one had beyond it
+ * survives -- which is what a real terminal shows, and what keeps R-6's classic
+ * `\r`-only tooling from losing content. A thousand progress-bar rewrites
+ * collapse to one row holding the final state.
+ */
+export function applyCarriageReturns(piece) {
+    if (piece.indexOf('\r') === -1)
+        return piece;
+    return piece.split('\r').reduce((acc, s) => s + acc.slice(s.length), '');
+}
+/** Expand tabs to the next multiple of `TAB_WIDTH`. */
+export function expandTabs(row) {
+    if (row.indexOf('\t') === -1)
+        return row;
+    let out = '';
+    for (let i = 0; i < row.length; i += 1) {
+        const ch = row[i];
+        if (ch === '\t')
+            out += ' '.repeat(TAB_WIDTH - (out.length % TAB_WIDTH));
+        else
+            out += ch;
+    }
+    return out;
+}
+/** Clip a row at `LIVE_ROW_MAX_CHARS`, marking the cut. */
+export function clipRow(row) {
+    return row.length <= LIVE_ROW_MAX_CHARS
+        ? row
+        : `${row.slice(0, LIVE_ROW_MAX_CHARS)}${TRUNCATION_MARK}`;
+}
+/**
+ * The carry as a RENDERED row: the held-back incomplete escape removed, then
+ * stripped and clipped.
+ *
+ * THE PARTIAL MUST BE CUT OFF, NOT STRIPPED (AC-24). `stripAnsi` alone is not
+ * enough and fails in the visible direction: its two-byte rule consumes the
+ * `\x1b[` of an unfinished CSI and leaves the PARAMETERS behind, so a chunk that
+ * split inside `\x1b[31m` renders as `red 3`. The bytes are held for the next
+ * chunk to complete; until then they are not text.
+ */
+export function toDisplayRow(carry) {
+    const at = partialEscapeStart(carry);
+    return clipRow(stripAnsi(at === -1 ? carry : carry.slice(0, at)));
+}
+/**
+ * Tab expansion is column arithmetic, so it cannot be done after the clip -- but
+ * it also need not run over four megabytes to decide the first 200 columns.
+ * Every character occupies at least one column, so a `CARRY_MAX_CHARS` prefix
+ * covers every column the clip can keep.
+ */
+function expandTabsForDisplay(piece) {
+    return piece.length <= CARRY_MAX_CHARS
+        ? expandTabs(piece)
+        : expandTabs(piece.slice(0, CARRY_MAX_CHARS));
+}
+/**
+ * Turn a raw chunk into complete rows plus the in-progress line.
+ *
+ * The order of the steps IS the specification (§3.2), and step 4's "every piece,
+ * THE INCOMPLETE TAIL INCLUDED" is the whole of P0-1: a progress bar emits no
+ * `\n` for its entire run, so a rule that collapsed only completed lines would
+ * never run for npm, pip, curl, docker or any other `\r` writer -- the tail
+ * would stay empty, `showLive` false, and the card the single `running` row this
+ * round exists to replace.
+ */
+export function sanitizeChunk(carry, chunk) {
+    const text = (typeof carry === 'string' ? carry : '') + (typeof chunk === 'string' ? chunk : '');
+    if (text.length === 0)
+        return { rows: [], carry: '' };
+    // 1-2. Concatenate and strip, holding back an escape the next chunk finishes.
+    const partialAt = partialEscapeStart(text);
+    const held = partialAt === -1 ? '' : text.slice(partialAt);
+    const clean = stripAnsi(partialAt === -1 ? text : text.slice(0, partialAt));
+    // 3. Split: the first n-1 pieces are complete rows, the last is the tail.
+    const pieces = clean.split('\n');
+    const rows = [];
+    for (let i = 0; i < pieces.length - 1; i += 1) {
+        // 4-6. Collapse, expand, clip.
+        rows.push(clipRow(expandTabsForDisplay(applyCarriageReturns(pieces[i]))));
+    }
+    const rawTail = applyCarriageReturns(pieces[pieces.length - 1]);
+    const tail = expandTabsForDisplay(rawTail);
+    // 7. Bound the carry. The held escape survives the flush: it belongs to the
+    // NEXT row, and dropping it here would corrupt the sequence it opened.
+    //
+    // BOTH LENGTHS ARE TESTED, and testing only the expanded one is the bug:
+    // `expandTabsForDisplay` truncates its input at `CARRY_MAX_CHARS`, so a
+    // megabyte-long line would sit at exactly the bound forever and never flush.
+    if (rawTail.length > CARRY_MAX_CHARS || tail.length > CARRY_MAX_CHARS) {
+        rows.push(clipRow(tail));
+        return { rows, carry: held };
+    }
+    return { rows, carry: tail + held };
+}

package/dist/tools/tool-output-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The CLI-local side channel a running tool's output travels on
+ * (agent-activity-presentation-live L1 / §3.1.1).
+ *
+ * It mirrors `file-change-store.ts` in shape and in its documented reasoning,
+ * with ONE deliberate difference: it is PEEK-AND-CLEAR, not take-once, because a
+ * running command is read many times and consumed once.
+ *
+ * Four properties, each load-bearing, each with the failure it prevents:
+ *
+ *  - **Owner-scoped.** The key is `${owner}:${toolCallId}`, for D-13's reason
+ *    unchanged: only `'lead'` is written this round, but subagents build their
+ *    tools from the same factory, and a child's tool-call id must never be able
+ *    to paint a lead's card.
+ *  - **Sanitised on write.** `append` calls `sanitizeChunk` BEFORE storing, so
+ *    the store's contract is "terminal-safe rows" and no consumer can forget.
+ *  - **Bounded twice.** `LIVE_TAIL_ROWS` per call and `TOOL_OUTPUT_STORE_CAP`
+ *    calls. A command emitting 400 MB to stdout costs a fixed number of retained
+ *    rows: the per-call bound is what makes the DISPLAY bounded, the cap is what
+ *    makes a session that never settles a call bounded.
+ *  - **Cleared at settle, not at read.** The authoritative result arrives with
+ *    `tool_execution_end`; from that instant the tail is superseded and must be
+ *    released. Clearing there keeps the store's size a function of CONCURRENT
+ *    calls rather than of total calls.
+ */
+/**
+ * ROWS retained per tool call.
+ *
+ * THIS AND THE CAP BELOW ARE DELIBERATELY DIFFERENT NUMBERS (P2-8). They bound
+ * unrelated things -- rows inside one call, and calls inside one session -- and
+ * a shared literal is how a later edit collapses two bounds into one.
+ */
+export declare const LIVE_TAIL_ROWS = 8;
+/** CONCURRENT CALLS retained before the oldest is evicted. */
+export declare const TOOL_OUTPUT_STORE_CAP = 16;
+/**
+ * Silence after which the card stops claiming progress and says so (§3.3.4).
+ *
+ * It lives here rather than in `ToolCard` because it is the STORE's notion of
+ * "quiet": the card reads it so there is no second copy to drift.
+ */
+export declare const STALL_AFTER_MS = 10000;
+export interface ToolOutputStore {
+    /**
+     * Append a raw chunk. Sanitises (§3.2), then returns the display tail: the
+     * last `LIVE_TAIL_ROWS` of `[...completedRows, carry]`, `carry` last and
+     * included only when non-empty.
+     */
+    append(owner: string, toolCallId: string, chunk: string): readonly string[];
+    /** Current tail, or `undefined`. Does NOT remove. Test-facing (P2-2). */
+    peek(owner: string, toolCallId: string): readonly string[] | undefined;
+    /** Drop the entry -- called at `tool_execution_end`. */
+    clear(owner: string, toolCallId: string): void;
+    size(): number;
+}
+/**
+ * What the controller's fourth CLI-local emitter carries (§3.1.3).
+ *
+ * `rows` IS THE WHOLE TAIL, not an increment, and that is what lets
+ * `mergeDeltas` keep only the last one per `toolCallId` (D-30). It is frozen, so
+ * a listener cannot mutate the array a later listener will see.
+ */
+export interface ToolOutputEvent {
+    toolCallId: string;
+    rows: readonly string[];
+}
+export type ToolOutputListener = (event: ToolOutputEvent) => void;
+export declare function createToolOutputStore(cap?: number): ToolOutputStore;

package/dist/tools/tool-output-store.js

@@ -0,0 +1,102 @@
+/**
+ * The CLI-local side channel a running tool's output travels on
+ * (agent-activity-presentation-live L1 / §3.1.1).
+ *
+ * It mirrors `file-change-store.ts` in shape and in its documented reasoning,
+ * with ONE deliberate difference: it is PEEK-AND-CLEAR, not take-once, because a
+ * running command is read many times and consumed once.
+ *
+ * Four properties, each load-bearing, each with the failure it prevents:
+ *
+ *  - **Owner-scoped.** The key is `${owner}:${toolCallId}`, for D-13's reason
+ *    unchanged: only `'lead'` is written this round, but subagents build their
+ *    tools from the same factory, and a child's tool-call id must never be able
+ *    to paint a lead's card.
+ *  - **Sanitised on write.** `append` calls `sanitizeChunk` BEFORE storing, so
+ *    the store's contract is "terminal-safe rows" and no consumer can forget.
+ *  - **Bounded twice.** `LIVE_TAIL_ROWS` per call and `TOOL_OUTPUT_STORE_CAP`
+ *    calls. A command emitting 400 MB to stdout costs a fixed number of retained
+ *    rows: the per-call bound is what makes the DISPLAY bounded, the cap is what
+ *    makes a session that never settles a call bounded.
+ *  - **Cleared at settle, not at read.** The authoritative result arrives with
+ *    `tool_execution_end`; from that instant the tail is superseded and must be
+ *    released. Clearing there keeps the store's size a function of CONCURRENT
+ *    calls rather than of total calls.
+ */
+import { sanitizeChunk, toDisplayRow } from './terminal-output.js';
+/**
+ * ROWS retained per tool call.
+ *
+ * THIS AND THE CAP BELOW ARE DELIBERATELY DIFFERENT NUMBERS (P2-8). They bound
+ * unrelated things -- rows inside one call, and calls inside one session -- and
+ * a shared literal is how a later edit collapses two bounds into one.
+ */
+export const LIVE_TAIL_ROWS = 8;
+/** CONCURRENT CALLS retained before the oldest is evicted. */
+export const TOOL_OUTPUT_STORE_CAP = 16;
+/**
+ * Silence after which the card stops claiming progress and says so (§3.3.4).
+ *
+ * It lives here rather than in `ToolCard` because it is the STORE's notion of
+ * "quiet": the card reads it so there is no second copy to drift.
+ */
+export const STALL_AFTER_MS = 10_000;
+const EMPTY = Object.freeze([]);
+export function createToolOutputStore(cap = TOOL_OUTPUT_STORE_CAP) {
+    // A `Map` iterates in insertion order, so the first key IS the oldest.
+    const entries = new Map();
+    const limit = Math.max(1, Math.floor(cap));
+    const keyOf = (owner, toolCallId) => `${owner}:${toolCallId}`;
+    /**
+     * The tail a consumer sees.
+     *
+     * THE IN-PROGRESS LINE IS PART OF IT, and that is the display half of P0-1: a
+     * command whose output is one continuously-rewritten line -- every progress
+     * bar there is -- has NO completed rows until it exits, and a tail built from
+     * completed rows alone would be empty for its entire run.
+     */
+    const tailOf = (slot) => {
+        const live = toDisplayRow(slot.carry);
+        const rows = live.length > 0 ? [...slot.rows, live] : [...slot.rows];
+        return Object.freeze(rows.length > LIVE_TAIL_ROWS ? rows.slice(-LIVE_TAIL_ROWS) : rows);
+    };
+    return {
+        append(owner, toolCallId, chunk) {
+            const key = keyOf(owner, toolCallId);
+            const slot = entries.get(key) ?? { rows: [], carry: '' };
+            // Delete first so an append moves the key to the END of the ring rather
+            // than leaving it at its original age: the cap must evict the least
+            // recently WRITTEN call, not the one that started first.
+            entries.delete(key);
+            entries.set(key, slot);
+            const { rows, carry } = sanitizeChunk(slot.carry, chunk);
+            if (rows.length > 0) {
+                slot.rows.push(...rows);
+                if (slot.rows.length > LIVE_TAIL_ROWS) {
+                    slot.rows.splice(0, slot.rows.length - LIVE_TAIL_ROWS);
+                }
+            }
+            slot.carry = carry;
+            while (entries.size > limit) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                entries.delete(oldest.value);
+            }
+            return tailOf(slot);
+        },
+        peek(owner, toolCallId) {
+            const slot = entries.get(keyOf(owner, toolCallId));
+            if (!slot)
+                return undefined;
+            const tail = tailOf(slot);
+            return tail.length > 0 ? tail : EMPTY;
+        },
+        clear(owner, toolCallId) {
+            entries.delete(keyOf(owner, toolCallId));
+        },
+        size() {
+            return entries.size;
+        },
+    };
+}

package/dist/ui/ActivityLine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The live working line (agent-activity-presentation §3.2.2).
+ *
+ * Exactly one row, immediately above the composer, while a run is in flight:
+ *
+ *     * Percolating...
+ *
+ * THE ROW CARRIES THE PHRASE AND NOTHING ELSE, AND THAT IS THE WHOLE OF ITS
+ * DESIGN (D-5 / P1-1). No elapsed clock, no token count, no `esc abort`, at any
+ * width. Every one of those is already on screen while running: the status bar
+ * renders `formatDuration(elapsedMs)` under exactly the `running` condition that
+ * mounts this row and the token cluster at `cols >= 72`, and both composers carry
+ * the abort hint. Duplicated rows are precisely what the v0.4.0 removal of the
+ * status bar's hint cluster was for, and that rule does not distinguish between a
+ * duplicated string and a duplicated number.
+ *
+ * Because there are no clusters there is NO WIDTH LADDER: one row, one
+ * truncating `<Text>`, identical at 200 columns and at 40. `cols` is therefore
+ * not a prop — nothing on the row depends on width, and a prop that changed on
+ * every resize but was never read would be a false dependency on a memo boundary.
+ *
+ * What is left is the one thing the status bar cannot say: THAT THE SILENCE IS
+ * WORK. The bar shows state; this row shows life.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+export interface ActivityLineProps {
+    /** Epoch ms the current run began — the phrase sequence's seed. */
+    startedAt: number;
+    /** `Date.now() - startedAt`, already computed by App's 200 ms ticker. */
+    elapsedMs: number;
+    reducedMotion: boolean;
+    /**
+     * The name of the tool currently in flight, or `undefined`
+     * (agent-activity-presentation-live L4 / D-31).
+     *
+     * `status === 'running'` covers the WHOLE turn, including the minutes the
+     * model is idle and a child process is doing the work. Round 1 chose the
+     * thinking vocabulary deliberately for the gap before the first token, and it
+     * is right for that gap; a UI that says "Pondering" while `npm test` runs is
+     * not calm, it is wrong.
+     */
+    runningTool?: string;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, theme, caps, }: ActivityLineProps): React.ReactElement;

package/dist/ui/ActivityLine.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { pickGlyphs } from './glyphs.js';
+import { pickActivityPhrase } from './activity-phrases.js';
+export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, theme, caps, }) {
+    const glyphs = pickGlyphs(caps);
+    // PURE AND DERIVED FROM `(startedAt, now)`, so the sequence does not need to
+    // keep rotating underneath the tool label: when the tool settles the phrase
+    // resumes at the position the clock implies, with no state anywhere.
+    const phrase = pickActivityPhrase(startedAt, startedAt + elapsedMs, !reducedMotion);
+    // `Running ${name}` rather than a per-tool verb table: a table would be a
+    // SECOND registry of tool names, and `toolGlyph` is already the one place that
+    // knows them. Everything round 1 legislated for this row survives — one row,
+    // no digits, no `esc abort`, no width ladder, ASCII only.
+    const label = runningTool ? `Running ${runningTool}` : `${phrase}${glyphs.ellipsis}`;
+    // The IDENTICAL branch `Transcript.tsx` uses for the assistant role marker, and
+    // it must stay identical: braille dots are both an animation AND a Unicode-only
+    // glyph, so reduced motion and an ASCII terminal fall back to the same marker.
+    const spinner = caps.unicode && !reducedMotion ? _jsx(Spinner, { type: "dots" }) : glyphs.spinnerStill;
+    return (_jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: theme.thinking, children: [' ', spinner, " ", label] }) }));
+}

package/dist/ui/App.d.ts

@@ -8,8 +8,8 @@ import React from 'react';
 import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
 import { type Overlay, type ToastLevel } from '../agent/reducer.js';
+import type { UpdateBridge } from '../update/types.js';
 import { type RenderMode } from './layout/frame.js';
-import { type FrameGeometry } from './layout/regions.js';
 import type { MouseSource } from '../input/stdin-mouse-filter.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
@@ -50,7 +50,14 @@ export interface AppProps {
      *  is off: inline mode, `--no-mouse`, a non-TTY, or a filter that failed to
      *  build (mouse-wheel-region-routing §4.2). */
     mouseSource?: MouseSource;
-    /** Test-only seam (§8.2): frame geometry, bypassing `measureElement`. */
-    geometryOverride?: FrameGeometry;
+    /**
+     * The auto-updater's late-arrival channel (cli-auto-update §3.8).
+     *
+     * A BRIDGE AND NOT THE SERVICE ITSELF, for the reason `confirmBridge` above is
+     * one: the service is built by a DYNAMIC `import()` fired after `render()`, so
+     * it does not exist when this component mounts. Absent under `update.mode:
+     * 'off'`, on a non-TTY, in CI, and in every test that does not exercise it.
+     */
+    updateBridge?: UpdateBridge;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, geometryOverride, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, updateBridge, }: AppProps): React.ReactElement;