@pi-unipi/image 2.2.1 → 2.2.3

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.1",
+  "version": "2.2.3",
   "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

@@ -244,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)."
     );
   }
 
@@ -285,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` +
@@ -293,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.
  *
@@ -331,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 " +
@@ -341,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);
@@ -398,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/recognize.ts

@@ -100,6 +100,7 @@ async function callAnthropic(options: RecognizeOptions): Promise<string> {
       body: JSON.stringify({
         model: modelId,
         max_tokens: maxTokens,
+        stream: false,
         system: systemPrompt,
         messages: [
           {
@@ -123,11 +124,14 @@ async function callAnthropic(options: RecognizeOptions): Promise<string> {
 
     if (!response.ok) throw new Error(await describeHttpError(response));
 
-    const data = (await response.json()) as {
-      content?: Array<{ type?: string; text?: string }>;
-    };
+    const data = await readJsonOrStream(response);
+
+    // A streamed response arrives as deltas rather than a `content` array.
+    const streamed = collectStreamedText(data);
+    if (streamed !== null) return streamed;
 
-    return (data.content ?? [])
+    const typed = data as { content?: Array<{ type?: string; text?: string }> };
+    return (typed.content ?? [])
       .filter((block) => block.type === "text" && typeof block.text === "string")
       .map((block) => block.text as string)
       .join("\n")
@@ -137,6 +141,79 @@ async function callAnthropic(options: RecognizeOptions): Promise<string> {
   }
 }
 
+/**
+ * Read a response body as JSON, tolerating a Server-Sent Events stream.
+ *
+ * Some OpenAI-compatible gateways (omniroute, for one) reply with
+ * `text/event-stream` even when streaming was never requested. Calling
+ * `response.json()` on that throws `Unexpected token 'd', "data: {"id"...`,
+ * which tells the user nothing. Parse the SSE frames instead and hand back a
+ * synthetic payload carrying the concatenated deltas.
+ */
+async function readJsonOrStream(response: Response): Promise<unknown> {
+  const body = await response.text();
+  const trimmed = body.trimStart();
+
+  if (!trimmed.startsWith("data:")) {
+    try {
+      return JSON.parse(body) as unknown;
+    } catch {
+      throw new Error(
+        `The model returned a response that could not be parsed:\n${body.slice(0, 200)}`,
+      );
+    }
+  }
+
+  const parts: string[] = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const payload = line.slice(5).trim();
+    if (!payload || payload === "[DONE]") continue;
+
+    let frame: unknown;
+    try {
+      frame = JSON.parse(payload);
+    } catch {
+      continue; // Ignore a partial or malformed frame rather than failing.
+    }
+    parts.push(...extractDeltaText(frame));
+  }
+
+  return { __streamedText: parts.join("") };
+}
+
+/** Pull text out of one SSE frame, in both OpenAI and Anthropic shapes. */
+function extractDeltaText(frame: unknown): string[] {
+  if (frame === null || typeof frame !== "object") return [];
+  const out: string[] = [];
+
+  // OpenAI: choices[].delta.content (or a non-streamed message.content)
+  const choices = (frame as { choices?: unknown }).choices;
+  if (Array.isArray(choices)) {
+    for (const choice of choices) {
+      if (choice === null || typeof choice !== "object") continue;
+      const delta = (choice as { delta?: { content?: unknown } }).delta;
+      if (typeof delta?.content === "string") out.push(delta.content);
+      const message = (choice as { message?: { content?: unknown } }).message;
+      if (typeof message?.content === "string") out.push(message.content);
+    }
+  }
+
+  // Anthropic: content_block_delta → delta.text
+  const delta = (frame as { delta?: { text?: unknown } }).delta;
+  if (typeof delta?.text === "string") out.push(delta.text);
+
+  return out;
+}
+
+/** Text collected from a streamed body, or null when it was ordinary JSON. */
+function collectStreamedText(data: unknown): string | null {
+  if (data === null || typeof data !== "object") return null;
+  const streamed = (data as { __streamedText?: unknown }).__streamedText;
+  if (typeof streamed !== "string") return null;
+  return streamed.trim();
+}
+
 /** OpenAI-compatible chat completions — image parts use a data: URL. */
 async function callOpenAICompatible(options: RecognizeOptions): Promise<string> {
   const {
@@ -159,6 +236,9 @@ async function callOpenAICompatible(options: RecognizeOptions): Promise<string>
         body: JSON.stringify({
           model: modelId,
           max_tokens: maxTokens,
+          // Ask for a single payload. Gateways may stream regardless, which
+          // readJsonOrStream handles.
+          stream: false,
           messages: [
             { role: "system", content: systemPrompt },
             {
@@ -181,11 +261,16 @@ async function callOpenAICompatible(options: RecognizeOptions): Promise<string>
 
     if (!response.ok) throw new Error(await describeHttpError(response));
 
-    const data = (await response.json()) as {
+    const data = await readJsonOrStream(response);
+
+    const streamed = collectStreamedText(data);
+    if (streamed !== null) return streamed;
+
+    const typed = data as {
       choices?: Array<{ message?: { content?: string | Array<{ text?: string }> } }>;
     };
 
-    const content = data.choices?.[0]?.message?.content;
+    const content = typed.choices?.[0]?.message?.content;
     if (typeof content === "string") return content.trim();
     if (Array.isArray(content)) {
       return content.map((part) => part?.text ?? "").join("").trim();

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;
@@ -63,6 +66,11 @@ export class ImageModelSelectorOverlay implements Component {
       return;
     }
 
+    if (this.customMode) {
+      this.handleCustomInput(data);
+      return;
+    }
+
     if (this.filterMode) {
       this.handleFilterInput(data);
       return;
@@ -81,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;
@@ -115,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,
@@ -203,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", "█")}`,
@@ -220,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,
         ),
       );
@@ -233,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"
@@ -255,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(
@@ -277,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

@@ -165,19 +165,20 @@ 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. Add an OpenRouter key with /login, or register a provider that exposes image models."
-        : "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 =