@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/input/win32-input-mode.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Win32-input-mode translation (win32 keyboard-enhancement section of the
+ * Shift+Enter newline fix).
+ *
+ * WHY THIS EXISTS. With `CSI ? 9001 h` the Windows console (conhost inside
+ * ConPTY included -- verified byte-level on both conhost and Windows Terminal
+ * 1.24, see docs/diagnoses/shift-enter-newline-dead-by-default) reports EVERY
+ * key as `ESC [ vk ; scan ; char ; keyDown ; mods ; repeat _`. That is the
+ * only Windows-side encoding in which Shift+Enter is distinguishable from
+ * Enter: mods carries SHIFT_PRESSED (0x10) on the record. Nothing else
+ * survives ConPTY: kitty `CSI > 1 u` is swallowed (a `CSI ? u` query never
+ * answers) and modifyOtherKeys is a no-op.
+ *
+ * THE CONTRACT. `splitWin32KeySequences` recognises the records in a chunk;
+ * `translateWin32Key` rewrites each one to the LEGACY bytes the same keypress
+ * would have produced with the mode off -- except the modified-Enter family,
+ * which becomes `ENTER_NEWLINE_FRAME` exactly like `enter-sequences.ts` maps
+ * its CSI-u cousins. Ink therefore sees the stream it has always seen. Key-up
+ * records are dropped (every press arrives as a down/up pair in one chunk).
+ *
+ * Pure: no node/React imports, callable from any test environment.
+ */
+/** Enable / disable win32-input-mode (private mode 9001). */
+export declare const WIN32_INPUT_ENABLE = "\u001B[?9001h";
+export declare const WIN32_INPUT_DISABLE = "\u001B[?9001l";
+/** One decoded `ESC [ vk ; sc ; char ; down ; mods ; rep _` record. */
+export interface Win32KeyRecord {
+    readonly vk: number;
+    readonly scan: number;
+    readonly char: number;
+    readonly down: boolean;
+    readonly mods: number;
+    readonly repeat: number;
+}
+export type Win32Segment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'key';
+    record: Win32KeyRecord;
+};
+/**
+ * Split a chunk into text spans and win32-input-mode records.
+ *
+ * MATCHES ONLY `ESC [ <digits/semicolons> _`: mouse reports need `<`, paste
+ * markers end in `~`, CSI-u ends in `u`, DECRPM replies start with `?`. A
+ * `_`-terminated all-numeric-parameter sequence is therefore unambiguous in
+ * the stream this filter ever sees.
+ */
+export declare function splitWin32KeySequences(text: string): Win32Segment[];
+/**
+ * Translate one record to the legacy bytes the same keypress would have
+ * produced with win32-input-mode off (Enter family excepted: a modified Enter
+ * becomes the newline frame, mirroring `ENTER_SEQUENCES`).
+ */
+export declare function translateWin32Key(record: Win32KeyRecord): string;
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * win32-input-mode record, or 0. Longest match, mirroring the other families.
+ */
+export declare function trailingWin32PrefixLength(text: string): number;

package/dist/input/win32-input-mode.js

@@ -0,0 +1,269 @@
+/**
+ * Win32-input-mode translation (win32 keyboard-enhancement section of the
+ * Shift+Enter newline fix).
+ *
+ * WHY THIS EXISTS. With `CSI ? 9001 h` the Windows console (conhost inside
+ * ConPTY included -- verified byte-level on both conhost and Windows Terminal
+ * 1.24, see docs/diagnoses/shift-enter-newline-dead-by-default) reports EVERY
+ * key as `ESC [ vk ; scan ; char ; keyDown ; mods ; repeat _`. That is the
+ * only Windows-side encoding in which Shift+Enter is distinguishable from
+ * Enter: mods carries SHIFT_PRESSED (0x10) on the record. Nothing else
+ * survives ConPTY: kitty `CSI > 1 u` is swallowed (a `CSI ? u` query never
+ * answers) and modifyOtherKeys is a no-op.
+ *
+ * THE CONTRACT. `splitWin32KeySequences` recognises the records in a chunk;
+ * `translateWin32Key` rewrites each one to the LEGACY bytes the same keypress
+ * would have produced with the mode off -- except the modified-Enter family,
+ * which becomes `ENTER_NEWLINE_FRAME` exactly like `enter-sequences.ts` maps
+ * its CSI-u cousins. Ink therefore sees the stream it has always seen. Key-up
+ * records are dropped (every press arrives as a down/up pair in one chunk).
+ *
+ * Pure: no node/React imports, callable from any test environment.
+ */
+import { ENTER_NEWLINE_FRAME, INDEX_KEY_FRAME } from './limits.js';
+/** Enable / disable win32-input-mode (private mode 9001). */
+export const WIN32_INPUT_ENABLE = '\x1b[?9001h';
+export const WIN32_INPUT_DISABLE = '\x1b[?9001l';
+/** Windows console `dwControlKeyState` modifier bits this module cares about. */
+const RIGHT_ALT = 0x1;
+const LEFT_ALT = 0x2;
+const RIGHT_CTRL = 0x4;
+const LEFT_CTRL = 0x8;
+const SHIFT = 0x10;
+/** Lock states, ENHANCED_KEY and friends must never look like modifiers. */
+const MODIFIER_MASK = SHIFT | LEFT_CTRL | RIGHT_CTRL | LEFT_ALT | RIGHT_ALT;
+/** Virtual-key codes the translator names explicitly. */
+const VK_BACK = 0x08;
+const VK_TAB = 0x09;
+const VK_ENTER = 0x0d;
+const VK_ESCAPE = 0x1b;
+const VK_PACKET = 0xe7;
+/**
+ * Parse one candidate body (`digits and semicolons`, the `_` excluded).
+ * Returns null when the field count is impossible for a real record -- that
+ * is what keeps a random `ESC [ 1 ; 2 3 _`-shaped paste from being eaten.
+ */
+function parseRecord(body) {
+    const fields = body.split(';');
+    if (fields.length !== 6)
+        return null;
+    const nums = fields.map(Number);
+    if (nums.some((n) => !Number.isInteger(n) || n < 0 || n > 0x10ffff))
+        return null;
+    const [vk, , char, down, mods, repeat] = nums;
+    if (vk === undefined || char === undefined || down === undefined)
+        return null;
+    if (mods === undefined || repeat === undefined)
+        return null;
+    if (vk > 0xff)
+        return null;
+    return { vk, scan: nums[1] ?? 0, char, down: down === 1, mods, repeat };
+}
+/**
+ * Split a chunk into text spans and win32-input-mode records.
+ *
+ * MATCHES ONLY `ESC [ <digits/semicolons> _`: mouse reports need `<`, paste
+ * markers end in `~`, CSI-u ends in `u`, DECRPM replies start with `?`. A
+ * `_`-terminated all-numeric-parameter sequence is therefore unambiguous in
+ * the stream this filter ever sees.
+ */
+export function splitWin32KeySequences(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 && text[end] !== '_') {
+            const c = text[end];
+            if (c < '0' || c > '9') {
+                if (c !== ';') {
+                    end = -1;
+                    break;
+                }
+            }
+            end += 1;
+        }
+        if (end === -1 || end >= text.length) {
+            index += 1;
+            continue;
+        }
+        const record = parseRecord(text.slice(index + 2, end));
+        if (!record) {
+            index += 1;
+            continue;
+        }
+        if (index > start)
+            segments.push({ kind: 'text', text: text.slice(start, index) });
+        segments.push({ kind: 'key', record });
+        index = end + 1;
+        start = index;
+    }
+    if (start < text.length)
+        segments.push({ kind: 'text', text: text.slice(start) });
+    return segments;
+}
+/** Legacy modifier parameter (xterm): 1 + shift + 2*alt + 4*ctrl. */
+function legacyModifierParam(m) {
+    let p = 1;
+    if (m & SHIFT)
+        p += 1;
+    if (m & (LEFT_ALT | RIGHT_ALT))
+        p += 2;
+    if (m & (LEFT_CTRL | RIGHT_CTRL))
+        p += 4;
+    return p;
+}
+/** Functional keys named by vk, as (letter | tilde-code) legacy shapes. */
+const FUNCTIONAL_KEYS = new Map([
+    [0x21, { code: 5 }], // PgUp
+    [0x22, { code: 6 }], // PgDn
+    [0x23, { letter: 'F' }], // End
+    [0x24, { letter: 'H' }], // Home
+    [0x25, { letter: 'D' }], // Left
+    [0x26, { letter: 'A' }], // Up
+    [0x27, { letter: 'C' }], // Right
+    [0x28, { letter: 'B' }], // Down
+    [0x2d, { code: 2 }], // Insert
+    [0x2e, { code: 3 }], // Delete
+    [0x70, { letter: 'P' }], // F1
+    [0x71, { letter: 'Q' }], // F2
+    [0x72, { letter: 'R' }], // F3
+    [0x73, { letter: 'S' }], // F4
+    [0x74, { code: 15 }], // F5
+    [0x75, { code: 17 }], // F6
+    [0x76, { code: 18 }], // F7
+    [0x77, { code: 19 }], // F8
+    [0x78, { code: 20 }], // F9
+    [0x79, { code: 21 }], // F10
+    [0x7a, { code: 23 }], // F11
+    [0x7b, { code: 24 }], // F12
+]);
+/** Emit the legacy form of a functional key under `m` modifiers. */
+function functionalLegacy(vk, m) {
+    const key = FUNCTIONAL_KEYS.get(vk);
+    if (!key)
+        return '';
+    if (m === 0) {
+        return 'letter' in key
+            ? (key.letter === 'P' || key.letter === 'Q' || key.letter === 'R' || key.letter === 'S'
+                ? `\x1bO${key.letter}`
+                : `\x1b[${key.letter}`)
+            : `\x1b[${key.code}~`;
+    }
+    const p = legacyModifierParam(m);
+    return 'letter' in key ? `\x1b[1;${p}${key.letter}` : `\x1b[${key.code};${p}~`;
+}
+/** Control code for Ctrl+letter, or the char itself when not a letter. */
+function ctrlByte(char) {
+    if (char >= 97 && char <= 122)
+        return char - 96; // a-z -> 1-26
+    if (char >= 65 && char <= 90)
+        return char - 64; // A-Z -> 1-26
+    return char;
+}
+const isPrintable = (char) => char >= 0x20 && char !== 0x7f;
+/**
+ * Translate one record to the legacy bytes the same keypress would have
+ * produced with win32-input-mode off (Enter family excepted: a modified Enter
+ * becomes the newline frame, mirroring `ENTER_SEQUENCES`).
+ */
+export function translateWin32Key(record) {
+    if (!record.down)
+        return '';
+    const m = record.mods & MODIFIER_MASK;
+    const ctrl = (m & (LEFT_CTRL | RIGHT_CTRL)) !== 0;
+    const alt = (m & (LEFT_ALT | RIGHT_ALT)) !== 0;
+    const shift = (m & SHIFT) !== 0;
+    const char = record.char === 0 ? '' : String.fromCodePoint(record.char);
+    // AltGr arrives as RightCtrl|RightAlt (or lone RightAlt) WITH the composed
+    // character already in `char`; prefixing ESC or control-translating it would
+    // break every non-US layout. Plain typing first, exotic combos never.
+    if (isPrintable(record.char) && (m === RIGHT_CTRL + RIGHT_ALT || m === RIGHT_ALT)) {
+        return char;
+    }
+    switch (record.vk) {
+        case VK_ENTER:
+            // A modified Enter NEVER submits -- same rule as `ENTER_SEQUENCES`.
+            return m === 0 ? '\r' : ENTER_NEWLINE_FRAME;
+        case VK_TAB:
+            // Ctrl+I is the project-indexer trigger, and the ONLY place the two are
+            // tell-apart is right here: legacy encoding collapses it to the Tab
+            // byte. Shift keeps ESC [ Z (Shift+Tab) so the mode toggle stays intact,
+            // and Ctrl+Shift+I stays on that Shift branch.
+            if (ctrl && !shift && !alt)
+                return INDEX_KEY_FRAME;
+            return shift ? '\x1b[Z' : '\t';
+        case VK_ESCAPE:
+            return alt ? '\x1b\x1b' : '\x1b';
+        case VK_BACK:
+            // POST-normalisation bytes: `handleText` rewrites DEL (0x7f) to BS
+            // (0x08) for Ink, and translated records bypass that walk -- emitting
+            // the final form keeps the stream byte-identical to the baseline.
+            if (alt)
+                return '\x1b\x08';
+            return '\x08';
+        default:
+            break;
+    }
+    if (record.char !== 0 && record.char < 0x20 && record.vk !== VK_PACKET) {
+        // Ctrl combos: Windows already resolves the control character (Ctrl+C is
+        // 0x03). Alt keeps the ESC prefix; Ctrl+Alt prefixes ESC over the code.
+        if (!ctrl && !alt && !shift)
+            return char;
+        if (!ctrl && alt)
+            return `\x1b${char}`;
+        // Ctrl+I, letter-vk shape: a physical Ctrl+I keeps the LETTER vk
+        // (0x49, the same Ctrl+letter probe rule that reports Ctrl+A as 65
+        // and Ctrl+J as 74) while `char` is already the Tab byte, so the
+        // VK_TAB switch above never sees the record. 0x09 is both the Tab
+        // byte and VK_TAB, so the tell-apart from plain Tab is ctrl alone,
+        // and Shift keeps ESC [ Z exactly like that switch: the mode toggle
+        // stays intact and Ctrl+Shift+I stays on the Shift branch.
+        if (ctrl && record.char === VK_TAB) {
+            if (!shift && !alt)
+                return INDEX_KEY_FRAME;
+            return shift ? '\x1b[Z' : '\t';
+        }
+        return ctrl ? `${alt ? '\x1b' : ''}${char}` : char;
+    }
+    if (isPrintable(record.char)) {
+        if (ctrl) {
+            const code = ctrlByte(record.char);
+            return `${alt ? '\x1b' : ''}${code === record.char ? char : String.fromCharCode(code)}`;
+        }
+        if (alt)
+            return `\x1b${char}`;
+        return char;
+    }
+    return functionalLegacy(record.vk, m);
+}
+/** True when `s` is a PROPER prefix of some win32-input-mode record. */
+function isWin32Prefix(s) {
+    // A bare ESC (or ESC + anything else) belongs to the Enter/mouse/paste
+    // families' hold; this family only ever extends `\x1b[` with digits and
+    // semicolons, up to but never including the `_`.
+    if (s.length < 3 || s[0] !== '\x1b' || s[1] !== '[')
+        return false;
+    for (let i = 2; i < s.length; i += 1) {
+        const c = s[i];
+        if ((c < '0' || c > '9') && c !== ';')
+            return false;
+    }
+    return true;
+}
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * win32-input-mode record, or 0. Longest match, mirroring the other families.
+ */
+export function trailingWin32PrefixLength(text) {
+    const max = Math.min(text.length, 32);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isWin32Prefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}

package/dist/model/agent/agent-mode.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Agent mode vocabulary (plan-mode §5.1).
+ *
+ * Pure: no React, no I/O, no `node:*`. Imported by the controller, the tool
+ * gate, the prompt builder, the slash command and four UI components, which is
+ * exactly why it must stay free of every one of their dependencies.
+ *
+ * `PLAN_MODE_BLOCKED_TOOLS` is deliberately NOT here. It lives in
+ * `tools/index.ts` beside `SKILL_TOOL_FLOOR`, because the invariant worth having
+ * is that the two sets PARTITION `HOST_TOOL_NAMES` — and a partition test is
+ * only as trustworthy as the distance between the two definitions. This file
+ * owns the mode vocabulary; that file owns which tools the modes act on.
+ *
+ * ASCII ONLY in every string literal below. `agent/` is inside the glyph
+ * scanner's scope (`glyphs.test.ts`), so a stray ellipsis here fails the build —
+ * which is why `OTHER_OPTION_LABEL` is a bare word and the ellipsis is appended
+ * at render time from `glyphs.ellipsis`.
+ */
+export type AgentMode = 'build' | 'plan';
+export declare const AGENT_MODES: readonly AgentMode[];
+/** The user-visible word for each mode. English, per the repo convention. */
+export declare const MODE_LABEL: Record<AgentMode, string>;
+/**
+ * The next mode in the cycle.
+ *
+ * Written as a cycle rather than a boolean flip so that adding Claude Code's
+ * "auto-accept edits" as a third posture is a one-line change to `AGENT_MODES`
+ * and nothing else. Two ship today (§1 non-goals).
+ */
+export declare function nextMode(current: AgentMode): AgentMode;
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+n` IS MEASURED, not guessed. On the lossy path it arrives as `0x0e`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/g/k/l/o/r/t,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * THIS KEY MOVED FROM `ctrl+p`, WHICH NOW OPENS THE PROMPT LIBRARY
+ * (quick-prompt-library D-1). The requirement names `ctrl+p` as the first entry
+ * to a feature users will build muscle memory for, and a key that is sometimes
+ * the prompt library and sometimes the mode switch is a key nobody can learn.
+ * `ctrl+n` was the only idle C0 byte left that survives the same lossy path, and
+ * it carries no conflicting behaviour: readline's `next-history` is `Up`/`Down`
+ * in this product.
+ *
+ * `^N` IS NOT AN ACCEPTABLE SPELLING OF IT, ANYWHERE. `^N` is already this
+ * product's word for TRANSCRIPT LINE OFFSET - the header's scroll chip reads
+ * `^<n>` and the help overlay has a `^N` row about the distance from the bottom -
+ * while every other `^X` in the same row is a key. Writing the mode fallback as
+ * `^N` would put two meanings of `^` on one line, so the header, the help
+ * overlay, `doctor`, the README and the one-shot migration notice all spell out
+ * `Ctrl+N`.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'n'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export declare const MODE_TOGGLE_KEYS: {
+    readonly primary: "shift+tab";
+    readonly fallback: "ctrl+n";
+};
+/** The two tools that only exist because a human is attached. */
+export declare const PLAN_TOOL_NAMES: readonly ["ask_user", "submit_plan"];
+/**
+ * The synthetic free-text option appended to every question.
+ *
+ * Plain `Other`, with no ellipsis: this module is inside the glyph scanner's
+ * scope, and the overlay appends `glyphs.ellipsis` itself so the label degrades
+ * to `Other...` on a terminal without Unicode.
+ */
+export declare const OTHER_OPTION_LABEL = "Other";
+/**
+ * Why a mutating tool was refused in plan mode.
+ *
+ * The wording carries weight beyond politeness (§3.9). A run that flips
+ * `build -> plan` mid-flight keeps its original system prompt to the end — the
+ * loop reads `ctx.systemPrompt`, which was copied by value when the run
+ * started — so for the rest of that run this refusal is the ONLY place the
+ * model learns that plan mode is on. A bare "not permitted" reads as a tool
+ * malfunction and gets retried.
+ */
+export declare function planRefusal(tool: string): string;
+/** Why `submit_plan` was refused outside plan mode. */
+export declare function submitPlanRefusal(): string;

package/dist/model/agent/agent-mode.js

@@ -0,0 +1,121 @@
+/**
+ * Agent mode vocabulary (plan-mode §5.1).
+ *
+ * Pure: no React, no I/O, no `node:*`. Imported by the controller, the tool
+ * gate, the prompt builder, the slash command and four UI components, which is
+ * exactly why it must stay free of every one of their dependencies.
+ *
+ * `PLAN_MODE_BLOCKED_TOOLS` is deliberately NOT here. It lives in
+ * `tools/index.ts` beside `SKILL_TOOL_FLOOR`, because the invariant worth having
+ * is that the two sets PARTITION `HOST_TOOL_NAMES` — and a partition test is
+ * only as trustworthy as the distance between the two definitions. This file
+ * owns the mode vocabulary; that file owns which tools the modes act on.
+ *
+ * ASCII ONLY in every string literal below. `agent/` is inside the glyph
+ * scanner's scope (`glyphs.test.ts`), so a stray ellipsis here fails the build —
+ * which is why `OTHER_OPTION_LABEL` is a bare word and the ellipsis is appended
+ * at render time from `glyphs.ellipsis`.
+ */
+export const AGENT_MODES = ['build', 'plan'];
+/** The user-visible word for each mode. English, per the repo convention. */
+export const MODE_LABEL = { build: 'BUILD', plan: 'PLAN' };
+/**
+ * The next mode in the cycle.
+ *
+ * Written as a cycle rather than a boolean flip so that adding Claude Code's
+ * "auto-accept edits" as a third posture is a one-line change to `AGENT_MODES`
+ * and nothing else. Two ship today (§1 non-goals).
+ */
+export function nextMode(current) {
+    const index = AGENT_MODES.indexOf(current);
+    return AGENT_MODES[(index + 1) % AGENT_MODES.length];
+}
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+n` IS MEASURED, not guessed. On the lossy path it arrives as `0x0e`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/g/k/l/o/r/t,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * THIS KEY MOVED FROM `ctrl+p`, WHICH NOW OPENS THE PROMPT LIBRARY
+ * (quick-prompt-library D-1). The requirement names `ctrl+p` as the first entry
+ * to a feature users will build muscle memory for, and a key that is sometimes
+ * the prompt library and sometimes the mode switch is a key nobody can learn.
+ * `ctrl+n` was the only idle C0 byte left that survives the same lossy path, and
+ * it carries no conflicting behaviour: readline's `next-history` is `Up`/`Down`
+ * in this product.
+ *
+ * `^N` IS NOT AN ACCEPTABLE SPELLING OF IT, ANYWHERE. `^N` is already this
+ * product's word for TRANSCRIPT LINE OFFSET - the header's scroll chip reads
+ * `^<n>` and the help overlay has a `^N` row about the distance from the bottom -
+ * while every other `^X` in the same row is a key. Writing the mode fallback as
+ * `^N` would put two meanings of `^` on one line, so the header, the help
+ * overlay, `doctor`, the README and the one-shot migration notice all spell out
+ * `Ctrl+N`.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'n'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export const MODE_TOGGLE_KEYS = { primary: 'shift+tab', fallback: 'ctrl+n' };
+/** The two tools that only exist because a human is attached. */
+export const PLAN_TOOL_NAMES = ['ask_user', 'submit_plan'];
+/**
+ * The synthetic free-text option appended to every question.
+ *
+ * Plain `Other`, with no ellipsis: this module is inside the glyph scanner's
+ * scope, and the overlay appends `glyphs.ellipsis` itself so the label degrades
+ * to `Other...` on a terminal without Unicode.
+ */
+export const OTHER_OPTION_LABEL = 'Other';
+/** Read-only alternatives named in every refusal, so the model has somewhere to go. */
+const READ_ONLY_ALTERNATIVES = 'read_file / list_dir / glob / grep';
+/**
+ * Why a mutating tool was refused in plan mode.
+ *
+ * The wording carries weight beyond politeness (§3.9). A run that flips
+ * `build -> plan` mid-flight keeps its original system prompt to the end — the
+ * loop reads `ctx.systemPrompt`, which was copied by value when the run
+ * started — so for the rest of that run this refusal is the ONLY place the
+ * model learns that plan mode is on. A bare "not permitted" reads as a tool
+ * malfunction and gets retried.
+ */
+export function planRefusal(tool) {
+    const extra = tool === 'bash'
+        ? ' bash is refused in full, including read-only commands like "git status":' +
+            ' a shell string cannot be classified reliably, and a gate that is right' +
+            ' most of the time is worse than one that is always right.'
+        : '';
+    return (`Plan mode is active, so ${tool} is refused.${extra}` +
+        ` Use ${READ_ONLY_ALTERNATIVES} to research, then call submit_plan.` +
+        ' Do not try to work around this; finish the plan instead.');
+}
+/** Why `submit_plan` was refused outside plan mode. */
+export function submitPlanRefusal() {
+    return ('submit_plan is only available in Plan mode. You are in Build mode - ' +
+        'just do the work and summarize when you are done.');
+}

package/dist/model/agent/entry-limits.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Bounded view state (tui-render-performance L1 / R5).
+ *
+ * `ViewState.entries` used to grow without any ceiling: `argsRaw`, assistant
+ * `text` and `thinking` all concatenated forever, and the entry array was never
+ * trimmed. That makes the per-frame cost of the renderer proportional to the
+ * total number of characters the session has ever produced, because Ink's
+ * `renderNodeToOutput` walks and measures every mounted text node whether or not
+ * `overflow: hidden` clips it.
+ *
+ * Two bounds live here, both pure and React-free:
+ *   - `appendBounded` caps one field by eliding its MIDDLE, and
+ *   - `trimEntries` ring-trims the entry array itself.
+ *
+ * ASCII ONLY. This module is produced outside `src/ui/**`, where no terminal
+ * capabilities are available, so the elision marker has to be safe on a legacy
+ * `cmd.exe` -- the same rule `PREVIEW_TRUNCATION_MARK` in `reducer.ts` records.
+ */
+import type { Entry } from './reducer.js';
+export interface EntryLimits {
+    /** Assistant answer text ceiling, in characters. */
+    text: number;
+    /** Assistant thinking ceiling. */
+    thinking: number;
+    /** Streamed tool-argument JSON ceiling. */
+    argsRaw: number;
+}
+/**
+ * The per-field ceilings.
+ *
+ * `text` is the generous one on purpose: a 256 KiB answer is already far past
+ * anything a terminal can usefully show, and the middle is what gets elided, so
+ * both the opening and the live cursor survive. `argsRaw` is the tight one --
+ * it is a streamed JSON fragment rendered as a 60-character card summary, so
+ * anything past a few KiB is invisible by construction.
+ */
+export declare const ENTRY_LIMITS: EntryLimits;
+/** Marker inserted at the elision point. ASCII -- produced outside `src/ui/**`. */
+export declare const ELISION_MARK_PREFIX = "\n[... ";
+export declare const ELISION_MARK_SUFFIX = " characters elided ...]\n";
+/**
+ * Append `delta` to `prev`, keeping the result at or below `cap` by eliding the
+ * MIDDLE. Head and tail are both preserved: the head is the answer's opening,
+ * the tail is where the cursor is. Idempotent -- re-eliding an already elided
+ * string collapses the two markers into one.
+ *
+ * The returned string is NEVER longer than `cap` (AC-7). The marker's own digit
+ * count is bounded before the tail budget is computed, so the arithmetic cannot
+ * overshoot by a digit the way a naive `cap - marker.length` would.
+ */
+export declare function appendBounded(prev: string, delta: string, cap: number): string;
+export interface TrimResult {
+    entries: Entry[];
+    dropped: number;
+}
+/**
+ * Ring-trim to `retain` entries; returns the SAME array reference when no-op.
+ *
+ * The identity return is load-bearing: the reducer spreads this result into a
+ * new `ViewState` on every append, and a fresh array on every action would
+ * defeat the `React.memo` boundaries L2 installs on the transcript.
+ */
+export declare function trimEntries(entries: Entry[], retain: number): TrimResult;
+export declare function setEntryRetain(value: number): void;
+export declare function entryRetain(): number;