@pi-unipi/image 2.2.0 → 2.2.2

package/README.md

@@ -22,10 +22,20 @@ 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)).
+Models come from two places, merged into one list:
+
+- pi-ai's built-in image catalog — 34 models including FLUX.2, Gemini 3 Pro
+  Image, GPT-5 Image, Recraft and Riverflow — served through **OpenRouter**
+  ([get a key](https://openrouter.ai/keys)).
+- **Any provider registered by another extension.** Third-party providers
+  publish no image metadata, so these are detected by name; a real registry
+  with 393 models contributed 12 generators (FLUX, Nano Banana, Ideogram,
+  Recraft, Seedream, Stable Diffusion) alongside the built-ins.
+
+Because that detection is heuristic, the picker has a **custom entry** — press
+`c` in `/unipi:image-settings` and type any `provider/model-id`. A
+well-formed reference is always accepted, even when the catalog has never
+heard of it, so no model is ever unreachable.
 
 The `model` parameter is fuzzy-matched, so `flux`, `recraft` and
 `gemini-3-pro` all work. Omit it to use the model chosen in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/image",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Image generation and image recognition tools for the Pi coding agent",
   "type": "module",
   "main": "src/index.ts",

package/skills/image/SKILL.md

@@ -63,8 +63,11 @@ magic numbers, so a misnamed extension still works.
 
 `/unipi:image-settings` configures both tools:
 
-- Generation model (picker over the image catalog)
+- Generation model (picker over the built-in catalog plus image models from
+  any provider registered by another extension)
 - Recognition model (picker over vision-capable models only)
+- Either picker accepts a **custom** `provider/model-id` — press `c` — for a
+  model the catalog does not list
 - Enable/disable either tool
 - Output directory and whether to save to disk
 - The recognition system prompt

package/src/models.ts

@@ -72,10 +72,20 @@ let imagesModelsAttempted = false;
 /**
  * Load pi-ai's built-in images collection.
  *
- * `getImageModels`/`generateImages` are not re-exported from the pi-ai package
- * root, but `providers/all` exports `builtinImagesModels()`, which is the
- * supported entry point and also resolves auth. A failure is not fatal: it
- * degrades to null and callers report that no models are available.
+ * ⚠️ Do NOT reach for `getImageModels`/`getImageProviders`/`generateImages`:
+ *
+ *   - They are NOT re-exported from the pi-ai package root. Importing
+ *     `@earendil-works/pi-ai` and calling `getImageModels("openrouter")`
+ *     returns an EMPTY ARRAY rather than throwing, so the mistake looks like
+ *     "no models are installed" and costs a long debugging session.
+ *   - The file that defines them, `dist/image-models.js`, is not a permitted
+ *     subpath in pi-ai's `exports` map, so importing it directly throws
+ *     ERR_PACKAGE_PATH_NOT_EXPORTED.
+ *
+ * The supported entry point is `@earendil-works/pi-ai/providers/all` →
+ * `builtinImagesModels()`, which returns the catalog AND resolves auth.
+ * A failure is not fatal: it degrades to null and callers report that no
+ * models are available.
  */
 export async function getImagesModels(): Promise<ImagesModelsLike | null> {
   if (cachedImagesModels || imagesModelsAttempted) return cachedImagesModels;
@@ -106,6 +116,111 @@ export async function listImageGenModels(): Promise<ImageGenModel[]> {
   }
 }
 
+/**
+ * Heuristic: does a chat-registry model look like an image generator?
+ *
+ * Third-party providers registered by other extensions (pi-omniroute-bridge,
+ * for example) surface text-to-image endpoints as ordinary chat models. They
+ * declare no `output` modality at all, so a strict `output.includes("image")`
+ * check finds nothing and the user sees only pi-ai's built-in OpenRouter
+ * catalog. We therefore accept an explicit image output when present, and
+ * otherwise fall back to well-known generator naming.
+ */
+const GENERATOR_NAME_HINTS = [
+  "text-to-image",
+  "flux",
+  "dall-e",
+  "dalle",
+  "imagen",
+  "recraft",
+  "seedream",
+  "riverflow",
+  "grok-imagine",
+  "stable-diffusion",
+  "sdxl",
+  "midjourney",
+  "ideogram",
+  "nano-banana",
+];
+
+export function looksLikeImageGenerator(model: {
+  id: string;
+  name?: string;
+  output?: string[];
+}): boolean {
+  // An explicit declaration always wins.
+  if (Array.isArray(model.output)) {
+    if (model.output.includes("image")) return true;
+    // Declared, but text-only — trust it and do not guess from the name.
+    if (model.output.length > 0) return false;
+  }
+
+  const haystack = `${model.id} ${model.name ?? ""}`.toLowerCase();
+  // Match "image" as a delimited segment ("gpt-5-image", "gemini-3-pro-image"),
+  // not the bare word anywhere — which would wrongly catch vision models such
+  // as "claude-image-understanding". \b handles the whitespace between id and
+  // name; a character class alone missed ids ending the id portion.
+  if (/(^|[/\-_\s])image\b/.test(haystack) && !haystack.includes("understand")) {
+    return true;
+  }
+  return GENERATOR_NAME_HINTS.some((hint) => haystack.includes(hint));
+}
+
+/**
+ * Image-generation models discovered from the chat registry — i.e. providers
+ * registered by other extensions, which pi-ai's built-in catalog knows nothing
+ * about.
+ */
+export function listRegistryImageGenModels(
+  registry: ChatModelRegistry,
+): ImageGenModel[] {
+  let models: unknown[];
+  try {
+    models = registry.getAvailable?.() ?? registry.getAll();
+  } catch {
+    return [];
+  }
+
+  const out: ImageGenModel[] = [];
+  for (const model of models) {
+    if (model === null || typeof model !== "object") continue;
+    const candidate = model as Partial<ImageGenModel>;
+    if (typeof candidate.id !== "string" || typeof candidate.provider !== "string") {
+      continue;
+    }
+    if (!looksLikeImageGenerator(candidate as ImageGenModel)) continue;
+    out.push({
+      id: candidate.id,
+      provider: candidate.provider,
+      name: candidate.name,
+      api: candidate.api ?? "",
+      ...(candidate.output ? { output: candidate.output } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * Every selectable generation model: pi-ai's built-in catalog plus anything
+ * contributed by registered providers, de-duplicated by "provider/id".
+ */
+export async function listAllImageGenModels(
+  registry?: ChatModelRegistry | null,
+): Promise<ImageGenModel[]> {
+  const builtin = await listImageGenModels();
+  const fromRegistry = registry ? listRegistryImageGenModels(registry) : [];
+
+  const seen = new Set(builtin.map((m) => formatModelRef(m).toLowerCase()));
+  const merged = [...builtin];
+  for (const model of fromRegistry) {
+    const key = formatModelRef(model).toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(model);
+  }
+  return merged;
+}
+
 /** Inject a stub images collection. Test-only. */
 export function __setImagesModelsForTests(models: ImagesModelsLike | null): void {
   cachedImagesModels = models;
@@ -129,12 +244,18 @@ export function resolveImageGenModel(
   input: string,
   models: ImageGenModel[],
 ): ImageGenModel | string {
-  const query = input.trim().toLowerCase();
+  const raw = input.trim();
+  const query = raw.toLowerCase();
   if (!query) return "No image model specified.";
   if (models.length === 0) {
+    // A fully-qualified reference still works: detection is heuristic, so the
+    // user must be able to name a model we failed to discover.
+    const explicit = asExplicitModelRef(raw);
+    if (explicit) return explicit;
     return (
       "No image generation models are available.\n" +
-      "→ Image generation requires an OpenRouter account: https://openrouter.ai/keys"
+      "→ Image generation requires an OpenRouter account: https://openrouter.ai/keys\n" +
+      "→ Or set an exact model with /unipi:image-settings (press c to enter one manually)."
     );
   }
 
@@ -170,6 +291,11 @@ export function resolveImageGenModel(
 
   if (best && bestScore > 0) return best;
 
+  // Nothing matched, but an explicit "provider/model-id" is taken at face
+  // value — the catalog is not authoritative for third-party providers.
+  const explicit = asExplicitModelRef(raw);
+  if (explicit) return explicit;
+
   const sample = models.slice(0, 10).map((m) => `  ${formatModelRef(m)}`).join("\n");
   return (
     `Unknown image model "${input}".\n` +
@@ -178,6 +304,22 @@ export function resolveImageGenModel(
   );
 }
 
+/**
+ * Treat a well-formed "provider/model-id" as a usable model even when it is
+ * absent from the catalog.
+ *
+ * Generator detection is heuristic and third-party providers publish no image
+ * metadata, so refusing an unknown-but-well-formed reference would make some
+ * models permanently unreachable. Requiring the provider segment keeps this
+ * from swallowing plain typos, which still get the "Unknown image model" list.
+ */
+function asExplicitModelRef(raw: string): ImageGenModel | null {
+  const parts = splitModelRef(raw);
+  if (!parts) return null;
+  if (/\s/.test(raw)) return null;
+  return { id: parts.id, provider: parts.provider, api: "" };
+}
+
 /**
  * List vision-capable chat models — those accepting image input.
  *
@@ -216,8 +358,13 @@ export function resolveVisionModel(
   registry: ChatModelRegistry,
 ): VisionModel | string {
   const vision = listVisionModels(registry);
+  const raw = input.trim();
 
   if (vision.length === 0) {
+    // Accept an explicit reference so a provider we cannot introspect is still
+    // usable (mirrors resolveImageGenModel).
+    const explicit = asExplicitVisionRef(raw);
+    if (explicit) return explicit;
     return (
       "No vision-capable models are configured.\n" +
       "→ image_recognize needs a model that accepts image input " +
@@ -226,7 +373,7 @@ export function resolveVisionModel(
     );
   }
 
-  const query = input.trim().toLowerCase();
+  const query = raw.toLowerCase();
   if (!query) return "No model specified.";
 
   const exact = vision.find((m) => formatModelRef(m).toLowerCase() === query);
@@ -283,8 +430,22 @@ export function resolveVisionModel(
       .join(", ")}`;
   }
 
+  // Unknown to the registry, but well-formed — accept it. Checked after
+  // `knownButBlind` so a registered text-only model still gets the precise
+  // "does not accept image input" error rather than being waved through.
+  const explicit = asExplicitVisionRef(raw);
+  if (explicit) return explicit;
+
   return (
     `Unknown model "${input}".\n` +
     `Vision-capable models: ${vision.map(formatModelRef).join(", ")}`
   );
 }
+
+/** Accept a well-formed "provider/model-id" the registry does not know. */
+function asExplicitVisionRef(raw: string): VisionModel | null {
+  const parts = splitModelRef(raw);
+  if (!parts) return null;
+  if (/\s/.test(raw)) return null;
+  return { id: parts.id, provider: parts.provider, input: ["text", "image"] };
+}

package/src/tools.ts

@@ -14,7 +14,7 @@ import { generateImage } from "./generate.js";
 import { loadImage } from "./image-source.js";
 import {
   formatModelRef,
-  listImageGenModels,
+  listAllImageGenModels,
   resolveImageGenModel,
   resolveVisionModel,
   splitModelRef,
@@ -108,7 +108,10 @@ function registerGenerateTool(pi: ExtensionAPI): void {
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       try {
         const config = loadConfig();
-        const models = await listImageGenModels();
+        const registry = getRegistry(ctx);
+        // Include image models contributed by registered providers, so the
+        // tool can resolve anything the settings picker offers.
+        const models = await listAllImageGenModels(registry);
 
         const requested = params.model?.trim() || config.generate.model;
         const resolved = resolveImageGenModel(requested, models);
@@ -116,7 +119,6 @@ function registerGenerateTool(pi: ExtensionAPI): void {
 
         // pi-ai resolves image auth from its own credential store; only fall
         // back to pi's chat-provider key when that comes up empty.
-        const registry = getRegistry(ctx);
         const fallbackKey = await resolveApiKey(registry, resolved.provider);
 
         const result = await generateImage({

package/src/tui/model-selector.ts

@@ -28,6 +28,9 @@ export class ImageModelSelectorOverlay implements Component {
   private saved = false;
   private error: string | null = null;
   private theme: Theme | null = null;
+  /** Free-text entry, for models the catalog does not know about. */
+  private customMode = false;
+  private custom = "";
 
   onClose?: () => void;
   onSelect?: (modelRef: string) => void;
@@ -56,6 +59,18 @@ export class ImageModelSelectorOverlay implements Component {
   invalidate(): void {}
 
   handleInput(data: string): void {
+    // Ctrl+C must always escape, even mid-filter. Without this the overlay traps
+    // the user with no way out.
+    if (data === "\x03") {
+      this.onClose?.();
+      return;
+    }
+
+    if (this.customMode) {
+      this.handleCustomInput(data);
+      return;
+    }
+
     if (this.filterMode) {
       this.handleFilterInput(data);
       return;
@@ -74,6 +89,14 @@ export class ImageModelSelectorOverlay implements Component {
         this.filterMode = true;
         this.filter = "";
         break;
+      case "c":
+      case "C":
+        // Escape hatch: generator detection is heuristic, so a provider may
+        // expose a model the catalog cannot recognise. Let the user name it.
+        this.customMode = true;
+        this.custom = "";
+        this.error = null;
+        break;
       case "\r":
         this.commit();
         break;
@@ -108,6 +131,50 @@ export class ImageModelSelectorOverlay implements Component {
     }
   }
 
+  /** Free-text "provider/model-id" entry. */
+  private handleCustomInput(data: string): void {
+    if (data === "\r") {
+      this.commitCustom();
+      return;
+    }
+    if (data === "\x1b") {
+      this.customMode = false;
+      this.custom = "";
+      this.error = null;
+      return;
+    }
+    if (data === "\x7f" || data === "\b") {
+      this.custom = this.custom.slice(0, -1);
+      this.error = null;
+      return;
+    }
+    if (data.length === 1 && data >= " ") {
+      this.custom += data;
+      this.error = null;
+    }
+  }
+
+  private commitCustom(): void {
+    const ref = this.custom.trim();
+    if (!ref) {
+      this.error = "Enter a model as provider/model-id";
+      return;
+    }
+    // Validate here rather than letting a malformed ref fail later with an
+    // opaque provider error.
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || slash === ref.length - 1) {
+      this.error = `"${ref}" must be in the form provider/model-id`;
+      return;
+    }
+
+    this.customMode = false;
+    this.onSelect?.(ref);
+    this.saved = true;
+    this.error = null;
+    this.onClose?.();
+  }
+
   private clampSelection(): void {
     this.selectedIndex = Math.min(
       this.selectedIndex,
@@ -137,7 +204,9 @@ export class ImageModelSelectorOverlay implements Component {
     this.onSelect?.(`${model.provider}/${model.id}`);
     this.saved = true;
     this.error = null;
-    setTimeout(() => this.onClose?.(), 500);
+    // Close immediately. A deferred close leaves the overlay focused while the
+    // caller resumes, which is what let input reach two components at once.
+    this.onClose?.();
   }
 
   // ─── Theme helpers ───────────────────────────────────────────────────
@@ -194,7 +263,20 @@ export class ImageModelSelectorOverlay implements Component {
     lines.push(this.ruleLine(innerWidth));
 
     // Filter bar
-    if (this.filterMode) {
+    if (this.customMode) {
+      lines.push(
+        this.frameLine(
+          `  ${this.fg("accent", "Model:")} ${this.custom}${this.fg("accent", "█")}`,
+          innerWidth,
+        ),
+      );
+      lines.push(
+        this.frameLine(
+          `  ${this.fg("dim", "e.g. omniroute/fal/fal-ai/flux-2-pro")}`,
+          innerWidth,
+        ),
+      );
+    } else if (this.filterMode) {
       lines.push(
         this.frameLine(
           `  ${this.fg("accent", "Filter:")} ${this.filter}${this.fg("accent", "█")}`,
@@ -211,7 +293,7 @@ export class ImageModelSelectorOverlay implements Component {
     } else {
       lines.push(
         this.frameLine(
-          `  ${this.fg("dim", `${this.models.length} models · press / to filter`)}`,
+          `  ${this.fg("dim", `${this.models.length} models · / filter · c custom`)}`,
           innerWidth,
         ),
       );
@@ -224,7 +306,9 @@ export class ImageModelSelectorOverlay implements Component {
     const start = Math.max(0, this.selectedIndex - Math.floor(maxVisible / 2));
     const end = Math.min(this.filtered.length, start + maxVisible);
 
-    if (this.filtered.length === 0) {
+    if (this.customMode) {
+      // The list is noise while typing a model reference.
+    } else if (this.filtered.length === 0) {
       const empty =
         this.models.length === 0
           ? this.kind === "generate"
@@ -246,7 +330,7 @@ export class ImageModelSelectorOverlay implements Component {
       }
     }
 
-    if (this.filtered.length > maxVisible) {
+    if (!this.customMode && this.filtered.length > maxVisible) {
       const pct = Math.round(((this.selectedIndex + 1) / this.filtered.length) * 100);
       lines.push(
         this.frameLine(
@@ -268,7 +352,12 @@ export class ImageModelSelectorOverlay implements Component {
     lines.push(this.ruleLine(innerWidth));
     lines.push(
       this.frameLine(
-        this.fg("dim", "↑↓ navigate · / filter · Enter select · Esc cancel"),
+        this.fg(
+          "dim",
+          this.customMode
+            ? "Enter save · Esc back to list"
+            : "↑↓ navigate · / filter · c custom · Enter select · Esc cancel",
+        ),
         innerWidth,
       ),
     );

package/src/tui/settings-dialog.ts

@@ -17,7 +17,7 @@ import {
 } from "../settings.js";
 import {
   formatModelRef,
-  listImageGenModels,
+  listAllImageGenModels,
   listVisionModels,
   type ChatModelRegistry,
 } from "../models.js";
@@ -165,36 +165,41 @@ async function pickModel(
 ): Promise<void> {
   const models = await collectModels(ctx, kind);
 
+  if (!ctx.hasUI) {
+    ctx.ui.notify("Model selection requires an interactive UI.", "warning");
+    return;
+  }
+
+  // An empty catalog is NOT a dead end: the overlay's custom entry (`c`) is
+  // precisely the escape hatch for a provider whose models we cannot detect.
   if (models.length === 0) {
     ctx.ui.notify(
       kind === "generate"
-        ? "No image models available. Image generation is served through OpenRouter — add a key with /login."
-        : "No vision-capable models configured. Add a model that accepts image input.",
+        ? "No image models detected — press c to enter one manually."
+        : "No vision-capable models detected — press c to enter one manually.",
       "warning",
     );
-    return;
-  }
-
-  if (!ctx.hasUI) {
-    ctx.ui.notify("Model selection requires an interactive UI.", "warning");
-    return;
   }
 
   const current =
     kind === "generate" ? config.generate.model : config.recognize.model;
 
-  await new Promise<void>((resolve) => {
-    ctx.ui.custom(
+  // `ctx.ui.custom` resolves only when the factory calls `done()`. It MUST be
+  // awaited: returning early leaves the overlay on screen while the settings
+  // loop mounts the next `ctx.ui.select`, so two focused components fight over
+  // the same keystrokes and neither can be closed.
+  let picked: string | undefined;
+
+  try {
+    picked = await ctx.ui.custom<string | undefined>(
       (tui, theme, _keybindings, done) => {
         const overlay = new ImageModelSelectorOverlay(kind, models, current);
         overlay.setTheme(theme);
+        overlay.requestRender = () => tui.requestRender();
         overlay.onSelect = (modelRef) => {
-          const next = loadConfig();
-          if (kind === "generate") next.generate.model = modelRef;
-          else next.recognize.model = modelRef;
-          saveConfig(next);
+          picked = modelRef;
         };
-        overlay.onClose = () => done(undefined);
+        overlay.onClose = () => done(picked);
         return {
           render: (width: number) => overlay.render(width),
           invalidate: () => overlay.invalidate(),
@@ -209,21 +214,36 @@ async function pickModel(
         overlayOptions: { width: "80%", minWidth: 50, anchor: "center", margin: 2 },
       },
     );
-    resolve();
-  });
+  } catch (err) {
+    ctx.ui.notify(`Model selector error: ${err}`, "error");
+    return;
+  }
+
+  // Persist only after the overlay has fully closed, so a cancel leaves the
+  // existing config untouched.
+  if (!picked) return;
+
+  const next = loadConfig();
+  if (kind === "generate") next.generate.model = picked;
+  else next.recognize.model = picked;
+  saveConfig(next);
+  ctx.ui.notify(`${kind === "generate" ? "Generation" : "Recognition"} model set to ${picked}`, "info");
 }
 
 async function collectModels(
   ctx: ExtensionCommandContext,
   kind: "generate" | "recognize",
 ): Promise<SelectableModel[]> {
+  const registry = (ctx as unknown as { modelRegistry?: ChatModelRegistry })
+    .modelRegistry;
+
   if (kind === "generate") {
-    const models = await listImageGenModels();
+    // Include models from providers registered by other extensions, not just
+    // pi-ai's built-in OpenRouter catalog.
+    const models = await listAllImageGenModels(registry);
     return models.map((m) => ({ provider: m.provider, id: m.id, name: m.name }));
   }
 
-  const registry = (ctx as unknown as { modelRegistry?: ChatModelRegistry })
-    .modelRegistry;
   if (!registry) return [];
 
   return listVisionModels(registry).map((m) => ({