bloby-bot 0.70.13 → 0.71.0

package/supervisor/harnesses/claude.ts

@@ -21,6 +21,15 @@ import { assembleSystemPrompt } from '../../worker/prompts/prompt-assembler.js';
 import { buildAgents } from '../agents/index.js';
 import { preWarm, claimWarmup, discardWarmup } from '../cli-warmup.js';
 import { mirrorSkillsInto } from './skills.js';
+import {
+  routeAttachment,
+  normalizeImageMediaType,
+  approxBase64Bytes,
+  buildSavedFilesNote,
+  INLINE_TEXT_PER_FILE_CHARS,
+  INLINE_TEXT_TOTAL_CHARS,
+  MAX_INLINE_IMAGE_BYTES,
+} from './attachment-policy.js';
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -157,30 +166,68 @@ function loadMcpServers(): Record<string, any> | undefined {
   return undefined;
 }
 
-/** Build an SDKUserMessage from text + optional attachments */
+/** Build an SDKUserMessage from text + optional attachments.
+ *  Routing is delegated to the shared attachment-policy so all three harnesses
+ *  ingest identically. The Anthropic Messages API base64 document source accepts
+ *  ONLY application/pdf — handing it a docx/xlsx/csv/markdown/octet-stream 400s
+ *  the whole turn — so non-PDF binaries are NOT emitted as provider blocks; they
+ *  ride on the saved-files disk pointer instead. Blocks stay MEDIA-FIRST, TEXT-last. */
 function buildUserMessage(text: string, attachments?: AgentAttachment[], savedFiles?: SavedFile[]): SDKUserMessage {
   const content: any[] = [];
 
   if (attachments?.length) {
+    // Running budget so the cross-file inline-text total never exceeds the cap.
+    let inlineTextBudget = INLINE_TEXT_TOTAL_CHARS;
+
     for (const att of attachments) {
-      if (att.type === 'image') {
-        content.push({
-          type: 'image',
-          source: { type: 'base64', media_type: att.mediaType, data: att.data },
-        });
-      } else {
-        content.push({
-          type: 'document',
-          source: { type: 'base64', media_type: att.mediaType, data: att.data },
-        });
+      // Claude natively renders PDF document blocks (vision over the rendered pages).
+      const route = routeAttachment(att, { canNativeDocument: true });
+      switch (route) {
+        case 'image': {
+          // Drop the inline copy when it would bloat every stateless resend — the
+          // file is on disk and buildSavedFilesNote points the file tools at it.
+          if (approxBase64Bytes(att.data) > MAX_INLINE_IMAGE_BYTES) break;
+          content.push({
+            type: 'image',
+            source: { type: 'base64', media_type: normalizeImageMediaType(att.mediaType), data: att.data },
+          });
+          break;
+        }
+        case 'native-document': {
+          content.push({
+            type: 'document',
+            source: { type: 'base64', media_type: 'application/pdf', data: att.data },
+          });
+          break;
+        }
+        case 'inline-text': {
+          if (inlineTextBudget <= 0) break;
+          let decoded = '';
+          try {
+            decoded = Buffer.from(att.data, 'base64').toString('utf-8');
+          } catch {
+            break; // undecodable → rely on the saved-files note
+          }
+          const cap = Math.min(INLINE_TEXT_PER_FILE_CHARS, inlineTextBudget);
+          const slice = decoded.slice(0, cap);
+          inlineTextBudget -= slice.length;
+          // text/csv/markdown also 400 as document sources, so inline as a text note.
+          content.push({ type: 'text', text: `--- ${att.name} ---\n${slice}` });
+          break;
+        }
+        case 'reference-only':
+        default:
+          // Binary we can't inline (docx/xlsx/zip/…) or an unexpected route — no
+          // provider block; the saved-files note below carries the disk pointer.
+          break;
       }
     }
   }
 
   let promptText = text || '(attached files)';
   if (savedFiles?.length) {
-    const lines = savedFiles.map((f) => `- ${f.name} -> ${f.relPath}`);
-    promptText += `\n\n[Attached files saved to disk]\n${lines.join('\n')}\nYou can read or reference these files using the paths above (relative to your cwd).`;
+    const note = buildSavedFilesNote(savedFiles);
+    if (note) promptText += `\n\n${note}`;
   }
 
   content.push({ type: 'text', text: promptText });
@@ -663,8 +710,8 @@ export async function startBlobyAgentQuery(
 
   let plainPrompt = prompt;
   if (savedFiles?.length && !attachments?.length) {
-    const lines = savedFiles.map((f) => `- ${f.name} -> ${f.relPath}`);
-    plainPrompt += `\n\n[Attached files saved to disk]\n${lines.join('\n')}\nYou can read or reference these files using the paths above (relative to your cwd).`;
+    const note = buildSavedFilesNote(savedFiles);
+    if (note) plainPrompt += `\n\n${note}`;
   }
 
   const sdkPrompt: string | AsyncIterable<SDKUserMessage> =

package/supervisor/harnesses/codex.ts

@@ -44,6 +44,15 @@ import type { SavedFile } from '../file-saver.js';
 import { getCodexAccessToken } from '../../worker/codex-auth.js';
 import { assembleSystemPrompt } from '../../worker/prompts/prompt-assembler.js';
 import { mirrorSkillsInto } from './skills.js';
+import {
+  routeAttachment,
+  normalizeImageMediaType,
+  approxBase64Bytes,
+  buildSavedFilesNote,
+  INLINE_TEXT_PER_FILE_CHARS,
+  INLINE_TEXT_TOTAL_CHARS,
+  MAX_INLINE_IMAGE_BYTES,
+} from './attachment-policy.js';
 import type { OnAgentMessage, RecentMessage, AgentAttachment, AgentQueryRequest, AgentQueryResult } from './types.js';
 export type { RecentMessage, AgentAttachment };
 
@@ -555,42 +564,24 @@ function emitDone(conv: CodexConversation): void {
 
 /* ── Input building ────────────────────────────────────────────────────── */
 
-/** mediaTypes whose content we inline into the prompt — codex has no document
- *  input type (verified against 0.138 UserInput), so this is the closest we get
- *  to claude's native base64 document ingestion for text-like files. */
-const INLINE_TEXT_MEDIA = /^(text\/|application\/(json|xml|yaml|x-yaml|toml|csv|javascript|typescript))/;
-const INLINE_TEXT_MAX_BYTES = 48_000;
-const INLINE_TEXT_TOTAL_BUDGET = 96_000;
-
+/**
+ * Build codex `UserInput` blocks from the user text + saved files + raw
+ * attachments. Routing is delegated to the shared attachment-policy so codex
+ * stays byte-for-byte consistent with the Claude/PI harnesses. Codex's UserInput
+ * has NO native document type (verified against 0.138), so canNativeDocument is
+ * FALSE: PDFs/binaries become a disk-pointer note and the agent opens them with
+ * its file tools.
+ *
+ * Block order is MEDIA-first then TEXT (matching Claude/PI): the inline-text
+ * notes and the saved-files pointer are folded into the trailing text block.
+ */
 function buildUserInput(text: string, savedFiles?: SavedFile[], attachments?: AgentAttachment[]): Array<Record<string, any>> {
   const input: Array<Record<string, any>> = [];
 
-  let promptText = text || '(attached files)';
-  if (savedFiles?.length) {
-    const lines = savedFiles.map((f) => `- ${f.name} -> ${f.relPath}`);
-    promptText += `\n\n[Attached files saved to disk]\n${lines.join('\n')}\nYou can read or reference these files using the paths above (relative to your cwd).`;
-  }
-
-  // Inline text-like attachments (size-capped) so the model can answer about
-  // their contents immediately instead of shelling out to read them from disk.
-  if (attachments?.length) {
-    let budget = INLINE_TEXT_TOTAL_BUDGET;
-    for (const att of attachments) {
-      if (att.type !== 'file' || !INLINE_TEXT_MEDIA.test(att.mediaType || '')) continue;
-      const approxBytes = Math.floor((att.data?.length || 0) * 0.75);
-      if (approxBytes === 0 || approxBytes > INLINE_TEXT_MAX_BYTES || approxBytes > budget) continue;
-      try {
-        const decoded = Buffer.from(att.data, 'base64').toString('utf-8');
-        budget -= approxBytes;
-        promptText += `\n\n[Attached file content: ${att.name}]\n\`\`\`\n${decoded}\n\`\`\``;
-      } catch {}
-    }
-  }
-
-  input.push({ type: 'text', text: promptText });
-
   // Codex understands `localImage` (path on disk) — Bloby's file-saver already
-  // wrote attachments to disk, so we just point at the absolute path.
+  // wrote image attachments to disk, so we point at the absolute path. Track a
+  // per-name COUNT (not presence): WhatsApp multi-image pushes share one
+  // attachment name and each saved file covers exactly one of them.
   const savedImageCounts = new Map<string, number>();
   if (savedFiles?.length) {
     for (const f of savedFiles) {
@@ -601,23 +592,58 @@ function buildUserInput(text: string, savedFiles?: SavedFile[], attachments?: Ag
     }
   }
 
-  // Fallback for image attachments that never made it to disk (file-saver
-  // failure): inline as a data URL so the agent still SEES the image — claude
-  // always gets the base64 inline, codex shouldn't silently go blind.
-  // Match by COUNT, not name presence: WhatsApp multi-image pushes share one
-  // attachment name, and each saved file covers exactly one of them.
+  // Route every attachment through the shared policy. Inline-text notes are
+  // accumulated into `inlineNotes` (appended to the trailing text block);
+  // images become data-URL blocks (with the localImage path already covering
+  // disk-saved copies); everything else falls back to the saved-files pointer.
+  let promptText = text || '(attached files)';
+  const inlineNotes: string[] = [];
+  let inlineBudget = INLINE_TEXT_TOTAL_CHARS;
   if (attachments?.length) {
     for (const att of attachments) {
-      if (att.type !== 'image' || !att.data) continue;
-      const remaining = savedImageCounts.get(att.name) || 0;
-      if (remaining > 0) {
-        savedImageCounts.set(att.name, remaining - 1);
-        continue;
+      switch (routeAttachment(att, { canNativeDocument: false })) {
+        case 'image': {
+          if (!att.data) break;
+          // Skip data-URL inlining when a disk copy exists (localImage already
+          // points codex at it) or when the payload is too big to resend on
+          // every stateless turn — the saved-files pointer covers it instead.
+          const remaining = savedImageCounts.get(att.name) || 0;
+          if (remaining > 0) {
+            savedImageCounts.set(att.name, remaining - 1);
+            break;
+          }
+          if (approxBase64Bytes(att.data) > MAX_INLINE_IMAGE_BYTES) break;
+          const mediaType = normalizeImageMediaType(att.mediaType);
+          input.push({ type: 'image', url: `data:${mediaType};base64,${att.data}` });
+          break;
+        }
+        case 'inline-text': {
+          if (!att.data) break;
+          try {
+            let decoded = Buffer.from(att.data, 'base64').toString('utf-8');
+            if (decoded.length > INLINE_TEXT_PER_FILE_CHARS) decoded = decoded.slice(0, INLINE_TEXT_PER_FILE_CHARS);
+            if (decoded.length > inlineBudget) decoded = decoded.slice(0, inlineBudget);
+            if (!decoded.length) break;
+            inlineBudget -= decoded.length;
+            inlineNotes.push(`\n\n[Attached file content: ${att.name}]\n\`\`\`\n${decoded}\n\`\`\``);
+          } catch {}
+          break;
+        }
+        // 'native-document' cannot occur (canNativeDocument:false); it and
+        // 'reference-only' both rely on the saved-files disk pointer below.
+        default:
+          break;
       }
-      input.push({ type: 'image', url: `data:${att.mediaType};base64,${att.data}` });
     }
   }
 
+  for (const note of inlineNotes) promptText += note;
+
+  const savedNote = buildSavedFilesNote(savedFiles || []);
+  if (savedNote) promptText += `\n\n${savedNote}`;
+
+  input.push({ type: 'text', text: promptText });
+
   return input;
 }
 

package/supervisor/harnesses/pi/index.ts

@@ -29,11 +29,20 @@ import type {
 export type { RecentMessage, AgentAttachment };
 
 import { buildSkillsIndex } from '../skills.js';
+import {
+  routeAttachment,
+  buildSavedFilesNote,
+  normalizeImageMediaType,
+  approxBase64Bytes,
+  MAX_INLINE_IMAGE_BYTES,
+  INLINE_TEXT_PER_FILE_CHARS,
+  INLINE_TEXT_TOTAL_CHARS,
+} from '../attachment-policy.js';
 import { createAsyncQueue, type AsyncQueue } from './async-queue.js';
 import { createPiSession, type PiSessionEvent, type PiSessionAuth } from './session.js';
-import { getPiSubProvider, getCatalogModel } from './sub-providers.js';
+import { getPiSubProvider, getCatalogModel, type PiApiFlavor } from './sub-providers.js';
 import { readPiAuth } from './auth-storage.js';
-import type { PiMessage } from './providers/types.js';
+import type { PiMessage, PiContentBlock } from './providers/types.js';
 import { toolDefsForProvider } from './tools/registry.js';
 import type { PiTaskHost } from './tools/types.js';
 
@@ -495,62 +504,82 @@ function recentToPiMessages(messages: RecentMessage[] | undefined): PiMessage[]
   }));
 }
 
-const DOC_INLINE_CAP_CHARS = 48_000;
-
-/** Text-like documents can ride inline as decoded text on every flavor. */
-function isTextLikeMediaType(mediaType: string): boolean {
-  const mt = (mediaType || '').toLowerCase();
-  return (
-    mt.startsWith('text/') ||
-    mt.includes('json') ||
-    mt.includes('xml') ||
-    mt.includes('yaml') ||
-    mt.includes('csv') ||
-    mt.includes('javascript') ||
-    mt.includes('typescript') ||
-    mt === 'application/x-sh'
-  );
+/** Native PDF document blocks reach only the flavors that render them — the
+ *  Anthropic Messages API and Gemini both ingest application/pdf inline
+ *  (base64 document source / inlineData). openai-completions has no document
+ *  type, so a PDF there falls back to the saved-files disk pointer. Matches the
+ *  shared attachment-policy routing rule. */
+function canNativeDocumentForFlavor(flavor: PiApiFlavor): boolean {
+  return flavor === 'anthropic-messages' || flavor === 'google-gemini';
 }
 
-/** Wrap a raw user input into a PiMessage with text + optional image blocks. */
-function buildUserMessage(text: string, attachments?: AgentAttachment[], savedFiles?: SavedFile[]): PiMessage {
-  const content: PiMessage['content'] = [];
+/** Build a PiContentBlock[] from raw text + attachments, MEDIA-FIRST then the
+ *  prompt text last (parity with claude.ts and the other pi providers). Routing
+ *  is delegated to the shared attachment-policy so all three harnesses ingest
+ *  identically; canNativeDocument is the active provider's PDF capability. */
+function buildAttachmentBlocks(
+  text: string,
+  canNativeDocument: boolean,
+  attachments?: AgentAttachment[],
+  savedFiles?: SavedFile[],
+): PiContentBlock[] {
+  const content: PiContentBlock[] = [];
   if (attachments?.length) {
+    // Running budget so the cross-file inline-text total never exceeds the cap.
+    let inlineTextBudget = INLINE_TEXT_TOTAL_CHARS;
     for (const att of attachments) {
-      if (att.type === 'image') {
-        content.push({ type: 'image', mediaType: att.mediaType, data: att.data });
-      } else if (isTextLikeMediaType(att.mediaType)) {
-        // Text-like documents are inlined (codex-parity posture, audit D5-7):
-        // claude sends native document blocks; pi inlines the decoded text,
-        // capped so a huge file can't blow the context.
-        let docText = '';
-        try { docText = Buffer.from(att.data, 'base64').toString('utf-8'); } catch {}
-        const capped = docText.length > DOC_INLINE_CAP_CHARS
-          ? `${docText.slice(0, DOC_INLINE_CAP_CHARS)}\n…[truncated at ${DOC_INLINE_CAP_CHARS} characters — the full file is in the saved-files note below]`
-          : docText;
-        content.push({
-          type: 'text',
-          text: capped
-            ? `[Attached document: ${att.name} (${att.mediaType})]\n${capped}\n[End of ${att.name}]`
-            : `[Attached document: ${att.name} (${att.mediaType}) — could not decode]`,
-        });
-      } else {
-        // Binary documents (PDF etc.) can't be inlined across all
-        // sub-providers — point the model at the saved copy instead.
-        content.push({
-          type: 'text',
-          text: `[Attached document: ${att.name} (${att.mediaType}). It is saved to disk — see the saved-files note below and use your tools to inspect it if needed.]`,
-        });
+      switch (routeAttachment(att, { canNativeDocument })) {
+        case 'image': {
+          // Drop the inline copy when it would bloat every stateless resend —
+          // the file is on disk and buildSavedFilesNote points the tools at it.
+          if (approxBase64Bytes(att.data) > MAX_INLINE_IMAGE_BYTES) break;
+          content.push({ type: 'image', mediaType: normalizeImageMediaType(att.mediaType), data: att.data });
+          break;
+        }
+        case 'native-document': {
+          // PDF on a flavor that renders it natively (anthropic / gemini).
+          content.push({ type: 'document', mediaType: 'application/pdf', data: att.data, name: att.name });
+          break;
+        }
+        case 'inline-text': {
+          if (inlineTextBudget <= 0) break;
+          let decoded = '';
+          try { decoded = Buffer.from(att.data, 'base64').toString('utf-8'); }
+          catch { break; } // undecodable → rely on the saved-files note
+          const cap = Math.min(INLINE_TEXT_PER_FILE_CHARS, inlineTextBudget);
+          const slice = decoded.slice(0, cap);
+          inlineTextBudget -= slice.length;
+          content.push({ type: 'text', text: `--- ${att.name} ---\n${slice}` });
+          break;
+        }
+        case 'reference-only':
+        default:
+          // Binary we can't inline (docx/xlsx/zip/…), a PDF on a flavor without
+          // native documents, or an unexpected route — no provider block; the
+          // saved-files note below carries the disk pointer. Never emit a
+          // malformed block (defensive default, review PI-E).
+          break;
       }
     }
   }
+
   let prompt = text || '(attached files)';
   if (savedFiles?.length) {
-    const lines = savedFiles.map((f) => `- ${f.name} -> ${f.relPath}`);
-    prompt += `\n\n[Attached files saved to disk]\n${lines.join('\n')}\nYou can read or reference these files using the paths above (relative to your cwd).`;
+    const note = buildSavedFilesNote(savedFiles);
+    if (note) prompt += `\n\n${note}`;
   }
   content.push({ type: 'text', text: prompt });
-  return { role: 'user', content };
+  return content;
+}
+
+/** Wrap a raw user input into a PiMessage with text + optional media blocks. */
+function buildUserMessage(
+  text: string,
+  canNativeDocument: boolean,
+  attachments?: AgentAttachment[],
+  savedFiles?: SavedFile[],
+): PiMessage {
+  return { role: 'user', content: buildAttachmentBlocks(text, canNativeDocument, attachments, savedFiles) };
 }
 
 // ── Live Conversation API ──────────────────────────────────────────────────
@@ -771,7 +800,13 @@ export function pushMessage(
   conv.busy = true;
   conv.pendingCount += 1;
   conv.turnOrigins.push('user');
-  conv.inputQueue.push(buildUserMessage(content, attachments, savedFiles));
+  // Resolve the active flavor at push time (the session re-resolves auth every
+  // round, so a wizard provider switch mid-session is honored). Unreadable auth
+  // ⇒ no native documents — the conservative route sends a PDF to the disk
+  // pointer rather than emitting a block the provider can't render.
+  const resolved = resolveAuth();
+  const canNativeDocument = resolved.ok ? canNativeDocumentForFlavor(resolved.auth.flavor) : false;
+  conv.inputQueue.push(buildUserMessage(content, canNativeDocument, attachments, savedFiles));
   conv.onMessage('bot:typing', { conversationId });
   return true;
 }
@@ -981,7 +1016,7 @@ export async function startBlobyAgentQuery(
     });
 
     const queue = createAsyncQueue<PiMessage>();
-    queue.push(buildUserMessage(prompt, attachments, savedFiles));
+    queue.push(buildUserMessage(prompt, canNativeDocumentForFlavor(resolved.auth.flavor), attachments, savedFiles));
     queue.end();
     await session.run(queue);
 

package/supervisor/harnesses/pi/providers/humanize-error.ts

@@ -48,6 +48,18 @@ const AUTH_RE =
 const BILLING_RE =
   /insufficient_quota|credit balance is too low|payment required|purchase more credits/i;
 
+// A text-only model rejecting an attached image. Vendors phrase it many ways:
+// OpenAI "Invalid content type. image_url is only supported by certain models",
+// OpenRouter "No endpoints found that support image input", others mention
+// "image input" / "does not support images" / "unsupported content type".
+// Only EXPLICIT image-naming phrases — the bare tokens "vision"/"multimodal"/
+// "modality" were removed because the provider body routinely echoes the model id
+// (e.g. "gpt-4-vision-preview", "llama-3.2-90b-vision-instruct"), which would
+// mis-classify an unrelated 400 from a vision-capable model and wrongly disable
+// vision for the rest of the session. Paired with a 400/415/422 status below.
+const IMAGE_UNSUPPORTED_RE =
+  /image[_ ]?url|image input|images?(?: are| is)? not supported|does not support images?|no endpoints? .*support image|unsupported content type/i;
+
 export function classifyPiError(
   providerLabel: string,
   status: number | undefined,
@@ -85,6 +97,19 @@ export function classifyPiError(
       message: `${providerLabel} rejected your API key. Update it from the dashboard (Bloby provider settings).${suffix}`,
     };
   }
+  // A text-only model that the catalog couldn't flag up front (dynamic/unknown
+  // sub-providers) 400/415/422s on the attached image. The session reacts by
+  // disabling vision for the rest of the session and re-running the round with
+  // images downgraded — self-healing so a single screenshot can't permanently
+  // 400-poison the conversation (it rides every stateless resend otherwise).
+  if ((status === 400 || status === 415 || status === 422) && IMAGE_UNSUPPORTED_RE.test(body)) {
+    return {
+      kind: 'image-unsupported',
+      retryable: false,
+      status,
+      message: `${providerLabel} rejected the attached image — this model appears to be text-only. Retrying without the image; switch to a vision-capable model to send images.${suffix}`,
+    };
+  }
   if (status === 429) {
     return {
       kind: 'rate-limit',

package/supervisor/harnesses/pi/providers/stream-anthropic.ts

@@ -89,6 +89,14 @@ function toAnthropicContent(blocks: PiContentBlock[]): any[] {
         type: 'image',
         source: { type: 'base64', media_type: b.mediaType, data: b.data },
       });
+    } else if (b.type === 'document') {
+      // Native PDF document block — the Messages API renders the pages and the
+      // model reads them as vision. The base64 document source accepts ONLY
+      // application/pdf (buildUserMessage gates it on canNativeDocument).
+      out.push({
+        type: 'document',
+        source: { type: 'base64', media_type: b.mediaType, data: b.data },
+      });
     } else if (b.type === 'tool_use') {
       out.push({
         type: 'tool_use',

package/supervisor/harnesses/pi/providers/stream-google.ts

@@ -102,6 +102,11 @@ function toGeminiParts(content: PiContentBlock[]): any[] {
       parts.push({ text: b.text });
     } else if (b.type === 'image') {
       parts.push({ inlineData: { mimeType: b.mediaType, data: b.data } });
+    } else if (b.type === 'document') {
+      // Gemini ingests application/pdf inline via the same inlineData shape as
+      // images (it OCRs/renders the document). buildUserMessage only routes a
+      // document block here when the flavor supports it.
+      parts.push({ inlineData: { mimeType: b.mediaType, data: b.data } });
     } else if (b.type === 'tool_use') {
       // Assistant turn: the model asked to invoke a tool. Thinking-capable
       // Gemini 3.x rejects (HTTP 400) any echoed functionCall whose

package/supervisor/harnesses/pi/providers/stream-openai-completions.ts

@@ -119,24 +119,33 @@ function toOpenAIMessages(pi: PiMessage[]): any[] {
       out.push(msg);
       continue;
     }
-    // role === 'user' with non-tool-result content (text + optional images)
+    // role === 'user' with non-tool-result content (text + optional images).
+    // Media parts go first; text is appended last (parity with the other
+    // providers and pi/index's media-first block ordering).
     const contentBlocks: any[] = [];
     let plainText = '';
-    let hasImage = false;
+    let hasMedia = false;
     for (const b of m.content) {
       if (b.type === 'text') {
         plainText += (plainText ? '\n' : '') + b.text;
       } else if (b.type === 'image') {
-        hasImage = true;
+        hasMedia = true;
         contentBlocks.push({
           type: 'image_url',
           image_url: { url: `data:${b.mediaType};base64,${b.data}` },
         });
+      } else if (b.type === 'document') {
+        // The Chat Completions schema has no document part — degrade to a text
+        // note rather than crashing. The file is also on disk (saved-files
+        // note), so the agent can open it with its tools. This shouldn't
+        // normally happen: buildUserMessage gates documents on canNativeDocument
+        // (false for this flavor), so a PDF here rides as the disk pointer.
+        plainText += (plainText ? '\n' : '') +
+          `[Attached document${b.name ? ` "${b.name}"` : ''} (${b.mediaType}) could not be inlined for this model — it is saved to disk; open it with your file tools.]`;
       }
     }
-    if (hasImage) {
-      // Mixed image+text: prepend text part to the content array.
-      if (plainText) contentBlocks.unshift({ type: 'text', text: plainText });
+    if (hasMedia) {
+      if (plainText) contentBlocks.push({ type: 'text', text: plainText });
       out.push({ role: 'user', content: contentBlocks });
     } else {
       out.push({ role: 'user', content: plainText });

package/supervisor/harnesses/pi/providers/types.ts

@@ -17,6 +17,11 @@ export type PiRole = 'user' | 'assistant' | 'tool';
 export type PiContentBlock =
   | { type: 'text'; text: string }
   | { type: 'image'; mediaType: string; data: string }   // base64
+  // Native document block (PDF). Only the flavors with native document support
+  // (anthropic-messages, google-gemini) ever receive one — buildUserMessage
+  // gates it on canNativeDocument; openai-completions degrades it to a text
+  // note rather than crashing if one ever reaches it.
+  | { type: 'document'; mediaType: string; data: string; name?: string }  // base64
   // `thoughtSignature` is a Gemini 3.x thinking-model field. Pi-flavored
   // providers that emit reasoning attach it to function-call parts; the API
   // rejects the next turn with HTTP 400 if we don't echo it back verbatim.
@@ -74,7 +79,19 @@ export type PiStopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'error' | 'a
  * string-matching: retry transient rounds, tear down on auth/overflow, and
  * show actionable messages instead of raw provider JSON.
  */
-export type PiErrorKind = 'auth' | 'context-overflow' | 'rate-limit' | 'billing' | 'transient' | 'other';
+export type PiErrorKind =
+  | 'auth'
+  | 'context-overflow'
+  | 'rate-limit'
+  | 'billing'
+  | 'transient'
+  /** The model rejected an image/vision/modality block (a text-only model 400/
+   *  415/422s on the attached image). The session reacts by disabling vision
+   *  for the rest of the session and re-running the round with images
+   *  downgraded to placeholders — self-healing for dynamic/unknown models whose
+   *  catalog can't tell us up front whether they see images. */
+  | 'image-unsupported'
+  | 'other';
 
 export type PiStreamEvent =
   | { type: 'text_delta'; delta: string }

package/supervisor/harnesses/pi/session.ts

@@ -181,6 +181,14 @@ export function createPiSession(init: PiSessionInit): PiSession {
   let lastUsage: PiUsage | undefined;
   let lastContextWindow: number | undefined;
 
+  // Self-healing vision (audit D rank 12): when a model the catalog couldn't
+  // classify (dynamic/unknown sub-providers ⇒ supportsImages undefined) rejects
+  // an image with an 'image-unsupported' error, latch this for the rest of the
+  // session and downgrade images on every subsequent send. The IMAGE stays in
+  // history (downgradeImages is transform-on-send only), so switching to a
+  // vision-capable model later restores it.
+  let visionDisabled = false;
+
   /** One stream round — collect the assistant blocks the model emits this pass. */
   interface RoundResult {
     text: string;
@@ -204,7 +212,11 @@ export function createPiSession(init: PiSessionInit): PiSession {
         baseUrl: auth.baseUrl,
         apiKey: auth.apiKey,
         systemPrompt: init.systemPrompt,
-        messages: auth.supportsImages === false ? downgradeImages(messages) : messages,
+        // Downgrade images when the catalog says text-only (supportsImages
+        // false) OR a prior round in THIS session learned it the hard way via
+        // an 'image-unsupported' error (visionDisabled). The stored history
+        // keeps the image so a later vision-capable model still restores it.
+        messages: auth.supportsImages === false || visionDisabled ? downgradeImages(messages) : messages,
         tools: init.tools,
         toolChoice: opts?.wrapUp ? 'none' : undefined,
         maxOutputTokens: auth.maxOutputTokens,
@@ -330,6 +342,21 @@ export function createPiSession(init: PiSessionInit): PiSession {
         res = await runOneRound(needsSeparator);
       }
 
+      // Self-healing vision (audit D rank 12): a model the catalog couldn't
+      // classify just 400/415/422'd on an attached image. Latch visionDisabled
+      // and re-run the round ONCE — runOneRound now downgrades images on send,
+      // so the resend succeeds. Guarded by !visionDisabled so it fires at most
+      // once per session; an image rides every stateless resend, so without
+      // this the whole conversation would keep re-400ing.
+      if (
+        res.errored && res.errorKind === 'image-unsupported' && !visionDisabled &&
+        !init.abortController.signal.aborted
+      ) {
+        log.info('[pi/session] model rejected image — disabling vision for this session and retrying without it');
+        visionDisabled = true;
+        res = await runOneRound(needsSeparator);
+      }
+
       const { text, toolUses, errored } = res;
 
       // Append whatever the model produced this round to history so subsequent