pi-paster 0.2.0 → 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`.
@@ -87,7 +104,7 @@ On macOS, pi exposes an image paste action through its keybinding system. In the
 
 ## Configuration
 
-By default all editor integrations are enabled.
+By default all editor integrations are enabled, and submitted image previews render in the raw chat-history style.
 
 To customize behavior, load a small wrapper extension:
 
@@ -95,6 +112,15 @@ To customize behavior, load a small wrapper extension:
 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,
@@ -105,11 +131,20 @@ export default createPaster({
 
 ### Options
 
-| Option                                  | Default | Description                                                                                                                 |
-| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `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

@@ -3,7 +3,39 @@ import { Component, EditorTheme, ImageDimensions, ImageTheme, TUI } from "@earen
 import { CustomEditor, ExtensionAPI, KeybindingsManager } from "@earendil-works/pi-coding-agent";
 
 //#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. */
@@ -11,6 +43,9 @@ interface PasterConfig {
   };
 }
 interface ResolvedPasterConfig {
+  submittedPreviewStyle: SubmittedPreviewStyle;
+  includeImagePathsInPrompt: boolean;
+  imageCompression: ResolvedImageCompressionConfig;
   customEditor: {
     enabled: boolean;
     showImagePreview: boolean;
@@ -65,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 = {
@@ -76,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;
@@ -109,6 +157,7 @@ declare class AttachmentStore {
 //#region src/editor.d.ts
 declare const PASTE_START = "\u001B[200~";
 declare const PASTE_END = "\u001B[201~";
+declare function segmentTextWithAtomicImages(text: string, store: AttachmentStore, validPasteIds?: Set<number>): Intl.SegmentData[];
 declare class PasterEditor extends CustomEditor {
   private readonly pasterKeybindings;
   private readonly pasterOptions;
@@ -125,9 +174,12 @@ declare class PasterEditor extends CustomEditor {
   insertTextAtCursor(text: string): void;
   handleInput(data: string): void;
   clearCursorPreview(): void;
+  private installAtomicImageSegmentation;
   private handlePasteClipboardImage;
   private handleBracketedPaste;
+  private handleAtomicPlaceholderNavigation;
   private handleAtomicPlaceholderDelete;
+  private setCursor;
   private deleteLineRange;
   private transform;
   private updateCursorPreview;
@@ -165,6 +217,7 @@ declare function replaceImagePathsInText(text: string, options: {
   accepted: ImageAttachment[];
 };
 declare function imagesForText(store: AttachmentStore, text: string, existing?: PasterImageContent[]): PasterImageContent[];
+declare function appendImagePathContext(text: string, attachments: ImageAttachment[]): string;
 /**
  * Async variant of imagesForText that runs each attachment through the
  * Anthropic-aware image optimizer (resize to 8000px cap, JPEG ladder to stay
@@ -180,11 +233,36 @@ declare function describeReject(result: Exclude<LoadImageResult, {
 }>, notify?: (message: string) => void): void;
 //#endregion
 //#region src/preview.d.ts
+type ImagePreviewMessageStyle = "raw" | "collapsible";
+interface ImagePreviewMessageTheme extends ImageTheme {
+  background?: (text: string) => string;
+  title?: (text: string) => string;
+  muted?: (text: string) => string;
+}
 declare class ImagePreviewMessage implements Component {
   private readonly attachments;
   private readonly theme;
+  private readonly options;
   private readonly images;
-  constructor(attachments: ImageAttachment[], theme: ImageTheme);
+  constructor(attachments: ImageAttachment[], theme: ImagePreviewMessageTheme, options?: {
+    expanded?: boolean;
+    style?: ImagePreviewMessageStyle;
+  });
+  invalidate(): void;
+  render(width: number): string[];
+  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;
 }
@@ -222,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, LoadImageResult, LoadedImage, MAX_IMAGE_BYTES, OptimizeResult, PASTE_END, PASTE_START, PasterConfig, PasterEditor, PasterImageContent, PasterPreviewDetails, ResolvedPasterConfig, SupportedImageMimeType, TerminalInputResult, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, 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 };