@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/utility/src/image/models.ts

@@ -0,0 +1,221 @@
+/**
+ * @pi-unipi/utility — image model catalog, routing and keys
+ *
+ * Catalog (merged into the shared model cache with real modalities):
+ *   - OpenRouter's image models (public /models?output_modalities=image),
+ *     refreshed at most daily into ~/.unipi/config/image-models-cache.json
+ *   - a short list of fal models (listed when a fal key is available)
+ *   - pi's chat models already in the cache (vision = input includes image)
+ *
+ * Routing a "provider/model-id" reference:
+ *   openrouter/… → OpenRouter chat+modalities   key: settings → pi login → OPENROUTER_API_KEY
+ *   fal/…        → fal.run                       key: settings → FAL_KEY / FAL_API_KEY
+ *   <other>/…    → that pi provider's baseUrl, OpenAI images shape, pi's key for it
+ *   custom endpoint set in settings → that endpoint, model id as typed, its key
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readModelCache, type CachedModel, type Modality } from "@pi-unipi/core";
+import type { EndpointSettings, ImageApi, ImageConfig } from "./settings.js";
+
+export interface ModelRegistryLike {
+  find(provider: string, id: string): unknown;
+  getAll(): unknown[];
+  getAvailable?(): unknown[];
+  getApiKeyForProvider?(provider: string): Promise<string | undefined>;
+}
+
+export function splitRef(ref: string): { provider: string; id: string } | null {
+  const t = ref.trim();
+  const slash = t.indexOf("/");
+  return slash > 0 && slash < t.length - 1 ? { provider: t.slice(0, slash), id: t.slice(slash + 1) } : null;
+}
+
+// ─── catalog ──────────────────────────────────────────────────────────────
+
+export const FAL_MODELS: CachedModel[] = [
+  { provider: "fal", id: "fal-ai/flux-2/klein/4b", name: "FLUX.2 [klein] 4B", input: ["text"], output: ["image"], kind: "images" },
+  { provider: "fal", id: "fal-ai/flux-2/klein/4b/edit", name: "FLUX.2 [klein] 4B edit", input: ["text", "image"], output: ["image"], kind: "images" },
+  { provider: "fal", id: "fal-ai/flux-2", name: "FLUX.2 [dev]", input: ["text"], output: ["image"], kind: "images" },
+  { provider: "fal", id: "fal-ai/flux-2/edit", name: "FLUX.2 [dev] edit", input: ["text", "image"], output: ["image"], kind: "images" },
+  { provider: "fal", id: "fal-ai/nano-banana-pro", name: "Nano Banana Pro", input: ["text"], output: ["image"], kind: "images" },
+  { provider: "fal", id: "fal-ai/nano-banana-pro/edit", name: "Nano Banana Pro edit", input: ["text", "image"], output: ["image"], kind: "images" },
+];
+
+const IMAGE_CACHE_TTL_MS = 24 * 3600_000;
+
+function imageCachePath(): string {
+  return path.join(process.env.HOME ?? process.env.USERPROFILE ?? "~", ".unipi", "config", "image-models-cache.json");
+}
+
+export function readImageModelCache(): { updatedAt: number; models: CachedModel[] } {
+  try {
+    const raw = JSON.parse(fs.readFileSync(imageCachePath(), "utf-8")) as { updatedAt?: number; models?: CachedModel[] };
+    return { updatedAt: raw.updatedAt ?? 0, models: Array.isArray(raw.models) ? raw.models : [] };
+  } catch {
+    return { updatedAt: 0, models: [] };
+  }
+}
+
+const modalities = (list: unknown): Modality[] =>
+  Array.isArray(list) ? (list.filter((m) => m === "text" || m === "image") as Modality[]) : [];
+
+/** OpenRouter /models (image output) → cache entries. */
+export function parseOpenRouterImageModels(json: unknown): CachedModel[] {
+  const data = (json as { data?: unknown[] })?.data;
+  if (!Array.isArray(data)) return [];
+  const out: CachedModel[] = [];
+  for (const raw of data) {
+    const m = raw as { id?: unknown; name?: unknown; architecture?: { input_modalities?: unknown; output_modalities?: unknown } };
+    if (typeof m.id !== "string" || m.id.startsWith("openrouter/")) continue;
+    const output = modalities(m.architecture?.output_modalities);
+    if (!output.includes("image")) continue;
+    const input = modalities(m.architecture?.input_modalities);
+    out.push({ provider: "openrouter", id: m.id, ...(typeof m.name === "string" ? { name: m.name } : {}), input: input.length ? input : ["text"], output, kind: "images" });
+  }
+  return out;
+}
+
+/** Refresh the OpenRouter image list when stale; never throws. */
+export async function refreshImageModelCache(fetchImpl: typeof fetch = fetch, now = Date.now()): Promise<boolean> {
+  const current = readImageModelCache();
+  if (current.models.length > 0 && now - current.updatedAt < IMAGE_CACHE_TTL_MS) return false;
+  try {
+    const res = await fetchImpl("https://openrouter.ai/api/v1/models?output_modalities=image", { signal: AbortSignal.timeout(15_000) });
+    if (!res.ok) return false;
+    const models = parseOpenRouterImageModels(await res.json());
+    if (models.length === 0) return false;
+    fs.mkdirSync(path.dirname(imageCachePath()), { recursive: true });
+    fs.writeFileSync(imageCachePath(), JSON.stringify({ updatedAt: now, models }, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function falKey(config: ImageConfig, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return config.keys.fal || env.FAL_KEY || env.FAL_API_KEY || undefined;
+}
+
+/** Image entries to merge into the shared model cache (first wins on dupes). */
+export function imageCatalogEntries(config: ImageConfig, env: NodeJS.ProcessEnv = process.env): CachedModel[] {
+  return [...readImageModelCache().models, ...(falKey(config, env) ? FAL_MODELS : [])];
+}
+
+/** Modalities of a reference, from the shared cache (undefined = unknown). */
+export function lookupModel(ref: string): CachedModel | undefined {
+  return readModelCache().find((m) => `${m.provider}/${m.id}` === ref);
+}
+
+// ─── routing ──────────────────────────────────────────────────────────────
+
+export interface Route {
+  api: ImageApi;
+  baseUrl: string;
+  apiKey: string;
+  modelId: string;
+  label: string;
+  output?: string[];
+}
+
+function providerBaseUrl(registry: ModelRegistryLike | undefined, provider: string): string | undefined {
+  try {
+    const models = (registry?.getAvailable?.() ?? registry?.getAll() ?? []) as Array<{ provider?: string; baseUrl?: string }>;
+    return models.find((m) => m.provider === provider && m.baseUrl)?.baseUrl;
+  } catch {
+    return undefined;
+  }
+}
+
+async function registryKey(registry: ModelRegistryLike | undefined, provider: string, env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  try {
+    const key = await registry?.getApiKeyForProvider?.(provider);
+    if (key) return key;
+  } catch {
+    // fall through
+  }
+  return env[`${provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`] || undefined;
+}
+
+/**
+ * Where and how to send a generate/edit request. Throws a message that says
+ * exactly what to set when a key or endpoint is missing.
+ */
+export async function resolveRoute(
+  ref: string,
+  endpoint: EndpointSettings,
+  config: ImageConfig,
+  registry: ModelRegistryLike | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<Route> {
+  const model = ref.trim();
+  if (!model) throw new Error("No image model configured — pick one in /unipi:settings → Image.");
+  if (endpoint.baseUrl.trim()) {
+    if (!endpoint.apiKey) throw new Error(`The custom image endpoint ${endpoint.baseUrl} has no key — set it in /unipi:settings → Image.`);
+    return { api: endpoint.api, baseUrl: endpoint.baseUrl.trim(), apiKey: endpoint.apiKey, modelId: model, label: `${model} @ ${endpoint.baseUrl.trim()}` };
+  }
+  const parts = splitRef(model);
+  if (!parts) throw new Error(`"${model}" is not a provider/model-id reference.`);
+  const output = lookupModel(model)?.output;
+  if (parts.provider === "openrouter") {
+    const apiKey = config.keys.openrouter || (await registryKey(registry, "openrouter", env));
+    if (!apiKey) throw new Error("No OpenRouter key. Set Keys → OpenRouter key in /unipi:settings → Image, log in with /login, or export OPENROUTER_API_KEY.");
+    return { api: "openrouter", baseUrl: "", apiKey, modelId: parts.id, label: model, ...(output ? { output } : {}) };
+  }
+  if (parts.provider === "fal") {
+    const apiKey = falKey(config, env);
+    if (!apiKey) throw new Error("No fal key. Set Keys → fal key in /unipi:settings → Image, or export FAL_KEY.");
+    return { api: "fal", baseUrl: "", apiKey, modelId: parts.id, label: model };
+  }
+  const baseUrl = providerBaseUrl(registry, parts.provider);
+  if (!baseUrl) throw new Error(`Provider "${parts.provider}" is not configured in pi, so there is no endpoint for ${model}. Pick an openrouter/ or fal/ model, or set a custom endpoint.`);
+  const apiKey = await registryKey(registry, parts.provider, env);
+  if (!apiKey) throw new Error(`No key for provider "${parts.provider}". Log in with /login or set a custom endpoint key.`);
+  return { api: "openai-images", baseUrl, apiKey, modelId: parts.id, label: model };
+}
+
+// ─── vision (recognize) ───────────────────────────────────────────────────
+
+export interface VisionModel {
+  id: string;
+  provider: string;
+  name?: string;
+  input?: string[];
+  baseUrl?: string;
+  api?: string;
+}
+
+export function isVisionModel(model: unknown): model is VisionModel {
+  const m = model as Partial<VisionModel> | null;
+  return !!m && typeof m.id === "string" && typeof m.provider === "string" && Array.isArray(m.input) && m.input.includes("image");
+}
+
+/** Active tools with image_recognize hidden for vision models, restored for text-only ones. */
+export function applyRecognizeGating(active: string[], model: unknown, tool: string): string[] {
+  const vision = isVisionModel(model);
+  const present = active.includes(tool);
+  if (vision !== present) return active;
+  return vision ? active.filter((n) => n !== tool) : [...active, tool];
+}
+
+/** A registry vision model by reference (exact, then id, then substring). */
+export function resolveVisionModel(ref: string, registry: ModelRegistryLike): VisionModel | string {
+  let all: unknown[] = [];
+  try {
+    all = registry.getAvailable?.() ?? registry.getAll();
+  } catch {
+    all = [];
+  }
+  const vision = all.filter(isVisionModel);
+  const q = ref.trim().toLowerCase();
+  const full = (m: VisionModel) => `${m.provider}/${m.id}`.toLowerCase();
+  const hit = vision.find((m) => full(m) === q) ?? vision.find((m) => m.id.toLowerCase() === q) ?? vision.find((m) => full(m).includes(q));
+  if (hit) return hit;
+  const known = all.find((m) => {
+    const c = m as Partial<VisionModel>;
+    return typeof c.id === "string" && typeof c.provider === "string" && (`${c.provider}/${c.id}`.toLowerCase() === q || c.id.toLowerCase() === q);
+  });
+  if (known) return `Model "${ref}" does not accept image input. Vision models: ${vision.slice(0, 5).map((m) => `${m.provider}/${m.id}`).join(", ")}`;
+  return `Unknown vision model "${ref}". Vision models: ${vision.slice(0, 5).map((m) => `${m.provider}/${m.id}`).join(", ") || "none configured"}`;
+}

package/packages/{image/src → utility/src/image}/recognize.ts

@@ -1,12 +1,12 @@
 /**
- * @pi-unipi/image — Image recognition
+ * @pi-unipi/utility — image: Image recognition
  *
  * Sends an image plus a question to a vision-capable chat model. Providers
  * differ in how image parts are encoded, so the request is built per API
  * family (mirroring `packages/notify/summarize.ts`).
  */
 
-import type { LoadedImage } from "./image-source.js";
+import type { LoadedImage } from "./source.js";
 
 /** How long to wait for a vision response. Images are slow. */
 const DEFAULT_TIMEOUT_MS = 120_000;

package/packages/utility/src/image/settings.ts

@@ -0,0 +1,178 @@
+/**
+ * @pi-unipi/utility — image settings (namespace `image`, unchanged from the
+ * former @pi-unipi/image package, so existing configs keep working)
+ *
+ *   generate  — text → image      (models whose output includes image)
+ *   edit      — image+text → image (models that take an image and output one)
+ *   recognize — image → text       (vision chat models; hidden while the
+ *                                   session model can see images itself)
+ *   keys      — OpenRouter / fal keys (empty = pi's login or the environment)
+ *   *.baseUrl — optional custom endpoint: when set, the model id is sent to
+ *               that endpoint as typed, with its own key.
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import { getSettings, registerSettings } from "@pi-unipi/core";
+
+export const DEFAULT_RECOGNIZE_SYSTEM_PROMPT =
+  "You are a precise image analyst assisting a software engineer. " +
+  "Describe what is actually visible — never speculate about what is not shown. " +
+  "For screenshots, transcribe visible text, UI structure, and any errors verbatim. " +
+  "For diagrams, describe the components and their relationships. " +
+  "For photographs, describe the subject, setting, and notable detail. " +
+  "Be specific and concise; lead with the single most important observation.";
+
+/** Cheap, fast defaults (FLUX.2 klein 4B does both text→image and edits). */
+export const DEFAULT_GENERATE_MODEL = "openrouter/black-forest-labs/flux.2-klein-4b";
+export const DEFAULT_EDIT_MODEL = "openrouter/black-forest-labs/flux.2-klein-4b";
+
+export type ImageApi = "openai-images" | "openrouter" | "fal";
+
+export interface EndpointSettings {
+  /** Custom endpoint; "" = route by the model's provider. */
+  baseUrl: string;
+  apiKey: string;
+  api: ImageApi;
+}
+
+export interface GenerateSettings extends EndpointSettings {
+  enabled: boolean;
+  model: string;
+  outputDir: string;
+  saveToDisk: boolean;
+}
+
+export interface EditSettings extends EndpointSettings {
+  enabled: boolean;
+  model: string;
+}
+
+export interface RecognizeSettings {
+  enabled: boolean;
+  /** "" = the session model. */
+  model: string;
+  systemPrompt: string;
+  /** Custom OpenAI-compatible chat endpoint; "" = the model's provider. */
+  baseUrl: string;
+  apiKey: string;
+}
+
+export interface ImageConfig {
+  generate: GenerateSettings;
+  edit: EditSettings;
+  recognize: RecognizeSettings;
+  keys: { openrouter: string; fal: string };
+}
+
+const NO_ENDPOINT: EndpointSettings = { baseUrl: "", apiKey: "", api: "openai-images" };
+
+export const DEFAULT_CONFIG: ImageConfig = {
+  generate: { enabled: true, model: DEFAULT_GENERATE_MODEL, outputDir: "~/.unipi/images", saveToDisk: true, ...NO_ENDPOINT },
+  edit: { enabled: true, model: DEFAULT_EDIT_MODEL, ...NO_ENDPOINT },
+  recognize: { enabled: true, model: "", systemPrompt: DEFAULT_RECOGNIZE_SYSTEM_PROMPT, baseUrl: "", apiKey: "" },
+  keys: { openrouter: "", fal: "" },
+};
+
+const API_OPTIONS = [
+  { value: "openai-images", label: "OpenAI images (/images/generations)" },
+  { value: "openrouter", label: "OpenRouter-style chat (modalities)" },
+  { value: "fal", label: "fal (fal.run/<model>)" },
+];
+
+registerSettings({
+  namespace: "image",
+  label: "Image",
+  defaults: DEFAULT_CONFIG as unknown as Record<string, unknown>,
+  schema: [
+    {
+      title: "Generate",
+      description: "Text → image (image_generate)",
+      fields: [
+        { key: "generate.enabled", type: "boolean", label: "Enabled", description: "Give the agent the image_generate tool" },
+        { key: "generate.model", type: "model", label: "Model", capability: "image-output", description: "Models whose output includes images" },
+        { key: "generate.outputDir", type: "string", label: "Save to folder", description: "~ is expanded" },
+        { key: "generate.saveToDisk", type: "boolean", label: "Save to disk" },
+        { key: "generate.baseUrl", type: "string", label: "Custom endpoint", emptyLabel: "none (use the model's provider)", description: "Send the model id as typed to this base URL instead" },
+        { key: "generate.apiKey", type: "secret", label: "Custom endpoint key", emptyLabel: "none" },
+        { key: "generate.api", type: "enum", label: "Custom endpoint API", options: API_OPTIONS },
+      ],
+    },
+    {
+      title: "Edit",
+      description: "Image + text → image (image_edit)",
+      fields: [
+        { key: "edit.enabled", type: "boolean", label: "Enabled", description: "Give the agent the image_edit tool" },
+        { key: "edit.model", type: "model", label: "Model", capability: "image-edit", description: "Models that take an image and output an image" },
+        { key: "edit.baseUrl", type: "string", label: "Custom endpoint", emptyLabel: "none (use the model's provider)" },
+        { key: "edit.apiKey", type: "secret", label: "Custom endpoint key", emptyLabel: "none" },
+        { key: "edit.api", type: "enum", label: "Custom endpoint API", options: API_OPTIONS },
+      ],
+    },
+    {
+      title: "Recognize",
+      description: "Image → text (image_recognize; hidden while the session model can see images)",
+      fields: [
+        { key: "recognize.enabled", type: "boolean", label: "Enabled", description: "Give text-only models the image_recognize tool" },
+        { key: "recognize.model", type: "model", label: "Model", capability: "image-input", emptyLabel: "inherit (session model)", emptyOption: "inherit (session model)" },
+        { key: "recognize.systemPrompt", type: "string", label: "System prompt", emptyLabel: "built-in analyst prompt" },
+        { key: "recognize.baseUrl", type: "string", label: "Custom endpoint", emptyLabel: "none (use the model's provider)", description: "OpenAI-compatible chat endpoint" },
+        { key: "recognize.apiKey", type: "secret", label: "Custom endpoint key", emptyLabel: "none" },
+      ],
+    },
+    {
+      title: "Keys",
+      description: "Used when the model's provider is OpenRouter or fal",
+      advanced: true,
+      fields: [
+        { key: "keys.openrouter", type: "secret", label: "OpenRouter key", emptyLabel: "pi login or OPENROUTER_API_KEY" },
+        { key: "keys.fal", type: "secret", label: "fal key", emptyLabel: "FAL_KEY / FAL_API_KEY" },
+      ],
+    },
+  ],
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Merge a loaded section over its defaults, ignoring wrong-typed fields. */
+function mergeSection<T extends object>(defaults: T, loaded: unknown): T {
+  const merged: T = { ...defaults };
+  if (!isRecord(loaded)) return merged;
+  for (const key of Object.keys(defaults) as Array<keyof T & string>) {
+    const value = loaded[key];
+    if (value !== undefined && value !== null && typeof value === typeof defaults[key]) merged[key] = value as T[keyof T & string];
+  }
+  return merged;
+}
+
+export function loadConfig(cwd: string = process.cwd()): ImageConfig {
+  try {
+    const parsed = getSettings("image", cwd);
+    if (!isRecord(parsed)) return structuredClone(DEFAULT_CONFIG);
+    const config: ImageConfig = {
+      generate: mergeSection(DEFAULT_CONFIG.generate, parsed.generate),
+      edit: mergeSection(DEFAULT_CONFIG.edit, parsed.edit),
+      recognize: mergeSection(DEFAULT_CONFIG.recognize, parsed.recognize),
+      keys: mergeSection(DEFAULT_CONFIG.keys, parsed.keys),
+    };
+    for (const section of [config.generate, config.edit]) {
+      if (!["openai-images", "openrouter", "fal"].includes(section.api)) section.api = "openai-images";
+    }
+    return config;
+  } catch {
+    return structuredClone(DEFAULT_CONFIG);
+  }
+}
+
+export function expandHome(target: string): string {
+  if (target === "~") return os.homedir();
+  if (target.startsWith("~/") || target.startsWith("~\\")) return path.join(os.homedir(), target.slice(2));
+  return target;
+}
+
+export function getOutputDir(config: ImageConfig = loadConfig()): string {
+  const dir = config.generate.outputDir?.trim();
+  return expandHome(dir && dir.length > 0 ? dir : DEFAULT_CONFIG.generate.outputDir);
+}

package/packages/{image/src/image-source.ts → utility/src/image/source.ts}

@@ -1,5 +1,5 @@
 /**
- * @pi-unipi/image — Image input handling
+ * @pi-unipi/utility — image: Image input handling
  *
  * Accepts a local file path, a data: URL, or a raw base64 string and
  * normalizes it to the `{ data, mimeType }` shape pi-ai expects.

package/packages/utility/src/image/tools.ts

@@ -0,0 +1,168 @@
+/**
+ * @pi-unipi/utility — image tools: image_generate, image_edit, image_recognize
+ *
+ * Registered once at load from the enabled flags (static schemas keep the
+ * provider prefix cache intact). Failures THROW so pi records them as failed
+ * tool results — returning `isError` is ignored by pi.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { IMAGE_TOOLS } from "@pi-unipi/core";
+import { loadImage } from "./source.js";
+import { recognizeImage } from "./recognize.js";
+import { generate, type ImagePayload } from "./transports.js";
+import { resolveRoute, resolveVisionModel, type ModelRegistryLike } from "./models.js";
+import { getOutputDir, loadConfig, type EndpointSettings } from "./settings.js";
+
+const EXT: Record<string, string> = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp", "image/gif": ".gif" };
+
+export function slugify(prompt: string, max = 40): string {
+  return prompt.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, max).replace(/-+$/g, "") || "image";
+}
+
+/** Save images; a failed write never loses the generated image. */
+export function saveImages(dir: string, prompt: string, images: ImagePayload[], now = new Date()): string[] {
+  const stamp = now.toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+  const saved: string[] = [];
+  images.forEach((img, i) => {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      const file = path.join(dir, `${stamp}-${slugify(prompt)}${i ? `-${i + 1}` : ""}${EXT[img.mimeType] ?? ".png"}`);
+      fs.writeFileSync(file, Buffer.from(img.data, "base64"));
+      saved.push(file);
+    } catch {
+      // keep going — the image is still returned inline
+    }
+  });
+  return saved;
+}
+
+function registry(ctx: ExtensionContext): ModelRegistryLike | undefined {
+  return (ctx as unknown as { modelRegistry?: ModelRegistryLike }).modelRegistry;
+}
+
+async function run(
+  ctx: ExtensionContext,
+  kind: "generate" | "edit",
+  prompt: string,
+  modelOverride: string | undefined,
+  endpoint: EndpointSettings & { model: string },
+  source: ImagePayload[] | undefined,
+  signal: AbortSignal | undefined,
+) {
+  const config = loadConfig(ctx.cwd);
+  const route = await resolveRoute(modelOverride?.trim() || endpoint.model, modelOverride?.trim() ? { ...endpoint, baseUrl: "" } : endpoint, config, registry(ctx));
+  const out = await generate({ ...route, prompt, ...(source ? { images: source } : {}), ...(signal ? { signal } : {}) });
+  const saved = config.generate.saveToDisk ? saveImages(getOutputDir(config), prompt, out.images) : [];
+  const verb = kind === "edit" ? "Edited" : "Generated";
+  const summary = [
+    `${verb} ${out.images.length} image${out.images.length === 1 ? "" : "s"} with ${route.label}.`,
+    saved.length ? `Saved to:\n${saved.map((p) => `  ${p}`).join("\n")}` : config.generate.saveToDisk ? "Could not save to disk; the image is inline only." : "",
+    out.text,
+  ].filter(Boolean).join("\n");
+  return {
+    content: [{ type: "text" as const, text: summary }, ...out.images.map((i) => ({ type: "image" as const, data: i.data, mimeType: i.mimeType }))],
+    details: { model: route.label, count: out.images.length, paths: saved },
+  };
+}
+
+export function registerImageTools(pi: ExtensionAPI): void {
+  const config = loadConfig();
+
+  if (config.generate.enabled) {
+    pi.registerTool({
+      name: IMAGE_TOOLS.GENERATE,
+      label: "Generate Image",
+      description: "Generate an image from a text prompt. Returned inline and saved to disk.",
+      promptSnippet: "Generate an image from a text prompt.",
+      promptGuidelines: [
+        "Write a detailed prompt — subject, style, composition and lighting all help.",
+        "Describe what you DO want; negation is unreliable in image models.",
+        "To change an existing image use image_edit instead.",
+        "Omit model to use the one configured in /unipi:settings. Images cost money; do not regenerate unasked.",
+      ],
+      parameters: Type.Object({
+        prompt: Type.String({ description: "Description of the image. Be specific." }),
+        model: Type.Optional(Type.String({ description: 'Override as "provider/model-id", e.g. "openrouter/black-forest-labs/flux.2-klein-4b" or "fal/fal-ai/flux-2/klein/4b".' })),
+      }),
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const c = loadConfig(ctx.cwd);
+        return run(ctx, "generate", params.prompt, params.model, c.generate, undefined, signal);
+      },
+    });
+  }
+
+  if (config.edit.enabled) {
+    pi.registerTool({
+      name: IMAGE_TOOLS.EDIT,
+      label: "Edit Image",
+      description: "Edit an existing image with a text instruction. Returned inline and saved to disk.",
+      promptSnippet: "Edit an existing image with a text instruction.",
+      promptGuidelines: [
+        "Pass the source image as a file path (preferred), data: URL or base64.",
+        "Say what to change and what to keep; unmentioned details may change.",
+      ],
+      parameters: Type.Object({
+        prompt: Type.String({ description: "What to change." }),
+        image: Type.String({ description: "Source image: local file path, data: URL, or base64." }),
+        model: Type.Optional(Type.String({ description: 'Override as "provider/model-id" (must accept an image and output one).' })),
+      }),
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const c = loadConfig(ctx.cwd);
+        const src = loadImage(params.image, ctx.cwd ?? process.cwd());
+        return run(ctx, "edit", params.prompt, params.model, c.edit, [{ data: src.data, mimeType: src.mimeType }], signal);
+      },
+    });
+  }
+
+  if (config.recognize.enabled) {
+    pi.registerTool({
+      name: IMAGE_TOOLS.RECOGNIZE,
+      label: "Recognize Image",
+      description: "Analyze an image and answer questions about it using a vision model.",
+      promptSnippet: "Analyze an image and answer questions about it.",
+      promptGuidelines: [
+        "Use image_recognize to read screenshots, diagrams, mockups and photos.",
+        "Pass a local file path when possible — cheaper than inlining base64.",
+        "Ask a specific question in `prompt` to focus the analysis.",
+      ],
+      parameters: Type.Object({
+        image: Type.String({ description: "Local file path, data: URL, or base64 (PNG, JPEG, GIF, WebP)." }),
+        prompt: Type.Optional(Type.String({ description: "What to ask about the image. Defaults to a general description." })),
+        model: Type.Optional(Type.String({ description: "Vision model override (must accept image input)." })),
+      }),
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const c = loadConfig(ctx.cwd).recognize;
+        const image = loadImage(params.image, ctx.cwd ?? process.cwd());
+        const prompt = params.prompt?.trim() || "Describe this image in detail.";
+        let target: { baseUrl: string; apiKey: string; api: string; modelId: string; label: string };
+        const requested = params.model?.trim() || c.model.trim();
+        if (c.baseUrl.trim() && !params.model?.trim()) {
+          if (!requested) throw new Error("Set a model id for the custom recognition endpoint in /unipi:settings → Image.");
+          target = { baseUrl: c.baseUrl.trim(), apiKey: c.apiKey, api: "openai-completions", modelId: requested, label: `${requested} @ ${c.baseUrl.trim()}` };
+        } else {
+          const reg = registry(ctx);
+          if (!reg) throw new Error("Model registry unavailable — image_recognize needs an active session.");
+          const session = (ctx as unknown as { model?: { provider?: string; id?: string } }).model;
+          const ref = requested || (session?.provider && session.id ? `${session.provider}/${session.id}` : "");
+          if (!ref) throw new Error("No vision model configured — choose one in /unipi:settings → Image.");
+          const model = resolveVisionModel(ref, reg);
+          if (typeof model === "string") throw new Error(model);
+          const full = reg.find(model.provider, model.id) as { baseUrl?: string; api?: string } | undefined;
+          if (!full?.baseUrl) throw new Error(`No endpoint known for ${model.provider}/${model.id}.`);
+          const apiKey = (await reg.getApiKeyForProvider?.(model.provider).catch(() => undefined)) ?? "";
+          if (!apiKey) throw new Error(`No key for provider "${model.provider}". Log in with /login.`);
+          target = { baseUrl: full.baseUrl, apiKey, api: full.api ?? "openai-completions", modelId: model.id, label: `${model.provider}/${model.id}` };
+        }
+        const result = await recognizeImage({ image, prompt, systemPrompt: c.systemPrompt, apiKey: target.apiKey, baseUrl: target.baseUrl, api: target.api, modelId: target.modelId, ...(signal ? { signal } : {}) });
+        return {
+          content: [{ type: "text" as const, text: `${result.text}\n\n— analyzed with ${target.label}${image.path ? ` (${image.path})` : ""}` }],
+          details: { model: target.label, mimeType: image.mimeType, ...(image.path ? { path: image.path } : {}) },
+        };
+      },
+    });
+  }
+}