@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/clients/attach/config-load.js

@@ -0,0 +1,113 @@
+// config-load.ts — load the user's pi keybindings + theme for `crtr attach` (M8).
+//
+// These loaders are CLI-layer: pi does the *resolution* (the KeybindingsManager
+// matcher, `initTheme`) but the FILE reads are not reusable from pi, so we own
+// them. We read pi's own config locations so an attach viewer honors the same
+// `~/.pi/agent/keybindings.json` + theme the user already configured for pi.
+//
+// THE KEYBINDINGS MANAGER. pi's app-level KeybindingsManager (`core/keybindings`,
+// with `.create()` + the `app.*` definition table `KEYBINDINGS`) is NOT exported
+// — only its TYPE is re-exported, and the `KEYBINDINGS` const not at all. So we
+// construct pi-tui's KeybindingsManager (the base class CustomEditor actually
+// matches against) over the merged definition set: pi-tui's `TUI_KEYBINDINGS`
+// (editor/cursor/select bindings) + a VENDORED copy of pi's `app.*` editor
+// bindings below (required — CustomEditor.handleInput gates onEscape/onPasteImage/
+// onAction on `keybindings.matches(data, "app.*")`, so without the app defs those
+// never fire). We also register it globally via `setKeybindings` so the reused
+// pi-tui components (SelectList autocomplete, the dialog editor) honor overrides.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { KeybindingsManager, TUI_KEYBINDINGS, setKeybindings, } from '@earendil-works/pi-tui';
+import { initTheme } from '@earendil-works/pi-coding-agent';
+/** pi's user config dir: `~/.pi/agent/`. */
+export function defaultAgentDir() {
+    return join(homedir(), '.pi', 'agent');
+}
+/**
+ * pi's `app.*` editor keybindings — VENDORED from pi `core/keybindings.ts`
+ * `KEYBINDINGS` (the const is not exported; review-C1 pattern). This is the
+ * subset CustomEditor's main editor consults; the selector-internal bindings
+ * (`app.tree.*`, `app.models.*`, session delete/rename) are omitted because the
+ * attach viewer does not open those selectors in Phase 4. Re-sync on each SDK
+ * bump against `core/keybindings.js`.
+ */
+const APP_KEYBINDINGS = {
+    'app.interrupt': { defaultKeys: 'escape', description: 'Cancel or abort' },
+    'app.clear': { defaultKeys: 'ctrl+c', description: 'Clear editor' },
+    'app.exit': { defaultKeys: 'ctrl+d', description: 'Exit when editor is empty' },
+    'app.suspend': { defaultKeys: 'ctrl+z', description: 'Suspend to background' },
+    'app.thinking.cycle': { defaultKeys: 'shift+tab', description: 'Cycle thinking level' },
+    'app.model.cycleForward': { defaultKeys: 'ctrl+p', description: 'Cycle to next model' },
+    'app.model.cycleBackward': { defaultKeys: 'shift+ctrl+p', description: 'Cycle to previous model' },
+    'app.model.select': { defaultKeys: 'ctrl+l', description: 'Open model selector' },
+    'app.tools.expand': { defaultKeys: 'ctrl+o', description: 'Toggle tool output' },
+    'app.thinking.toggle': { defaultKeys: 'ctrl+t', description: 'Toggle thinking blocks' },
+    'app.editor.external': { defaultKeys: 'ctrl+g', description: 'Open external editor' },
+    'app.message.followUp': { defaultKeys: 'alt+enter', description: 'Queue follow-up message' },
+    'app.message.dequeue': { defaultKeys: 'alt+up', description: 'Restore queued messages' },
+    'app.clipboard.pasteImage': { defaultKeys: ['alt+v', 'ctrl+v'], description: 'Paste image from clipboard' },
+    'app.session.new': { defaultKeys: [], description: 'Start a new session' },
+    'app.session.tree': { defaultKeys: [], description: 'Open session tree' },
+    'app.session.fork': { defaultKeys: [], description: 'Fork current session' },
+    'app.session.resume': { defaultKeys: [], description: 'Resume a session' },
+};
+/**
+ * Read `~/.pi/agent/keybindings.json` (if present) and return the user's binding
+ * overrides. Tolerates a flat `{action: keys}` map or a `{keybindings: {...}}`
+ * wrapper; a missing/malformed file → `undefined` (fall back to defaults).
+ */
+export function loadUserKeybindings(agentDir = defaultAgentDir()) {
+    try {
+        const raw = JSON.parse(readFileSync(join(agentDir, 'keybindings.json'), 'utf8'));
+        const obj = raw && typeof raw === 'object' && 'keybindings' in raw
+            ? raw.keybindings
+            : raw;
+        if (!obj || typeof obj !== 'object')
+            return undefined;
+        return obj;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the KeybindingsManager the attach viewer drives input with: TUI defaults
+ * + vendored `app.*` defs, with the user's overrides applied, registered as the
+ * global pi-tui keybindings so reused components pick up the same bindings.
+ * (`as unknown as` bridges the readonly `TUI_KEYBINDINGS`/string-literal defs to
+ * the mutable `KeybindingDefinitions` param — vendoring cast, no behavior change.)
+ */
+export function createKeybindingsManager(agentDir = defaultAgentDir()) {
+    const definitions = { ...TUI_KEYBINDINGS, ...APP_KEYBINDINGS };
+    const km = new KeybindingsManager(definitions, loadUserKeybindings(agentDir));
+    setKeybindings(km);
+    return km;
+}
+/**
+ * The user's theme name from pi settings — project (`<cwd>/.pi/settings.json`)
+ * overrides global (`~/.pi/agent/settings.json`). `undefined` → pi's default.
+ */
+export function loadThemeName(opts) {
+    const files = [
+        join(opts?.cwd ?? process.cwd(), '.pi', 'settings.json'),
+        join(opts?.agentDir ?? defaultAgentDir(), 'settings.json'),
+    ];
+    for (const file of files) {
+        try {
+            const raw = JSON.parse(readFileSync(file, 'utf8'));
+            if (raw && typeof raw === 'object' && typeof raw.theme === 'string') {
+                return raw.theme;
+            }
+        }
+        catch {
+            /* missing/malformed — try the next location */
+        }
+    }
+    return undefined;
+}
+/** Resolve + activate the user's theme so the reused pi components (markdown,
+ *  editor, select-list themes) render at parity with the user's pi. */
+export function applyTheme(opts) {
+    initTheme(loadThemeName(opts));
+}

package/dist/clients/attach/extension-dialogs.d.ts

@@ -0,0 +1,29 @@
+import { KeybindingsManager, type TUI } from '@earendil-works/pi-tui';
+import type { RpcExtensionUIRequest, RpcExtensionUIResponse } from '../../core/runtime/broker-protocol.js';
+/** Handle for a rendered dialog: tear it down (without responding) when the
+ *  request is superseded — e.g. the broker resolves it on its own timeout, or a
+ *  control handoff re-routes it. */
+export interface DialogHandle {
+    dismiss(): void;
+}
+/** The 4 user-blocking dialog methods. The other 5 RpcExtensionUIRequest methods
+ *  are non-blocking display ops (notify/setStatus/setWidget/setTitle/
+ *  set_editor_text) the broker never forwards as a request. */
+export declare function isBlockingDialog(req: RpcExtensionUIRequest): boolean;
+/**
+ * Render a blocking extension dialog as a focused overlay over `tui`, and resolve
+ * by invoking `onRespond` with the matching `extension_ui_response` (or a
+ * `cancelled` response on user-cancel/timeout). Returns a {@link DialogHandle}
+ * whose `dismiss()` removes the overlay without responding (idempotent; safe to
+ * call after the dialog already resolved).
+ *
+ * @param keybindings - used only by the `editor` dialog, which calls
+ *   `keybindings.matches(key, "app.editor.external")` for the Ctrl+G external-editor
+ *   shortcut. Defaults to a fresh `KeybindingsManager(TUI_KEYBINDINGS)` — that
+ *   knows the base TUI bindings but not pi's app-level `app.editor.external`, so
+ *   Ctrl+G is inert until the input controller (T6) passes the app keybindings
+ *   manager. `ExtensionEditorComponent` is typed against pi's CORE
+ *   KeybindingsManager (a subclass of pi-tui's), so we widen via the constructor's
+ *   own parameter type rather than importing the core class (type-only export).
+ */
+export declare function renderDialog(tui: TUI, req: RpcExtensionUIRequest, onRespond: (resp: RpcExtensionUIResponse) => void, keybindings?: KeybindingsManager): DialogHandle;

package/dist/clients/attach/extension-dialogs.js

@@ -0,0 +1,101 @@
+// extension-dialogs.ts — the blocking-dialog renderer for `crtr attach` (T5).
+//
+// The broker forwards an extension's user-blocking UI request as an
+// `extension_ui_request` frame (RpcExtensionUIRequest). The viewer renders it
+// with pi's matching exported component and ships the resolved
+// `extension_ui_response` (RpcExtensionUIResponse) back over the socket.
+//
+// Only the 4 blocking methods carry behavior — and they are the only ones the
+// broker ever routes as a request: `makeBrokerUiContext` (broker.ts) no-ops
+// notify/setStatus/setWidget/setTitle/set_editor_text, so those never arrive as
+// a blocking dialog. `isBlockingDialog` lets the caller filter cleanly; for a
+// non-blocking method, `renderDialog` returns an inert handle (no overlay, no
+// response — there is nothing to answer).
+//
+// Mapping (mirrors interactive-mode.js): select → ExtensionSelectorComponent;
+// confirm → the SAME selector over ["Yes","No"] (pi has no separate confirm
+// component, :1658); input → ExtensionInputComponent; editor →
+// ExtensionEditorComponent. The select/input components run their own
+// timeout/countdown when `req.timeout` is present; editor takes none. The broker
+// ALSO arms a default timeout, so a dialog may be superseded by the broker
+// resolving first — `dismiss()` tears the overlay down cleanly without
+// responding (the response would be a no-op the broker drops by id).
+import { KeybindingsManager, TUI_KEYBINDINGS, } from '@earendil-works/pi-tui';
+import { ExtensionEditorComponent, ExtensionInputComponent, ExtensionSelectorComponent, } from '@earendil-works/pi-coding-agent';
+/** The 4 user-blocking dialog methods. The other 5 RpcExtensionUIRequest methods
+ *  are non-blocking display ops (notify/setStatus/setWidget/setTitle/
+ *  set_editor_text) the broker never forwards as a request. */
+export function isBlockingDialog(req) {
+    return (req.method === 'select' ||
+        req.method === 'confirm' ||
+        req.method === 'input' ||
+        req.method === 'editor');
+}
+const INERT = { dismiss: () => { } };
+const OVERLAY_OPTIONS = { anchor: 'center', width: '70%', maxHeight: '80%' };
+/**
+ * Render a blocking extension dialog as a focused overlay over `tui`, and resolve
+ * by invoking `onRespond` with the matching `extension_ui_response` (or a
+ * `cancelled` response on user-cancel/timeout). Returns a {@link DialogHandle}
+ * whose `dismiss()` removes the overlay without responding (idempotent; safe to
+ * call after the dialog already resolved).
+ *
+ * @param keybindings - used only by the `editor` dialog, which calls
+ *   `keybindings.matches(key, "app.editor.external")` for the Ctrl+G external-editor
+ *   shortcut. Defaults to a fresh `KeybindingsManager(TUI_KEYBINDINGS)` — that
+ *   knows the base TUI bindings but not pi's app-level `app.editor.external`, so
+ *   Ctrl+G is inert until the input controller (T6) passes the app keybindings
+ *   manager. `ExtensionEditorComponent` is typed against pi's CORE
+ *   KeybindingsManager (a subclass of pi-tui's), so we widen via the constructor's
+ *   own parameter type rather than importing the core class (type-only export).
+ */
+export function renderDialog(tui, req, onRespond, keybindings) {
+    if (!isBlockingDialog(req))
+        return INERT;
+    let done = false;
+    let handle;
+    let component;
+    const teardown = () => {
+        handle?.hide();
+        const disposable = component;
+        try {
+            disposable?.dispose?.();
+        }
+        catch {
+            /* ignore dispose errors during teardown */
+        }
+    };
+    const respond = (resp) => {
+        if (done)
+            return;
+        done = true;
+        teardown();
+        onRespond(resp);
+    };
+    const cancel = () => respond({ type: 'extension_ui_response', id: req.id, cancelled: true });
+    switch (req.method) {
+        case 'select':
+            component = new ExtensionSelectorComponent(req.title, req.options, (option) => respond({ type: 'extension_ui_response', id: req.id, value: option }), cancel, { tui, timeout: req.timeout });
+            break;
+        case 'confirm':
+            component = new ExtensionSelectorComponent(`${req.title}\n${req.message}`, ['Yes', 'No'], (option) => respond({ type: 'extension_ui_response', id: req.id, confirmed: option === 'Yes' }), cancel, { tui, timeout: req.timeout });
+            break;
+        case 'input':
+            component = new ExtensionInputComponent(req.title, req.placeholder, (value) => respond({ type: 'extension_ui_response', id: req.id, value }), cancel, { tui, timeout: req.timeout });
+            break;
+        case 'editor':
+            component = new ExtensionEditorComponent(tui, (keybindings ?? new KeybindingsManager(TUI_KEYBINDINGS)), req.title, req.prefill, (value) => respond({ type: 'extension_ui_response', id: req.id, value }), cancel);
+            break;
+        default:
+            return INERT;
+    }
+    handle = tui.showOverlay(component, OVERLAY_OPTIONS);
+    return {
+        dismiss: () => {
+            if (done)
+                return;
+            done = true;
+            teardown();
+        },
+    };
+}

package/dist/clients/attach/input-controller.d.ts

@@ -0,0 +1,54 @@
+import type { CustomEditor } from '@earendil-works/pi-coding-agent';
+import type { KeybindingsManager, TUI } from '@earendil-works/pi-tui';
+import { type BrokerSnapshot, type ClientToBroker, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from '../../core/runtime/broker-protocol.js';
+export interface InputControllerHooks {
+    /** Send a command frame to the broker. */
+    onCommand: (frame: ClientToBroker) => void;
+    /** Answer a blocking extension dialog. */
+    onDialogResponse: (resp: RpcExtensionUIResponse) => void;
+    /** OPTIONAL (additive to the fixed interface): surface a transient notice in
+     *  the viewer. The InputController does not own the layout (T5/T7 do), so it
+     *  reports notices up the same way it reports commands. Absent → notices are
+     *  dropped silently. */
+    onNotice?: (message: string) => void;
+}
+export declare class InputController {
+    private readonly tui;
+    private readonly editor;
+    private readonly keybindings;
+    private readonly hooks;
+    /** Images pasted since the last send, attached to the next prompt/follow-up. */
+    private pendingImages;
+    /** Running base64-byte total of `pendingImages` (review M2 aggregate budget). */
+    private pendingImageBytes;
+    /** The currently-rendered blocking dialog, if any (for supersede/dismiss). */
+    private dialog;
+    /** Latest engine state from `welcome`/`session_info_changed` (for `/session`). */
+    private state;
+    constructor(tui: TUI, editor: CustomEditor, keybindings: KeybindingsManager, hooks: InputControllerHooks);
+    /** Render a blocking extension dialog and route its answer to the broker.
+     *  Supersedes any dialog already on screen (e.g. a re-route on control
+     *  handoff) by dismissing it first. */
+    attachDialog(req: RpcExtensionUIRequest): void;
+    /** Feed the latest engine state so read-only commands (e.g. `/session`) report
+     *  current values. Optional; the controller works without it. */
+    setState(state: BrokerSnapshot['state']): void;
+    private wire;
+    private slashContext;
+    private handleSubmit;
+    private handleFollowUp;
+    /** 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 so the caller leaves the editor + pending
+     *  images intact for the user to trim, never a socket-destroying overflow. */
+    private emitDrive;
+    private handlePaste;
+    /** Snapshot the pending images as an `images?` payload (undefined when none)
+     *  WITHOUT clearing — so a frame refused by `emitDrive` (too large) keeps them
+     *  for the user to trim. The caller clears via `clearPendingImages` only after a
+     *  successful send. */
+    private pendingImagesPayload;
+    /** Drop all pending images + reset the aggregate byte counter (after a send). */
+    private clearPendingImages;
+    private notify;
+}

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

@@ -0,0 +1,204 @@
+// input-controller.ts — the input half of `crtr 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 `attach-cmd.ts` constructs it and wires the socket.
+//
+// Keybinding matching is delegated to CustomEditor + its KeybindingsManager
+// (built by config-load 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 { BROKER_READ_CAPS, encodeFrame, } from '../../core/runtime/broker-protocol.js';
+import { renderDialog } from './extension-dialogs.js';
+import { readClipboardImage } from './clipboard-image.js';
+import { dispatchSlashCommand, isSlashCommand } from './slash-commands.js';
+/** Aggregate budget for images held for the next message (review M2). A drained
+ *  prompt/steer/follow_up frame inlines ALL pending images as base64 in a single
+ *  frame; these ceilings keep the images[] portion well within the broker's
+ *  24 MiB line cap. Each clipboard image is ≤ 3 MiB base64 (clipboard-image
+ *  MAX_BYTES), so the worst case is MAX_PENDING_IMAGES × 3 MiB = 12 MiB. A paste
+ *  that would exceed EITHER bound is refused (not accumulated). The WHOLE frame
+ *  (images + unbounded text + JSON envelope) is then bounded airtight by the
+ *  MAX_FRAME_BYTES guard in `emitDrive` — this budget alone is not enough, since
+ *  `text` is otherwise unbounded. */
+const MAX_PENDING_IMAGE_BYTES = 16 * 1024 * 1024;
+const MAX_PENDING_IMAGES = 4;
+/** 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 + base64 images[] + JSON envelope), so the cap holds no
+ *  matter how the bytes split — closing the gap where a large text paste plus
+ *  max images could otherwise overflow and tear down the socket. */
+const MAX_FRAME_BYTES = BROKER_READ_CAPS.maxLineBytes - 4 * 1024 * 1024;
+export class InputController {
+    tui;
+    editor;
+    keybindings;
+    hooks;
+    /** Images pasted since the last send, attached to the next prompt/follow-up. */
+    pendingImages = [];
+    /** Running base64-byte total of `pendingImages` (review M2 aggregate budget). */
+    pendingImageBytes = 0;
+    /** The currently-rendered blocking dialog, if any (for supersede/dismiss). */
+    dialog;
+    /** Latest engine state from `welcome`/`session_info_changed` (for `/session`). */
+    state;
+    constructor(tui, editor, keybindings, hooks) {
+        this.tui = tui;
+        this.editor = editor;
+        this.keybindings = keybindings;
+        this.hooks = hooks;
+        this.wire();
+    }
+    /** Render a blocking extension dialog and route its answer to the broker.
+     *  Supersedes any dialog already on screen (e.g. a re-route on control
+     *  handoff) by dismissing it first. */
+    attachDialog(req) {
+        this.dialog?.dismiss();
+        this.dialog = renderDialog(this.tui, req, (resp) => {
+            this.dialog = undefined;
+            this.hooks.onDialogResponse(resp);
+        }, this.keybindings);
+        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 / app.interrupt → abort the running turn.
+        this.editor.onEscape = () => this.hooks.onCommand({ type: 'abort' });
+        // Ctrl+V / Alt+V → read clipboard image, hold it for the next message.
+        this.editor.onPasteImage = () => {
+            void this.handlePaste();
+        };
+        // Keyboard shortcuts that map 1:1 to a frame needing no engine-side data.
+        this.editor.onAction('app.session.new', () => this.hooks.onCommand({ type: 'new_session' }));
+        this.editor.onAction('app.model.cycleForward', () => this.hooks.onCommand({ type: 'cycle_model' }));
+        this.editor.onAction('app.message.followUp', () => this.handleFollowUp());
+    }
+    slashContext() {
+        return {
+            send: (frame) => this.hooks.onCommand(frame),
+            notify: (message) => this.notify(message),
+            state: this.state,
+            cwd: process.cwd(),
+        };
+    }
+    handleSubmit(text) {
+        const trimmed = text.trim();
+        if (!trimmed && this.pendingImages.length === 0)
+            return;
+        if (trimmed && isSlashCommand(trimmed)) {
+            // Recognized builtin/scoped-out → handled here; unrecognized falls through
+            // and is sent to the engine as a prompt (extension command).
+            if (dispatchSlashCommand(trimmed, this.slashContext())) {
+                this.editor.setText('');
+                return;
+            }
+        }
+        const images = this.pendingImagesPayload();
+        // 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).
+        const busy = this.state?.isStreaming === true;
+        const frame = busy
+            ? { type: 'steer', text: trimmed, images }
+            : { type: 'prompt', text: trimmed, images };
+        if (!this.emitDrive(frame))
+            return; // too large — keep editor + pending to trim
+        this.clearPendingImages();
+        if (trimmed)
+            this.editor.addToHistory(trimmed);
+        this.editor.setText('');
+    }
+    handleFollowUp() {
+        const text = this.editor.getText().trim();
+        if (!text && this.pendingImages.length === 0)
+            return;
+        const images = this.pendingImagesPayload();
+        if (!this.emitDrive({ type: 'follow_up', text, images }))
+            return;
+        this.clearPendingImages();
+        if (text)
+            this.editor.addToHistory(text);
+        this.editor.setText('');
+    }
+    /** 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 so the caller leaves the editor + pending
+     *  images intact for the user to trim, never 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;
+        }
+        this.hooks.onCommand(frame);
+        return true;
+    }
+    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 (over its per-image
+            // ceiling) — surface the reason and attach nothing.
+            if (!result.image) {
+                this.notify(result.note ?? 'Image not attached');
+                return;
+            }
+            // Enforce the aggregate pending-image budget so the eventual drained frame
+            // stays under the broker cap: refuse a paste that would breach the count or
+            // byte ceiling rather than accumulate an over-cap images[] (review M2).
+            const bytes = Buffer.byteLength(result.image.data);
+            if (this.pendingImages.length + 1 > MAX_PENDING_IMAGES ||
+                this.pendingImageBytes + bytes > MAX_PENDING_IMAGE_BYTES) {
+                this.notify('Image not attached: pending image budget exceeded — send your message first');
+                return;
+            }
+            this.pendingImages.push(result.image);
+            this.pendingImageBytes += bytes;
+            this.notify(result.note
+                ? `Image attached (${result.note}) — sends with your next message`
+                : 'Image attached — sends with your next message');
+            this.tui.requestRender();
+        }
+        catch {
+            this.notify('Could not read the clipboard image');
+        }
+    }
+    /** Snapshot the pending images as an `images?` payload (undefined when none)
+     *  WITHOUT clearing — so a frame refused by `emitDrive` (too large) keeps them
+     *  for the user to trim. The caller clears via `clearPendingImages` only after a
+     *  successful send. */
+    pendingImagesPayload() {
+        return this.pendingImages.length === 0 ? undefined : this.pendingImages.slice();
+    }
+    /** Drop all pending images + reset the aggregate byte counter (after a send). */
+    clearPendingImages() {
+        this.pendingImages = [];
+        this.pendingImageBytes = 0;
+    }
+    notify(message) {
+        this.hooks.onNotice?.(message);
+    }
+}

package/dist/clients/attach/slash-commands.d.ts

@@ -0,0 +1,36 @@
+import type { AutocompleteItem, SlashCommand } from '@earendil-works/pi-tui';
+import type { BrokerSnapshot, ClientToBroker } from '../../core/runtime/broker-protocol.js';
+/** Everything a slash handler needs: the frame sink, a notice sink, the latest
+ *  engine state (for read-only commands like `/session`), and the cwd (for the
+ *  default `/export` path). */
+export interface SlashContext {
+    /** Send a command frame to the broker (= InputController hooks.onCommand). */
+    send: (frame: ClientToBroker) => void;
+    /** Surface a transient one-line notice in the viewer. */
+    notify: (message: string) => void;
+    /** Latest `welcome`/`session_info_changed` state, if the controller fed it. */
+    state?: BrokerSnapshot['state'];
+    /** cwd for the default `/export` path; defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/** True if `text` is a leading-slash command (vs. a normal prompt). */
+export declare function isSlashCommand(text: string): boolean;
+/**
+ * Parse + dispatch a leading-slash command. Returns `true` if it was handled
+ * (a recognized builtin or a scoped-out notice) — the caller then clears the
+ * editor and sends nothing else. Returns `false` for an UNRECOGNIZED command,
+ * which the caller forwards to the engine as a `prompt` (extension command).
+ */
+export declare function dispatchSlashCommand(text: string, ctx: SlashContext): boolean;
+/** Build slash-command autocomplete entries from the merged command list (the
+ *  broker's `get_commands` result, which T7 may inject) — defaults to the
+ *  vendored builtins. Shaped for pi-tui's `CombinedAutocompleteProvider`. */
+export declare function slashCommandList(commands?: ReadonlyArray<{
+    name: string;
+    description?: string;
+}>): SlashCommand[];
+/** Same list as flat autocomplete items (value/label/description). */
+export declare function commandAutocompleteItems(commands?: ReadonlyArray<{
+    name: string;
+    description?: string;
+}>): AutocompleteItem[];