pi-image-tools 1.0.11 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.1.0] - 2026-05-03
+
+### Added
+- Added centralized image MIME, image-size, PowerShell, and error utilities used by clipboard, preview, attachment, and recent-image flows.
+- Added size-limit enforcement for image attachments, recent-cache writes, recent-image loads, and Sixel preview conversion through `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES`.
+
+### Changed
+- Reworked recent-image caching to use an extension-owned cache directory with safe pruning that preserves user files.
+- Reworked Sixel preview rendering to use an existing PowerShell `Sixel` module only, normalize converter output into complete terminal sequences, and fall back to native previews with actionable warnings.
+- Reworked terminal image width resolution to honor Pi project/global `terminal.imageWidthCells` settings with a documented default fallback.
+
+### Fixed
+- Prevented extension debug logging from writing terminal output; debug events now remain file-based and disabled by default.
+- Preserved Sixel, Kitty, and iTerm inline image protocol rows during preview width fitting.
+
 ## [1.0.11] - 2026-04-25
 
 ### Changed

package/README.md

@@ -114,6 +114,7 @@ Pi's built-in image paste shortcut is not overridden by default. To keep the pre
 |----------|-------------|---------|
 | `PI_IMAGE_TOOLS_RECENT_DIRS` | Semicolon-separated directories to search for recent images | Platform defaults listed below |
 | `PI_IMAGE_TOOLS_RECENT_CACHE_DIR` | Custom cache directory for clipboard-pasted images | OS temp dir + `pi-image-tools/recent-cache` |
+| `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES` | Maximum accepted image payload size before attachment, recent-cache writes, and preview conversion | `20971520` (20 MB) |
 
 Example:
 
@@ -254,8 +255,10 @@ When you queue one or more images, the extension renders an inline preview insid
 
 Preview behavior:
 - up to **3 images** are previewed per message
-- Sixel rendering is attempted on Windows when available
+- Sixel rendering is attempted on Windows when the PowerShell `Sixel` module is already installed
+- no PowerShell modules are installed automatically at runtime
 - native TUI image rendering is used as the fallback
+- image payloads over `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES` are rejected before attachment, recent-cache writes, or Sixel conversion
 - inline width fitting now preserves Sixel, Kitty, and iTerm image protocol rows instead of truncating them like plain text
 
 ### Clipboard readers
@@ -285,11 +288,16 @@ pi-image-tools/
 │   ├── clipboard.ts            # Cross-platform clipboard image reading
 │   ├── config.ts               # Runtime config loading and validation
 │   ├── debug-logger.ts         # File-based debug logging
+│   ├── errors.ts               # Shared error normalization
+│   ├── image-mime.ts           # Shared image MIME and extension mapping
+│   ├── image-size.ts           # Shared image byte-size limits
 │   ├── recent-images.ts        # Recent image discovery and cache management
 │   ├── image-preview.ts        # Preview building and Sixel/native rendering
 │   ├── inline-user-preview.ts  # Inline preview patching for user messages
 │   ├── keybindings.ts          # Keyboard shortcut registration
-│   ├── temp-file.ts            # Temporary file management and cleanup
+│   ├── powershell.ts           # Shared PowerShell command runner
+│   ├── sixel-protocol.ts       # Sixel protocol normalization and render lines
+│   ├── terminal-image-width.ts # Terminal image width settings resolution
 │   └── types.ts                # Shared TypeScript types
 └── config/
     └── config.example.json     # Starter runtime config

package/package.json

@@ -1,66 +1,66 @@
-{
-  "name": "pi-image-tools",
-  "version": "1.0.11",
-  "description": "Image attachment and rendering extension for Pi TUI",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "test": "node --test",
-    "check": "npm run lint && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-coding-agent",
-    "pi-tui",
-    "coding-agent",
-    "image",
-    "image-attachment",
-    "image-preview",
-    "clipboard",
-    "preview",
-    "windows"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-image-tools.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-image-tools#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-image-tools/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.70.2",
-    "@mariozechner/pi-tui": "^0.70.2"
-  },
-  "optionalDependencies": {
-    "@mariozechner/clipboard": "^0.3.3"
-  }
-}
+{
+  "name": "pi-image-tools",
+  "version": "1.1.0",
+  "description": "Image attachment and rendering extension for Pi TUI",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "node --test",
+    "check": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi-tui",
+    "coding-agent",
+    "image",
+    "image-attachment",
+    "image-preview",
+    "clipboard",
+    "preview",
+    "windows"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-image-tools.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-image-tools#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-image-tools/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.72.0",
+    "@mariozechner/pi-tui": "^0.72.0"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "^0.3.5"
+  }
+}

package/src/clipboard.ts

@@ -1,6 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 
+import { isErrnoException } from "./errors.js";
+import { normalizeMimeType, selectPreferredImageMimeType, SUPPORTED_IMAGE_MIME_TYPES } from "./image-mime.js";
+import { runPowerShellCommand } from "./powershell.js";
 import type { ClipboardImage, ClipboardModule } from "./types.js";
 
 const require = createRequire(import.meta.url);
@@ -8,14 +11,6 @@ const require = createRequire(import.meta.url);
 const LIST_TYPES_TIMEOUT_MS = 1000;
 const READ_TIMEOUT_MS = 5000;
 const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
-const SUPPORTED_IMAGE_MIME_TYPES = [
-  "image/png",
-  "image/jpeg",
-  "image/webp",
-  "image/gif",
-  "image/bmp",
-] as const;
-
 let cachedClipboardModule: ClipboardModule | null | undefined;
 
 interface CommandResult {
@@ -29,10 +24,6 @@ interface ClipboardReadResult {
   image: ClipboardImage | null;
 }
 
-function isErrnoException(error: Error): error is NodeJS.ErrnoException {
-  return "code" in error;
-}
-
 function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
   return platform !== "linux" || Boolean(environment.DISPLAY || environment.WAYLAND_DISPLAY);
 }
@@ -41,27 +32,6 @@ function isWaylandSession(environment: NodeJS.ProcessEnv): boolean {
   return Boolean(environment.WAYLAND_DISPLAY) || environment.XDG_SESSION_TYPE === "wayland";
 }
 
-function normalizeMimeType(mimeType: string): string {
-  return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-}
-
-function selectPreferredImageMimeType(mimeTypes: readonly string[]): string | null {
-  const normalized = mimeTypes
-    .map((mimeType) => mimeType.trim())
-    .filter((mimeType) => mimeType.length > 0)
-    .map((mimeType) => ({ raw: mimeType, normalized: normalizeMimeType(mimeType) }));
-
-  for (const preferredMimeType of SUPPORTED_IMAGE_MIME_TYPES) {
-    const match = normalized.find((mimeType) => mimeType.normalized === preferredMimeType);
-    if (match) {
-      return match.raw;
-    }
-  }
-
-  const firstImage = normalized.find((mimeType) => mimeType.normalized.startsWith("image/"));
-  return firstImage?.raw ?? null;
-}
-
 function loadClipboardModule(
   platform: NodeJS.Platform = process.platform,
   environment: NodeJS.ProcessEnv = process.env,
@@ -141,10 +111,6 @@ function runCommand(
   };
 }
 
-function encodePowerShell(script: string): string {
-  return Buffer.from(script, "utf16le").toString("base64");
-}
-
 function readClipboardImageViaPowerShell(): ClipboardReadResult {
   const script = `
 $ErrorActionPreference = 'Stop'
@@ -170,33 +136,18 @@ try {
 }
 `;
 
-  const result = spawnSync(
-    "powershell.exe",
-    [
-      "-NoProfile",
-      "-NonInteractive",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-STA",
-      "-EncodedCommand",
-      encodePowerShell(script),
-    ],
-    {
-      encoding: "utf8",
-      timeout: READ_TIMEOUT_MS,
-      maxBuffer: MAX_BUFFER_BYTES,
-      windowsHide: true,
-    },
-  );
+  const result = runPowerShellCommand(script, {
+    encoded: true,
+    sta: true,
+    timeout: READ_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER_BYTES,
+  });
 
-  if (result.error) {
-    return {
-      available: !isErrnoException(result.error) || result.error.code !== "ENOENT",
-      image: null,
-    };
+  if (result.missingCommand) {
+    return { available: false, image: null };
   }
 
-  if (result.status !== 0) {
+  if (!result.ok) {
     return { available: true, image: null };
   }
 

package/src/debug-logger.ts

@@ -2,20 +2,13 @@ import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
 import { getExtensionRoot, type ImageToolsConfig } from "./config.js";
+import { getErrorMessage } from "./errors.js";
 
 const DEBUG_DIRECTORY_NAME = "debug";
 const DEBUG_LOG_FILE_NAME = "debug.log";
 
 type DebugFields = Record<string, unknown>;
 
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error && error.message.trim().length > 0) {
-    return error.message;
-  }
-
-  return "Unknown error";
-}
-
 export class DebugLogger {
   private readonly logPath: string | undefined;
 

package/src/errors.ts

@@ -0,0 +1,11 @@
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return "Unknown error";
+}
+
+export function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/src/image-mime.ts

@@ -0,0 +1,60 @@
+const PREFERRED_IMAGE_MIME_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+  "image/bmp",
+] as const;
+
+const MIME_TYPE_TO_EXTENSION = new Map<string, string>([
+  ["image/png", "png"],
+  ["image/jpeg", "jpg"],
+  ["image/webp", "webp"],
+  ["image/gif", "gif"],
+  ["image/bmp", "bmp"],
+  ["image/tiff", "tiff"],
+]);
+
+const EXTENSION_TO_MIME_TYPE = new Map<string, string>([
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".webp", "image/webp"],
+  [".gif", "image/gif"],
+  [".bmp", "image/bmp"],
+]);
+
+export const SUPPORTED_IMAGE_MIME_TYPES: readonly string[] = PREFERRED_IMAGE_MIME_TYPES;
+
+export function normalizeMimeType(mimeType: string): string {
+  return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
+}
+
+export function selectPreferredImageMimeType(mimeTypes: readonly string[]): string | null {
+  const normalized = mimeTypes
+    .map((mimeType) => mimeType.trim())
+    .filter((mimeType) => mimeType.length > 0)
+    .map((mimeType) => ({ raw: mimeType, normalized: normalizeMimeType(mimeType) }));
+
+  for (const preferredMimeType of SUPPORTED_IMAGE_MIME_TYPES) {
+    const match = normalized.find((mimeType) => mimeType.normalized === preferredMimeType);
+    if (match) {
+      return match.raw;
+    }
+  }
+
+  const firstImage = normalized.find((mimeType) => mimeType.normalized.startsWith("image/"));
+  return firstImage?.raw ?? null;
+}
+
+export function mimeTypeToExtension(mimeType: string, fallbackExtension = "png"): string {
+  return MIME_TYPE_TO_EXTENSION.get(normalizeMimeType(mimeType)) ?? fallbackExtension;
+}
+
+export function extensionToMimeType(fileNameOrExtension: string): string | null {
+  const extension = fileNameOrExtension.startsWith(".")
+    ? fileNameOrExtension.toLowerCase()
+    : `.${fileNameOrExtension.toLowerCase()}`;
+
+  return EXTENSION_TO_MIME_TYPE.get(extension) ?? null;
+}

package/src/image-preview.ts

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -15,6 +14,12 @@ import {
   type Component,
 } from "@mariozechner/pi-tui";
 
+import { isRecord } from "./config.js";
+import type { DebugLogger } from "./debug-logger.js";
+import { getErrorMessage } from "./errors.js";
+import { getBase64DecodedByteLength, assertImageWithinByteLimit } from "./image-size.js";
+import { mimeTypeToExtension } from "./image-mime.js";
+import { runPowerShellCommand } from "./powershell.js";
 import { buildSixelRenderLines, ensureCompleteSixelSequence } from "./sixel-protocol.js";
 import {
   DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS,
@@ -77,22 +82,6 @@ function normalizeText(value: unknown): string {
   return typeof value === "string" ? value.trim() : "";
 }
 
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error && error.message.trim()) {
-    return error.message;
-  }
-
-  return "Unknown error";
-}
-
-function toRecord(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return {};
-  }
-
-  return value as Record<string, unknown>;
-}
-
 function normalizeEnvValue(value: string | undefined): string {
   return typeof value === "string" ? value.trim().toLowerCase() : "";
 }
@@ -118,63 +107,6 @@ function shouldAttemptSixelRendering(): boolean {
   return !getCapabilities().images;
 }
 
-function runPowerShellCommand(
-  script: string,
-  args: string[] = [],
-): { ok: boolean; stdout: string; stderr: string; reason?: string } {
-  if (process.platform !== "win32") {
-    return {
-      ok: false,
-      stdout: "",
-      stderr: "",
-      reason: "PowerShell-based Sixel rendering is only available on Windows.",
-    };
-  }
-
-  const result = spawnSync(
-    "powershell.exe",
-    [
-      "-NoProfile",
-      "-NonInteractive",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-Command",
-      script,
-      ...args,
-    ],
-    {
-      encoding: "utf8",
-      timeout: POWER_SHELL_TIMEOUT_MS,
-      maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
-      windowsHide: true,
-    },
-  );
-
-  if (result.error) {
-    return {
-      ok: false,
-      stdout: result.stdout ?? "",
-      stderr: result.stderr ?? "",
-      reason: getErrorMessage(result.error),
-    };
-  }
-
-  if (result.status !== 0) {
-    return {
-      ok: false,
-      stdout: result.stdout ?? "",
-      stderr: result.stderr ?? "",
-      reason: `PowerShell exited with code ${result.status}`,
-    };
-  }
-
-  return {
-    ok: true,
-    stdout: result.stdout ?? "",
-    stderr: result.stderr ?? "",
-  };
-}
-
 const sixelAvailabilityState: SixelAvailability = {
   checked: false,
   available: false,
@@ -191,26 +123,16 @@ $ProgressPreference = 'SilentlyContinue'
 
 $module = Get-Module -ListAvailable -Name Sixel | Sort-Object Version -Descending | Select-Object -First 1
 if ($null -eq $module) {
-  try {
-    if (Get-Command Install-Module -ErrorAction SilentlyContinue) {
-      Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber -Repository PSGallery -ErrorAction Stop | Out-Null
-    } elseif (Get-Command Install-PSResource -ErrorAction SilentlyContinue) {
-      Install-PSResource -Name Sixel -Scope CurrentUser -TrustRepository -Reinstall -Force -ErrorAction Stop | Out-Null
-    }
-  } catch {
-  }
-
-  $module = Get-Module -ListAvailable -Name Sixel | Sort-Object Version -Descending | Select-Object -First 1
-}
-
-if ($null -eq $module) {
-  Write-Error 'Sixel PowerShell module is unavailable.'
+  Write-Error 'Sixel PowerShell module is unavailable. Install the Sixel module manually to enable Sixel previews.'
 }
 
 Write-Output ('Sixel/' + $module.Version.ToString())
 `;
 
-  const result = runPowerShellCommand(script);
+  const result = runPowerShellCommand(script, {
+    timeout: POWER_SHELL_TIMEOUT_MS,
+    maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
+  });
   sixelAvailabilityState.checked = true;
 
   if (!result.ok) {
@@ -219,7 +141,7 @@ Write-Output ('Sixel/' + $module.Version.ToString())
     sixelAvailabilityState.available = false;
     sixelAvailabilityState.version = undefined;
     sixelAvailabilityState.reason =
-      stderr || stdout || result.reason || "Failed to detect/install the Sixel PowerShell module.";
+      stderr || stdout || result.reason || "Failed to detect the Sixel PowerShell module.";
     return sixelAvailabilityState;
   }
 
@@ -232,26 +154,6 @@ Write-Output ('Sixel/' + $module.Version.ToString())
   return sixelAvailabilityState;
 }
 
-function extensionForImageMimeType(mimeType: string): string {
-  const normalized = mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-  switch (normalized) {
-    case "image/png":
-      return "png";
-    case "image/jpeg":
-      return "jpg";
-    case "image/webp":
-      return "webp";
-    case "image/gif":
-      return "gif";
-    case "image/bmp":
-      return "bmp";
-    case "image/tiff":
-      return "tiff";
-    default:
-      return "png";
-  }
-}
-
 function escapePowerShellSingleQuoted(value: string): string {
   return value.replace(/'/g, "''");
 }
@@ -260,9 +162,10 @@ function convertImageToSixelSequence(
   image: ImagePayload,
 ): { sequence?: string; error?: string } {
   const tempBaseDir = mkdtempSync(join(tmpdir(), "pi-image-tools-image-"));
-  const imagePath = join(tempBaseDir, `preview.${extensionForImageMimeType(image.mimeType)}`);
+  const imagePath = join(tempBaseDir, `preview.${mimeTypeToExtension(image.mimeType)}`);
 
   try {
+    assertImageWithinByteLimit(getBase64DecodedByteLength(image.data), "Preview image");
     const bytes = Buffer.from(image.data, "base64");
     if (bytes.length === 0) {
       return { error: "Image conversion failed: clipboard payload was empty." };
@@ -292,7 +195,10 @@ if ([string]::IsNullOrWhiteSpace($rendered)) {
 Write-Output $rendered
 `;
 
-    const result = runPowerShellCommand(script);
+    const result = runPowerShellCommand(script, {
+      timeout: POWER_SHELL_TIMEOUT_MS,
+      maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
+    });
     if (!result.ok) {
       const detail = normalizeText(result.stderr) || normalizeText(result.stdout) || result.reason;
       return {
@@ -328,15 +234,22 @@ function estimateImageRows(image: ImagePayload, maxWidthCells: number): number {
 }
 
 function parseImagePreviewDetails(value: unknown): ImagePreviewDetails | null {
-  const record = toRecord(value);
-  const itemsRaw = record.items;
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const itemsRaw = value.items;
   if (!Array.isArray(itemsRaw)) {
     return null;
   }
 
   const items: ImagePreviewItem[] = [];
   for (const raw of itemsRaw) {
-    const itemRecord = toRecord(raw);
+    if (!isRecord(raw)) {
+      continue;
+    }
+
+    const itemRecord = raw;
     const protocol = itemRecord.protocol === "sixel" ? "sixel" : "native";
     const mimeType = typeof itemRecord.mimeType === "string" ? itemRecord.mimeType : "image/png";
     const rows =
@@ -432,7 +345,26 @@ export function buildPreviewItems(
   });
 }
 
-export function registerImagePreviewDisplay(pi: ExtensionAPI): void {
+export interface RegisterImagePreviewDisplayOptions {
+  logger?: DebugLogger;
+}
+
+function logPreviewHandlerError(
+  logger: DebugLogger | undefined,
+  event: string,
+  error: unknown,
+): void {
+  try {
+    logger?.log(event, { error: getErrorMessage(error) });
+  } catch {
+    // Debug logging is best-effort inside Pi event handlers.
+  }
+}
+
+export function registerImagePreviewDisplay(
+  pi: ExtensionAPI,
+  options: RegisterImagePreviewDisplayOptions = {},
+): void {
   let warnedSixelSetup = false;
 
   pi.registerMessageRenderer<ImagePreviewDetails>(
@@ -481,17 +413,21 @@ export function registerImagePreviewDisplay(pi: ExtensionAPI): void {
   );
 
   pi.on("session_start", async (_event, ctx) => {
-    if (!shouldAttemptSixelRendering()) {
-      return;
-    }
+    try {
+      if (!shouldAttemptSixelRendering()) {
+        return;
+      }
 
-    const availability = ensureSixelModuleAvailable();
-    if (!availability.available && !warnedSixelSetup && ctx.hasUI) {
-      warnedSixelSetup = true;
-      ctx.ui.notify(
-        `Image preview fallback active: ${availability.reason || "Sixel module unavailable."}`,
-        "warning",
-      );
+      const availability = ensureSixelModuleAvailable();
+      if (!availability.available && !warnedSixelSetup && ctx.hasUI) {
+        warnedSixelSetup = true;
+        ctx.ui.notify(
+          `Image preview fallback active: ${availability.reason || "Sixel module unavailable."}`,
+          "warning",
+        );
+      }
+    } catch (error) {
+      logPreviewHandlerError(options.logger, "image-preview.session_start_failed", error);
     }
   });
 }

package/src/image-size.ts

@@ -0,0 +1,63 @@
+export const IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR = "PI_IMAGE_TOOLS_MAX_IMAGE_BYTES";
+export const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+
+function parseMaxImageBytes(environment: NodeJS.ProcessEnv): number {
+  const rawValue = environment[IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR]?.trim();
+  if (!rawValue) {
+    return DEFAULT_MAX_IMAGE_BYTES;
+  }
+
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new Error(
+      `${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} must be a positive byte count when set.`,
+    );
+  }
+
+  return Math.floor(parsed);
+}
+
+export function getMaxImageBytes(environment: NodeJS.ProcessEnv = process.env): number {
+  return parseMaxImageBytes(environment);
+}
+
+export function formatByteLimit(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+
+  const units = ["KB", "MB", "GB"] as const;
+  let value = bytes / 1024;
+  let unitIndex = 0;
+
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+
+  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unitIndex]}`;
+}
+
+export function assertImageWithinByteLimit(
+  sizeBytes: number,
+  label: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): void {
+  const maxImageBytes = getMaxImageBytes(environment);
+  if (sizeBytes > maxImageBytes) {
+    throw new Error(
+      `${label} is too large (${formatByteLimit(sizeBytes)}). The pi-image-tools limit is ${formatByteLimit(maxImageBytes)}. Set ${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} to a larger byte count if needed.`,
+    );
+  }
+}
+
+export function getBase64DecodedByteLength(base64Data: string): number {
+  const normalized = base64Data.trim().replace(/^data:[^,]*,/, "").replace(/\s/g, "");
+  if (normalized.length === 0) {
+    return 0;
+  }
+
+  const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor((normalized.length * 3) / 4) - padding);
+}
+

package/src/index.ts

@@ -4,6 +4,8 @@ import { readClipboardImage } from "./clipboard.js";
 import { registerPasteImageCommand } from "./commands.js";
 import { loadImageToolsConfig } from "./config.js";
 import { DebugLogger } from "./debug-logger.js";
+import { getErrorMessage } from "./errors.js";
+import { assertImageWithinByteLimit } from "./image-size.js";
 import {
   IMAGE_PREVIEW_CUSTOM_TYPE,
   buildPreviewItems,
@@ -27,15 +29,8 @@ const IMAGE_ATTACHMENT_INDICATOR = "[󰈟 Image Attached]";
 
 interface PendingImage extends ImagePayload {}
 
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error && error.message.trim().length > 0) {
-    return error.message;
-  }
-
-  return "Unknown error";
-}
-
 function imageToBase64(image: ClipboardImage): string {
+  assertImageWithinByteLimit(image.bytes.length, "Image attachment");
   return Buffer.from(image.bytes).toString("base64");
 }
 
@@ -155,8 +150,8 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
     pasteImageShortcutsConfigured: config.shortcuts.pasteImage !== undefined,
   });
 
-  registerInlineUserImagePreview(pi);
-  registerImagePreviewDisplay(pi);
+  registerInlineUserImagePreview(pi, { logger });
+  registerImagePreviewDisplay(pi, { logger });
 
   const pasteImageFromClipboard = async (ctx: PasteContext): Promise<void> => {
     if (!ctx.hasUI) {

package/src/inline-user-preview.ts

@@ -5,6 +5,9 @@ import {
 } from "@mariozechner/pi-coding-agent";
 import { Image, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 
+import { isRecord } from "./config.js";
+import type { DebugLogger } from "./debug-logger.js";
+import { getErrorMessage } from "./errors.js";
 import { buildPreviewItems, type ImagePayload, type ImagePreviewItem } from "./image-preview.js";
 import { buildSixelRenderLines, isInlineImageProtocolLine } from "./sixel-protocol.js";
 import { setActiveTerminalImageSettingsCwd } from "./terminal-image-width.js";
@@ -108,19 +111,15 @@ function renderPreviewLines(items: readonly ImagePreviewItem[], width: number):
 }
 
 function toUserMessage(value: unknown): UserMessageLike {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return {};
-  }
-
-  return value as UserMessageLike;
+  return isRecord(value) ? value : {};
 }
 
 function toImageContent(value: unknown): UserImageContent | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     return null;
   }
 
-  const record = value as Record<string, unknown>;
+  const record = value;
   if (record.type !== "image") {
     return null;
   }
@@ -237,7 +236,19 @@ function assignPreviewItemsToLatestUserMessage(
   }
 }
 
-function patchInteractiveMode(): void {
+function logInlinePreviewError(
+  logger: DebugLogger | undefined,
+  event: string,
+  error: unknown,
+): void {
+  try {
+    logger?.log(event, { error: getErrorMessage(error) });
+  } catch {
+    // Debug logging is best-effort inside Pi event handlers.
+  }
+}
+
+function patchInteractiveMode(logger?: DebugLogger): void {
   const prototype = (InteractiveMode as unknown as { prototype: InteractiveModePrototype }).prototype;
   if (!prototype) {
     return;
@@ -281,7 +292,8 @@ function patchInteractiveMode(): void {
     if (imagePayloads.length > 0) {
       try {
         previewItems = buildPreviewItems(imagePayloads);
-      } catch {
+      } catch (error) {
+        logInlinePreviewError(logger, "inline-user-preview.build_preview_failed", error);
         previewItems = [];
       }
     }
@@ -303,31 +315,53 @@ function patchInteractiveMode(): void {
   prototype.__piImageToolsPreviewPatched = true;
 }
 
-export function registerInlineUserImagePreview(pi: ExtensionAPI): void {
-  const schedulePatch = (): void => {
-    setTimeout(() => {
-      patchInteractiveMode();
-      patchUserMessageRender();
-    }, 0);
+export interface RegisterInlineUserImagePreviewOptions {
+  logger?: DebugLogger;
+}
 
+export function registerInlineUserImagePreview(
+  pi: ExtensionAPI,
+  options: RegisterInlineUserImagePreviewOptions = {},
+): void {
+  const runPatch = (delayMs: number): void => {
     setTimeout(() => {
-      patchInteractiveMode();
-      patchUserMessageRender();
-    }, 25);
+      try {
+        patchInteractiveMode(options.logger);
+        patchUserMessageRender();
+      } catch (error) {
+        logInlinePreviewError(options.logger, "inline-user-preview.patch_failed", error);
+      }
+    }, delayMs);
+  };
+
+  const schedulePatch = (): void => {
+    runPatch(0);
+    runPatch(25);
+  };
+
+  const handleSessionEvent = (eventName: string, cwd: string | undefined): void => {
+    try {
+      setActiveTerminalImageSettingsCwd(cwd);
+      schedulePatch();
+    } catch (error) {
+      logInlinePreviewError(options.logger, `inline-user-preview.${eventName}_failed`, error);
+    }
   };
 
   pi.on("session_start", async (_event, ctx) => {
-    setActiveTerminalImageSettingsCwd(ctx.cwd);
-    schedulePatch();
+    handleSessionEvent("session_start", ctx.cwd);
   });
 
   pi.on("before_agent_start", async (_event, ctx) => {
-    setActiveTerminalImageSettingsCwd(ctx.cwd);
-    schedulePatch();
+    handleSessionEvent("before_agent_start", ctx.cwd);
   });
 
-  pi.on("session_switch", async (_event, ctx) => {
-    setActiveTerminalImageSettingsCwd(ctx.cwd);
-    schedulePatch();
+  const onSessionSwitch = pi.on as unknown as (
+    event: "session_switch",
+    handler: (_event: unknown, ctx: { cwd?: string }) => Promise<void>,
+  ) => void;
+
+  onSessionSwitch("session_switch", async (_event, ctx) => {
+    handleSessionEvent("session_switch", ctx.cwd);
   });
 }

package/src/powershell.ts

@@ -0,0 +1,71 @@
+import { spawnSync } from "node:child_process";
+
+import { getErrorMessage, isErrnoException } from "./errors.js";
+
+export interface PowerShellCommandResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  missingCommand: boolean;
+  reason?: string;
+}
+
+export interface RunPowerShellCommandOptions {
+  args?: string[];
+  encoded?: boolean;
+  maxBuffer: number;
+  sta?: boolean;
+  timeout: number;
+}
+
+function encodePowerShell(script: string): string {
+  return Buffer.from(script, "utf16le").toString("base64");
+}
+
+export function runPowerShellCommand(
+  script: string,
+  options: RunPowerShellCommandOptions,
+): PowerShellCommandResult {
+  if (process.platform !== "win32") {
+    return {
+      ok: false,
+      stdout: "",
+      stderr: "",
+      missingCommand: false,
+      reason: "PowerShell is only available through pi-image-tools on Windows.",
+    };
+  }
+
+  const commandArgs = [
+    "-NoProfile",
+    "-NonInteractive",
+    ...(options.sta ? ["-STA"] : []),
+    ...(options.encoded ? ["-EncodedCommand", encodePowerShell(script)] : ["-Command", script]),
+    ...(options.args ?? []),
+  ];
+
+  const result = spawnSync("powershell.exe", commandArgs, {
+    encoding: "utf8",
+    timeout: options.timeout,
+    maxBuffer: options.maxBuffer,
+    windowsHide: true,
+  });
+
+  if (result.error) {
+    return {
+      ok: false,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
+      reason: getErrorMessage(result.error),
+    };
+  }
+
+  return {
+    ok: result.status === 0,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    missingCommand: false,
+    reason: result.status === 0 ? undefined : `PowerShell exited with code ${result.status}`,
+  };
+}

package/src/recent-images.ts

@@ -11,6 +11,8 @@ import {
 import { homedir, tmpdir } from "node:os";
 import { basename, extname, join, resolve } from "node:path";
 
+import { extensionToMimeType, mimeTypeToExtension } from "./image-mime.js";
+import { assertImageWithinByteLimit, formatByteLimit } from "./image-size.js";
 import type { ClipboardImage } from "./types.js";
 
 export const RECENT_IMAGE_ENV_VAR = "PI_IMAGE_TOOLS_RECENT_DIRS";
@@ -30,15 +32,6 @@ const SCREENSHOT_NAME_PATTERNS: readonly RegExp[] = [
   /^スクリーンショット/i,
 ];
 
-const EXTENSION_TO_MIME = new Map<string, string>([
-  [".png", "image/png"],
-  [".jpg", "image/jpeg"],
-  [".jpeg", "image/jpeg"],
-  [".webp", "image/webp"],
-  [".gif", "image/gif"],
-  [".bmp", "image/bmp"],
-]);
-
 interface RecentImageSource {
   path: string;
   filterScreenshotNames: boolean;
@@ -193,27 +186,11 @@ function isLikelyScreenshotName(name: string): boolean {
 }
 
 function toMimeType(fileName: string): string | null {
-  const extension = extname(fileName).toLowerCase();
-  return EXTENSION_TO_MIME.get(extension) ?? null;
+  return extensionToMimeType(extname(fileName));
 }
 
-function extensionForMimeType(mimeType: string): string {
-  const normalized = mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-
-  switch (normalized) {
-    case "image/png":
-      return "png";
-    case "image/jpeg":
-      return "jpg";
-    case "image/webp":
-      return "webp";
-    case "image/gif":
-      return "gif";
-    case "image/bmp":
-      return "bmp";
-    default:
-      return "png";
-  }
+function isExtensionOwnedCacheFileName(name: string): boolean {
+  return /^pi-recent-\d+-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[a-z0-9]+$/i.test(name);
 }
 
 function listRecentImagesFromSource(source: RecentImageSource): RecentImageCandidate[] {
@@ -372,7 +349,7 @@ function pruneCacheDirectory(cacheDirectory: string, maxCacheFiles: number): voi
           return null;
         }
 
-        if (!toMimeType(name)) {
+        if (!isExtensionOwnedCacheFileName(name) || !toMimeType(name)) {
           return null;
         }
 
@@ -406,8 +383,9 @@ export function persistImageToRecentCache(
   }
 
   const environment = options.environment ?? process.env;
+  assertImageWithinByteLimit(image.bytes.length, "Cached image", environment);
   const cacheDirectory = getRecentImageCacheDirectory(environment);
-  const extension = extensionForMimeType(image.mimeType);
+  const extension = mimeTypeToExtension(image.mimeType);
 
   mkdirSync(cacheDirectory, { recursive: true });
 
@@ -451,23 +429,6 @@ function formatRelativeAge(modifiedAtMs: number, nowMs: number): string {
   return `${deltaYears}y ago`;
 }
 
-function formatSize(sizeBytes: number): string {
-  if (sizeBytes < 1024) {
-    return `${sizeBytes} B`;
-  }
-
-  const units = ["KB", "MB", "GB"] as const;
-  let value = sizeBytes / 1024;
-  let unitIndex = 0;
-
-  while (value >= 1024 && unitIndex < units.length - 1) {
-    value /= 1024;
-    unitIndex += 1;
-  }
-
-  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unitIndex]}`;
-}
-
 function detectPathSeparator(pathValue: string): string {
   return pathValue.includes("\\") ? "\\" : "/";
 }
@@ -489,13 +450,17 @@ function abbreviatePath(pathValue: string, maxChars: number): string {
 
 export function formatRecentImageLabel(candidate: RecentImageCandidate, nowMs = Date.now()): string {
   const age = formatRelativeAge(candidate.modifiedAtMs, nowMs);
-  const size = formatSize(candidate.sizeBytes);
+  const size = formatByteLimit(candidate.sizeBytes);
   const shortPath = abbreviatePath(candidate.path, 64);
 
   return `${candidate.name} • ${age} • ${size} • ${shortPath}`;
 }
 
-export function loadRecentImage(candidate: RecentImageCandidate): ClipboardImage {
+export function loadRecentImage(
+  candidate: RecentImageCandidate,
+  environment: NodeJS.ProcessEnv = process.env,
+): ClipboardImage {
+  assertImageWithinByteLimit(candidate.sizeBytes, `Recent image ${candidate.name}`, environment);
   const raw = readFileSync(candidate.path);
   if (raw.length === 0) {
     throw new Error(`File is empty: ${candidate.path}`);

package/src/terminal-image-width.ts

@@ -1,6 +1,8 @@
 import { SettingsManager, getAgentDir } from "@mariozechner/pi-coding-agent";
 import { resolve } from "node:path";
 
+import { isRecord } from "./config.js";
+
 export const DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS = 60;
 
 export interface TerminalImageWidthOptions {
@@ -42,7 +44,7 @@ function normalizeImageWidthCells(value: unknown): number {
 }
 
 function readRawImageWidthCells(settings: unknown): unknown {
-  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+  if (!isRecord(settings)) {
     return undefined;
   }
 

package/src/temp-file.ts

@@ -1,82 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { mkdirSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import type { ClipboardImage } from "./types.js";
-
-function extensionForImageMimeType(mimeType: string): string {
-  const normalized = mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-
-  switch (normalized) {
-    case "image/png":
-      return "png";
-    case "image/jpeg":
-      return "jpg";
-    case "image/webp":
-      return "webp";
-    case "image/gif":
-      return "gif";
-    default:
-      return "png";
-  }
-}
-
-export class TempFileManager {
-  private readonly baseDir: string;
-  private readonly createdFiles = new Set<string>();
-  private exitHookRegistered = false;
-
-  constructor(baseDir: string = join(tmpdir(), "pi-images")) {
-    this.baseDir = baseDir;
-  }
-
-  registerExitCleanup(): void {
-    if (this.exitHookRegistered) {
-      return;
-    }
-
-    process.once("exit", () => {
-      this.cleanupSync();
-    });
-
-    this.exitHookRegistered = true;
-  }
-
-  saveImage(image: ClipboardImage): string {
-    mkdirSync(this.baseDir, { recursive: true });
-
-    const ext = extensionForImageMimeType(image.mimeType);
-    const filePath = join(this.baseDir, `pi-image-${Date.now()}-${randomUUID()}.${ext}`);
-
-    writeFileSync(filePath, Buffer.from(image.bytes));
-    this.createdFiles.add(filePath);
-
-    return filePath;
-  }
-
-  async cleanup(): Promise<void> {
-    this.cleanupSync();
-  }
-
-  cleanupSync(): void {
-    for (const filePath of this.createdFiles) {
-      try {
-        unlinkSync(filePath);
-      } catch {
-        // Best-effort cleanup only.
-      }
-    }
-
-    this.createdFiles.clear();
-
-    try {
-      const entries = readdirSync(this.baseDir);
-      if (entries.length === 0) {
-        rmSync(this.baseDir, { recursive: true, force: true });
-      }
-    } catch {
-      // Ignore directory cleanup errors.
-    }
-  }
-}