@nanhara/hara 0.122.6 → 0.123.0

package/dist/session/task.js

@@ -0,0 +1,161 @@
+import { randomUUID } from "node:crypto";
+export const TASK_SCHEMA_VERSION = 1;
+export const MAX_TASK_OBJECTIVE_CHARS = 4096;
+export const MAX_TASK_STEERING_CHARS = 4096;
+export const MAX_TASK_STEERING_ENTRIES = 24;
+function iso(at = new Date()) {
+    return typeof at === "string" ? at : at.toISOString();
+}
+function boundedText(value, max) {
+    const normalized = value.replace(/\r\n?/g, "\n").trim();
+    return (normalized || "(image-only task)").slice(0, max);
+}
+function validId(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 220 && !/[\\/\0]/.test(value);
+}
+function validTimestamp(value) {
+    return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+export function newTurnInteraction() {
+    return { kind: "turn", turnId: randomUUID() };
+}
+export function newSteerInteraction(expectedTurnId) {
+    return { kind: "steer", expectedTurnId, turnId: randomUUID() };
+}
+export function createTaskExecution(objective, turnId, at = new Date()) {
+    const now = iso(at);
+    return {
+        schemaVersion: TASK_SCHEMA_VERSION,
+        id: randomUUID(),
+        objective: boundedText(objective, MAX_TASK_OBJECTIVE_CHARS),
+        status: "running",
+        turnId,
+        createdAt: now,
+        updatedAt: now,
+        startedAt: now,
+    };
+}
+export function continueTaskExecution(task, interaction, at = new Date()) {
+    if (!task)
+        return { ok: false, reason: "there is no task to steer" };
+    if (task.turnId !== interaction.expectedTurnId) {
+        return { ok: false, reason: `stale steer for turn ${interaction.expectedTurnId}; active turn is ${task.turnId}` };
+    }
+    const now = iso(at);
+    return {
+        ok: true,
+        task: {
+            ...task,
+            status: "running",
+            turnId: interaction.turnId,
+            updatedAt: now,
+            startedAt: now,
+            endedAt: undefined,
+            lastOutcome: undefined,
+        },
+    };
+}
+export function recordTaskSteering(task, expectedTurnId, content, at = new Date()) {
+    if (!task)
+        return { ok: false, reason: "there is no running task to steer" };
+    if (task.status !== "running")
+        return { ok: false, reason: `task ${task.id} is ${task.status}, not running` };
+    if (task.turnId !== expectedTurnId) {
+        return { ok: false, reason: `stale steer for turn ${expectedTurnId}; active turn is ${task.turnId}` };
+    }
+    const now = iso(at);
+    const steering = [
+        ...(task.steering ?? []),
+        { id: randomUUID(), turnId: expectedTurnId, content: boundedText(content, MAX_TASK_STEERING_CHARS), createdAt: now },
+    ].slice(-MAX_TASK_STEERING_ENTRIES);
+    return { ok: true, task: { ...task, steering, updatedAt: now } };
+}
+export function finishTaskExecution(task, outcome, todos = [], interrupted = false, at = new Date()) {
+    if (!task)
+        return undefined;
+    const now = iso(at);
+    const incomplete = todos.some((todo) => todo.status !== "done");
+    const lastOutcome = interrupted ? "interrupted" : (outcome?.status ?? "interrupted");
+    const status = interrupted
+        ? "paused"
+        : outcome?.status === "completed"
+            ? (incomplete ? "paused" : "completed")
+            : outcome?.status === "error" || outcome?.status === "empty" || outcome?.status === "halted"
+                ? "blocked"
+                : "paused";
+    return { ...task, status, lastOutcome, updatedAt: now, endedAt: now };
+}
+/** A process died while this task was running. Recovery is explicit and never claims success. */
+export function recoverTaskExecution(task, at = new Date()) {
+    if (!task || task.status !== "running")
+        return task;
+    const now = iso(at);
+    return { ...task, status: "paused", lastOutcome: "interrupted", updatedAt: now, endedAt: now };
+}
+export function forkTaskExecution(task, at = new Date()) {
+    if (!task)
+        return undefined;
+    const now = iso(at);
+    return {
+        ...task,
+        id: randomUUID(),
+        status: "paused",
+        turnId: randomUUID(),
+        createdAt: now,
+        updatedAt: now,
+        startedAt: now,
+        endedAt: now,
+        lastOutcome: "interrupted",
+        steering: task.steering?.slice(-MAX_TASK_STEERING_ENTRIES).map((entry) => ({ ...entry })),
+    };
+}
+export function taskExecutionContext(task, interaction) {
+    const steeringNote = interaction.kind === "steer"
+        ? "This interaction steers the existing task. Refine execution without replacing its objective."
+        : "This interaction created a new task.";
+    return [
+        "# Task execution (authoritative; separate from conversation history)",
+        `Task ID: ${task.id}`,
+        `Turn ID: ${task.turnId}`,
+        `Objective: ${task.objective}`,
+        `Interaction: ${interaction.kind}`,
+        steeringNote,
+        "Conversation messages provide evidence and refinements, but the task objective above remains authoritative until an explicit new task starts.",
+    ].join("\n");
+}
+export function formatTaskExecution(task) {
+    if (!task)
+        return "(no task state)";
+    return [
+        `task ${task.id.slice(0, 8)} · ${task.status}`,
+        `turn ${task.turnId.slice(0, 8)} · outcome ${task.lastOutcome ?? "running"}`,
+        `objective: ${task.objective}`,
+        `steering: ${task.steering?.length ?? 0}`,
+    ].join("\n");
+}
+export function isTaskExecution(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const task = value;
+    if (task.schemaVersion !== TASK_SCHEMA_VERSION ||
+        !validId(task.id) ||
+        typeof task.objective !== "string" || task.objective.length === 0 || task.objective.length > MAX_TASK_OBJECTIVE_CHARS ||
+        (task.status !== "running" && task.status !== "paused" && task.status !== "completed" && task.status !== "blocked") ||
+        !validId(task.turnId) ||
+        !validTimestamp(task.createdAt) || !validTimestamp(task.updatedAt) || !validTimestamp(task.startedAt) ||
+        (task.endedAt !== undefined && !validTimestamp(task.endedAt)) ||
+        (task.lastOutcome !== undefined && task.lastOutcome !== "completed" && task.lastOutcome !== "error" && task.lastOutcome !== "empty" && task.lastOutcome !== "halted" && task.lastOutcome !== "interrupted"))
+        return false;
+    if (task.steering === undefined)
+        return true;
+    if (!Array.isArray(task.steering) || task.steering.length > MAX_TASK_STEERING_ENTRIES)
+        return false;
+    return task.steering.every((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return false;
+        const steering = entry;
+        return validId(steering.id) && validId(steering.turnId) &&
+            typeof steering.content === "string" && steering.content.length > 0 && steering.content.length <= MAX_TASK_STEERING_CHARS &&
+            validTimestamp(steering.createdAt);
+    });
+}

package/dist/tui/App.js

@@ -20,6 +20,7 @@ import { clearTodos, currentTodos, onTodosChange } from "../tools/todo.js";
 import { onTurnPhase, turnPhase } from "../agent/phase.js";
 import { listJobs, onJobsChange } from "../exec/jobs.js";
 import { ModelPicker } from "./model-picker.js";
+import { newSteerInteraction, newTurnInteraction } from "../session/task.js";
 let _id = 0;
 const nid = () => ++_id;
 const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
@@ -289,7 +290,7 @@ function StatusRow({ working, todos, queued }) {
     // Pre-first-token honesty (codex-parity): "waiting for the model" reads very differently from a
     // generic "working" when the network is slow — the user knows the request is out, not dead.
     const verb = (phase === "waiting" ? `waiting for the model… ${elapsedSec}s · esc to interrupt` : spinnerVerb(todos, elapsedSec)) + bgTag;
-    return (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "yellow", children: frames[frame % frames.length] }), _jsx(Text, { dimColor: true, children: ` ${verb} · ⏎ queues${queued ? ` (${queued})` : ""}` })] }));
+    return (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "yellow", children: frames[frame % frames.length] }), _jsx(Text, { dimColor: true, children: ` ${verb} · ⏎ steers task${queued ? ` (${queued})` : ""}` })] }));
 }
 // Short per-mode descriptions for the ONE-ROW mode line (the old two-row ModeBar's long sentences
 // don't fit inline). Full behavior is documented in /help; this line is a switching aid, not a manual.
@@ -366,6 +367,7 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
     const [todos, setTodos] = useState(() => currentTodos());
     const ctrlRef = useRef(null);
     const queueRef = useRef([]); // type-ahead: FIFO of messages entered while working
+    const activeTurnRef = useRef(null); // interaction identity survives React render timing
     const [pool, setPool] = useState([]); // type-ahead pool: queued message lines, shown above the input
     const drainingRef = useRef(false); // idempotency guard so the drain effect can't double-send one item
     const statusRef = useRef(status);
@@ -478,7 +480,7 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         }
         ctrlRef.current?.abort();
     }, []);
-    const handleSubmit = useCallback(async (line, images) => {
+    const handleSubmit = useCallback(async (line, images, forcedInteraction) => {
         const t = line.trim();
         // A free-text question (ask_user) is awaiting an answer: this submission IS the answer, not a new turn.
         if (askText) {
@@ -490,15 +492,21 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         if ((!t && !images?.length) || prompt)
             return; // nothing to send, or a choice is pending
         if (working) {
-            // type-ahead: hold the message in the pool; all pooled messages are sent together when the turn ends
-            queueRef.current.push({ line, images });
+            // Bind every type-ahead message to the exact live turn. A stale message must never silently become
+            // a new task after another turn starts (Codex's expected_turn_id steering invariant).
+            const expectedTurnId = activeTurnRef.current;
+            if (!expectedTurnId)
+                return;
+            queueRef.current.push({ line, images, expectedTurnId });
             setPool(queueRef.current.map((q) => q.line.trim() || "🖼 (image)"));
             return;
         }
+        const interaction = forcedInteraction ?? newTurnInteraction();
+        activeTurnRef.current = interaction.turnId;
         // Fold the previous turn's checklist NOW, at the natural boundary (a new task begins). The old
         // 30s-idle timer yanked the input box UP by the panel's height while the user was reading/typing
         // (anti-bob); folding on submit means the shrink coincides with the user's own action.
-        if (currentTodos().length) {
+        if (interaction.kind === "turn" && currentTodos().length) {
             const list = currentTodos();
             const done = list.filter((td) => td.status === "done").length;
             setHistory((h) => [...h, { id: nid(), kind: "notice", text: `  ✓ Todos: ${done}/${list.length} done` }]);
@@ -609,7 +617,7 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         // so pressing Enter leaves the message stuck in the input box for seconds ("回车一直不动"). One tick.
         await new Promise((resolve) => setTimeout(resolve, 0));
         try {
-            await onSubmit(t, { sink, confirm: confirmFn, select: selectFn, ask: askFn, pickModel: pickModelFn, setApproval: setApprovalFn, signal: ctrl.signal, exit, approval: statusRef.current.approval, drainQueue }, images);
+            await onSubmit(t, { sink, confirm: confirmFn, select: selectFn, ask: askFn, pickModel: pickModelFn, setApproval: setApprovalFn, signal: ctrl.signal, exit, approval: statusRef.current.approval, drainQueue }, images, interaction);
         }
         catch (e) {
             pushCurrent("notice", `error: ${e instanceof Error ? e.message : String(e)}`);
@@ -630,9 +638,12 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         setCurrent([]);
         setWorking(false);
         ctrlRef.current = null;
+        if (activeTurnRef.current === interaction.turnId)
+            activeTurnRef.current = null;
     }, [working, prompt, askText, onSubmit, pushCurrent, model, exit, drainQueue, noteVisionIfNeeded]);
-    // Drain the type-ahead pool: when the turn finishes (working → false) and nothing awaits a choice, COALESCE
-    // every pooled message into ONE turn and send it — additions/clarifications go to the agent together, in order.
+    // A message can arrive after runAgent's final pending-input drain but before the view flips to idle. Keep
+    // its original expectedTurnId and run it as a STEER continuation of that task — never as an ordinary new
+    // task inferred from queue timing.
     useEffect(() => {
         if (working || prompt || askText || drainingRef.current || !queueRef.current.length)
             return;
@@ -642,7 +653,8 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         setPool([]);
         const line = batch.map((b) => b.line).join("\n\n");
         const images = batch.flatMap((b) => b.images ?? []);
-        void Promise.resolve(handleSubmit(line, images.length ? images : undefined)).finally(() => {
+        const expectedTurnId = batch[0].expectedTurnId;
+        void Promise.resolve(handleSubmit(line, images.length ? images : undefined, newSteerInteraction(expectedTurnId))).finally(() => {
             drainingRef.current = false;
         });
     }, [working, prompt, askText, handleSubmit]);

package/dist/tui/InputBox.js

@@ -319,19 +319,40 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
     const [mode, setMode] = useState("insert"); // vim only
     const [pending, setPending] = useState(""); // vim operator-pending (d/c/g)
     const [register, setRegister] = useState(""); // vim yank/delete register
+    // Ink may emit several logical inputs from one OS chunk (notably bracketed paste followed by Enter)
+    // inside one React batch. Refs are the authoritative event-time draft; state remains the render copy.
+    // Without this split, the second callback observes the previous render and can submit an empty draft.
+    const valueRef = useRef(value);
+    const cursorRef = useRef(cursor);
+    const imagesRef = useRef(images);
+    const pastesRef = useRef(pastes);
+    valueRef.current = value;
+    cursorRef.current = cursor;
+    imagesRef.current = images;
+    pastesRef.current = pastes;
     const historyRef = useRef(null);
     if (!historyRef.current)
         historyRef.current = new ComposerHistory();
     const inputHistory = historyRef.current;
     const set = (v, c) => {
         inputHistory.abandonNavigation();
+        valueRef.current = v;
+        cursorRef.current = c;
         setValue(v);
         setCursor(c);
         setSel(0);
         setDismissed(false);
     };
-    const snapshot = () => ({ value, attachments: images, pastes });
+    const snapshot = () => ({
+        value: valueRef.current,
+        attachments: imagesRef.current,
+        pastes: pastesRef.current,
+    });
     const restore = (draft) => {
+        valueRef.current = draft.value;
+        cursorRef.current = draft.value.length;
+        imagesRef.current = draft.attachments;
+        pastesRef.current = draft.pastes;
         setValue(draft.value);
         setCursor(draft.value.length);
         setImages(draft.attachments);
@@ -343,12 +364,21 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
     // (codex / Claude-Code style). Backspace over the token removes both.
     const addImage = (img) => {
         inputHistory.abandonNavigation();
-        const tok = `[Image #${images.length + 1}]`;
-        const before = value.slice(0, cursor);
+        const currentValue = valueRef.current;
+        const currentCursor = cursorRef.current;
+        const currentImages = imagesRef.current;
+        const tok = `[Image #${currentImages.length + 1}]`;
+        const before = currentValue.slice(0, currentCursor);
         const ins = (before && !/\s$/.test(before) ? " " : "") + tok + " ";
-        setValue(before + ins + value.slice(cursor));
-        setCursor((before + ins).length);
-        setImages((xs) => [...xs, img]);
+        const nextValue = before + ins + currentValue.slice(currentCursor);
+        const nextCursor = (before + ins).length;
+        const nextImages = [...currentImages, img];
+        valueRef.current = nextValue;
+        cursorRef.current = nextCursor;
+        imagesRef.current = nextImages;
+        setValue(nextValue);
+        setCursor(nextCursor);
+        setImages(nextImages);
         setSel(0);
         setDismissed(false);
     };
@@ -357,23 +387,36 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
     // can no longer fire the newline-submit path mid-paste. Expanded back to the full text on submit.
     const addPaste = (text) => {
         inputHistory.abandonNavigation();
+        const currentValue = valueRef.current;
+        const currentCursor = cursorRef.current;
+        const currentPastes = pastesRef.current;
         const lines = text.split("\n").length;
-        const tok = `[Paste #${pastes.length + 1} +${lines} lines]`;
-        const before = value.slice(0, cursor);
+        const tok = `[Paste #${currentPastes.length + 1} +${lines} lines]`;
+        const before = currentValue.slice(0, currentCursor);
         const ins = (before && !/\s$/.test(before) ? " " : "") + tok + " ";
-        setValue(before + ins + value.slice(cursor));
-        setCursor((before + ins).length);
-        setPastes((xs) => [...xs, text]);
+        const nextValue = before + ins + currentValue.slice(currentCursor);
+        const nextCursor = (before + ins).length;
+        const nextPastes = [...currentPastes, text];
+        valueRef.current = nextValue;
+        cursorRef.current = nextCursor;
+        pastesRef.current = nextPastes;
+        setValue(nextValue);
+        setCursor(nextCursor);
+        setPastes(nextPastes);
         setSel(0);
         setDismissed(false);
     };
-    const expandPastes = (text) => text.replace(/\[Paste #(\d+) \+\d+ lines\]/g, (m, d) => pastes[Number(d) - 1] ?? m);
-    const submit = (text) => {
-        if (!text.trim() && images.length === 0)
+    const expandPastes = (text) => text.replace(/\[Paste #(\d+) \+\d+ lines\]/g, (m, d) => pastesRef.current[Number(d) - 1] ?? m);
+    const submit = () => {
+        const text = valueRef.current;
+        const currentImages = imagesRef.current;
+        if (!text.trim() && currentImages.length === 0)
             return; // nothing to send
         inputHistory.record(snapshot());
-        onSubmit?.(expandPastes(text), images.length ? images : undefined);
+        onSubmit?.(expandPastes(text), currentImages.length ? currentImages : undefined);
         set("", 0);
+        imagesRef.current = [];
+        pastesRef.current = [];
         setImages([]);
         setPastes([]);
         setMode("insert"); // a fresh prompt starts in insert
@@ -422,7 +465,7 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
         // vim NORMAL mode: printable keys are commands, not text (Enter/arrows/backspace still navigate/submit)
         if (vim && mode === "normal") {
             if (key.return)
-                return submit(value);
+                return submit();
             if (key.leftArrow)
                 return setCursor((c) => Math.max(0, c - 1));
             if (key.rightArrow)
@@ -472,7 +515,7 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
                 set(value.slice(0, cursor) + "\n" + value.slice(cursor), cursor + 1);
                 return;
             }
-            submit(value);
+            submit();
             return;
         }
         if (key.leftArrow)
@@ -536,7 +579,7 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
             // A lone newline delivered through `input` (some terminals send Enter this way instead of
             // setting key.return) = the user pressed Enter → submit.
             if (/^[\r\n]+$/.test(input)) {
-                submit(value);
+                submit();
                 return;
             }
             // A PASTE containing newlines inserts as REAL MULTI-LINE TEXT (normalize CRLF/CR → LF) — the

package/dist/tui/bracketed-paste.js

@@ -0,0 +1,265 @@
+import { StringDecoder } from "node:string_decoder";
+import { Readable } from "node:stream";
+export const BRACKETED_PASTE_START = "\u001b[200~";
+export const BRACKETED_PASTE_END = "\u001b[201~";
+export const ENABLE_BRACKETED_PASTE = "\u001b[?2004h";
+export const DISABLE_BRACKETED_PASTE = "\u001b[?2004l";
+export const MAX_BRACKETED_PASTE_CHARS = 2 * 1024 * 1024;
+export const INCOMPLETE_PASTE_TIMEOUT_MS = 750;
+const pasteTooLargeMessage = (limit) => {
+    const size = limit >= 1024 * 1024 ? `${Math.ceil(limit / (1024 * 1024))} MiB` : `${limit} characters`;
+    return `[Paste rejected: input exceeds ${size}]`;
+};
+function suffixPrefixLength(value, marker) {
+    const max = Math.min(value.length, marker.length - 1);
+    for (let length = max; length > 0; length--) {
+        if (value.endsWith(marker.slice(0, length)))
+            return length;
+    }
+    return 0;
+}
+/**
+ * Stateful decoder for xterm bracketed-paste framing. Terminals are free to split both markers and
+ * UTF-8 content across arbitrary stdin chunks, so no individual chunk can be treated as a paste.
+ * Completed paste contents are emitted as exactly one logical input event; framing bytes never reach
+ * Ink's key parser.
+ */
+export class BracketedPasteDecoder {
+    maxPasteChars;
+    mode = "normal";
+    buffer = "";
+    constructor(maxPasteChars = MAX_BRACKETED_PASTE_CHARS) {
+        this.maxPasteChars = maxPasteChars;
+    }
+    get hasIncompletePaste() {
+        return this.mode !== "normal";
+    }
+    get hasPendingMarker() {
+        return this.mode === "normal" && this.buffer.length > 0;
+    }
+    feed(input) {
+        if (!input)
+            return [];
+        this.buffer += input;
+        const output = [];
+        while (this.buffer.length > 0) {
+            if (this.mode === "normal") {
+                const start = this.buffer.indexOf(BRACKETED_PASTE_START);
+                if (start >= 0) {
+                    if (start > 0)
+                        output.push(this.buffer.slice(0, start));
+                    this.buffer = this.buffer.slice(start + BRACKETED_PASTE_START.length);
+                    this.mode = "paste";
+                    continue;
+                }
+                // Retain only a suffix that could become a split start marker. Everything before it is
+                // ordinary keyboard input and can be forwarded immediately.
+                const retained = suffixPrefixLength(this.buffer, BRACKETED_PASTE_START);
+                const ready = this.buffer.slice(0, this.buffer.length - retained);
+                if (ready)
+                    output.push(ready);
+                this.buffer = retained ? this.buffer.slice(-retained) : "";
+                break;
+            }
+            const end = this.buffer.indexOf(BRACKETED_PASTE_END);
+            if (end >= 0) {
+                if (this.mode === "paste" && end <= this.maxPasteChars)
+                    output.push(this.buffer.slice(0, end));
+                else
+                    output.push(pasteTooLargeMessage(this.maxPasteChars));
+                this.buffer = this.buffer.slice(end + BRACKETED_PASTE_END.length);
+                this.mode = "normal";
+                continue;
+            }
+            if (this.mode === "paste" && this.buffer.length > this.maxPasteChars) {
+                // Fail closed instead of retaining an unbounded terminal stream or silently submitting a
+                // truncated source file. Keep only a possible split end marker while discarding the payload.
+                const retained = suffixPrefixLength(this.buffer, BRACKETED_PASTE_END);
+                this.buffer = retained ? this.buffer.slice(-retained) : "";
+                this.mode = "overflow";
+            }
+            else if (this.mode === "overflow") {
+                const retained = suffixPrefixLength(this.buffer, BRACKETED_PASTE_END);
+                this.buffer = retained ? this.buffer.slice(-retained) : "";
+            }
+            break;
+        }
+        return output;
+    }
+    /** Recover when a terminal sent paste-start but never sent paste-end. */
+    flushIncomplete() {
+        if (this.mode === "normal") {
+            const pending = this.buffer;
+            this.buffer = "";
+            return pending ? [pending] : [];
+        }
+        const output = this.mode === "paste" ? this.buffer : pasteTooLargeMessage(this.maxPasteChars);
+        this.mode = "normal";
+        this.buffer = "";
+        return output ? [output] : [];
+    }
+}
+/**
+ * Readable proxy passed to Ink. It preserves the real TTY's raw-mode lifecycle while turning each
+ * completed bracketed paste into one readable event. Multiple logical events from one OS chunk are
+ * emitted on separate event-loop turns so `paste + Enter` cannot be coalesced back into one keypress.
+ */
+export class BracketedPasteInput extends Readable {
+    source;
+    isTTY;
+    utf8 = new StringDecoder("utf8");
+    decoder;
+    queue = [];
+    drainImmediate;
+    markerImmediate;
+    pasteTimer;
+    ending = false;
+    disposed = false;
+    constructor(source, options = {}) {
+        super();
+        this.source = source;
+        this.isTTY = Boolean(source.isTTY);
+        this.decoder = new BracketedPasteDecoder(options.maxPasteChars);
+        this.incompleteTimeoutMs = options.incompleteTimeoutMs ?? INCOMPLETE_PASTE_TIMEOUT_MS;
+        source.on("data", this.onData);
+        source.on("end", this.onEnd);
+        source.on("error", this.onError);
+    }
+    incompleteTimeoutMs;
+    _read() {
+        // Input is pushed by the wrapped terminal stream.
+    }
+    setRawMode(enabled) {
+        this.source.setRawMode?.(enabled);
+        return this;
+    }
+    ref() {
+        this.source.ref?.();
+        return this;
+    }
+    unref() {
+        this.source.unref?.();
+        return this;
+    }
+    onData = (chunk) => {
+        if (this.disposed)
+            return;
+        this.clearMarkerImmediate();
+        const text = Buffer.isBuffer(chunk) ? this.utf8.write(chunk) : String(chunk);
+        this.enqueue(this.decoder.feed(text));
+        if (this.decoder.hasIncompletePaste) {
+            this.resetPasteTimer();
+        }
+        else {
+            this.clearPasteTimer();
+            // Like Ink's own input parser, retain a lone/split ESC sequence for only one event-loop turn.
+            if (this.decoder.hasPendingMarker) {
+                this.markerImmediate = setImmediate(() => {
+                    this.markerImmediate = undefined;
+                    this.enqueue(this.decoder.flushIncomplete());
+                });
+            }
+        }
+    };
+    onEnd = () => {
+        if (this.disposed)
+            return;
+        const tail = this.utf8.end();
+        if (tail)
+            this.enqueue(this.decoder.feed(tail));
+        this.enqueue(this.decoder.flushIncomplete());
+        this.ending = true;
+        this.finishIfDrained();
+    };
+    onError = (error) => {
+        this.destroy(error);
+    };
+    resetPasteTimer() {
+        this.clearPasteTimer();
+        this.pasteTimer = setTimeout(() => {
+            this.pasteTimer = undefined;
+            this.enqueue(this.decoder.flushIncomplete());
+        }, this.incompleteTimeoutMs);
+        this.pasteTimer.unref?.();
+    }
+    enqueue(values) {
+        for (const value of values)
+            if (value)
+                this.queue.push(value);
+        if (this.queue.length === 0 || this.drainImmediate)
+            return;
+        const first = this.queue.shift();
+        if (first !== undefined)
+            this.push(first);
+        if (this.queue.length > 0)
+            this.scheduleDrain();
+        else
+            this.finishIfDrained();
+    }
+    scheduleDrain() {
+        if (this.drainImmediate)
+            return;
+        this.drainImmediate = setImmediate(() => {
+            this.drainImmediate = undefined;
+            const next = this.queue.shift();
+            if (next !== undefined)
+                this.push(next);
+            if (this.queue.length > 0)
+                this.scheduleDrain();
+            else
+                this.finishIfDrained();
+        });
+    }
+    finishIfDrained() {
+        if (this.ending && this.queue.length === 0 && !this.drainImmediate)
+            this.push(null);
+    }
+    clearPasteTimer() {
+        if (this.pasteTimer)
+            clearTimeout(this.pasteTimer);
+        this.pasteTimer = undefined;
+    }
+    clearMarkerImmediate() {
+        if (this.markerImmediate)
+            clearImmediate(this.markerImmediate);
+        this.markerImmediate = undefined;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.clearPasteTimer();
+        this.clearMarkerImmediate();
+        if (this.drainImmediate)
+            clearImmediate(this.drainImmediate);
+        this.drainImmediate = undefined;
+        this.source.off("data", this.onData);
+        this.source.off("end", this.onEnd);
+        this.source.off("error", this.onError);
+        this.push(null);
+    }
+}
+/** Enable terminal-side paste framing and return an idempotent cleanup. */
+export function enableBracketedPaste(output) {
+    if (!output.isTTY)
+        return () => { };
+    let enabled = false;
+    try {
+        output.write(ENABLE_BRACKETED_PASTE);
+        enabled = true;
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        if (!enabled)
+            return;
+        enabled = false;
+        try {
+            output.write(DISABLE_BRACKETED_PASTE);
+        }
+        catch {
+            // Terminal cleanup is best effort; never mask the original TUI exit/error.
+        }
+    };
+}