@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/clients/attach/chat-view.js

@@ -0,0 +1,450 @@
+// chat-view.ts — the render half of `crtr attach` (Phase 4, T5).
+//
+// A direct port of pi's `InteractiveMode.handleEvent()`
+// (interactive-mode.js:2169-2462) + its rebuild path
+// (`addMessageToChat`/`renderSessionContext`, :2483-2648) that DRIVES pi's own
+// exported TUI components rather than reimplementing them. The viewer never
+// spawns pi and never opens the session — it only consumes the relayed
+// `AgentSessionEvent` stream + the `welcome` snapshot over `view.sock`.
+//
+// Ownership boundary: ChatView owns the chat scroll `Container` it is handed,
+// plus an activity/status area pinned to the bottom of that container (working
+// spinner, compaction/retry indicators, inline status/error lines). It does NOT
+// own the editor, the footer, or the terminal title — those are chrome laid out
+// by the attach command (T7). Events that only affect that chrome
+// (queue_update / session_info_changed / thinking_level_changed) are forwarded
+// to the optional `onFooterEvent` sink instead of rendered here.
+//
+// Custom-tool rendering (plan §3.3): extensions run in the broker, so the viewer
+// has no `ToolDefinition`. Every tool renders through the DEFAULT
+// `ToolExecutionComponent` path (toolDef = undefined) — builtin tools, diffs, and
+// partial-result streaming all work; only custom `renderCall`/`renderResult`
+// extensions degrade to the default, which is the decided Phase-4 behavior.
+import { Container, Loader, Spacer, Text } from '@earendil-works/pi-tui';
+import { AssistantMessageComponent, BashExecutionComponent, BranchSummaryMessageComponent, CompactionSummaryMessageComponent, CustomMessageComponent, getMarkdownTheme, parseSkillBlock, SkillInvocationMessageComponent, ToolExecutionComponent, UserMessageComponent, } from '@earendil-works/pi-coding-agent';
+/** `theme` (the live instance) is NOT re-exported by pi's strict `.` map, so the
+ *  loaders use small local ANSI styling rather than `theme.fg(...)`. Theme parity
+ *  for activity spinners is cosmetic; the message components themselves still use
+ *  `getMarkdownTheme()` for full-fidelity rendering. */
+const spinnerStyle = (s) => `\x1b[36m${s}\x1b[39m`; // cyan
+const dimStyle = (s) => `\x1b[2m${s}\x1b[22m`; // dim
+export class ChatView {
+    tui;
+    /** The chat scroll area handed in by the attach command. */
+    container;
+    /** Activity/status area, pinned as the LAST child of `container` (mirrors pi's
+     *  statusContainer sitting directly below chatContainer). Holds the working
+     *  spinner / compaction+retry loaders. */
+    statusContainer = new Container();
+    cwd;
+    showImages;
+    imageWidthCells;
+    hideThinking;
+    hiddenThinkingLabel;
+    toolOutputExpanded;
+    onFooterEvent;
+    /** The assistant message component currently being streamed (between
+     *  message_start and message_end for an assistant turn). */
+    streamingComponent;
+    /** Tool-call id → its execution component, for the duration of the call. */
+    pendingTools = new Map();
+    /** The single active activity loader (working/compaction/retry), if any. */
+    activityLoader;
+    /** While true, `append` skips re-pinning the status container (bulk rebuild). */
+    bulkMode = false;
+    constructor(tui, container, opts = {}) {
+        this.tui = tui;
+        this.container = container;
+        this.cwd = opts.cwd ?? process.cwd();
+        this.showImages = opts.showImages ?? true;
+        this.imageWidthCells = opts.imageWidthCells ?? 60;
+        this.hideThinking = opts.hideThinking ?? false;
+        this.hiddenThinkingLabel = opts.hiddenThinkingLabel ?? 'Thinking...';
+        this.toolOutputExpanded = opts.toolOutputExpanded ?? false;
+        this.onFooterEvent = opts.onFooterEvent;
+        this.container.addChild(this.statusContainer);
+    }
+    // -------------------------------------------------------------------------
+    // Catch-up: render the welcome snapshot, then live events resume.
+    // -------------------------------------------------------------------------
+    /** Render the full message history from a `welcome` snapshot. Ports pi's
+     *  `renderSessionContext` (interactive-mode.js:2553): assistant messages spawn
+     *  tool-execution components matched to their toolResult messages; everything
+     *  else routes through `addMessageToChat`. The TUI's differential renderer +
+     *  reflow-on-resize is automatic — no scrollback reconstruction needed. */
+    applySnapshot(snapshot) {
+        this.resetChat();
+        const renderedPendingTools = new Map();
+        const messages = snapshot.messages;
+        const lastIndex = messages.length - 1;
+        // Rebuild in bulk: detach the pinned status area, append children directly,
+        // re-pin ONCE at the end. Keeps the rebuild O(N) instead of O(N²) re-pins for
+        // a long transcript (see `append`).
+        this.container.removeChild(this.statusContainer);
+        this.bulkMode = true;
+        try {
+            for (let i = 0; i < messages.length; i++) {
+                const message = messages[i];
+                if (message.role === 'assistant') {
+                    // If the snapshot caught an IN-FLIGHT assistant turn (state.isStreaming
+                    // and this is the trailing, non-terminal assistant message), bind it as
+                    // the live streaming component so the relayed message_update/message_end
+                    // frames that follow `welcome` land on it. Otherwise the in-flight
+                    // message would freeze at its snapshot value until the next turn — the
+                    // common case, since you typically attach to a node that is working.
+                    const isStreamingTail = i === lastIndex &&
+                        snapshot.state.isStreaming &&
+                        message.stopReason !== 'aborted' &&
+                        message.stopReason !== 'error';
+                    if (isStreamingTail) {
+                        this.streamingComponent = new AssistantMessageComponent(undefined, this.hideThinking, getMarkdownTheme(), this.hiddenThinkingLabel);
+                        this.append(this.streamingComponent);
+                        this.streamingComponent.updateContent(message);
+                    }
+                    else {
+                        this.addMessageToChat(message);
+                    }
+                    for (const content of this.assistantToolCalls(message)) {
+                        const component = this.makeToolComponent(content.name, content.id, content.arguments);
+                        this.append(component);
+                        // (isStreamingTail is never aborted/error, so its tools fall through to
+                        //  renderedPendingTools → pendingTools, where live tool events find them.)
+                        if (message.stopReason === 'aborted' || message.stopReason === 'error') {
+                            const errorMessage = message.stopReason === 'aborted'
+                                ? 'Operation aborted'
+                                : (message.errorMessage ?? 'Error');
+                            component.updateResult({ content: [{ type: 'text', text: errorMessage }], isError: true });
+                        }
+                        else {
+                            renderedPendingTools.set(content.id, component);
+                        }
+                    }
+                }
+                else if (message.role === 'toolResult') {
+                    const component = renderedPendingTools.get(message.toolCallId);
+                    if (component) {
+                        component.updateResult(message);
+                        renderedPendingTools.delete(message.toolCallId);
+                    }
+                }
+                else {
+                    this.addMessageToChat(message);
+                }
+            }
+        }
+        finally {
+            this.bulkMode = false;
+            this.container.addChild(this.statusContainer);
+        }
+        for (const [id, component] of renderedPendingTools) {
+            this.pendingTools.set(id, component);
+        }
+        this.tui.requestRender();
+    }
+    /** Stop any spinning activity loader. A one-shot `crtr attach` process lets its
+     *  timers die with the process, but if T7 reuses a ChatView across reconnects in
+     *  one process it should call this on detach to avoid a leaked interval. */
+    dispose() {
+        this.setActivity(undefined);
+    }
+    // -------------------------------------------------------------------------
+    // Live stream: the 15-of-17-case handleEvent port (turn_start/turn_end no-op,
+    // exactly as interactive pi falls through default for those two).
+    // -------------------------------------------------------------------------
+    handleEvent(event) {
+        switch (event.type) {
+            case 'agent_start': {
+                this.pendingTools.clear();
+                this.setActivity(this.makeLoader('Working...'));
+                break;
+            }
+            case 'agent_end': {
+                // Drop a dangling streaming component (e.g. aborted before message_end).
+                if (this.streamingComponent) {
+                    this.container.removeChild(this.streamingComponent);
+                    this.streamingComponent = undefined;
+                }
+                this.pendingTools.clear();
+                this.setActivity(undefined);
+                break;
+            }
+            case 'message_start': {
+                if (event.message.role === 'custom' || event.message.role === 'user') {
+                    this.addMessageToChat(event.message);
+                }
+                else if (event.message.role === 'assistant') {
+                    this.streamingComponent = new AssistantMessageComponent(undefined, this.hideThinking, getMarkdownTheme(), this.hiddenThinkingLabel);
+                    this.append(this.streamingComponent);
+                    this.streamingComponent.updateContent(event.message);
+                }
+                break;
+            }
+            case 'message_update': {
+                if (this.streamingComponent && event.message.role === 'assistant') {
+                    this.streamingComponent.updateContent(event.message);
+                    for (const content of this.assistantToolCalls(event.message)) {
+                        const existing = this.pendingTools.get(content.id);
+                        if (existing) {
+                            existing.updateArgs(content.arguments);
+                        }
+                        else {
+                            const component = this.makeToolComponent(content.name, content.id, content.arguments);
+                            this.append(component);
+                            this.pendingTools.set(content.id, component);
+                        }
+                    }
+                }
+                break;
+            }
+            case 'message_end': {
+                if (event.message.role !== 'assistant')
+                    break;
+                if (this.streamingComponent) {
+                    const stopReason = event.message.stopReason;
+                    let errorMessage = event.message.errorMessage;
+                    if (stopReason === 'aborted' && !errorMessage) {
+                        errorMessage = 'Operation aborted';
+                        // Surface the abort on the assistant bubble itself, mirroring pi
+                        // (interactive-mode.js:2280 sets streamingMessage.errorMessage before
+                        // updateContent) so the rendered message shows the annotation.
+                        event.message.errorMessage = errorMessage;
+                    }
+                    this.streamingComponent.updateContent(event.message);
+                    if (stopReason === 'aborted' || stopReason === 'error') {
+                        const text = errorMessage ?? 'Error';
+                        for (const component of this.pendingTools.values()) {
+                            component.updateResult({ content: [{ type: 'text', text }], isError: true });
+                        }
+                        this.pendingTools.clear();
+                    }
+                    else {
+                        // Args complete → trigger diff computation for edit tools.
+                        for (const component of this.pendingTools.values()) {
+                            component.setArgsComplete();
+                        }
+                    }
+                    this.streamingComponent = undefined;
+                }
+                break;
+            }
+            case 'tool_execution_start': {
+                let component = this.pendingTools.get(event.toolCallId);
+                if (!component) {
+                    component = this.makeToolComponent(event.toolName, event.toolCallId, event.args);
+                    this.append(component);
+                    this.pendingTools.set(event.toolCallId, component);
+                }
+                component.markExecutionStarted();
+                break;
+            }
+            case 'tool_execution_update': {
+                const component = this.pendingTools.get(event.toolCallId);
+                if (component) {
+                    component.updateResult({ ...event.partialResult, isError: false }, true);
+                }
+                break;
+            }
+            case 'tool_execution_end': {
+                const component = this.pendingTools.get(event.toolCallId);
+                if (component) {
+                    component.updateResult({ ...event.result, isError: event.isError });
+                    this.pendingTools.delete(event.toolCallId);
+                }
+                break;
+            }
+            case 'compaction_start': {
+                const label = event.reason === 'manual' ? 'Compacting context...' : 'Auto-compacting...';
+                this.setActivity(this.makeLoader(label));
+                break;
+            }
+            case 'compaction_end': {
+                this.setActivity(undefined);
+                if (event.aborted) {
+                    this.showStatus(event.reason === 'manual' ? 'Compaction cancelled' : 'Auto-compaction cancelled');
+                }
+                else if (event.result) {
+                    // 0.78.1 divergence from the §3.2 sketch: `compaction_end` carries only
+                    // the CompactionResult (summary + tokensBefore), NOT the post-compaction
+                    // message list — so the viewer cannot clear+rebuild the transcript the
+                    // way in-process pi does (it rebuilds from its own SessionManager). We
+                    // append the compaction summary marker instead and KEEP the
+                    // pre-compaction scrollback for the rest of this attach session; a fresh
+                    // re-attach gets the already-compacted history via `welcome`. (Reported
+                    // in T5's final.)
+                    this.addMessageToChat({
+                        role: 'compactionSummary',
+                        summary: event.result.summary,
+                        tokensBefore: event.result.tokensBefore,
+                        timestamp: Date.now(),
+                    });
+                }
+                else if (event.errorMessage) {
+                    this.showError(event.errorMessage);
+                }
+                break;
+            }
+            case 'auto_retry_start': {
+                const seconds = Math.ceil(event.delayMs / 1000);
+                this.setActivity(this.makeLoader(`Retrying (${event.attempt}/${event.maxAttempts}) in ${seconds}s...`));
+                break;
+            }
+            case 'auto_retry_end': {
+                this.setActivity(undefined);
+                if (!event.success) {
+                    this.showError(`Retry failed after ${event.attempt} attempts: ${event.finalError ?? 'Unknown error'}`);
+                }
+                break;
+            }
+            // Footer/header-only — ChatView owns no footer; forward to the sink.
+            case 'queue_update':
+            case 'session_info_changed':
+            case 'thinking_level_changed':
+                this.onFooterEvent?.(event);
+                break;
+            // turn_start / turn_end — interactive pi ignores these (falls through
+            // default); the viewer does too.
+            default:
+                break;
+        }
+        this.tui.requestRender();
+    }
+    // -------------------------------------------------------------------------
+    // Rebuild path (ports addMessageToChat, interactive-mode.js:2483).
+    // -------------------------------------------------------------------------
+    addMessageToChat(message) {
+        switch (message.role) {
+            case 'bashExecution': {
+                const component = new BashExecutionComponent(message.command, this.tui, message.excludeFromContext);
+                if (message.output)
+                    component.appendOutput(message.output);
+                component.setComplete(message.exitCode, message.cancelled, 
+                // pi's interactive mode passes a minimal `{truncated:true}` marker here
+                // (interactive-mode.js:2489) where the typed param is the full
+                // TruncationResult; the snapshot message only carries the boolean, so we
+                // mirror pi and cast.
+                message.truncated ? { truncated: true } : undefined, message.fullOutputPath);
+                this.append(component);
+                break;
+            }
+            case 'custom': {
+                if (message.display) {
+                    // No extension renderer in the viewer → default custom-message render.
+                    const component = new CustomMessageComponent(message, undefined, getMarkdownTheme());
+                    component.setExpanded(this.toolOutputExpanded);
+                    this.append(component);
+                }
+                break;
+            }
+            case 'compactionSummary': {
+                this.append(new Spacer(1));
+                const component = new CompactionSummaryMessageComponent(message, getMarkdownTheme());
+                component.setExpanded(this.toolOutputExpanded);
+                this.append(component);
+                break;
+            }
+            case 'branchSummary': {
+                this.append(new Spacer(1));
+                const component = new BranchSummaryMessageComponent(message, getMarkdownTheme());
+                component.setExpanded(this.toolOutputExpanded);
+                this.append(component);
+                break;
+            }
+            case 'user': {
+                const textContent = this.userMessageText(message);
+                if (!textContent)
+                    break;
+                if (this.chatChildCount() > 0)
+                    this.append(new Spacer(1));
+                const skillBlock = parseSkillBlock(textContent);
+                if (skillBlock) {
+                    const component = new SkillInvocationMessageComponent(skillBlock, getMarkdownTheme());
+                    component.setExpanded(this.toolOutputExpanded);
+                    this.append(component);
+                    if (skillBlock.userMessage) {
+                        this.append(new UserMessageComponent(skillBlock.userMessage, getMarkdownTheme()));
+                    }
+                }
+                else {
+                    this.append(new UserMessageComponent(textContent, getMarkdownTheme()));
+                }
+                break;
+            }
+            case 'assistant': {
+                this.append(new AssistantMessageComponent(message, this.hideThinking, getMarkdownTheme(), this.hiddenThinkingLabel));
+                break;
+            }
+            // toolResult is rendered inline with its tool call (handled in applySnapshot).
+            default:
+                break;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+    /** Default-path tool component (toolDef undefined → builtin/default rendering). */
+    makeToolComponent(name, id, args) {
+        const component = new ToolExecutionComponent(name, id, args, { showImages: this.showImages, imageWidthCells: this.imageWidthCells }, undefined, this.tui, this.cwd);
+        component.setExpanded(this.toolOutputExpanded);
+        return component;
+    }
+    /** Append a child while keeping the activity/status area pinned to the bottom. */
+    append(child) {
+        if (this.bulkMode) {
+            this.container.addChild(child);
+            return;
+        }
+        this.container.removeChild(this.statusContainer);
+        this.container.addChild(child);
+        this.container.addChild(this.statusContainer);
+    }
+    /** Number of chat children excluding the pinned status container. */
+    chatChildCount() {
+        return this.container.children.filter((c) => c !== this.statusContainer).length;
+    }
+    /** Clear all chat content and re-pin an empty status container. */
+    resetChat() {
+        this.setActivity(undefined);
+        this.streamingComponent = undefined;
+        this.pendingTools.clear();
+        this.container.clear();
+        this.container.addChild(this.statusContainer);
+    }
+    makeLoader(message) {
+        return new Loader(this.tui, spinnerStyle, dimStyle, message);
+    }
+    /** Swap the single active activity indicator (working/compaction/retry). */
+    setActivity(loader) {
+        this.activityLoader?.stop();
+        this.statusContainer.clear();
+        this.activityLoader = loader;
+        if (loader)
+            this.statusContainer.addChild(loader);
+    }
+    showStatus(message) {
+        this.append(new Spacer(1));
+        this.append(new Text(dimStyle(message), 1, 0));
+    }
+    showError(message) {
+        this.append(new Spacer(1));
+        this.append(new Text(`\x1b[31m${message}\x1b[39m`, 1, 0));
+    }
+    /** Extract the tool-call content items from an assistant message. */
+    assistantToolCalls(message) {
+        const content = message.content;
+        if (!Array.isArray(content))
+            return [];
+        return content.filter((c) => typeof c === 'object' && c !== null && c.type === 'toolCall');
+    }
+    /** Concatenate the text blocks of a user message (string or content array). */
+    userMessageText(message) {
+        const content = message.content;
+        if (typeof content === 'string')
+            return content;
+        if (!Array.isArray(content))
+            return '';
+        return content
+            .filter((c) => typeof c === 'object' && c !== null && c.type === 'text')
+            .map((c) => c.text)
+            .join('');
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { ImageContent } from '@earendil-works/pi-ai';
+/** A clipboard image ready to attach, plus an optional human-readable note about
+ *  the resize (from pi's `formatDimensionNote`) for the controller to surface. */
+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);
+     *  `note` then carries the drop 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 the image was dropped. */
+    note?: string;
+}
+/** Read + resize the current clipboard image. Returns `null` when there is no
+ *  image, no clipboard tool, or the read fails (all best-effort — the caller
+ *  shows a brief notice and carries on). */
+export declare function readClipboardImage(): Promise<ClipboardImageResult | null>;

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

@@ -0,0 +1,113 @@
+// clipboard-image.ts — read the clipboard image for `crtr 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
+// (pngpaste on macOS, wl-paste on Wayland, xclip on X11) — small + best-effort:
+// no tool / empty clipboard → `null` and the caller shows a brief notice.
+//
+// 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 { 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;
+/** Read + resize the current clipboard image. Returns `null` when there is no
+ *  image, no clipboard tool, or the read fails (all best-effort — the caller
+ *  shows a brief notice and carries on). */
+export async function readClipboardImage() {
+    const raw = readRawClipboardImage();
+    if (!raw)
+        return 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') {
+        const out = run('pngpaste', ['-']);
+        return out ? { bytes: out, mimeType: 'image/png' } : null;
+    }
+    // Linux: Wayland first (wl-paste), then X11 (xclip). Try PNG then JPEG.
+    if (isWayland()) {
+        const out = run('wl-paste', ['--type', 'image/png', '--no-newline']);
+        if (out)
+            return { bytes: out, mimeType: 'image/png' };
+    }
+    for (const mimeType of ['image/png', 'image/jpeg']) {
+        const out = run('xclip', ['-selection', 'clipboard', '-t', mimeType, '-o']);
+        if (out)
+            return { bytes: out, mimeType };
+    }
+    return null;
+}
+function isWayland() {
+    return Boolean(process.env.WAYLAND_DISPLAY) || process.env.XDG_SESSION_TYPE === 'wayland';
+}
+/** Run a clipboard tool; return its stdout Buffer, or `null` on any failure
+ *  (missing binary, non-zero exit, timeout, empty output). */
+function run(command, args) {
+    const result = spawnSync(command, args, {
+        timeout: SPAWN_TIMEOUT_MS,
+        maxBuffer: SPAWN_MAX_BUFFER,
+    });
+    if (result.error || result.status !== 0)
+        return null;
+    const stdout = result.stdout;
+    if (!stdout || stdout.length === 0)
+        return null;
+    return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
+}

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

@@ -0,0 +1,31 @@
+import { KeybindingsManager, type KeybindingsConfig } 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;
+/**
+ * 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 declare function createKeybindingsManager(agentDir?: string): KeybindingsManager;
+/**
+ * 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;