pi-cliproxyapi-native 0.3.1 → 0.3.3

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.3
 ```
 
-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.3`. 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
 
@@ -359,11 +376,17 @@ Run `/reload` after changing settings and `/cliproxyapi-refresh` before starting
 
 ## Protocol notes
 
-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.
+Claude uses the legacy fine-grained tool-streaming header in place of eager tool fields.
+
+GPT models keep Pi's OpenAI Responses capabilities when the proxy lists them as owned by OpenAI. These capabilities are strict tools, grammar tools such as codemode, tool declarations added mid-conversation, tool search, and instructions placed mid-conversation. Each passed live checks through CLIProxyAPI 8.0.48 with an OpenAI API key and with a ChatGPT subscription. OpenAI-compatible providers and other model families keep these capabilities off.
+
+On `api/` routes, Pi can send thinking effort as a `configuration_update` item. ChatGPT subscriptions ignore that item, so unprefixed and `oauth/` routes send the effort as a request field.
+
+When Pi omits strictness in the top-level Responses tool list, the extension sends `strict: null`, so optional arguments remain optional. Tools declared inside the conversation keep Pi's strictness values. 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.3",
   "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)
@@ -243,6 +332,16 @@ export function mapCatalog(value: unknown, config: Config, known: readonly Model
       skipped.add(entry.id);
       continue;
     }
+    // CLIProxyAPI 8.0.48 forwards strict and grammar tools, additional_tools, tool search, and
+    // mid-conversation instructions to OpenAI API keys and ChatGPT subscriptions (live-checked).
+    // Other owners stay conservative. If an OpenAI-compatible provider shares a bare ID, the proxy
+    // lists one owner, and its Chat translator converts these items for that provider.
+    const openai =
+      api === "openai-responses" &&
+      !metadataId.includes("/") &&
+      (!prefix || prefix === "api" || prefix === "oauth") &&
+      (preferred === "openai" || preferred === "openai-codex") &&
+      (reference.provider === "openai" || reference.provider === "openai-codex");
     const model: Model<CpaApi> = {
       ...structuredClone(reference),
       id: entry.id,
@@ -264,15 +363,19 @@ export function mapCatalog(value: unknown, config: Config, known: readonly Model
             }
           : api === "google-generative-ai"
             ? reference.compat
-            : {
-                ...reference.compat,
-                supportsStrictMode: false,
-                supportsMidConvoSystemMessages: false,
-                supportsMidConvoToolAdditions: false,
-                supportsOpenAIGrammarTools: false,
-                supportsToolSearch: false,
-                supportsAdditionalTools: false,
-              },
+            : openai
+              ? // ChatGPT subscriptions ignore configuration_update effort items; only API keys apply them.
+                { ...reference.compat, ...(prefix === "api" ? {} : { supportsMidConvoEffort: false }) }
+              : {
+                  ...reference.compat,
+                  supportsStrictMode: false,
+                  supportsMidConvoSystemMessages: false,
+                  supportsMidConvoToolAdditions: false,
+                  supportsOpenAIGrammarTools: false,
+                  supportsToolSearch: false,
+                  supportsAdditionalTools: false,
+                  supportsMidConvoEffort: false,
+                },
     };
     models.set(model.id, model);
     skipped.delete(model.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 {