@north-light/crouter 0.3.154

package/dist/clients/attach/input/controller.js

@@ -0,0 +1,689 @@
+// input/controller.ts — the input half of `crtr surface attach` (T6).
+//
+// Owns the editor's behavior: turns keystrokes + submits into `ClientToBroker`
+// command frames (sent via `hooks.onCommand`), reads pasted clipboard images to
+// attach to the next message (review M1), and renders blocking extension dialogs
+// (delegating to T5's `renderDialog`, routing the answer through
+// `hooks.onDialogResponse`). It NEVER touches the session or spawns pi — it only
+// produces frames; T7's `viewer.ts` constructs it and wires the socket.
+//
+// Keybinding matching is delegated to CustomEditor + its KeybindingsManager
+// (built by config.ts with the vendored `app.*` defs + user overrides) — that
+// is what calls `matchesKey` internally, so the controller wires intent via the
+// editor's `onSubmit`/`onEscape`/`onPasteImage` hooks + `onAction(app.*)`
+// registrations rather than matching raw keys itself.
+import { spawn } from 'node:child_process';
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { BROKER_READ_CAPS, encodeFrame, } from '../../../core/runtime/broker-protocol.js';
+import { isBlockingDialog, renderDialog } from '../overlays/dialogs.js';
+import { readClipboardImage, writeClipboardImageToFile } from './clipboard-image.js';
+import { dispatchSlashCommand, isSlashCommand, readOnlySlashRefusal } from '../slash/dispatch.js';
+import { buildForkPicker, buildModelPicker, buildScopedModelsPicker, buildSessionPicker, buildSettingsPicker, buildTreePicker, } from '../overlays/pickers.js';
+import { buildMcpPicker, readMcpServers, startMcpServerAction, MCP_EMPTY_STATE_HINT } from '../overlays/mcp.js';
+import { buildFileReviewPicker } from '../overlays/file-review.js';
+/** Overlay geometry for the native pickers — a touch wider/taller than the
+ *  extension-dialog default since the model/session/tree lists are denser. */
+const PICKER_OVERLAY_OPTIONS = { anchor: 'center', width: '80%', maxHeight: '85%' };
+/** Max gap between two Esc presses to count as a double-tap (pi uses 500ms). */
+const DOUBLE_ESCAPE_MS = 500;
+/** Largest drive frame the controller will emit. The broker DESTROYS the viewer
+ *  socket on any client line over BROKER_READ_CAPS.maxLineBytes (24 MiB), so we
+ *  refuse to emit within a 4 MiB margin of that. `emitDrive` measures the ACTUAL
+ *  encoded frame (text + JSON envelope), so the cap holds however the bytes
+ *  split. Pasted images go to a temp file and enter the prompt as a path, never
+ *  as inline base64, so a paste can no longer push a frame toward this ceiling. */
+const MAX_FRAME_BYTES = BROKER_READ_CAPS.maxLineBytes - 4 * 1024 * 1024;
+/** ClientToBroker frame types that mutate the engine/session — everything the
+ *  broker gates behind a writable role (`read_only` in broker.ts), plus
+ *  `reload_auth`
+ *  (open to any role server-side, but viewer-local login/logout are unwired for
+ *  a read-only viewer — this entry is belt-and-suspenders in case a
+ *  future path routes it through onCommand). A read-only viewer — an observer
+ *  (`--observer`) or a REMOTE attach (`--canvas`, always an observer) — is
+ *  a strictly VIEW-ONLY surface: even though the broker would itself reject
+ *  these from an observer, the input layer must never even emit one —
+ *  server-side rejection alone is not the contract.
+ *  `dequeue` is listed for documentation completeness even though it never
+ *  reaches `emitCommand` (it rides the separate `onRequest` read-op channel —
+ *  see `handleDequeue`'s own capability guard). Read-only frames (get_commands,
+ *  list_models, list_sessions, get_tree, get_settings, list_scoped_models)
+ *  and hello/bye/shutdown/extension_ui_response are deliberately absent —
+ *  reads stay live for remote (pickers just never get the chance to select,
+ *  see slash/dispatch.ts's READ_ONLY_SAFE_BUILTIN_NAMES gate). */
+const DRIVE_FRAME_TYPES = new Set([
+    'prompt', 'steer', 'follow_up', 'abort', 'bash',
+    'set_model', 'cycle_model', 'cycle_ladder', 'cycle_thinking', 'set_thinking_level', 'dequeue',
+    'set_auto_retry', 'set_auto_compaction', 'compact', 'new_session',
+    'switch_session', 'fork', 'set_session_name', 'navigate_tree', 'reload',
+    'export', 'clone', 'share', 'reload_auth',
+]);
+export class InputController {
+    tui;
+    editor;
+    keybindings;
+    hooks;
+    /** The currently-rendered blocking dialog, if any (for supersede/dismiss). */
+    dialog;
+    /** The request id of {@link dialog} — so a broker-driven `extension_ui_dismiss`
+     *  tears down ONLY the matching overlay (correlated dismissal), never an
+     *  unrelated one. */
+    dialogId;
+    /** The currently-open native picker overlay, if any (for supersede/dismiss). */
+    picker;
+    /** Monotonic open counter — a slow read-op reply whose `seq` is no longer the
+     *  latest is dropped, so an earlier picker never pops over a later request. */
+    openSeq = 0;
+    /** Latest engine state from `welcome`/`session_info_changed` (for `/session`). */
+    state;
+    /** Timestamp of the last lone Esc, for double-tap → tree detection (0 = none). */
+    lastEscapeAt = 0;
+    /** Pasted-image registry: placeholder ordinal → temp-file path. The editor
+     *  shows a clean `[Image #N]` token instead of the ugly temp path; on submit
+     *  each token is expanded back to its path so the agent reads it off disk.
+     *  Cleared whenever the editor is emptied (send / clear). */
+    pastedImages = new Map();
+    /** Monotonic paste counter — the `N` in `[Image #N]`. */
+    pasteSeq = 0;
+    constructor(tui, editor, keybindings, hooks) {
+        this.tui = tui;
+        this.editor = editor;
+        this.keybindings = keybindings;
+        this.hooks = hooks;
+        this.wire();
+    }
+    /** Why this viewer may not mutate the engine, or `undefined` when it may. The
+     *  ONE capability gate: a remote attach and an `--observer` attach are both
+     *  read-only, and the role is fixed at hello, so this answer cannot change
+     *  mid-session. */
+    readOnlyReason() {
+        if (this.hooks.remote === true)
+            return 'Read-only remote attach';
+        if ((this.hooks.role ?? 'controller') !== 'controller')
+            return 'Read-only observer attach';
+        return undefined;
+    }
+    /** Central choke point for every command frame the input layer emits (direct
+     *  keybindings, emitDrive, and the slash-command/picker `send` sink). Returns
+     *  false when the gate refused the frame, so callers stop without emitting
+     *  it. A writable local attach is byte-for-byte unchanged. */
+    emitCommand(frame) {
+        const reason = this.readOnlyReason();
+        if (reason !== undefined && DRIVE_FRAME_TYPES.has(frame.type)) {
+            this.notify(`${reason} — cannot drive the engine`);
+            return false;
+        }
+        this.hooks.onCommand(frame);
+        return true;
+    }
+    /** The model-ladder keybinding (alt+m / alt+shift+m), which viewer.ts's global
+     *  key listener owns rather than the editor's action table. Public so that
+     *  binding rides the gate above instead of going straight to the socket. */
+    cycleLadder(direction) {
+        this.emitCommand({ type: 'cycle_ladder', direction });
+    }
+    /** Render extension UI requests from the broker. Blocking dialogs route their
+     *  answer back to the broker; non-blocking notify requests become the viewer's
+     *  normal notice line and NOTHING else — a notify must never tear down an
+     *  unrelated blocking dialog whose broker request is still pending. A dialog is
+     *  torn down only by (a) a NEW blocking dialog superseding it, (b) its own
+     *  answer, or (c) a correlated {@link dismissDialog}
+     *  from the broker (the request was aborted/timed out out-of-band). */
+    attachDialog(req) {
+        if (req.method === 'notify') {
+            const prefix = req.notifyType === 'error' ? 'Error: ' : req.notifyType === 'warning' ? 'Warning: ' : '';
+            this.notify(`${prefix}${req.message}`);
+            this.tui.requestRender();
+            return;
+        }
+        // Everything past here TEARS DOWN the showing dialog, so a non-blocking
+        // method must never reach it: pi's envelope carries display/editor methods
+        // this viewer handles elsewhere (or not at all), and letting one through
+        // would orphan an in-flight blocking request whose overlay it dismissed
+        // without answering. `renderDialog` is inert for them anyway — the guard is
+        // about the teardown above it, not the overlay below it.
+        if (!isBlockingDialog(req))
+            return;
+        this.dialog?.dismiss();
+        this.dialogId = req.id;
+        this.dialog = renderDialog(this.tui, req, (resp) => {
+            this.dialog = undefined;
+            this.dialogId = undefined;
+            this.hooks.onDialogResponse(resp);
+        }, this.keybindings);
+        this.tui.requestRender();
+    }
+    /** Broker-driven correlated dismissal: the broker resolved this request itself
+     *  (its request was aborted out-of-band — e.g. a local OAuth loopback callback
+     *  won the race against this manual-paste dialog — or its timeout fired). Tear
+     *  down ONLY the overlay whose id matches; leave any other dialog untouched. */
+    dismissDialog(id) {
+        if (this.dialogId !== id)
+            return;
+        this.dialog?.dismiss();
+        this.dialog = undefined;
+        this.dialogId = undefined;
+        this.tui.requestRender();
+    }
+    /** Feed the latest engine state so read-only commands (e.g. `/session`) report
+     *  current values. Optional; the controller works without it. */
+    setState(state) {
+        this.state = state;
+    }
+    // -------------------------------------------------------------------------
+    wire() {
+        this.editor.onSubmit = (text) => this.handleSubmit(text);
+        // Esc — mirror pi's native interactive escape (interactive-mode
+        // setupKeyHandlers): while streaming, abort the turn; with an EMPTY editor
+        // and idle, a double-tap (≤500ms) opens the session-tree navigator to rewind
+        // to an earlier point (a lone tap just arms it); a non-empty editor swallows
+        // Esc (it never clears text). openTreePicker is the same get_tree →
+        // navigate_tree path that `/tree` and app.session.tree use.
+        this.editor.onEscape = () => {
+            if (this.state?.isStreaming) {
+                this.emitCommand({ type: 'abort' });
+                return;
+            }
+            if (this.editor.getText().trim())
+                return;
+            const now = Date.now();
+            if (now - this.lastEscapeAt < DOUBLE_ESCAPE_MS) {
+                this.lastEscapeAt = 0;
+                void this.openTreePicker();
+            }
+            else {
+                this.lastEscapeAt = now;
+            }
+        };
+        // Ctrl+V / Alt+V → read clipboard image, save it to a temp file, and splice
+        // the file PATH into the editor at the caret (so the agent can read it).
+        this.editor.onPasteImage = () => {
+            void this.handlePaste();
+        };
+        // A file DRAGGED into the pane arrives as bracketed-paste text (its path), not
+        // an image event — TitledEditor recognizes an image path and routes it here so
+        // it becomes an `[Image #N]` token just like a Ctrl+V paste.
+        const dropEditor = this.editor;
+        dropEditor.onPasteImagePath = (path) => {
+            this.attachImage(path);
+            return true;
+        };
+        // Keyboard shortcuts that map 1:1 to a frame needing no engine-side data.
+        this.editor.onAction('app.session.new', () => this.emitCommand({ type: 'new_session' }));
+        this.editor.onAction('app.model.cycleForward', () => this.emitCommand({ type: 'cycle_model', direction: 'forward' }));
+        this.editor.onAction('app.model.cycleBackward', () => this.emitCommand({ type: 'cycle_model', direction: 'backward' }));
+        this.editor.onAction('app.thinking.cycle', () => this.emitCommand({ type: 'cycle_thinking' }));
+        this.editor.onAction('app.message.followUp', () => this.handleFollowUp());
+        this.editor.onAction('app.message.dequeue', () => void this.handleDequeue());
+        // Pure client-side render toggles (ChatView owns the components).
+        this.editor.onAction('app.tools.expand', () => this.hooks.onToggleToolsExpand?.());
+        this.editor.onAction('app.thinking.toggle', () => this.hooks.onToggleThinking?.());
+        // Ctrl+G — compose the prompt in $VISUAL/$EDITOR, then load it back.
+        this.editor.onAction('app.editor.external', () => void this.openExternalEditor());
+        // Native pickers via keybinding. `app.model.select` is bound to ctrl+l by
+        // default (vendored in config.ts); the session.* actions ship with no
+        // default key but fire if the user binds one — wiring them keeps parity.
+        this.editor.onAction('app.model.select', () => void this.openModelPicker());
+        this.editor.onAction('app.session.tree', () => void this.openTreePicker());
+        this.editor.onAction('app.session.fork', () => void this.openForkPicker());
+        this.editor.onAction('app.session.resume', () => void this.openSessionPicker());
+    }
+    slashContext() {
+        return {
+            send: (frame) => this.emitCommand(frame),
+            notify: (message) => this.notify(message),
+            state: this.state,
+            cwd: process.cwd(),
+            nodeId: this.hooks.nodeId,
+            profileId: this.hooks.profileId,
+            remote: this.hooks.remote,
+            role: this.hooks.role,
+            onGraph: this.hooks.onGraph,
+            onQuit: this.hooks.onQuit,
+            onCopy: this.hooks.onCopy,
+            onColor: this.hooks.onColor,
+            onNodeMetadata: this.hooks.onNodeMetadata,
+            openModelPicker: () => void this.openModelPicker(),
+            openSessionPicker: () => void this.openSessionPicker(),
+            openForkPicker: () => void this.openForkPicker(),
+            openTreePicker: () => void this.openTreePicker(),
+            openSettingsPicker: () => void this.openSettingsPicker(),
+            openScopedModelsPicker: () => void this.openScopedModelsPicker(),
+            openMcpPicker: (serverName) => this.openMcpPicker(serverName),
+            openLoginPicker: this.hooks.openLoginPicker ? () => this.hooks.openLoginPicker() : undefined,
+            openLogoutPicker: this.hooks.openLogoutPicker ? () => this.hooks.openLogoutPicker() : undefined,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Native interactive pickers (overlays). Each fetches its payload via the
+    // correlated read-op, builds the REAL pi selector, and routes selection to the
+    // same command frame the text-arg slash path sends. Opened by slash command
+    // (via slashContext) AND by keybinding (onAction, below).
+    // -------------------------------------------------------------------------
+    /** Send a command frame to the broker (picker selection sink). */
+    send = (frame) => {
+        this.emitCommand(frame);
+    };
+    /** Fetch a picker payload (narrowed on `kind`), then build + show its overlay
+     *  iff this open is still the latest (m4: a stale slow reply is dropped). Any
+     *  failure — unwired channel, wrong kind, request error, or a throwing builder
+     *  — surfaces a notice instead of an unhandled rejection (m5). */
+    async openPicker(frame, kind, label, build) {
+        if (this.hooks.onRequest === undefined) {
+            this.notify(`The ${label} picker isn't available in this viewer`);
+            return;
+        }
+        const seq = ++this.openSeq;
+        let reply;
+        try {
+            reply = await this.hooks.onRequest(frame);
+        }
+        catch (err) {
+            this.notify(`Could not open the ${label} picker: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        if (seq !== this.openSeq)
+            return; // a newer picker open superseded this one
+        if (reply.kind !== kind) {
+            this.notify(`Unexpected reply building the ${label} picker`);
+            return;
+        }
+        this.showPicker((controls) => build(reply, controls.close));
+    }
+    /** Show a picker built by `build` (given a `close` that tears it down).
+     *  Mounted INLINE under the editor when viewer.ts wires onMountPicker/
+     *  onUnmountPicker (the integrated chrome path); otherwise falls back to a
+     *  centered overlay. Supersedes any picker already on screen. Routes focus to
+     *  the builder's declared focus target (an inner list for fork/settings) and
+     *  ALWAYS restores editor focus on close — `OverlayHandle.hide()` only
+     *  auto-restores when the OUTER component held focus, which is not the case
+     *  once we focus an inner child. A throwing builder is caught into a notice (m5). */
+    showPicker(build) {
+        this.picker?.dismiss();
+        const inline = this.hooks.onMountPicker !== undefined && this.hooks.onUnmountPicker !== undefined;
+        let handle;
+        let current;
+        let done = false;
+        const disposeCurrent = () => {
+            const disposable = current?.component;
+            try {
+                disposable?.dispose?.();
+            }
+            catch {
+                /* ignore dispose errors during teardown */
+            }
+        };
+        const mount = (p) => {
+            if (inline)
+                this.hooks.onMountPicker(p.component);
+            else
+                handle = this.tui.showOverlay(p.component, PICKER_OVERLAY_OPTIONS);
+            this.tui.setFocus(p.focus);
+        };
+        const unmount = () => {
+            if (inline)
+                this.hooks.onUnmountPicker?.();
+            else
+                handle?.hide();
+        };
+        // Swap the mounted component IN PLACE (same inline slot) — multi-step flows
+        // like /login replace the provider selector with the login dialog without
+        // ever popping a centered overlay. Does NOT restore editor focus (only a
+        // genuine close does); focus moves to the new component.
+        const replace = (component, focus) => {
+            if (done)
+                return;
+            disposeCurrent();
+            unmount();
+            current = { component, focus };
+            mount(current);
+            this.tui.requestRender();
+        };
+        const close = () => {
+            if (done)
+                return;
+            done = true;
+            disposeCurrent();
+            unmount();
+            this.picker = undefined;
+            this.tui.setFocus(this.editor);
+            this.tui.requestRender();
+        };
+        try {
+            current = build({ close, replace });
+        }
+        catch (err) {
+            this.notify(`Could not open picker: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        mount(current);
+        this.picker = {
+            // Supersede: tear down without restoring editor focus — the new picker
+            // grabs focus next. Genuine close restores the editor (above).
+            dismiss: () => {
+                if (done)
+                    return;
+                done = true;
+                disposeCurrent();
+                unmount();
+            },
+        };
+        this.tui.requestRender();
+    }
+    openModelPicker() {
+        return this.openPicker({ type: 'list_models' }, 'list_models', 'model', (data, close) => buildModelPicker(this.tui, data, this.send, close));
+    }
+    /** Unlike the other pickers, the session picker opens IMMEDIATELY — its
+     *  component owns async loaders (with a Loading header), so the multi-second
+     *  session-dir scan runs off the open path instead of blocking it. */
+    openSessionPicker() {
+        const request = this.hooks.onRequest;
+        if (request === undefined) {
+            this.notify("The session picker isn't available in this viewer");
+            return Promise.resolve();
+        }
+        this.openSeq++; // supersede any in-flight fetch-first picker open
+        this.showPicker((controls) => buildSessionPicker(this.tui, this.state?.sessionFile, request, this.keybindings, this.send, controls.close));
+        return Promise.resolve();
+    }
+    openTreePicker() {
+        return this.openPicker({ type: 'get_tree' }, 'get_tree', 'tree', (data, close) => buildTreePicker(this.tui, data, this.send, close));
+    }
+    openForkPicker() {
+        return this.openPicker({ type: 'get_tree' }, 'get_tree', 'fork', (data, close) => buildForkPicker(data, this.send, close));
+    }
+    openSettingsPicker() {
+        return this.openPicker({ type: 'get_settings' }, 'get_settings', 'settings', (data, close) => buildSettingsPicker(data, this.send, close, (m) => this.notify(m)));
+    }
+    openScopedModelsPicker() {
+        return this.openPicker({ type: 'list_scoped_models' }, 'list_scoped_models', 'scoped-models', (data, close) => buildScopedModelsPicker(data, close, (m) => this.notify(m)));
+    }
+    /** `/mcp` — the MCP server status panel. Viewer-local (no read-op): the rows
+     *  come from the adapter's on-disk config sources + tool cache
+     *  (overlays/mcp.ts), and the actions (connect / auth-start) ride a `prompt`
+     *  frame to the engine, where the adapter runtime actually lives. With a
+     *  server name (`/mcp <server>`), act on that server directly. */
+    openMcpPicker(serverName) {
+        const rows = readMcpServers();
+        if (rows.length === 0) {
+            this.notify(MCP_EMPTY_STATE_HINT);
+            return;
+        }
+        if (serverName !== undefined) {
+            const row = rows.find((r) => r.name === serverName);
+            if (row === undefined) {
+                this.notify(`No MCP server named ${JSON.stringify(serverName)} — usage: /mcp [server]`);
+                return;
+            }
+            startMcpServerAction(row, this.send, (m) => this.notify(m));
+            return;
+        }
+        this.showPicker((controls) => buildMcpPicker(rows, this.send, controls.close, (m) => this.notify(m)));
+    }
+    /** Open the transcript-backed file-review picker. The caller owns the popup
+     *  process and cursor insertion; this controller only owns picker lifetime. */
+    openFileReviewPicker(candidates, cwd, onChoose) {
+        this.showPicker((controls) => buildFileReviewPicker(candidates, cwd, onChoose, controls.close, (message) => this.notify(message)));
+    }
+    /** Open a viewer-local auth picker (login/logout) — uses the same showPicker
+     *  machinery as read-op pickers, but with a locally-built component (no read-op
+     *  request; auth operations are viewer-local in tmux-local attach). `prepare`
+     *  is async because provider status is async; superseded opens drop on openSeq. */
+    async openAuthPicker(prepare) {
+        const seq = ++this.openSeq;
+        let build;
+        try {
+            build = await prepare();
+        }
+        catch (err) {
+            this.notify(`Could not open the auth picker: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        if (seq !== this.openSeq)
+            return; // a newer picker open superseded this one
+        this.showPicker(build);
+    }
+    handleSubmit(text) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        if (isSlashCommand(trimmed)) {
+            const slashCtx = this.slashContext();
+            // A read-only viewer's refusal is surfaced BEFORE dispatch, so no command
+            // or engine frame is emitted.
+            const refusal = readOnlySlashRefusal(trimmed, slashCtx);
+            if (refusal !== undefined) {
+                this.notify(refusal);
+                return;
+            }
+            // Recognized builtin/scoped-out → handled here; unrecognized falls through
+            // and is sent to the engine as a prompt (extension command).
+            if (dispatchSlashCommand(trimmed, slashCtx)) {
+                this.editor.setText('');
+                return;
+            }
+        }
+        // Node dormant → there is NO broker to drive. Rather than emit a prompt/steer
+        // frame into a dead socket (the old "I typed and nothing happened" trap),
+        // deliver the text as a wake message: it revives the node and lands as the
+        // first thing it reads, and the reconnect supervisor repaints the live pane.
+        // Local-only — remote attach leaves onDormantSubmit unwired, so prompts fall
+        // through unchanged there. Slash commands are dispatched above and don't reach
+        // here, so `/quit`-style local commands keep working while dormant.
+        if (this.hooks.isDormant?.() === true && this.hooks.onDormantSubmit !== undefined) {
+            // Raw text (whitespace and all) — not `trimmed` — per Major 4: emptiness is
+            // judged on the trimmed view above, but what's actually delivered is the
+            // human's exact typed content, same as the prompt/steer frame below.
+            const expanded = this.expandImagePlaceholders(text);
+            this.hooks.onDormantSubmit(expanded);
+            this.editor.addToHistory(trimmed);
+            this.editor.setText('');
+            this.clearPastedImages();
+            return;
+        }
+        // `!cmd` / `!!cmd` → run bash in the engine and inject output into context,
+        // WITHOUT starting an agent turn (pi-native `!` semantics). `!!` withholds
+        // the output from the LLM. The broker relays the run as bash_* frames.
+        if (trimmed.startsWith('!')) {
+            const excludeFromContext = trimmed.startsWith('!!');
+            const command = trimmed.slice(excludeFromContext ? 2 : 1).trim();
+            if (command === '')
+                return; // bare `!`/`!!`: nothing to run
+            if (!this.emitDrive({ type: 'bash', command, excludeFromContext }))
+                return;
+            this.editor.addToHistory(trimmed);
+            this.editor.setText('');
+            return;
+        }
+        // Submit-while-streaming = steer (pi-native parity): interject into the
+        // running turn instead of queueing a fresh prompt. `isStreaming` is the
+        // broker snapshot's busy signal; the broker routes `steer` → session.steer()
+        // and `prompt` → session.prompt(). Idle / no state yet → prompt (safe default).
+        // Classification above (slash/dormant/bash/emptiness) reads the TRIMMED
+        // view, but the frame itself carries the exact editor text (post image-
+        // placeholder substitution) — leading/trailing whitespace is the human's,
+        // not ours to discard.
+        const expanded = this.expandImagePlaceholders(text);
+        const busy = this.state?.isStreaming === true;
+        const frame = busy
+            ? { type: 'steer', text: expanded }
+            : { type: 'prompt', text: expanded };
+        if (!this.emitDrive(frame))
+            return; // refused or too large — no frame emitted
+        this.editor.addToHistory(trimmed);
+        this.editor.setText('');
+        this.clearPastedImages();
+    }
+    handleFollowUp() {
+        const text = this.editor.getText();
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        // Same trimmed-classification/original-content split as handleSubmit's
+        // prompt/steer frame: emptiness is judged on the trimmed view, but the
+        // sent text is the exact editor content (post image-placeholder
+        // substitution), whitespace and all.
+        if (!this.emitDrive({ type: 'follow_up', text: this.expandImagePlaceholders(text) }))
+            return;
+        this.editor.addToHistory(trimmed);
+        this.editor.setText('');
+        this.clearPastedImages();
+    }
+    /** Replace every `[Image #N]` token with the temp-file path of the image the
+     *  user pasted, so the agent receives a readable path even though the editor
+     *  only ever showed the clean placeholder. Unknown ordinals are left as-is. */
+    expandImagePlaceholders(text) {
+        if (this.pastedImages.size === 0)
+            return text;
+        return text.replace(/\[Image #(\d+)\]/g, (match, digits) => {
+            const path = this.pastedImages.get(Number(digits));
+            return path ?? match;
+        });
+    }
+    /** Drop the pasted-image registry and reset the ordinal counter — called once
+     *  a submit has consumed the editor text. */
+    clearPastedImages() {
+        this.pastedImages.clear();
+        this.pasteSeq = 0;
+    }
+    /** Ctrl+G / app.editor.external — open the current editor text in $VISUAL/$EDITOR
+     *  and load the saved result back. Ported from pi's `openExternalEditor`: stop
+     *  the TUI to release the terminal, run the editor with inherited stdio, and on
+     *  a clean exit (status 0) replace the editor text; the socket keeps running in
+     *  the background throughout. */
+    async openExternalEditor() {
+        const editorCmd = process.env.VISUAL || process.env.EDITOR;
+        if (!editorCmd) {
+            this.notify('No editor configured — set $VISUAL or $EDITOR');
+            return;
+        }
+        const editorWithExpanded = this.editor;
+        const currentText = editorWithExpanded.getExpandedText?.() ?? this.editor.getText();
+        const tmpFile = join(tmpdir(), `crtr-attach-editor-${Date.now()}.pi.md`);
+        try {
+            writeFileSync(tmpFile, currentText, 'utf-8');
+            this.tui.stop();
+            // Split on spaces so `code --wait`-style commands keep their args.
+            const [cmd, ...args] = editorCmd.split(' ');
+            process.stdout.write(`Launching external editor: ${editorCmd}\nThe viewer resumes when it exits.\n`);
+            const status = await new Promise((resolve) => {
+                const child = spawn(cmd, [...args, tmpFile], {
+                    stdio: 'inherit',
+                    shell: process.platform === 'win32',
+                });
+                child.on('error', () => resolve(null));
+                child.on('close', (code) => resolve(code));
+            });
+            if (status === 0) {
+                this.editor.setText(readFileSync(tmpFile, 'utf-8').replace(/\n$/, ''));
+            }
+        }
+        catch (err) {
+            this.notify(`External editor failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            try {
+                unlinkSync(tmpFile);
+            }
+            catch {
+                /* ignore temp-file cleanup errors */
+            }
+            this.tui.start();
+            this.tui.requestRender(true);
+        }
+    }
+    /** Alt+Up / app.message.dequeue — clear the broker's queued steering + follow-up
+     *  messages and restore them to the editor, prepended to any in-progress text
+     *  (pi's `restoreQueuedMessagesToEditor`: queued text first, joined by blank
+     *  lines). A read-AND-mutate op over the correlated request channel. */
+    async handleDequeue() {
+        const reason = this.readOnlyReason();
+        if (reason !== undefined) {
+            this.notify(`${reason} — cannot restore queued messages`);
+            return;
+        }
+        if (this.hooks.onRequest === undefined) {
+            this.notify("Restoring queued messages isn't available in this viewer");
+            return;
+        }
+        let reply;
+        try {
+            reply = await this.hooks.onRequest({ type: 'dequeue' });
+        }
+        catch (err) {
+            this.notify(`Could not restore queued messages: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        if (reply.kind !== 'dequeue') {
+            this.notify('Unexpected reply restoring queued messages');
+            return;
+        }
+        const queued = [...reply.steering, ...reply.followUp];
+        if (queued.length === 0) {
+            this.notify('No queued messages to restore');
+            return;
+        }
+        const combined = [queued.join('\n\n'), this.editor.getText()].filter((t) => t.trim()).join('\n\n');
+        this.editor.setText(combined);
+        this.tui.requestRender();
+        this.notify(`Restored ${queued.length} queued message${queued.length > 1 ? 's' : ''} to editor`);
+    }
+    /** Send a drive frame iff the WHOLE encoded frame fits under MAX_FRAME_BYTES
+     *  (the broker destroys the socket on any line over its 24 MiB read cap). Over
+     *  the ceiling → notify + refuse without sending a socket-destroying overflow. */
+    emitDrive(frame) {
+        let bytes;
+        try {
+            bytes = Buffer.byteLength(encodeFrame(frame));
+        }
+        catch {
+            this.notify('Message could not be encoded');
+            return false;
+        }
+        if (bytes > MAX_FRAME_BYTES) {
+            const mib = Math.round(bytes / (1024 * 1024));
+            this.notify(`Message too large to send (${mib} MiB) — shorten the text or remove an attached image`);
+            return false;
+        }
+        return this.emitCommand(frame);
+    }
+    async handlePaste() {
+        try {
+            const result = await readClipboardImage();
+            if (!result) {
+                this.notify('No image in the clipboard');
+                return;
+            }
+            // The clipboard layer read an image but DROPPED it — surface the reason.
+            if (!result.image) {
+                this.notify(result.note ?? 'Image not pasted');
+                return;
+            }
+            // Persist to a temp file (the agent reads the image off disk instead of
+            // relying on inline base64 the viewer can't render), then attach it as an
+            // `[Image #N]` token (see attachImage).
+            const path = writeClipboardImageToFile(result.image);
+            this.attachImage(path, result.note);
+        }
+        catch {
+            this.notify('Could not read the clipboard image');
+        }
+    }
+    /** Register an image path in the paste registry and splice a clean `[Image #N]`
+     *  token into the editor at the caret instead of the raw path. On submit the
+     *  token is expanded back to the path (see expandImagePlaceholders), so the
+     *  agent reads the image off disk. Shared by clipboard paste and drag-drop. */
+    attachImage(path, note) {
+        const n = ++this.pasteSeq;
+        this.pastedImages.set(n, path);
+        const cur = this.editor.getText();
+        const sep = cur && !/\s$/.test(cur) ? ' ' : '';
+        this.editor.insertTextAtCursor(`${sep}[Image #${n}] `);
+        this.notify(note ? `Image #${n} attached (${note})` : `Image #${n} attached`);
+        this.tui.requestRender();
+    }
+    notify(message) {
+        this.hooks.onNotice?.(message);
+    }
+}