@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/exec/events.d.ts

@@ -157,6 +157,55 @@ export interface ExecFastReviewEvent {
     model: string;
     text: string;
 }
+/**
+ * Context compaction (context-auto-compaction §4.6).
+ *
+ * ONE ADDITIVE EVENT TYPE, AND `EXEC_SCHEMA_VERSION` DOES NOT MOVE — the rule
+ * this file's header states in the same words: adding a field or an event type
+ * never bumps it; renaming or removing one does. A consumer that ignores event
+ * types it does not know is unaffected.
+ *
+ * THE SUMMARY TEXT IS DELIBERATELY ABSENT (D-18). It can be tens of thousands of
+ * characters, no wrapper needs it, and the transcript card and the log both have
+ * it. What a wrapper does need is the SHAPE of what happened, which is here.
+ */
+export interface ExecCompactionEvent {
+    type: 'compaction';
+    sessionId: string;
+    turn: number;
+    subtype: 'start' | 'end';
+    trigger: 'pressure' | 'overflow' | 'manual';
+    /** `end` only. */
+    applied?: boolean;
+    /**
+     * `relieved` means the RETAINED turns were clipped and nothing was dropped
+     * (context-auto-compaction-hardening §3.3 / W2).
+     *
+     * A NEW MEMBER OF AN EXISTING UNION, WHICH DOES NOT MOVE `EXEC_SCHEMA_VERSION`
+     * either - the rule this file's header states covers adding, not renaming or
+     * removing. A consumer switching on this field already has to handle a value it
+     * does not know, because `none` and `truncated` were both already possible.
+     */
+    mode?: 'summarized' | 'truncated' | 'relieved' | 'none';
+    reason?: string;
+    messagesBefore?: number;
+    messagesAfter?: number;
+    tokensBefore?: number;
+    tokensAfter?: number;
+    /**
+     * Present only when tail relief fired (§4.5).
+     *
+     * A BOUNDED, ANNOUNCED DATA LOSS INSIDE THE TURNS THE RUN CONTINUES FROM, and
+     * therefore something a wrapper is entitled to see. The clipped bodies
+     * themselves are not on the stream, for the same reason `summary` is not
+     * (D-18).
+     */
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    durationMs?: number;
+}
 export interface ExecRetryEvent {
     type: 'retry';
     sessionId: string;
@@ -202,7 +251,7 @@ export interface ExecResultEvent {
     todos: ExecTodoCounts | null;
     error: ExecErrorInfo | null;
 }
-export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
+export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecCompactionEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
 /** Everything `system/init` needs that the runner cannot derive for itself. */
 export interface ExecInitParams {
     sessionId: string;

package/dist/exec/runner.js

@@ -121,6 +121,48 @@ export class ExecRunner {
         });
         if (fast)
             this.unsubscribers.push(fast);
+        // Context compaction (context-auto-compaction §4.6). Usage is folded into the
+        // run's totals for the reason the team and fast branches above give: a
+        // summarization is real spend, and `result.usage` is the only cost readout a
+        // wrapper gets.
+        const compaction = controller.subscribeCompaction?.((event) => {
+            if (event.type === 'usage') {
+                this.usage.inputTokens += event.usage.inputTokens;
+                this.usage.outputTokens += event.usage.outputTokens;
+                return;
+            }
+            if (event.type === 'compaction_start') {
+                this.emit({
+                    type: 'compaction',
+                    sessionId: this.sessionId,
+                    turn: this.turns,
+                    subtype: 'start',
+                    trigger: event.trigger,
+                });
+                return;
+            }
+            if (event.type !== 'compaction_end')
+                return;
+            const r = event.record;
+            this.emit({
+                type: 'compaction',
+                sessionId: this.sessionId,
+                turn: this.turns,
+                subtype: 'end',
+                trigger: r.trigger,
+                applied: r.applied,
+                mode: r.mode,
+                ...(r.reason !== undefined ? { reason: r.reason } : {}),
+                messagesBefore: r.messagesBefore,
+                messagesAfter: r.messagesAfter,
+                tokensBefore: r.tokensBefore,
+                tokensAfter: r.tokensAfter,
+                ...(r.tailRelief ? { tailRelief: r.tailRelief } : {}),
+                durationMs: r.durationMs,
+            });
+        });
+        if (compaction)
+            this.unsubscribers.push(compaction);
         this.installTerminator();
     }
     /**

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/mouse-events.d.ts

@@ -15,8 +15,10 @@
  * module exists so `stdin-mouse-filter.ts` can remove every byte of every
  * report before Ink ever sees the chunk (invariant I-1).
  *
- * Non-wheel reports (press / release / drag) are recognized and DISCARDED
- * rather than passed through, for the same reason.
+ * Every mouse report is CONSUMED here whatever it turns out to be; what changed
+ * with tui-selection-and-scroll-follow is that press / drag / release are now
+ * EMITTED as well as consumed, so `SelectionController` can build a selection
+ * out of them (§4.4.2). They were previously recognized and thrown away.
  */
 export interface WheelEvent {
     readonly kind: 'wheel';
@@ -29,14 +31,33 @@ export interface WheelEvent {
     readonly alt: boolean;
     readonly ctrl: boolean;
 }
+export interface ButtonEvent {
+    readonly kind: 'press' | 'drag' | 'release';
+    /** 0 = left, 1 = middle, 2 = right. Never 3 — see `decodeReport`. */
+    readonly button: 0 | 1 | 2;
+    /** 1-based terminal column, as reported. */
+    readonly x: number;
+    /** 1-based terminal row, as reported. */
+    readonly y: number;
+    readonly shift: boolean;
+    readonly alt: boolean;
+    readonly ctrl: boolean;
+}
+export type MouseEvent = WheelEvent | ButtonEvent;
 export interface MouseSplit {
-    /** Wheel events, in arrival order. Non-wheel reports are dropped, not returned. */
-    readonly events: WheelEvent[];
+    /** Mouse events, in arrival order. Unrecognized reports are dropped, not returned. */
+    readonly events: MouseEvent[];
     /** Everything that was not a mouse report — forward this to Ink verbatim. */
     readonly text: string;
     /** Trailing strict prefix of a possible report; feed it back in with the next chunk. */
     readonly pending: string;
 }
+/**
+ * Which wire encoding a report arrived in. It is a PARAMETER rather than a
+ * remembered rule because the rule it expresses is invariant I-11 and the cost
+ * of forgetting it is a permanently frozen viewport (see `decodeReport`).
+ */
+export type MouseEncoding = 'sgr' | 'x10';
 /**
  * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
  * forever must never be able to wedge input: past this length the tail is
@@ -51,11 +72,16 @@ export declare const MAX_PENDING_MOUSE_CHARS = 32;
  */
 export declare function isMousePrefix(s: string): boolean;
 /**
- * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * Split a decoded stdin chunk into mouse events, passthrough text, and a
  * trailing prefix to carry into the next chunk.
  *
  * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
  * split writes mid-sequence, and a report torn across two chunks would
  * otherwise leak its tail into the composer (R-6).
+ *
+ * ONE CHANNEL, NOT TWO (§4.4.2). Widening this list to carry buttons alongside
+ * wheel notches is what keeps ARRIVAL ORDER intact between them; a second
+ * channel would let a press overtake the notch that preceded it, and the
+ * selection would then be anchored against rows that had already scrolled.
  */
 export declare function splitMouseEvents(buffer: string): MouseSplit;

package/dist/input/mouse-events.js

@@ -15,8 +15,10 @@
  * module exists so `stdin-mouse-filter.ts` can remove every byte of every
  * report before Ink ever sees the chunk (invariant I-1).
  *
- * Non-wheel reports (press / release / drag) are recognized and DISCARDED
- * rather than passed through, for the same reason.
+ * Every mouse report is CONSUMED here whatever it turns out to be; what changed
+ * with tui-selection-and-scroll-follow is that press / drag / release are now
+ * EMITTED as well as consumed, so `SelectionController` can build a selection
+ * out of them (§4.4.2). They were previously recognized and thrown away.
  */
 /**
  * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
@@ -38,34 +40,80 @@ const SGR_PREFIX = /^\x1b\[<[\d;]*$/;
 export function isMousePrefix(s) {
     return /^\x1B(\[(<[\d;]*|M[\s\S]{0,2})?)?$/.test(s);
 }
+function modifiers(b) {
+    return { shift: (b & 4) !== 0, alt: (b & 8) !== 0, ctrl: (b & 16) !== 0 };
+}
 /**
- * Decode an SGR button byte into a wheel event, or `null` when the report is
- * not a wheel notch we act on.
+ * Decode one report, or `null` when it is a report we consume without acting on.
  *
  * THE ORDER OF THESE TESTS IS THE SPECIFICATION, not a presentation choice.
  * Button 66 (wheel-left) has `b & 1 === 0` and would decode as `'up'`, so the
- * horizontal test has to precede the direction decode.
+ * horizontal test has to precede the direction decode; and `b & 32` (motion) has
+ * to precede the `final` test, because a drag is reported with `M` exactly as a
+ * press is.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * I-11 — BUTTON EVENTS COME FROM THE SGR PATH ONLY. X10 stays wheel-only, which
+ * is exactly the contract it has today.
+ *
+ * `matchX10` reconstructs a legacy report and hard-codes `final = 'M'`, because
+ * X10 HAS NO SEPARATE RELEASE FORM AT ALL — it encodes a release as button 3 of
+ * a press. Fed through the table below, an X10 release would become a `press`
+ * that is never followed by a `release`, whose `button` is 3 while the type says
+ * `0 | 1 | 2`, and whose consequence is a `hold` that is set and never cleared:
+ * content anchoring never lets go, the resume timer's third condition never
+ * passes, and the transcript is frozen for the rest of the session with nothing
+ * raised anywhere.
+ *
+ * This costs nothing real (D-16): we never REQUEST X10 — `?1006h` is over a
+ * decade old and every terminal that implements `?1000` implements it — and a
+ * terminal that ignored the SGR request also has no usable drag coordinates past
+ * column 223 (R-2). X10 exists in this parser only so a stray report cannot
+ * reach the user's draft.
+ * ═══════════════════════════════════════════════════════════════════════════
  */
-function decodeWheel(b, x, y, final) {
-    // 1. Not a wheel report at all (press / release / drag) — consume, emit nothing.
-    if ((b & 64) === 0)
-        return null;
-    // 2. Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
-    if ((b & 3) >= 2)
-        return null;
-    // 3. Wheel buttons are press-only; a terminal that ever sent a release for one
-    //    must not produce a second step for the same physical notch.
-    if (final !== 'M')
+function decodeReport(b, x, y, final, encoding) {
+    // 1. Wheel. Buttons 64-67 in both encodings.
+    if ((b & 64) !== 0) {
+        // Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
+        if ((b & 3) >= 2)
+            return null;
+        // Wheel buttons are press-only; a terminal that ever sent a release for one
+        // must not produce a second step for the same physical notch.
+        if (final !== 'M')
+            return null;
+        return { kind: 'wheel', dir: (b & 1) === 1 ? 'down' : 'up', x, y, ...modifiers(b) };
+    }
+    if (encoding !== 'sgr')
+        return null; // I-11
+    // 2. Motion while a button is held (`?1002h`). `3` is "no button", which
+    //    `?1002` should never send and `?1003` sends constantly — dropping it is
+    //    what keeps an any-event terminal from painting a selection with no button
+    //    down at all.
+    if ((b & 32) !== 0) {
+        const button = b & 3;
+        if (button === 3)
+            return null;
+        return { kind: 'drag', button: button, x, y, ...modifiers(b) };
+    }
+    // 3. Release. In SGR the final byte carries the transition, so this is
+    //    unambiguous — unlike X10, which is why step 1's guard exists.
+    //
+    //    A release whose button field reads `3` is a terminal saying "some button
+    //    came up" without naming it. It is mapped to button 0 rather than dropped:
+    //    the ONE thing a release must always do is let go of `hold`, and dropping
+    //    it would leave the viewport frozen — the exact failure I-11 is about. A
+    //    spurious button-0 release is harmless, because a selection can only exist
+    //    if button 0 was pressed in the first place.
+    if (final === 'm') {
+        const button = b & 3;
+        return { kind: 'release', button: (button === 3 ? 0 : button), x, y, ...modifiers(b) };
+    }
+    // 4. Press.
+    const button = b & 3;
+    if (button === 3)
         return null;
-    return {
-        kind: 'wheel',
-        dir: (b & 1) === 1 ? 'down' : 'up',
-        x,
-        y,
-        shift: (b & 4) !== 0,
-        alt: (b & 8) !== 0,
-        ctrl: (b & 16) !== 0,
-    };
+    return { kind: 'press', button: button, x, y, ...modifiers(b) };
 }
 /**
  * X10 legacy reports (`\x1b[M` + three chars, each `code - 32`).
@@ -84,7 +132,13 @@ function matchX10(s) {
     if (codes.some((c) => c < 32 || c > 255))
         return { kind: 'complete', length: 6, event: null };
     const [b, x, y] = codes;
-    return { kind: 'complete', length: 6, event: decodeWheel(b - 32, x - 32, y - 32, 'M') };
+    return {
+        kind: 'complete',
+        length: 6,
+        // `'x10'` is what makes I-11 a property of the code rather than of somebody's
+        // memory: this encoding yields wheel events or nothing, ever.
+        event: decodeReport(b - 32, x - 32, y - 32, 'M', 'x10'),
+    };
 }
 /** Classify the escape sequence starting at `s[0] === ESC`. */
 function matchReport(s) {
@@ -100,7 +154,7 @@ function matchReport(s) {
             const b = Number(m[1]);
             const x = Number(m[2]);
             const y = Number(m[3]);
-            return { kind: 'complete', length: m[0].length, event: decodeWheel(b, x, y, m[4]) };
+            return { kind: 'complete', length: m[0].length, event: decodeReport(b, x, y, m[4], 'sgr') };
         }
         return SGR_PREFIX.test(s) ? { kind: 'partial' } : { kind: 'none' };
     }
@@ -109,12 +163,17 @@ function matchReport(s) {
     return { kind: 'none' };
 }
 /**
- * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * Split a decoded stdin chunk into mouse events, passthrough text, and a
  * trailing prefix to carry into the next chunk.
  *
  * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
  * split writes mid-sequence, and a report torn across two chunks would
  * otherwise leak its tail into the composer (R-6).
+ *
+ * ONE CHANNEL, NOT TWO (§4.4.2). Widening this list to carry buttons alongside
+ * wheel notches is what keeps ARRIVAL ORDER intact between them; a second
+ * channel would let a press overtake the notch that preceded it, and the
+ * selection would then be anchored against rows that had already scrolled.
  */
 export function splitMouseEvents(buffer) {
     const events = [];

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, '');
+}