privateer-agent 0.12.45 → 0.12.49

package/src/permissions/cliSpend.ts

@@ -0,0 +1,163 @@
+// SPEND PRE-APPROVAL FOR ONE HEADLESS RUN, typed on the command line.
+//
+//   privateer -p --allow-spend generate_video --max-calls 1 --max-spend 1.00 "…"
+//
+// THE PROBLEM. A `-p` run has no screen, so the gate's local asker has nobody to ask
+// and every billing tool — each one `alwaysAsk` — is denied. An agent driving Privateer
+// from a script could plan a whole film and only discover at the last step that the
+// one call that mattered could never be approved. The routine grant (childSpend.ts)
+// solves this for scheduled runs; this is the same idea for a run a person starts.
+//
+// WHY A FLAG, NOT AN ENV VAR. The grant is typed per invocation, capped, and gone when
+// the process exits. The launcher carries it to the gate in PRIVATEER_CLI_SPEND — the
+// only channel into Pi's process — but deletes any inherited value before parsing argv
+// (bin/privateer-launch.mjs), so an export lingering in someone's shell never counts.
+// And it is honoured only where the flag can apply: a TOP-LEVEL headless session. Not
+// the TUI (a person approves each call there), and not a subagent child (a child's
+// grant comes only from childSpend.ts, whose caps this ledger does not share).
+//
+// WHAT IT LIFTS. Exactly what the routine grant lifts, through the same
+// ModeGate.isSpendPreauthorized hook and under the same guards: `alwaysAsk` must be the
+// only reason to ask, and a call that leaves the working directory or touches a
+// protected file is never covered. On top of that, two caps:
+//
+//   • --max-calls counts calls this ledger ALLOWED, not calls that succeeded — a call
+//     that then fails server-side still used its slot. Over-counting is the safe error.
+//   • --max-spend is checked BEFORE each call against the server's own reservation
+//     figure for that exact call (tools/media.ts quoteMediaCallUsd), which is
+//     worst-case by design. A call that can't be priced is REFUSED under a dollar cap
+//     rather than waved through — a cap that skips what it can't measure isn't one.
+
+import type { PermissionRequest } from "./gate.ts";
+import { BILLED_MEDIA_TOOLS } from "./classify.ts";
+
+/** The env var the launcher writes from `--allow-spend` (mirrors bin/headless-flags.mjs). */
+export const CLI_SPEND_ENV = "PRIVATEER_CLI_SPEND";
+
+export interface CliSpendGrant {
+  tools: string[];
+  maxCalls?: number;
+  maxSpendUsd?: number;
+}
+
+/**
+ * The grant this run was launched with, or null. Defensive: anything malformed, any
+ * tool that isn't a billing tool, or a grant with no cap at all reads as NO grant —
+ * the launcher never writes one of those, so seeing one means it didn't come from it.
+ */
+export function readCliSpendGrant(env: NodeJS.ProcessEnv = process.env): CliSpendGrant | null {
+  const raw = env[CLI_SPEND_ENV];
+  if (!raw) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const g = parsed as Partial<CliSpendGrant>;
+  if (!g || !Array.isArray(g.tools)) return null;
+  const tools = g.tools.filter((t): t is string => typeof t === "string" && BILLED_MEDIA_TOOLS.has(t));
+  if (tools.length === 0) return null;
+  const maxCalls = Number.isInteger(g.maxCalls) && (g.maxCalls as number) > 0 ? (g.maxCalls as number) : undefined;
+  const maxSpendUsd =
+    typeof g.maxSpendUsd === "number" && Number.isFinite(g.maxSpendUsd) && g.maxSpendUsd > 0 ? g.maxSpendUsd : undefined;
+  if (maxCalls === undefined && maxSpendUsd === undefined) return null;
+  return { tools, ...(maxCalls !== undefined ? { maxCalls } : {}), ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {}) };
+}
+
+/** Price one call of `tool` with these arguments, in USD; null when it can't be priced. */
+export type SpendQuote = (tool: string, input: unknown, signal?: AbortSignal) => Promise<number | null>;
+
+export type SpendDecision = { ok: true; usd: number | null } | { ok: false; reason: string };
+
+const money = (n: number): string => `$${n.toFixed(2)}`;
+
+/**
+ * The running tally for one grant. One per process: the caps are for the whole run.
+ */
+export class CliSpendLedger {
+  private calls = 0;
+  private spentUsd = 0;
+
+  constructor(
+    readonly grant: CliSpendGrant,
+    private readonly quote: SpendQuote,
+  ) {}
+
+  /**
+   * May this call spend? Records it when it may. The check and the record happen in
+   * one synchronous step after the (async) quote, so two calls racing in parallel can't
+   * both squeeze under the same remaining budget.
+   */
+  async authorize(tool: string, input: unknown, signal?: AbortSignal): Promise<SpendDecision> {
+    const { tools, maxCalls, maxSpendUsd } = this.grant;
+    if (!tools.includes(tool)) {
+      return { ok: false, reason: `this run's --allow-spend covers ${tools.join(", ")}, not ${tool}` };
+    }
+    if (maxCalls !== undefined && this.calls >= maxCalls) {
+      return { ok: false, reason: `this run's --max-calls ${maxCalls} is used up` };
+    }
+    let usd: number | null = null;
+    if (maxSpendUsd !== undefined) {
+      try {
+        usd = await this.quote(tool, input, signal);
+      } catch {
+        usd = null;
+      }
+      if (usd === null) {
+        return {
+          ok: false,
+          reason:
+            `${tool} can't be priced before it runs, so it can't be checked against --max-spend ${money(maxSpendUsd)}` +
+            (tool === "generate_image" || tool === "generate_sprite"
+              ? " (a call that overrides the image model is one of those — leave `model`/`image_model` unset)"
+              : "") +
+            ". Cap this run with --max-calls instead",
+        };
+      }
+      // Recheck after the await: a parallel call may have spent while we were quoting.
+      if (maxCalls !== undefined && this.calls >= maxCalls) {
+        return { ok: false, reason: `this run's --max-calls ${maxCalls} is used up` };
+      }
+      if (this.spentUsd + usd > maxSpendUsd + 1e-9) {
+        return {
+          ok: false,
+          reason:
+            `this call is estimated at ${money(usd)} and only ${money(Math.max(0, maxSpendUsd - this.spentUsd))} ` +
+            `of this run's --max-spend ${money(maxSpendUsd)} is left`,
+        };
+      }
+      this.spentUsd += usd;
+    }
+    this.calls++;
+    return { ok: true, usd };
+  }
+
+  /** One line for the end of the run / a denial: what the grant has used so far. */
+  summary(): string {
+    const { maxCalls, maxSpendUsd } = this.grant;
+    const parts = [`${this.calls}${maxCalls !== undefined ? `/${maxCalls}` : ""} billed call(s)`];
+    if (maxSpendUsd !== undefined) parts.push(`~${money(this.spentUsd)} of ${money(maxSpendUsd)} estimated`);
+    return parts.join(", ");
+  }
+}
+
+/**
+ * The guidance a headless run gives when a billed call hits the gate with nothing to
+ * approve it — written for the MODEL as much as the person, since the model is the one
+ * that reads a tool denial and decides what to do next. It names every way out.
+ */
+export function headlessSpendGuidance(tool: string, cmd = process.env.PRIVATEER_CMD || "privateer"): string {
+  return (
+    `This is a headless run (-p) with no one at a screen to approve ${tool}, which bills the account. ` +
+    `It can't be approved from inside this run. To allow it, the person running Privateer can re-run with ` +
+    `\`${cmd} -p --allow-spend ${tool} --max-calls 1\` (optionally --max-spend <usd>), add --approve-in-app to ` +
+    `approve it from the Privateer app, or drive Privateer over ACP (\`${cmd} acp\`), where the controlling ` +
+    `program is asked. Stop and report this rather than retrying.`
+  );
+}
+
+/** Is this the request a CLI grant could ever cover? (Billing tool, and billing is the only ask.) */
+export function isSpendRequest(req: PermissionRequest): boolean {
+  return req.alwaysAsk === true && BILLED_MEDIA_TOOLS.has(req.tool);
+}

package/src/permissions/modeGate.ts

@@ -63,7 +63,12 @@ export interface ModeGateDeps {
   // Consulted ONLY to lift `alwaysAsk`, and only under the guards in ModeGate.request.
   // Absent ⇒ nothing is pre-authorized, which is the posture every interactive session
   // keeps: a terminal always asks its human, however cheap the call.
-  isSpendPreauthorized?: (req: PermissionRequest) => boolean;
+  //
+  // May be async: a `--max-spend` grant prices the call before answering (cliSpend.ts).
+  // It is consulted LAST, after every other guard has passed, because a grant with a
+  // budget RECORDS what it allows — asking it about a call the mode would refuse anyway
+  // would spend budget on nothing.
+  isSpendPreauthorized?: (req: PermissionRequest) => boolean | Promise<boolean>;
 }
 
 // The permission gate used by the live TUI. It first applies the mode/allowlist
@@ -129,8 +134,9 @@ export class ModeGate implements PermissionGate {
       req.alwaysAsk &&
       !req.outside &&
       !req.protected &&
-      this.deps.isSpendPreauthorized?.(req) === true &&
-      decideAuto({ ...req, alwaysAsk: false }, this.deps.getMode(), this.deps.allowlist, denylist) === "allow"
+      this.deps.isSpendPreauthorized &&
+      decideAuto({ ...req, alwaysAsk: false }, this.deps.getMode(), this.deps.allowlist, denylist) === "allow" &&
+      (await this.deps.isSpendPreauthorized(req)) === true
     ) {
       return "allow";
     }

package/src/permissions/noQuarter.ts

@@ -27,9 +27,20 @@
 //     process.env is the one thing all those copies share, so the state lives there and
 //     nowhere else: every reader, in every extension, sees every toggle.
 //
+// NO QUARTER ALSO TAKES THE PRIVACY FILTER DOWN. Lowering the moat is the "step away"
+// switch, and a turn that runs to completion unattended must not stall on pi-privacy's
+// PII prompt either — so going to no quarter is also `/privacy off`. Raising the moat
+// puts the filter back, but ONLY if no quarter is what took it down: a session already
+// running with `/privacy off` (or `--no-privacy`) stays off. The marker that records
+// "no quarter did this" lives in the env for the same cross-copy reasons as the flag,
+// and setPrivacyDisabled clears it — so an explicit `/privacy on|off` mid-no-quarter
+// is the operator's word and a later shift+tab doesn't overrule it.
+//
 // IMPORT-SAFETY: no Pi imports, no node builtins — safe to load from anywhere,
 // including boot-ordered entrypoints (see boot.ts's ORDERING CONTRACT).
 
+import { NO_QUARTER_PRIVACY_MARK, privacyDisabled, setPrivacyDisabled } from "../config/privacyDisabled.ts";
+
 const ENV = "PRIVATEER_NO_QUARTER";
 
 /** True while the gate is fully lowered for this session. Read live, never cached. */
@@ -39,8 +50,16 @@ export function noQuarterActive(): boolean {
 
 /** Set the state — in the env, so every copy of this module and every child agrees. Returns the new state. */
 export function setNoQuarter(on: boolean): boolean {
-  if (on) process.env[ENV] = "1";
-  else delete process.env[ENV];
+  if (on) {
+    process.env[ENV] = "1";
+    if (!privacyDisabled()) {
+      setPrivacyDisabled(true);
+      process.env[NO_QUARTER_PRIVACY_MARK] = "1";
+    }
+  } else {
+    delete process.env[ENV];
+    if (process.env[NO_QUARTER_PRIVACY_MARK] === "1") setPrivacyDisabled(false); // clears the mark
+  }
   return on;
 }
 

package/src/providers/account.ts

@@ -27,7 +27,7 @@ import { join } from "node:path";
 import { globalDir } from "../config/paths.ts";
 import { canOpenBrowser, openInBrowser } from "../util/openBrowser.ts";
 import { installGzipRequestBodies } from "../util/gzipRequestBody.ts";
-import { describeAccountBalanceError } from "../engine/errors.ts";
+import { describeAccountBalanceError, isConnectionFailureText } from "../engine/errors.ts";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { interpretReport, teePosture, tierFromTeePosture, type PrivacyTier } from "pi-privacy";
 import { ACCOUNT_DEFAULT_MODEL_ID, ACCOUNT_NEAR_MODEL_ID, ensurePiDefaultModel } from "./defaultModel.ts";
@@ -38,6 +38,7 @@ import {
   sealedProviderFor,
   sealedShimBase,
   ensureSealedShim,
+  stopSealedShim,
   attestSealed,
 } from "./sealedShim.ts";
 import type { PhalaEnclaveIdentity } from "./phalaSeal.ts";
@@ -897,6 +898,10 @@ export function makeAccountProvider() {
       // An auth failure, unlike a balance failure, needs a fresh child session.
       // Pi has no reactive-401 refresh; see recoverAccountSession.
       void recoverAccountSession(ctx, msg.errorMessage);
+      // A request that got no response at all. See recoverAccountConnection.
+      if (isConnectionFailureText(msg.errorMessage)) {
+        void recoverAccountConnection(ctx, (msg as { model?: string }).model ?? "", () => register(lastIds));
+      }
     });
   };
 }
@@ -1125,6 +1130,89 @@ const ACCOUNT_AUTH_FAILURE =
 // plenty, and the user gets a clear message instead of a retry loop.
 const RECOVERY_COOLDOWN_MS = 30_000;
 
+// Ask the server whether an account access token is still accepted. The status, or
+// null when there was no answer at all (which says nothing about the token).
+async function probeAccountToken(access: string): Promise<number | null> {
+  try {
+    const res = await fetch(`${serverBaseUrl()}/auth/me`, {
+      headers: { Authorization: `Bearer ${access}` },
+      signal: AbortSignal.timeout(8_000),
+    });
+    void res.body?.cancel().catch(() => {});
+    return res.status;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get a session that answers "Connection error." on every message working again.
+ *
+ * The report this exists for: a session started while a sign-in was failing kept
+ * failing with the SDK's bare "Connection error." on every retry, while a fresh
+ * `privateer` on the same machine worked. Nothing noticed, because the only recovery
+ * the account channel had keyed on a 401 (recoverAccountSession), and a request that
+ * never gets an HTTP response carries no status at all. Two pieces of per-SESSION state
+ * can strand requests that way while the machine's login is fine, and both are cheap
+ * to renew:
+ *
+ *   • the sealed shim (tinfoil/phala): the model's baseUrl points at a loopback port
+ *     for the life of the process. Restart the shim and re-register — Pi re-reads the
+ *     live model's baseUrl from the registry on registration — so the next request
+ *     goes to a listener that exists;
+ *   • the credential: probe the token this process holds; if the server now refuses it,
+ *     mint a fresh session exactly as a 401 would. A probe that gets NO answer is a real
+ *     outage, and replacing a good session over it would only leak a Linked Devices row.
+ *
+ * Bounded by the same cooldown as recoverAccountSession, so a dead network costs one
+ * probe per window, not one per retry. Returns what it renewed.
+ */
+export async function recoverAccountConnection(
+  ctx: unknown,
+  modelId: string,
+  reRegister: () => void,
+  probe: (access: string) => Promise<number | null> = probeAccountToken,
+): Promise<{ shim: boolean; session: boolean }> {
+  const renewed = { shim: false, session: false };
+  if (!hasCredentials()) return renewed;
+  const slot = armSlot() as ReturnType<typeof armSlot> & { connectionRecoveredAt?: number };
+  const now = Date.now();
+  if (slot.connectionRecoveredAt !== undefined && now - slot.connectionRecoveredAt < RECOVERY_COOLDOWN_MS) return renewed;
+  slot.connectionRecoveredAt = now;
+
+  if (sealedEnabled() && sealedProviderFor(modelId)) {
+    try {
+      await stopSealedShim();
+      await ensureSealedShim();
+      reRegister();
+      renewed.shim = true;
+    } catch {
+      /* the shim won't start → sealed models fall back to the cleartext path on re-register */
+      try {
+        reRegister();
+      } catch {
+        /* nothing more to do from here */
+      }
+    }
+  }
+
+  const held = slot.cred;
+  const status = held ? await probe(held.access) : null;
+  if (status === 401 || status === 403) {
+    slot.cred = undefined;
+    renewed.session = await armAccountCredential(ctx, { notify: false });
+  }
+
+  const c = ctx as SeedContext;
+  if (c?.hasUI && (renewed.shim || renewed.session)) {
+    c.ui?.notify?.(
+      `Couldn't reach Privateer — renewed this session's ${[renewed.shim ? "sealed connection" : "", renewed.session ? "credential" : ""].filter(Boolean).join(" and ")}. Send that message again.`,
+      "warning",
+    );
+  }
+  return renewed;
+}
+
 // Replace a dead account session after an auth failure, so the NEXT prompt works.
 //
 // This is the client-side answer to a gap in Pi's OAuth contract: inference goes out

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 };
+  });
+}