@aragon-agent/cli 0.6.14 → 0.6.16

package/dist/config/schema.js

@@ -744,7 +744,7 @@ export const DEFAULT_COMPACTION_CONFIG = {
     warnThreshold: 0.75,
     keepRecentTurns: 4,
     useFastTier: true,
-    onFailure: 'truncate',
+    onFailure: 'stop',
     subagents: true,
     archive: true,
 };
@@ -896,6 +896,7 @@ export const DEFAULT_CONFIG = {
     mouse: true,
     mouseSelect: DEFAULT_MOUSE_SELECT,
     paste: true,
+    keyboardEnhancement: true,
     scrollResumeMs: DEFAULT_SCROLL_RESUME_MS,
     planModeDefault: false,
     planModeMaxAskRounds: DEFAULT_PLAN_MAX_ASK_ROUNDS,

package/dist/exec/events.d.ts

@@ -274,6 +274,14 @@ export interface ExecFastTierEvent {
  * it. What a wrapper does need is the SHAPE of what happened, which is here.
  */
 export interface ExecCompactionEvent {
+    decision?: {
+        occupied: number;
+        contextWindow: number;
+        threshold: number;
+        source: 'usage' | 'estimate';
+        deltaTokens: number;
+    };
+    memoryVersion?: 2;
     type: 'compaction';
     sessionId: string;
     turn: number;

package/dist/exec/index.js

@@ -111,7 +111,7 @@ async function execute(input) {
         now,
     });
     if (plan.saved) {
-        controller.replaceMessages(plan.saved.messages);
+        controller.replaceMessages(plan.saved.messages, plan.saved.compactionIdentity);
         controller.restoreTodos(plan.saved.todos);
     }
     const config = controller.getConfig();
@@ -187,7 +187,7 @@ async function execute(input) {
             outputTokens: stats.usage.outputTokens,
             totalTokens: stats.usage.inputTokens + stats.usage.outputTokens,
         },
-        cost: buildCost(controller, stats.usage),
+        cost: buildCost(controller, stats.usage, stats.compactionBilling),
         model: { provider: config.provider, id: config.model },
         todos: todo ? { total: todo.total, done: todo.doneCount } : null,
         error: stats.errorCode && stats.errorMessage
@@ -253,17 +253,24 @@ async function drive(input, controller, runner) {
 function withPermissionMode(flags, mode) {
     return mode === 'plan' ? { ...flags, plan: true } : flags;
 }
-function buildCost(controller, usage) {
+function buildCost(controller, usage, compaction) {
     const config = controller.getConfig();
-    const known = controller.isPricedModel({
+    const known = !compaction?.pricingUnknown && controller.isPricedModel({
         providerId: config.provider,
         modelId: config.model,
     });
+    const mainUsage = {
+        inputTokens: usage.inputTokens - (compaction?.usage.inputTokens ?? 0),
+        outputTokens: usage.outputTokens - (compaction?.usage.outputTokens ?? 0),
+        cacheReadTokens: (usage.cacheReadTokens ?? 0) - (compaction?.usage.cacheReadTokens ?? 0),
+        cacheWriteTokens: (usage.cacheWriteTokens ?? 0) - (compaction?.usage.cacheWriteTokens ?? 0),
+    };
     // `amount` is `0` when the price is unknown, mirroring the fast tier's rule
     // that a feature which looks free while it is spending money is worse than one
     // that admits it does not know.
     return {
-        amount: known ? computeCost(usage, controller.getModelInfo().cost) : 0,
+        amount: known ? computeCost(mainUsage, controller.getModelInfo().cost) +
+            (compaction?.costUsd ?? 0) : 0,
         currency: 'USD',
         known,
     };
@@ -460,7 +467,7 @@ function persist(plan, controller, turns, usage, cli, at) {
                     modelId: config.model,
                     ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
                 },
-                messages: controller.getMessages(),
+                ...(controller.getSessionSnapshot?.() ?? { messages: controller.getMessages() }),
                 entries: [],
                 todos: controller.getTodoSnapshot?.()?.items ?? [],
             },

package/dist/exec/runner.d.ts

@@ -72,7 +72,13 @@ export interface ExecRunnerOptions {
     /** Turns already spent by earlier invocations of a resumed session. */
     priorTurns?: number;
 }
+export interface ExecCompactionBilling {
+    usage: TokenUsage;
+    costUsd: number;
+    pricingUnknown: boolean;
+}
 export interface ExecRunStats {
+    compactionBilling?: ExecCompactionBilling;
     turns: number;
     usage: TokenUsage;
     lastAssistantText: string;
@@ -93,6 +99,7 @@ export declare class ExecRunner {
     private unsubscribers;
     private turns;
     private readonly usage;
+    private compactionBilling;
     private lastAssistantText;
     private errored;
     private sawTurnEnd;
@@ -143,6 +150,7 @@ export declare class ExecRunner {
      * the two faces cannot drift about what "unfinished" means.
      */
     run(source: ExecPromptSource): Promise<void>;
+    private onCompactionUsage;
     private requestSeq;
     private requestHadError;
     private isRequestCancelled;

package/dist/exec/runner.js

@@ -46,6 +46,7 @@ export class ExecRunner {
     unsubscribers = [];
     turns = 0;
     usage = { inputTokens: 0, outputTokens: 0 };
+    compactionBilling;
     lastAssistantText = '';
     errored = false;
     sawTurnEnd = false;
@@ -175,8 +176,7 @@ export class ExecRunner {
         // wrapper gets.
         const compaction = controller.subscribeCompaction?.((event) => {
             if (event.type === 'usage') {
-                this.usage.inputTokens += event.usage.inputTokens;
-                this.usage.outputTokens += event.usage.outputTokens;
+                this.onCompactionUsage(event);
                 return;
             }
             if (event.type === 'compaction_start') {
@@ -208,6 +208,8 @@ export class ExecRunner {
                 tokensBefore: r.tokensBefore,
                 tokensAfter: r.tokensAfter,
                 ...(r.tailRelief ? { tailRelief: r.tailRelief } : {}),
+                ...(r.decision ? { decision: r.decision } : {}),
+                ...(r.memoryVersion ? { memoryVersion: r.memoryVersion } : {}),
                 durationMs: r.durationMs,
             });
         });
@@ -246,6 +248,9 @@ export class ExecRunner {
         return {
             turns: this.turns,
             usage: { ...this.usage },
+            ...(this.compactionBilling ? { compactionBilling: {
+                    ...this.compactionBilling, usage: { ...this.compactionBilling.usage },
+                } } : {}),
             lastAssistantText: this.lastAssistantText,
             errored: this.errored,
             stopReason: this.stopReason,
@@ -322,6 +327,25 @@ export class ExecRunner {
             }
         }
     }
+    onCompactionUsage(event) {
+        const usage = event.usage;
+        this.usage.inputTokens += usage.inputTokens;
+        this.usage.outputTokens += usage.outputTokens;
+        for (const key of ['cacheReadTokens', 'cacheWriteTokens']) {
+            if (usage[key] !== undefined)
+                this.usage[key] = (this.usage[key] ?? 0) + usage[key];
+        }
+        if (event.costUsd === undefined && event.pricingUnknown === undefined)
+            return;
+        const billing = this.compactionBilling ??= { costUsd: 0, pricingUnknown: false,
+            usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 } };
+        billing.costUsd += event.costUsd ?? 0;
+        billing.pricingUnknown ||= event.pricingUnknown === true;
+        billing.usage.inputTokens += usage.inputTokens;
+        billing.usage.outputTokens += usage.outputTokens;
+        billing.usage.cacheReadTokens += usage.cacheReadTokens ?? 0;
+        billing.usage.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+    }
     requestSeq = 0;
     requestHadError = false;
     isRequestCancelled() {

package/dist/input/csiu-keys.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CSI-u key translation (posix keyboard-enhancement section of the Shift+Enter
+ * newline fix).
+ *
+ * WHY THIS EXISTS. On macOS/Linux the only lever that makes Shift+Enter
+ * distinguishable from Enter is asking the terminal to report modified keys in
+ * the CSI-u encoding: kitty's disambiguate mode (`CSI > 1 u`, pushed and popped
+ * with `CSI < u`) and xterm's `modifyOtherKeys=2` (`CSI > 4 ; 2 m`, reset with
+ * `CSI > 4 m`). iTerm2, kitty, ghostty, WezTerm, foot and Alacritty implement
+ * at least one of the two; a terminal implementing neither ignores both bytes,
+ * which the conhost probe confirmed is a harmless no-op.
+ *
+ * WHAT CHANGES IN THE STREAM -- AND WHAT NEVER DOES. Both modes re-encode only
+ * keys whose legacy encoding is ambiguous: Ctrl/Ctrl+Shift/Ctrl+Alt+letters and
+ * digits, the Enter family, the Escape key (kitty), and Backspace with
+ * modifiers. `modifyOtherKeys` is named for the OTHER keys: arrows, Home/End,
+ * PgUp/PgDn and F-keys keep their standard `\x1b[1;mA` / `\x1b[m~` encodings,
+ * and Shift+printable still types text. So the translator below only ever sees
+ * codepoints below 128 plus a few named control codes; anything else (a kitty
+ * functional-key code from a mode this app never pushes) passes through
+ * untouched, which is exactly the pre-enhancement behaviour.
+ *
+ * THE CONTRACT mirrors `win32-input-mode.ts`: split, translate back to the
+ * legacy bytes, with the modified-Enter family becoming `ENTER_NEWLINE_FRAME`.
+ * Pure: no node/React imports.
+ */
+/** Enable / disable the two CSI-u report modes (posix side). */
+export declare const CSI_U_ENABLE = "\u001B[>1u\u001B[>4;2m";
+export declare const CSI_U_DISABLE = "\u001B[<u\u001B[>4m";
+export interface CsiUKey {
+    /** The full original sequence, for pass-through. */
+    readonly seq: string;
+    /** First parameter's primary number (the key's codepoint). */
+    readonly code: number;
+    /** Optional `:alternate` sub-parameters of the key field (kitty/mok). */
+    readonly alternates: readonly number[];
+    /** Modifier parameter minus one (bit 1 shift, 2 alt, 4 ctrl), or 0. */
+    readonly mods: number;
+}
+export type CsiUSegment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'key';
+    key: CsiUKey;
+};
+/**
+ * Split a chunk into text spans and CSI-u sequences.
+ *
+ * Grammar accepted: `ESC [ <params> u` where params are digits, `;` and `:`
+ * only, and at least one field exists. `\x1b[13;2u` is INCLUDED: with
+ * enhancement on, this module owns every `u`-terminated sequence and applies
+ * the same Enter semantics `enter-sequences.ts` defines.
+ */
+export declare function splitCsiUKeys(text: string): CsiUSegment[];
+/**
+ * Translate one CSI-u sequence to the legacy bytes the same keypress would
+ * have produced without the report modes (Enter family excepted: a modified
+ * Enter becomes the newline frame). Unknown keys pass through unchanged.
+ */
+export declare function translateCsiUKey(key: CsiUKey): string;
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * CSI-u sequence, or 0. Longest match, mirroring the other families.
+ */
+export declare function trailingCsiUPrefixLength(text: string): number;

package/dist/input/csiu-keys.js

@@ -0,0 +1,170 @@
+/**
+ * CSI-u key translation (posix keyboard-enhancement section of the Shift+Enter
+ * newline fix).
+ *
+ * WHY THIS EXISTS. On macOS/Linux the only lever that makes Shift+Enter
+ * distinguishable from Enter is asking the terminal to report modified keys in
+ * the CSI-u encoding: kitty's disambiguate mode (`CSI > 1 u`, pushed and popped
+ * with `CSI < u`) and xterm's `modifyOtherKeys=2` (`CSI > 4 ; 2 m`, reset with
+ * `CSI > 4 m`). iTerm2, kitty, ghostty, WezTerm, foot and Alacritty implement
+ * at least one of the two; a terminal implementing neither ignores both bytes,
+ * which the conhost probe confirmed is a harmless no-op.
+ *
+ * WHAT CHANGES IN THE STREAM -- AND WHAT NEVER DOES. Both modes re-encode only
+ * keys whose legacy encoding is ambiguous: Ctrl/Ctrl+Shift/Ctrl+Alt+letters and
+ * digits, the Enter family, the Escape key (kitty), and Backspace with
+ * modifiers. `modifyOtherKeys` is named for the OTHER keys: arrows, Home/End,
+ * PgUp/PgDn and F-keys keep their standard `\x1b[1;mA` / `\x1b[m~` encodings,
+ * and Shift+printable still types text. So the translator below only ever sees
+ * codepoints below 128 plus a few named control codes; anything else (a kitty
+ * functional-key code from a mode this app never pushes) passes through
+ * untouched, which is exactly the pre-enhancement behaviour.
+ *
+ * THE CONTRACT mirrors `win32-input-mode.ts`: split, translate back to the
+ * legacy bytes, with the modified-Enter family becoming `ENTER_NEWLINE_FRAME`.
+ * Pure: no node/React imports.
+ */
+import { ENTER_NEWLINE_FRAME } from './limits.js';
+/** Enable / disable the two CSI-u report modes (posix side). */
+export const CSI_U_ENABLE = '\x1b[>1u\x1b[>4;2m';
+export const CSI_U_DISABLE = '\x1b[<u\x1b[>4m';
+const isParamChar = (c) => (c >= '0' && c <= '9') || c === ';' || c === ':';
+/**
+ * Split a chunk into text spans and CSI-u sequences.
+ *
+ * Grammar accepted: `ESC [ <params> u` where params are digits, `;` and `:`
+ * only, and at least one field exists. `\x1b[13;2u` is INCLUDED: with
+ * enhancement on, this module owns every `u`-terminated sequence and applies
+ * the same Enter semantics `enter-sequences.ts` defines.
+ */
+export function splitCsiUKeys(text) {
+    const segments = [];
+    let start = 0;
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== '\x1b' || text[index + 1] !== '[') {
+            index += 1;
+            continue;
+        }
+        let end = index + 2;
+        while (end < text.length && isParamChar(text[end]))
+            end += 1;
+        if (end >= text.length || text[end] !== 'u') {
+            index += 1;
+            continue;
+        }
+        const key = parseKey(text.slice(index + 2, end), text.slice(index, end + 1));
+        if (!key) {
+            index += 1;
+            continue;
+        }
+        if (index > start)
+            segments.push({ kind: 'text', text: text.slice(start, index) });
+        segments.push({ kind: 'key', key });
+        index = end + 1;
+        start = index;
+    }
+    if (start < text.length)
+        segments.push({ kind: 'text', text: text.slice(start) });
+    return segments;
+}
+/** Parse the parameter body of a CSI-u sequence, or null when malformed. */
+function parseKey(body, seq) {
+    if (body.length === 0)
+        return null;
+    const fields = body.split(';');
+    const keyParts = fields[0]?.split(':').map(Number) ?? [];
+    if (keyParts.some((n) => !Number.isInteger(n) || n < 0 || n > 0x10ffff))
+        return null;
+    const code = keyParts[0];
+    if (code === undefined)
+        return null;
+    let mods = 0;
+    if (fields.length > 1) {
+        const modParts = fields[1]?.split(':').map(Number) ?? [];
+        if (modParts.some((n) => !Number.isInteger(n) || n < 0 || n > 64))
+            return null;
+        const m = modParts[0] ?? 0;
+        mods = Math.max(0, m - 1);
+    }
+    return { seq, code, alternates: keyParts.slice(1), mods };
+}
+/** Control code for Ctrl+letter (a-z -> 1-26), or the char itself. */
+function ctrlByte(char) {
+    if (char >= 97 && char <= 122)
+        return char - 96;
+    if (char >= 65 && char <= 90)
+        return char - 64;
+    return char;
+}
+/**
+ * Translate one CSI-u sequence to the legacy bytes the same keypress would
+ * have produced without the report modes (Enter family excepted: a modified
+ * Enter becomes the newline frame). Unknown keys pass through unchanged.
+ */
+export function translateCsiUKey(key) {
+    const m = key.mods;
+    const ctrl = (m & 4) !== 0;
+    const alt = (m & 2) !== 0;
+    const shift = (m & 1) !== 0;
+    if (key.code === 13)
+        return m === 0 ? '\r' : ENTER_NEWLINE_FRAME;
+    if (key.code === 27)
+        return alt ? '\x1b\x1b' : '\x1b';
+    if (key.code === 9)
+        return shift ? '\x1b[Z' : '\t';
+    if (key.code === 127) {
+        // POST-normalisation bytes, same rationale as VK_BACK in win32-input-mode.
+        if (alt)
+            return '\x1b\x08';
+        return '\x08';
+    }
+    if (key.code === 32) {
+        // Ctrl+Space is 0x00 in legacy xterm; plain/alt space is the character.
+        if (ctrl)
+            return alt ? '\x1b\x00' : '\x00';
+        return alt ? '\x1b ' : ' ';
+    }
+    if (key.code >= 32 && key.code <= 126) {
+        const char = String.fromCharCode(key.code);
+        if (ctrl) {
+            const code = ctrlByte(key.code);
+            const text = code === key.code ? char : String.fromCharCode(code);
+            return alt ? `\x1b${text}` : text;
+        }
+        if (alt)
+            return `\x1b${char}`;
+        if (shift && key.alternates.length > 0) {
+            const shifted = key.alternates[0];
+            if (shifted !== undefined && shifted > 0)
+                return String.fromCodePoint(shifted);
+        }
+        return char;
+    }
+    // Functional-key codes only appear under modes this app never pushes
+    // (kitty flags 2+); pass them through so behaviour matches the un-enhanced
+    // stream instead of inventing a translation.
+    return key.seq;
+}
+/** True when `s` is a PROPER prefix of some CSI-u sequence. */
+function isCsiUPrefix(s) {
+    if (s.length < 3 || s[0] !== '\x1b' || s[1] !== '[')
+        return false;
+    for (let i = 2; i < s.length; i += 1) {
+        if (!isParamChar(s[i]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * CSI-u sequence, or 0. Longest match, mirroring the other families.
+ */
+export function trailingCsiUPrefixLength(text) {
+    const max = Math.min(text.length, 32);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isCsiUPrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}

package/dist/input/keyboard-enhancement.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Keyboard-enhancement lifecycle (the Shift+Enter newline fix).
+ *
+ * WHY A LIFECYCLE MODULE AND NOT ANOTHER `screen.ts` MODE. The alternate
+ * screen is bound to fullscreen rendering; keyboard enhancement must run in
+ * every interactive session, inline included, because the composer is always
+ * there. It still follows the screen module's discipline: bytes are written
+ * ONLY for a TTY stdout, restore is idempotent, and the caller owns every
+ * decision -- this module is told the resolved capability and never derives
+ * one from config or environment.
+ *
+ * PLATFORM SPLIT, DECIDED BY BYTE-LEVEL PROBES (see
+ * docs/diagnoses/shift-enter-newline-dead-by-default):
+ *
+ * - win32: `?9001h` (win32-input-mode). It works through ConPTY on both
+ *   conhost and Windows Terminal; kitty `CSI > 1 u` is swallowed there (a
+ *   `CSI ? u` query never answers) and modifyOtherKeys is a no-op. Gated on
+ *   the SAME `vtInputSupported` measurement the mouse feature uses: on Node
+ *   < 22.17 / < 24.2 libuv never turns on `ENABLE_VIRTUAL_TERMINAL_INPUT`,
+ *   so the records cannot reach the process and the mode would be a lie.
+ * - everything else: kitty disambiguate (`CSI > 1 u`) plus
+ *   `modifyOtherKeys=2`. iTerm2 / kitty / ghostty / WezTerm / foot implement
+ *   at least one; terminals that implement neither ignore both bytes.
+ */
+export interface KeyboardEnhancementHandle {
+    /** Idempotent; writes the disable bytes exactly once. */
+    restore(): void;
+}
+/** The handle a gated-out session reads: nothing was pushed, nothing unwinds. */
+export declare const NOOP_KEYBOARD_ENHANCEMENT: KeyboardEnhancementHandle;
+/**
+ * Ask the terminal to report modified keys distinctly. The returned handle's
+ * `restore()` hands the keyboard back; wire it into the same convergence
+ * point the screen restore uses so every exit path unwinds both.
+ *
+ * `vtInputSupported` is the measurement `cli.tsx` already resolves for the
+ * mouse gate; on win32 it decides between `?9001h` and nothing at all.
+ */
+export declare function enableKeyboardEnhancement(stdout: NodeJS.WriteStream | undefined, opts: {
+    readonly platform: string;
+    readonly vtInputSupported: boolean;
+}): KeyboardEnhancementHandle;

package/dist/input/keyboard-enhancement.js

@@ -0,0 +1,65 @@
+/**
+ * Keyboard-enhancement lifecycle (the Shift+Enter newline fix).
+ *
+ * WHY A LIFECYCLE MODULE AND NOT ANOTHER `screen.ts` MODE. The alternate
+ * screen is bound to fullscreen rendering; keyboard enhancement must run in
+ * every interactive session, inline included, because the composer is always
+ * there. It still follows the screen module's discipline: bytes are written
+ * ONLY for a TTY stdout, restore is idempotent, and the caller owns every
+ * decision -- this module is told the resolved capability and never derives
+ * one from config or environment.
+ *
+ * PLATFORM SPLIT, DECIDED BY BYTE-LEVEL PROBES (see
+ * docs/diagnoses/shift-enter-newline-dead-by-default):
+ *
+ * - win32: `?9001h` (win32-input-mode). It works through ConPTY on both
+ *   conhost and Windows Terminal; kitty `CSI > 1 u` is swallowed there (a
+ *   `CSI ? u` query never answers) and modifyOtherKeys is a no-op. Gated on
+ *   the SAME `vtInputSupported` measurement the mouse feature uses: on Node
+ *   < 22.17 / < 24.2 libuv never turns on `ENABLE_VIRTUAL_TERMINAL_INPUT`,
+ *   so the records cannot reach the process and the mode would be a lie.
+ * - everything else: kitty disambiguate (`CSI > 1 u`) plus
+ *   `modifyOtherKeys=2`. iTerm2 / kitty / ghostty / WezTerm / foot implement
+ *   at least one; terminals that implement neither ignore both bytes.
+ */
+import { CSI_U_DISABLE, CSI_U_ENABLE, } from './csiu-keys.js';
+import { WIN32_INPUT_DISABLE, WIN32_INPUT_ENABLE } from './win32-input-mode.js';
+const NOOP_HANDLE = { restore() { } };
+/** The handle a gated-out session reads: nothing was pushed, nothing unwinds. */
+export const NOOP_KEYBOARD_ENHANCEMENT = NOOP_HANDLE;
+function safeWrite(stdout, data) {
+    try {
+        stdout.write(data);
+    }
+    catch {
+        // A closed/broken stdout must never crash the exit path.
+    }
+}
+/**
+ * Ask the terminal to report modified keys distinctly. The returned handle's
+ * `restore()` hands the keyboard back; wire it into the same convergence
+ * point the screen restore uses so every exit path unwinds both.
+ *
+ * `vtInputSupported` is the measurement `cli.tsx` already resolves for the
+ * mouse gate; on win32 it decides between `?9001h` and nothing at all.
+ */
+export function enableKeyboardEnhancement(stdout, opts) {
+    if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
+        return NOOP_HANDLE;
+    const enable = opts.platform === 'win32'
+        ? (opts.vtInputSupported ? WIN32_INPUT_ENABLE : '')
+        : CSI_U_ENABLE;
+    if (enable.length === 0)
+        return NOOP_HANDLE;
+    const disable = opts.platform === 'win32' ? WIN32_INPUT_DISABLE : CSI_U_DISABLE;
+    safeWrite(stdout, enable);
+    let restored = false;
+    return {
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            safeWrite(stdout, disable);
+        },
+    };
+}

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

@@ -60,6 +60,15 @@ export interface StdinFilterFeatures {
     readonly mouse: boolean;
     /** Recognise pastes and deliver them framed. */
     readonly paste: boolean;
+    /**
+     * Translate keyboard-enhancement encodings (win32-input-mode records on
+     * Windows, CSI-u sequences from kitty/modifyOtherKeys elsewhere) back to
+     * legacy bytes BEFORE Ink parses them. TOLD, never derived: `cli.tsx`
+     * resolves config, TTY state and `vtInputSupported`, and passes the same
+     * boolean to `enableKeyboardEnhancement`, so the filter only ever
+     * translates for a session whose mode push actually happened.
+     */
+    readonly enhancedKeys?: boolean;
 }
 export interface StdinFilter {
     /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */

package/dist/input/stdin-filter.js

@@ -36,6 +36,8 @@ import { MAX_PENDING_MOUSE_CHARS, splitMouseEvents, isMousePrefix, } from './mou
 import { ENTER_NEWLINE_FRAME, PASTE_ASSEMBLY_MAX_MS, PASTE_BURST_MS, PASTE_CLOSE, PASTE_MAX_BYTES, PASTE_OPEN, formatPasteSize, } from './limits.js';
 import { PASTE_BEGIN_MARK, PASTE_END_MARK, classifyChunk, sanitisePaste, trailingPastePrefixLength, } from './paste-parse.js';
 import { splitEnterSequences, trailingEnterPrefixLength } from './enter-sequences.js';
+import { splitCsiUKeys, trailingCsiUPrefixLength, translateCsiUKey } from './csiu-keys.js';
+import { splitWin32KeySequences, trailingWin32PrefixLength, translateWin32Key, } from './win32-input-mode.js';
 /**
  * How long a possible-prefix tail is held before being flushed as text.
  *
@@ -82,6 +84,7 @@ function trailingMousePrefixLength(text) {
     return 0;
 }
 export function createStdinFilter(real, features, bridge, onWarn) {
+    const enhancedKeys = features.enhancedKeys === true;
     const wrapper = new PassThrough();
     const listeners = new Set();
     let pending = '';
@@ -251,17 +254,50 @@ export function createStdinFilter(real, features, bridge, onWarn) {
         else
             writeInput(split.pending);
     };
+    /**
+     * THE ENHANCED-KEY WALK, OUTSIDE PASTES ONLY. win32-input-mode records are
+     * split first (their bodies are digits/semicolons, so no paste marker or
+     * CSI-u sequence can live inside one), then CSI-u sequences in the
+     * remaining text, and only then the legacy Enter family. Each translated
+     * key terminates a heuristic burst exactly like an Enter frame does -- a
+     * keystroke mid-burst is the definition of "not a paste".
+     */
+    const writeEnhancedKey = (legacy) => {
+        if (legacy.length === 0)
+            return;
+        flushBurst();
+        writeInput(legacy);
+    };
     const handleOutsidePaste = (text, holdTail) => {
-        const segments = splitEnterSequences(text);
-        for (let index = 0; index < segments.length; index += 1) {
-            const segment = segments[index];
-            if (segment.kind === 'text') {
-                handleText(segment.text, holdTail && index === segments.length - 1);
+        const win32 = enhancedKeys ? splitWin32KeySequences(text)
+            : [{ kind: 'text', text }];
+        for (let w = 0; w < win32.length; w += 1) {
+            const wSeg = win32[w];
+            const wLast = holdTail && w === win32.length - 1;
+            if (wSeg.kind === 'key') {
+                writeEnhancedKey(translateWin32Key(wSeg.record));
                 continue;
             }
-            // A key terminates the heuristic paste before its internal frame is written.
-            flushBurst();
-            writeInput(segment.kind === 'submit' ? '\r' : ENTER_NEWLINE_FRAME);
+            const csiu = enhancedKeys ? splitCsiUKeys(wSeg.text)
+                : [{ kind: 'text', text: wSeg.text }];
+            for (let c = 0; c < csiu.length; c += 1) {
+                const cSeg = csiu[c];
+                if (cSeg.kind === 'key') {
+                    writeEnhancedKey(translateCsiUKey(cSeg.key));
+                    continue;
+                }
+                const segments = splitEnterSequences(cSeg.text);
+                for (let index = 0; index < segments.length; index += 1) {
+                    const segment = segments[index];
+                    if (segment.kind === 'text') {
+                        handleText(segment.text, wLast && c === csiu.length - 1
+                            && index === segments.length - 1);
+                        continue;
+                    }
+                    // A key terminates the heuristic paste before its internal frame is written.
+                    writeEnhancedKey(segment.kind === 'submit' ? '\r' : ENTER_NEWLINE_FRAME);
+                }
+            }
         }
     };
     const appendBracketed = (text) => {
@@ -310,7 +346,7 @@ export function createStdinFilter(real, features, bridge, onWarn) {
                 // the ESC / ESC-[ head bytes, which the max keeps for whoever needs
                 // them. The existing 12 ms flush and the 32-char ceiling bound the
                 // hold, so no new timer is needed.
-                const keep = Math.max(trailingPastePrefixLength(rest), features.mouse ? trailingMousePrefixLength(rest) : 0, trailingEnterPrefixLength(rest));
+                const keep = Math.max(trailingPastePrefixLength(rest), features.mouse ? trailingMousePrefixLength(rest) : 0, trailingEnterPrefixLength(rest), enhancedKeys ? trailingWin32PrefixLength(rest) : 0, enhancedKeys ? trailingCsiUPrefixLength(rest) : 0);
                 const tail = rest.slice(rest.length - keep);
                 handleOutsidePaste(rest.slice(0, rest.length - keep), true);
                 pending += tail;