@north-light/crouter 0.3.154

package/dist/clients/attach/command.js

@@ -0,0 +1,96 @@
+// command.ts — the LIGHT `crtr surface attach` command definition.
+//
+// This module holds only the command metadata (help schema, flags) and the
+// thin `run` entry. It is deliberately kept OFF the heavy pi-coding-agent module
+// graph so that registering the `surface` subtree — for `surface view`,
+// `surface web`, `surface workspace`, `surface tmux-spread`, and every
+// `surface -h` render — costs a cheap command-framework load, not the ~363ms
+// ESM load of the esbuild-bundled attach viewer (`viewer.ts`, which pulls
+// pi-coding-agent's babel/highlight.js). The viewer runtime is dynamically
+// imported inside `run`, so the bundle loads ONLY when a viewer actually opens.
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { mark } from '../../core/timing.js';
+const attachToLeaf = defineLeaf({
+    name: 'to',
+    description: 'attach an interactive terminal viewer to a node (reviving it if dormant)',
+    whenToUse: 'you want to WATCH or DRIVE a headless node live in this pane — it connects over the node\'s unix socket to the broker hosting the engine and renders the same chat stream. Normal local attaches are writable; use --observer for read-only, or --canvas for a remote read-only view. A DORMANT node is revived first: crtrd runs reviveNode server-side, then the viewer streams over the broker\'s socket. The configured detach shortcuts leave the engine running',
+    help: {
+        name: 'attach to',
+        summary: 'attach a terminal viewer to a headless node\'s running broker (writable by default, --observer for read-only); configured detach shortcuts leave the engine running',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: true,
+                constraint: 'Node id to attach to. A dormant node is revived (server-side) before the viewer connects.',
+            },
+            {
+                kind: 'flag',
+                name: 'observer',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Attach READ-ONLY: request the observer role. Default local attaches request the writable controller role.',
+            },
+            {
+                kind: 'flag',
+                name: 'canvas',
+                type: 'string',
+                required: false,
+                constraint: 'Attach against a remote canvas target configured via `crtr canvas config add` instead of the local canvas — connects over a relayed WebSocket to the target\'s preview endpoint using the relay token from the 0600 secrets store. Omit for local (default): connects to the node\'s local unix socket, which must already exist in THIS machine\'s canvas.db. Does NOT honor `crtr canvas use` — this flag is the only way to attach remotely.',
+            },
+        ],
+        output: [
+            {
+                name: 'note',
+                type: 'string',
+                required: false,
+                constraint: 'Only set on the non-TTY/piped path (a static notice); the interactive path returns nothing.',
+            },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Takes over the current pane in raw mode and renders the node\'s live engine stream until you use a configured detach shortcut or the broker exits.',
+            'As a writable controller: sends prompts/steers/dialog answers to the engine over the socket. As observer: read-only. Multiple writable local viewers may drive the same broker.',
+            'A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects; this LOCAL process NEVER spawns pi and NEVER writes the session — it holds only a socket to the broker.',
+            'Outside a TTY (piped): prints a short notice and exits 0 — attach is an interactive program, not a pipe stage.',
+        ],
+    },
+    run: async (input) => {
+        const nodeId = input['node'];
+        const observer = input['observer'] ?? false;
+        const canvasName = input['canvas'];
+        // attach IS the in-pane interactive program — it only needs a TTY (crtr is
+        // tmux-only, but the pane itself is the surface). Non-TTY (piped) → static
+        // notice + exit, never a non-tmux interactive fallback. Guarded BEFORE the
+        // heavy import so a piped invocation never pays the viewer's load cost.
+        if (!process.stdout.isTTY) {
+            return {
+                note: `crtr surface attach is an interactive terminal viewer — run it in a tmux pane (a TTY), not a pipe. Node: ${nodeId}`,
+            };
+        }
+        // The viewer runtime (the pi-coding-agent-heavy bundle) loads only here.
+        mark('viewer.bundle_import_start');
+        const { runAttach } = await import('./viewer.js');
+        mark('viewer.bundle_loaded');
+        await runAttach(nodeId, observer, canvasName);
+        return;
+    },
+    render: (result) => (result['note'] !== undefined ? String(result['note']) : ''),
+});
+export function registerAttach() {
+    return defineBranch({
+        name: 'attach',
+        rootEntry: {
+            concept: 'a terminal viewer for a headless node — connect over its socket and drive (or watch) the live engine',
+            desc: 'attach a terminal viewer to a headless node',
+            useWhen: 'you want to open a headless node live in this pane — watch its engine stream and drive it by typing, without the node ever running pi in your window. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects over a unix socket; this local process never starts the engine itself. Configured detach shortcuts leave the engine running.',
+        },
+        help: {
+            name: 'attach',
+            summary: 'attach a terminal viewer to a headless node\'s running broker',
+            model: 'The branch opens a viewer in the current pane. A TTY is required; piped invocation prints a notice and exits. Normal local attaches request the writable controller role; --observer and --canvas are read-only. Multiple local writable viewers may watch and drive one broker. Configured detach shortcuts detach cleanly and the engine runs on. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects. If the broker exits, the viewer holds the pane and auto-reconnects — through a yield/refresh relaunch, and across dormancy until the node wakes again — reporting "broker gone" and exiting only when the node is terminal (done/dead/canceled) or deleted. This local process NEVER spawns pi or writes the session — it holds only a socket to the broker. --canvas <name> is the escape hatch for a node hosted on a different machine\'s canvas — see the leaf\'s own -h.',
+        },
+        children: [attachToLeaf],
+    });
+}

package/dist/clients/attach/config.d.ts

@@ -0,0 +1,91 @@
+import { KeybindingsManager, type KeybindingsConfig, type MarkdownTheme } from '@earendil-works/pi-tui';
+/** pi's user config dir: `~/.pi/agent/`. */
+export declare function defaultAgentDir(): string;
+/**
+ * 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 declare function loadUserKeybindings(agentDir?: string): KeybindingsConfig | undefined;
+export declare function createKeybindingsManager(agentDir?: string): KeybindingsManager;
+/** Register the manager on the editor's pi-tui instance too (see `editorPiTui`),
+ *  so the editor's newline/submit handling honors the same (user-overridden)
+ *  bindings as the rest of the viewer. Call once, after `createKeybindingsManager`. */
+export declare function mirrorKeybindingsToEditor(km: KeybindingsManager): Promise<void>;
+/** Mirror the negotiated kitty-keyboard-protocol flag onto the editor's pi-tui
+ *  instance (ProcessTerminal sets it only on OUR copy). Call after the terminal
+ *  has negotiated, i.e. after `tui.start()`. */
+export declare function mirrorKittyProtocolToEditor(active: boolean): Promise<void>;
+export declare function resolveFdPath(): Promise<string | null>;
+/**
+ * The user's theme name from pi settings — project (`<cwd>/.pi/settings.json`)
+ * overrides global (`~/.pi/agent/settings.json`). `undefined` → pi's default.
+ */
+export declare function loadThemeName(opts?: {
+    agentDir?: string;
+    cwd?: string;
+}): string | 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 declare function applyTheme(opts?: {
+    agentDir?: string;
+    cwd?: string;
+}): void;
+/**
+ * The named styling roles the attach chrome paints with, all theme-derived so the
+ * viewer matches whatever theme the user configured for pi. Each is a
+ * `str => str` colorizer applied to a whole token.
+ */
+export interface AttachPalette {
+    /** Headings / badges / panel titles — the theme accent (gold in the default). */
+    accent: (s: string) => string;
+    /** Live/active markers + the working spinner — the theme's bright accent (teal). */
+    active: (s: string) => string;
+    /** Informational values (model name, counts) — the theme link color (blue). */
+    info: (s: string) => string;
+    /** Secondary text — the theme muted gray. */
+    muted: (s: string) => string;
+    /** Least-important text — SGR faint (a style, not a hue). */
+    faint: (s: string) => string;
+    /** Border rules / frames — the theme border color. */
+    border: (s: string) => string;
+    /** Distinct-surface paint for a modal/overlay: wraps a WHOLE rendered line so
+     *  it sits on the theme's `selectedBg` background, edge to edge, re-asserting
+     *  the bg after every embedded full-reset so an inner `\x1b[0m` (a status dot,
+     *  the cursor bar) can't punch a hole in the surface. Closes with a bg-only
+     *  reset so the surface never bleeds past the line. */
+    surface: (s: string) => string;
+    /** Emphasis. */
+    bold: (s: string) => string;
+    /** Error text. pi's public theme API does NOT surface the `error` ThemeColor
+     *  (only markdown/select-list/settings-list derived colors are re-exported), so
+     *  this is the semantically-correct ANSI red — NOT an ad-hoc hardcode. */
+    error: (s: string) => string;
+    /** Warning / transient notices. Same constraint as `error` → ANSI yellow. */
+    warning: (s: string) => string;
+    /** Editor border for a SINGLE-`!` bash command (output IS added to the agent's
+     *  context). Dull/normal ANSI green — pi paints shell mode from its `bashMode`
+     *  theme color (default `green`), which pi does NOT re-export through its public
+     *  surface, so like `error`/`warning` this is the semantically-correct ANSI green. */
+    bashMode: (s: string) => string;
+    /** Editor border for a `!!` bash command (output is HIDDEN from the agent).
+     *  BRIGHT ANSI green, so the more consequential "agent won't see this" form
+     *  reads as visually hotter than the plain `!`. */
+    bashModeAlt: (s: string) => string;
+}
+/** Markdown theme for the attach transcript. Fenced code keeps pi's native
+ *  shape and syntax, but its content is painted on a distinct theme surface. */
+export declare function attachMarkdownTheme(): MarkdownTheme;
+/**
+ * Build the attach chrome's color palette from the LIVE theme. Call AFTER
+ * `applyTheme()` — the colors are pulled from pi's `getMarkdownTheme()` /
+ * `getSelectListTheme()`, which read the active theme singleton at call time.
+ *
+ * pi does not re-export the raw `Theme` instance (its `.` export map omits the
+ * `theme` const and `getEditorTheme`/`getTheme`), so the accent/border/muted hues
+ * are sourced from the markdown + select-list theme colorizers, which ARE
+ * re-exported and are themselves backed by `theme.fg(...)`. The two semantic
+ * colors pi never exposes through that surface — `error`/`warning` — fall back to
+ * standard ANSI red/yellow.
+ */
+export declare function attachPalette(): AttachPalette;

package/dist/clients/attach/config.js

@@ -0,0 +1,271 @@
+// config.ts — load the user's pi keybindings + theme for `crtr surface 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 { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { KeybindingsManager, TUI_KEYBINDINGS, setKeybindings, } from '@earendil-works/pi-tui';
+import { initTheme, getMarkdownTheme, getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { surfaceBgAnsi } from '../../core/runtime/surface-bg.js';
+/** 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' },
+    // Alt+Enter inserts a newline in the attach editor (shift+enter is unreliable
+    // across terminals), so the follow-up-queue action drops its alt+enter default
+    // to free the chord — see ATTACH_KEYBINDING_OVERRIDES below.
+    'app.message.followUp': { defaultKeys: [], 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.)
+ */
+/**
+ * Attach-specific default overrides applied OVER pi's TUI defaults. Alt+Enter
+ * inserts a newline here (the follow-up-queue action gives up its alt+enter
+ * default above), because shift+enter — pi's stock newline chord — does not
+ * transmit a distinct sequence in many terminals. User `keybindings.json` still
+ * wins on top of these (applied as the manager's override config).
+ */
+const ATTACH_KEYBINDING_OVERRIDES = {
+    'tui.input.newLine': { defaultKeys: ['shift+enter', 'alt+enter'], description: 'Insert new line' },
+};
+export function createKeybindingsManager(agentDir = defaultAgentDir()) {
+    const definitions = {
+        ...TUI_KEYBINDINGS,
+        ...APP_KEYBINDINGS,
+        ...ATTACH_KEYBINDING_OVERRIDES,
+    };
+    const km = new KeybindingsManager(definitions, loadUserKeybindings(agentDir));
+    setKeybindings(km);
+    return km;
+}
+/**
+ * pi-coding-agent's `CustomEditor` resolves `@earendil-works/pi-tui` from its OWN
+ * `node_modules`, which can be a SEPARATE module instance from the one this file
+ * imports (a non-deduped install leaves a nested copy). The editor's newline /
+ * submit handling reads keybindings AND the kitty-protocol flag from THAT
+ * instance's module-globals via `getKeybindings()` / `isKittyProtocolActive()`,
+ * so state we set only on our copy is invisible to it — the user's `alt+enter`
+ * newline binding never applies and Enter falls through to submit. We mirror our
+ * state onto the editor's instance too. When the install IS deduped both resolve
+ * to one module and the mirror is a harmless re-set. Best-effort: a resolution /
+ * import failure leaves the editor on our copy's state (the deduped case).
+ */
+let editorPiTuiPromise;
+function editorPiTui() {
+    if (!editorPiTuiPromise) {
+        editorPiTuiPromise = (async () => {
+            try {
+                const pcaEntry = import.meta.resolve('@earendil-works/pi-coding-agent');
+                const piTuiPath = createRequire(pcaEntry).resolve('@earendil-works/pi-tui');
+                return (await import(pathToFileURL(piTuiPath).href));
+            }
+            catch {
+                return undefined;
+            }
+        })();
+    }
+    return editorPiTuiPromise;
+}
+/** Register the manager on the editor's pi-tui instance too (see `editorPiTui`),
+ *  so the editor's newline/submit handling honors the same (user-overridden)
+ *  bindings as the rest of the viewer. Call once, after `createKeybindingsManager`. */
+export async function mirrorKeybindingsToEditor(km) {
+    (await editorPiTui())?.setKeybindings(km);
+}
+/** Mirror the negotiated kitty-keyboard-protocol flag onto the editor's pi-tui
+ *  instance (ProcessTerminal sets it only on OUR copy). Call after the terminal
+ *  has negotiated, i.e. after `tui.start()`. */
+export async function mirrorKittyProtocolToEditor(active) {
+    (await editorPiTui())?.setKittyProtocolActive(active);
+}
+/**
+ * Resolve the `fd` binary path the @-mention file picker needs. pi-tui's
+ * `CombinedAutocompleteProvider` only returns file suggestions when handed an
+ * `fdPath` (its third ctor arg) — without it, typing `@` triggers the picker but
+ * `getFuzzyFileSuggestions` returns `[]`, so the picker never appears (issue #6).
+ * pi's own interactive mode resolves this via `ensureTool('fd')` from its
+ * internal `utils/tools-manager` (checks pi's managed bin dir + system PATH,
+ * downloading the binary if missing). That module is NOT on pi-coding-agent's
+ * `.`-only export map, so we reach it the same way we reach the editor's pi-tui
+ * instance: resolve the package entry, then import the sibling file by URL
+ * (file URLs bypass the bare-specifier exports gate). Best-effort: any
+ * resolution/import failure (or no fd available) → `null`, and the picker stays
+ * file-less rather than crashing.
+ */
+let fdPathPromise;
+export function resolveFdPath() {
+    if (!fdPathPromise) {
+        fdPathPromise = (async () => {
+            try {
+                const pcaEntry = import.meta.resolve('@earendil-works/pi-coding-agent');
+                const toolsManagerUrl = new URL('./utils/tools-manager.js', pcaEntry).href;
+                const toolsManager = (await import(toolsManagerUrl));
+                return (await toolsManager.ensureTool('fd', true)) ?? null;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return fdPathPromise;
+}
+/**
+ * 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));
+}
+const FAINT = (s) => `\x1b[2m${s}\x1b[22m`;
+const RED = (s) => `\x1b[31m${s}\x1b[39m`;
+const YELLOW = (s) => `\x1b[33m${s}\x1b[39m`;
+const GREEN = (s) => `\x1b[32m${s}\x1b[39m`;
+const BRIGHT_GREEN = (s) => `\x1b[92m${s}\x1b[39m`;
+// Terminals do not support alpha. This neutral charcoal is the dark-theme
+// equivalent of a low-opacity gray overlay, without borrowing the purple
+// selection surface used by interactive chrome.
+const CODE_BLOCK_BACKGROUND = '\x1b[48;2;36;36;36m';
+/** Paint a code-block fragment and keep its background active through the
+ *  renderer's trailing spaces, so the surface reaches the transcript's edge.
+ *  TUI applies a full reset after every rendered line. */
+function codeSurfaceFragment(render, text) {
+    return `${CODE_BLOCK_BACKGROUND}${render(text).replace(/\x1b\[0m/g, `\x1b[0m${CODE_BLOCK_BACKGROUND}`)}`;
+}
+/** Markdown theme for the attach transcript. Fenced code keeps pi's native
+ *  shape and syntax, but its content is painted on a distinct theme surface. */
+export function attachMarkdownTheme() {
+    const base = getMarkdownTheme();
+    const paint = (render, text) => codeSurfaceFragment(render, text);
+    return {
+        ...base,
+        // `Markdown` emits this before each body line; leave the surface on until
+        // the following code fragment closes it.
+        codeBlockIndent: `${CODE_BLOCK_BACKGROUND}${base.codeBlockIndent ?? '  '}`,
+        codeBlock: (text) => paint(base.codeBlock, text),
+        codeBlockBorder: (text) => paint(base.codeBlockBorder, text),
+        highlightCode: base.highlightCode
+            ? (code, language) => base.highlightCode(code, language).map((line) => paint((value) => value, line))
+            : undefined,
+    };
+}
+/**
+ * Build the attach chrome's color palette from the LIVE theme. Call AFTER
+ * `applyTheme()` — the colors are pulled from pi's `getMarkdownTheme()` /
+ * `getSelectListTheme()`, which read the active theme singleton at call time.
+ *
+ * pi does not re-export the raw `Theme` instance (its `.` export map omits the
+ * `theme` const and `getEditorTheme`/`getTheme`), so the accent/border/muted hues
+ * are sourced from the markdown + select-list theme colorizers, which ARE
+ * re-exported and are themselves backed by `theme.fg(...)`. The two semantic
+ * colors pi never exposes through that surface — `error`/`warning` — fall back to
+ * standard ANSI red/yellow.
+ */
+export function attachPalette() {
+    const md = getMarkdownTheme();
+    const sel = getSelectListTheme();
+    // The distinct-surface bg-on SGR, captured once. Re-asserted after every
+    // embedded `\x1b[0m` (full reset) inside a line so a coloured cell can't drop
+    // back to the default background mid-row; the line ends with `\x1b[49m` (reset
+    // background only) so the surface never bleeds onto the next line.
+    const bgOn = surfaceBgAnsi();
+    return {
+        accent: md.heading,
+        active: md.code,
+        info: md.link,
+        muted: sel.description,
+        faint: FAINT,
+        border: md.hr,
+        bold: md.bold,
+        error: RED,
+        warning: YELLOW,
+        bashMode: GREEN,
+        bashModeAlt: BRIGHT_GREEN,
+        surface: (line) => `${bgOn}${line.replace(/\x1b\[0m/g, `\x1b[0m${bgOn}`)}\x1b[49m`,
+    };
+}

package/dist/clients/attach/input/clipboard-image.d.ts

@@ -0,0 +1,55 @@
+import type { ImageContent } from '@earendil-works/pi-ai';
+/** A clipboard image ready to attach, plus an optional note for the controller
+ *  to surface — either a resize note (from pi's `formatDimensionNote`) or, when
+ *  no image was attached, the reason (dropped over the cap, or no clipboard
+ *  tool / read failure). */
+export interface ClipboardImageResult {
+    /** Ready to push into a `prompt`/`steer`/`follow_up` frame's `images?`. ABSENT
+     *  when the image was read but DROPPED (a fallback exceeded MAX_BYTES base64),
+     *  or when there was no image to read but a precise reason is worth surfacing;
+     *  `note` then carries that reason and the caller attaches nothing. */
+    image?: ImageContent;
+    /** Either a resize note ("Resized from 4032×3024 to 1568×1176", present only
+     *  when resized) or, when `image` is absent, the reason no image was attached. */
+    note?: string;
+}
+/** 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 declare function writeClipboardImageToFile(image: ImageContent): string;
+/** 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 declare function readClipboardImage(): Promise<ClipboardImageResult | null>;
+interface RawImage {
+    bytes: Buffer;
+    mimeType: string;
+}
+/** Outcome of the raw clipboard read, distinguishing the three cases the caller
+ *  must tell apart: `image` present → got bytes; `note` present → no image AND a
+ *  precise reason to surface (no clipboard tool / read failure); both absent →
+ *  the clipboard genuinely holds no image. */
+export interface RawReadOutcome {
+    image?: RawImage;
+    note?: string;
+}
+/** Result of probing one clipboard tool, distinguishing a MISSING binary (so the
+ *  caller can say "no clipboard tool") from a tool that ran but produced no image
+ *  (`bytes` absent, `missing` false → genuinely empty). */
+export interface RunResult {
+    /** Tool stdout when it produced non-empty output. */
+    bytes?: Buffer;
+    /** The binary was not found on PATH (ENOENT). */
+    missing?: boolean;
+}
+/** 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 declare function selectMacOutcome(runTool: (command: string, args: string[]) => RunResult, readNative: () => RawReadOutcome): RawReadOutcome;
+/** 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 declare function selectLinuxOutcome(runTool: (command: string, args: string[]) => RunResult, wayland: boolean): RawReadOutcome;
+export {};