pi-paster 0.2.1 → 0.2.2

package/README.md

@@ -30,6 +30,7 @@ Terminal image workflows are awkward: dragging a screenshot into a terminal usua
 - Attaches only placeholders still present in the submitted prompt.
 - Preserves attachment order by first placeholder occurrence.
 - Shows submitted image previews in chat history.
+- Provides `/image-compress` to fork the current branch into a new session where image blocks are replaced with text summaries.
 - Optional custom editor integration:
   - cursor-based image preview above the input
   - atomic deletion of whole image placeholders
@@ -79,6 +80,22 @@ What is wrong in this screenshot? [#image 1]
 
 On submit, the text and matching image attachment are sent together.
 
+## Image compression command
+
+Run `/image-compress` to summarize every image block in the current conversation branch and switch to a new session where those image blocks are replaced by text summaries.
+
+This is intentionally different from summarizing or compacting the whole session. Sometimes the text/tool context is still useful as-is, but screenshots are making the context heavy. Image compression preserves the same branch shape and surrounding conversation while pruning expensive image blocks into concise descriptions, so the agent keeps the relevant context without carrying every original image.
+
+The original session is not modified. Paster copies the active branch into a new session, replaces image blocks during the copy, and links the new session back to the original as its parent. By default, paster also adds a visible collapsible compression report for the user; the report details are stored outside model context.
+
+By default the command uses a pi subprocess with `openai-codex/gpt-5.4-mini` and a short 2-4 sentence summarization prompt. If that model is not configured or lacks credentials, paster shows a setup hint and you can configure a different summarization model. You can pass a one-off model after the command:
+
+```text
+/image-compress openrouter/google/gemini-2.5-flash
+```
+
+No extra runtime dependencies are used; the command shells out to the installed `pi` executable.
+
 ## Clipboard image paste
 
 On macOS, pi exposes an image paste action through its keybinding system. In the default pi keybindings this is `Ctrl+V`.
@@ -97,6 +114,13 @@ import { createPaster } from "pi-paster";
 export default createPaster({
   submittedPreviewStyle: "raw",
   includeImagePathsInPrompt: true,
+  imageCompression: {
+    enabled: true,
+    command: "image-compress",
+    model: "openai-codex/gpt-5.4-mini",
+    prompt: "Summarize this image in 2-4 concise sentences.",
+    includeReport: true,
+  },
   customEditor: {
     enabled: true,
     showImagePreview: true,
@@ -107,13 +131,20 @@ export default createPaster({
 
 ### Options
 
-| Option                                  | Default | Description                                                                                                                             |
-| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `submittedPreviewStyle`                 | `"raw"` | How submitted image previews render in chat history. Use `"collapsible"` to wrap them in pi's ctrl+o expandable/collapsible message UI. |
-| `includeImagePathsInPrompt`             | `true`  | Appends placeholder-to-local-path mappings to the submitted prompt so the agent can manipulate the source image files when asked.       |
-| `customEditor.enabled`                  | `true`  | Replaces pi's input editor with paster's editor integration. Disable this to keep pi's default editor.                                  |
-| `customEditor.showImagePreview`         | `true`  | Shows an image preview above the input when the cursor is inside an image placeholder. Requires `customEditor.enabled`.                 |
-| `customEditor.deletePlaceholderAsBlock` | `true`  | Makes backspace/delete remove the whole placeholder when editing inside or adjacent to it. Requires `customEditor.enabled`.             |
+| Option                                  | Default                       | Description                                                                                                                             |
+| --------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `submittedPreviewStyle`                 | `"raw"`                       | How submitted image previews render in chat history. Use `"collapsible"` to wrap them in pi's ctrl+o expandable/collapsible message UI. |
+| `includeImagePathsInPrompt`             | `true`                        | Appends placeholder-to-local-path mappings to the submitted prompt so the agent can manipulate the source image files when asked.       |
+| `imageCompression.enabled`              | `true`                        | Registers the image compression command.                                                                                                |
+| `imageCompression.command`              | `"image-compress"`            | Slash command name without the leading slash.                                                                                           |
+| `imageCompression.model`                | `"openai-codex/gpt-5.4-mini"` | Model passed to pi for per-image summarization. Set to `""` to use pi's default model.                                                  |
+| `imageCompression.prompt`               | built-in                      | Prompt used to summarize each image.                                                                                                    |
+| `imageCompression.piCommand`            | `"pi"`                        | pi executable used for summarization subprocesses.                                                                                      |
+| `imageCompression.timeoutMs`            | `120000`                      | Per-image summarization timeout in milliseconds.                                                                                        |
+| `imageCompression.includeReport`        | `true`                        | Adds a visible collapsible compression report after the copied compressed branch. Report details are not sent to the agent.             |
+| `customEditor.enabled`                  | `true`                        | Replaces pi's input editor with paster's editor integration. Disable this to keep pi's default editor.                                  |
+| `customEditor.showImagePreview`         | `true`                        | Shows an image preview above the input when the cursor is inside an image placeholder. Requires `customEditor.enabled`.                 |
+| `customEditor.deletePlaceholderAsBlock` | `true`                        | Makes backspace/delete remove the whole placeholder when editing inside or adjacent to it. Requires `customEditor.enabled`.             |
 
 When `customEditor.enabled` is `false`, paster still handles bracketed terminal paste/drop image paths, but cursor previews, atomic placeholder deletion, and paster's clipboard-image handler are disabled.
 

package/dist/index.d.mts

@@ -4,11 +4,38 @@ import { CustomEditor, ExtensionAPI, KeybindingsManager } from "@earendil-works/
 
 //#region src/config.d.ts
 type SubmittedPreviewStyle = "raw" | "collapsible";
+interface ImageCompressionConfig {
+  /** Enable the image compression slash command. */
+  enabled?: boolean;
+  /** Slash command name without the leading slash. */
+  command?: string;
+  /** Model passed to pi for image summarization. Pass an empty string to use pi's default model. */
+  model?: string;
+  /** Prompt used to summarize each image. */
+  prompt?: string;
+  /** pi executable used for summarization subprocesses. */
+  piCommand?: string;
+  /** Per-image summarization timeout in milliseconds. */
+  timeoutMs?: number;
+  /** Add a visible, collapsible UI report after compression. */
+  includeReport?: boolean;
+}
+interface ResolvedImageCompressionConfig {
+  enabled: boolean;
+  command: string;
+  model: string;
+  prompt: string;
+  piCommand: string;
+  timeoutMs: number;
+  includeReport: boolean;
+}
 interface PasterConfig {
   /** How submitted attachment previews render in chat history. */
   submittedPreviewStyle?: SubmittedPreviewStyle;
   /** Append local image paths to the submitted prompt so the agent can manipulate the source files. */
   includeImagePathsInPrompt?: boolean;
+  /** Configure the /image-compress command. */
+  imageCompression?: ImageCompressionConfig;
   customEditor?: {
     /** Replace pi's input editor to enable inline image UX features. */enabled?: boolean; /** Show an image preview above the input while the cursor is inside an image placeholder. */
     showImagePreview?: boolean; /** Treat image placeholders as atomic blocks for backspace/delete. */
@@ -18,6 +45,7 @@ interface PasterConfig {
 interface ResolvedPasterConfig {
   submittedPreviewStyle: SubmittedPreviewStyle;
   includeImagePathsInPrompt: boolean;
+  imageCompression: ResolvedImageCompressionConfig;
   customEditor: {
     enabled: boolean;
     showImagePreview: boolean;
@@ -72,6 +100,15 @@ type LoadImageResult = {
 interface PasterPreviewDetails {
   placeholders: string[];
 }
+interface ImageCompressionReportItem {
+  index: number;
+  summary: string;
+}
+interface ImageCompressionReportDetails {
+  imageCount: number;
+  summaryCount: number;
+  items: ImageCompressionReportItem[];
+}
 //#endregion
 //#region src/clipboard.d.ts
 type ClipboardImageResult = {
@@ -83,6 +120,10 @@ type ClipboardImageResult = {
 };
 declare function readClipboardImage(maxBytes?: number): ClipboardImageResult;
 //#endregion
+//#region src/compress.d.ts
+declare const DEFAULT_IMAGE_SUMMARY_PROMPT = "Summarize this image in 2-4 concise sentences. Include important visible text, UI elements, errors, diagrams, and details that may matter for future coding or design work.";
+declare function registerImageCompressionCommand(pi: ExtensionAPI, config: ResolvedImageCompressionConfig): void;
+//#endregion
 //#region src/optimize-image.d.ts
 interface OptimizeResult {
   data: string;
@@ -212,6 +253,19 @@ declare class ImagePreviewMessage implements Component {
   private renderRaw;
   private renderCollapsible;
 }
+interface CompressionReportTheme {
+  background?: (text: string) => string;
+  title: (text: string) => string;
+  muted: (text: string) => string;
+}
+declare class ImageCompressionReportMessage implements Component {
+  private readonly details;
+  private readonly theme;
+  private readonly expanded;
+  constructor(details: ImageCompressionReportDetails, theme: CompressionReportTheme, expanded?: boolean);
+  render(width: number): string[];
+  invalidate(): void;
+}
 interface CursorPreviewTheme {
   title: (text: string) => string;
   muted: (text: string) => string;
@@ -246,4 +300,4 @@ declare function createImagePasteTerminalInputHandler(options: {
 declare function createPaster(config?: PasterConfig): (pi: ExtensionAPI) => void;
 declare function paster(pi: ExtensionAPI, config?: PasterConfig): void;
 //#endregion
-export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, ClipboardImageResult, CursorImagePreviewWidget, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImageAttachment, ImagePreviewMessage, ImagePreviewMessageStyle, LoadImageResult, LoadedImage, MAX_IMAGE_BYTES, OptimizeResult, PASTE_END, PASTE_START, PasterConfig, PasterEditor, PasterImageContent, PasterPreviewDetails, ResolvedPasterConfig, SubmittedPreviewStyle, SupportedImageMimeType, TerminalInputResult, appendImagePathContext, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, segmentTextWithAtomicImages, shellUnescape, tokenizePathLikeText, windowsToWslPath };
+export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, ClipboardImageResult, CursorImagePreviewWidget, DEFAULT_IMAGE_SUMMARY_PROMPT, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImageAttachment, ImageCompressionConfig, ImageCompressionReportDetails, ImageCompressionReportItem, ImageCompressionReportMessage, ImagePreviewMessage, ImagePreviewMessageStyle, LoadImageResult, LoadedImage, MAX_IMAGE_BYTES, OptimizeResult, PASTE_END, PASTE_START, PasterConfig, PasterEditor, PasterImageContent, PasterPreviewDetails, ResolvedImageCompressionConfig, ResolvedPasterConfig, SubmittedPreviewStyle, SupportedImageMimeType, TerminalInputResult, appendImagePathContext, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, registerImageCompressionCommand, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, segmentTextWithAtomicImages, shellUnescape, tokenizePathLikeText, windowsToWslPath };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { platform } from "node:process";
@@ -647,10 +647,210 @@ function readMacOSClipboardImage(maxBytes) {
 	};
 }
 //#endregion
+//#region src/compress.ts
+const DEFAULT_IMAGE_SUMMARY_PROMPT = "Summarize this image in 2-4 concise sentences. Include important visible text, UI elements, errors, diagrams, and details that may matter for future coding or design work.";
+function isImageBlock(block) {
+	return !!block && typeof block === "object" && block.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string";
+}
+function imageKey(image) {
+	return `${image.mimeType}:${image.data.length}:${image.data.slice(0, 48)}`;
+}
+function collectImages(entries) {
+	const images = [];
+	for (const entry of entries) {
+		const content = entry.type === "custom_message" ? entry.content : entry.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) {
+			if (!isImageBlock(block)) continue;
+			images.push({
+				key: imageKey(block),
+				image: block
+			});
+		}
+	}
+	return images;
+}
+function extensionForMime(mimeType) {
+	switch (mimeType) {
+		case "image/jpeg": return ".jpg";
+		case "image/webp": return ".webp";
+		case "image/gif": return ".gif";
+		default: return ".png";
+	}
+}
+function normalizeSummary(stdout) {
+	return stdout.trim().replace(/\n{3,}/g, "\n\n");
+}
+async function summarizeImage(pi, ctx, image, config) {
+	const dir = mkdtempSync(join(tmpdir(), "pi-paster-image-compress-"));
+	try {
+		const imagePath = join(dir, `image${extensionForMime(image.mimeType)}`);
+		writeFileSync(imagePath, Buffer.from(image.data, "base64"));
+		const args = [
+			"--no-session",
+			"--no-extensions",
+			"--no-tools",
+			"--mode",
+			"text",
+			"-p"
+		];
+		if (config.model) args.splice(0, 0, "--model", config.model);
+		args.push(`@${imagePath}`, config.prompt);
+		const result = await pi.exec(config.piCommand, args, {
+			cwd: ctx.cwd,
+			timeout: config.timeoutMs
+		});
+		if (result.code !== 0) {
+			const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.code}`;
+			throw new Error(`image summarization failed: ${detail}`);
+		}
+		const summary = normalizeSummary(result.stdout);
+		if (!summary) throw new Error("image summarization returned an empty response");
+		return summary;
+	} finally {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function summaryBlock(summary) {
+	return {
+		type: "text",
+		text: `Image summary: ${summary}`
+	};
+}
+function transformContent(content, summaries) {
+	if (!Array.isArray(content)) return content;
+	return content.map((block) => {
+		if (!isImageBlock(block)) return block;
+		return summaryBlock(summaries.get(imageKey(block)) ?? "Image summary unavailable.");
+	});
+}
+function buildReportDetails(images, summaries) {
+	const items = [...summaries.values()].map((summary, index) => ({
+		index: index + 1,
+		summary
+	}));
+	return {
+		imageCount: images.length,
+		summaryCount: summaries.size,
+		items
+	};
+}
+function appendTransformedEntry(sessionManager, entry, summaries) {
+	const manager = sessionManager;
+	switch (entry.type) {
+		case "thinking_level_change":
+			if (entry.thinkingLevel) manager.appendThinkingLevelChange(entry.thinkingLevel);
+			return;
+		case "model_change":
+			if (entry.provider && entry.modelId) manager.appendModelChange(entry.provider, entry.modelId);
+			return;
+		case "compaction":
+			if (entry.summary) manager.appendCustomMessageEntry("paster-image-compress-compaction-summary", entry.summary, false, entry.details);
+			return;
+		case "branch_summary":
+			if (entry.summary) manager.appendCustomMessageEntry("paster-image-compress-branch-summary", entry.summary, false, entry.details);
+			return;
+		case "custom":
+			if (entry.customType) manager.appendCustomEntry(entry.customType, entry.data);
+			return;
+		case "session_info":
+			if (typeof entry.name === "string") manager.appendSessionInfo(entry.name);
+			return;
+		case "custom_message":
+			if (entry.customType === "paster-preview") return;
+			if (entry.customType && entry.content !== void 0) manager.appendCustomMessageEntry(entry.customType, transformContent(entry.content, summaries) ?? "", entry.display ?? true, entry.details);
+			return;
+		case "message":
+			if (entry.message) manager.appendMessage({
+				...entry.message,
+				content: transformContent(entry.message.content, summaries)
+			});
+			return;
+		default: return;
+	}
+}
+function resolveCommandOptions(args, config) {
+	const model = args.trim() || config.model;
+	return {
+		...config,
+		model
+	};
+}
+function setCompressionProgress(ctx, current, total, model) {
+	if (!ctx.hasUI) return;
+	const progress = `Summarizing image ${current}/${total}`;
+	ctx.ui.setStatus("paster-image-compress", progress);
+	ctx.ui.setWidget("paster-image-compress-progress", [`paster: ${progress}`, model ? `model: ${model}` : "model: pi default"], { placement: "aboveEditor" });
+}
+function clearCompressionProgress(ctx) {
+	if (!ctx.hasUI) return;
+	ctx.ui.setStatus("paster-image-compress", void 0);
+	ctx.ui.setWidget("paster-image-compress-progress", void 0, { placement: "aboveEditor" });
+}
+function registerImageCompressionCommand(pi, config) {
+	if (!config.enabled) return;
+	pi.registerCommand(config.command, {
+		description: "Summarize images in the current branch and switch to a new session where image blocks are replaced with text summaries.",
+		handler: async (args, ctx) => {
+			await ctx.waitForIdle();
+			const commandConfig = resolveCommandOptions(args, config);
+			const branch = ctx.sessionManager.getBranch();
+			const images = collectImages(branch);
+			if (images.length === 0) {
+				if (ctx.hasUI) ctx.ui.notify("No images found in the current branch", "warning");
+				return;
+			}
+			const uniqueImages = [...new Map(images.map((item) => [item.key, item.image])).entries()];
+			const summaries = /* @__PURE__ */ new Map();
+			if (ctx.hasUI) ctx.ui.notify(`Summarizing ${uniqueImages.length} image(s)...`, "info");
+			setCompressionProgress(ctx, 0, uniqueImages.length, commandConfig.model);
+			try {
+				for (let index = 0; index < uniqueImages.length; index++) {
+					const [key, image] = uniqueImages[index];
+					setCompressionProgress(ctx, index + 1, uniqueImages.length, commandConfig.model);
+					summaries.set(key, await summarizeImage(pi, ctx, image, commandConfig));
+				}
+			} catch (error) {
+				const reason = error instanceof Error ? error.message : String(error);
+				const message = `Image compression failed while using ${commandConfig.model || "pi's default model"}. ${reason}\n\nTo try another model once, run /${commandConfig.command} provider/model. To change the default, configure pi-paster's imageCompression.model option in your wrapper extension. See https://github.com/beowulf11/pi-paster#configuration.`;
+				if (ctx.hasUI) ctx.ui.notify(message, "error");
+				else console.error(message);
+				return;
+			} finally {
+				clearCompressionProgress(ctx);
+			}
+			const parentSession = ctx.sessionManager.getSessionFile();
+			const reportDetails = buildReportDetails(images, summaries);
+			await ctx.newSession({
+				parentSession,
+				setup: async (sessionManager) => {
+					for (const entry of branch) appendTransformedEntry(sessionManager, entry, summaries);
+					if (commandConfig.includeReport) sessionManager.appendCustomMessageEntry("paster-image-compress-report", "", true, reportDetails);
+				},
+				withSession: async (newCtx) => {
+					if (newCtx.hasUI) newCtx.ui.notify(`Compressed ${images.length} image block(s) into text summaries`, "info");
+				}
+			});
+		}
+	});
+}
+//#endregion
 //#region src/config.ts
 const DEFAULT_PASTER_CONFIG = {
 	submittedPreviewStyle: "raw",
 	includeImagePathsInPrompt: true,
+	imageCompression: {
+		enabled: true,
+		command: "image-compress",
+		model: "openai-codex/gpt-5.4-mini",
+		prompt: "Summarize this image in 2-4 concise sentences. Include important visible text, UI elements, errors, diagrams, and details that may matter for future coding or design work.",
+		piCommand: "pi",
+		timeoutMs: 12e4,
+		includeReport: true
+	},
 	customEditor: {
 		enabled: true,
 		showImagePreview: true,
@@ -661,6 +861,15 @@ function resolvePasterConfig(config = {}) {
 	return {
 		submittedPreviewStyle: config.submittedPreviewStyle ?? DEFAULT_PASTER_CONFIG.submittedPreviewStyle,
 		includeImagePathsInPrompt: config.includeImagePathsInPrompt ?? DEFAULT_PASTER_CONFIG.includeImagePathsInPrompt,
+		imageCompression: {
+			enabled: config.imageCompression?.enabled ?? DEFAULT_PASTER_CONFIG.imageCompression.enabled,
+			command: config.imageCompression?.command ?? DEFAULT_PASTER_CONFIG.imageCompression.command,
+			model: config.imageCompression?.model ?? DEFAULT_PASTER_CONFIG.imageCompression.model,
+			prompt: config.imageCompression?.prompt ?? DEFAULT_PASTER_CONFIG.imageCompression.prompt,
+			piCommand: config.imageCompression?.piCommand ?? DEFAULT_PASTER_CONFIG.imageCompression.piCommand,
+			timeoutMs: config.imageCompression?.timeoutMs ?? DEFAULT_PASTER_CONFIG.imageCompression.timeoutMs,
+			includeReport: config.imageCompression?.includeReport ?? DEFAULT_PASTER_CONFIG.imageCompression.includeReport
+		},
 		customEditor: {
 			enabled: config.customEditor?.enabled ?? DEFAULT_PASTER_CONFIG.customEditor.enabled,
 			showImagePreview: config.customEditor?.showImagePreview ?? DEFAULT_PASTER_CONFIG.customEditor.showImagePreview,
@@ -927,6 +1136,27 @@ var ImagePreviewMessage = class {
 		return lines;
 	}
 };
+var ImageCompressionReportMessage = class {
+	constructor(details, theme, expanded = false) {
+		this.details = details;
+		this.theme = theme;
+		this.expanded = expanded;
+	}
+	render(width) {
+		const container = new Container();
+		container.addChild(new Spacer(1));
+		const box = new Box(1, 1, this.theme.background);
+		container.addChild(box);
+		const suffix = this.expanded ? " (ctrl+o to collapse)" : " (ctrl+o to expand)";
+		box.addChild(new Text(`${this.theme.title(`Compressed ${this.details.imageCount} image block(s) into ${this.details.summaryCount} summary/summaries`)}${this.theme.muted(suffix)}`, 0, 0));
+		if (this.expanded) for (const item of this.details.items) {
+			box.addChild(new Text(this.theme.muted(`Image ${item.index}:`), 0, 0));
+			box.addChild(new Text(truncateToWidth(item.summary, Math.max(1, width - 4), "…"), 0, 0));
+		}
+		return container.render(width);
+	}
+	invalidate() {}
+};
 var CursorImagePreviewWidget = class {
 	image;
 	constructor(attachment, theme) {
@@ -1035,9 +1265,19 @@ function createPaster(config = {}) {
 function paster(pi, config = {}) {
 	const resolvedConfig = resolvePasterConfig(config);
 	const store = new AttachmentStore();
+	registerImageCompressionCommand(pi, resolvedConfig.imageCompression);
 	let pendingPreview = [];
 	let activeEditor;
 	let unsubscribeTerminalInput;
+	pi.registerMessageRenderer("paster-image-compress-report", (message, options, theme) => {
+		const details = message.details;
+		if (!details) return void 0;
+		return new ImageCompressionReportMessage(details, {
+			background: (text) => theme.bg("toolSuccessBg", text),
+			title: (text) => theme.fg("toolTitle", theme.bold(text)),
+			muted: (text) => theme.fg("muted", text)
+		}, options.expanded);
+	});
 	pi.registerMessageRenderer("paster-preview", (message, options, theme) => {
 		const placeholders = message.details?.placeholders ?? [];
 		const attachments = store.list().filter((attachment) => placeholders.includes(attachment.placeholder));
@@ -1138,4 +1378,4 @@ function paster(pi, config = {}) {
 	});
 }
 //#endregion
-export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, CursorImagePreviewWidget, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImagePreviewMessage, MAX_IMAGE_BYTES, PASTE_END, PASTE_START, PasterEditor, appendImagePathContext, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, segmentTextWithAtomicImages, shellUnescape, tokenizePathLikeText, windowsToWslPath };
+export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, CursorImagePreviewWidget, DEFAULT_IMAGE_SUMMARY_PROMPT, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImageCompressionReportMessage, ImagePreviewMessage, MAX_IMAGE_BYTES, PASTE_END, PASTE_START, PasterEditor, appendImagePathContext, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, registerImageCompressionCommand, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, segmentTextWithAtomicImages, shellUnescape, tokenizePathLikeText, windowsToWslPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-paster",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Pi extension that turns pasted image paths into first-class image attachments.",
   "keywords": [
     "image-attachments",
@@ -58,6 +58,6 @@
     "extensions": [
       "./src/index.ts"
     ],
-    "image": "https://unpkg.com/pi-paster@0.2.1/docs/preview.png"
+    "image": "https://unpkg.com/pi-paster@0.2.2/docs/preview.png"
   }
 }

package/src/compress.ts

@@ -0,0 +1,329 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedImageCompressionConfig } from "./config.ts";
+import type { ImageCompressionReportDetails } from "./types.ts";
+
+export const DEFAULT_IMAGE_SUMMARY_PROMPT =
+  "Summarize this image in 2-4 concise sentences. Include important visible text, UI elements, errors, diagrams, and details that may matter for future coding or design work.";
+
+interface TextBlock {
+  type: "text";
+  text: string;
+}
+
+interface ImageBlock {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+
+type ContentBlock = TextBlock | ImageBlock | Record<string, unknown>;
+
+type SessionEntryLike = {
+  type: string;
+  thinkingLevel?: string;
+  provider?: string;
+  modelId?: string;
+  summary?: string;
+  firstKeptEntryId?: string;
+  tokensBefore?: number;
+  details?: unknown;
+  data?: unknown;
+  name?: string;
+  fromHook?: boolean;
+  customType?: string;
+  content?: string | ContentBlock[];
+  display?: boolean;
+  message?: {
+    role?: string;
+    content?: string | ContentBlock[];
+    [key: string]: unknown;
+  };
+};
+
+interface ImageOccurrence {
+  key: string;
+  image: ImageBlock;
+}
+
+function isImageBlock(block: unknown): block is ImageBlock {
+  return (
+    !!block &&
+    typeof block === "object" &&
+    (block as { type?: unknown }).type === "image" &&
+    typeof (block as { data?: unknown }).data === "string" &&
+    typeof (block as { mimeType?: unknown }).mimeType === "string"
+  );
+}
+
+function imageKey(image: ImageBlock): string {
+  return `${image.mimeType}:${image.data.length}:${image.data.slice(0, 48)}`;
+}
+
+function collectImages(entries: SessionEntryLike[]): ImageOccurrence[] {
+  const images: ImageOccurrence[] = [];
+  for (const entry of entries) {
+    const content = entry.type === "custom_message" ? entry.content : entry.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (!isImageBlock(block)) continue;
+      images.push({ key: imageKey(block), image: block });
+    }
+  }
+  return images;
+}
+
+function extensionForMime(mimeType: string): string {
+  switch (mimeType) {
+    case "image/jpeg":
+      return ".jpg";
+    case "image/webp":
+      return ".webp";
+    case "image/gif":
+      return ".gif";
+    case "image/png":
+    default:
+      return ".png";
+  }
+}
+
+function normalizeSummary(stdout: string): string {
+  return stdout.trim().replace(/\n{3,}/g, "\n\n");
+}
+
+async function summarizeImage(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  image: ImageBlock,
+  config: ResolvedImageCompressionConfig,
+): Promise<string> {
+  const dir = mkdtempSync(join(tmpdir(), "pi-paster-image-compress-"));
+  try {
+    const imagePath = join(dir, `image${extensionForMime(image.mimeType)}`);
+    writeFileSync(imagePath, Buffer.from(image.data, "base64"));
+
+    const args = ["--no-session", "--no-extensions", "--no-tools", "--mode", "text", "-p"];
+    if (config.model) {
+      args.splice(0, 0, "--model", config.model);
+    }
+    args.push(`@${imagePath}`, config.prompt);
+
+    const result = await pi.exec(config.piCommand, args, {
+      cwd: ctx.cwd,
+      timeout: config.timeoutMs,
+    });
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.code}`;
+      throw new Error(`image summarization failed: ${detail}`);
+    }
+    const summary = normalizeSummary(result.stdout);
+    if (!summary) throw new Error("image summarization returned an empty response");
+    return summary;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function summaryBlock(summary: string): TextBlock {
+  return { type: "text", text: `Image summary: ${summary}` };
+}
+
+function transformContent(
+  content: string | ContentBlock[] | undefined,
+  summaries: Map<string, string>,
+): string | ContentBlock[] | undefined {
+  if (!Array.isArray(content)) return content;
+  return content.map((block) => {
+    if (!isImageBlock(block)) return block;
+    return summaryBlock(summaries.get(imageKey(block)) ?? "Image summary unavailable.");
+  });
+}
+
+function buildReportDetails(
+  images: ImageOccurrence[],
+  summaries: Map<string, string>,
+): ImageCompressionReportDetails {
+  const items = [...summaries.values()].map((summary, index) => ({ index: index + 1, summary }));
+  return { imageCount: images.length, summaryCount: summaries.size, items };
+}
+
+function appendTransformedEntry(
+  sessionManager: unknown,
+  entry: SessionEntryLike,
+  summaries: Map<string, string>,
+) {
+  const manager = sessionManager as {
+    appendThinkingLevelChange(level: string): void;
+    appendModelChange(provider: string, modelId: string): void;
+    appendCustomEntry(customType: string, data?: unknown): void;
+    appendSessionInfo(name: string): void;
+    appendCustomMessageEntry(
+      customType: string,
+      content: string | ContentBlock[],
+      display: boolean,
+      details?: unknown,
+    ): void;
+    appendMessage(message: Record<string, unknown>): void;
+  };
+
+  switch (entry.type) {
+    case "thinking_level_change":
+      if (entry.thinkingLevel) manager.appendThinkingLevelChange(entry.thinkingLevel);
+      return;
+    case "model_change":
+      if (entry.provider && entry.modelId) manager.appendModelChange(entry.provider, entry.modelId);
+      return;
+    case "compaction":
+      if (entry.summary) {
+        manager.appendCustomMessageEntry(
+          "paster-image-compress-compaction-summary",
+          entry.summary,
+          false,
+          entry.details,
+        );
+      }
+      return;
+    case "branch_summary":
+      if (entry.summary) {
+        manager.appendCustomMessageEntry(
+          "paster-image-compress-branch-summary",
+          entry.summary,
+          false,
+          entry.details,
+        );
+      }
+      return;
+    case "custom":
+      if (entry.customType) manager.appendCustomEntry(entry.customType, entry.data);
+      return;
+    case "session_info":
+      if (typeof entry.name === "string") {
+        manager.appendSessionInfo(entry.name);
+      }
+      return;
+    case "custom_message":
+      if (entry.customType === "paster-preview") return;
+      if (entry.customType && entry.content !== undefined) {
+        manager.appendCustomMessageEntry(
+          entry.customType,
+          transformContent(entry.content, summaries) ?? "",
+          entry.display ?? true,
+          entry.details,
+        );
+      }
+      return;
+    case "message":
+      if (entry.message) {
+        manager.appendMessage({
+          ...entry.message,
+          content: transformContent(entry.message.content, summaries),
+        });
+      }
+      return;
+    default:
+      return;
+  }
+}
+
+function resolveCommandOptions(args: string, config: ResolvedImageCompressionConfig) {
+  const model = args.trim() || config.model;
+  return { ...config, model };
+}
+
+function setCompressionProgress(
+  ctx: ExtensionCommandContext,
+  current: number,
+  total: number,
+  model: string,
+): void {
+  if (!ctx.hasUI) return;
+  const progress = `Summarizing image ${current}/${total}`;
+  ctx.ui.setStatus("paster-image-compress", progress);
+  ctx.ui.setWidget(
+    "paster-image-compress-progress",
+    [`paster: ${progress}`, model ? `model: ${model}` : "model: pi default"],
+    { placement: "aboveEditor" },
+  );
+}
+
+function clearCompressionProgress(ctx: ExtensionCommandContext): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.setStatus("paster-image-compress", undefined);
+  ctx.ui.setWidget("paster-image-compress-progress", undefined, { placement: "aboveEditor" });
+}
+
+export function registerImageCompressionCommand(
+  pi: ExtensionAPI,
+  config: ResolvedImageCompressionConfig,
+): void {
+  if (!config.enabled) return;
+
+  pi.registerCommand(config.command, {
+    description:
+      "Summarize images in the current branch and switch to a new session where image blocks are replaced with text summaries.",
+    handler: async (args, ctx): Promise<void> => {
+      await ctx.waitForIdle();
+      const commandConfig = resolveCommandOptions(args, config);
+      const branch = ctx.sessionManager.getBranch() as SessionEntryLike[];
+      const images = collectImages(branch);
+      if (images.length === 0) {
+        if (ctx.hasUI) ctx.ui.notify("No images found in the current branch", "warning");
+        return;
+      }
+
+      const uniqueImages = [...new Map(images.map((item) => [item.key, item.image])).entries()];
+      const summaries = new Map<string, string>();
+
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Summarizing ${uniqueImages.length} image(s)...`, "info");
+      }
+      setCompressionProgress(ctx, 0, uniqueImages.length, commandConfig.model);
+
+      try {
+        for (let index = 0; index < uniqueImages.length; index++) {
+          const [key, image] = uniqueImages[index]!;
+          setCompressionProgress(ctx, index + 1, uniqueImages.length, commandConfig.model);
+          summaries.set(key, await summarizeImage(pi, ctx, image, commandConfig));
+        }
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const modelHint = commandConfig.model || "pi's default model";
+        const message = `Image compression failed while using ${modelHint}. ${reason}\n\nTo try another model once, run /${commandConfig.command} provider/model. To change the default, configure pi-paster's imageCompression.model option in your wrapper extension. See https://github.com/beowulf11/pi-paster#configuration.`;
+        if (ctx.hasUI) ctx.ui.notify(message, "error");
+        else console.error(message);
+        return;
+      } finally {
+        clearCompressionProgress(ctx);
+      }
+
+      const parentSession = ctx.sessionManager.getSessionFile();
+      const reportDetails = buildReportDetails(images, summaries);
+      await ctx.newSession({
+        parentSession,
+        setup: async (sessionManager) => {
+          for (const entry of branch) appendTransformedEntry(sessionManager, entry, summaries);
+          if (commandConfig.includeReport) {
+            sessionManager.appendCustomMessageEntry(
+              "paster-image-compress-report",
+              "",
+              true,
+              reportDetails,
+            );
+          }
+        },
+        withSession: async (newCtx) => {
+          if (newCtx.hasUI) {
+            newCtx.ui.notify(
+              `Compressed ${images.length} image block(s) into text summaries`,
+              "info",
+            );
+          }
+        },
+      });
+
+      return;
+    },
+  });
+}

package/src/config.ts

@@ -1,10 +1,39 @@
 export type SubmittedPreviewStyle = "raw" | "collapsible";
 
+export interface ImageCompressionConfig {
+  /** Enable the image compression slash command. */
+  enabled?: boolean;
+  /** Slash command name without the leading slash. */
+  command?: string;
+  /** Model passed to pi for image summarization. Pass an empty string to use pi's default model. */
+  model?: string;
+  /** Prompt used to summarize each image. */
+  prompt?: string;
+  /** pi executable used for summarization subprocesses. */
+  piCommand?: string;
+  /** Per-image summarization timeout in milliseconds. */
+  timeoutMs?: number;
+  /** Add a visible, collapsible UI report after compression. */
+  includeReport?: boolean;
+}
+
+export interface ResolvedImageCompressionConfig {
+  enabled: boolean;
+  command: string;
+  model: string;
+  prompt: string;
+  piCommand: string;
+  timeoutMs: number;
+  includeReport: boolean;
+}
+
 export interface PasterConfig {
   /** How submitted attachment previews render in chat history. */
   submittedPreviewStyle?: SubmittedPreviewStyle;
   /** Append local image paths to the submitted prompt so the agent can manipulate the source files. */
   includeImagePathsInPrompt?: boolean;
+  /** Configure the /image-compress command. */
+  imageCompression?: ImageCompressionConfig;
   customEditor?: {
     /** Replace pi's input editor to enable inline image UX features. */
     enabled?: boolean;
@@ -18,6 +47,7 @@ export interface PasterConfig {
 export interface ResolvedPasterConfig {
   submittedPreviewStyle: SubmittedPreviewStyle;
   includeImagePathsInPrompt: boolean;
+  imageCompression: ResolvedImageCompressionConfig;
   customEditor: {
     enabled: boolean;
     showImagePreview: boolean;
@@ -28,6 +58,16 @@ export interface ResolvedPasterConfig {
 export const DEFAULT_PASTER_CONFIG: ResolvedPasterConfig = {
   submittedPreviewStyle: "raw",
   includeImagePathsInPrompt: true,
+  imageCompression: {
+    enabled: true,
+    command: "image-compress",
+    model: "openai-codex/gpt-5.4-mini",
+    prompt:
+      "Summarize this image in 2-4 concise sentences. Include important visible text, UI elements, errors, diagrams, and details that may matter for future coding or design work.",
+    piCommand: "pi",
+    timeoutMs: 120_000,
+    includeReport: true,
+  },
   customEditor: {
     enabled: true,
     showImagePreview: true,
@@ -41,6 +81,19 @@ export function resolvePasterConfig(config: PasterConfig = {}): ResolvedPasterCo
       config.submittedPreviewStyle ?? DEFAULT_PASTER_CONFIG.submittedPreviewStyle,
     includeImagePathsInPrompt:
       config.includeImagePathsInPrompt ?? DEFAULT_PASTER_CONFIG.includeImagePathsInPrompt,
+    imageCompression: {
+      enabled: config.imageCompression?.enabled ?? DEFAULT_PASTER_CONFIG.imageCompression.enabled,
+      command: config.imageCompression?.command ?? DEFAULT_PASTER_CONFIG.imageCompression.command,
+      model: config.imageCompression?.model ?? DEFAULT_PASTER_CONFIG.imageCompression.model,
+      prompt: config.imageCompression?.prompt ?? DEFAULT_PASTER_CONFIG.imageCompression.prompt,
+      piCommand:
+        config.imageCompression?.piCommand ?? DEFAULT_PASTER_CONFIG.imageCompression.piCommand,
+      timeoutMs:
+        config.imageCompression?.timeoutMs ?? DEFAULT_PASTER_CONFIG.imageCompression.timeoutMs,
+      includeReport:
+        config.imageCompression?.includeReport ??
+        DEFAULT_PASTER_CONFIG.imageCompression.includeReport,
+    },
     customEditor: {
       enabled: config.customEditor?.enabled ?? DEFAULT_PASTER_CONFIG.customEditor.enabled,
       showImagePreview:

package/src/index.ts

@@ -1,14 +1,24 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readClipboardImage } from "./clipboard.ts";
+import { registerImageCompressionCommand } from "./compress.ts";
 import { type PasterConfig, resolvePasterConfig } from "./config.ts";
 import { PasterEditor } from "./editor.ts";
 import { appendImagePathContext, imagesForTextOptimized } from "./image-utils.ts";
-import { CursorImagePreviewWidget, ImagePreviewMessage } from "./preview.ts";
+import {
+  CursorImagePreviewWidget,
+  ImageCompressionReportMessage,
+  ImagePreviewMessage,
+} from "./preview.ts";
 import { AttachmentStore } from "./store.ts";
 import { createImagePasteTerminalInputHandler } from "./terminal-input.ts";
-import type { ImageAttachment, PasterPreviewDetails } from "./types.ts";
+import type {
+  ImageAttachment,
+  ImageCompressionReportDetails,
+  PasterPreviewDetails,
+} from "./types.ts";
 
 export * from "./clipboard.ts";
+export * from "./compress.ts";
 export * from "./optimize-image.ts";
 export * from "./config.ts";
 export * from "./editor.ts";
@@ -25,10 +35,28 @@ export function createPaster(config: PasterConfig = {}): (pi: ExtensionAPI) => v
 export default function paster(pi: ExtensionAPI, config: PasterConfig = {}): void {
   const resolvedConfig = resolvePasterConfig(config);
   const store = new AttachmentStore();
+  registerImageCompressionCommand(pi, resolvedConfig.imageCompression);
   let pendingPreview: ImageAttachment[] = [];
   let activeEditor: PasterEditor | undefined;
   let unsubscribeTerminalInput: (() => void) | undefined;
 
+  pi.registerMessageRenderer<ImageCompressionReportDetails>(
+    "paster-image-compress-report",
+    (message, options, theme) => {
+      const details = message.details;
+      if (!details) return undefined;
+      return new ImageCompressionReportMessage(
+        details,
+        {
+          background: (text) => theme.bg("toolSuccessBg", text),
+          title: (text) => theme.fg("toolTitle", theme.bold(text)),
+          muted: (text) => theme.fg("muted", text),
+        },
+        options.expanded,
+      );
+    },
+  );
+
   pi.registerMessageRenderer<PasterPreviewDetails>("paster-preview", (message, options, theme) => {
     const placeholders = message.details?.placeholders ?? [];
     const attachments = store

package/src/preview.ts

@@ -10,7 +10,7 @@ import {
   truncateToWidth,
   visibleWidth,
 } from "@earendil-works/pi-tui";
-import type { ImageAttachment } from "./types.ts";
+import type { ImageAttachment, ImageCompressionReportDetails } from "./types.ts";
 
 function formatAttachmentLine(
   attachment: ImageAttachment,
@@ -99,6 +99,47 @@ export class ImagePreviewMessage implements Component {
   }
 }
 
+interface CompressionReportTheme {
+  background?: (text: string) => string;
+  title: (text: string) => string;
+  muted: (text: string) => string;
+}
+
+export class ImageCompressionReportMessage implements Component {
+  constructor(
+    private readonly details: ImageCompressionReportDetails,
+    private readonly theme: CompressionReportTheme,
+    private readonly expanded = false,
+  ) {}
+
+  render(width: number): string[] {
+    const container = new Container();
+    container.addChild(new Spacer(1));
+    const box = new Box(1, 1, this.theme.background);
+    container.addChild(box);
+
+    const suffix = this.expanded ? " (ctrl+o to collapse)" : " (ctrl+o to expand)";
+    box.addChild(
+      new Text(
+        `${this.theme.title(`Compressed ${this.details.imageCount} image block(s) into ${this.details.summaryCount} summary/summaries`)}${this.theme.muted(suffix)}`,
+        0,
+        0,
+      ),
+    );
+
+    if (this.expanded) {
+      for (const item of this.details.items) {
+        box.addChild(new Text(this.theme.muted(`Image ${item.index}:`), 0, 0));
+        box.addChild(new Text(truncateToWidth(item.summary, Math.max(1, width - 4), "…"), 0, 0));
+      }
+    }
+
+    return container.render(width);
+  }
+
+  invalidate(): void {}
+}
+
 interface CursorPreviewTheme {
   title: (text: string) => string;
   muted: (text: string) => string;

package/src/types.ts

@@ -57,3 +57,14 @@ export type LoadImageResult =
 export interface PasterPreviewDetails {
   placeholders: string[];
 }
+
+export interface ImageCompressionReportItem {
+  index: number;
+  summary: string;
+}
+
+export interface ImageCompressionReportDetails {
+  imageCount: number;
+  summaryCount: number;
+  items: ImageCompressionReportItem[];
+}