@pi-unipi/unipi 2.2.7 → 2.4.0

package/CHANGELOG.md

@@ -6,6 +6,67 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.4.0] — 2026-08-09
+
+Image generation no longer requires an OpenRouter account, and `image_generate` can now edit an existing image.
+
+### Added
+
+- **`image`: image editing.** `image_generate` takes an optional `image` argument — a file path, `data:` URL, or raw base64 — and edits that image instead of generating from scratch. The result is saved and returned like any other generation.
+
+  Editing regenerates the whole image rather than masking a region, so details you did not mention can still shift. Which model you pick matters a lot here: in testing, `flux.2-pro` preserved unmentioned elements faithfully, while the `gemini-*-image` family tended to reinterpret the whole scene. Note also that image models respond to what you *describe*, not to what you negate — "no text" is as likely to add text as remove it.
+
+### Changed
+
+- **`image`: generation works with any OpenAI-compatible provider configured in pi.** Previously pi-ai shipped exactly one image provider (`openrouter`), so generating an image meant holding an OpenRouter key even when you had several other providers signed in. Every provider in pi's model registry is now bridged into pi-ai's images collection at session start, backed by a single generic adapter that posts to `{baseUrl}/images/generations`.
+
+  Credentials come from pi's existing auth — there is no separate image login. Gateways disagree on the response shape, so three known forms are normalized (`b64_json` + `media_type`, `b64_json` + `revised_prompt`, and a `data:` URL under `url`); a remote `url` is surfaced as text rather than silently dropped.
+
+  Model *discovery* remains heuristic. pi's `ProviderModelConfig` has no `output` field and the provider composer rebuilds each model from a fixed field list, so an extension cannot record "this model emits images" — hence the name-based matching, with an explicit `provider/model-id` always accepted as the escape hatch.
+
+- **`image`: errors name the provider you are actually using.** A missing key now points at that provider's environment variable and `/login` instead of unconditionally linking OpenRouter, and an unusable provider reports "no image-generation route" rather than the misleading "cannot generate images".
+
+### Fixed
+
+- **`image`: a valid API key could be reported as missing.** pi-ai resolves credentials to an `AuthResult` — `{ auth: { apiKey } }` — but the key was read from the top level, so generation failed with "No API key for provider" while a perfectly good credential sat one level down. Both shapes are now accepted.
+
+- **`image`: models discovered from the registry lost their endpoint.** Provider registration rebuilt each model from a field list that omitted `baseUrl`, so setup appeared to succeed and only the first real request failed with "No baseUrl for image model". The endpoint is now carried through discovery, and filled in from the registry at resolve time for hand-typed `provider/model-id` references, which never carry one.
+
+## [2.3.0] — 2026-08-07
+
+Startup went from **23.1s to 0.75s** — 31× faster, and within ~0.7s of bare `pi` with no extensions at all. A cold start (empty cache) is now the same speed as a warm one.
+
+### Changed
+
+- **`info-screen`: `showOnBoot` is now `bootMode`, with three states.** `"on"` keeps the dashboard up until you dismiss it, `"auto-close"` (the new default) closes it after `bootTimeoutMs`, and `"off"` never builds it at all. All three are configurable from `/unipi:info-settings` — `←/→` cycles the mode, and the row below adjusts the delay in 0.5s steps (clamped 0.5–30s). Any keypress cancels the auto-close, so the dashboard stays put if you are reading it. `/unipi:info` opened by hand never auto-closes.
+
+  Existing configs migrate automatically on read: `showOnBoot: true` → `"on"`, `false` → `"off"`. Note that `true` maps to `"on"` rather than the new `"auto-close"` default, so nobody's startup behaviour changes underneath them. An explicit `bootMode` always wins over the legacy key.
+
+- **`info-screen`: dashboard panels load lazily.** Only the visible tab fetches at boot; the rest are prefetched 1.5s later, and any tab opened before that fetches on demand. Previously all ~17 panels were built before the first prompt was ready, including when the dashboard was disabled entirely.
+
+- **`memory`: orphaned markdown is imported on first use rather than at startup.** `syncOrphanedFiles()` spawns a Python bridge; nothing reads its result until memory is actually used. A `.md` file dropped into a project directory is now picked up by the first memory tool call instead of at boot. Still runs exactly once per session; nothing is lost.
+
+- **`unipi`: the all-in-one entry now ships as a prebuilt bundle.** pi loads extensions through jiti with its module cache disabled, so every startup transpiled ~577 TypeScript files from scratch — the factory calls themselves take 5ms, the cost was entirely transpilation. `pi.extensions` points at `packages/unipi/bundled.js`, built by `npm run build` and regenerated automatically by `prepublishOnly`. Only `@pi-unipi` sources are bundled; every third-party dependency stays external and resolves from `node_modules` at runtime.
+
+### Performance
+
+- **`info-screen`: usage stats are cached per file (8,671ms → 70ms).** `parseUsageStats()` re-read and re-parsed the entire session history on every call — 2.6GB across 600 JSONL files — and ran twice per startup. Results are now cached in `~/.unipi/cache/usage-stats.json`, keyed on each file's mtime and size. Statting 600 files costs ~1ms while only ~11 change on a busy day, so ~96% of the work was recomputing an immutable result.
+
+  This single function was the dominant startup cost. Because it never yielded, every other extension's `session_start` handler queued behind it — which is why earlier profiling rounds blamed unrelated extensions for ~9s each. They were waiting on this, not doing work.
+
+- **`info-screen`: the usage parser no longer blocks the event loop.** A new `parseUsageStatsAsync()` yields via `setImmediate` between files, so even a cold parse cannot freeze keystrokes or the first paint. The reader also streams line-by-line instead of `readFileSync` — the largest single session file here is 213MB and was being materialized in full, along with its `split("\n")` array.
+
+- **`memory`: MemPalace bridge calls are async (1,581ms → ~0ms of blocked loop).** The status-bar counts called `listAll()` and the cross-project listing through `spawnSync`, freezing the process for the full Python round-trip just to render `mem 32p/2262all`. Added `runBridgeAsync` plus `listAllAsync()` / `listAllProjectsCachedAsync()`; the status bar paints immediately and fills in when the bridge answers. The cross-project listing is additionally cached for 60s, invalidated on any store or delete.
+
+- **`info-screen`/`utility`: pi's version is resolved without spawning a subprocess (710ms → ~1ms).** `getPiVersion()` probed a hardcoded path for one specific Node version and, on any other, fell through to `execSync("pi --version")` — starting a whole second pi process, synchronously, twice per startup. A shared implementation in `@pi-unipi/core` now walks up from pi's own entry point, resolving the symlink first (the binary on `PATH` is typically a shim), and caches the result.
+
+### Fixed
+
+- `info-screen`: the overview panel displayed **`Pi Version: unknown`**. The `execSync` fallback matched `/v([\d.]+)/`, requiring a literal `v` prefix that pi no longer emits — so it paid 710ms per startup *and* still failed. Now shows the real version.
+- `info-screen`: `bootTimeoutMs` had existed in `InfoScreenSettings` and in user configs since the beginning but was never connected to anything. It now drives the auto-close timer.
+- `info-screen`: `writeSettingsFile()` called `require()` from an ESM module, which throws under Node's module-format detection whenever the settings directory does not already exist.
+- `unipi`: `diff` is a dependency of `@pi-unipi/utility` and lives in that package's own `node_modules`. That resolves fine under jiti (each file resolves from its own location) and fine when installed (npm hoists it), but was unresolvable from a single bundle in a local checkout. Now declared at the root.
+
 ## [2.2.7] — 2026-08-04
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.2.7",
+  "version": "2.4.0",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -23,9 +23,12 @@
     "packages/*"
   ],
   "scripts": {
-    "typecheck": "npx tsc --noEmit --skipLibCheck",
+    "build": "node scripts/build-bundle.mjs",
+    "prepare": "node scripts/build-bundle.mjs --if-missing",
+    "prepublishOnly": "npm run build",
+    "publish:all": "npm publish --workspaces --access public",
     "test": "npx tsx --test tests/*.test.js && npm test --workspaces --if-present",
-    "publish:all": "npm publish --workspaces --access public"
+    "typecheck": "npx tsc --noEmit --skipLibCheck"
   },
   "files": [
     "CHANGELOG.md",
@@ -37,11 +40,12 @@
     "packages/*/tui/*",
     "packages/*/SKILL.md",
     "packages/*/skills/**/*",
-    "packages/*/README.md"
+    "packages/*/README.md",
+    "packages/unipi/bundled.js"
   ],
   "pi": {
     "extensions": [
-      "packages/unipi/index.ts"
+      "packages/unipi/bundled.js"
     ],
     "skills": [
       "packages/workflow/skills",
@@ -67,26 +71,26 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "2.2.0",
-    "@pi-unipi/btw": "2.2.0",
-    "@pi-unipi/compactor": "2.2.1",
-    "@pi-unipi/notify": "2.2.2",
-    "@pi-unipi/command-enchantment": "2.2.0",
-    "@pi-unipi/core": "2.2.0",
-    "@pi-unipi/info-screen": "2.2.1",
-    "@pi-unipi/mcp": "2.2.0",
-    "@pi-unipi/memory": "2.2.1",
-    "@pi-unipi/ralph": "2.2.1",
-    "@pi-unipi/subagents": "2.2.1",
-    "@pi-unipi/utility": "2.2.0",
-    "@pi-unipi/milestone": "2.2.0",
-    "@pi-unipi/kanboard": "2.2.0",
-    "@pi-unipi/web-api": "2.2.0",
-    "@pi-unipi/workflow": "2.2.0",
-    "@pi-unipi/footer": "2.2.1",
-    "@pi-unipi/updater": "2.2.1",
-    "@pi-unipi/input-shortcuts": "2.2.0",
-    "@pi-unipi/cocoindex": "2.2.0"
+    "@pi-unipi/ask-user": "2.4.0",
+    "@pi-unipi/btw": "2.4.0",
+    "@pi-unipi/compactor": "2.4.0",
+    "@pi-unipi/notify": "2.4.0",
+    "@pi-unipi/command-enchantment": "2.4.0",
+    "@pi-unipi/core": "2.4.0",
+    "@pi-unipi/info-screen": "2.4.0",
+    "@pi-unipi/mcp": "2.4.0",
+    "@pi-unipi/memory": "2.4.0",
+    "@pi-unipi/ralph": "2.4.0",
+    "@pi-unipi/subagents": "2.4.0",
+    "@pi-unipi/utility": "2.4.0",
+    "@pi-unipi/milestone": "2.4.0",
+    "@pi-unipi/kanboard": "2.4.0",
+    "@pi-unipi/web-api": "2.4.0",
+    "@pi-unipi/workflow": "2.4.0",
+    "@pi-unipi/footer": "2.4.0",
+    "@pi-unipi/updater": "2.4.0",
+    "@pi-unipi/input-shortcuts": "2.4.0",
+    "@pi-unipi/cocoindex": "2.4.0"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.80.0",
@@ -94,6 +98,8 @@
     "@earendil-works/pi-coding-agent": "^0.80.0",
     "@earendil-works/pi-tui": "^0.80.0",
     "@types/node": "^25.6.0",
+    "diff": "^7.0.0",
+    "esbuild": "^0.27.7",
     "tsx": "^4.21.0",
     "typescript": "^6.0.0"
   }

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.2.0"
+    "@pi-unipi/core": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",

package/packages/btw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
   "type": "module",
   "main": "extensions/btw.ts",
@@ -37,7 +37,7 @@
     "@earendil-works/pi-tui": "^0.80.0"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.2.0"
+    "@pi-unipi/core": "2.4.0"
   },
   "pi": {
     "extensions": [],

package/packages/cocoindex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/cocoindex",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "CocoIndex integration for Pi — AST-aware content indexing, semantic vector search, and incremental pipeline management",
   "type": "module",
   "main": "index.ts",
@@ -25,7 +25,7 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.2.0"
+    "@pi-unipi/core": "2.4.0"
   },
   "optionalDependencies": {
     "@lancedb/lancedb": "^0.21.0"

package/packages/compactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
   "type": "module",
   "main": "src/index.ts",
@@ -34,8 +34,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.2.0",
-    "@pi-unipi/info-screen": "2.2.1",
+    "@pi-unipi/core": "2.4.0",
+    "@pi-unipi/info-screen": "2.4.0",
     "@earendil-works/pi-agent-core": "^0.80.0"
   },
   "peerDependencies": {

package/packages/compactor/src/info-screen.ts

@@ -12,7 +12,7 @@
 
 import type { SessionDB } from "./session/db.js";
 import { getLastCompactionStats } from "./compaction/hooks.js";
-import { parseUsageStats } from "@pi-unipi/info-screen/usage-parser.js";
+import { parseUsageStatsAsync } from "@pi-unipi/info-screen/usage-parser.js";
 import type { RuntimeCounters } from "./types.js";
 
 export interface CompactorInfoData {
@@ -42,9 +42,9 @@ function formatCost(n: number): string {
 }
 
 /** Estimate cost per token for the most-used model in the current session. */
-function estimateCostPerToken(): number | null {
+async function estimateCostPerToken(): Promise<number | null> {
   try {
-    const usage = parseUsageStats();
+    const usage = await parseUsageStatsAsync();
     // Use today's most-used model if available, otherwise all-time
     const models = usage.byModelToday;
     const todayKeys = Object.keys(models);
@@ -154,7 +154,7 @@ export async function getInfoScreenData(
       : "No tool calls yet";
 
     // ── Cost saved estimate ──
-    const costPerToken = estimateCostPerToken();
+    const costPerToken = await estimateCostPerToken();
     const costSaved = costPerToken !== null ? tokensSaved * costPerToken : null;
 
     // ── Last compaction details ──

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/core/utils.ts

@@ -187,6 +187,43 @@ export function getInstalledPackageVersion(startDir: string, packageName: string
   return getPackageVersion(root);
 }
 
+/** Cached pi version — resolved at most once per process. */
+let cachedPiVersion: string | null = null;
+
+/**
+ * Get the running Pi agent's version.
+ *
+ * Resolves by walking up from Pi's own entry point (`process.argv[1]`), which
+ * must be `realpath`'d first: the executable on PATH is typically a symlink
+ * (e.g. mise shims `~/.local/share/mise/installs/node/lts/bin/pi`), and the
+ * package.json lives next to the *real* `dist/cli.js`, not the link.
+ *
+ * Never spawns a subprocess. A previous implementation fell back to
+ * `execSync("pi --version")`, which cost ~350ms per call and still returned
+ * "unknown" because it matched against a `v` prefix that Pi no longer emits.
+ */
+export function getPiVersion(): string {
+  if (cachedPiVersion !== null) return cachedPiVersion;
+
+  const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+  const entry = process.argv[1];
+  if (entry) {
+    try {
+      const realEntry = fs.realpathSync(entry);
+      const root = findPackageRoot(path.dirname(realEntry), PI_PACKAGE);
+      if (root) {
+        cachedPiVersion = getPackageVersion(root);
+        return cachedPiVersion;
+      }
+    } catch {
+      // Fall through to "unknown".
+    }
+  }
+
+  cachedPiVersion = "unknown";
+  return cachedPiVersion;
+}
+
 /**
  * Check if a module is available in node_modules.
  */

package/packages/footer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "main": "src/index.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.2.0"
+    "@pi-unipi/core": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/image",
-  "version": "2.2.5",
+  "version": "2.4.0",
   "description": "Image generation and image recognition tools for the Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.2.0"
+    "@pi-unipi/core": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.80.0",

package/packages/image/src/generate.ts

@@ -131,6 +131,8 @@ export interface GenerateOptions {
   signal?: AbortSignal;
   /** Absolute directory for saved images; omit to skip saving. */
   outputDir?: string;
+  /** Source image; when set the request is an edit rather than a generation. */
+  inputImage?: { data: string; mimeType: string };
   now?: Date;
   /** Injected images collection, for tests. */
   images?: ImagesModelsLike;
@@ -141,7 +143,7 @@ export interface GenerateOptions {
  * @throws {Error} with an actionable message when generation fails.
  */
 export async function generateImage(options: GenerateOptions): Promise<GenerateResult> {
-  const { prompt, model, signal, outputDir, now } = options;
+  const { prompt, model, signal, outputDir, now, inputImage } = options;
 
   if (!prompt.trim()) {
     throw new Error("A non-empty prompt is required.");
@@ -154,19 +156,19 @@ export async function generateImage(options: GenerateOptions): Promise<GenerateR
     );
   }
 
-  // pi-ai's images collection carries its own provider set (currently only
-  // `openrouter`) and is entirely separate from pi's chat model registry.
-  // A chat provider registered by another extension can therefore list image
-  // models that generation cannot actually drive — pi-ai answers with a bare
-  // "Unknown provider: x". Detect that here and say something useful.
+  // pi-ai's images collection has its own provider set, separate from pi's
+  // chat registry. `registerRegistryImageProviders()` bridges pi's providers
+  // in, but a model may still name a provider with no image route at all —
+  // pi-ai would answer with a bare "Unknown provider: x", so say something
+  // useful instead.
   if (!providerCanGenerate(imagesApi, model.provider)) {
     const supported = supportedProviders(imagesApi);
     throw new Error(
-      `Provider "${model.provider}" cannot generate images.\n` +
-        `→ Image generation is served by: ${supported.join(", ") || "openrouter"}.\n` +
-        `→ "${model.provider}" is a chat provider; its image models are listed for ` +
-        `recognition and reference, but generation must go through a supported provider.\n` +
-        "→ Pick one with /unipi:image-settings.",
+      `Provider "${model.provider}" has no image-generation route.\n` +
+        `→ Available: ${supported.join(", ") || "openrouter"}.\n` +
+        "→ Providers are bridged from pi automatically; one without a baseUrl " +
+        "or an API key cannot be used.\n" +
+        "→ Pick another with /unipi:image-settings.",
     );
   }
 
@@ -174,7 +176,13 @@ export async function generateImage(options: GenerateOptions): Promise<GenerateR
   // a bare OPENROUTER_API_KEY still works.
   let apiKey: string | undefined;
   try {
-    apiKey = (await imagesApi.getAuth(model))?.apiKey;
+    // pi-ai resolves to an `AuthResult`, i.e. `{ auth: { apiKey } }`. Older
+    // shapes put the key at the top level, so accept both — reading only one
+    // fails silently and looks like a missing credential.
+    const resolvedAuth = (await imagesApi.getAuth(model)) as
+      | { apiKey?: string; auth?: { apiKey?: string } }
+      | undefined;
+    apiKey = resolvedAuth?.auth?.apiKey ?? resolvedAuth?.apiKey;
   } catch {
     // Reported as a missing key below.
   }
@@ -183,14 +191,25 @@ export async function generateImage(options: GenerateOptions): Promise<GenerateR
   if (!apiKey) {
     throw new Error(
       `No API key for provider "${model.provider}".\n` +
-        `→ Add one with /login, or set the provider's API key environment variable.\n` +
-        `→ Image models are served through OpenRouter: https://openrouter.ai/keys`,
+        "→ Sign in with /login, or set the provider's API key environment variable.\n" +
+        `→ Expected environment variable: ` +
+        `${model.provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`,
     );
   }
 
+  const input: Array<{ type: string; text?: string; data?: string; mimeType?: string }> =
+    [{ type: "text", text: prompt }];
+  if (inputImage) {
+    input.push({
+      type: "image",
+      data: inputImage.data,
+      mimeType: inputImage.mimeType,
+    });
+  }
+
   const result = (await imagesApi.generateImages(
     model,
-    { input: [{ type: "text", text: prompt }] },
+    { input } as { input: Array<{ type: string; text?: string }> },
     { apiKey, ...(signal ? { signal } : {}) },
   )) as AssistantImagesLike;
 

package/packages/image/src/index.ts

@@ -21,6 +21,7 @@ import {
 import { registerImageCommands } from "./commands.js";
 import { registerImageTools } from "./tools.js";
 import { listImageGenModels, listVisionModels, type ChatModelRegistry } from "./models.js";
+import { registerRegistryImageProviders } from "./register-providers.js";
 import { loadConfig } from "./settings.js";
 
 const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
@@ -43,6 +44,13 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     const config = loadConfig();
 
+    // Bridge pi's configured providers into pi-ai's images collection up front,
+    // so the settings picker and the info screen see them without a prior
+    // image_generate call. Best-effort: never block session start.
+    void registerRegistryImageProviders(
+      (ctx as unknown as { modelRegistry?: ChatModelRegistry }).modelRegistry,
+    ).catch(() => undefined);
+
     const tools: string[] = [];
     if (config.generate.enabled) tools.push(IMAGE_TOOLS.GENERATE);
     if (config.recognize.enabled) tools.push(IMAGE_TOOLS.RECOGNIZE);

package/packages/image/src/models.ts

@@ -211,12 +211,40 @@ export function listRegistryImageGenModels(
       provider: candidate.provider,
       name: candidate.name,
       api: candidate.api ?? "",
+      // Carry the endpoint through. The generic images adapter POSTs to
+      // `{baseUrl}/images/generations`, and this is the only place the
+      // registry's baseUrl is available — dropping it here surfaces later as
+      // "No baseUrl for image model ..." once generation is attempted.
+      ...(candidate.baseUrl ? { baseUrl: candidate.baseUrl } : {}),
       ...(candidate.output ? { output: candidate.output } : {}),
     });
   }
   return out;
 }
 
+/**
+ * Find a provider's API endpoint in pi's registry.
+ *
+ * Needed because a model can reach generation without one: a user-typed
+ * "provider/model-id" is accepted at face value by `asExplicitModelRef`, and
+ * carries no baseUrl of its own.
+ */
+export function findProviderBaseUrl(
+  registry: ChatModelRegistry | undefined,
+  provider: string,
+): string | undefined {
+  if (!registry) return undefined;
+  try {
+    const models = (registry.getAvailable?.() ?? registry.getAll()) as Array<{
+      provider?: string;
+      baseUrl?: string;
+    }>;
+    return models.find((m) => m?.provider === provider && m.baseUrl)?.baseUrl;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Every selectable generation model: pi-ai's built-in catalog plus anything
  * contributed by registered providers, de-duplicated by "provider/id".