privateer-agent 0.12.45 → 0.12.47

package/bin/privateer-subagent.mjs

@@ -55,6 +55,7 @@ export function moatExtensionPaths(repoRoot = REPO, env = process.env) {
     join(repoRoot, "extensions", "privateer-privacy.ts"),
     join(repoRoot, "extensions", "privateer-account.ts"),
     join(repoRoot, "extensions", "privateer-media.ts"),
+    join(repoRoot, "extensions", "privateer-vision.ts"),
   ];
 }
 

package/extensions/privateer-vision.ts

@@ -0,0 +1,39 @@
+// Vision delegation: when the current model can't see images, a vision model on the
+// same provider (same key) describes them, and the description is what gets sent.
+// All the policy — which delegate, why never another provider, what gets rewritten —
+// lives in src/providers/visionDelegate.ts; this file is only the Pi wiring.
+//
+// It hooks `context`, which runs before EVERY LLM call on a per-request copy of the
+// messages, rather than `input`/`tool_result`. That catches images from every source
+// (@file mentions, pasted images, `read`, media and computer tools, MCP results, and
+// history from before a /model switch) while leaving the session's own copy intact.
+// Descriptions are cached by image hash, so each image costs one delegate call per
+// process, not one per turn.
+
+import { describeImagesInMessages, pickVisionDelegate } from "../src/providers/visionDelegate.ts";
+
+export default function privateerVision(pi: any): void {
+  const announced = new Set<string>();
+
+  pi.on("context", async (event: any, ctx: any) => {
+    const model = ctx?.model;
+    const registry = ctx?.modelRegistry;
+    if (!model || !registry) return;
+    const delegate = pickVisionDelegate(model, registry);
+    if (!delegate) return;
+
+    const currentSpec = `${model.provider}/${model.id}`;
+    const delegateSpec = `${delegate.provider}/${delegate.id}`;
+    const messages = await describeImagesInMessages(event.messages, delegate, registry, {
+      currentSpec,
+      signal: ctx.signal,
+      onDescribe: () => {
+        const key = `${currentSpec}→${delegateSpec}`;
+        if (announced.has(key) || !ctx.hasUI) return;
+        announced.add(key);
+        ctx.ui.notify(`${currentSpec} can't see images — ${delegateSpec} will describe them for it.`, "info");
+      },
+    });
+    return messages ? { messages } : undefined;
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.45",
+  "version": "0.12.47",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",

package/patches/@earendil-works+pi-coding-agent+0.86.0.patch

@@ -1025,6 +1025,19 @@ index d101003..540b972 100644
                  return "project";
          }
          return "path";
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/slash-commands.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/slash-commands.js
+index 170a066..b535f72 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/core/slash-commands.js
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/slash-commands.js
+@@ -8,7 +8,7 @@ export const BUILTIN_SLASH_COMMANDS = [
+     { name: "export", description: "Export session (HTML default, or specify path: .html/.jsonl)" },
+     { name: "import", description: "Import and resume a session from a JSONL file" },
+     { name: "share", description: "Share session as a secret GitHub gist" },
+-    { name: "bug", description: "Report a bug to the Pi developers", argumentHint: "<description>" },
++    { name: "bug", description: "Export a bug report to email to Privateer support", argumentHint: "<description>" },
+     { name: "copy", description: "Copy last agent message to clipboard" },
+     { name: "name", description: "Set session display name" },
+     { name: "session", description: "Show session info and stats" },
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/tools/output-accumulator.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/tools/output-accumulator.js
 index 7241668..7b79305 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/tools/output-accumulator.js
@@ -1292,6 +1305,123 @@ index c30d6b8..ad1654a 100644
      ];
      return warnings;
  }
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.d.ts b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.d.ts
+index 7eae594..b21fae3 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.d.ts
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.d.ts
+@@ -8,7 +8,7 @@ interface BugReportContext {
+     showStatus: (message: string) => void;
+     showError: (message: string) => void;
+ }
+-/** Run the `/bug` flow: consent, optional summary, then upload or export. */
++/** Run the `/bug` flow: consent, optional summary, then export a zip to email to support. */
+ export declare function reportBug(context: BugReportContext, initialHint?: string): Promise<void>;
+ export {};
+ //# sourceMappingURL=bug-report.d.ts.map
+
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.js
+index 59ae447..68cf842 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.js
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/bug-report.js
+@@ -1,18 +1,21 @@
+ import * as path from "node:path";
+-import { getAuthCredential } from "../../cli/auth-command.js";
+ import { BUG_REPORT_CUSTOM_ENTRY_TYPE, bugReportArchiveFileName, collectBugReportDiagnostics, collectBugReportMetadata, writeBugReportArchive, } from "../../core/bug-report.js";
+-import { uploadBugReport } from "../../core/bug-report-upload.js";
+ import { clearCrashLog, readCrashLog } from "../../core/crash-log.js";
+-import { getRadiusGatewayUrl, RADIUS_PROVIDER_ID } from "../../core/radius.js";
+ import { serializeSessionBranch } from "../../core/session-export.js";
+ import { BorderedLoader } from "./components/bordered-loader.js";
+ import { ExtensionInputComponent } from "./components/extension-input.js";
+ import { ExtensionSelectorComponent } from "./components/extension-selector.js";
+ import { createShareTrailingEntries } from "./session-share.js";
+ import { theme } from "./theme/theme.js";
+-const DISCLAIMER = "This report goes to the Pi developers (Earendil) and is not shared publicly. It includes your pi version, operating system, the current model and provider configuration (without API keys), loaded extensions, settings, and provider error diagnostics from this session.";
++// Privateer patch: stock Pi's `/bug` uploads this bundle straight to Earendil's Radius
++// Gateway (session transcript, settings, environment) with no Privateer-controlled
++// endpoint in between — not acceptable for a privacy-first tool. We keep the same
++// consent/redaction flow but the only delivery is a local zip the user emails to us
++// themselves, so nothing leaves the machine without them explicitly attaching it.
++const SUPPORT_EMAIL = "support@privateer.pro";
++const DISCLAIMER = `This report is written to a zip file on your machine only — nothing is uploaded automatically. It includes your Privateer version, operating system, the current model and provider configuration (without API keys), loaded extensions, settings, and provider error diagnostics from this session. Email the file to ${SUPPORT_EMAIL} to send it to us.`;
+ const TRANSCRIPT_NOTE = "The transcript contains your messages, model output, tool calls and their results, including file contents and command output read during this session.";
+-/** Run the `/bug` flow: consent, optional summary, then upload or export. */
++/** Run the `/bug` flow: consent, optional summary, then export a zip for the user to email us. */
+ export async function reportBug(context, initialHint) {
+     const options = await promptForOptions(context, initialHint);
+     if (!options) {
+@@ -47,16 +50,6 @@ export async function reportBug(context, initialHint) {
+         context.showError(`Failed to build bug report: ${errorMessage(error)}`);
+         return;
+     }
+-    if (options.delivery === "upload") {
+-        const failure = await upload(context, bundle);
+-        if (failure === undefined)
+-            return;
+-        const fallback = await choose(context, "Upload failed", ["Export as Zip", "Cancel"], `${failure}\n\nExport the report as a zip archive instead?`);
+-        if (fallback !== "Export as Zip") {
+-            context.showStatus("Bug report cancelled");
+-            return;
+-        }
+-    }
+     await exportZip(context, bundle);
+ }
+ async function promptForOptions(context, initialHint) {
+@@ -76,14 +69,13 @@ async function promptForOptions(context, initialHint) {
+         includeSummary = summary !== "No";
+     }
+     const description = hint.trim();
+-    const delivery = await choose(context, "Bug report", ["Upload Report", "Export as Zip", "Cancel"], `Description: ${description || "none"}\nTranscript: ${includeSession ? "included" : "not included"}\nSummary: ${includeSummary ? `written by ${context.session.model?.name ?? "the current model"}` : "none"}\n\nUpload sends the report to ${new URL(getRadiusGatewayUrl()).host}. Export writes a zip archive to the current directory instead.`);
+-    if (!delivery || delivery === "Cancel")
++    const confirmed = await choose(context, "Bug report", ["Export Report", "Cancel"], `Description: ${description || "none"}\nTranscript: ${includeSession ? "included" : "not included"}\nSummary: ${includeSummary ? `written by ${context.session.model?.name ?? "the current model"}` : "none"}\n\nWrites a zip archive to the current directory. Email it to ${SUPPORT_EMAIL}.`);
++    if (!confirmed || confirmed === "Cancel")
+         return undefined;
+     return {
+         hint: description || undefined,
+         includeSession,
+         includeSummary,
+-        delivery: delivery === "Upload Report" ? "upload" : "zip",
+     };
+ }
+ function buildBundle(session, options, summary) {
+@@ -111,28 +103,6 @@ function buildBundle(session, options, summary) {
+             : undefined,
+     };
+ }
+-async function upload(context, bundle) {
+-    const loader = showLoader(context, "Uploading bug report...");
+-    try {
+-        const provider = context.session.modelRuntime.getProvider(RADIUS_PROVIDER_ID);
+-        const token = provider
+-            ? getAuthCredential(await context.session.modelRuntime.getAuth(RADIUS_PROVIDER_ID, { minOAuthValidityMs: 5 * 60_000 }))
+-            : undefined;
+-        const result = await uploadBugReport(bundle, { token, signal: loader.signal });
+-        restoreEditor(context, loader);
+-        recordInSession(context.session, bundle, { delivery: "upload" });
+-        context.showStatus(`Bug report uploaded. Report ID: ${result.id}`);
+-        return undefined;
+-    }
+-    catch (error) {
+-        restoreEditor(context, loader);
+-        if (loader.signal.aborted) {
+-            context.showStatus("Bug report cancelled");
+-            return undefined;
+-        }
+-        return errorMessage(error);
+-    }
+-}
+ async function exportZip(context, bundle) {
+     const archivePath = path.join(process.cwd(), bugReportArchiveFileName(bundle.metadata.id));
+     try {
+@@ -143,7 +113,7 @@ async function exportZip(context, bundle) {
+         return;
+     }
+     recordInSession(context.session, bundle, { delivery: "zip", path: archivePath });
+-    context.showStatus(`Bug report exported to: ${archivePath}\nReport ID: ${bundle.metadata.id}`);
++    context.showStatus(`Bug report exported to: ${archivePath}\nReport ID: ${bundle.metadata.id}\n\nEmail this file to ${SUPPORT_EMAIL} to reach support.`);
+ }
+ function recordInSession(session, bundle, delivery) {
+     session.sessionManager.appendCustomEntry(BUG_REPORT_CUSTOM_ENTRY_TYPE, {
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/config-selector.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/config-selector.js
 index 6f7ed6a..b0ed0ae 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/config-selector.js
@@ -1694,7 +1824,7 @@ index 6d0356c..ca0aa98 100644
          if (content) {
              text += `\n\n${content}`;
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
-index d82182c..41426bc 100644
+index d82182c..2764952 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 @@ -10,7 +10,7 @@ import * as TuiLayouts from "@earendil-works/pi-tui";
@@ -1835,6 +1965,15 @@ index d82182c..41426bc 100644
          // Check tmux keyboard setup asynchronously
          this.checkTmuxKeyboardSetup().then((warning) => {
              if (warning) {
+@@ -1568,7 +1635,7 @@ export class InteractiveMode {
+         if (this.bugReportHintShown)
+             return;
+         this.bugReportHintShown = true;
+-        this.chatContainer.addChild(new Text(theme.fg("muted", `If this looks like a ${APP_NAME} bug, /bug sends a report to the developers.`), this.outputPad, 0));
++        this.chatContainer.addChild(new Text(theme.fg("muted", `If this looks like a ${APP_NAME} bug, /bug exports a report you can email to support@privateer.pro.`), this.outputPad, 0));
+         this.ui.requestRender();
+     }
+     renderCurrentSessionState() {
 @@ -2419,7 +2486,17 @@ export class InteractiveMode {
              if (text === "/model" || text.startsWith("/model ")) {
                  const searchTerm = text.startsWith("/model ") ? text.slice(7).trim() : undefined;

package/src/cli/chat.ts

@@ -449,7 +449,7 @@ async function main() {
   // Shown once per distinct non-vision spec (visionWarningAcknowledged), not on every
   // launch — a user who keeps a deliberate non-vision pick already knows the tradeoff.
   if (!acceptsImages(spec) && !visionWarningAcknowledged(spec)) {
-    console.log(`${YELLOW}⚠ ${provider}/${modelId} can't see images — @file/read on a picture or video frame will be dropped silently. Run /model to switch.${RESET}`);
+    console.log(`${YELLOW}⚠ ${provider}/${modelId} can't see images — a vision model on the same key will describe them for it (none available → they're dropped). Run /model to switch.${RESET}`);
     acknowledgeVisionWarning(spec);
   }
   if (noQuarterActive()) applyNoQuarter(true); // launched with --no-quarter: say so up front

package/src/config/moat.ts

@@ -284,6 +284,11 @@ export async function buildMoat(opts: MoatOptions): Promise<ExtensionFactory[]>
   }
   factories.push(makeAccountProvider()); // must follow pi-privacy — see header
 
+  // Every kind: a text-only model gets image descriptions from a vision model on the
+  // same key instead of silently losing the image. See providers/visionDelegate.ts.
+  const { default: privateerVision } = await import("../../extensions/privateer-vision.ts");
+  factories.push(privateerVision);
+
   if (caps.context) {
     const { default: privateerContext } = await import("../../extensions/privateer-context.ts");
     factories.push(privateerContext);

package/src/config/moatManifest.json

@@ -16,6 +16,7 @@
     { "entry": "extensions/privateer-tools.ts", "name": "privateer-tools", "note": "Privateer tool pack" },
     { "entry": "extensions/privateer-privacy.ts", "name": "privateer-privacy", "note": "pi-privacy + account tier resolver" },
     { "entry": "extensions/privateer-connect.ts", "name": "privateer-connect", "note": "/connect — MCP connector manager" },
+    { "entry": "extensions/privateer-vision.ts", "name": "privateer-vision", "note": "a vision model on the same key describes images for a text-only model" },
     { "entry": "extensions/privateer-media.ts", "name": "privateer-media", "note": "image/video/speech/music + ffmpeg compose" },
     { "entry": "extensions/privateer-computer.ts", "name": "privateer-computer", "note": "screen control — screenshots, mouse and keyboard (off unless armed with --allow-computer-control)" },
     { "entry": "extensions/privateer-desktop.ts", "name": "privateer-desktop", "note": "/desktop — open the Privateer desktop app" },

package/src/engine/errors.ts

@@ -359,8 +359,11 @@ export function describeError(err: unknown): DescribedError {
     });
   }
   if (status === 429) {
+    // Never name the upstream provider here — OpenRouter is an implementation
+    // detail behind the Privateer account channel, and a plain "rate limited"
+    // is all a user needs to know regardless of who's actually throttling us.
     return out({
-      message: `Rate limited${forProvider} (429).`,
+      message: `Rate limited (429).`,
       hint: "Wait a moment and try again.",
       retryable: true,
     });

package/src/providers/visionDelegate.ts

@@ -0,0 +1,199 @@
+// Seeing on behalf of a model that can't.
+//
+// providers/vision.ts makes a text-only model HONEST about images — it declares
+// `input: ["text"]`, and Pi then drops every image block on the way to the provider.
+// Honest, but blind: a user on glm-5-2 who points the agent at a screenshot still
+// gets an answer about a picture the model never saw, just with a note saying so.
+//
+// This module closes that gap. Before each LLM call (Pi's `context` event) every
+// image in the outgoing messages is handed to a vision-capable model and replaced
+// with that model's description — so the text-only model gets words where it would
+// have got nothing. The session itself keeps the original images: only the
+// per-request copy is rewritten, so switching to a vision model later still sends
+// the real pixels.
+//
+// WHICH delegate — "the key type provided". The delegate must be reachable with the
+// credential the user is ALREADY using, i.e. the same provider as the current model:
+//
+//   privateer/* (account)  → privateer/tinfoil/gemma4-31b, the confidential default
+//   tinfoil/*   (TEE key)  → tinfoil/gemma4-31b
+//   openrouter/* …         → the best vision model that provider serves
+//
+// Never a different provider. Crossing providers would ship the user's screenshot
+// to a company they did not pick for this session — on a privacy-first agent that
+// is not a fallback, it's a leak. If the current provider has no vision model with
+// working auth, nothing is rewritten and Pi's existing "image omitted" behaviour
+// stands. PRIVATEER_VISION_MODEL=<provider/id> overrides the choice (and is the one
+// deliberate way to cross providers).
+
+import { createHash } from "node:crypto";
+import { ACCOUNT_DEFAULT_MODEL_ID, TINFOIL_MODEL_ID } from "./defaultModel.ts";
+
+export interface VisionModel {
+  provider: string;
+  id: string;
+  input: string[];
+}
+
+/** The slice of Pi's ModelRegistry this module needs (kept structural). */
+export interface VisionRegistry {
+  getAvailable(): VisionModel[];
+  find(provider: string, id: string): VisionModel | undefined;
+  hasConfiguredAuth(model: VisionModel): boolean;
+  complete(model: any, context: any, options?: any): Promise<{ content: any[]; stopReason?: string; errorMessage?: string }>;
+}
+
+const specOf = (m: { provider: string; id: string }) => `${m.provider}/${m.id}`;
+const seesImages = (m: { input?: string[] }) => Array.isArray(m.input) && m.input.includes("image");
+
+// Per-provider first choices, tried before "any vision model on this provider". Only
+// providers where the pick matters are listed: on the account channel it keeps the
+// image inside the attested Tinfoil enclave rather than whichever vision model sorts
+// first; elsewhere the registry's own list is good enough.
+const PREFERRED: Record<string, string[]> = {
+  privateer: [ACCOUNT_DEFAULT_MODEL_ID],
+  tinfoil: [TINFOIL_MODEL_ID.replace(/^tinfoil\//, "")],
+  openrouter: ["google/gemini-2.5-flash", "openai/gpt-4o-mini", "anthropic/claude-haiku-4.5"],
+};
+
+/**
+ * The model that should look at images for `current`, or undefined when there is no
+ * reachable vision model on the same key. Returns undefined for a model that can
+ * already see — there is nothing to delegate.
+ */
+export function pickVisionDelegate(
+  current: VisionModel | undefined,
+  registry: VisionRegistry,
+  env: NodeJS.ProcessEnv = process.env,
+): VisionModel | undefined {
+  if (!current || seesImages(current)) return undefined;
+  const usable = (m: VisionModel | undefined): m is VisionModel =>
+    !!m && seesImages(m) && registry.hasConfiguredAuth(m);
+
+  const override = env.PRIVATEER_VISION_MODEL?.trim();
+  if (override) {
+    const slash = override.indexOf("/");
+    const m = slash > 0 ? registry.find(override.slice(0, slash), override.slice(slash + 1)) : undefined;
+    if (usable(m)) return m;
+  }
+
+  for (const id of PREFERRED[current.provider] ?? []) {
+    const m = registry.find(current.provider, id);
+    if (usable(m)) return m;
+  }
+  return registry.getAvailable().find((m) => m.provider === current.provider && usable(m));
+}
+
+// Pi's read tool appends this to an image it knows the model can't see. Once we've
+// described the image the note is false, and leaving it in invites the model to tell
+// the user it couldn't look.
+const OMITTED_NOTE = /\n?\[Current model does not support images\. The image will be omitted from this request\.\]/g;
+
+const SYSTEM_PROMPT = [
+  "You are the eyes for another AI model that cannot see images.",
+  "Describe the image so that model can act on it without seeing it.",
+  "Transcribe ALL legible text verbatim (code, error messages, labels, numbers), preserving line breaks.",
+  "Then describe layout, UI elements and their state, colors where meaningful, charts/diagrams and what they show, and anything unusual.",
+  "Be precise and factual. Do not speculate beyond what is visible. No preamble.",
+].join(" ");
+
+type Block = { type: string; text?: string; data?: string; mimeType?: string };
+
+const cache = new Map<string, Promise<string>>();
+
+/** Test hook: forget every cached description. */
+export function clearVisionCache(): void {
+  cache.clear();
+}
+
+function describe(
+  registry: VisionRegistry,
+  delegate: VisionModel,
+  image: Block,
+  hint: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const key = `${specOf(delegate)}:${createHash("sha256").update(image.data ?? "").digest("hex")}`;
+  const hit = cache.get(key);
+  if (hit) return hit;
+  const job = (async () => {
+    const res = await registry.complete(
+      delegate,
+      {
+        systemPrompt: SYSTEM_PROMPT,
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: hint ? `Context it appeared in:\n${hint.slice(0, 2000)}\n\nDescribe this image.` : "Describe this image." },
+              { type: "image", data: image.data, mimeType: image.mimeType },
+            ],
+            timestamp: Date.now(),
+          },
+        ],
+      },
+      { signal, cacheRetention: "none" },
+    );
+    if (res.stopReason === "error" || res.stopReason === "aborted") {
+      throw new Error(res.errorMessage || `vision model ${res.stopReason}`);
+    }
+    const text = res.content.filter((c) => c?.type === "text").map((c) => c.text).join("\n").trim();
+    if (!text) throw new Error("vision model returned no description");
+    return text;
+  })();
+  cache.set(key, job);
+  // A failure must not stick: the next turn should get another try.
+  job.catch(() => cache.delete(key));
+  return job;
+}
+
+/**
+ * Rewrite `messages` so every image block becomes a text description from
+ * `delegate`. Returns undefined when there was nothing to rewrite. Never throws: an
+ * image that can't be described becomes a note saying so (Pi would have dropped it
+ * anyway), so one bad image can't fail the turn.
+ */
+export async function describeImagesInMessages(
+  messages: any[],
+  delegate: VisionModel,
+  registry: VisionRegistry,
+  opts: { currentSpec: string; signal?: AbortSignal; onDescribe?: (count: number) => void } = { currentSpec: "" },
+): Promise<any[] | undefined> {
+  const jobs: Array<{ block: Block; hint: string }> = [];
+  for (const msg of messages) {
+    if (!msg || msg.role === "assistant" || !Array.isArray(msg.content)) continue;
+    const hint = (msg.content as Block[])
+      .filter((b) => b?.type === "text")
+      .map((b) => b.text ?? "")
+      .join("\n")
+      .replace(OMITTED_NOTE, "");
+    for (const b of msg.content as Block[]) if (b?.type === "image" && b.data) jobs.push({ block: b, hint });
+  }
+  if (jobs.length === 0) return undefined;
+  opts.onDescribe?.(jobs.length);
+
+  const results = new Map<Block, string>();
+  await Promise.all(
+    jobs.map(async ({ block, hint }) => {
+      try {
+        const text = await describe(registry, delegate, block, hint, opts.signal);
+        results.set(block, `[Image — ${opts.currentSpec || "this model"} can't see images, so ${specOf(delegate)} described it:]\n${text}`);
+      } catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        results.set(block, `[Image omitted — ${specOf(delegate)} could not describe it: ${why}]`);
+      }
+    }),
+  );
+
+  return messages.map((msg) => {
+    if (!msg || msg.role === "assistant" || !Array.isArray(msg.content)) return msg;
+    if (!(msg.content as Block[]).some((b) => results.has(b))) return msg;
+    const content = (msg.content as Block[]).map((b) => {
+      const described = results.get(b);
+      if (described !== undefined) return { type: "text", text: described };
+      if (b?.type === "text" && b.text) return { ...b, text: b.text.replace(OMITTED_NOTE, "") };
+      return b;
+    });
+    return { ...msg, content };
+  });
+}