@pi-unipi/unipi 2.1.2 → 2.2.0

package/packages/core/tui-width.ts

@@ -0,0 +1,127 @@
+/**
+ * @pi-unipi/core — TUI width helpers
+ *
+ * pi-tui's differential renderer throws when a rendered line is wider than the
+ * terminal (see `TUI.render` in @earendil-works/pi-tui — it writes
+ * `~/.pi/agent/pi-crash.log`, stops the TUI and rethrows). That makes any
+ * "minimum width" floor a crash waiting to happen on a narrow terminal:
+ *
+ *     const innerWidth = Math.max(40, width - 2);   // ← 42-col lines at width=20
+ *
+ * The invariant every component must hold is:
+ *
+ *     for every returned line:  visibleWidth(line) <= width
+ *
+ * These helpers make that invariant easy to satisfy. They are pure arithmetic
+ * so this module stays free of a pi-tui dependency.
+ */
+
+/**
+ * Terminals narrower than this cannot usefully show a bordered box: two
+ * columns go to the border, leaving too little for content. Below the
+ * threshold, callers should render borderless (see {@link shouldRenderBorder}).
+ */
+export const MIN_BORDERED_WIDTH = 12;
+
+/** Smallest width any layout is asked to cope with. */
+export const MIN_RENDER_WIDTH = 1;
+
+/**
+ * Normalize an incoming render width. Guards against `0`, negative, `NaN`
+ * and fractional widths, all of which have been observed during terminal
+ * resize races.
+ */
+export function normalizeWidth(width: number): number {
+  if (!Number.isFinite(width)) return MIN_RENDER_WIDTH;
+  return Math.max(MIN_RENDER_WIDTH, Math.floor(width));
+}
+
+/**
+ * Whether a bordered box fits at this width. When false, render the content
+ * without `│` side borders so the full width is usable.
+ */
+export function shouldRenderBorder(width: number): boolean {
+  return normalizeWidth(width) >= MIN_BORDERED_WIDTH;
+}
+
+/**
+ * Content width inside a bordered box, i.e. the terminal width minus the two
+ * border columns, so that `│ + content + │` is `<= width`.
+ *
+ * Use this for components that always draw a border. Components that can drop
+ * the border on narrow terminals should branch on {@link shouldRenderBorder}
+ * and use {@link adaptiveInnerWidth} instead.
+ */
+export function boxInnerWidth(width: number): number {
+  return Math.max(1, normalizeWidth(width) - 2);
+}
+
+/**
+ * Content width for components that drop their border on narrow terminals:
+ * the box inner width when a border fits, otherwise the full width.
+ *
+ * Pair with {@link shouldRenderBorder} to decide whether to emit the border
+ * characters. Together they guarantee every emitted line is `<= width` at any
+ * width down to 1.
+ */
+export function adaptiveInnerWidth(width: number): number {
+  const w = normalizeWidth(width);
+  return shouldRenderBorder(w) ? boxInnerWidth(w) : w;
+}
+
+/**
+ * Width remaining after reserving `reserved` columns for a prefix, indent or
+ * gutter. Never returns less than 1, so it is safe to pass to wrapping and
+ * truncation helpers (which throw or misbehave on non-positive widths).
+ */
+export function contentWidth(available: number, reserved: number): number {
+  return Math.max(1, normalizeWidth(available) - Math.max(0, Math.floor(reserved)));
+}
+
+/**
+ * Clamp a repeat count to a non-negative integer.
+ *
+ * `String.prototype.repeat` throws `RangeError: Invalid count value` for
+ * negative counts, which crashes the render pass.
+ */
+export function safeRepeatCount(count: number): number {
+  if (!Number.isFinite(count)) return 0;
+  return Math.max(0, Math.floor(count));
+}
+
+/** `" ".repeat(n)` that cannot throw. */
+export function safeRepeat(char: string, count: number): string {
+  return char.repeat(safeRepeatCount(count));
+}
+
+/**
+ * Width-keyed render cache.
+ *
+ * Components that cache their rendered lines must invalidate on width change.
+ * pi-tui's `requestRender()` does *not* call `invalidate()`, so a component
+ * that caches `string[]` without keying on width will return stale, over-wide
+ * lines after the terminal is made narrower — and the next differential frame
+ * throws.
+ */
+export class WidthKeyedCache {
+  private lines: string[] | null = null;
+  private width = -1;
+
+  /** Cached lines for this width, or `null` on miss. */
+  get(width: number): string[] | null {
+    return this.lines !== null && this.width === normalizeWidth(width) ? this.lines : null;
+  }
+
+  /** Store lines for this width. Returns the lines for convenient chaining. */
+  set(width: number, lines: string[]): string[] {
+    this.lines = lines;
+    this.width = normalizeWidth(width);
+    return lines;
+  }
+
+  /** Drop the cache — call from `invalidate()` and on any state change. */
+  clear(): void {
+    this.lines = null;
+    this.width = -1;
+  }
+}

package/packages/footer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "main": "src/index.ts",
@@ -26,13 +26,13 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --experimental-strip-types --test tests/**/*.test.ts"
+    "test": "npx tsx --test tests/**/*.test.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.1.2"
+    "@pi-unipi/core": "2.2.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/footer/src/tui/settings-tui.ts

@@ -15,6 +15,7 @@ import { loadFooterSettings, saveFooterSettings } from "../config.js";
 import { PRESET_NAMES } from "../presets.js";
 import { setIconStyle } from "../rendering/icons.js";
 import type { FooterGroup, FooterSettings, SeparatorStyle, IconStyle } from "../types.js";
+import { boxInnerWidth } from "@pi-unipi/core";
 
 // ─── Section types ─────────────────────────────────────────────────────
 
@@ -457,7 +458,7 @@ class FooterSettingsOverlay {
   // ─── Render ────────────────────────────────────────────────────────
 
   render(width: number): string[] {
-    const innerWidth = Math.max(22, width - 2);
+    const innerWidth = boxInnerWidth(width);
     const lines: string[] = [];
 
     // Header

package/packages/image/README.md

@@ -0,0 +1,82 @@
+# @pi-unipi/image
+
+Image generation and image recognition tools for the agent.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `image_generate` | Generate an image from a text prompt. Returned inline and saved to disk. |
+| `image_recognize` | Analyze an image with a vision model. Accepts a file path, `data:` URL, or base64. |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:image-settings` | Configure models, output directory and the recognition system prompt |
+
+## image_generate
+
+```
+image_generate(prompt: "A cutaway diagram of a submarine, technical illustration")
+image_generate(prompt: "...", model: "flux.2-pro")
+```
+
+Models come from pi-ai's image catalog — 34 models including FLUX.2,
+Gemini 3 Pro Image, GPT-5 Image, Recraft and Riverflow — all served through
+**OpenRouter**, so an OpenRouter key is required
+([get one](https://openrouter.ai/keys)).
+
+The `model` parameter is fuzzy-matched, so `flux`, `recraft` and
+`gemini-3-pro` all work. Omit it to use the model chosen in
+`/unipi:image-settings`.
+
+Images are returned inline **and** written to `~/.unipi/images` by default;
+the saved path is reported back to the agent. A failed write never discards a
+successfully generated image.
+
+## image_recognize
+
+```
+image_recognize(image: "./screenshot.png")
+image_recognize(image: "./error.png", prompt: "What does the stack trace say?")
+```
+
+Uses any chat model whose input modality includes `image`. A model that cannot
+accept images is rejected up front with a clear message rather than failing
+inside the provider.
+
+Input can be a local file path, a `data:` URL, or raw base64. The media type is
+detected from the file's magic numbers, so a `.jpg` that is really a PNG still
+works. Supported: PNG, JPEG, GIF, WebP. Remote URLs are not fetched.
+
+Prefer file paths — inlining base64 into the conversation is far more
+expensive in tokens.
+
+## Configuration
+
+`~/.unipi/config/image/config.json`:
+
+```json
+{
+  "generate": {
+    "enabled": true,
+    "model": "openrouter/google/gemini-3-pro-image",
+    "outputDir": "~/.unipi/images",
+    "saveToDisk": true
+  },
+  "recognize": {
+    "enabled": true,
+    "model": "",
+    "systemPrompt": "You are a precise image analyst…"
+  }
+}
+```
+
+- `recognize.model` empty means "use the session's current model".
+- The system prompt is fully customizable, and can be overridden per call.
+- Enabling or disabling a tool takes effect next session, since tools are
+  registered at startup.
+- Every read falls back to defaults, so a corrupt config never breaks the tools.
+
+Set `UNIPI_IMAGE_CONFIG_DIR` to relocate the config directory (used by tests).

package/packages/image/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/packages/image/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@pi-unipi/image",
+  "version": "2.2.0",
+  "description": "Image generation and image recognition tools for the Pi coding agent",
+  "type": "module",
+  "main": "src/index.ts",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/image"
+  },
+  "homepage": "https://github.com/Neuron-Mr-White/unipi#readme",
+  "bugs": {
+    "url": "https://github.com/Neuron-Mr-White/unipi/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "image",
+    "vision",
+    "image-generation"
+  ],
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "skills/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "2.2.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^0.80.0",
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@earendil-works/pi-tui": "^0.80.0",
+    "typebox": "^1.1.38"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  },
+  "scripts": {
+    "test": "npx tsx --test tests/**/*.test.ts"
+  },
+  "pi": {
+    "extensions": [],
+    "skills": [],
+    "prompts": [],
+    "themes": []
+  }
+}

package/packages/image/skills/image/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: image
+description: Generate images from text prompts and analyze images with vision models
+---
+
+# Image Tools
+
+Two agent tools: `image_generate` creates images from a text prompt, and
+`image_recognize` analyzes an existing image.
+
+## image_generate
+
+```
+image_generate(prompt: "A cutaway diagram of a submarine, technical illustration, muted blues")
+image_generate(prompt: "...", model: "flux.2-pro")
+```
+
+- `prompt` (required) — describe subject, style, composition and lighting.
+  Detail materially improves the result.
+- `model` (optional) — fuzzy-matched against the image catalog
+  (`flux`, `gemini-3-pro-image`, `recraft-v4`, …). Omit to use the model
+  configured in `/unipi:image-settings`.
+
+The image is returned inline and, when `saveToDisk` is on (the default),
+written to the output directory (default `~/.unipi/images`). The saved path is
+reported in the result.
+
+**Image generation costs money per call.** Never regenerate an image
+speculatively — only when the user asks for a change.
+
+Models are served through OpenRouter, so an OpenRouter key is required:
+https://openrouter.ai/keys
+
+## image_recognize
+
+```
+image_recognize(image: "./screenshot.png")
+image_recognize(image: "./error.png", prompt: "What does the stack trace say?")
+image_recognize(image: "...", model: "claude-sonnet", systemPrompt: "Reply only with the visible text.")
+```
+
+- `image` (required) — a local file path, a `data:` URL, or raw base64.
+  **Prefer a file path**: inlining base64 into the conversation is far more
+  expensive. Remote URLs are not fetched — download first.
+- `prompt` (optional) — the question to ask. Defaults to a general
+  description. A specific question gives a far more useful answer.
+- `model` (optional) — must accept image input. Omit to use the configured
+  model, falling back to the session's current model.
+- `systemPrompt` (optional) — override the configured system prompt for one
+  call.
+
+Supported types: PNG, JPEG, GIF, WebP. The type is detected from the file's
+magic numbers, so a misnamed extension still works.
+
+### When to use it
+
+- Reading a screenshot of an error, a stack trace, or failing UI
+- Understanding a design mockup or wireframe before implementing it
+- Extracting content from an architecture diagram or flowchart
+- Checking what a rendered page or chart actually looks like
+
+## Configuration
+
+`/unipi:image-settings` configures both tools:
+
+- Generation model (picker over the image catalog)
+- Recognition model (picker over vision-capable models only)
+- Enable/disable either tool
+- Output directory and whether to save to disk
+- The recognition system prompt
+
+Config lives at `~/.unipi/config/image/config.json`. Toggling a tool on or off
+takes effect on the next session, since tools are registered at startup.

package/packages/image/src/commands.ts

@@ -0,0 +1,17 @@
+/**
+ * @pi-unipi/image — Slash commands
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { IMAGE_COMMANDS, UNIPI_PREFIX } from "@pi-unipi/core";
+
+import { showSettingsDialog } from "./tui/settings-dialog.js";
+
+export function registerImageCommands(pi: ExtensionAPI): void {
+  pi.registerCommand(`${UNIPI_PREFIX}${IMAGE_COMMANDS.SETTINGS}`, {
+    description: "Configure image generation and recognition models",
+    handler: async (_args, ctx) => {
+      await showSettingsDialog(ctx);
+    },
+  });
+}

package/packages/image/src/generate.ts

@@ -0,0 +1,201 @@
+/**
+ * @pi-unipi/image — Image generation
+ *
+ * Wraps pi-ai's image API. `generateImages` never rejects — failures come back
+ * as `stopReason: "error"` — so every call site must inspect the result rather
+ * than relying on try/catch.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getImagesModels, type ImageGenModel, type ImagesModelsLike } from "./models.js";
+
+export interface GeneratedImage {
+  /** Base64 image data. */
+  data: string;
+  mimeType: string;
+  /** Absolute path, when saved to disk. */
+  path?: string;
+}
+
+export interface GenerateResult {
+  images: GeneratedImage[];
+  /** Any accompanying commentary from the model. */
+  text: string;
+  model: string;
+  provider: string;
+}
+
+/** Structural view of pi-ai's AssistantImages. */
+interface AssistantImagesLike {
+  output?: Array<{ type?: string; text?: string; data?: string; mimeType?: string }>;
+  stopReason?: string;
+  errorMessage?: string;
+  usage?: unknown;
+}
+
+/** Injectable generation function, for tests. */
+export type GenerateImagesFn = (
+  model: unknown,
+  context: { input: Array<{ type: string; text?: string }> },
+  options: { apiKey?: string; signal?: AbortSignal },
+) => Promise<AssistantImagesLike>;
+
+/** Extension for a media type, for naming saved files. */
+function extensionFor(mimeType: string): string {
+  switch (mimeType) {
+    case "image/png":
+      return ".png";
+    case "image/jpeg":
+      return ".jpg";
+    case "image/webp":
+      return ".webp";
+    case "image/gif":
+      return ".gif";
+    case "image/svg+xml":
+      return ".svg";
+    default:
+      return ".img";
+  }
+}
+
+/** Filesystem-safe slug from a prompt, for a recognizable filename. */
+export function slugify(prompt: string, maxLength = 40): string {
+  const slug = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, maxLength)
+    .replace(/-+$/g, "");
+  return slug || "image";
+}
+
+/** Build a collision-free filename. */
+export function buildFileName(
+  prompt: string,
+  mimeType: string,
+  index: number,
+  now: Date = new Date(),
+): string {
+  const stamp = now.toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+  const suffix = index > 0 ? `-${index + 1}` : "";
+  return `${stamp}-${slugify(prompt)}${suffix}${extensionFor(mimeType)}`;
+}
+
+/**
+ * Write an image to disk.
+ * @returns the absolute path, or undefined if the write failed (never throws —
+ * a failed save must not discard a successfully generated image).
+ */
+export function saveImage(
+  outputDir: string,
+  fileName: string,
+  base64: string,
+): string | undefined {
+  try {
+    fs.mkdirSync(outputDir, { recursive: true });
+    const target = path.join(outputDir, fileName);
+    fs.writeFileSync(target, Buffer.from(base64, "base64"));
+    return target;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface GenerateOptions {
+  prompt: string;
+  model: ImageGenModel;
+  /** Fallback key, used only when pi-ai's own auth resolution comes up empty. */
+  apiKey?: string;
+  signal?: AbortSignal;
+  /** Absolute directory for saved images; omit to skip saving. */
+  outputDir?: string;
+  now?: Date;
+  /** Injected images collection, for tests. */
+  images?: ImagesModelsLike;
+}
+
+/**
+ * Generate images and optionally save them.
+ * @throws {Error} with an actionable message when generation fails.
+ */
+export async function generateImage(options: GenerateOptions): Promise<GenerateResult> {
+  const { prompt, model, signal, outputDir, now } = options;
+
+  if (!prompt.trim()) {
+    throw new Error("A non-empty prompt is required.");
+  }
+
+  const imagesApi = options.images ?? (await getImagesModels());
+  if (!imagesApi) {
+    throw new Error(
+      "Image generation is unavailable — this version of pi-ai does not expose an image API.",
+    );
+  }
+
+  // Prefer pi-ai's own credential store, then the caller-supplied fallback so
+  // a bare OPENROUTER_API_KEY still works.
+  let apiKey: string | undefined;
+  try {
+    apiKey = (await imagesApi.getAuth(model))?.apiKey;
+  } catch {
+    // Reported as a missing key below.
+  }
+  apiKey ||= options.apiKey;
+
+  if (!apiKey) {
+    throw new Error(
+      `No API key for provider "${model.provider}".\n` +
+        `→ Add one with /login, or set the provider's API key environment variable.\n` +
+        `→ Image models are served through OpenRouter: https://openrouter.ai/keys`,
+    );
+  }
+
+  const result = (await imagesApi.generateImages(
+    model,
+    { input: [{ type: "text", text: prompt }] },
+    { apiKey, ...(signal ? { signal } : {}) },
+  )) as AssistantImagesLike;
+
+  // pi-ai reports failures in-band rather than rejecting.
+  if (result.stopReason === "error") {
+    throw new Error(result.errorMessage || "Image generation failed.");
+  }
+  if (result.stopReason === "aborted") {
+    throw new Error("Image generation was cancelled.");
+  }
+
+  const images: GeneratedImage[] = [];
+  const textParts: string[] = [];
+
+  for (const part of result.output ?? []) {
+    if (part?.type === "image" && typeof part.data === "string" && part.data.length > 0) {
+      images.push({ data: part.data, mimeType: part.mimeType || "image/png" });
+    } else if (part?.type === "text" && typeof part.text === "string" && part.text.trim()) {
+      textParts.push(part.text.trim());
+    }
+  }
+
+  if (images.length === 0) {
+    throw new Error(
+      textParts.length > 0
+        ? `The model returned no image. It said: ${textParts.join(" ")}`
+        : "The model returned no image.",
+    );
+  }
+
+  if (outputDir) {
+    images.forEach((image, index) => {
+      const fileName = buildFileName(prompt, image.mimeType, index, now);
+      image.path = saveImage(outputDir, fileName, image.data);
+    });
+  }
+
+  return {
+    images,
+    text: textParts.join("\n"),
+    model: model.id,
+    provider: model.provider,
+  };
+}