privateer-agent 0.12.44 → 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.44",
+  "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

@@ -53,8 +53,14 @@ async function main() {
   const { modelRegistryOf } = await import("../providers/piAuthStore.ts");
   const { agentVersion } = await import("../config/version.ts");
   const { pickerCatalog, hiddenAccountNotice, hiddenAccountTitleSuffix } = await import("../providers/modelCatalog.ts");
-  const { resolveDefaultModel, resolveSignedInModel, savedPiDefaultSpec, writePiDefaultModel } =
-    await import("../providers/defaultModel.ts");
+  const {
+    resolveDefaultModel,
+    resolveSignedInModel,
+    savedPiDefaultSpec,
+    writePiDefaultModel,
+    visionWarningAcknowledged,
+    acknowledgeVisionWarning,
+  } = await import("../providers/defaultModel.ts");
   const { acceptsImages } = await import("../providers/vision.ts");
   const { postOutbox } = await import("../outbox/cloudOutbox.ts");
   const { addPendingCloud } = await import("../routines/store.ts");
@@ -440,8 +446,11 @@ async function main() {
   // blocks for a model that doesn't declare the modality with NO error — `read` on a
   // screenshot just quietly answers about nothing — so make that failure visible
   // instead of letting a user discover it turn by turn. /model to switch.
-  if (!acceptsImages(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}`);
+  // 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 — 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/defaultModel.ts

@@ -227,6 +227,43 @@ export function resolveSignedInModel(env: NodeJS.ProcessEnv = process.env): stri
   return resolveDefaultModel({ env, signedIn: true, saved: null });
 }
 
+// Whether the startup "can't see images" nag (cli/chat.ts) has already been shown for
+// this exact spec. Without this, a user who deliberately keeps a non-vision saved pick
+// (speed over sight, say) sees the same warning on every single launch forever, which
+// trains people to stop reading warnings at all. Keyed by spec so switching to a
+// DIFFERENT non-vision model warns again once — this tracks "have they seen this
+// specific tradeoff", not "should we ever mention it again".
+export function visionWarningAcknowledged(spec: string): boolean {
+  try {
+    const raw = readFileSync(join(agentDir(), "settings.json"), "utf8").trim();
+    if (!raw) return false;
+    const s = JSON.parse(raw) as Record<string, unknown>;
+    return s.visionWarningAcknowledgedFor === spec;
+  } catch {
+    return false;
+  }
+}
+
+// Record that the nag has been shown for `spec`, so the next launch on the same pick
+// stays quiet. Best-effort and silent like the writers below — losing this write just
+// means the warning repeats once more, never a crash.
+export function acknowledgeVisionWarning(spec: string): void {
+  const dir = agentDir();
+  const settingsPath = join(dir, "settings.json");
+  try {
+    mkdirSync(dir, { recursive: true });
+    let settings: Record<string, unknown> = {};
+    if (existsSync(settingsPath)) {
+      const raw = readFileSync(settingsPath, "utf8").trim();
+      if (raw) settings = JSON.parse(raw) as Record<string, unknown>;
+    }
+    settings.visionWarningAcknowledgedFor = spec;
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  } catch {
+    // best-effort: the warning already printed either way.
+  }
+}
+
 // Split a "provider/id" spec on its first slash (model ids themselves contain "/", so
 // only the first delimiter separates provider from model). Returns null for a spec
 // with no provider prefix.

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

package/src/tools/media.ts

@@ -738,6 +738,10 @@ interface AudioResponse {
   audioBase64?: string;
   mimeType?: string;
   model?: string;
+  /** The exact wire voice the provider actually received (post-resolution —
+   *  e.g. an aura-2 override of 'jupiter' comes back as 'aura-2-jupiter-en').
+   *  Absent only on models that take no voice at all. */
+  voice?: string;
   /** Present only for the models that take a length — an sfx model always does. */
   durationSeconds?: number;
 }
@@ -749,11 +753,21 @@ export const generateSpeechToolDefinition = {
     "Turn text into spoken audio and save it to disk. Use it to narrate a video you are assembling, or " +
     "to produce a spoken version of a written answer. Billed to the user's Privateer account; the " +
     "account's default voice model is a confidential-compute one, so the text is processed inside an " +
-    "enclave rather than by a retaining provider. Mux the result onto video with video_compose.",
+    "enclave rather than by a retaining provider. Mux the result onto video with video_compose. " +
+    "Call media_capabilities first if you want to override `voice` or `model` — it lists the exact " +
+    "wire voice ids for the account's current TTS model (and any model you pass it), which is not " +
+    "the same as a spoken character or brand name.",
   parameters: Type.Object({
     text: Type.String({ description: "The words to speak. Write them as they should be read aloud." }),
     path: Type.String({ description: "Where to write the audio, relative to cwd or absolute (e.g. 'audio/narration.mp3')." }),
-    voice: Type.Optional(Type.String({ description: "Voice name, if the account's TTS model offers a choice. Leave unset for its default." })),
+    voice: Type.Optional(Type.String({
+      description:
+        "Voice id, if the account's TTS model offers a choice. Leave unset for its default. These are " +
+        "PROVIDER wire ids, not free text — e.g. Deepgram Aura-2 voices are 'aura-2-<name>-<lang>' " +
+        "('aura-2-jupiter-en', not 'jupiter' or 'Jupiter'). Get the exact legal list for the model in " +
+        "play from media_capabilities' `speech.voices` before guessing one; an unrecognised id is " +
+        "refused with VOICE_UNSUPPORTED rather than silently served on a different voice.",
+    })),
     model: Type.Optional(Type.String({ description: "Override the account's text-to-speech model." })),
   }),
   async execute(
@@ -783,7 +797,13 @@ export const generateSpeechToolDefinition = {
     const target = abs(cwd, params.path);
     const ext = extname(target) || extForMime(r.data.mimeType ?? "", ".mp3");
     const out = `${target.slice(0, target.length - extname(target).length)}${ext}`;
-    return text(`Generated speech: ${writeOut(out, Buffer.from(r.data.audioBase64, "base64"))}`);
+    // Report what actually ran, not what was requested — the two can differ
+    // (a resolved default, a normalized voice id) and the caller has no other
+    // way to find out short of listening to the file.
+    const via = [r.data.model, r.data.voice].filter(Boolean).join(" / ");
+    return text(
+      `Generated speech${via ? ` with ${via}` : ""}: ${writeOut(out, Buffer.from(r.data.audioBase64, "base64"))}`,
+    );
   },
 };
 
@@ -951,6 +971,20 @@ interface CapabilitiesResponse {
    *  the account's own privacy setting. They are different refusals with different
    *  remedies, and only one of them is the user's to fix. */
   sfx?: { model?: string; configured?: boolean; blockedByZdr?: boolean; maxDurationSeconds?: number };
+  /** `voices` (on the described model) is populated only for models with an
+   *  enumerable, closed voice set (Deepgram Aura-2, Tinfoil, fal) — pass
+   *  `ttsModel` to describe one other than the account default. Empty for
+   *  models whose voices aren't data this server holds (Gemini, OpenAI-shaped);
+   *  guessing one there is on you. `catalog` is EVERY TTS model this account
+   *  can reach, summarized — the only place other than the default to
+   *  discover an id, since there is no TTS picker in this CLI. */
+  speech?: {
+    model?: string; blockedByZdr?: boolean; voices?: string[];
+    catalog?: {
+      id: string; name?: string; provider?: string;
+      isZdr?: boolean; isTee?: boolean; blockedByZdr?: boolean; voiceCount?: number;
+    }[];
+  };
   privacy?: { requireZdr?: boolean; allowNonZdrMedia?: boolean };
 }
 
@@ -1060,6 +1094,44 @@ export function describeSfx(sfx: CapabilitiesResponse["sfx"]): string[] {
   ];
 }
 
+/**
+ * Speech, worded the same way describeSfx is: a [BLOCKED] model is the
+ * account's own ZDR setting, not something retrying fixes. `voices` prints
+ * only when the model publishes an enumerable set — printing all 90 of
+ * Aura-2's inline is the whole point (a bare character name is not a legal
+ * id on the wire), but a model with none gets no fabricated list either.
+ */
+export function describeSpeech(speech: CapabilitiesResponse["speech"]): string[] {
+  const blocked = speech?.blockedByZdr ? "  [BLOCKED by this account's ZDR setting]" : "";
+  const lines = [`Speech model: ${speech?.model ?? "unknown"}${blocked}`];
+  if (speech?.blockedByZdr) {
+    lines.push(
+      "  This voice model is non-ZDR, so this account cannot use it until its owner enables non-ZDR " +
+        "media (Settings → Privacy). Omit `model` to use the account's confidential-compute default " +
+        "instead of retrying this one.",
+    );
+  }
+  if (speech?.voices?.length) {
+    lines.push(
+      `  ${speech.voices.length} voice id(s) for this model — pass one of these EXACTLY as generate_speech's ` +
+        `\`voice\`, never a guessed name: ${speech.voices.join(", ")}`,
+    );
+  } else {
+    lines.push("  No enumerable voice list for this model; omit `voice` to use its default.");
+  }
+  if (speech?.catalog?.length) {
+    lines.push("  every TTS model available (pass `ttsModel` to this tool to see its voices):");
+    for (const m of speech.catalog) {
+      const tags = [m.isTee ? "confidential" : m.isZdr ? "ZDR" : "non-ZDR", `${m.voiceCount ?? 0} voice(s)`];
+      if (m.blockedByZdr) tags.push("BLOCKED");
+      lines.push(
+        `    ${m.id}  (${tags.join(", ")})${m.id === speech.model ? "  [described above]" : ""}`,
+      );
+    }
+  }
+  return lines;
+}
+
 export const mediaCapabilitiesToolDefinition = {
   name: "media_capabilities",
   label: "Media Capabilities",
@@ -1072,7 +1144,10 @@ export const mediaCapabilitiesToolDefinition = {
     "It is also the ONLY way to find out which 3D models exist and what options each one takes: they " +
     "range from $0.14 to $2.41 a mesh and no two take the same options, so call this with `model` set " +
     "to the id you are considering BEFORE generate_model, or you will pay the default model's price " +
-    "for a job a cheaper one could have done.",
+    "for a job a cheaper one could have done.\n" +
+    "It is also the ONLY way to find a text-to-speech model's real voice ids — Deepgram Aura-2's are " +
+    "'aura-2-<name>-<lang>', not a bare character name — so call this with `ttsModel` set BEFORE " +
+    "generate_speech whenever you plan to pass `voice`.",
   parameters: Type.Object({
     model: Type.Optional(
       Type.String({
@@ -1082,13 +1157,27 @@ export const mediaCapabilitiesToolDefinition = {
           "their legal values and the price — is per-model.",
       }),
     ),
+    ttsModel: Type.Optional(
+      Type.String({
+        description:
+          "A text-to-speech model id to describe instead of the account default (e.g. 'deepgram/aura-2'). " +
+          "The response's `speech.voices` lists every legal voice id for THIS model — voice ids are not " +
+          "shared across models.",
+      }),
+    ),
   }),
-  async execute(_toolCallId: string, params: { model?: string }, signal?: AbortSignal) {
-    const query = params?.model ? `?model=${encodeURIComponent(params.model)}` : "";
-    const r = await callAccount<CapabilitiesResponse>(`/api/agent/media/capabilities${query}`, { method: "GET", signal });
+  async execute(_toolCallId: string, params: { model?: string; ttsModel?: string }, signal?: AbortSignal) {
+    const query = new URLSearchParams();
+    if (params?.model) query.set("model", params.model);
+    if (params?.ttsModel) query.set("ttsModel", params.ttsModel);
+    const qs = query.toString();
+    const r = await callAccount<CapabilitiesResponse>(
+      `/api/agent/media/capabilities${qs ? `?${qs}` : ""}`,
+      { method: "GET", signal },
+    );
     if (!r.ok) return text(`Could not read media capabilities: ${r.message}`);
 
-    const { image, video, model3d, sfx, privacy } = r.data;
+    const { image, video, model3d, sfx, speech, privacy } = r.data;
     const lines = [
       `Image model: ${image?.model ?? "unknown"}${image?.blockedByZdr ? "  [BLOCKED by this account's ZDR setting]" : ""}`,
       `  up to ${image?.maxPerCall ?? 1} image(s) per call`,
@@ -1099,18 +1188,19 @@ export const mediaCapabilitiesToolDefinition = {
 
     lines.push(...describeModel3d(model3d));
     lines.push(...describeSfx(sfx));
+    lines.push(...describeSpeech(speech));
 
     lines.push(`Privacy: requireZdr=${privacy?.requireZdr ?? "?"}, allowNonZdrMedia=${privacy?.allowNonZdrMedia ?? "?"}`);
-    if (image?.blockedByZdr || video?.blockedByZdr || model3d?.blockedByZdr || sfx?.blockedByZdr) {
+    if (image?.blockedByZdr || video?.blockedByZdr || model3d?.blockedByZdr || sfx?.blockedByZdr || speech?.blockedByZdr) {
       lines.push(
         "A [BLOCKED] model means the account requires Zero Data Retention and that model has no ZDR endpoint. " +
           "Only the account owner can change it (Settings → Privacy); do not keep retrying.",
       );
     }
     lines.push(
-      "Speech and music are always available; sound effects are not (see above). Speech runs confidentially, " +
-        "music has no ZDR gate at all, and effects are gated like image and video — so a blocked effect must " +
-        "never be answered with music.",
+      "Music is always available; sound effects and (per above) speech's CURRENT model may not be. Music has " +
+        "no ZDR gate at all; effects are gated like image and video, so a blocked effect must never be " +
+        "answered with music instead.",
     );
     return text(lines.join("\n"));
   },