@north-light/crouter 0.3.154

package/dist/clients/attach/input/clipboard-image.js

@@ -0,0 +1,237 @@
+// input/clipboard-image.ts — read the clipboard image for `crtr surface attach` (T6, review M1).
+//
+// pi's `readClipboardImage` is NOT re-exported (it lives behind a native
+// clipboard binding + Photon worker the package gates off `.`-only exports), so
+// we reimplement the READ by shelling out to the platform clipboard tool. macOS:
+// `pngpaste` is a faster path IF present, but it is NOT a built-in (`brew install
+// pngpaste`), so the authoritative read is the dependency-free `osascript` path
+// (`the clipboard as «class PNGf»` → temp PNG), which works on a stock Mac.
+// Linux: `wl-paste` on Wayland, `xclip` on X11. The reader DISTINGUISHES three
+// outcomes — got bytes, clipboard genuinely empty, or no clipboard tool / read
+// failure — so the caller's notice is accurate ("No image in the clipboard" vs a
+// precise "install xclip" / "osascript failed") instead of collapsing every
+// miss to "no image".
+//
+// The bytes are then resized AGGRESSIVELY through pi's exported `resizeImage`
+// (which is reusable, unlike the reader) so the base64 stays well within the
+// broker's client-read line cap (`BROKER_READ_CAPS.maxLineBytes` = 24 MiB).
+// `resizeImage`'s `maxBytes` is the BASE64-PAYLOAD ceiling (it compares the
+// encoded size, not raw bytes — see image-resize-core), so MAX_BYTES (3 MiB)
+// bounds the base64 itself, far under 24 MiB. `resizeImage` already tries PNG and
+// JPEG and picks the smaller, so it doubles as format normalization;
+// `convertToPng` is the fallback when the Photon resizer is unavailable. The
+// fallbacks (convertToPng / raw bytes) are NOT size-bounded by `resizeImage`, so
+// each is gated on the SAME MAX_BYTES base64 ceiling (review M1): over it → the
+// image is DROPPED with a user-visible note rather than shipped as an over-cap
+// frame that would overflow BROKER_READ_CAPS.maxLineBytes (24 MiB) and destroy
+// the viewer socket. The result is an `ImageContent` (pi-ai) ready to drop
+// straight into a `prompt`/`steer`/`follow_up` frame's `images?` array (or, when
+// dropped, a `note`-only result and no image).
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { convertToPng, formatDimensionNote, resizeImage, } from '@earendil-works/pi-coding-agent';
+/** Longest edge (px) the pasted image is resized to — aggressive, matches the
+ *  ~1568px long-edge guidance vision models use. */
+const MAX_EDGE = 1568;
+/** Largest BASE64 payload per image — the ceiling for BOTH paths: passed as
+ *  `resizeImage`'s `maxBytes` (which bounds the encoded base64, not raw bytes)
+ *  on the primary path, and compared against the fallbacks' base64 length. 3 MiB
+ *  base64, far under BROKER_READ_CAPS.maxLineBytes (24 MiB). */
+const MAX_BYTES = 3 * 1024 * 1024;
+/** Bound the shell read so a giant/garbage clipboard can't blow up memory. */
+const SPAWN_MAX_BUFFER = 64 * 1024 * 1024;
+const SPAWN_TIMEOUT_MS = 3000;
+/** Persist a (already-resized) clipboard image to a stable temp file and return
+ *  its absolute path, so the attach editor can drop the PATH inline into the
+ *  prompt instead of inlining base64 the agent can't see. The broker runs on the
+ *  same host, so a tmpdir path is readable by the engine. */
+export function writeClipboardImageToFile(image) {
+    const dir = join(tmpdir(), 'crtr-clip-images');
+    mkdirSync(dir, { recursive: true });
+    const ext = image.mimeType === 'image/jpeg' ? 'jpg' : 'png';
+    const path = join(dir, `paste-${Date.now()}-${process.pid}.${ext}`);
+    writeFileSync(path, Buffer.from(image.data, 'base64'));
+    return path;
+}
+/** Read + resize the current clipboard image. Returns `null` ONLY when the
+ *  clipboard genuinely holds no image; a `note`-only result means there is a
+ *  precise reason to surface (no clipboard tool, read failure, or an over-cap
+ *  drop). All best-effort — the caller shows a brief notice and carries on. */
+export async function readClipboardImage() {
+    const outcome = readRawClipboardImage();
+    const raw = outcome.image;
+    if (!raw) {
+        // No bytes. A `note` means a precise reason worth surfacing (no clipboard
+        // tool, or a read failure) — return it so the caller shows it instead of the
+        // generic "No image in the clipboard". No note → the clipboard is genuinely
+        // empty → null (caller shows the generic notice).
+        return outcome.note ? { note: outcome.note } : null;
+    }
+    // Primary path: resize aggressively. Handles format (PNG/JPEG) + size bound.
+    const resized = await resizeImage(new Uint8Array(raw.bytes), raw.mimeType, {
+        maxWidth: MAX_EDGE,
+        maxHeight: MAX_EDGE,
+        maxBytes: MAX_BYTES,
+    });
+    if (resized) {
+        return {
+            image: { type: 'image', data: resized.data, mimeType: resized.mimeType },
+            note: resized.wasResized ? formatDimensionNote(resized) : undefined,
+        };
+    }
+    // Fallback: the Photon resizer is unavailable — at least normalize to PNG so
+    // the engine gets a format it accepts. Capped at MAX_BYTES (base64).
+    const png = await convertToPng(raw.bytes.toString('base64'), raw.mimeType);
+    if (png)
+        return capped({ type: 'image', data: png.data, mimeType: png.mimeType });
+    // Last resort: ship the raw bytes — also capped, never an over-cap frame.
+    return capped({ type: 'image', data: raw.bytes.toString('base64'), mimeType: raw.mimeType });
+}
+/** Gate a FALLBACK image on the per-image base64 ceiling (MAX_BYTES): under it →
+ *  attach; over → DROP with a user-visible note rather than ship a frame that
+ *  would overflow the broker's 24 MiB read cap and destroy the viewer socket.
+ *  base64 is ASCII, so its byte length equals the bytes the frame puts on the
+ *  wire. */
+function capped(image) {
+    const encodedBytes = Buffer.byteLength(image.data);
+    if (encodedBytes <= MAX_BYTES)
+        return { image };
+    const mib = (n) => Math.round(n / (1024 * 1024));
+    return {
+        note: `Image not attached: ${mib(encodedBytes)} MiB exceeds the ${mib(MAX_BYTES)} MiB attach limit (clipboard resizer unavailable)`,
+    };
+}
+/** Shell out to the platform clipboard tool for raw image bytes. */
+function readRawClipboardImage() {
+    if (process.platform === 'darwin') {
+        return selectMacOutcome(run, readMacClipboardViaOsascript);
+    }
+    return selectLinuxOutcome(run, isWayland());
+}
+/** Pure macOS dispatch (the regression-test seam): try `pngpaste` if present,
+ *  else fall through to the native osascript read — a missing `pngpaste` must
+ *  NOT collapse to "no image", which was the stock-Mac bug. */
+export function selectMacOutcome(runTool, readNative) {
+    const fast = runTool('pngpaste', ['-']);
+    if (fast.bytes)
+        return { image: { bytes: fast.bytes, mimeType: 'image/png' } };
+    // pngpaste missing OR clipboard empty → osascript is authoritative.
+    return readNative();
+}
+/** Pure Linux dispatch (the regression-test seam): Wayland (`wl-paste`) first,
+ *  then X11 (`xclip`), PNG then JPEG. If NO tool binary was found, surface a
+ *  precise "install …" note; if a tool ran but found no image, report empty. */
+export function selectLinuxOutcome(runTool, wayland) {
+    let anyToolPresent = false;
+    if (wayland) {
+        const out = runTool('wl-paste', ['--type', 'image/png', '--no-newline']);
+        if (out.bytes)
+            return { image: { bytes: out.bytes, mimeType: 'image/png' } };
+        if (!out.missing)
+            anyToolPresent = true;
+    }
+    for (const mimeType of ['image/png', 'image/jpeg']) {
+        const out = runTool('xclip', ['-selection', 'clipboard', '-t', mimeType, '-o']);
+        if (out.bytes)
+            return { image: { bytes: out.bytes, mimeType } };
+        if (!out.missing)
+            anyToolPresent = true;
+    }
+    if (!anyToolPresent) {
+        return {
+            note: wayland
+                ? 'No clipboard tool found — install wl-clipboard (wl-paste) to paste images'
+                : 'No clipboard tool found — install xclip to paste images',
+        };
+    }
+    return {}; // a tool ran but the clipboard holds no image
+}
+/** AppleScript that writes the clipboard's PNG representation to the temp path
+ *  in `argv`. `the clipboard as «class PNGf»` THROWS when the clipboard has no
+ *  PNG-convertible image — caught → "NO_IMAGE" (a clean empty signal, distinct
+ *  from a failure). A write failure (after `set eof` already truncated the file)
+ *  closes the handle and returns "WRITE_FAILED" rather than swallowing the error
+ *  and reporting a false "OK" over a 0-byte/partial file — so "OK" reliably means
+ *  the full bytes are in the temp file, preserving the empty-vs-failure split. */
+const MAC_PNG_SCRIPT = `on run argv
+  set outPath to item 1 of argv
+  try
+    set pngData to (the clipboard as «class PNGf»)
+  on error
+    return "NO_IMAGE"
+  end try
+  set fh to open for access (POSIX file outPath) with write permission
+  try
+    set eof fh to 0
+    write pngData to fh
+    close access fh
+  on error
+    try
+      close access fh
+    end try
+    return "WRITE_FAILED"
+  end try
+  return "OK"
+end run`;
+/** Native, dependency-free macOS read: osascript (always present) writes the
+ *  clipboard PNG to a temp file we then read. Distinguishes empty ("NO_IMAGE")
+ *  from a genuine read failure so the caller's notice is accurate. */
+function readMacClipboardViaOsascript() {
+    const tmpFile = join(tmpdir(), `crtr-clip-${process.pid}-${Date.now()}.png`);
+    try {
+        const result = spawnSync('osascript', ['-e', MAC_PNG_SCRIPT, tmpFile], {
+            timeout: SPAWN_TIMEOUT_MS,
+            maxBuffer: SPAWN_MAX_BUFFER,
+            encoding: 'utf-8',
+        });
+        if (result.error || result.status !== 0) {
+            return { note: 'Could not read the clipboard (osascript failed)' };
+        }
+        const signal = (result.stdout ?? '').trim();
+        if (signal === 'NO_IMAGE')
+            return {}; // clipboard genuinely holds no image
+        if (signal !== 'OK')
+            return { note: 'Could not read the clipboard image' };
+        let bytes;
+        try {
+            bytes = readFileSync(tmpFile);
+        }
+        catch {
+            return { note: 'Could not read the clipboard image' };
+        }
+        return bytes.length > 0 ? { image: { bytes, mimeType: 'image/png' } } : {};
+    }
+    finally {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch {
+            /* ignore temp-file cleanup errors (NO_IMAGE never created it) */
+        }
+    }
+}
+function isWayland() {
+    return Boolean(process.env.WAYLAND_DISPLAY) || process.env.XDG_SESSION_TYPE === 'wayland';
+}
+/** Run a clipboard tool; return its stdout bytes, or a `missing` flag when the
+ *  binary isn't on PATH (so the caller can distinguish "no tool" from "no
+ *  image"). Any other failure (non-zero exit, timeout, empty output) → an empty
+ *  result ({}), i.e. the tool ran but yielded no image. */
+function run(command, args) {
+    const result = spawnSync(command, args, {
+        timeout: SPAWN_TIMEOUT_MS,
+        maxBuffer: SPAWN_MAX_BUFFER,
+    });
+    if (result.error) {
+        const missing = result.error.code === 'ENOENT';
+        return { missing };
+    }
+    if (result.status !== 0)
+        return {};
+    const stdout = result.stdout;
+    if (!stdout || stdout.length === 0)
+        return {};
+    return { bytes: Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout) };
+}

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

@@ -0,0 +1,210 @@
+import type { CustomEditor } from '@earendil-works/pi-coding-agent';
+import type { Component, KeybindingsManager, TUI } from '@earendil-works/pi-tui';
+import { type BrokerDataFrame, type ClientRole, type BrokerSnapshot, type ClientToBroker, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
+import type { ReadOpRequest } from '../../../core/broker-client/index.js';
+import { type Picker, type PickerControls } from '../overlays/pickers.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;
+    /** OPTIONAL: the canvas node this viewer is attached to — forwarded to the
+     *  slash context so `/promote` targets it (Unit Q wires it from runAttach). */
+    nodeId?: string;
+    /** OPTIONAL: the attached node's profile identity — forwarded to `/resume-node`
+     *  so canvas browse opens scoped to this profile. */
+    profileId?: string;
+    /** OPTIONAL: true for a REMOTE attach (`crtr surface attach --canvas`) —
+     *  forwarded to the slash context so it can structurally omit/no-op the
+     *  local-only native canvas commands (`/promote`, `/resume-node`, `/context`),
+     *  and (with {@link InputControllerHooks.role}) one half of the drive gate.
+     *  Defaults to `false` (local, unchanged) when absent. */
+    remote?: boolean;
+    /** OPTIONAL: this viewer's FIXED capability, resolved once for the hello
+     *  handshake (`resolveHelloRole`) and never renegotiated. `'observer'` makes
+     *  the viewer read-only: no drive frame is emitted, while reads (`onRequest`,
+     *  `get_commands`, the pickers' fetches) stay live. Absent → `'controller'`. */
+    role?: ClientRole;
+    /** OPTIONAL: toggle the GRAPH overlay — forwarded to the slash context so
+     *  `/graph` opens/closes it (Unit Q wires it from runAttach). */
+    onGraph?: () => void;
+    /** OPTIONAL: detach the viewer — forwarded to the slash context so `/quit`
+     *  tears down the TUI/socket (the engine keeps running). Wired by viewer.ts. */
+    onQuit?: () => void;
+    /** OPTIONAL: copy the last assistant message to the clipboard — forwarded to
+     *  the slash context so `/copy` works. Wired by viewer.ts (it owns ChatView). */
+    onCopy?: () => void;
+    /** OPTIONAL: recolor the editor's name chip — forwarded to the slash context
+     *  so `/color` paints it (`null` clears). Wired by viewer.ts (it owns the
+     *  TitledEditor). */
+    onColor?: (color: string | null) => void;
+    /** OPTIONAL: open the focused node's metadata dossier. */
+    onNodeMetadata?: () => void;
+    /** OPTIONAL: Ctrl+O / app.tools.expand — flip global tool-output expansion in
+     *  the render layer (ChatView owns the components). Absent → the key no-ops. */
+    onToggleToolsExpand?: () => void;
+    /** OPTIONAL: Ctrl+T / app.thinking.toggle — flip thinking-block visibility in
+     *  the render layer. Absent → the key no-ops. */
+    onToggleThinking?: () => void;
+    /** OPTIONAL: issue a correlated read-op and resolve with the broker's `data`
+     *  reply. MUST be wired by viewer.ts (`onRequest: (f) => socket.request(f)`)
+     *  for the native pickers to work; when absent every picker degrades to a
+     *  text-arg notice. */
+    onRequest?: (frame: ReadOpRequest) => Promise<BrokerDataFrame>;
+    /** OPTIONAL pair: mount/unmount a native picker INLINE in the viewer's layout
+     *  (viewer.ts slots it directly under the editor). When BOTH are wired,
+     *  showPicker uses them instead of a centered overlay; absent → overlay
+     *  fallback. The controller stays layout-agnostic either way (T5/T7 own it). */
+    onMountPicker?: (component: Component) => void;
+    onUnmountPicker?: () => void;
+    /** OPTIONAL: open the native /login provider picker (viewer-local auth flow). */
+    openLoginPicker?: () => void;
+    /** OPTIONAL: open the native /logout provider picker (viewer-local auth flow). */
+    openLogoutPicker?: () => void;
+    /** OPTIONAL: true while the attached node is DORMANT (no live broker to drive).
+     *  When true, a submitted prompt has no socket to reach, so `handleSubmit`
+     *  routes it through {@link onDormantSubmit} (a wake message) instead of
+     *  emitting into a dead socket. Wired by viewer.ts's reconnect supervisor. */
+    isDormant?: () => boolean;
+    /** OPTIONAL: deliver `text` as an inbox message that WAKES the dormant node
+     *  (revive + deliver), so the still-open viewer's input box just works. Wired
+     *  by viewer.ts to `cliClient().sendMessage`; absent (e.g. remote attach) →
+     *  the dormant-submit path is disabled and prompts fall through as before. */
+    onDormantSubmit?: (text: string) => void;
+}
+export declare class InputController {
+    private readonly tui;
+    private readonly editor;
+    private readonly keybindings;
+    private readonly hooks;
+    /** The currently-rendered blocking dialog, if any (for supersede/dismiss). */
+    private 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. */
+    private dialogId;
+    /** The currently-open native picker overlay, if any (for supersede/dismiss). */
+    private 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. */
+    private openSeq;
+    /** Latest engine state from `welcome`/`session_info_changed` (for `/session`). */
+    private state;
+    /** Timestamp of the last lone Esc, for double-tap → tree detection (0 = none). */
+    private lastEscapeAt;
+    /** 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). */
+    private pastedImages;
+    /** Monotonic paste counter — the `N` in `[Image #N]`. */
+    private pasteSeq;
+    constructor(tui: TUI, editor: CustomEditor, keybindings: KeybindingsManager, hooks: InputControllerHooks);
+    /** 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. */
+    private readOnlyReason;
+    /** 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. */
+    private emitCommand;
+    /** 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: 'forward' | 'backward'): void;
+    /** 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: RpcExtensionUIRequest): void;
+    /** 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: string): 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;
+    /** Send a command frame to the broker (picker selection sink). */
+    private send;
+    /** 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). */
+    private openPicker;
+    /** 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). */
+    private showPicker;
+    private openModelPicker;
+    /** 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. */
+    private openSessionPicker;
+    private openTreePicker;
+    private openForkPicker;
+    private openSettingsPicker;
+    private openScopedModelsPicker;
+    /** `/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. */
+    private openMcpPicker;
+    /** Open the transcript-backed file-review picker. The caller owns the popup
+     *  process and cursor insertion; this controller only owns picker lifetime. */
+    openFileReviewPicker(candidates: string[], cwd: string, onChoose: (file: string) => void): void;
+    /** 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. */
+    openAuthPicker(prepare: () => Promise<(controls: PickerControls) => Picker>): Promise<void>;
+    private handleSubmit;
+    private handleFollowUp;
+    /** 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. */
+    private expandImagePlaceholders;
+    /** Drop the pasted-image registry and reset the ordinal counter — called once
+     *  a submit has consumed the editor text. */
+    private clearPastedImages;
+    /** 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. */
+    private openExternalEditor;
+    /** 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. */
+    private handleDequeue;
+    /** 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. */
+    private emitDrive;
+    private handlePaste;
+    /** 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. */
+    private attachImage;
+    private notify;
+}