@aragon-agent/cli 0.5.10 → 0.5.12

package/dist/ui/frame-differ.js

@@ -0,0 +1,230 @@
+/**
+ * Frame differ — F1 of tui-input-flicker-fix (§3.2).
+ *
+ * Ink 5.2.1 has exactly one repaint strategy: on every commit it serialises the
+ * WHOLE frame and hands it to `log-update`, which writes
+ * `eraseLines(previousLineCount) + frame` in a single `stdout.write`
+ * (`ink/build/log-update.js:17`). `ansiEscapes.eraseLines` walks BOTTOM-UP, so
+ * the composer — the last row of the frame — is erased near the start of every
+ * repaint and rewritten at the very end of it. During a run that happens 15–30
+ * times a second with the composer's bytes unchanged, and the user sees the
+ * bottom of their screen flicker while they type (§2 R1/R2).
+ *
+ * This module recognises that write shape, diffs the new frame against the
+ * previous one line by line, and emits only the rows that actually changed, each
+ * addressed absolutely. It is PURE: no I/O, no Node globals, no event emitter —
+ * `stdout-frame-writer.ts` is what binds it to a real stream. That is what keeps
+ * it unit-testable with plain string literals and no TTY.
+ *
+ * THREE INVARIANTS LIVE HERE AND EACH ONE FAILS SILENTLY IF DROPPED:
+ *
+ *  - I-4 · An emitted line is `CUP · SGR0 · text · SGR0 · CSI K`, IN THAT ORDER,
+ *    and it never contains `CSI 2K`. Erasing first would blank the row and refill
+ *    it, which is R1's defect at 1/H the scale but on the one row the user is
+ *    watching. Overwriting in place means no cell is ever presentably empty; the
+ *    trailing `CSI K` removes only the residue a longer previous line left, and
+ *    the trailing SGR reset before it stops a BCE terminal painting that residue
+ *    in whatever background colour the line ended inside.
+ *  - I-5 · Every emitted batch ends parked on row `H+1`. Ink's own
+ *    `previousLineCount` is computed from the string IT produced and is
+ *    unaffected by what we actually wrote, so a later pass-through's
+ *    `eraseLines(H+1)` must find the cursor exactly where log-update left it last
+ *    time. Drop this and one fallback shifts the frame up a row for the rest of
+ *    the session.
+ *  - I-6 · Any unrecognised write invalidates the cache. Absolute addressing is
+ *    valid only while nothing else writes to stdout. Full-screen mode already
+ *    forbids that, but "forbidden" is not "impossible", and the failure mode of
+ *    the guard being absent is a permanently misaligned screen while the failure
+ *    mode of it firing spuriously is one extra full repaint.
+ */
+import { MIN_FULLSCREEN_ROWS } from './layout/frame.js';
+// ---------------------------------------------------------------------------
+// Constants — exact, so no call site ever re-derives an escape sequence.
+// ---------------------------------------------------------------------------
+/** Control Sequence Introducer. Spelled out once; nothing below re-escapes it. */
+const CSI = '\x1b[';
+/** Erase the WHOLE line. Ink uses it on every repaint; this module never emits it (I-4). */
+const ERASE_LINE = `${CSI}2K`;
+/** Erase cursor → end of line. This is what an emitted line ends with. */
+const ERASE_TO_EOL = `${CSI}K`;
+const CURSOR_UP_1 = `${CSI}1A`;
+const CURSOR_LEFT = `${CSI}G`;
+const SGR_RESET = `${CSI}0m`;
+/** Erase cursor → end of screen. One sequence instead of H+1 line erases. */
+const ERASE_DOWN = `${CSI}J`;
+/** DEC private mode 2026 — begin/end synchronized update (F2, §3.3). */
+const SYNC_BEGIN = `${CSI}?2026h`;
+const SYNC_END = `${CSI}?2026l`;
+/**
+ * `eraseLines(n)` for any n ≥ 1, anchored at the start of the chunk.
+ *
+ * FALLBACK ONLY (P2-3). Whenever `prev !== null` the differ already knows the
+ * exact prefix it expects — `eraseLinesPrefix(prev.length + 1)` is a
+ * deterministic string — so the hot path is `chunk.startsWith(expected)`:
+ * linear, unambiguous, and it collapses step 7's `erased !== prev.length + 1`
+ * test into the same comparison. This regex is reached only on the first
+ * diffable chunk after a session start or an `invalidate()`, where no
+ * expectation exists yet.
+ */
+const ERASE_PREFIX_RE = /^(?:\x1b\[2K(?:\x1b\[1A)?)+\x1b\[G/;
+function cursorTo(row) {
+    return `${CSI}${row};1H`;
+}
+/**
+ * Rebuild `ansiEscapes.eraseLines(count)` byte for byte.
+ *
+ * Exported for the upgrade tripwire (`frame-differ-ink-shape.test.ts`), which
+ * drives the real `ink/build/log-update.js` and asserts this reconstruction is
+ * byte-equal to what it produced. If a future Ink changes the shape, that test
+ * fails loudly instead of this module silently degrading to pass-through for the
+ * rest of the package's life (K-2).
+ */
+export function eraseLinesPrefix(count) {
+    if (count <= 0)
+        return '';
+    let out = '';
+    for (let i = 0; i < count; i += 1) {
+        out += ERASE_LINE + (i < count - 1 ? CURSOR_UP_1 : '');
+    }
+    return out + CURSOR_LEFT;
+}
+function countErases(prefix) {
+    return prefix.split(ERASE_LINE).length - 1;
+}
+export function createFrameDiffer(options) {
+    /** Last frame, one entry per row. `null` = no cache, next frame is a full repaint. */
+    let prev = null;
+    /**
+     * Whether any chunk has been seen at all.
+     *
+     * The session's FIRST write has `previousLineCount === 0`, so `eraseLines(0)`
+     * is the empty string and the chunk carries no erase prefix (§3.2.1). That is
+     * expected, not a desync, so it must not raise the §5.6 notice on every launch.
+     * After it, every chunk Ink produces carries a prefix, so a prefix-less chunk
+     * from then on really is foreign.
+     */
+    let seenAnyChunk = false;
+    const counters = {
+        framesTotal: 0,
+        framesDiffed: 0,
+        framesFull: 0,
+        linesWritten: 0,
+        bytesWritten: 0,
+        fallbacks: 0,
+    };
+    const invalidate = () => {
+        prev = null;
+    };
+    /**
+     * Write `chunk` verbatim — today's behaviour, and the only failure mode.
+     *
+     * `counted` is false for the two cases the differ inflicts on itself and knows
+     * are harmless (the seed write, degenerate geometry); true means a foreign
+     * write desynced absolute addressing, which is what `fallbacks` reports.
+     */
+    const passThrough = (counted) => {
+        invalidate();
+        if (counted) {
+            counters.fallbacks += 1;
+            if (counters.fallbacks === 1)
+                options.onFirstFallback?.();
+        }
+        return null;
+    };
+    const wrapSync = (payload) => options.sync ? SYNC_BEGIN + payload + SYNC_END : payload;
+    const emit = (payload, lines, addressed, full) => {
+        prev = lines;
+        counters.framesTotal += 1;
+        if (full)
+            counters.framesFull += 1;
+        else
+            counters.framesDiffed += 1;
+        counters.linesWritten += addressed;
+        counters.bytesWritten += payload.length;
+        return payload;
+    };
+    /** `undefined` ⇒ the I-9 stand-down: a viewport too small to address safely. */
+    const usableRows = () => {
+        const rows = options.rows();
+        if (rows === undefined || !Number.isFinite(rows))
+            return undefined;
+        return rows < MIN_FULLSCREEN_ROWS ? undefined : rows;
+    };
+    const matchErasePrefix = (chunk) => {
+        if (prev !== null) {
+            const expected = eraseLinesPrefix(prev.length + 1);
+            if (chunk.startsWith(expected))
+                return { prefix: expected, erased: prev.length + 1 };
+        }
+        const m = ERASE_PREFIX_RE.exec(chunk);
+        if (m === null)
+            return null;
+        return { prefix: m[0], erased: countErases(m[0]) };
+    };
+    /**
+     * Full repaint — the first diffable frame of a session, every invalidation
+     * (including the resize invalidation of I-8), and any line-count change.
+     *
+     * `CSI J` replaces the H+1 individual line erases with one sequence, and the
+     * alternate screen is exactly the region being erased. `\r\n` rather than `\n`
+     * is deliberate: Ink relies on the tty's `ONLCR` post-processing to turn `\n`
+     * into CRLF, and that dependency is invisible until it is not there.
+     *
+     * P0-1's blank-then-paint objection does not apply here and the asymmetry with
+     * the per-line path is deliberate: a full repaint rewrites every row, so there
+     * is no unchanged content that has to survive, and full repaints are rare by
+     * construction — one per session, one per resize, one per invalidation.
+     */
+    const fullRepaint = (lines) => {
+        const payload = cursorTo(1) +
+            SGR_RESET +
+            ERASE_DOWN +
+            lines.join('\r\n') +
+            '\r\n' +
+            cursorTo(lines.length + 1);
+        return emit(wrapSync(payload), lines, lines.length, true);
+    };
+    const diffRepaint = (lines, previous) => {
+        const out = [];
+        for (let i = 0; i < lines.length; i += 1) {
+            // I-4: paint, THEN clear the tail. Never `ERASE_LINE` first.
+            if (lines[i] !== previous[i]) {
+                out.push(cursorTo(i + 1) + SGR_RESET + lines[i] + SGR_RESET + ERASE_TO_EOL);
+            }
+        }
+        // DEFENSIVE ONLY, not a live path (P2-4). `log-update.js:13-15` returns early
+        // on an identical frame, so a chunk that reaches here differs by at least one
+        // line; the only way to observe zero is a cache that disagrees with the
+        // screen, which is the state `invalidate()` exists to prevent.
+        if (out.length === 0)
+            return emit('', lines, 0, false);
+        out.push(cursorTo(lines.length + 1)); // I-5
+        return emit(wrapSync(out.join('')), lines, out.length - 1, false);
+    };
+    const transform = (chunk) => {
+        const firstChunk = !seenAnyChunk;
+        seenAnyChunk = true;
+        const rows = usableRows();
+        if (rows === undefined)
+            return passThrough(false); // I-9
+        const matched = matchErasePrefix(chunk);
+        // A prefix-less chunk is the session's seed write (P1-1) or a foreign one.
+        if (matched === null)
+            return passThrough(!firstChunk);
+        const body = chunk.slice(matched.prefix.length);
+        if (!body.endsWith('\n'))
+            return passThrough(true); // `log.clear()` and friends
+        const lines = body.slice(0, -1).split('\n');
+        if (lines.length + 1 > rows)
+            return passThrough(false); // I-9
+        if (prev === null || prev.length !== lines.length || matched.erased !== prev.length + 1) {
+            return fullRepaint(lines);
+        }
+        return diffRepaint(lines, prev);
+    };
+    return {
+        transform,
+        invalidate,
+        stats: () => ({ ...counters }),
+    };
+}

package/dist/ui/overlays/HelpOverlay.js

@@ -33,7 +33,7 @@ const COMMANDS = [
         'Todo planning: status, switches, the rail, follow-through',
     ],
     ['/tools', 'List active tools'],
-    ['/clear', 'Clear the visible transcript'],
+    ['/clear', 'Clear the visible transcript and the todo panel'],
     ['/reset', 'New conversation'],
     ['/cwd [dir]', 'Show or change the tool working directory'],
     ['/save [file]', 'Save the session to JSON'],

package/dist/ui/stdout-frame-writer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stdout frame writer — the `Proxy` that binds `frame-differ.ts` to a real
+ * stream (tui-input-flicker-fix §3.2 / §5.5).
+ *
+ * Ink offers no hook for "how to write a frame": `Ink#log` is constructed
+ * internally and `log-update` is a private module. It DOES accept a `stdout` in
+ * `render()`'s options, so the whole interposition is one `Proxy` whose only
+ * trapped behaviour is `write` — everything else is the real stream.
+ *
+ * THREE THINGS IN HERE ARE LOAD-BEARING:
+ *
+ *  - The `get` trap MUST bind non-`write` function members to the REAL stream.
+ *    Without the bind, `stdout.on('resize', …)` executes with `this === proxy`,
+ *    and `useTerminalSize` registers and removes its listener against a
+ *    different `_events` object than the one Node emits on — the frame stops
+ *    resizing and nothing reports why.
+ *  - The UNTYPED BOUNDARY LIVES HERE, not in the differ (P1-4). A `Uint8Array`
+ *    chunk, and any `write` whose `encoding` is present and is not UTF-8, is
+ *    passed straight through after `invalidate()`: in both cases the bytes on
+ *    the wire are not the string a differ could reason about, and diffing one
+ *    encoding while writing another is the kind of bug that only shows up on
+ *    someone else's machine.
+ *  - The `'resize'` SUBSCRIPTION (I-8 / P0-2). Ink renders SYNCHRONOUSLY from its
+ *    own `'resize'` handler while the frame's height is still the pre-resize one
+ *    — `useTerminalSize` debounces by 50 ms — so the line count is unchanged
+ *    across that window and the differ's line-count guard cannot see the resize.
+ *    Meanwhile the emulator has re-flowed the alternate screen, so every row the
+ *    differ believes unchanged is a row it will not repaint, for the rest of the
+ *    drag. It goes on the REAL stream, not the `Proxy`, and `dispose()` removes
+ *    it.
+ */
+import type { FrameDiffer, FrameWriterStats } from './frame-differ.js';
+export interface FrameWriterHandle {
+    /** Hand this to `render(…, { stdout })`. */
+    stdout: NodeJS.WriteStream;
+    /** Hand this to `setFrameStatsProvider`. */
+    stats(): FrameWriterStats;
+    /** Removes the `'resize'` subscription of I-8. Idempotent. */
+    dispose(): void;
+}
+export declare function wrapStdoutForFrames(stdout: NodeJS.WriteStream, differ: FrameDiffer): FrameWriterHandle;

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

@@ -0,0 +1,102 @@
+/**
+ * Stdout frame writer — the `Proxy` that binds `frame-differ.ts` to a real
+ * stream (tui-input-flicker-fix §3.2 / §5.5).
+ *
+ * Ink offers no hook for "how to write a frame": `Ink#log` is constructed
+ * internally and `log-update` is a private module. It DOES accept a `stdout` in
+ * `render()`'s options, so the whole interposition is one `Proxy` whose only
+ * trapped behaviour is `write` — everything else is the real stream.
+ *
+ * THREE THINGS IN HERE ARE LOAD-BEARING:
+ *
+ *  - The `get` trap MUST bind non-`write` function members to the REAL stream.
+ *    Without the bind, `stdout.on('resize', …)` executes with `this === proxy`,
+ *    and `useTerminalSize` registers and removes its listener against a
+ *    different `_events` object than the one Node emits on — the frame stops
+ *    resizing and nothing reports why.
+ *  - The UNTYPED BOUNDARY LIVES HERE, not in the differ (P1-4). A `Uint8Array`
+ *    chunk, and any `write` whose `encoding` is present and is not UTF-8, is
+ *    passed straight through after `invalidate()`: in both cases the bytes on
+ *    the wire are not the string a differ could reason about, and diffing one
+ *    encoding while writing another is the kind of bug that only shows up on
+ *    someone else's machine.
+ *  - The `'resize'` SUBSCRIPTION (I-8 / P0-2). Ink renders SYNCHRONOUSLY from its
+ *    own `'resize'` handler while the frame's height is still the pre-resize one
+ *    — `useTerminalSize` debounces by 50 ms — so the line count is unchanged
+ *    across that window and the differ's line-count guard cannot see the resize.
+ *    Meanwhile the emulator has re-flowed the alternate screen, so every row the
+ *    differ believes unchanged is a row it will not repaint, for the rest of the
+ *    drag. It goes on the REAL stream, not the `Proxy`, and `dispose()` removes
+ *    it.
+ */
+/** The only encodings for which the chunk string IS the bytes on the wire. */
+function isUtf8Encoding(encoding) {
+    const e = encoding.toLowerCase();
+    return e === 'utf8' || e === 'utf-8';
+}
+export function wrapStdoutForFrames(stdout, differ) {
+    const bound = new Map();
+    const writeReal = (chunk, encoding, cb) => {
+        if (encoding !== undefined)
+            return stdout.write(chunk, encoding, cb);
+        return stdout.write(chunk, cb);
+    };
+    /**
+     * All three Node overloads: `write(chunk)`, `write(chunk, cb)`,
+     * `write(chunk, encoding, cb)`.
+     */
+    const write = (chunk, encodingOrCb, maybeCb) => {
+        const encoding = typeof encodingOrCb === 'string' ? encodingOrCb : undefined;
+        const cb = typeof encodingOrCb === 'function'
+            ? encodingOrCb
+            : typeof maybeCb === 'function'
+                ? maybeCb
+                : undefined;
+        // Foreign by construction: Ink never writes Buffers, and a non-UTF-8
+        // encoding means the string is not the bytes (P1-4).
+        if (typeof chunk !== 'string' || (encoding !== undefined && !isUtf8Encoding(encoding))) {
+            differ.invalidate();
+            return writeReal(chunk, encoding, cb);
+        }
+        const out = differ.transform(chunk);
+        if (out === null)
+            return writeReal(chunk, encoding, cb);
+        // Nothing to write, but the callback is still part of the contract — a
+        // skipped `cb` strands whatever was waiting on the drain.
+        if (out.length === 0) {
+            cb?.();
+            return true;
+        }
+        return writeReal(out, encoding, cb);
+    };
+    const onResize = () => differ.invalidate();
+    stdout.on('resize', onResize);
+    let disposed = false;
+    const proxy = new Proxy(stdout, {
+        get(target, prop) {
+            if (prop === 'write')
+                return write;
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== 'function')
+                return value;
+            // Cached so repeated property access does not allocate a new bound
+            // function on a hot path (K-9).
+            let fn = bound.get(prop);
+            if (fn === undefined) {
+                fn = value.bind(target);
+                bound.set(prop, fn);
+            }
+            return fn;
+        },
+    });
+    return {
+        stdout: proxy,
+        stats: () => differ.stats(),
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stdout.off('resize', onResize);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "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",
@@ -52,7 +52,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.10",
+    "@aragon-agent/core": "^0.2.12",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",