@aragon-agent/cli 0.6.15 → 0.6.16

package/dist/config/model-windows.d.ts

@@ -0,0 +1,91 @@
+/**
+ * User-declared context windows, read from `~/.aragon-agent/model-windows.json`
+ * (path owned by `app-paths.ts`).
+ *
+ * WHY THIS FILE EXISTS. `ModelRegistry.getContextWindow` resolves a window from
+ * API discovery, the builtin model lists and the ten-entry catalog - and for
+ * every other id (a gateway alias, a self-hosted model, a release too new for
+ * the table) it returns the explicitly-untrusted 128k `fallback`. The gauge
+ * then renders `?` forever, by design: it refuses to divide by a guessed
+ * denominator. The one number that can make the denominator real is the user's
+ * own, and `config.json`'s `contextWindow` key can only hold ONE of it. This
+ * file is the per-model form of the same assertion.
+ *
+ * THE APPLICATION NEVER WRITES IT. A file the user owns by hand cannot be
+ * clobbered by an upgrade, and its absence is the ordinary case, not an error.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`).
+ */
+/** Structural bounds only; there is no policy surface to tune here. */
+export interface ModelWindowsLimits {
+    /** Entries beyond this many are dropped, in file order. */
+    readonly maxEntries: number;
+    /** Keys longer than this are dropped rather than trusted as ids. */
+    readonly maxKeyLength: number;
+    /** A window below the smallest real context (1k) is a typo, not a limit. */
+    readonly minWindow: number;
+    /** A window above 1e9 tokens is also a typo; no model ships that today. */
+    readonly maxWindow: number;
+}
+export declare const MODEL_WINDOWS_LIMITS: ModelWindowsLimits;
+/** Normalized model id -> declared window. Keys are stored ALREADY normalized. */
+export type ModelWindowTable = ReadonlyMap<string, number>;
+/**
+ * Same normalization core's `catalogModelId` applies, restated here because it
+ * is not part of Core's public surface and a second exporter would be a
+ * dependency on an internal. Keep the two in step: a date-stamped id
+ * (`kimi-k3-20260716`) and its bare form must resolve to one entry.
+ */
+export declare function normalizeModelKey(modelId: string): string;
+/** What a parse produced, and whether the FILE itself was at fault. */
+export interface ModelWindowsParse {
+    table: ModelWindowTable;
+    /**
+     * True only when the text could not be understood at all (bad JSON, wrong
+     * top-level type). A valid file with zero USABLE entries is `false`: the
+     * user wrote JSON, the values were the problem, and every dead value was
+     * already dropped rather than trusted.
+     */
+    malformed: boolean;
+}
+/**
+ * Parse already-decoded text into a table. NEVER THROWS - a hand-edited file
+ * is the rule here, not the exception, and a typo must cost the user one dead
+ * entry, not the session. Two accepted shapes:
+ *
+ *   { "version": 1, "windows": { "kimi-k3": 1048576 } }
+ *   { "kimi-k3": 1048576 }                        (bare map, same effect)
+ *
+ * The wrapper exists so the format can grow fields without a migration; the
+ * bare map is accepted because the first shape a user types is the simple one.
+ * A leading UTF-8 BOM is tolerated: `readFileSync(..., 'utf8')` does not strip
+ * it, `JSON.parse` cannot parse it, and Notepad writes it by default.
+ */
+export declare function parseModelWindowsResult(text: string): ModelWindowsParse;
+/** The table alone, for callers that do not care why it might be empty. */
+export declare function parseModelWindows(text: string): ModelWindowTable;
+/**
+ * mtime-cached lookup over the file.
+ *
+ * WHY A STAT PER LOOKUP RATHER THAN A LOAD AT STARTUP: `getModelInfoFor` is
+ * called on every measurement, and the meter's `refreshValidity` re-reads the
+ * window precisely so a moved denominator (a `/model` switch, a live config
+ * edit) re-measures without a relaunch. A user saving this file mid-session
+ * gets the same treatment - `statSync` is microseconds, and the read itself
+ * only happens when the stamp actually changes.
+ *
+ * THE STAMP IS mtimeMs+size, so a rewrite that lands in the SAME millisecond
+ * with the SAME byte count serves the previous table once. Squeezing that
+ * window shut would need a content hash per lookup, which is exactly the cost
+ * the stamp exists to avoid; the next differing write clears it regardless.
+ */
+export declare class ModelWindows {
+    private readonly path;
+    private table;
+    private stamp;
+    constructor(path?: string);
+    /** The declared window for `modelId`, or `undefined` when nobody declared one. */
+    lookup(modelId: string): number | undefined;
+    private refresh;
+}

package/dist/config/model-windows.js

@@ -0,0 +1,181 @@
+/**
+ * User-declared context windows, read from `~/.aragon-agent/model-windows.json`
+ * (path owned by `app-paths.ts`).
+ *
+ * WHY THIS FILE EXISTS. `ModelRegistry.getContextWindow` resolves a window from
+ * API discovery, the builtin model lists and the ten-entry catalog - and for
+ * every other id (a gateway alias, a self-hosted model, a release too new for
+ * the table) it returns the explicitly-untrusted 128k `fallback`. The gauge
+ * then renders `?` forever, by design: it refuses to divide by a guessed
+ * denominator. The one number that can make the denominator real is the user's
+ * own, and `config.json`'s `contextWindow` key can only hold ONE of it. This
+ * file is the per-model form of the same assertion.
+ *
+ * THE APPLICATION NEVER WRITES IT. A file the user owns by hand cannot be
+ * clobbered by an upgrade, and its absence is the ordinary case, not an error.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`).
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { getLogger } from '../logging/logger.js';
+import { getModelWindowsPath } from './app-paths.js';
+export const MODEL_WINDOWS_LIMITS = {
+    maxEntries: 512,
+    maxKeyLength: 200,
+    minWindow: 1_024,
+    maxWindow: 1_000_000_000,
+};
+/**
+ * Same normalization core's `catalogModelId` applies, restated here because it
+ * is not part of Core's public surface and a second exporter would be a
+ * dependency on an internal. Keep the two in step: a date-stamped id
+ * (`kimi-k3-20260716`) and its bare form must resolve to one entry.
+ */
+export function normalizeModelKey(modelId) {
+    return modelId.trim().toLowerCase()
+        .replace(/^(models|openai|anthropic|google)\//, '')
+        .replace(/-(?:\d{4}-\d{2}-\d{2}|\d{8})$/, '');
+}
+function isWindowValue(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) &&
+        value >= MODEL_WINDOWS_LIMITS.minWindow && value <= MODEL_WINDOWS_LIMITS.maxWindow;
+}
+/**
+ * Parse already-decoded text into a table. NEVER THROWS - a hand-edited file
+ * is the rule here, not the exception, and a typo must cost the user one dead
+ * entry, not the session. Two accepted shapes:
+ *
+ *   { "version": 1, "windows": { "kimi-k3": 1048576 } }
+ *   { "kimi-k3": 1048576 }                        (bare map, same effect)
+ *
+ * The wrapper exists so the format can grow fields without a migration; the
+ * bare map is accepted because the first shape a user types is the simple one.
+ * A leading UTF-8 BOM is tolerated: `readFileSync(..., 'utf8')` does not strip
+ * it, `JSON.parse` cannot parse it, and Notepad writes it by default.
+ */
+export function parseModelWindowsResult(text) {
+    const body = text.replace(/^\uFEFF/, '');
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return { table: new Map(), malformed: true };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { table: new Map(), malformed: true };
+    }
+    const record = parsed;
+    const source = record.windows !== undefined && record.windows !== null &&
+        typeof record.windows === 'object' && !Array.isArray(record.windows)
+        ? record.windows
+        : record;
+    const table = new Map();
+    for (const [rawKey, rawValue] of Object.entries(source)) {
+        const key = normalizeModelKey(rawKey);
+        if (key.length === 0 || key.length > MODEL_WINDOWS_LIMITS.maxKeyLength)
+            continue;
+        if (!isWindowValue(rawValue))
+            continue;
+        table.set(key, rawValue);
+        if (table.size >= MODEL_WINDOWS_LIMITS.maxEntries)
+            break;
+    }
+    return { table, malformed: false };
+}
+/** The table alone, for callers that do not care why it might be empty. */
+export function parseModelWindows(text) {
+    return parseModelWindowsResult(text).table;
+}
+/**
+ * Decode the raw bytes the way a Windows text editor may have saved them.
+ *
+ * `readFileSync(path, 'utf8')` alone fails THREE ways on this machine's most
+ * common editors: a UTF-8 BOM survives into the string and kills `JSON.parse`,
+ * and Notepad's "Unicode" saves are UTF-16LE (or BE), which decode as NUL-laden
+ * mojibake. All three are silent feature-death for exactly the user who just
+ * tried to configure it, so the sniff happens before any parse.
+ */
+function decodeModelWindowsFile(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+        return bytes.subarray(2).toString('utf16le');
+    }
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        // Big-endian UTF-16: Node has no utf16be decoder, so swap pairs in place
+        // on a COPY and reuse the little-endian decoder.
+        const swapped = Buffer.from(bytes.subarray(2));
+        for (let i = 0; i + 1 < swapped.length; i += 2) {
+            const high = swapped[i];
+            swapped[i] = swapped[i + 1];
+            swapped[i + 1] = high;
+        }
+        return swapped.toString('utf16le');
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return bytes.subarray(3).toString('utf8');
+    }
+    return bytes.toString('utf8');
+}
+/**
+ * mtime-cached lookup over the file.
+ *
+ * WHY A STAT PER LOOKUP RATHER THAN A LOAD AT STARTUP: `getModelInfoFor` is
+ * called on every measurement, and the meter's `refreshValidity` re-reads the
+ * window precisely so a moved denominator (a `/model` switch, a live config
+ * edit) re-measures without a relaunch. A user saving this file mid-session
+ * gets the same treatment - `statSync` is microseconds, and the read itself
+ * only happens when the stamp actually changes.
+ *
+ * THE STAMP IS mtimeMs+size, so a rewrite that lands in the SAME millisecond
+ * with the SAME byte count serves the previous table once. Squeezing that
+ * window shut would need a content hash per lookup, which is exactly the cost
+ * the stamp exists to avoid; the next differing write clears it regardless.
+ */
+export class ModelWindows {
+    path;
+    table = new Map();
+    stamp = null;
+    constructor(path = getModelWindowsPath()) {
+        this.path = path;
+    }
+    /** The declared window for `modelId`, or `undefined` when nobody declared one. */
+    lookup(modelId) {
+        this.refresh();
+        return this.table.get(normalizeModelKey(modelId));
+    }
+    refresh() {
+        let stamp;
+        try {
+            const stats = statSync(this.path);
+            stamp = { mtimeMs: stats.mtimeMs, size: stats.size };
+        }
+        catch (error) {
+            // A deleted file (ENOENT) is a decision: drop the entries. Any OTHER
+            // failure (EACCES, an antivirus lock) is transient, and blanking every
+            // declared window because a scanner held the file open for 50 ms would
+            // swing the gauge to `?` for a reason the user cannot see - keep the
+            // last good table and try again on the next lookup.
+            if (error.code === 'ENOENT') {
+                this.stamp = null;
+                this.table = new Map();
+            }
+            return;
+        }
+        if (stamp.mtimeMs === this.stamp?.mtimeMs && stamp.size === this.stamp.size)
+            return;
+        let bytes;
+        try {
+            bytes = readFileSync(this.path);
+        }
+        catch {
+            return; // Appeared in the stat, gone in the read: try again next lookup.
+        }
+        const result = parseModelWindowsResult(decodeModelWindowsFile(bytes));
+        if (result.malformed) {
+            getLogger().warn('config', 'model-windows.json could not be parsed; ignoring it until it is fixed', { path: this.path });
+        }
+        this.table = result.table;
+        this.stamp = stamp;
+    }
+}

package/dist/config/schema.d.ts

@@ -786,6 +786,14 @@ export interface PersistedConfig {
      * asked for; a kill switch is what a bug report needs.
      */
     paste: boolean;
+    /**
+     * Ask the terminal to report modified keys distinctly so Shift+Enter can
+     * insert a newline (win32-input-mode on Windows, kitty disambiguate +
+     * modifyOtherKeys elsewhere). A KILL SWITCH in the exact sense `paste`
+     * above records: the encoding tables are structural and live in
+     * `input/win32-input-mode.ts` / `input/csiu-keys.ts`.
+     */
+    keyboardEnhancement: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
@@ -971,6 +979,15 @@ export interface CliConfig {
      * reach none of them.
      */
     paste: boolean;
+    /**
+     * Whether this session may push the keyboard-enhancement modes.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `paste` above records: `runInteractive` reads it -- where `config`
+     * is a `CliConfig` -- to decide the filter's `enhancedKeys` feature
+     * and the `enableKeyboardEnhancement` push.
+     */
+    keyboardEnhancement: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /**

package/dist/config/schema.js

@@ -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/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 })`. */