pi-custom-provider-model 0.1.2 → 0.1.3

package/README.md

@@ -16,6 +16,7 @@ Published on npm as [`pi-custom-provider-model`](https://www.npmjs.com/package/p
 - Save provider/model definitions to `models.json`, API keys through Pi's native `auth.json` handling, and startup defaults to `settings.json`.
 - Preserve existing unknown settings/model overrides and JSON comments when editing; detect stale writes and retain the last 10 `models.json` backups.
 - Show credential source without returning saved keys or headers to the browser.
+- Optionally route images through an authenticated vision-capable fallback model while keeping the selected Pi model responsible for the main reasoning and tool loop.
 
 ## Install
 
@@ -93,6 +94,12 @@ The extension uses Pi's `getAgentDir()`, including `PI_CODING_AGENT_DIR`. It doe
 6. Use **Test chat** for a quick streaming check, or **Check capabilities** for chat, tools, reasoning and image input. Progress and results appear directly under that model; **Stop tests** cancels the remaining work.
 7. Click **Save provider**, then select it in Pi's `/model` picker. **Set default** applies to future Pi launches.
 
+### Vision fallback
+
+Choose an authenticated image-capable model under **Vision fallback** and click **Save fallback**. When the active Pi model is text-only, the extension sends attached user images and images returned by tools to that fallback model for description. It then gives the description—not the image—to the active model, which remains selected and performs the main reasoning and tool loop.
+
+Fallback is bypassed when the active model already declares image input. If fallback analysis fails, a direct image prompt is stopped rather than silently dropping the image; a tool image is replaced with an explicit failure note. The fallback makes an additional model request and may incur provider usage/cost. Configuration is stored separately in `<agentDir>/pi-custom-provider.json`; native `models.json`, `auth.json`, and `settings.json` formats are not extended.
+
 ### Base URL examples
 
 | Protocol | Base URL | Model list | Chat |
@@ -163,6 +170,8 @@ Provider-scoped API keys use Pi's public `ModelRuntime.login()` / `logout()` and
 
 Replacing a credential with provider-scoped `env` settings is currently refused to avoid losing that advanced state through Pi's login replacement behavior. Use Pi's native auth configuration for those entries. Deleting a provider retains its key; remove the key first if desired. Removing an `auth.json` key does not remove a fallback key from `models.json` or the environment.
 
+Vision fallback selection lives in `<agentDir>/pi-custom-provider.json`. The file contains only provider/model IDs, never credentials.
+
 Backups live in `<agentDir>/provider-manager-backups/`. To restore, stop the panel and copy the desired backup over `models.json`, then reopen `/model`. Backups can contain pre-existing secrets from models.json and are created with owner-only permissions where supported. Only `models.json` is backed up; authentication and defaults use Pi's own writers. A partial save reports which operation needs attention.
 
 ## Development and verification

package/docs/design.md

@@ -1,6 +1,6 @@
 # v0.1 design and reference map
 
-Status: local prototype. Pi compatibility baseline: 0.85.1. Package name/scope and public repository have not been chosen. `private: true` prevents accidental publication while retaining local/git installation and tarball inspection.
+Status: published as `pi-custom-provider-model`. Pi compatibility baseline: 0.85.1. Tagged releases are published through GitHub Actions.
 
 ## Official Pi sources (version pinned)
 
@@ -32,6 +32,7 @@ API discovery complements Pi's documentation with [OpenAI Models](https://develo
 - API keys go through the public ModelRuntime login/logout interface using its native authPath-backed credential store. This keeps key interpolation and locking in Pi itself. No imports of private AuthStorage internals. API-key replacement follows Pi's /login semantics; unrelated providers and OAuth entries are preserved.
 - All configuration updates merge into the latest document under lock, check revisions, keep unknown fields/comments, and back up models.json. Conflicting external edits return a conflict instead of replacing the latest version. Native OAuth entries remain managed by Pi /login.
 - Existing built-in provider overrides are displayed read-only in v0.1. Manage custom provider definitions here.
+- Optional vision fallback is extension-owned configuration in `<agentDir>/pi-custom-provider.json`, not a non-native model/settings field. For a text-only active model, user images are transformed into a fallback model's textual description before the main agent starts; images from tool results are similarly replaced and nested usage is attached to that tool result. The active model remains selected. Native vision models bypass fallback, and direct prompts fail closed instead of silently dropping images when fallback fails.
 
 ## Components
 
@@ -51,4 +52,4 @@ Bind to 127.0.0.1 on a random port. A session token in the URL fragment is excha
 
 ## Publication checklist
 
-Choose an available npm scope/name and repository; add repository metadata and changelog; verify Windows and CI on Linux/macOS; run tests and inspect npm pack; remove private only for an intentional public release. Include the prebuilt web assets (this prototype needs no frontend build). Gallery indexing uses npm's pi-package keyword; listing timing is outside this project's control.
+Run `npm run verify` and `npm run pack:check`, update the committed package version, then push the matching `v*` tag. GitHub Actions validates the tag/version match and publishes to npm. Include the prebuilt web assets (there is no frontend build). Gallery indexing uses npm's `pi-package` keyword; listing timing is outside this project's control.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-custom-provider-model",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A local browser-based custom provider and API-key manager for Pi.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { getAgentDir, VERSION, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { startManager } from "./server.ts";
+import { transformToolImages, transformUserImages } from "./vision-fallback.ts";
 
 function openBrowser(url: string) {
   const [program, args] = process.platform === "win32"
@@ -35,6 +36,8 @@ export default function (pi: ExtensionAPI) {
   pi.on("agent_settled", async (_event, ctx) => {
     if (pendingModelSync) await syncActiveModel(ctx);
   });
+  pi.on("input", async (event, ctx) => transformUserImages(getAgentDir(), event, ctx));
+  pi.on("tool_result", async (event, ctx) => transformToolImages(getAgentDir(), event, ctx));
   pi.registerCommand("custom-provider", {
     description: "Manage custom providers, API keys and models in a local browser",
     handler: async (args, ctx) => {

package/src/server.ts

@@ -63,7 +63,7 @@ export async function startManager(dir: string, onSaved?: () => Promise<void>) {
       const controller = new AbortController();
       response.on("close", () => { if (!response.writableEnded) controller.abort(); });
       const signal = AbortSignal.any([controller.signal, lifecycle.signal]);
-      const writes = ["/api/save", "/api/delete", "/api/remove-key", "/api/default"];
+      const writes = ["/api/save", "/api/delete", "/api/remove-key", "/api/default", "/api/vision-fallback"];
       const isWrite = writes.includes(path);
       if (isWrite && mutationPending) throw new AppError("Another save is in progress. Try again.", 409);
       if (isWrite) mutationPending = true;
@@ -79,6 +79,7 @@ export async function startManager(dir: string, onSaved?: () => Promise<void>) {
           case "/api/delete": result = await service.remove(input.id, input.revision); break;
           case "/api/remove-key": result = await service.removeKey(input.id); break;
           case "/api/default": result = await service.setDefault(input.id, input.modelId); break;
+          case "/api/vision-fallback": result = await service.setVisionFallback(input.provider, input.modelId, input.revision); break;
           default: throw new AppError("Not found.", 404);
         }
         json(response, 200, result);

package/src/service.ts

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ModelRuntime, readStoredCredential, SettingsManager, VERSION } from "@earendil-works/pi-coding-agent";
-import { ConfigStore, parseDocument, patch, readText } from "./storage.ts";
+import { ConfigStore, ExtensionConfigStore, parseDocument, patch, readText } from "./storage.ts";
 import { discover, endpointUrls, requestHeaders } from "./discovery.ts";
 import { CAPABILITIES, probeModel, type Capability } from "./probes.ts";
 import { LimitCatalog, LIMIT_FIELDS } from "./limits.ts";
@@ -24,9 +24,13 @@ function visibleModel(model: JsonObject): ModelInput {
 
 export class ProviderService {
   readonly store: ConfigStore;
+  readonly extensionStore: ExtensionConfigStore;
   private reserved: Set<string> = new Set();
   private limitCatalog = new LimitCatalog();
-  constructor(readonly dir: string, private onSaved?: () => Promise<void>) { this.store = new ConfigStore(dir); }
+  constructor(readonly dir: string, private onSaved?: () => Promise<void>) {
+    this.store = new ConfigStore(dir);
+    this.extensionStore = new ExtensionConfigStore(dir);
+  }
 
   private async runtime() {
     return ModelRuntime.create({ authPath: join(this.dir, "auth.json"), modelsPath: this.store.path, refreshOnCreate: false });
@@ -39,7 +43,13 @@ export class ProviderService {
 
   async state() {
     const current = await this.store.read();
+    const extension = await this.extensionStore.read();
     const settings = parseDocument(await readText(join(this.dir, "settings.json")));
+    const runtime = await this.runtime();
+    const available = await runtime.getAvailable();
+    const visionModels = available.filter((model) => model.input.includes("image")).map((model) => ({
+      provider: model.provider, id: model.id, name: model.name,
+    })).sort((a, b) => `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`));
     const providers = Object.entries(current.data.providers).map(([id, entry]) => {
       const p = entry as JsonObject;
       const credential = readStoredCredential(id, join(this.dir, "auth.json"));
@@ -56,6 +66,7 @@ export class ProviderService {
     return {
       dir: this.dir, piVersion: VERSION, managerVersion: MANAGER_VERSION, revision: current.revision, providers,
       defaultProvider: settings.defaultProvider ?? "", defaultModel: settings.defaultModel ?? "",
+      visionFallback: extension.data.visionFallback ?? null, visionFallbackRevision: extension.revision, visionModels,
       reservedIds: [...this.reserved],
     };
   }
@@ -197,6 +208,29 @@ export class ProviderService {
     return { ok: true, state: await this.state() };
   }
 
+  async setVisionFallback(providerInput: unknown, modelInput: unknown, expected: unknown) {
+    if (typeof expected !== "string") throw new AppError("Reload fallback configuration before saving.", 409);
+    const disabled = (providerInput === "" || providerInput === null || providerInput === undefined)
+      && (modelInput === "" || modelInput === null || modelInput === undefined);
+    let value: { provider: string; model: string } | undefined;
+    if (!disabled) {
+      if (typeof providerInput !== "string" || !providerInput.trim() || providerInput.length > 100
+          || typeof modelInput !== "string" || !modelInput.trim() || modelInput.length > 300) {
+        throw new AppError("Choose a valid fallback vision model.");
+      }
+      const provider = providerInput.trim(); const modelId = modelInput.trim();
+      const runtime = await this.runtime();
+      const model = runtime.getModel(provider, modelId);
+      const available = await runtime.getAvailable(provider);
+      if (!model || !model.input.includes("image") || !available.some((entry) => entry.id === modelId)) {
+        throw new AppError("The fallback model must support images and have configured credentials.");
+      }
+      value = { provider, model: modelId };
+    }
+    await this.extensionStore.saveVisionFallback(expected, value);
+    return { ok: true, state: await this.state() };
+  }
+
   async setDefault(idInput: unknown, modelId: unknown) {
     const id = validateId(idInput);
     const runtime = await this.runtime();

package/src/storage.ts

@@ -33,7 +33,7 @@ export async function readText(path: string, fallback = "{}\n"): Promise<string>
   catch (error: any) { if (error.code === "ENOENT") return fallback; throw error; }
 }
 
-async function atomicWrite(path: string, content: string): Promise<void> {
+export async function atomicWrite(path: string, content: string): Promise<void> {
   const temporary = `${path}.${randomUUID()}.tmp`;
   try {
     await writeFile(temporary, content, { encoding: "utf8", mode: 0o600 });
@@ -41,6 +41,29 @@ async function atomicWrite(path: string, content: string): Promise<void> {
   } finally { await unlink(temporary).catch(() => {}); }
 }
 
+export class ExtensionConfigStore {
+  readonly path: string;
+  constructor(readonly dir: string) { this.path = join(dir, "pi-custom-provider.json"); }
+
+  async read() {
+    const text = await readText(this.path, "{}\n");
+    return { text, data: parseDocument(text), revision: revision(text) };
+  }
+
+  async saveVisionFallback(expected: string, value: { provider: string; model: string } | undefined) {
+    await mkdir(this.dir, { recursive: true });
+    const release = await lockfile.lock(this.path, { realpath: false, retries: { retries: 20, minTimeout: 20, maxTimeout: 100 } });
+    try {
+      const current = await this.read();
+      if (current.revision !== expected) throw new AppError("Fallback configuration changed in another window. Reload before saving.", 409);
+      const next = patch(current.text, ["visionFallback"], value);
+      parseDocument(next);
+      if (next !== current.text) await atomicWrite(this.path, next);
+      return revision(next);
+    } finally { await release(); }
+  }
+}
+
 export class ConfigStore {
   readonly path: string;
   constructor(readonly dir: string) { this.path = join(dir, "models.json"); }

package/src/vision-fallback.ts

@@ -0,0 +1,88 @@
+import { join } from "node:path";
+import type { AssistantMessage, ImageContent, Model, TextContent, Usage } from "@earendil-works/pi-ai";
+import type { ExtensionContext, InputEventResult } from "@earendil-works/pi-coding-agent";
+import { parseDocument, readText } from "./storage.ts";
+
+export interface VisionFallbackConfig { provider: string; model: string }
+
+const SYSTEM_PROMPT = `You are a visual inspection component for a coding agent. Describe every supplied image accurately and concretely. Preserve visible text, errors, labels, UI layout, charts, code, file contents, spatial relationships, and details relevant to the user's request. Do not solve the broader task or claim actions. Return only a concise but sufficiently detailed description.`;
+
+export async function readVisionFallback(dir: string): Promise<VisionFallbackConfig | undefined> {
+  const data = parseDocument(await readText(join(dir, "pi-custom-provider.json")));
+  const value = data.visionFallback;
+  if (!value || typeof value.provider !== "string" || typeof value.model !== "string") return;
+  if (!value.provider.trim() || !value.model.trim()) return;
+  return { provider: value.provider, model: value.model };
+}
+
+function textOf(message: AssistantMessage): string {
+  return message.content.filter((block): block is TextContent => block.type === "text").map((block) => block.text).join("\n").trim();
+}
+
+function sumUsage(items: Usage[]): Usage {
+  const total: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+  for (const usage of items) {
+    total.input += usage.input; total.output += usage.output; total.cacheRead += usage.cacheRead; total.cacheWrite += usage.cacheWrite;
+    total.totalTokens += usage.totalTokens; total.cost.input += usage.cost.input; total.cost.output += usage.cost.output;
+    total.cost.cacheRead += usage.cost.cacheRead; total.cost.cacheWrite += usage.cost.cacheWrite; total.cost.total += usage.cost.total;
+    if (usage.reasoning !== undefined) total.reasoning = (total.reasoning ?? 0) + usage.reasoning;
+    if (usage.cacheWrite1h !== undefined) total.cacheWrite1h = (total.cacheWrite1h ?? 0) + usage.cacheWrite1h;
+  }
+  return total;
+}
+
+function assertFallbackModel(ctx: ExtensionContext, config: VisionFallbackConfig): Model<any> {
+  const model = ctx.modelRegistry.find(config.provider, config.model);
+  if (!model) throw new Error(`Vision fallback model ${config.provider}/${config.model} is unavailable.`);
+  if (!model.input.includes("image")) throw new Error(`Vision fallback model ${config.provider}/${config.model} is not configured for image input.`);
+  return model;
+}
+
+async function describeImages(ctx: ExtensionContext, config: VisionFallbackConfig, images: ImageContent[], request: string, signal?: AbortSignal) {
+  const model = assertFallbackModel(ctx, config);
+  const timeout = AbortSignal.any([AbortSignal.timeout(60000), ...(signal ? [signal] : [])]);
+  const response = await ctx.modelRegistry.complete(model, { systemPrompt: SYSTEM_PROMPT, messages: [{ role: "user", timestamp: Date.now(), content: [
+    { type: "text", text: `User request/context: ${request || "No additional text."}\nDescribe the attached image(s) for another model that cannot see them. Distinguish multiple images by order.` },
+    ...images,
+  ] }] }, { signal: timeout, maxTokens: Math.min(model.maxTokens, 2048), cacheRetention: "none", maxRetries: 0, timeoutMs: 60000 });
+  if (response.stopReason === "error" || response.stopReason === "aborted") throw new Error("The fallback vision model could not analyze the image.");
+  const description = textOf(response);
+  if (!description) throw new Error("The fallback vision model returned no image description.");
+  return { description, usage: response.usage, model: `${model.provider}/${model.id}` };
+}
+
+export async function transformUserImages(dir: string, event: { text: string; images?: ImageContent[] }, ctx: ExtensionContext): Promise<InputEventResult | void> {
+  if (!event.images?.length || !ctx.model || ctx.model.input.includes("image")) return;
+  const config = await readVisionFallback(dir);
+  if (!config) return;
+  try {
+    ctx.ui.setWorkingMessage(`Analyzing image with ${config.provider}/${config.model}…`);
+    const result = await describeImages(ctx, config, event.images, event.text, ctx.signal);
+    ctx.ui.notify(`Image analyzed with ${result.model}; continuing with ${ctx.model.provider}/${ctx.model.id}.`, "info");
+    return { action: "transform", text: `${event.text}\n\n[Vision fallback analysis from ${result.model}]\n${result.description}`, images: [] };
+  } catch (error) {
+    ctx.ui.notify(`${error instanceof Error ? error.message : "Vision fallback failed."} The prompt was stopped so the image is not silently omitted.`, "error");
+    return { action: "handled" };
+  } finally { ctx.ui.setWorkingMessage(); }
+}
+
+export async function transformToolImages(dir: string, event: { content: (TextContent | ImageContent)[]; usage?: Usage }, ctx: ExtensionContext): Promise<{ content?: (TextContent | ImageContent)[]; usage?: Usage } | void> {
+  const images = event.content.filter((block): block is ImageContent => block.type === "image");
+  if (!images.length || !ctx.model || ctx.model.input.includes("image")) return;
+  const config = await readVisionFallback(dir);
+  if (!config) return;
+  const originalText = event.content.filter((block): block is TextContent => block.type === "text").map((block) => block.text).join("\n");
+  try {
+    const result = await describeImages(ctx, config, images, originalText || "Image returned by a tool.", ctx.signal);
+    return { content: [
+      ...event.content.filter((block): block is TextContent => block.type === "text"),
+      { type: "text", text: `[Vision fallback analysis from ${result.model}]\n${result.description}` },
+    ], usage: sumUsage([...(event.usage ? [event.usage] : []), result.usage]) };
+  } catch (error) {
+    return { content: [
+      ...event.content.filter((block): block is TextContent => block.type === "text"),
+      { type: "text", text: `[Vision fallback failed: ${error instanceof Error ? error.message : "unknown error"}]` },
+    ] };
+  }
+}

package/web/app.js

@@ -1,10 +1,10 @@
 const $ = (id) => document.getElementById(id);
 const translations = {
   id: {
-    local:"Workspace lokal",providers:"Provider",addProvider:"+ Tambah provider",configuration:"KONFIGURASI",docs:"Dokumentasi resmi Pi ↗",connections:"KONEKSI",subtitle:"Endpoint dan model pilihanmu. Konfigurasi asli Pi.",refresh:"Muat ulang konfigurasi",connection:"Koneksi",native:"Format Pi",readonly:"Provider ini dikelola Pi atau integrasi lain. Buat provider custom untuk mengedit di sini.",defaultProviderBadge:"Default Pi",defaultProviderNote:"Provider ini adalah default Pi dan belum dapat dihapus. Untuk menghapusnya, buka provider lain lalu pilih ‘Jadikan default’ pada salah satu modelnya.",defaultActionHelp:"‘Jadikan default’ pada Aksi model menetapkan model dan provider tersebut sebagai default Pi untuk pembukaan berikutnya.",providerId:"ID provider",idHelp:"Nama unik di Pi, misalnya my-gateway.",protocol:"Protokol API",protocolHelp:"Pilih protokol yang didukung endpoint.",requestPreview:"PREVIEW REQUEST",credentialSource:"SUMBER KREDENSIAL",removeKey:"Hapus key tersimpan",bearer:"Tambahkan header Authorization: Bearer secara eksplisit (Pi authHeader)",advanced:"Field lanjutan dan header custom yang sudah ada dipertahankan. Override per model dapat mengubah request efektif.",testConnection:"Tes koneksi",fetchModels:"Tarik model ↗",testHint:"Memeriksa daftar model. Tanpa request generasi.",models:"Model",addModel:"+ Model manual",modelHint:"Pilih model untuk disimpan. ID yang terdaftar belum menjamin dukungan chat, vision, atau tools.",selectAll:"Pilih yang terlihat",modelId:"ID model",context:"Konteks",input:"Input",actions:"Aksi",noModels:"Hubungkan model pertamamu",noModelsHint:"Tarik model dari endpoint atau tambahkan ID secara manual.",saveHelp:"Model → models.json · Key → auth.json",deleteProvider:"Hapus provider",save:"Simpan provider",footnote:"Konfigurasi disimpan lokal. Buka /model di Pi untuk memilih model. Default berlaku saat Pi dibuka kembali.",editModel:"Pengaturan model",displayName:"Nama tampilan (opsional)",maxOutput:"Maksimal token output",vision:"Input gambar",reasoning:"Dukungan reasoning",defaultText:"Default Pi (teks)",defaultOff:"Default Pi (nonaktif)",textOnly:"Teks saja",textImage:"Teks + gambar",off:"Nonaktif",on:"Aktif",metadataHelp:"Biarkan nilai yang belum diketahui memakai default Pi. Mengaktifkan opsi tidak menambahkan kemampuan pada model upstream.",applyModel:"Terapkan pengaturan",newProvider:"Provider baru",selected:"dipilih",edit:"Edit",test:"Tes",setDefault:"Jadikan default",default:"Default",remove:"Hapus",unsaved:"Ada perubahan yang belum disimpan. Lanjutkan?",keyHelp:"Kosongkan untuk mempertahankan key. Key baru disimpan di auth.json.",openaiHelp:"URL asli Pi. Biasanya diakhiri /v1; SDK menambahkan /chat/completions atau /responses.",anthropicHelp:"URL asli Pi. Biasanya tanpa /v1 di akhir; SDK menambahkan /v1/messages. Prefix gateway seperti /anthropic tetap dipakai.",busy:"Sedang memproses…",saved:"Provider tersimpan. Buka /model di Pi untuk memilihnya.",confirmDelete:"Hapus konfigurasi provider ini? Kredensialnya tetap tersimpan.",confirmKey:"Hapus key provider dari auth.json? Sumber key lain tetap dapat dipakai Pi.",confirmTest:"Kirim prompt singkat ke model ini? Tes memakai token, tanpa mengirim file atau percakapan proyek.",defaultSaved:"Default tersimpan untuk sesi Pi berikutnya.",fetchDone:"Daftar model diterima",allFetched:"Semua halaman yang dilaporkan endpoint telah diambil.",removeModel:"Hapus model ini dari pilihan? Perubahan berlaku setelah disimpan.",missingToken:"Buka manager dari link yang ditampilkan Pi.",search:"Cari ID model…",noProviders:"Belum ada provider custom.",saveFirst:"Simpan provider dahulu.",duplicate:"ID model sudah ada.",fallback:"default Pi",keyRemoved:"Key di auth.json dihapus.",working:"Bekerja",connectionOk:"Endpoint daftar model merespons.",refreshDone:"Konfigurasi dimuat ulang.",defaultHelp:"Berlaku saat Pi dibuka kembali.",partial:"Sebagian hasil",matches:"terlihat",
+    local:"Workspace lokal",providers:"Provider",addProvider:"+ Tambah provider",configuration:"KONFIGURASI",docs:"Dokumentasi resmi Pi ↗",connections:"KONEKSI",subtitle:"Endpoint dan model pilihanmu. Konfigurasi asli Pi.",refresh:"Muat ulang konfigurasi",visionFallback:"Fallback vision",globalSetting:"Pengaturan global",visionFallbackHelp:"Ketika model Pi yang aktif tidak dapat menerima gambar, model ini akan mendeskripsikan gambar dari pengguna dan tool terlebih dahulu. Model aktif tetap dipilih dan melakukan reasoning utama.",visionFallbackModel:"Model vision fallback",visionFallbackOff:"Nonaktif",visionFallbackCredentialHelp:"Hanya model dengan dukungan gambar dan kredensial yang terkonfigurasi yang ditampilkan.",saveVisionFallback:"Simpan fallback",visionFallbackSaved:"Pengaturan vision fallback tersimpan.",connection:"Koneksi",native:"Format Pi",readonly:"Provider ini dikelola Pi atau integrasi lain. Buat provider custom untuk mengedit di sini.",defaultProviderBadge:"Default Pi",defaultProviderNote:"Provider ini adalah default Pi dan belum dapat dihapus. Untuk menghapusnya, buka provider lain lalu pilih ‘Jadikan default’ pada salah satu modelnya.",defaultActionHelp:"‘Jadikan default’ pada Aksi model menetapkan model dan provider tersebut sebagai default Pi untuk pembukaan berikutnya.",providerId:"ID provider",idHelp:"Nama unik di Pi, misalnya my-gateway.",protocol:"Protokol API",protocolHelp:"Pilih protokol yang didukung endpoint.",requestPreview:"PREVIEW REQUEST",credentialSource:"SUMBER KREDENSIAL",removeKey:"Hapus key tersimpan",bearer:"Tambahkan header Authorization: Bearer secara eksplisit (Pi authHeader)",advanced:"Field lanjutan dan header custom yang sudah ada dipertahankan. Override per model dapat mengubah request efektif.",testConnection:"Tes koneksi",fetchModels:"Tarik model ↗",testHint:"Memeriksa daftar model. Tanpa request generasi.",models:"Model",addModel:"+ Model manual",modelHint:"Pilih model untuk disimpan. ID yang terdaftar belum menjamin dukungan chat, vision, atau tools.",selectAll:"Pilih yang terlihat",modelId:"ID model",context:"Konteks",input:"Input",actions:"Aksi",noModels:"Hubungkan model pertamamu",noModelsHint:"Tarik model dari endpoint atau tambahkan ID secara manual.",saveHelp:"Model → models.json · Key → auth.json",deleteProvider:"Hapus provider",save:"Simpan provider",footnote:"Konfigurasi disimpan lokal. Buka /model di Pi untuk memilih model. Default berlaku saat Pi dibuka kembali.",editModel:"Pengaturan model",displayName:"Nama tampilan (opsional)",maxOutput:"Maksimal token output",vision:"Input gambar",reasoning:"Dukungan reasoning",defaultText:"Default Pi (teks)",defaultOff:"Default Pi (nonaktif)",textOnly:"Teks saja",textImage:"Teks + gambar",off:"Nonaktif",on:"Aktif",metadataHelp:"Biarkan nilai yang belum diketahui memakai default Pi. Mengaktifkan opsi tidak menambahkan kemampuan pada model upstream.",applyModel:"Terapkan pengaturan",newProvider:"Provider baru",selected:"dipilih",edit:"Edit",test:"Tes",setDefault:"Jadikan default",default:"Default",remove:"Hapus",unsaved:"Ada perubahan yang belum disimpan. Lanjutkan?",keyHelp:"Kosongkan untuk mempertahankan key. Key baru disimpan di auth.json.",openaiHelp:"URL asli Pi. Biasanya diakhiri /v1; SDK menambahkan /chat/completions atau /responses.",anthropicHelp:"URL asli Pi. Biasanya tanpa /v1 di akhir; SDK menambahkan /v1/messages. Prefix gateway seperti /anthropic tetap dipakai.",busy:"Sedang memproses…",saved:"Provider tersimpan. Buka /model di Pi untuk memilihnya.",confirmDelete:"Hapus konfigurasi provider ini? Kredensialnya tetap tersimpan.",confirmKey:"Hapus key provider dari auth.json? Sumber key lain tetap dapat dipakai Pi.",confirmTest:"Kirim prompt singkat ke model ini? Tes memakai token, tanpa mengirim file atau percakapan proyek.",defaultSaved:"Default tersimpan untuk sesi Pi berikutnya.",fetchDone:"Daftar model diterima",allFetched:"Semua halaman yang dilaporkan endpoint telah diambil.",removeModel:"Hapus model ini dari pilihan? Perubahan berlaku setelah disimpan.",missingToken:"Buka manager dari link yang ditampilkan Pi.",search:"Cari ID model…",noProviders:"Belum ada provider custom.",saveFirst:"Simpan provider dahulu.",duplicate:"ID model sudah ada.",fallback:"default Pi",keyRemoved:"Key di auth.json dihapus.",working:"Bekerja",connectionOk:"Endpoint daftar model merespons.",refreshDone:"Konfigurasi dimuat ulang.",defaultHelp:"Berlaku saat Pi dibuka kembali.",partial:"Sebagian hasil",matches:"terlihat",
   },
   en: {
-    newProvider:"New provider",selected:"selected",edit:"Edit",test:"Test",setDefault:"Set default",default:"Default",defaultProviderBadge:"Pi default",defaultProviderNote:"This provider is Pi's default and cannot be deleted yet. To delete it, open another provider and choose ‘Set default’ on one of its models.",defaultActionHelp:"‘Set default’ in a model's Actions makes that model and provider Pi's default for new launches.",remove:"Remove",unsaved:"You have unsaved changes. Continue?",keyHelp:"Leave blank to keep the current key. New keys are stored in auth.json.",openaiHelp:"Pi-native URL. Usually ends in /v1; the SDK appends /chat/completions or /responses.",anthropicHelp:"Pi-native URL. Usually no trailing /v1; the SDK appends /v1/messages. Gateway prefixes such as /anthropic are preserved.",busy:"Working…",saved:"Provider saved. Open /model in Pi to select it.",confirmDelete:"Delete this provider configuration? Its credentials will be kept.",confirmKey:"Remove this provider's key from auth.json? Pi may still use other configured key sources.",confirmTest:"Send a short prompt to this model? This uses tokens, but sends no project files or chat history.",defaultSaved:"Default saved for new Pi launches.",fetchDone:"Model list received",allFetched:"All pages reported by the endpoint have been fetched.",removeModel:"Remove this model from the selection? Changes take effect after saving.",missingToken:"Open the manager using the link printed by Pi.",search:"Search model IDs…",noProviders:"No custom providers yet.",saveFirst:"Save the provider first.",duplicate:"This model ID already exists.",fallback:"Pi default",keyRemoved:"Saved key removed from auth.json.",working:"Working",connectionOk:"Model-list endpoint responded.",refreshDone:"Configuration reloaded.",defaultHelp:"Applies to new Pi launches.",partial:"Partial results",matches:"visible",
+    visionFallback:"Vision fallback",globalSetting:"Global setting",visionFallbackHelp:"When the active Pi model cannot accept images, this model describes user and tool images first. The active model remains selected and performs the main reasoning.",visionFallbackModel:"Fallback vision model",visionFallbackOff:"Disabled",visionFallbackCredentialHelp:"Only image-capable models with configured credentials are listed.",saveVisionFallback:"Save fallback",visionFallbackSaved:"Vision fallback setting saved.",newProvider:"New provider",selected:"selected",edit:"Edit",test:"Test",setDefault:"Set default",default:"Default",defaultProviderBadge:"Pi default",defaultProviderNote:"This provider is Pi's default and cannot be deleted yet. To delete it, open another provider and choose ‘Set default’ on one of its models.",defaultActionHelp:"‘Set default’ in a model's Actions makes that model and provider Pi's default for new launches.",remove:"Remove",unsaved:"You have unsaved changes. Continue?",keyHelp:"Leave blank to keep the current key. New keys are stored in auth.json.",openaiHelp:"Pi-native URL. Usually ends in /v1; the SDK appends /chat/completions or /responses.",anthropicHelp:"Pi-native URL. Usually no trailing /v1; the SDK appends /v1/messages. Gateway prefixes such as /anthropic are preserved.",busy:"Working…",saved:"Provider saved. Open /model in Pi to select it.",confirmDelete:"Delete this provider configuration? Its credentials will be kept.",confirmKey:"Remove this provider's key from auth.json? Pi may still use other configured key sources.",confirmTest:"Send a short prompt to this model? This uses tokens, but sends no project files or chat history.",defaultSaved:"Default saved for new Pi launches.",fetchDone:"Model list received",allFetched:"All pages reported by the endpoint have been fetched.",removeModel:"Remove this model from the selection? Changes take effect after saving.",missingToken:"Open the manager using the link printed by Pi.",search:"Search model IDs…",noProviders:"No custom providers yet.",saveFirst:"Save the provider first.",duplicate:"This model ID already exists.",fallback:"Pi default",keyRemoved:"Saved key removed from auth.json.",working:"Working",connectionOk:"Model-list endpoint responded.",refreshDone:"Configuration reloaded.",defaultHelp:"Applies to new Pi launches.",partial:"Partial results",matches:"visible",
   },
 };
 const original = new Map([...document.querySelectorAll("[data-i18n]")].map((el) => [el, el.textContent]));
@@ -118,7 +118,7 @@ function translate() {
   $("editor-title").textContent = state.id || t("newProvider");
   if (noticeTranslation) $("notice").textContent = t(noticeTranslation);
   if (editingLimits) renderLimitEditor();
-  renderProviders(); renderDefaultProviderNote(); renderModels();
+  renderVisionFallback(); renderProviders(); renderDefaultProviderNote(); renderModels();
 }
 
 async function api(path, data, signal) {
@@ -151,6 +151,7 @@ async function operation(fn, diagnostics = false) {
 
 function setDisabled() {
   document.querySelectorAll("button").forEach((button) => { button.disabled = state.busy; });
+  $("vision-fallback").disabled = state.busy;
   $("connection-fields").disabled = state.busy || state.readOnly;
   $("provider-id").disabled = state.busy || !!state.id || state.readOnly;
   for (const id of ["test-connection", "fetch-models", "add-model", "fill-limits", "save-provider", "delete-provider", "remove-key"]) {
@@ -163,6 +164,19 @@ function setDisabled() {
   if (editingLimits) $("use-model-limits").disabled = !limitFields.some((field) => editingLimits.hints[field]);
 }
 
+function renderVisionFallback() {
+  const select = $("vision-fallback");
+  const selected = state.config?.visionFallback;
+  select.replaceChildren();
+  const off = document.createElement("option"); off.value = ""; off.textContent = t("visionFallbackOff"); select.append(off);
+  for (const model of state.config?.visionModels || []) {
+    const option = document.createElement("option"); option.value = `${model.provider}\n${model.id}`;
+    option.textContent = `${model.provider} / ${model.id}${model.name && model.name !== model.id ? ` — ${model.name}` : ""}`;
+    select.append(option);
+  }
+  select.value = selected ? `${selected.provider}\n${selected.model}` : "";
+}
+
 function renderProviders() {
   const list = $("provider-list"); list.replaceChildren();
   const providers = state.config?.providers || [];
@@ -593,6 +607,13 @@ $("remove-key").onclick = () => {
   if (!state.id || !confirm(t("confirmKey"))) return;
   operation(async () => { const result = await api("remove-key", { id: state.id }); state.config = result.state; loadProvider(state.id); notify(t("keyRemoved")); });
 };
+$("save-vision-fallback").onclick = () => {
+  const [provider = "", modelId = ""] = $("vision-fallback").value.split("\n");
+  operation(async () => {
+    const result = await api("vision-fallback", { provider, modelId, revision: state.config.visionFallbackRevision });
+    state.config = result.state; renderVisionFallback(); notify(t("visionFallbackSaved"));
+  });
+};
 $("refresh-state").onclick = () => {
   if (state.dirty && !confirm(t("unsaved"))) return;
   operation(async () => { state.config = await api("state"); loadProvider(state.id); notify(t("refreshDone")); });

package/web/index.html

@@ -23,6 +23,14 @@
     <main>
       <div class="page-heading"><div><span class="eyebrow" data-i18n="connections">CONNECTIONS</span><h1 id="editor-title">New provider</h1><p data-i18n="subtitle">Your endpoint. Your models. Native Pi configuration.</p></div><button id="refresh-state" class="quiet" data-i18n="refresh">Reload configuration</button></div>
       <div id="notice" role="status" aria-live="polite" hidden></div>
+      <section class="card vision-fallback-card">
+        <div class="section-heading"><div><span class="step">00</span><h2 data-i18n="visionFallback">Vision fallback</h2></div><span class="tag" data-i18n="globalSetting">Global setting</span></div>
+        <p class="hint" data-i18n="visionFallbackHelp">When the active Pi model cannot accept images, this model describes user and tool images first. The active model remains selected and performs the main reasoning.</p>
+        <div class="grid fallback-grid spaced">
+          <label><span data-i18n="visionFallbackModel">Fallback vision model</span><select id="vision-fallback"><option value="" data-i18n="visionFallbackOff">Disabled</option></select><small data-i18n="visionFallbackCredentialHelp">Only image-capable models with configured credentials are listed.</small></label>
+          <div class="fallback-action"><button id="save-vision-fallback" type="button" class="primary" data-i18n="saveVisionFallback">Save fallback</button></div>
+        </div>
+      </section>
       <form id="provider-form">
         <section class="card">
           <div class="section-heading"><div><span class="step">01</span><h2 data-i18n="connection">Connection</h2></div><span class="tag" data-i18n="native">Pi native</span></div>

package/web/style.css

@@ -163,6 +163,9 @@ label small, .hint { color: var(--muted); font-weight: 400; line-height: 1.65; }
 .endpoint-preview b { color: var(--accent); }
 code { font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 1rem; }
 .auth-grid { grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); }
+.fallback-grid { grid-template-columns: minmax(0, 1fr) auto; align-items: end; }
+.fallback-action { padding-bottom: 1px; }
+.fallback-action button { min-width: 160px; }
 .auth-status { display: flex; flex-direction: column; gap: 12px; border-left: 1px solid var(--line); padding: 2px 0 0 24px; align-items: flex-start; overflow-wrap: anywhere; }
 .auth-status button { padding: 4px 0; }
 .checkbox-line { flex-direction: row; align-items: flex-start; gap: 12px; font-weight: 400; line-height: 1.6; }
@@ -252,7 +255,8 @@ dialog .hint { margin: 24px 0; }
   main { padding: 28px 24px; }
   .page-heading { align-items: flex-start; flex-direction: column; }
   .card { padding: 24px; }
-  .two, .auth-grid { grid-template-columns: minmax(0, 1fr); }
+  .two, .auth-grid, .fallback-grid { grid-template-columns: minmax(0, 1fr); }
+  .fallback-action button { width: 100%; }
   .auth-status { border-left: 0; padding-left: 0; }
   .probe-grid { grid-template-columns: minmax(0, 1fr); }
 }