feat(ui-pi): paste an image from the clipboard with Ctrl-V

Terminals deliver only text on paste, so Ctrl-V now shells out to the
platform clipboard tool (pngpaste / wl-paste / xclip / powershell), reads
an image if present, and attaches it to the next prompt as an ImageContent
block — submitUserPrompt + agent.prompt already accept images. Detection
and base64 assembly are unit-tested; the live clipboard read needs a
desktop (none of those tools exist on the CI/dev box).

Author: halfaipg

src/agent/agent.ts

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { Agent, type AgentEvent, type AgentMessage } from "@earendil-works/pi-agent-core";
-import type { Model } from "@earendil-works/pi-ai";
+import type { ImageContent, Model } from "@earendil-works/pi-ai";
 import { defaultOAuthConfig } from "../auth/cli.js";
 import { CredentialsStore } from "../auth/credentials.js";
 import { TokenManager } from "../auth/token-manager.js";
@@ -124,7 +124,10 @@ export interface AgentBundle {
 	 * veto. Callers that originate prompts from real user input should use
 	 * this instead of `agent.prompt()` directly.
 	 */
-	submitUserPrompt: (text: string) => Promise<{ submitted: boolean; reason?: string; error?: string }>;
+	submitUserPrompt: (
+		text: string,
+		images?: ImageContent[],
+	) => Promise<{ submitted: boolean; reason?: string; error?: string }>;
 	/**
 	 * Set when `--resume` actually loaded a prior session, with its
 	 * timestamp + message count so the welcome banner can say
@@ -467,7 +470,10 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 	 * accepted the prompt. The agent's own turn lifecycle still emits
 	 * events on bundle.subscribe.
 	 */
-	const submitUserPrompt = async (text: string): Promise<{ submitted: boolean; reason?: string; error?: string }> => {
+	const submitUserPrompt = async (
+		text: string,
+		images?: ImageContent[],
+	): Promise<{ submitted: boolean; reason?: string; error?: string }> => {
 		const outcome = await hooks.dispatch("UserPromptSubmit", {
 			event: "UserPromptSubmit",
 			workingDir: cwd,
@@ -481,7 +487,7 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 		// callers don't await us — they subscribe to bundle.subscribe for the
 		// streaming events independent of this resolution.
 		try {
-			await agent.prompt(text);
+			await agent.prompt(text, images && images.length > 0 ? images : undefined);
 		} catch (e) {
 			// Throws that fire BEFORE agent_start (auth misconfigured, model
 			// rejected, network refused at the SDK boundary) never produce an

src/ui-pi/app.ts

@@ -1,6 +1,7 @@
 import { appendFileSync } from "node:fs";
 import { basename } from "node:path";
 import type { AgentEvent, AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ImageContent } from "@earendil-works/pi-ai";
 import {
 	type AutocompleteItem,
 	CombinedAutocompleteProvider,
@@ -24,6 +25,7 @@ import { runPlanFlow } from "../plan/run-flow.js";
 import type { ChatState, ToolExecution } from "../types.js";
 import { EMPTY_USAGE } from "../types.js";
 import { buildAttachmentPrompt, collectAttachments } from "../ui/attachments.js";
+import { type ClipboardImage, readClipboardImage } from "../ui/clipboard-image.js";
 import { HistoryStore } from "../ui/history-store.js";
 import { notifyTurnComplete } from "../ui/notify.js";
 import { runShellEscape } from "../ui/shell-escape.js";
@@ -109,6 +111,8 @@ export class App extends Container {
 	/** Keyboard copy mode: registry of transcript copy boxes + the Ctrl-O picker. */
 	private readonly copyRegistry = new CopyRegistry();
 	private copyPickerOverlay: { handle: OverlayHandle; component: CopyPickerOverlay } | undefined;
+	/** Images pulled off the clipboard with Ctrl-V, attached to the next prompt. */
+	private pendingImages: ClipboardImage[] = [];
 
 	constructor() {
 		super();
@@ -369,6 +373,23 @@ export class App extends Container {
 		this.tui?.requestRender();
 	}
 
+	/** Pull an image off the clipboard and stage it for the next prompt. */
+	private async attachClipboardImage(): Promise<void> {
+		try {
+			const image = await readClipboardImage();
+			if (!image) {
+				this.statusBar.note("No image on the clipboard (copy one first; needs pngpaste / wl-paste / xclip).");
+			} else {
+				this.pendingImages.push(image);
+				const kb = Math.round((image.data.length * 3) / 4 / 1024);
+				this.statusBar.note(`📎 image attached (${kb} KB) — send a message to include it.`);
+			}
+		} catch {
+			this.statusBar.note("Couldn't read the clipboard image.");
+		}
+		this.tui?.requestRender();
+	}
+
 	/** Dynamic terminal title: cwd basename + a ● marker while a turn runs. */
 	private setTitle(working: boolean): void {
 		const dir = basename(this.bundle.toolContext.cwd) || "codebase";
@@ -423,6 +444,12 @@ export class App extends Container {
 			this.showCopyPickerOverlay();
 			return { consume: true };
 		}
+		// Ctrl-V attaches an image from the system clipboard to the next
+		// prompt (text paste arrives via bracketed paste, not Ctrl-V).
+		if (data === "\x16" && this.inputBar) {
+			void this.attachClipboardImage();
+			return { consume: true };
+		}
 		// Ghost suggestion: Tab on an empty editor accepts it; any other
 		// keystroke dismisses it (and still reaches the editor).
 		const ghost = this.suggestionLine.get();
@@ -534,7 +561,8 @@ export class App extends Container {
 
 	private async handleSubmitInner(text: string): Promise<void> {
 		const trimmed = text.trim();
-		if (!trimmed) return;
+		// Allow an image-only submit (Ctrl-V then Enter with no text).
+		if (!trimmed && this.pendingImages.length === 0) return;
 
 		// Slash commands and `!cmd` shell escapes bypass the agent and the
 		// type-ahead queue. They run immediately so the user never has to
@@ -558,6 +586,10 @@ export class App extends Container {
 		// Claude-Code "type while it works" behavior. The message also lands
 		// in the transcript so the user sees what they steered with.
 		if (this.busy) {
+			if (!trimmed) {
+				this.statusBar.note("Finish the current turn before sending an image.");
+				return;
+			}
 			const userMsg: AgentMessage = { role: "user", content: trimmed, timestamp: Date.now() };
 			this.messages.push(userMsg);
 			this.transcript.appendUserMessage(trimmed);
@@ -585,10 +617,12 @@ export class App extends Container {
 			this.statusBar.note(`Attached: ${attachments.map((a) => a.relPath).join(", ")}`);
 		}
 
-		const userMsg: AgentMessage = { role: "user", content: trimmed, timestamp: Date.now() };
+		const imageCount = this.pendingImages.length;
+		const display = trimmed || (imageCount > 0 ? `📎 ${imageCount} image${imageCount === 1 ? "" : "s"}` : "");
+		const userMsg: AgentMessage = { role: "user", content: display, timestamp: Date.now() };
 		this.messages.push(userMsg);
-		this.transcript.appendUserMessage(trimmed);
-		this.persistHistory(trimmed);
+		this.transcript.appendUserMessage(display);
+		if (trimmed) this.persistHistory(trimmed);
 
 		// Glue-router classification: plan-style requests run through the
 		// plan flow (Q&A → reviewable plan → agent); everything else
@@ -631,8 +665,11 @@ export class App extends Container {
 		// stderr as a status-bar note. A real error (agent throws before
 		// reaching agent_start) surfaces as an ErrorCard — otherwise the
 		// user just sees their prompt land with no response.
+		// Attach + clear any clipboard images staged with Ctrl-V.
+		const images = this.pendingImages.length > 0 ? this.pendingImages : undefined;
+		this.pendingImages = [];
 		this.bundle
-			.submitUserPrompt(promptText)
+			.submitUserPrompt(promptText, images)
 			.then((result) => {
 				if (!result.submitted && result.reason) {
 					this.statusBar.note(`Prompt blocked by hook: ${result.reason}`);

src/ui/clipboard-image.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { detectImageCommand, readClipboardImage } from "./clipboard-image.js";
+
+describe("detectImageCommand", () => {
+	it("uses pngpaste on macOS", () => {
+		expect(detectImageCommand("darwin", {})).toMatchObject({ cmd: "pngpaste", mimeType: "image/png" });
+	});
+
+	it("uses wl-paste on Wayland Linux", () => {
+		expect(detectImageCommand("linux", { WAYLAND_DISPLAY: "wayland-0" })?.cmd).toBe("wl-paste");
+	});
+
+	it("uses xclip on X11 Linux", () => {
+		expect(detectImageCommand("linux", {})?.cmd).toBe("xclip");
+	});
+
+	it("uses powershell on Windows", () => {
+		expect(detectImageCommand("win32", {})?.cmd).toBe("powershell");
+	});
+
+	it("returns null on unknown platforms", () => {
+		expect(detectImageCommand("aix" as NodeJS.Platform, {})).toBeNull();
+	});
+});
+
+describe("readClipboardImage", () => {
+	it("returns an ImageContent block when the tool yields bytes", async () => {
+		const png = Buffer.from([0x89, 0x50, 0x4e, 0x47]); // PNG magic
+		const img = await readClipboardImage({
+			command: { cmd: "x", args: [], mimeType: "image/png" },
+			run: async () => png,
+		});
+		expect(img).toEqual({ type: "image", mimeType: "image/png", data: png.toString("base64") });
+	});
+
+	it("returns null when the clipboard has no image (empty output)", async () => {
+		const img = await readClipboardImage({
+			command: { cmd: "x", args: [], mimeType: "image/png" },
+			run: async () => null,
+		});
+		expect(img).toBeNull();
+	});
+
+	it("returns null when no tool is known for the platform", async () => {
+		expect(await readClipboardImage({ command: null })).toBeNull();
+	});
+});

src/ui/clipboard-image.ts

@@ -0,0 +1,84 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Read an image off the system clipboard and return it as an
+ * ImageContent block the agent can take as input. Terminals don't deliver
+ * image bytes through paste (bracketed paste is text-only), so we shell
+ * out to the platform's clipboard tool on demand — the same approach
+ * Claude Code uses.
+ *
+ * Returns null when no tool is installed, the clipboard holds no image,
+ * or the read fails — callers treat that as "nothing to attach."
+ */
+
+export interface ClipboardImage {
+	type: "image";
+	mimeType: string;
+	/** Base64-encoded image bytes. */
+	data: string;
+}
+
+export interface ImageCommand {
+	cmd: string;
+	args: string[];
+	mimeType: string;
+}
+
+/**
+ * Pick the clipboard-image read command for this platform, or null when
+ * we don't know one. Pure + testable; the caller checks the tool exists.
+ */
+export function detectImageCommand(
+	platform: NodeJS.Platform = process.platform,
+	env: NodeJS.ProcessEnv = process.env,
+): ImageCommand | null {
+	if (platform === "darwin") {
+		// pngpaste streams the clipboard image as PNG to stdout with `-`.
+		return { cmd: "pngpaste", args: ["-"], mimeType: "image/png" };
+	}
+	if (platform === "linux") {
+		if (env.WAYLAND_DISPLAY) {
+			return { cmd: "wl-paste", args: ["--type", "image/png", "--no-newline"], mimeType: "image/png" };
+		}
+		return { cmd: "xclip", args: ["-selection", "clipboard", "-t", "image/png", "-o"], mimeType: "image/png" };
+	}
+	if (platform === "win32") {
+		// PowerShell pulls the clipboard image and writes PNG bytes to stdout.
+		const ps =
+			"$i=Get-Clipboard -Format Image; if($i){$ms=New-Object IO.MemoryStream; $i.Save($ms,[Drawing.Imaging.ImageFormat]::Png); [Console]::OpenStandardOutput().Write($ms.ToArray(),0,$ms.Length)}";
+		return { cmd: "powershell", args: ["-NoProfile", "-Command", ps], mimeType: "image/png" };
+	}
+	return null;
+}
+
+export interface ReadClipboardDeps {
+	command?: ImageCommand | null;
+	/** Inject a spawn for tests. */
+	run?: (cmd: string, args: string[]) => Promise<Buffer | null>;
+}
+
+export async function readClipboardImage(deps: ReadClipboardDeps = {}): Promise<ClipboardImage | null> {
+	const command = deps.command !== undefined ? deps.command : detectImageCommand();
+	if (!command) return null;
+	const run = deps.run ?? runCapture;
+	const bytes = await run(command.cmd, command.args);
+	if (!bytes || bytes.length === 0) return null;
+	return { type: "image", mimeType: command.mimeType, data: bytes.toString("base64") };
+}
+
+/** Spawn a command and capture its stdout as a Buffer; null on any failure. */
+function runCapture(cmd: string, args: string[]): Promise<Buffer | null> {
+	return new Promise((resolve) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+		} catch {
+			resolve(null);
+			return;
+		}
+		const chunks: Buffer[] = [];
+		child.stdout?.on("data", (c: Buffer) => chunks.push(c));
+		child.on("error", () => resolve(null)); // tool not installed
+		child.on("close", (code) => resolve(code === 0 && chunks.length > 0 ? Buffer.concat(chunks) : null));
+	});
+}