pi-cliproxyapi-native 0.3.1 → 0.3.2

package/README.md

@@ -13,6 +13,8 @@ Chat uses Pi's native API adapters and model metadata, with availability from yo
   - [Generate media](#generate-media)
   - [Resolution and aspect ratio](#resolution-and-aspect-ratio)
   - [OpenAI image controls and editing](#openai-image-controls-and-editing)
+  - [Image usage and cost](#image-usage-and-cost)
+  - [Pi image models](#pi-image-models)
   - [Supported media models](#supported-media-models)
   - [Files, status, and limits](#files-status-and-limits)
 - [Chat models](#chat-models)
@@ -34,10 +36,10 @@ The extension targets Pi 1.4.0 and CLIProxyAPI 8.0.48, with Node.js 22.19 or new
 If you installed `pi-cliproxy-native`, remove it before installing the renamed package. Both register the same `cliproxyapi` provider.
 
 ```sh
-pi install npm:pi-cliproxyapi-native@0.3.1
+pi install npm:pi-cliproxyapi-native@0.3.2
 ```
 
-For Git installation, use `pi install git:github.com/hawkff/pi-cliproxyapi-native@v0.3.1`. For a local checkout, use `pi install /path/to/pi-cliproxyapi-native`.
+For Git installation, use `pi install git:github.com/hawkff/pi-cliproxyapi-native@v0.3.2`. For a local checkout, use `pi install /path/to/pi-cliproxyapi-native`.
 
 The default proxy address is `http://localhost:8317`. For another address, set the [connection](#connection) before logging in. Restart Pi, then run:
 
@@ -154,17 +156,18 @@ Control values follow the [OpenAI image guide](https://developers.openai.com/api
 
 Use `cliproxyapi_media_models` to inspect controls for the exact advertised model ID. Omitted options keep the backend defaults. The extension rejects unsupported values before contacting the proxy.
 
-| Option               | Supported values                                                                                                                                                            |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `quality`            | `auto`, `low`, `medium`, `high`. Sunburst and Flare also accept `xhigh` and `max`.                                                                                          |
-| `background`         | `auto`, `opaque`, `transparent`. Transparent output requires PNG or WebP; GPT Image 2 transparency is in preview upstream.                                                  |
-| `output_format`      | `png`, `jpeg`, `webp`. JPEG and WebP can reduce file size and help keep results within the response limit.                                                                  |
-| `output_compression` | Integer from 0 to 100, with an explicit `jpeg` or `webp` format. Zero is a valid value.                                                                                     |
-| `moderation`         | `auto` or `low`. OpenAI still applies its content policies.                                                                                                                 |
-| `n`                  | Integer from 1 to 10 on an explicit `api/` image route. Other routes allow only 1 because subscription translation can drop the count.                                      |
-| `images`             | One to 16 local PNG, JPEG, or WebP paths. Supplying these selects `/v1/images/edits` instead of generation.                                                                 |
-| `mask`               | Optional local PNG mask. The first image must also be PNG with matching dimensions. The mask needs a grayscale-alpha or RGBA alpha channel; transparent regions mark edits. |
-| `input_fidelity`     | `low` or `high`, for GPT Image 1.5 editing only. Omit it for other models.                                                                                                  |
+| Option               | Supported values                                                                                                                                                                                   |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `quality`            | `auto`, `low`, `medium`, `high`. Sunburst and Flare also accept `xhigh` and `max`.                                                                                                                 |
+| `background`         | `auto`, `opaque`, `transparent`. Transparent output requires PNG or WebP; GPT Image 2 transparency is in preview upstream.                                                                         |
+| `output_format`      | `png`, `jpeg`, `webp`. JPEG and WebP can reduce file size and help keep results within the response limit.                                                                                         |
+| `output_compression` | Integer from 0 to 100, with an explicit `jpeg` or `webp` format. Zero is a valid value.                                                                                                            |
+| `moderation`         | `auto` or `low`. OpenAI still applies its content policies.                                                                                                                                        |
+| `n`                  | Integer from 1 to 10 on an explicit `api/` image route. Other routes allow only 1 because subscription translation can drop the count.                                                             |
+| `partial_images`     | Integer from 0 to 3. The proxy streams up to that many draft frames while the image renders, and Pi shows them as tool progress. Requires `n` of 1. Each draft adds about 100 image output tokens. |
+| `images`             | One to 16 local PNG, JPEG, or WebP paths. Supplying these selects `/v1/images/edits` instead of generation.                                                                                        |
+| `mask`               | Optional local PNG mask. The first image must also be PNG with matching dimensions. The mask needs a grayscale-alpha or RGBA alpha channel; transparent regions mark edits.                        |
+| `input_fidelity`     | `low` or `high`, for GPT Image 1.5 editing only. Omit it for other models.                                                                                                                         |
 
 Editing uploads the files you name to the configured proxy. Paths can be absolute or relative to the working directory. The extension accepts regular files, checks file signatures, and limits uploads to 14 MiB per file and 20 MiB total including the mask. It does not fetch input URLs, resize inputs, or modify source files. OpenAI performs full image decoding and validates the edit. These local limits keep base64 uploads bounded and may be lower than upstream limits.
 
@@ -173,9 +176,21 @@ Generate two images with api/gpt-image-2.5-sunburst at 1536x864, quality max, ou
 Edit ./photo.png with api/gpt-image-2.5-flare: replace the background with a garden, using ./mask.png as the mask.
 ```
 
-All returned images share the existing 32 MiB response limit and 4 MiB preview budget. Larger sizes, higher quality, and multiple images can increase cost and latency. Use fewer images or JPEG/WebP if the response exceeds the limit. Generation and editing do not retry after a failure.
+All returned images share the existing 32 MiB response limit and 4 MiB preview budget. Streamed requests allow another 32 MiB for each draft frame. The extension saves only the final image and drops drafts it cannot decode. Larger sizes, higher quality, and multiple images can increase cost and latency. Use fewer images or JPEG/WebP if the response exceeds the limit. Generation and editing do not retry after a failure.
 
-The extension supports the verified options above, not a general OpenAI API passthrough. Streaming image previews, remote file IDs, annotation markup, audio, batches, and realtime APIs are not exposed. Adding an upstream API key does not enable endpoints that the proxy or extension cannot handle.
+The extension supports the verified options above, not a general OpenAI API passthrough. Remote file IDs, annotation markup, audio, batches, and realtime APIs are not exposed. Adding an upstream API key does not enable endpoints that the proxy or extension cannot handle.
+
+### Image usage and cost
+
+OpenAI image responses report token usage. The image tool returns it to Pi, so image calls count toward the session totals in the footer and `/session`.
+
+Costs are estimates at OpenAI list prices per million tokens: $5 for text input, $8 for image input, and $30 for image output on GPT Image 2 and 2.5 Sunburst and Flare. GPT Image 1.5 output costs $32. The plain `gpt-image-2.5` subscription model has no published price, so it reports tokens at zero cost. Subscription routes show the same estimates when the proxy reports usage, even though the plan covers them. Google and xAI image results report no usage.
+
+### Pi image models
+
+When Pi refreshes the catalog, at interactive startup or through `/cliproxyapi-refresh`, the advertised image models also register as Pi image models. Codemode scripts list them with `models.getAvailableOfType("image", "cliproxyapi")` and call `models.generateImages()`, and other extensions can use `ctx.modelRegistry.generateImages()`.
+
+These calls send the prompt with backend defaults. Pi's image interface has no size, quality, count, mask, or preview options. Image blocks in the input select OpenAI editing, under the same 16-image, 14 MiB per image, and 20 MiB total limits. Google and xAI models accept text only. Results arrive as image blocks with usage and are not saved to disk. Use `cliproxyapi_generate_image` when you need controls, masks, or saved files.
 
 ### Supported media models
 
@@ -187,7 +202,7 @@ Your proxy must advertise the exact ID for a model to be available.
 | Google models | `gemini-2.5-flash-image`, `gemini-3.1-flash-image`, `gemini-3-pro-image`, `gemini-3.1-flash-lite-image`                                                        |
 | xAI models    | `grok-imagine-image`, `grok-imagine-image-quality`, `grok-imagine-image-2.0`, `grok-imagine-video`, `grok-imagine-video-1.5`, `grok-imagine-video-1.5-preview` |
 
-Supported media IDs can also use advertised `api/` and `oauth/` credential routes. Gemini image models also support `vertex/` and `antigravity/` backend routes. Those backend prefixes do not enable OpenAI or xAI media execution; the picker shows those entries as disabled. Other prefixes, nested prefixes, media aliases, unknown media IDs, Google Veo, and non-OpenAI editing are unsupported.
+Supported media IDs can also use advertised `api/` and `oauth/` credential routes. OpenAI's API has no plain `gpt-image-2.5`, so the picker disables `api/gpt-image-2.5` and points to Sunburst or Flare; subscription routes keep it. Gemini image models also support `vertex/` and `antigravity/` backend routes. Those backend prefixes do not enable OpenAI or xAI media execution; the picker shows those entries as disabled. Other prefixes, nested prefixes, media aliases, unknown media IDs, Google Veo, and non-OpenAI editing are unsupported.
 
 The extension disables these retired Imagen IDs, including their supported prefixed forms:
 
@@ -213,21 +228,23 @@ Video submission returns a request ID without waiting for generation. Call `clip
 | ---------------------------------- | ---------- | ---------------------------------------------- |
 | Catalog fetch                      | 10 seconds | 4 MiB                                          |
 | Media listing or video status      | 15 seconds | 4 MiB for the catalog; 64 KiB for video status |
-| OpenAI image generation or editing | 10 minutes | 32 MiB                                         |
+| OpenAI image generation or editing | 10 minutes | 32 MiB, plus 32 MiB per streamed draft         |
 | Other image generation             | 3 minutes  | 32 MiB                                         |
 | Video submission                   | 60 seconds | 64 KiB                                         |
 
-Media deadlines include input-file reads, authentication, and network waits. Discovery and media requests reject redirects and report HTTP errors without upstream response bodies.
+Media deadlines include input-file reads, authentication, and network waits. Discovery and media requests reject redirects. Media errors quote the `message` from an upstream JSON error, cut to 500 characters, with credentials and control characters removed. Other error bodies and discovery errors report only the HTTP status.
 
 The media tools do not retry generation. Cancellation or timeout can leave work running upstream. Check a known video request ID before submitting another generation.
 
 ## Chat models
 
-The extension discovers available IDs through `/v1/models` and matches them against Pi's built-in metadata for limits, prices, inputs, and thinking capabilities.
+The extension discovers available IDs through `/v1/models` and matches them against Pi's Anthropic, OpenAI, OpenAI Codex, Google, and xAI metadata for limits, prices, inputs, and thinking capabilities. xAI Grok models use Pi's native Responses adapter through the proxy.
+
+During a session, the extension also reads the provider catalogs that Pi refreshes from its catalog service. Models newer than Pi's bundled data can then register; for models Pi already bundles, the bundled metadata wins.
 
 ### Refresh
 
-Run `/cliproxyapi-refresh` to update the chat catalog.
+Run `/cliproxyapi-refresh` to update the chat and image catalogs. It reports both counts and lists up to 20 advertised IDs that it could not register because Pi has no metadata for them or the match is ambiguous.
 
 ### Wait for quota reset
 
@@ -361,9 +378,9 @@ Run `/reload` after changing settings and `/cliproxyapi-refresh` before starting
 
 Claude uses the legacy fine-grained tool-streaming header in place of eager tool fields. The extension disables unverified deferred-tool and strict-tool capabilities. Responses function tools use `strict: null` when Pi omits strictness, so optional arguments remain optional. Explicit payload hooks retain final control.
 
-OpenAI images POST `model`, `prompt`, `n`, and supplied controls to `/v1/images/generations`, without `response_format`. Editing uses `/v1/images/edits` with JSON `images` and optional `mask` data URLs. xAI uses the same route with `response_format: "b64_json"`. Gemini uses `/v1beta/models/{id}:generateContent`. Media generation sends the prompt and generation options without chat history, system instructions, or tools.
+OpenAI images POST `model`, `prompt`, `n`, and supplied controls to `/v1/images/generations`, without `response_format`. Editing uses `/v1/images/edits` with JSON `images` and optional `mask` data URLs. A nonzero `partial_images` adds `stream: true`, and the extension reads server-sent events. Each `*.partial_image` frame becomes a progress preview, and the `*.completed` frame carries the final image and usage. xAI uses the same route with `response_format: "b64_json"`. Gemini uses `/v1beta/models/{id}:generateContent`. Media generation sends the prompt and generation options without chat history, system instructions, or tools.
 
-OpenAI image POSTs use a dedicated HTTP connection and preserve Node's configured proxy routing. They disable socket timeouts so the ten-minute deadline controls the request, request identity encoding, and reject compressed responses.
+OpenAI image POSTs use a dedicated HTTP connection. It follows `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` from the environment, where Pi also places its `httpProxy` setting, on Node 22.21+ and 24.5+. Older Node versions connect directly. The connection disables socket timeouts so the ten-minute deadline controls the request, requests identity encoding, and rejects compressed responses.
 
 The OpenAI image implementation follows CLIProxyAPI v8.0.48's [image handler](https://github.com/router-for-me/CLIProxyAPI/blob/v8.0.48/sdk/api/handlers/openai/openai_images_handlers.go) and [Codex image executor](https://github.com/router-for-me/CLIProxyAPI/blob/v8.0.48/internal/runtime/executor/codex_openai_images.go), plus the OpenAI [generation](https://developers.openai.com/api/reference/resources/images/methods/generate) and [editing](https://developers.openai.com/api/reference/resources/images/methods/edit) references. The xAI and Google routes follow v7.2.158's [video handler](https://github.com/router-for-me/CLIProxyAPI/blob/v7.2.158/sdk/api/handlers/openai/openai_videos_handlers.go), [Gemini handler](https://github.com/router-for-me/CLIProxyAPI/blob/v7.2.158/sdk/api/handlers/gemini/gemini_handlers.go), and [Vertex executor](https://github.com/router-for-me/CLIProxyAPI/blob/v7.2.158/internal/runtime/executor/gemini_vertex_executor.go). See [xAI's video documentation](https://docs.x.ai/developers/model-capabilities/video/generation) for duration and status semantics.
 

package/extensions/index.ts

@@ -4,7 +4,7 @@ import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil
 import { PROVIDER_ID, parseConfig } from "../src/config.ts";
 import { registerMediaTools } from "../src/media.ts";
 import { registerModelPicker } from "../src/picker.ts";
-import { createCliproxyProvider } from "../src/provider.ts";
+import { createCliproxyProvider, metadataCatalog } from "../src/provider.ts";
 import { registerAutoRetry } from "../src/retry.ts";
 
 export default async function (pi: ExtensionAPI) {
@@ -37,32 +37,32 @@ export default async function (pi: ExtensionAPI) {
     context = undefined;
     waits.clear();
   });
-  pi.registerProvider(
-    createCliproxyProvider(
-      config,
-      undefined,
-      (id, seconds) => {
-        if (!context) return;
-        if (seconds === undefined) waits.delete(id);
-        else {
-          if (!waits.has(id)) {
-            const message = `CLIProxyAPI quota limit. Retrying at ${new Date(Date.now() + seconds * 1000).toLocaleString()}. Cancel the current request to stop waiting.`;
-            if (context.mode === "print" || context.mode === "json") process.stderr.write(`${message}\n`);
-            else context.ui.notify(message, "warning");
-          }
-          waits.set(id, seconds);
+  const provider = createCliproxyProvider(
+    config,
+    // Session context exposes Pi's refreshed catalogs, including models newer than its bundled data.
+    () => metadataCatalog(context && ((id) => context?.modelRegistry.getProvider(id)?.getModels())),
+    (id, seconds) => {
+      if (!context) return;
+      if (seconds === undefined) waits.delete(id);
+      else {
+        if (!waits.has(id)) {
+          const message = `CLIProxyAPI quota limit. Retrying at ${new Date(Date.now() + seconds * 1000).toLocaleString()}. Cancel the current request to stop waiting.`;
+          if (context.mode === "print" || context.mode === "json") process.stderr.write(`${message}\n`);
+          else context.ui.notify(message, "warning");
         }
-        const remaining = Math.min(...waits.values());
-        context.ui.setStatus(
-          "cliproxyapi-quota",
-          waits.size
-            ? `CLIProxyAPI quota: retry in ${Math.floor(remaining / 3600)}h ${Math.floor(remaining / 60) % 60}m ${remaining % 60}s`
-            : undefined,
-        );
-      },
-      compactionSignals,
-    ),
+        waits.set(id, seconds);
+      }
+      const remaining = Math.min(...waits.values());
+      context.ui.setStatus(
+        "cliproxyapi-quota",
+        waits.size
+          ? `CLIProxyAPI quota: retry in ${Math.floor(remaining / 3600)}h ${Math.floor(remaining / 60) % 60}m ${remaining % 60}s`
+          : undefined,
+      );
+    },
+    compactionSignals,
   );
+  pi.registerProvider(provider);
   registerAutoRetry(pi);
   registerMediaTools(pi, config);
   registerModelPicker(pi, config);
@@ -88,7 +88,16 @@ export default async function (pi: ExtensionAPI) {
         return;
       }
       const count = ctx.modelRegistry.getAll().filter((model) => model.provider === PROVIDER_ID).length;
-      ctx.ui.notify(`CLIProxyAPI: ${count} models.`, "info");
+      const images = ctx.modelRegistry.getModelsOfType("image", PROVIDER_ID).length;
+      const skipped = provider.skippedModels();
+      const listed = [
+        ...skipped.slice(0, 20),
+        ...(skipped.length > 20 ? [`${skipped.length - 20} more`] : []),
+      ];
+      ctx.ui.notify(
+        `CLIProxyAPI: ${count} chat models, ${images} image models.${listed.length ? ` Not registered (missing or ambiguous Pi metadata): ${listed.join(", ")}.` : ""}`,
+        "info",
+      );
     },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cliproxyapi-native",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "CLIProxyAPI chat discovery, image generation and editing, and video generation with Pi's native adapters",
   "publishConfig": {
     "access": "public"

package/src/catalog.ts

@@ -1,5 +1,5 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { type Config, isModelId, isRecord, PROVIDER_ID } from "./config.ts";
+import { type Config, deadline, isModelId, isRecord, PROVIDER_ID, validateKey } from "./config.ts";
 
 export type CpaApi =
   | "anthropic-messages"
@@ -34,6 +34,51 @@ export function parseCatalog(value: unknown) {
   });
 }
 
+export async function fetchCatalog(config: Config, key: string, signal: AbortSignal) {
+  validateKey(key);
+  const boundedSignal = deadline(signal, 10000);
+  let response: Response;
+  try {
+    response = await fetch(`${config.baseUrl}/v1/models`, {
+      headers: { Authorization: `Bearer ${key}` },
+      redirect: "error",
+      signal: boundedSignal,
+    });
+  } catch {
+    signal.throwIfAborted();
+    throw new Error("CLIProxyAPI discovery failed: connection, timeout, or redirect error.");
+  }
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(`CLIProxyAPI discovery failed (HTTP ${response.status}).`);
+  }
+  let payload: unknown;
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error("CLIProxyAPI discovery returned an empty response.");
+  try {
+    const decoder = new TextDecoder();
+    let text = "";
+    let size = 0;
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 4 * 1024 * 1024) {
+        await reader.cancel();
+        throw new Error("Catalog too large.");
+      }
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    payload = JSON.parse(text + decoder.decode());
+  } catch {
+    signal.throwIfAborted();
+    throw new Error("CLIProxyAPI catalog is invalid, incomplete, or larger than 4 MiB.");
+  } finally {
+    reader.releaseLock();
+  }
+  return payload;
+}
+
 // Resolve metadata and capabilities without changing registry or request IDs.
 export function modelRoute(id: string) {
   const match = /^(vertex|antigravity|oauth|api)\/(.+)$/.exec(id);
@@ -59,17 +104,31 @@ export function routedName(id: string, name = id) {
 export type MediaPurpose = "image" | "video";
 
 const imagenRetirement = "Retired on Vertex (June 2026); disabled. Select a Nano Banana image model instead.";
+// OpenAI list prices in USD per million tokens: text input, image input, image output.
+const gptImage2Price = [5, 8, 30] as const;
 
 // Exact media IDs, including retired entries; vision input alone does not imply image output.
 const mediaModels = new Map<
   string,
-  { name: string; purpose: MediaPurpose; route?: "xai" | "gemini" | "openai"; disabledReason?: string }
+  {
+    name: string;
+    purpose: MediaPurpose;
+    route?: "xai" | "gemini" | "openai";
+    disabledReason?: string;
+    price?: readonly [number, number, number];
+  }
 >([
-  ["gpt-image-2.5-flare", { name: "GPT Image 2.5 Flare", purpose: "image", route: "openai" }],
-  ["gpt-image-2.5-sunburst", { name: "GPT Image 2.5 Sunburst", purpose: "image", route: "openai" }],
+  [
+    "gpt-image-2.5-flare",
+    { name: "GPT Image 2.5 Flare", purpose: "image", route: "openai", price: gptImage2Price },
+  ],
+  [
+    "gpt-image-2.5-sunburst",
+    { name: "GPT Image 2.5 Sunburst", purpose: "image", route: "openai", price: gptImage2Price },
+  ],
   ["gpt-image-2.5", { name: "GPT Image 2.5", purpose: "image", route: "openai" }],
-  ["gpt-image-2", { name: "GPT Image 2", purpose: "image", route: "openai" }],
-  ["gpt-image-1.5", { name: "GPT Image 1.5", purpose: "image", route: "openai" }],
+  ["gpt-image-2", { name: "GPT Image 2", purpose: "image", route: "openai", price: gptImage2Price }],
+  ["gpt-image-1.5", { name: "GPT Image 1.5", purpose: "image", route: "openai", price: [5, 8, 32] }],
   ["grok-imagine-image", { name: "Grok Imagine Image", purpose: "image", route: "xai" }],
   ["grok-imagine-image-quality", { name: "Grok Imagine Image Quality", purpose: "image", route: "xai" }],
   ["grok-imagine-image-2.0", { name: "Grok Imagine Image 2.0", purpose: "image", route: "xai" }],
@@ -100,11 +159,20 @@ const mediaModels = new Map<
 ]);
 
 export function mediaCapability(id: string) {
-  const { metadataId, backend } = modelRoute(id);
+  const { metadataId, backend, authType } = modelRoute(id);
   const capability = mediaModels.get(metadataId);
   if (backend && (capability?.route === "xai" || capability?.route === "openai")) {
     return { ...capability, route: undefined, disabledReason: `Unsupported media execution on ${backend}.` };
   }
+  // CLIProxyAPI 8.0.48 advertises it for API keys, but OpenAI's Images API rejects the bare 2.5 name.
+  if (capability && authType === "api-key" && metadataId === "gpt-image-2.5") {
+    return {
+      ...capability,
+      route: undefined,
+      disabledReason:
+        "OpenAI's API has no gpt-image-2.5 model. Use api/gpt-image-2.5-sunburst or api/gpt-image-2.5-flare.",
+    };
+  }
   return capability;
 }
 
@@ -160,6 +228,7 @@ export function mediaControls(id: string) {
     moderation: openai ? ["auto", "low"] : [],
     // Subscription image-tool translation does not forward n.
     n: openai ? { min: 1, max: authType === "api-key" ? 10 : 1 } : undefined,
+    partial_images: openai ? { min: 0, max: 3 } : undefined,
     editing: openai
       ? { max_images: 16, max_file_bytes: 14 * 1024 * 1024, max_total_bytes: 20 * 1024 * 1024, mask: "png" }
       : undefined,
@@ -167,6 +236,29 @@ export function mediaControls(id: string) {
   };
 }
 
+export const IMAGE_API = "cliproxyapi-images";
+
+// Pi image models for codemode and extensions; video stays tool-only because Pi has no video interface.
+export function mapImageModels(value: unknown, config: Config) {
+  return mapMediaCatalog(value).flatMap(({ id, purpose, name, controls }) => {
+    if (purpose !== "image") return [];
+    const [input = 0, , output = 0] = mediaCapability(id)?.price ?? [];
+    return [
+      {
+        type: "image" as const,
+        id,
+        name,
+        api: IMAGE_API,
+        provider: PROVIDER_ID,
+        baseUrl: config.baseUrl,
+        input: controls.editing ? ["text" as const, "image" as const] : ["text" as const],
+        output: ["image" as const],
+        cost: { input, output, cacheRead: 0, cacheWrite: 0 },
+      },
+    ];
+  });
+}
+
 export function mapMediaCatalog(value: unknown) {
   const models = new Map<
     string,
@@ -194,6 +286,7 @@ const owners: Readonly<Record<string, string>> = {
   google: "google",
   gemini: "google",
   "gemini-cli": "google",
+  xai: "xai",
 };
 
 // Built-in aliases for advertised IDs without native metadata; exact metadata still wins.
@@ -209,11 +302,7 @@ export function mapCatalog(value: unknown, config: Config, known: readonly Model
   const byId = Map.groupBy(known, (model) => model.id);
   const byReference = Map.groupBy(known, (model) => `${model.provider}/${model.id}`);
   for (const entry of parseCatalog(value)) {
-    if (entry.hidden || models.has(entry.id)) continue;
-    if (mediaPurpose(entry.id)) {
-      skipped.add(entry.id);
-      continue;
-    }
+    if (entry.hidden || models.has(entry.id) || mediaPurpose(entry.id)) continue;
     const { metadataId, prefix } = modelRoute(entry.id);
     const routed = !entry.id.includes("/") || prefix;
     const alias = Object.hasOwn(config.aliases, entry.id)

package/src/config.ts

@@ -9,6 +9,17 @@ export function isModelId(value: unknown): value is string {
   return typeof value === "string" && /^[!-~]{1,256}$/.test(value);
 }
 
+export function validateKey(key: string) {
+  if (!/^[!-~]{1,4096}$/.test(key)) {
+    throw new Error("CLIProxyAPI requires a non-empty API key without whitespace or control characters.");
+  }
+  return key;
+}
+
+export function deadline(signal: AbortSignal | undefined, milliseconds: number) {
+  return AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(milliseconds)]);
+}
+
 export function normalizeBaseUrl(value: string) {
   let url: URL;
   try {

package/src/media.ts

@@ -4,12 +4,22 @@ import * as http from "node:http";
 import * as https from "node:https";
 import { join, resolve } from "node:path";
 import { addAbortSignal, Readable } from "node:stream";
-import { type ImageContent, type Static, type TextContent, Type } from "@earendil-works/pi-ai";
+import {
+  type AssistantImages,
+  type ImageApi,
+  type ImageContent,
+  type ImageModel,
+  type ImagesContext,
+  type ImagesOptions,
+  type Static,
+  type TextContent,
+  Type,
+  type Usage,
+} from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { mapMediaCatalog, mediaCapability, mediaControls } from "./catalog.ts";
-import { type Config, isRecord, PROVIDER_ID } from "./config.ts";
+import { fetchCatalog, mapMediaCatalog, mediaCapability, mediaControls } from "./catalog.ts";
+import { type Config, deadline, isRecord, PROVIDER_ID, validateKey } from "./config.ts";
 import { type DefaultsContext, effectiveMediaDefaults, resolveMediaModel } from "./media-defaults.ts";
-import { deadline, fetchCatalog, validateKey } from "./provider.ts";
 
 type MediaContext = Pick<ExtensionContext, "cwd" | "model"> &
   DefaultsContext & {
@@ -17,6 +27,7 @@ type MediaContext = Pick<ExtensionContext, "cwd" | "model"> &
   };
 
 const MAX_INLINE_IMAGE_BASE64_BYTES = 4 * 1024 * 1024;
+const MAX_IMAGE_RESPONSE_BYTES = 32 * 1024 * 1024;
 
 const generationParameters = Type.Object({
   model: Type.Optional(
@@ -79,6 +90,14 @@ const imageParameters = Type.Object({
         "OpenAI image count. Values above 1 require an explicit api/ route; see controls.n. Default 1.",
     }),
   ),
+  partial_images: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      maximum: 3,
+      description:
+        "OpenAI only: stream up to 3 partial previews while generating. Requires n of 1; each preview adds about 100 output tokens. Omit or 0 for none.",
+    }),
+  ),
   images: Type.Optional(
     Type.Array(Type.String({ minLength: 1 }), {
       minItems: 1,
@@ -129,6 +148,7 @@ function mediaOutputOptions(model: string, params: Partial<Static<typeof imagePa
     moderation: params.moderation,
     n: params.n,
     input_fidelity: params.input_fidelity,
+    partial_images: params.partial_images,
   };
   const controls = mediaControls(model);
   for (const field of [
@@ -171,6 +191,17 @@ function mediaOutputOptions(model: string, params: Partial<Static<typeof imagePa
     (!controls.n || !Number.isInteger(options.n) || options.n < controls.n.min || options.n > controls.n.max)
   )
     throw new Error("CLIProxyAPI n is unsupported for this route. Use an api/ image model for 2–10 images.");
+  if (
+    options.partial_images !== undefined &&
+    (!controls.partial_images ||
+      !Number.isInteger(options.partial_images) ||
+      options.partial_images < controls.partial_images.min ||
+      options.partial_images > controls.partial_images.max ||
+      (options.partial_images > 0 && (options.n ?? 1) !== 1))
+  )
+    throw new Error(
+      "CLIProxyAPI partial_images requires an OpenAI image model, n of 1, and an integer from 0 to 3.",
+    );
   if (
     options.output_compression !== undefined &&
     (!controls.output_compression ||
@@ -296,64 +327,180 @@ export async function mediaKey(ctx: Pick<MediaContext, "modelRegistry">, signal:
   }
 }
 
-function openaiImageResponse(config: Config, key: string, path: string, body: object, signal: AbortSignal) {
-  return new Promise<{ ok: boolean; status: number; body: ReturnType<typeof Readable.toWeb> | null }>(
-    (resolve, reject) => {
-      const url = new URL(`${config.baseUrl}/${path}`);
-      const transport = url.protocol === "https:" ? https : http;
-      const options = "options" in transport.globalAgent ? transport.globalAgent.options : undefined;
-      // Preserve configured proxies without inheriting the global agent's socket timeout.
-      const agent = new transport.Agent({
-        ...(isRecord(options) ? options : {}),
-        keepAlive: false,
+// Pi's native image interface can supply transport options; the image tool uses none.
+type TransportOptions = Pick<ImagesOptions, "fetch" | "headers" | "env"> & {
+  onResponse?: (response: { status: number; headers: Record<string, string> }) => unknown;
+};
+
+function requestHeaders(key: string, extra: TransportOptions["headers"] = {}) {
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(extra))
+    if (value !== null && !["authorization", "content-type", "accept-encoding"].includes(name.toLowerCase()))
+      headers[name] = value;
+  return { ...headers, Authorization: `Bearer ${key}`, "Content-Type": "application/json" };
+}
+
+function openaiImageResponse(
+  config: Config,
+  key: string,
+  path: string,
+  body: unknown,
+  signal: AbortSignal,
+  { headers, env }: TransportOptions,
+) {
+  return new Promise<{
+    ok: boolean;
+    status: number;
+    headers: Record<string, string>;
+    body: ResponseBody | null;
+  }>((resolve, reject) => {
+    const url = new URL(`${config.baseUrl}/${path}`);
+    const transport = url.protocol === "https:" ? https : http;
+    const options = "options" in transport.globalAgent ? transport.globalAgent.options : undefined;
+    // Pi exports its proxy setting to the environment. Node 22.21+ and 24.5+ apply proxyEnv,
+    // including NO_PROXY; older Node versions connect directly. The global socket timeout is dropped.
+    const agent = new transport.Agent({
+      ...(isRecord(options) ? options : {}),
+      proxyEnv: { ...process.env, ...env },
+      keepAlive: false,
+      timeout: 0,
+    });
+    const connect = agent.createConnection.bind(agent);
+    agent.createConnection = (connectionOptions, callback) => {
+      // Node assigns HTTPS proxy sockets to the request only after CONNECT completes.
+      const socket = connect(connectionOptions, callback);
+      return socket ? addAbortSignal(signal, socket) : socket;
+    };
+    const request = transport.request(
+      url,
+      {
+        method: "POST",
+        agent,
         timeout: 0,
-      });
-      const connect = agent.createConnection.bind(agent);
-      agent.createConnection = (connectionOptions, callback) => {
-        // Node assigns HTTPS proxy sockets to the request only after CONNECT completes.
-        const socket = connect(connectionOptions, callback);
-        return socket ? addAbortSignal(signal, socket) : socket;
-      };
-      const request = transport.request(
-        url,
-        {
-          method: "POST",
-          agent,
-          timeout: 0,
-          signal,
-          headers: {
-            Authorization: `Bearer ${key}`,
-            "Content-Type": "application/json",
-            "Accept-Encoding": "identity",
-          },
-        },
-        (incoming) => {
-          const status = incoming.statusCode ?? 500;
-          if (status < 200 || status >= 300) {
-            incoming.destroy();
-            resolve({ ok: false, status, body: null });
-            return;
-          }
-          if (incoming.headers["content-encoding"] && incoming.headers["content-encoding"] !== "identity") {
-            incoming.destroy();
-            reject(new Error("Unsupported image response encoding."));
-            return;
-          }
-          resolve({
-            ok: true,
-            status,
-            body: Readable.toWeb(addAbortSignal(signal, incoming), { strategy: { highWaterMark: 1 } }),
-          });
-        },
-      );
-      request.on("error", reject);
-      request.on("upgrade", (incoming, socket) => {
-        socket.destroy();
-        resolve({ ok: false, status: incoming.statusCode ?? 101, body: null });
-      });
-      request.end(JSON.stringify(body));
-    },
-  );
+        signal,
+        headers: { ...requestHeaders(key, headers), "Accept-Encoding": "identity" },
+      },
+      (incoming) => {
+        const status = incoming.statusCode ?? 500;
+        const ok = status >= 200 && status < 300;
+        const received = Object.fromEntries(
+          Object.entries(incoming.headers).flatMap(([name, value]) =>
+            value === undefined ? [] : [[name, Array.isArray(value) ? value.join(", ") : value]],
+          ),
+        );
+        if (incoming.headers["content-encoding"] && incoming.headers["content-encoding"] !== "identity") {
+          incoming.destroy();
+          if (ok) reject(new Error("Unsupported image response encoding."));
+          else resolve({ ok, status, headers: received, body: null });
+          return;
+        }
+        resolve({
+          ok,
+          status,
+          headers: received,
+          body: Readable.toWeb(addAbortSignal(signal, incoming), { strategy: { highWaterMark: 1 } }),
+        });
+      },
+    );
+    request.on("error", reject);
+    request.on("upgrade", (incoming, socket) => {
+      socket.destroy();
+      resolve({ ok: false, status: incoming.statusCode ?? 101, headers: {}, body: null });
+    });
+    request.end(JSON.stringify(body));
+  });
+}
+
+type StreamReader = {
+  read(): Promise<{ done: boolean; value?: Uint8Array }>;
+  cancel(): Promise<void>;
+};
+// Fetch and Node web streams have incompatible DOM typings; both satisfy this shape.
+type ResponseBody = { getReader(): StreamReader & { releaseLock(): void }; cancel(): Promise<void> };
+
+// Upstream errors name the rejected option or model. Show a short JSON message without credentials.
+async function errorDetail(reader: StreamReader, key: string) {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  // A stalled error body must not hold the failure until the request deadline; cancel ends pending reads.
+  const stall = setTimeout(() => void reader.cancel().catch(() => {}), 5000);
+  try {
+    while (size <= 64 * 1024) {
+      const chunk = await reader.read();
+      if (chunk.done || !chunk.value) break;
+      chunks.push(chunk.value);
+      size += chunk.value.byteLength;
+    }
+    return errorText(JSON.parse(Buffer.concat(chunks).toString("utf8")), key);
+  } catch {
+    return "";
+  } finally {
+    clearTimeout(stall);
+    void reader.cancel().catch(() => {});
+  }
+}
+
+function errorText(value: unknown, key: string) {
+  const error = isRecord(value) && isRecord(value.error) ? value.error : value;
+  // OpenAI-style bodies nest { message }; xAI-style bodies use a string error.
+  const message = !isRecord(error)
+    ? undefined
+    : typeof error.message === "string"
+      ? error.message
+      : typeof error.error === "string"
+        ? error.error
+        : undefined;
+  if (message === undefined) return "";
+  // Covers the proxy key, bearer tokens, and OpenAI, Anthropic, xAI, and Google key formats.
+  return message
+    .split(key)
+    .join("[redacted]")
+    .replace(/\b(?:sk-|xai-|AIza|ya29\.|Bearer\s+)[\w.~+/=-]+/gi, "[redacted]")
+    .replace(/[\p{C}\s]+/gu, " ")
+    .trim()
+    .slice(0, 500);
+}
+
+// Server-sent events: partial previews go to the callback, other events are returned in order.
+async function readEvents(
+  reader: StreamReader,
+  maxBytes: number,
+  onPartial: (event: Record<string, unknown>) => void,
+) {
+  const decoder = new TextDecoder();
+  const events: Record<string, unknown>[] = [];
+  let buffer = "";
+  // A CRLF pair can straddle two chunks; hold a trailing CR until the next chunk arrives.
+  let carry = "";
+  let size = 0;
+  const frame = (text: string) => {
+    const data = text
+      .split("\n")
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).replace(/^ /, "").replace(/\r$/, ""))
+      .join("\n");
+    if (!data || data === "[DONE]") return;
+    const event: unknown = JSON.parse(data);
+    if (!isRecord(event)) throw new Error("Invalid image event.");
+    if (typeof event.type === "string" && event.type.endsWith(".partial_image")) onPartial(event);
+    else events.push(event);
+  };
+  for (let searched = 0; ; ) {
+    const chunk = await reader.read();
+    if (chunk.done || !chunk.value) break;
+    size += chunk.value.byteLength;
+    if (size > maxBytes) throw new Error("Response too large.");
+    const text = carry + decoder.decode(chunk.value, { stream: true });
+    carry = text.endsWith("\r") ? "\r" : "";
+    buffer += (carry ? text.slice(0, -1) : text).replace(/\r\n/g, "\n");
+    for (let end = buffer.indexOf("\n\n", searched); end >= 0; end = buffer.indexOf("\n\n")) {
+      frame(buffer.slice(0, end));
+      buffer = buffer.slice(end + 2);
+    }
+    searched = Math.max(0, buffer.length - 1);
+  }
+  frame(buffer + (carry + decoder.decode()).replace(/\r\n/g, "\n"));
+  return events;
 }
 
 async function mediaRequest(
@@ -361,39 +508,65 @@ async function mediaRequest(
   key: string,
   path: string,
   signal: AbortSignal,
-  maxBytes: number,
-  body?: object,
-  openaiImage = false,
+  {
+    maxBytes,
+    body,
+    openaiImage = false,
+    onPartial,
+    ...transport
+  }: TransportOptions & {
+    maxBytes: number;
+    body?: unknown;
+    openaiImage?: boolean;
+    onPartial?: (event: Record<string, unknown>) => void;
+  },
 ) {
-  let response: Response | Awaited<ReturnType<typeof openaiImageResponse>>;
+  let response: Awaited<ReturnType<typeof openaiImageResponse>>;
   try {
-    response =
-      openaiImage && body
-        ? await openaiImageResponse(config, key, path, body, signal)
-        : await fetch(`${config.baseUrl}/${path}`, {
-            method: body ? "POST" : "GET",
-            headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
-            body: body ? JSON.stringify(body) : undefined,
-            redirect: "error",
-            signal,
-          });
+    // A caller-supplied fetch replaces the dedicated image connection and owns its timeouts.
+    if (openaiImage && body && !transport.fetch)
+      response = await openaiImageResponse(config, key, path, body, signal, transport);
+    else {
+      const result = await (transport.fetch ?? fetch)(`${config.baseUrl}/${path}`, {
+        method: body ? "POST" : "GET",
+        headers: requestHeaders(key, transport.headers),
+        body: body ? JSON.stringify(body) : undefined,
+        redirect: "error",
+        signal,
+      });
+      response = {
+        ok: result.ok,
+        status: result.status,
+        headers: Object.fromEntries(result.headers),
+        body: result.body,
+      };
+    }
   } catch {
     throw new Error(
       "CLIProxyAPI media request failed: connection, cancellation, timeout, or redirect error. Generation was not retried.",
     );
   }
-  if (!response.ok) {
-    await response.body?.cancel();
-    throw new Error(`CLIProxyAPI media request failed (HTTP ${response.status}).`);
+  try {
+    await transport.onResponse?.({ status: response.status, headers: response.headers });
+  } catch (error) {
+    await response.body?.cancel().catch(() => {});
+    throw error;
   }
   const reader = response.body?.getReader();
+  if (!response.ok) {
+    const detail = reader ? await errorDetail(reader, key) : "";
+    throw new Error(
+      `CLIProxyAPI media request failed (HTTP ${response.status})${detail ? `: ${detail}` : "."}`,
+    );
+  }
   if (!reader) throw new Error("CLIProxyAPI media returned an empty response.");
   try {
+    if (onPartial) return await readEvents(reader, maxBytes, onPartial);
     const chunks: Uint8Array[] = [];
     let size = 0;
     while (true) {
       const chunk = await reader.read();
-      if (chunk.done) break;
+      if (chunk.done || !chunk.value) break;
       size += chunk.value.byteLength;
       if (size > maxBytes) {
         await reader.cancel();
@@ -404,6 +577,7 @@ async function mediaRequest(
     const result: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
     return result;
   } catch {
+    void reader.cancel().catch(() => {});
     throw new Error(
       "CLIProxyAPI media response is invalid, incomplete, cancelled, or exceeds the response size limit.",
     );
@@ -553,12 +727,199 @@ function parseGoogleImages(value: unknown) {
   return images;
 }
 
+// OpenAI reports image token usage. Costs use list prices and stay zero for unpriced models.
+function imageUsage(model: string, value: unknown) {
+  const tokens = (field: unknown) =>
+    typeof field === "number" && Number.isSafeInteger(field) && field >= 0 ? field : undefined;
+  if (!isRecord(value)) return undefined;
+  const input = tokens(value.input_tokens);
+  const output = tokens(value.output_tokens);
+  if (input === undefined || output === undefined) return undefined;
+  const imageInput = Math.min(
+    input,
+    tokens(isRecord(value.input_tokens_details) ? value.input_tokens_details.image_tokens : 0) ?? 0,
+  );
+  const [textPrice, imagePrice, outputPrice] = mediaCapability(model)?.price ?? [0, 0, 0];
+  const cost = {
+    input: ((input - imageInput) * textPrice + imageInput * imagePrice) / 1e6,
+    output: (output * outputPrice) / 1e6,
+    cacheRead: 0,
+    cacheWrite: 0,
+    total: 0,
+  };
+  cost.total = cost.input + cost.output;
+  const usage: Usage = { input, output, cacheRead: 0, cacheWrite: 0, totalTokens: input + output, cost };
+  return usage;
+}
+
+// Shared by the image tool and Pi's native image interface.
+async function requestImages(
+  config: Config,
+  key: string,
+  model: string,
+  request: {
+    prompt: string;
+    output: Partial<ReturnType<typeof mediaOutputOptions>>;
+    images?: { image_url: string }[];
+    mask?: { image_url: string };
+  },
+  signal: AbortSignal,
+  onPartial?: (image: ImageContent, index: number) => void,
+  { onPayload, ...transport }: TransportOptions & { onPayload?: (payload: unknown) => unknown } = {},
+) {
+  const route = mediaCapability(model)?.route;
+  const { prompt, images, mask } = request;
+  const { partial_images = 0, ...output } = request.output;
+  const n = output.n ?? 1;
+  const stream = route === "openai" && partial_images > 0;
+  const body =
+    route === "xai"
+      ? {
+          model,
+          prompt,
+          n: 1,
+          response_format: "b64_json",
+          resolution: output.resolution,
+          aspect_ratio: output.aspect_ratio,
+        }
+      : route === "openai"
+        ? { model, prompt, ...output, n, images, mask, ...(stream ? { stream, partial_images } : {}) }
+        : {
+            contents: [{ role: "user", parts: [{ text: prompt }] }],
+            generationConfig: {
+              responseModalities: ["TEXT", "IMAGE"],
+              candidateCount: 1,
+              ...(output.resolution !== undefined || output.aspect_ratio !== undefined
+                ? { imageConfig: { imageSize: output.resolution, aspectRatio: output.aspect_ratio } }
+                : {}),
+            },
+          };
+  const payload = (await onPayload?.(body)) ?? body;
+  const path =
+    route === "gemini"
+      ? `v1beta/models/${model}:generateContent`
+      : images
+        ? "v1/images/edits"
+        : "v1/images/generations";
+  if (!stream) {
+    const result = await mediaRequest(config, key, path, signal, {
+      ...transport,
+      maxBytes: MAX_IMAGE_RESPONSE_BYTES,
+      body: payload,
+      openaiImage: route === "openai",
+    });
+    return {
+      images: route === "gemini" ? parseGoogleImages(result) : parseImages(result, n),
+      usage: route === "openai" && isRecord(result) ? imageUsage(model, result.usage) : undefined,
+    };
+  }
+  // Each frame carries one full image, so the stream may hold the final image plus every preview.
+  const events = await mediaRequest(config, key, path, signal, {
+    ...transport,
+    maxBytes: MAX_IMAGE_RESPONSE_BYTES * (1 + partial_images),
+    body: payload,
+    openaiImage: true,
+    onPartial: (event) => {
+      try {
+        const index = typeof event.partial_image_index === "number" ? event.partial_image_index : 0;
+        onPartial?.(parseImage(event).image, index);
+      } catch {
+        // A malformed preview does not affect the final image.
+      }
+    },
+  });
+  if (!Array.isArray(events)) throw new Error("CLIProxyAPI returned an invalid image stream.");
+  const failed = events.find(
+    (event) => isRecord(event) && (event.type === "error" || event.error !== undefined),
+  );
+  if (failed) {
+    const detail = errorText(failed, key);
+    throw new Error(`CLIProxyAPI image stream failed${detail ? `: ${detail}` : "."}`);
+  }
+  const completed = events.filter(
+    (event) => isRecord(event) && typeof event.type === "string" && event.type.endsWith(".completed"),
+  );
+  if (completed.length !== n) throw new Error(`CLIProxyAPI image stream must complete ${n} image(s).`);
+  return { images: completed.map(parseImage), usage: imageUsage(model, completed[0].usage) };
+}
+
+export async function generateNativeImages(
+  config: Config,
+  model: ImageModel<ImageApi>,
+  context: ImagesContext,
+  options?: ImagesOptions,
+) {
+  const result: AssistantImages = {
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    output: [],
+    stopReason: "stop",
+    timestamp: Date.now(),
+  };
+  try {
+    const capability = mediaCapability(model.id);
+    if (capability?.purpose !== "image" || capability.disabledReason)
+      throw new Error(capability?.disabledReason ?? "Choose a supported CLIProxyAPI image model.");
+    const prompt = context.input.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("\n\n");
+    if (!prompt.trim() || (capability.route === "openai" && prompt.length > 32000))
+      throw new Error(
+        "CLIProxyAPI requires a non-empty prompt; OpenAI prompts are limited to 32000 characters.",
+      );
+    const limits = mediaControls(model.id).editing;
+    const blocks = context.input.flatMap((block) => (block.type === "image" ? [block] : []));
+    let total = 0;
+    const images = blocks.map(({ data }) => {
+      const bytes = Buffer.from(data, "base64");
+      total += bytes.length;
+      if (
+        !limits ||
+        blocks.length > limits.max_images ||
+        bytes.length > limits.max_file_bytes ||
+        total > limits.max_total_bytes
+      )
+        throw new Error(
+          "CLIProxyAPI image inputs need an OpenAI image model: at most 16 images, 14 MiB each, 20 MiB total.",
+        );
+      let mimeType: string;
+      try {
+        ({ mimeType } = imageType(bytes));
+      } catch {
+        throw new Error("CLIProxyAPI image inputs must be PNG, JPEG, or WebP.");
+      }
+      return { image_url: `data:${mimeType};base64,${bytes.toString("base64")}` };
+    });
+    const generated = await requestImages(
+      config,
+      validateKey(options?.apiKey ?? ""),
+      model.id,
+      { prompt, output: {}, ...(images.length ? { images } : {}) },
+      deadline(options?.signal, capability.route === "openai" ? 600000 : 180000),
+      undefined,
+      {
+        fetch: options?.fetch,
+        headers: options?.headers,
+        env: options?.env,
+        onPayload: options?.onPayload && ((payload) => options.onPayload?.(payload, model)),
+        onResponse: options?.onResponse && ((response) => options.onResponse?.(response, model)),
+      },
+    );
+    result.output = generated.images.map(({ image }) => image);
+    result.usage = generated.usage;
+  } catch (error) {
+    result.stopReason = options?.signal?.aborted ? "aborted" : "error";
+    result.errorMessage = error instanceof Error ? error.message : String(error);
+  }
+  return result;
+}
+
 export async function generateImage(
   config: Config,
   params: Static<typeof imageParameters>,
   ctx: MediaContext,
   signal?: AbortSignal,
   onProgress?: (text: string) => void,
+  onPartial?: (image: ImageContent, index: number) => void,
 ) {
   const model = resolveMediaModel(config, ctx, "image", params.model);
   const route = mediaCapability(model)?.route;
@@ -577,40 +938,14 @@ export async function generateImage(
   bounded.throwIfAborted();
   onProgress?.(inputs.images ? "Editing image..." : "Generating image...");
   bounded.throwIfAborted();
-  const result = await mediaRequest(
+  const { images, usage } = await requestImages(
     config,
     key,
-    route === "gemini"
-      ? `v1beta/models/${model}:generateContent`
-      : inputs.images
-        ? "v1/images/edits"
-        : "v1/images/generations",
+    model,
+    { prompt: params.prompt, output, ...inputs },
     bounded,
-    32 * 1024 * 1024,
-    route === "xai"
-      ? {
-          model,
-          prompt: params.prompt,
-          n: 1,
-          response_format: "b64_json",
-          resolution: output.resolution,
-          aspect_ratio: output.aspect_ratio,
-        }
-      : route === "openai"
-        ? { model, prompt: params.prompt, ...output, n: output.n ?? 1, ...inputs }
-        : {
-            contents: [{ role: "user", parts: [{ text: params.prompt }] }],
-            generationConfig: {
-              responseModalities: ["TEXT", "IMAGE"],
-              candidateCount: 1,
-              ...(output.resolution !== undefined || output.aspect_ratio !== undefined
-                ? { imageConfig: { imageSize: output.resolution, aspectRatio: output.aspect_ratio } }
-                : {}),
-            },
-          },
-    route === "openai",
+    onPartial,
   );
-  const images = route === "gemini" ? parseGoogleImages(result) : parseImages(result, output.n ?? 1);
   bounded.throwIfAborted();
   onProgress?.("Saving image...");
   bounded.throwIfAborted();
@@ -647,7 +982,7 @@ export async function generateImage(
       previewBudget -= image.data.length;
     }
   }
-  return { content, details: { model, files } };
+  return { content, details: { model, files }, usage };
 }
 
 function requestId(value: unknown) {
@@ -675,12 +1010,15 @@ export async function generateVideo(
   const output = mediaOutputOptions(model, params);
   const bounded = deadline(signal, 60000);
   const key = await generationKey(config, { ...params, model }, ctx, bounded);
-  const result = await mediaRequest(config, key, "v1/videos", bounded, 64 * 1024, {
-    model,
-    prompt: params.prompt,
-    duration: params.duration,
-    resolution: output.resolution,
-    aspect_ratio: output.aspect_ratio,
+  const result = await mediaRequest(config, key, "v1/videos", bounded, {
+    maxBytes: 64 * 1024,
+    body: {
+      model,
+      prompt: params.prompt,
+      duration: params.duration,
+      resolution: output.resolution,
+      aspect_ratio: output.aspect_ratio,
+    },
   });
   if (!isRecord(result)) throw new Error("CLIProxyAPI returned an invalid video submission.");
   return { model, request_id: requestId(result.request_id), status: "pending" };
@@ -690,7 +1028,7 @@ export async function videoStatus(config: Config, id: string, ctx: MediaContext,
   const request_id = requestId(id);
   const bounded = deadline(signal, 15000);
   const key = await mediaKey(ctx, bounded);
-  const result = await mediaRequest(config, key, `v1/videos/${request_id}`, bounded, 64 * 1024);
+  const result = await mediaRequest(config, key, `v1/videos/${request_id}`, bounded, { maxBytes: 64 * 1024 });
   if (!isRecord(result)) throw new Error("CLIProxyAPI returned an invalid video status.");
   if (result.status === "pending") return { request_id, status: "pending" };
   if (result.status === "failed" || result.status === "expired") {
@@ -739,15 +1077,32 @@ export function registerMediaTools(pi: ExtensionAPI, config: Config) {
     name: "cliproxyapi_generate_image",
     label: "CLIProxyAPI image",
     description:
-      "Generate images, or edit local images with OpenAI models by supplying images and an optional mask. Supports OpenAI size, quality, background, format/compression and image count from cliproxyapi_media_models. Uses the selected model or automatic OpenAI/GPT default without changing chat. Saves final images under a new .pi/ directory with optional previews. Maximum response: 32 MiB; inline base64: 4 MiB. No automatic retries.",
+      "Generate images, or edit local images with OpenAI models by supplying images and an optional mask. Supports OpenAI size, quality, background, format/compression, image count and streamed partial previews from cliproxyapi_media_models. Uses the selected model or automatic OpenAI/GPT default without changing chat. Saves final images under a new .pi/ directory with optional previews. Maximum response: 32 MiB in total, plus 32 MiB per streamed preview; inline base64: 4 MiB. No automatic retries.",
     promptSnippet: "Generate requested raster images through CLIProxyAPI using the effective image default.",
     promptGuidelines: [
       "Use cliproxyapi_generate_image for requested raster images. Omit model to use the effective default unless a specific image model is requested; keep the current chat model.",
     ],
     parameters: imageParameters,
     async execute(_id, params, signal, onUpdate, ctx) {
-      return generateImage(config, params, ctx, signal, (text) =>
-        onUpdate?.({ content: [{ type: "text", text }], details: {} }),
+      return generateImage(
+        config,
+        params,
+        ctx,
+        signal,
+        (text) => onUpdate?.({ content: [{ type: "text", text }], details: {} }),
+        (image, index) => {
+          const large = image.data.length > MAX_INLINE_IMAGE_BASE64_BYTES;
+          onUpdate?.({
+            content: [
+              {
+                type: "text",
+                text: `Partial image ${index + 1}${large ? " (preview over 4 MiB omitted)" : ""}`,
+              },
+              ...(large ? [] : [image]),
+            ],
+            details: {},
+          });
+        },
       );
     },
   });

package/src/picker.ts

@@ -7,8 +7,8 @@ import {
   type TuiMouseEvent,
   truncateToWidth,
 } from "@earendil-works/pi-tui";
-import { backendLabel, mediaCapability, parseCatalog, routedName } from "./catalog.ts";
-import type { Config } from "./config.ts";
+import { backendLabel, fetchCatalog, mediaCapability, parseCatalog, routedName } from "./catalog.ts";
+import { type Config, deadline } from "./config.ts";
 import { mediaKey } from "./media.ts";
 import {
   effectiveMediaDefaults,
@@ -16,7 +16,6 @@ import {
   type MediaDefaults,
   readMediaDefaults,
 } from "./media-defaults.ts";
-import { deadline, fetchCatalog } from "./provider.ts";
 
 export function pickerCatalog(value: unknown) {
   const rows = new Map<

package/src/provider.ts

@@ -18,10 +18,19 @@ import {
   openAIResponsesApi,
 } from "@earendil-works/pi-ai/compat";
 import { getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
-import { type CpaApi, endpoint, mapCatalog, modelRoute } from "./catalog.ts";
+import {
+  type CpaApi,
+  endpoint,
+  fetchCatalog,
+  IMAGE_API,
+  mapCatalog,
+  mapImageModels,
+  modelRoute,
+} from "./catalog.ts";
 import { type QuotaWaitHandler, waitForClaudeQuota } from "./claude-quota.ts";
 import { withCompactionRecovery } from "./compaction.ts";
-import { type Config, isRecord, PROVIDER_ID } from "./config.ts";
+import { type Config, isRecord, PROVIDER_ID, validateKey } from "./config.ts";
+import { generateNativeImages } from "./media.ts";
 
 export type { QuotaWaitHandler } from "./claude-quota.ts";
 
@@ -31,63 +40,21 @@ export function builtinCatalog() {
     ...getBuiltinModels("openai"),
     ...getBuiltinModels("openai-codex"),
     ...getBuiltinModels("google"),
+    ...getBuiltinModels("xai"),
   ];
 }
 
-export function validateKey(key: string) {
-  if (!/^[!-~]{1,4096}$/.test(key)) {
-    throw new Error("CLIProxyAPI requires a non-empty API key without whitespace or control characters.");
-  }
-  return key;
-}
-
-export function deadline(signal: AbortSignal | undefined, milliseconds: number) {
-  return AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(milliseconds)]);
-}
-
-export async function fetchCatalog(config: Config, key: string, signal: AbortSignal) {
-  validateKey(key);
-  const boundedSignal = deadline(signal, 10000);
-  let response: Response;
-  try {
-    response = await fetch(`${config.baseUrl}/v1/models`, {
-      headers: { Authorization: `Bearer ${key}` },
-      redirect: "error",
-      signal: boundedSignal,
-    });
-  } catch {
-    signal.throwIfAborted();
-    throw new Error("CLIProxyAPI discovery failed: connection, timeout, or redirect error.");
-  }
-  if (!response.ok) {
-    await response.body?.cancel();
-    throw new Error(`CLIProxyAPI discovery failed (HTTP ${response.status}).`);
-  }
-  let payload: unknown;
-  const reader = response.body?.getReader();
-  if (!reader) throw new Error("CLIProxyAPI discovery returned an empty response.");
-  try {
-    const decoder = new TextDecoder();
-    let text = "";
-    let size = 0;
-    while (true) {
-      const chunk = await reader.read();
-      if (chunk.done) break;
-      size += chunk.value.byteLength;
-      if (size > 4 * 1024 * 1024) {
-        await reader.cancel();
-        throw new Error("Catalog too large.");
-      }
-      text += decoder.decode(chunk.value, { stream: true });
-    }
-    payload = JSON.parse(text + decoder.decode());
-  } catch {
-    signal.throwIfAborted();
-    throw new Error("CLIProxyAPI catalog is invalid, incomplete, or larger than 4 MiB.");
-  } finally {
-    reader.releaseLock();
-  }
-  return payload;
+// Pi's live catalogs add models released after this Pi build; bundled metadata wins for known IDs.
+export function metadataCatalog(live?: (provider: string) => readonly Model<Api>[] | undefined) {
+  const bundled = builtinCatalog();
+  if (!live) return bundled;
+  const ids = new Set(bundled.map(({ provider, id }) => `${provider}/${id}`));
+  return [
+    ...bundled,
+    ...["anthropic", "openai", "openai-codex", "google", "xai"]
+      .flatMap((provider) => live(provider) ?? [])
+      .filter(({ provider, id }) => !ids.has(`${provider}/${id}`)),
+  ];
 }
 
 export async function discover(
@@ -345,10 +312,12 @@ function route(
 
 export function createCliproxyProvider(
   config: Config,
-  known: readonly Model<Api>[] = builtinCatalog(),
+  known: readonly Model<Api>[] | (() => readonly Model<Api>[]) = builtinCatalog,
   onQuotaWait?: QuotaWaitHandler,
   compactionSignals = new WeakSet<AbortSignal>(),
 ) {
+  const metadata = typeof known === "function" ? known : () => known;
+  let skipped: string[] = [];
   const standardAuth = envApiKeyAuth("CLIProxyAPI API key", ["CLIPROXYAPI_API_KEY"]);
   const scope = createHash("sha256")
     .update(JSON.stringify([5, { baseUrl: config.baseUrl, aliases: config.aliases }]))
@@ -364,7 +333,7 @@ export function createCliproxyProvider(
           const credential = await standardAuth.login?.(interaction);
           if (!credential?.key) throw new Error("CLIProxyAPI requires an API key.");
           validateKey(credential.key);
-          await discover(config, credential.key, interaction.signal, known);
+          await discover(config, credential.key, interaction.signal, metadata());
           return credential;
         },
         async resolve(input) {
@@ -380,7 +349,15 @@ export function createCliproxyProvider(
       if (context.credential?.type !== "api_key" || !context.credential.key) {
         throw new Error("Use /login cliproxyapi or set CLIPROXYAPI_API_KEY before refreshing.");
       }
-      return (await discover(config, context.credential.key, context.signal, known)).models;
+      const payload = await fetchCatalog(config, context.credential.key, context.signal);
+      const chat = mapCatalog(payload, config, metadata());
+      skipped = chat.skipped;
+      return [...chat.models, ...mapImageModels(payload, config)];
+    },
+    images: {
+      [IMAGE_API]: {
+        generateImages: (model, context, options) => generateNativeImages(config, model, context, options),
+      },
     },
     api: {
       "anthropic-messages": route(anthropicMessagesApi(), config, compactionSignals, onQuotaWait),
@@ -392,6 +369,8 @@ export function createCliproxyProvider(
   const refresh = provider.refreshModels;
   return {
     ...provider,
+    // Chat IDs without Pi metadata from the latest network refresh, for diagnostics.
+    skippedModels: () => skipped,
     async refreshModels(context: RefreshModelsContext) {
       await refresh?.({
         ...context,