pi-image-tools 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.2.0] - 2026-05-22
+
+### Added
+- Added Linux Sixel previews through `img2sixel` detection and conversion when the converter is available on `PATH`.
+- Added asynchronous image preview conversion so user-message previews can fall back without blocking the TUI.
+
+### Changed
+- Updated Pi peer dependencies and runtime imports to the `@earendil-works` scope.
+- Improved preview setup diagnostics so missing Sixel converters report actionable fallback warnings.
+
+### Fixed
+- Hardened debug logging with redaction and asynchronous file writes while keeping logging disabled by default.
+
 ## [1.1.0] - 2026-05-03
 
 ### Added

package/README.md

@@ -255,8 +255,8 @@ 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 the PowerShell `Sixel` module is already installed
-- no PowerShell modules are installed automatically at runtime
+- Sixel rendering is attempted on Windows when the PowerShell `Sixel` module is already installed and on Linux when `img2sixel` is available on `PATH`
+- no PowerShell modules or Linux packages 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
@@ -311,9 +311,14 @@ pi-image-tools/
 | Linux clipboard paste fails | Make sure you are in a graphical session and install `wl-clipboard` or `xclip` |
 | Recent picker is empty | Add directories via `PI_IMAGE_TOOLS_RECENT_DIRS` or paste images from clipboard first so they enter the recent cache |
 | `/paste-image recent` says it requires interactive mode | Run Pi in interactive TUI mode |
-| Sixel preview warning appears | On Windows, install the PowerShell `Sixel` module and restart Pi |
+| Sixel preview warning appears | On Linux, install `img2sixel` (for example from `libsixel-bin`); on Windows, install the PowerShell `Sixel` module and restart Pi |
 
-Manual Sixel installation:
+Manual Sixel installation examples:
+
+```bash
+# Debian/Ubuntu
+sudo apt install libsixel-bin
+```
 
 ```powershell
 Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber

package/package.json

@@ -1,66 +1,69 @@
-{
-  "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"
-  }
-}
+{
+  "name": "pi-image-tools",
+  "version": "1.2.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": {
+    "typecheck": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noEmit",
+    "build": "npm run typecheck",
+    "lint": "npm run typecheck",
+    "test": "node --test",
+    "check": "npm run build && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi-tui",
+    "coding-agent",
+    "image",
+    "image-attachment",
+    "image-preview",
+    "clipboard",
+    "preview",
+    "windows",
+    "linux",
+    "cross-platform"
+  ],
+  "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": {
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@earendil-works/pi-tui": "^0.75.4"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "^0.3.6"
+  }
+}

package/src/clipboard.ts

@@ -24,7 +24,7 @@ interface ClipboardReadResult {
   image: ClipboardImage | null;
 }
 
-function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
+export function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
   return platform !== "linux" || Boolean(environment.DISPLAY || environment.WAYLAND_DISPLAY);
 }
 

package/src/commands.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import type { PasteImageCommandHandlers } from "./types.js";
 

package/src/config.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { KeyId } from "@mariozechner/pi-tui";
+import type { KeyId } from "@earendil-works/pi-tui";
 
 const CONFIG_FILE_NAME = "config.json";
 const EXTENSION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");

package/src/debug-logger.ts

@@ -1,23 +1,43 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
 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";
+const SECRET_KEYS = /api[_-]?key|authorization|token|secret|password/i;
 
 type DebugFields = Record<string, unknown>;
 
+interface DebugLoggerCreateOptions {
+  extensionRoot?: string;
+}
+
+function redactFields(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((entry) => redactFields(entry));
+  if (value && typeof value === "object") {
+    const output: Record<string, unknown> = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+      output[key] = SECRET_KEYS.test(key) ? "[REDACTED]" : redactFields(nestedValue);
+    }
+    return output;
+  }
+  return value;
+}
+
 export class DebugLogger {
+  private readonly debugDirectory: string | undefined;
   private readonly logPath: string | undefined;
+  private debugDirectoryReady = false;
+  private writeQueue: Promise<void> = Promise.resolve();
 
-  private constructor(private readonly enabled: boolean) {
-    this.logPath = enabled ? join(getExtensionRoot(), DEBUG_DIRECTORY_NAME, DEBUG_LOG_FILE_NAME) : undefined;
+  private constructor(private readonly enabled: boolean, extensionRoot = getExtensionRoot()) {
+    this.debugDirectory = enabled ? join(extensionRoot, DEBUG_DIRECTORY_NAME) : undefined;
+    this.logPath = this.debugDirectory ? join(this.debugDirectory, DEBUG_LOG_FILE_NAME) : undefined;
   }
 
-  static create(config: ImageToolsConfig): DebugLogger {
-    return new DebugLogger(config.debug);
+  static create(config: ImageToolsConfig, options: DebugLoggerCreateOptions = {}): DebugLogger {
+    return new DebugLogger(config.debug, options.extensionRoot);
   }
 
   log(event: string, fields: DebugFields = {}): void {
@@ -25,17 +45,38 @@ export class DebugLogger {
       return;
     }
 
-    const debugDirectory = join(getExtensionRoot(), DEBUG_DIRECTORY_NAME);
-
     try {
-      mkdirSync(debugDirectory, { recursive: true });
-      appendFileSync(
-        this.logPath,
-        `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...fields })}\n`,
-        "utf-8",
+      const redactedFields = redactFields(fields) as DebugFields;
+      const line = `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...redactedFields })}\n`;
+      this.writeQueue = this.writeQueue.then(
+        () => this.appendLine(line),
+        () => this.appendLine(line),
       );
-    } catch (error) {
-      throw new Error(`pi-image-tools debug logging failed at ${this.logPath}: ${getErrorMessage(error)}`);
+      void this.writeQueue.catch(() => undefined);
+    } catch {
+      // Debug logging must never affect extension behavior.
+    }
+  }
+
+  flush(): Promise<void> {
+    return this.writeQueue.catch(() => undefined);
+  }
+
+  private async appendLine(line: string): Promise<void> {
+    if (!this.logPath) {
+      return;
+    }
+
+    this.ensureDebugDirectory();
+    await appendFile(this.logPath, line, "utf-8");
+  }
+
+  private ensureDebugDirectory(): void {
+    if (this.debugDirectoryReady || !this.debugDirectory) {
+      return;
     }
+
+    mkdirSync(this.debugDirectory, { recursive: true });
+    this.debugDirectoryReady = true;
   }
 }

package/src/image-preview.ts

@@ -2,7 +2,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   calculateImageRows,
   Container,
@@ -12,14 +12,14 @@ import {
   Spacer,
   Text,
   type Component,
-} from "@mariozechner/pi-tui";
+} from "@earendil-works/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 { runBufferedCommand, runPowerShellCommandAsync, type BufferedCommandResult, type PowerShellCommandResult, type RunPowerShellCommandOptions } from "./powershell.js";
 import { buildSixelRenderLines, ensureCompleteSixelSequence } from "./sixel-protocol.js";
 import {
   DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS,
@@ -31,6 +31,8 @@ export const IMAGE_PREVIEW_CUSTOM_TYPE = "pi-image-tools-preview";
 const MAX_IMAGES_PER_MESSAGE = 3;
 const POWER_SHELL_TIMEOUT_MS = 120_000;
 const POWER_SHELL_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
+const LINUX_SIXEL_TIMEOUT_MS = 120_000;
+const LINUX_SIXEL_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
 const FORCE_SIXEL_ENV_VAR = "PI_IMAGE_TOOLS_FORCE_SIXEL";
 const DISABLE_SIXEL_ENV_VAR = "PI_IMAGE_TOOLS_DISABLE_SIXEL";
 
@@ -40,9 +42,22 @@ export type ImagePayload = {
   mimeType: string;
 };
 
+type SixelConverter = "powershell-sixel" | "img2sixel";
+type SixelProcessRunner = (
+  command: string,
+  args: readonly string[],
+  options: { timeout: number; maxBuffer: number; windowsHide?: boolean },
+) => Promise<BufferedCommandResult>;
+
+type SixelPowerShellRunner = (
+  script: string,
+  options: RunPowerShellCommandOptions,
+) => Promise<PowerShellCommandResult>;
+
 type SixelAvailability = {
   checked: boolean;
   available: boolean;
+  converter?: SixelConverter;
   version?: string;
   reason?: string;
 };
@@ -91,16 +106,19 @@ function isTruthyEnvFlag(value: string | undefined): boolean {
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
 
-function shouldAttemptSixelRendering(): boolean {
-  if (process.platform !== "win32") {
+function shouldAttemptSixelRendering(
+  environment: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (isTruthyEnvFlag(environment[DISABLE_SIXEL_ENV_VAR])) {
     return false;
   }
 
-  if (isTruthyEnvFlag(process.env[DISABLE_SIXEL_ENV_VAR])) {
+  if (platform !== "win32" && platform !== "linux") {
     return false;
   }
 
-  if (isTruthyEnvFlag(process.env[FORCE_SIXEL_ENV_VAR])) {
+  if (isTruthyEnvFlag(environment[FORCE_SIXEL_ENV_VAR])) {
     return true;
   }
 
@@ -112,9 +130,15 @@ const sixelAvailabilityState: SixelAvailability = {
   available: false,
 };
 
-function ensureSixelModuleAvailable(forceRefresh = false): SixelAvailability {
-  if (sixelAvailabilityState.checked && !forceRefresh) {
-    return sixelAvailabilityState;
+async function ensureSixelModuleAvailable(
+  forceRefresh = false,
+  powerShellRunner: SixelPowerShellRunner = runPowerShellCommandAsync,
+): Promise<SixelAvailability> {
+  const useCache = powerShellRunner === runPowerShellCommandAsync;
+  const state: SixelAvailability = useCache ? sixelAvailabilityState : { checked: false, available: false };
+
+  if (state.checked && !forceRefresh) {
+    return state;
   }
 
   const script = `
@@ -129,38 +153,103 @@ if ($null -eq $module) {
 Write-Output ('Sixel/' + $module.Version.ToString())
 `;
 
-  const result = runPowerShellCommand(script, {
+  const result = await powerShellRunner(script, {
     timeout: POWER_SHELL_TIMEOUT_MS,
     maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
   });
-  sixelAvailabilityState.checked = true;
+  state.checked = true;
 
   if (!result.ok) {
     const stderr = normalizeText(result.stderr);
     const stdout = normalizeText(result.stdout);
-    sixelAvailabilityState.available = false;
-    sixelAvailabilityState.version = undefined;
-    sixelAvailabilityState.reason =
+    state.available = false;
+    state.converter = undefined;
+    state.version = undefined;
+    state.reason =
       stderr || stdout || result.reason || "Failed to detect the Sixel PowerShell module.";
-    return sixelAvailabilityState;
+    return state;
   }
 
   const marker = normalizeText(result.stdout)
     .split(/\r?\n/)
     .find((line) => line.startsWith("Sixel/"));
-  sixelAvailabilityState.available = true;
-  sixelAvailabilityState.version = marker ? marker.slice("Sixel/".length) : undefined;
-  sixelAvailabilityState.reason = undefined;
-  return sixelAvailabilityState;
+  state.available = true;
+  state.converter = "powershell-sixel";
+  state.version = marker ? marker.slice("Sixel/".length) : undefined;
+  state.reason = undefined;
+  return state;
+}
+
+async function ensureLinuxSixelConverterAvailable(
+  forceRefresh = false,
+  processRunner: SixelProcessRunner = runBufferedCommand,
+): Promise<SixelAvailability> {
+  const useCache = processRunner === runBufferedCommand;
+  const state: SixelAvailability = useCache ? sixelAvailabilityState : { checked: false, available: false };
+
+  if (state.checked && !forceRefresh) {
+    return state;
+  }
+
+  state.checked = true;
+
+  const result = await processRunner("img2sixel", ["--version"], {
+    timeout: 5_000,
+    maxBuffer: 1024 * 1024,
+  });
+
+  if (result.error) {
+    state.available = false;
+    state.converter = undefined;
+    state.version = undefined;
+    state.reason = isErrnoLike(result.error, "ENOENT")
+      ? "img2sixel is not installed. Install libsixel-bin or an equivalent package to enable Linux Sixel previews."
+      : getErrorMessage(result.error);
+    return state;
+  }
+
+  if (result.status !== 0) {
+    state.available = false;
+    state.converter = undefined;
+    state.version = undefined;
+    state.reason = normalizeText(result.stderr.toString("utf8")) || normalizeText(result.stdout.toString("utf8")) || "img2sixel detection failed.";
+    return state;
+  }
+
+  state.available = true;
+  state.converter = "img2sixel";
+  state.version = normalizeText(result.stdout.toString("utf8")).split(/\r?\n/)[0] || undefined;
+  state.reason = undefined;
+  return state;
+}
+
+function ensureSixelConverterAvailable(
+  forceRefresh = false,
+  platform: NodeJS.Platform = process.platform,
+  processRunner: SixelProcessRunner = runBufferedCommand,
+  powerShellRunner: SixelPowerShellRunner = runPowerShellCommandAsync,
+): Promise<SixelAvailability> {
+  if (platform === "linux") {
+    return ensureLinuxSixelConverterAvailable(forceRefresh, processRunner);
+  }
+
+  return ensureSixelModuleAvailable(forceRefresh, powerShellRunner);
+}
+
+function isErrnoLike(error: unknown, code: string): boolean {
+  return error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === code;
 }
 
 function escapePowerShellSingleQuoted(value: string): string {
   return value.replace(/'/g, "''");
 }
 
-function convertImageToSixelSequence(
+async function convertImageToSixelSequence(
   image: ImagePayload,
-): { sequence?: string; error?: string } {
+  converter: SixelConverter,
+  processRunner: SixelProcessRunner = runBufferedCommand,
+  powerShellRunner: SixelPowerShellRunner = runPowerShellCommandAsync,
+): Promise<{ sequence?: string; error?: string }> {
   const tempBaseDir = mkdtempSync(join(tmpdir(), "pi-image-tools-image-"));
   const imagePath = join(tempBaseDir, `preview.${mimeTypeToExtension(image.mimeType)}`);
 
@@ -173,6 +262,33 @@ function convertImageToSixelSequence(
 
     writeFileSync(imagePath, bytes);
 
+    if (converter === "img2sixel") {
+      const result = await processRunner("img2sixel", [imagePath], {
+        timeout: LINUX_SIXEL_TIMEOUT_MS,
+        maxBuffer: LINUX_SIXEL_MAX_BUFFER_BYTES,
+      });
+
+      if (result.error) {
+        return { error: `Sixel conversion failed: ${getErrorMessage(result.error)}` };
+      }
+
+      if (result.status !== 0) {
+        const detail = normalizeText(result.stderr.toString("utf8")) || normalizeText(result.stdout.toString("utf8"));
+        return {
+          error: detail
+            ? `Sixel conversion failed: ${detail}`
+            : "Sixel conversion failed for an unknown reason.",
+        };
+      }
+
+      const normalized = ensureCompleteSixelSequence(result.stdout.toString("utf8"));
+      if (!normalized) {
+        return { error: "Sixel conversion produced empty output." };
+      }
+
+      return { sequence: normalized };
+    }
+
     const escapedPath = escapePowerShellSingleQuoted(imagePath);
 
     const script = `
@@ -195,7 +311,7 @@ if ([string]::IsNullOrWhiteSpace($rendered)) {
 Write-Output $rendered
 `;
 
-    const result = runPowerShellCommand(script, {
+    const result = await powerShellRunner(script, {
       timeout: POWER_SHELL_TIMEOUT_MS,
       maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
     });
@@ -291,47 +407,93 @@ function parseImagePreviewDetails(value: unknown): ImagePreviewDetails | null {
   return { items };
 }
 
-export type BuildPreviewItemsOptions = TerminalImageWidthOptions;
+export type BuildPreviewItemsOptions = TerminalImageWidthOptions & {
+  environment?: NodeJS.ProcessEnv;
+  logger?: DebugLogger;
+  platform?: NodeJS.Platform;
+  sixelProcessRunner?: SixelProcessRunner;
+  sixelPowerShellRunner?: SixelPowerShellRunner;
+};
 
-export function buildPreviewItems(
+function logSixelEvent(
+  logger: DebugLogger | undefined,
+  event: string,
+  fields: Record<string, unknown> = {},
+): void {
+  try {
+    logger?.log(event, fields);
+  } catch {
+    // Debug logging is best-effort and must never block image rendering.
+  }
+}
+
+export async function buildPreviewItems(
   images: readonly ImagePayload[],
   options: BuildPreviewItemsOptions = {},
-): ImagePreviewItem[] {
+): Promise<ImagePreviewItem[]> {
   const selectedImages = images.slice(0, MAX_IMAGES_PER_MESSAGE);
   if (selectedImages.length === 0) {
     return [];
   }
 
   const maxWidthCells = resolveTerminalImageWidthCells(options);
-  const attemptSixel = shouldAttemptSixelRendering();
-  const sixelState = attemptSixel ? ensureSixelModuleAvailable() : undefined;
+  const platform = options.platform ?? process.platform;
+  const processRunner = options.sixelProcessRunner ?? runBufferedCommand;
+  const powerShellRunner = options.sixelPowerShellRunner ?? runPowerShellCommandAsync;
+  const attemptSixel = shouldAttemptSixelRendering(options.environment, platform);
+  const sixelState = attemptSixel
+    ? await ensureSixelConverterAvailable(false, platform, processRunner, powerShellRunner)
+    : undefined;
+
+  logSixelEvent(options.logger, "image-preview.sixel.detected", {
+    attemptSixel,
+    available: sixelState?.available ?? false,
+    converter: sixelState?.converter ?? null,
+    reason: sixelState?.reason ?? null,
+    platform,
+  });
 
-  return selectedImages.map((image) => {
+  const items: ImagePreviewItem[] = [];
+  for (const image of selectedImages) {
     const rows = estimateImageRows(image, maxWidthCells);
 
-    if (attemptSixel && sixelState?.available) {
-      const conversion = convertImageToSixelSequence(image);
+    if (attemptSixel && sixelState?.available && sixelState.converter) {
+      const conversion = await convertImageToSixelSequence(image, sixelState.converter, processRunner, powerShellRunner);
       if (conversion.sequence) {
-        return {
+        logSixelEvent(options.logger, "image-preview.sixel.converted", {
+          converter: sixelState.converter,
+          mimeType: image.mimeType,
+          rows,
+          maxWidthCells,
+        });
+        items.push({
           protocol: "sixel",
           mimeType: image.mimeType,
           rows,
           maxWidthCells,
           sixelSequence: conversion.sequence,
-        };
+        });
+        continue;
       }
 
-      return {
+      logSixelEvent(options.logger, "image-preview.sixel.conversion_failed", {
+        converter: sixelState.converter,
+        mimeType: image.mimeType,
+        error: conversion.error ?? "unknown",
+      });
+
+      items.push({
         protocol: "native",
         mimeType: image.mimeType,
         rows,
         maxWidthCells,
         data: image.data,
         warning: conversion.error,
-      };
+      });
+      continue;
     }
 
-    return {
+    items.push({
       protocol: "native",
       mimeType: image.mimeType,
       rows,
@@ -339,10 +501,12 @@ export function buildPreviewItems(
       data: image.data,
       warning:
         attemptSixel && sixelState && !sixelState.available
-          ? `Sixel preview unavailable: ${sixelState.reason || "missing PowerShell Sixel module."}`
+          ? `Sixel preview unavailable: ${sixelState.reason || "missing Sixel converter."}`
           : undefined,
-    };
-  });
+    });
+  }
+
+  return items;
 }
 
 export interface RegisterImagePreviewDisplayOptions {
@@ -418,7 +582,7 @@ export function registerImagePreviewDisplay(
         return;
       }
 
-      const availability = ensureSixelModuleAvailable();
+      const availability = await ensureSixelConverterAvailable();
       if (!availability.available && !warnedSixelSetup && ctx.hasUI) {
         warnedSixelSetup = true;
         ctx.ui.notify(

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { readClipboardImage } from "./clipboard.js";
 import { registerPasteImageCommand } from "./commands.js";
@@ -108,12 +108,13 @@ function buildRecentImageEmptyStateMessage(searchedDirectories: readonly string[
   ].join(" ");
 }
 
-function showRecentSelectionPreview(
+async function showRecentSelectionPreview(
   pi: ExtensionAPI,
   image: ClipboardImage,
   cwd: string,
-): void {
-  const previewItems = buildPreviewItems(
+  logger: DebugLogger,
+): Promise<void> {
+  const previewItems = await buildPreviewItems(
     [
       {
         type: "image",
@@ -121,7 +122,7 @@ function showRecentSelectionPreview(
         mimeType: image.mimeType,
       },
     ],
-    { cwd },
+    { cwd, logger },
   );
 
   if (previewItems.length === 0) {
@@ -209,11 +210,9 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
       const selectedCandidate = discovery.candidates[selectedIndex];
       const selectedImage = loadRecentImage(selectedCandidate);
 
-      try {
-        showRecentSelectionPreview(pi, selectedImage, ctx.cwd);
-      } catch (error) {
+      void showRecentSelectionPreview(pi, selectedImage, ctx.cwd, logger).catch((error: unknown) => {
         ctx.ui.notify(`Could not render recent image preview: ${getErrorMessage(error)}`, "warning");
-      }
+      });
 
       queueImageAttachment(
         ctx,

package/src/inline-user-preview.ts

@@ -2,8 +2,8 @@ import {
   type ExtensionAPI,
   InteractiveMode,
   UserMessageComponent,
-} from "@mariozechner/pi-coding-agent";
-import { Image, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-coding-agent";
+import { Image, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import { isRecord } from "./config.js";
 import type { DebugLogger } from "./debug-logger.js";
@@ -288,16 +288,6 @@ function patchInteractiveMode(logger?: DebugLogger): void {
       : 0;
 
     const imagePayloads = extractImagePayloads(message);
-    let previewItems: ImagePreviewItem[] = [];
-    if (imagePayloads.length > 0) {
-      try {
-        previewItems = buildPreviewItems(imagePayloads);
-      } catch (error) {
-        logInlinePreviewError(logger, "inline-user-preview.build_preview_failed", error);
-        previewItems = [];
-      }
-    }
-
     const original = prototype.__piImageToolsOriginalAddMessageToChat;
     if (!original) {
       return;
@@ -305,11 +295,21 @@ function patchInteractiveMode(logger?: DebugLogger): void {
 
     original.call(this, message, options);
 
-    if (previewItems.length === 0) {
+    if (imagePayloads.length === 0) {
       return;
     }
 
-    assignPreviewItemsToLatestUserMessage(mode, beforeCount, previewItems);
+    void buildPreviewItems(imagePayloads, { logger })
+      .then((previewItems) => {
+        if (previewItems.length === 0) {
+          return;
+        }
+
+        assignPreviewItemsToLatestUserMessage(mode, beforeCount, previewItems);
+      })
+      .catch((error: unknown) => {
+        logInlinePreviewError(logger, "inline-user-preview.build_preview_failed", error);
+      });
   };
 
   prototype.__piImageToolsPreviewPatched = true;

package/src/keybindings.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { getAgentDir, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { TUI_KEYBINDINGS, type KeyId, type KeybindingsConfig } from "@mariozechner/pi-tui";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { TUI_KEYBINDINGS, type KeyId, type KeybindingsConfig } from "@earendil-works/pi-tui";
 
 import { isRecord, type ImageToolsConfig } from "./config.js";
 import type { DebugLogger } from "./debug-logger.js";

package/src/powershell.ts

@@ -1,71 +1,222 @@
-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}`,
-  };
-}
+import { spawn, 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 BufferedCommandResult {
+  status: number | null;
+  stdout: Buffer;
+  stderr: Buffer;
+  error?: Error;
+}
+
+export interface RunBufferedCommandOptions {
+  maxBuffer: number;
+  timeout: number;
+  windowsHide?: boolean;
+}
+
+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 runBufferedCommand(
+  command: string,
+  args: readonly string[],
+  options: RunBufferedCommandOptions,
+): Promise<BufferedCommandResult> {
+  return new Promise((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command, [...args], {
+        windowsHide: options.windowsHide,
+      });
+    } catch (error) {
+      resolve({
+        status: null,
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.alloc(0),
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+      return;
+    }
+
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    let processError: Error | undefined;
+
+    const finish = (result: BufferedCommandResult): void => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const failAndKill = (error: Error): void => {
+      processError = error;
+      child.kill();
+    };
+
+    const appendChunk = (chunks: Buffer[], chunk: unknown, currentBytes: number): number => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+      const nextBytes = currentBytes + buffer.length;
+      if (nextBytes > options.maxBuffer && !processError) {
+        failAndKill(new Error(`Command output exceeded maxBuffer (${options.maxBuffer} bytes).`));
+        return nextBytes;
+      }
+
+      chunks.push(buffer);
+      return nextBytes;
+    };
+
+    const timeout = setTimeout(() => {
+      failAndKill(new Error(`Command timed out after ${options.timeout}ms.`));
+    }, options.timeout);
+    timeout.unref?.();
+
+    child.stdout?.on("data", (chunk: unknown) => {
+      stdoutBytes = appendChunk(stdoutChunks, chunk, stdoutBytes);
+    });
+
+    child.stderr?.on("data", (chunk: unknown) => {
+      stderrBytes = appendChunk(stderrChunks, chunk, stderrBytes);
+    });
+
+    child.on("error", (error: Error) => {
+      processError = error;
+      finish({
+        status: null,
+        stdout: Buffer.concat(stdoutChunks),
+        stderr: Buffer.concat(stderrChunks),
+        error: processError,
+      });
+    });
+
+    child.on("close", (status: number | null) => {
+      finish({
+        status,
+        stdout: Buffer.concat(stdoutChunks),
+        stderr: Buffer.concat(stderrChunks),
+        error: processError,
+      });
+    });
+  });
+}
+
+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}`,
+  };
+}
+
+export async function runPowerShellCommandAsync(
+  script: string,
+  options: RunPowerShellCommandOptions,
+): Promise<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 = await runBufferedCommand("powershell.exe", commandArgs, {
+    timeout: options.timeout,
+    maxBuffer: options.maxBuffer,
+    windowsHide: true,
+  });
+  const stdout = result.stdout.toString("utf8");
+  const stderr = result.stderr.toString("utf8");
+
+  if (result.error) {
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
+      reason: getErrorMessage(result.error),
+    };
+  }
+
+  return {
+    ok: result.status === 0,
+    stdout,
+    stderr,
+    missingCommand: false,
+    reason: result.status === 0 ? undefined : `PowerShell exited with code ${result.status}`,
+  };
+}

package/src/terminal-image-width.ts

@@ -1,4 +1,4 @@
-import { SettingsManager, getAgentDir } from "@mariozechner/pi-coding-agent";
+import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { resolve } from "node:path";
 
 import { isRecord } from "./config.js";

package/src/types.ts

@@ -1,20 +1,20 @@
-import type { ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
-
-export type PasteContext = ExtensionContext | ExtensionCommandContext;
-
-export interface ClipboardImage {
-  bytes: Uint8Array;
-  mimeType: string;
-}
-
-export interface ClipboardModule {
-  hasImage: () => boolean;
-  getImageBinary: () => Promise<Array<number> | Uint8Array>;
-}
-
-export type PasteImageHandler = (ctx: PasteContext) => Promise<void>;
-
-export interface PasteImageCommandHandlers {
-  fromClipboard: PasteImageHandler;
-  fromRecent: PasteImageHandler;
-}
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type PasteContext = ExtensionContext | ExtensionCommandContext;
+
+export interface ClipboardImage {
+  bytes: Uint8Array;
+  mimeType: string;
+}
+
+export interface ClipboardModule {
+  hasImage: () => boolean;
+  getImageBinary: () => Promise<Array<number> | Uint8Array>;
+}
+
+export type PasteImageHandler = (ctx: PasteContext) => Promise<void>;
+
+export interface PasteImageCommandHandlers {
+  fromClipboard: PasteImageHandler;
+  fromRecent: PasteImageHandler;
+}