@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/fast/wiring.js

@@ -53,6 +53,9 @@ export function offFastStatus() {
         tier: { ok: false, reason: 'disabled' },
         snapshot: {
             live: false,
+            // A tier that never existed was never switched off by its reviewer, so
+            // `false` here is the truth and not a placeholder.
+            selfDisabled: false,
             model: '',
             sameAsMain: false,
             reviews: 0,
@@ -113,6 +116,9 @@ export class FastWiring {
             available: () => this.available(),
             getApiKey: deps.getApiKey,
             emit: (event) => this.emit(event),
+            // The reviewer announces its own self-disable with a `tier_changed`, and
+            // only the wiring can build the snapshot that carries it.
+            snapshot: () => this.snapshot(),
             notify: deps.notify,
         });
     }
@@ -158,7 +164,16 @@ export class FastWiring {
     isEnabled() {
         return this.enabled;
     }
-    /** §3.3's live predicate. THE THIRD TERM IS THE POINT - see the header. */
+    /**
+     * §3.3's live predicate. THE THIRD TERM IS THE POINT - see the header.
+     *
+     * `FastReviewer.isSelfDisabled()` is DELIBERATELY NOT a fourth term. Folding
+     * it in would look tidier and would break something else: `delegationAvailable()`
+     * is `available() && config.fast.delegate === true`, so three consecutive
+     * REVIEW failures would silently switch DELEGATION off as well - turning a
+     * diagnostic signal into a behaviour change for every user. The two facts are
+     * reported separately on `FastSnapshot` instead (`live` / `selfDisabled`).
+     */
     available() {
         return this.registered && this.enabled && this.tier.ok;
     }
@@ -272,6 +287,8 @@ export class FastWiring {
         const ref = this.tier.ok ? this.tier.ref : null;
         return {
             live: this.available(),
+            // ORTHOGONAL TO `live`, never derivable from it (see `FastSnapshot`).
+            selfDisabled: this.reviewer.isSelfDisabled(),
             model: ref ? ref.modelId : '',
             sameAsMain: this.tier.ok ? this.tier.sameAsMain : false,
             // THE NUMERATOR, THE DENOMINATOR AND THE FLAG ARE READ IN ONE EXPRESSION,

package/dist/input/limits.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Structural bounds for paste handling (tui-paste-handling D-10 / section 8).
+ *
+ * THESE ARE STRUCTURAL, NOT POLICY. The package convention recorded in
+ * `.claude-index/index.md` is that `limits.ts` carries the numbers an
+ * implementation needs to stay bounded, while `config/schema.ts` carries the
+ * preferences a user is allowed to have. The only user-facing key this feature
+ * adds is the boolean `paste`; a tunable collapse threshold is a preference
+ * nobody has asked for, and a kill switch is what a bug report actually needs.
+ *
+ * The two framing constants below are the only bytes that cross from the stdin
+ * filter into the composer, so they are load-bearing in a way a threshold is
+ * not: see `PASTE_OPEN`.
+ */
+/**
+ * Ceiling on ONE paste. Above it the body is dropped and the user is told,
+ * never truncated (D-11): a truncated paste loses data and looks like success.
+ */
+export declare const PASTE_MAX_BYTES: number;
+/** Ceiling on every live payload in one draft, summed. Above it a paste is refused. */
+export declare const PASTE_DRAFT_MAX_BYTES: number;
+/** Ceiling on collapsed blocks in one draft. Above it a paste is refused. */
+export declare const PASTE_MAX_BLOCKS = 32;
+/**
+ * Tier 2's single-line rule: a chunk of at least this many printable characters
+ * with no line break is a paste.
+ *
+ * Safe because coalescing a keyboard burst into 25 characters inside one
+ * event-loop turn needs roughly 1 500 WPM. It is a statement about what a
+ * KEYBOARD can emit, not about what text looks like.
+ */
+export declare const PASTE_MIN_BURST_CHARS = 25;
+/** Tier 2 coalescing window. Ordinary typing never opens it, so never pays it. */
+export declare const PASTE_BURST_MS = 15;
+/**
+ * How long an unterminated Tier 1 body is held before it is force-flushed.
+ *
+ * I-4: an unterminated `\x1b[200~` must never be able to wedge keyboard input,
+ * which is the rule `MAX_PENDING_MOUSE_CHARS` already encodes for mouse reports.
+ */
+export declare const PASTE_ASSEMBLY_MAX_MS = 2000;
+/**
+ * The inline frame the filter writes into the stream Ink reads (D-3 / I-5).
+ *
+ * ON THE SAME STREAM, NOT A SIDE CHANNEL. `wrapper.write(text)` is delivered
+ * asynchronously; a synchronous side-channel emit would apply the paste BEFORE
+ * text that preceded it in the same chunk. Framing preserves order by
+ * construction.
+ *
+ * NUL is the delimiter because no terminal delivers it for any key, and because
+ * `sanitisePaste` strips every NUL out of every payload -- so a payload can
+ * never forge a frame boundary.
+ */
+export declare const PASTE_OPEN = "\0[";
+export declare const PASTE_CLOSE = "\0]";
+/**
+ * The one channel from the stdin filter to `App`'s notice dispatch (P1-3 / I-15).
+ *
+ * The filter is constructed in `cli.tsx` BEFORE `render()`, so it has no
+ * `dispatch`. Its only other outlet is the logger, and a limit that writes only
+ * to a log file is indistinguishable -- from the user's chair -- from a paste
+ * that silently did nothing, which is exactly what D-11 exists to rule out.
+ *
+ * Same late-bound shape as `selectionBridge` / `updateBridge` / `terminalBridge`:
+ * `cli.tsx` creates the object, `App` assigns `notify` on mount and clears it on
+ * unmount, and the filter calls `bridge.notify?.(...)`.
+ */
+export interface PasteBridge {
+    notify: ((level: 'warn' | 'error', text: string) => void) | null;
+}
+/** Human-readable byte size for the refusal toast (`4.1 MB`, `812.0 KB`, `7 B`). */
+export declare function formatPasteSize(bytes: number): string;

package/dist/input/limits.js

@@ -0,0 +1,63 @@
+/**
+ * Structural bounds for paste handling (tui-paste-handling D-10 / section 8).
+ *
+ * THESE ARE STRUCTURAL, NOT POLICY. The package convention recorded in
+ * `.claude-index/index.md` is that `limits.ts` carries the numbers an
+ * implementation needs to stay bounded, while `config/schema.ts` carries the
+ * preferences a user is allowed to have. The only user-facing key this feature
+ * adds is the boolean `paste`; a tunable collapse threshold is a preference
+ * nobody has asked for, and a kill switch is what a bug report actually needs.
+ *
+ * The two framing constants below are the only bytes that cross from the stdin
+ * filter into the composer, so they are load-bearing in a way a threshold is
+ * not: see `PASTE_OPEN`.
+ */
+/**
+ * Ceiling on ONE paste. Above it the body is dropped and the user is told,
+ * never truncated (D-11): a truncated paste loses data and looks like success.
+ */
+export const PASTE_MAX_BYTES = 2 * 1024 * 1024;
+/** Ceiling on every live payload in one draft, summed. Above it a paste is refused. */
+export const PASTE_DRAFT_MAX_BYTES = 8 * 1024 * 1024;
+/** Ceiling on collapsed blocks in one draft. Above it a paste is refused. */
+export const PASTE_MAX_BLOCKS = 32;
+/**
+ * Tier 2's single-line rule: a chunk of at least this many printable characters
+ * with no line break is a paste.
+ *
+ * Safe because coalescing a keyboard burst into 25 characters inside one
+ * event-loop turn needs roughly 1 500 WPM. It is a statement about what a
+ * KEYBOARD can emit, not about what text looks like.
+ */
+export const PASTE_MIN_BURST_CHARS = 25;
+/** Tier 2 coalescing window. Ordinary typing never opens it, so never pays it. */
+export const PASTE_BURST_MS = 15;
+/**
+ * How long an unterminated Tier 1 body is held before it is force-flushed.
+ *
+ * I-4: an unterminated `\x1b[200~` must never be able to wedge keyboard input,
+ * which is the rule `MAX_PENDING_MOUSE_CHARS` already encodes for mouse reports.
+ */
+export const PASTE_ASSEMBLY_MAX_MS = 2_000;
+/**
+ * The inline frame the filter writes into the stream Ink reads (D-3 / I-5).
+ *
+ * ON THE SAME STREAM, NOT A SIDE CHANNEL. `wrapper.write(text)` is delivered
+ * asynchronously; a synchronous side-channel emit would apply the paste BEFORE
+ * text that preceded it in the same chunk. Framing preserves order by
+ * construction.
+ *
+ * NUL is the delimiter because no terminal delivers it for any key, and because
+ * `sanitisePaste` strips every NUL out of every payload -- so a payload can
+ * never forge a frame boundary.
+ */
+export const PASTE_OPEN = '\u0000[';
+export const PASTE_CLOSE = '\u0000]';
+/** Human-readable byte size for the refusal toast (`4.1 MB`, `812.0 KB`, `7 B`). */
+export function formatPasteSize(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    if (bytes >= 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${bytes} B`;
+}

package/dist/input/paste-parse.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Paste recognition primitives (tui-paste-handling section 5.1) -- pure,
+ * stream-free, no timers.
+ *
+ * WHY THIS LIVES BELOW INK. `ink/build/components/App.js:131-138` reads stdin on
+ * `'readable'` and emits each chunk as one `'input'` event;
+ * `parse-keypress.js:145-148` maps the exact string `'\r'` to `name: 'return'`,
+ * which `PromptInput` reads as "send the message". A 15-line paste on a Windows
+ * console routinely arrives as a dozen chunks that are exactly `"\r"`, and each
+ * one SUBMITS THE DRAFT AS IT STOOD. No component-level heuristic can undo a
+ * `key.return` that has already fired, so recognition has to happen on the byte
+ * stream, in front of Ink -- the same lesson `mouse-events.ts` records.
+ *
+ * Two tiers feed one framing (D-4). Tier 1 is bracketed paste and is exact;
+ * Tier 2 is a heuristic on chunk SHAPE for the terminals that ignore
+ * `DECSET 2004`. Both are about what a keyboard can physically emit.
+ */
+/** `DECSET 2004` wraps a paste in these two markers. */
+export declare const PASTE_BEGIN_MARK = "\u001B[200~";
+export declare const PASTE_END_MARK = "\u001B[201~";
+/** The longest tail worth holding back while a marker might still complete. */
+export declare const PASTE_MARK_LENGTH: number;
+/**
+ * True when `s` is a PROPER prefix of either paste marker (never a whole one).
+ *
+ * Both markers are held, in every mode, whether or not THIS process enabled DEC
+ * 2004 (I-16): the user's shell, `tmux` or a wrapper script may have left it on,
+ * and an unconsumed marker is a literal `[200~` typed into the draft -- the
+ * exact failure the feature exists to prevent.
+ */
+export declare function isPastePrefix(s: string): boolean;
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a paste
+ * marker, or 0. Shortest match wins, so only the bytes that could still become a
+ * marker are held back.
+ */
+export declare function trailingPastePrefixLength(text: string): number;
+/**
+ * Tier 2: is this chunk a paste, or keystrokes?
+ *
+ * The PRIMARY rule -- "longer than one character AND contains a line break" --
+ * is exactly the shape defect A needs, so the two coincide: any chunk that could
+ * submit the draft by accident is classified as a paste. A lone `\r` is the
+ * Enter key and stays `'keys'`.
+ *
+ * The SECONDARY rule needs `PASTE_MIN_BURST_CHARS` printable characters in one
+ * chunk. It excludes chunks carrying any C0 byte but TAB, which is what keeps an
+ * arrow-key burst (`\x1b[B\x1b[B...`, and every wheel notch translated by
+ * alternate scroll) out of the paste path.
+ */
+export declare function classifyChunk(text: string, minBurstChars?: number): 'paste' | 'keys';
+/**
+ * Make a payload safe to put in a buffer and draw through `<Text>` (G2).
+ *
+ * 1. CRLF and lone CR both become exactly ONE `\n` -- terminals send CR for a
+ *    newline in pasted text, and a lone LF is dropped by Ink's key parser
+ *    entirely, so both have to be normalised here or a pasted line break either
+ *    submits the message or silently vanishes.
+ * 2. Every C0 byte except `\n` and `\t` is removed. Ink writes `<Text>` children
+ *    to the terminal without escaping anything, so a surviving `\r` overwrites
+ *    the row it is drawn on and a surviving `\x1b` repaints the frame's colours.
+ * 3. DEL and every C1 byte (U+0080..U+009F) go too, and that is NOT padding:
+ *    U+009B is the single-byte CSI and U+0085 is NEL, and a terminal that decodes
+ *    them acts on them exactly as it acts on `\x1b[`. A file pasted out of a
+ *    non-UTF-8 editor walks straight through a "strip C0" rule.
+ * 4. TAB is KEPT. Indentation is content, and it is what the model receives.
+ *
+ * Applied to PAYLOAD ONLY, never to keystrokes, so `Ctrl+A` and Escape keep
+ * working. Non-ASCII text (CJK, emoji) is untouched.
+ */
+export declare function sanitisePaste(raw: string): string;

package/dist/input/paste-parse.js

@@ -0,0 +1,95 @@
+/**
+ * Paste recognition primitives (tui-paste-handling section 5.1) -- pure,
+ * stream-free, no timers.
+ *
+ * WHY THIS LIVES BELOW INK. `ink/build/components/App.js:131-138` reads stdin on
+ * `'readable'` and emits each chunk as one `'input'` event;
+ * `parse-keypress.js:145-148` maps the exact string `'\r'` to `name: 'return'`,
+ * which `PromptInput` reads as "send the message". A 15-line paste on a Windows
+ * console routinely arrives as a dozen chunks that are exactly `"\r"`, and each
+ * one SUBMITS THE DRAFT AS IT STOOD. No component-level heuristic can undo a
+ * `key.return` that has already fired, so recognition has to happen on the byte
+ * stream, in front of Ink -- the same lesson `mouse-events.ts` records.
+ *
+ * Two tiers feed one framing (D-4). Tier 1 is bracketed paste and is exact;
+ * Tier 2 is a heuristic on chunk SHAPE for the terminals that ignore
+ * `DECSET 2004`. Both are about what a keyboard can physically emit.
+ */
+import { PASTE_MIN_BURST_CHARS } from './limits.js';
+/** `DECSET 2004` wraps a paste in these two markers. */
+export const PASTE_BEGIN_MARK = '\x1b[200~';
+export const PASTE_END_MARK = '\x1b[201~';
+/** The longest tail worth holding back while a marker might still complete. */
+export const PASTE_MARK_LENGTH = PASTE_BEGIN_MARK.length;
+/**
+ * True when `s` is a PROPER prefix of either paste marker (never a whole one).
+ *
+ * Both markers are held, in every mode, whether or not THIS process enabled DEC
+ * 2004 (I-16): the user's shell, `tmux` or a wrapper script may have left it on,
+ * and an unconsumed marker is a literal `[200~` typed into the draft -- the
+ * exact failure the feature exists to prevent.
+ */
+export function isPastePrefix(s) {
+    if (s.length === 0 || s.length >= PASTE_MARK_LENGTH)
+        return false;
+    return PASTE_BEGIN_MARK.startsWith(s) || PASTE_END_MARK.startsWith(s);
+}
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a paste
+ * marker, or 0. Shortest match wins, so only the bytes that could still become a
+ * marker are held back.
+ */
+export function trailingPastePrefixLength(text) {
+    const max = Math.min(text.length, PASTE_MARK_LENGTH - 1);
+    for (let k = 1; k <= max; k += 1) {
+        if (isPastePrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}
+/** Any C0 control byte other than TAB -- ESC, BEL, NUL, CR, LF included. */
+const HAS_CONTROL_EXCEPT_TAB = /[\u0000-\u0008\u000A-\u001F]/;
+/**
+ * Tier 2: is this chunk a paste, or keystrokes?
+ *
+ * The PRIMARY rule -- "longer than one character AND contains a line break" --
+ * is exactly the shape defect A needs, so the two coincide: any chunk that could
+ * submit the draft by accident is classified as a paste. A lone `\r` is the
+ * Enter key and stays `'keys'`.
+ *
+ * The SECONDARY rule needs `PASTE_MIN_BURST_CHARS` printable characters in one
+ * chunk. It excludes chunks carrying any C0 byte but TAB, which is what keeps an
+ * arrow-key burst (`\x1b[B\x1b[B...`, and every wheel notch translated by
+ * alternate scroll) out of the paste path.
+ */
+export function classifyChunk(text, minBurstChars = PASTE_MIN_BURST_CHARS) {
+    if (text.length > 1 && /[\r\n]/.test(text))
+        return 'paste';
+    if (text.length >= minBurstChars && !HAS_CONTROL_EXCEPT_TAB.test(text))
+        return 'paste';
+    return 'keys';
+}
+/**
+ * Make a payload safe to put in a buffer and draw through `<Text>` (G2).
+ *
+ * 1. CRLF and lone CR both become exactly ONE `\n` -- terminals send CR for a
+ *    newline in pasted text, and a lone LF is dropped by Ink's key parser
+ *    entirely, so both have to be normalised here or a pasted line break either
+ *    submits the message or silently vanishes.
+ * 2. Every C0 byte except `\n` and `\t` is removed. Ink writes `<Text>` children
+ *    to the terminal without escaping anything, so a surviving `\r` overwrites
+ *    the row it is drawn on and a surviving `\x1b` repaints the frame's colours.
+ * 3. DEL and every C1 byte (U+0080..U+009F) go too, and that is NOT padding:
+ *    U+009B is the single-byte CSI and U+0085 is NEL, and a terminal that decodes
+ *    them acts on them exactly as it acts on `\x1b[`. A file pasted out of a
+ *    non-UTF-8 editor walks straight through a "strip C0" rule.
+ * 4. TAB is KEPT. Indentation is content, and it is what the model receives.
+ *
+ * Applied to PAYLOAD ONLY, never to keystrokes, so `Ctrl+A` and Escape keep
+ * working. Non-ASCII text (CJK, emoji) is untouched.
+ */
+export function sanitisePaste(raw) {
+    return raw
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '');
+}

package/dist/input/stdin-filter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Stdin filter (mouse-wheel-region-routing section 4.2 / 5.2, extended by
+ * tui-paste-handling section 5.1).
+ *
+ * WHY A WRAPPER AND NOT A SECOND LISTENER. Ink 5.2.1 owns stdin in a way that
+ * forbids a second reader: `components/App.js` calls `setEncoding('utf8')`,
+ * `ref()`, `setRawMode(true)`, subscribes to `'readable'` and drains with
+ * `read()`. Attaching our own `'data'` listener to the same `process.stdin`
+ * would switch the stream into flowing mode and RACE Ink's `read()` for chunks
+ * -- some keystrokes would reach Ink, some would not, non-deterministically
+ * (D-3). So the filter REPLACES the stream Ink is given: it reads the real
+ * stdin, strips every mouse report, frames every paste, and writes the
+ * remainder into a `PassThrough` that carries the surface Ink requires.
+ *
+ * ONE CHANNEL, NOT TWO, AND THAT NOW COVERS PASTES AS WELL (D-2 / D-3). A second
+ * chained filter would need a second `PassThrough` and would reopen the ordering
+ * hazard this note closes; a side-channel paste emit would apply the payload
+ * BEFORE text that preceded it in the same chunk, because `wrapper.write` is
+ * asynchronous and a synchronous emit is not. The paste therefore travels
+ * INLINE, wrapped in `PASTE_OPEN` / `PASTE_CLOSE` (I-5).
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h` or `\x1b[?2004h`. Reporting or
+ * bracketed paste enabled while Ink still holds the raw stream does not degrade
+ * the feature -- it types `[<0;12;5M` or `[200~` into the user's message, which
+ * is strictly worse than the bug being fixed.
+ *
+ * THE HANDLE ANSWERS EXACTLY ONE QUESTION: "is a stream wrapped?" (I-11 / D-17).
+ * It stopped being the answer to "is the mouse on?" the moment paste could build
+ * a filter on its own -- `paste` defaults to `true`, so `aragon --no-mouse`
+ * builds one. `cli.tsx` reads its own `mouseOn` / `pasteOn` booleans; this module
+ * is told which features it is running and never derives them.
+ */
+import { type MouseEvent } from './mouse-events.js';
+import { type PasteBridge } from './limits.js';
+export interface MouseSource {
+    /**
+     * Returns an unsubscribe function. Multiple subscribers are allowed -- the
+     * wheel router and (since tui-selection-and-scroll-follow) the selection
+     * controller both take this one channel, and each ignores the kinds it does
+     * not own.
+     *
+     * With `features.mouse` false the channel exists and stays SILENT forever, so
+     * a subscriber written against it does not have to know which features are on.
+     */
+    subscribe(listener: (event: MouseEvent) => void): () => void;
+}
+/**
+ * Which stream-level features this filter is running.
+ *
+ * TOLD, NEVER DERIVED (D-17 / P0-1). With `{ mouse: false, paste: true }` no
+ * `MouseEvent` is ever emitted and `splitMouseEvents` is not called at all: a
+ * `--no-mouse` session never wrote `?1000h`, so no real report can arrive, and
+ * running the parser anyway could only ever EAT pasted bytes that happen to look
+ * like one. With `{ mouse: true, paste: false }` this is byte-for-byte the
+ * v0.6.3 mouse filter.
+ */
+export interface StdinFilterFeatures {
+    /** Parse and strip SGR / X10 mouse reports, and emit `MouseEvent`s. */
+    readonly mouse: boolean;
+    /** Recognise pastes and deliver them framed. */
+    readonly paste: boolean;
+}
+export interface StdinFilter {
+    /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */
+    readonly stdin: NodeJS.ReadStream;
+    readonly source: MouseSource;
+    /** Idempotent. Detaches from the real stdin and clears every timer (I-7). */
+    dispose(): void;
+}
+export declare function createStdinFilter(real: NodeJS.ReadStream, features: StdinFilterFeatures, bridge?: PasteBridge, onWarn?: (reason: string) => void): StdinFilter;
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): a construction failure must
+ * degrade to "the wheel is inert and pastes are keystrokes" -- a supported,
+ * tested rung of the fail-safe ladder -- rather than leaving `?1000h` or `?2004h`
+ * on with no filter in front of Ink. `cli.tsx` derives BOTH `mouseOn` and
+ * `pasteOn` from the returned handle for exactly that reason.
+ */
+export declare function tryCreateStdinFilter(real: NodeJS.ReadStream, features: StdinFilterFeatures, onError?: (reason: string) => void, bridge?: PasteBridge): StdinFilter | null;