bloby-bot 0.70.13 → 0.71.0

package/supervisor/channels/manager.ts

@@ -29,7 +29,7 @@ import { AlexaChannel } from './alexa.js';
 import { TelegramChannel, type TelegramInbound } from './telegram.js';
 import type { ChannelConfig, ChannelProvider, ChannelStatus, ChannelType, InboundMessage, InboundMessageAttachment, RoutingTarget, SenderRole } from './types.js';
 import type { AgentAttachment } from '../bloby-agent.js';
-import { saveAttachment, type SavedFile } from '../file-saver.js';
+import { saveAttachment, MAX_ATTACHMENTS_PER_MESSAGE, MAX_TOTAL_ATTACHMENT_BYTES, type SavedFile } from '../file-saver.js';
 import type { WAMessageKey } from '@whiskeysockets/baileys';
 
 const MAX_CONCURRENT_AGENTS = 5;
@@ -37,16 +37,34 @@ const MAX_BUFFER_MESSAGES = 30;
 const DEBOUNCE_MS = 4000; // 4s — wait for the user to finish typing
 
 /** Persist channel-inbound attachments to disk so harnesses that consume file
- *  paths (Codex's `localImage`) can see them. Failures are logged and the
- *  attachment is dropped — text-only delivery is still useful. */
-function saveInboundAttachments(attachments?: AgentAttachment[]): SavedFile[] {
-  if (!attachments?.length) return [];
+ *  paths (Codex's `localImage`) can see them. Per-file failures are logged and that
+ *  attachment is dropped — one oversize/corrupt file can't abort the whole message,
+ *  and text-only delivery still goes through. Bounded by MAX_ATTACHMENTS_PER_MESSAGE
+ *  (count) and MAX_TOTAL_ATTACHMENT_BYTES (decoded bytes) so a single message can't
+ *  flood the disk; saveAttachment itself caps each file's size. */
+function saveInboundAttachments(attachments?: AgentAttachment[]): { saved: SavedFile[]; accepted: AgentAttachment[] } {
+  if (!attachments?.length) return { saved: [], accepted: [] };
+  const capped = attachments.slice(0, MAX_ATTACHMENTS_PER_MESSAGE);
+  if (attachments.length > capped.length) {
+    log.warn(`[channels] Dropping ${attachments.length - capped.length} inbound attachment(s) over the per-message cap (${MAX_ATTACHMENTS_PER_MESSAGE})`);
+  }
   const saved: SavedFile[] = [];
-  for (const att of attachments) {
-    try { saved.push(saveAttachment(att)); }
+  // The raw attachments that actually saved within budget — handed to the harness so the
+  // model inlines exactly what got persisted + shown in chat (no over-cap divergence).
+  const accepted: AgentAttachment[] = [];
+  let totalBytes = 0;
+  for (const att of capped) {
+    // Estimate decoded size from the base64 length (×3/4) before writing so a burst of
+    // mid-size files can't blow the per-message byte budget in aggregate.
+    totalBytes += Math.floor((att.data?.length || 0) * 0.75);
+    if (totalBytes > MAX_TOTAL_ATTACHMENT_BYTES) {
+      log.warn('[channels] Per-message attachment byte budget exceeded — dropping remaining inbound attachments');
+      break;
+    }
+    try { saved.push(saveAttachment(att)); accepted.push(att); }
     catch (err: any) { log.warn(`[channels] Failed to save inbound attachment: ${err.message}`); }
   }
-  return saved;
+  return { saved, accepted };
 }
 
 interface ChannelManagerOpts {
@@ -144,8 +162,8 @@ export class ChannelManager {
     if (channelConfigs?.whatsapp?.enabled && !this.providers.has('whatsapp')) {
       log.info('[channels] Initializing WhatsApp channel...');
       const whatsapp = new WhatsAppChannel(
-        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, images, inboundKey) => {
-          const attachments = images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, media, inboundKey) => {
+          const attachments = media?.map((att) => ({ type: att.type, mediaType: att.mediaType, data: att.data, name: att.name }));
           this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, attachments, inboundKey);
         },
         (status) => this.handleStatusChange(status),
@@ -211,7 +229,7 @@ export class ChannelManager {
       }
     }
     const isOwner = !!ownerUserId && msg.fromUserId === String(ownerUserId);
-    const attachments = msg.images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+    const attachments = msg.attachments?.map((att) => ({ type: att.type, mediaType: att.mediaType, data: att.data, name: att.name }));
     // Sanitize the attacker-controlled display name so it can't fake a `[Telegram | … | admin]`
     // context tag or inject newlines into the agent's context.
     const safeName = msg.senderName ? msg.senderName.replace(/[\[\]|\r\n]/g, ' ').slice(0, 64).trim() || undefined : undefined;
@@ -236,8 +254,8 @@ export class ChannelManager {
     if (provider?.getStatus().connected) return;
     if (!provider) {
       const whatsapp = new WhatsAppChannel(
-        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, images, inboundKey) => {
-          const attachments = images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, media, inboundKey) => {
+          const attachments = media?.map((att) => ({ type: att.type, mediaType: att.mediaType, data: att.data, name: att.name }));
           this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, attachments, inboundKey);
         },
         (status) => this.handleStatusChange(status),
@@ -992,12 +1010,34 @@ export class ChannelManager {
     const channelTag = `[${this.channelLabel(msg.channel)} | ${msg.sender} | ${earlyRoleTag}]\n`;
     const displayContent = channelTag + rawDisplay;
 
+    // Convert inbound attachments to agent format and persist them to disk BEFORE the
+    // user-message persist/broadcast — so the StoredAttachment array (filePath-based, served
+    // at /api/files/<relPath>) can ride along in meta.attachments + chat:sync. Without this
+    // the agent sees the media but the chat shows nothing (live or after refresh). An image
+    // keeps an auto-generated name; a file uses the channel-provided filename. (Mirrors the
+    // PWA path in supervisor/index.ts.)
+    const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
+      type: att.type,
+      name: att.type === 'image'
+        ? `${msg.channel}_image.${att.mediaType.split('/')[1] || 'jpg'}`
+        : (att.name || `${msg.channel}_file`),
+      mediaType: att.mediaType,
+      data: att.data,
+    }));
+    // Save to disk so providers that consume file paths (Codex → localImage) can see the
+    // attachment. Claude consumes raw base64 from `agentAttachments` directly, but the
+    // on-disk copy is what the chat UI renders (filePath → /api/files/<relPath>).
+    const { saved: savedFiles, accepted: acceptedAttachments } = saveInboundAttachments(agentAttachments);
+    const storedAtts = savedFiles.map((f) => ({ type: f.type, name: f.name, mediaType: f.mediaType, filePath: f.relPath }));
+
     // Save user message to DB
     try {
+      const userMeta: any = { model, channel: msg.channel };
+      if (storedAtts.length) userMeta.attachments = JSON.stringify(storedAtts);
       await workerApi(`/api/conversations/${convId}/messages`, 'POST', {
         role: 'user',
         content: displayContent,
-        meta: { model, channel: msg.channel },
+        meta: userMeta,
       });
     } catch (err: any) {
       log.warn(`[channels] DB persist error: ${err.message}`);
@@ -1006,7 +1046,12 @@ export class ChannelManager {
     // Broadcast to chat clients (mirroring)
     broadcastBloby('chat:sync', {
       conversationId: convId,
-      message: { role: 'user', content: displayContent, timestamp: new Date().toISOString() },
+      message: {
+        role: 'user',
+        content: displayContent,
+        timestamp: new Date().toISOString(),
+        attachments: storedAtts.length ? storedAtts : undefined,
+      },
     });
 
     // Fetch names and recent messages
@@ -1033,18 +1078,6 @@ export class ChannelManager {
     // Channel context — same tag we already prepended to the stored display content
     const channelContext = channelTag;
 
-    // Convert inbound attachments to agent format
-    const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
-      type: 'image' as const,
-      name: `whatsapp_image.${att.mediaType.split('/')[1] || 'jpg'}`,
-      mediaType: att.mediaType,
-      data: att.data,
-    }));
-    // Save to disk so providers that consume file paths (Codex → localImage)
-    // can see the attachment. Claude consumes raw base64 from `agentAttachments`
-    // directly, but the on-disk copy is still useful for the path mention.
-    const savedFiles = saveInboundAttachments(agentAttachments);
-
     // Show "typing..." in the correct chat
     this.startTyping(msg.channel, msg.rawSender);
 
@@ -1127,7 +1160,7 @@ export class ChannelManager {
       assistantBufferKey: msg.role === 'assistant' ? `${msg.channel}:${msg.sender}` : undefined,
       inboundKey: msg.inboundKey,
     };
-    this.pushWithRouting(convId, target, channelContent, agentAttachments, savedFiles);
+    this.pushWithRouting(convId, target, channelContent, acceptedAttachments, savedFiles);
   }
 
   /** Synchronously handle an Alexa utterance: push into the shared conversation,
@@ -1338,14 +1371,16 @@ export class ChannelManager {
 
     const channelContext = `[${this.channelLabel(msg.channel)} | ${msg.sender} | customer${msg.senderName ? ` | ${msg.senderName}` : ''}]\n`;
 
-    // Convert inbound attachments to agent format
+    // Convert inbound attachments to agent format (image → auto-name; file → channel filename)
     const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
-      type: 'image' as const,
-      name: `whatsapp_image.${att.mediaType.split('/')[1] || 'jpg'}`,
+      type: att.type,
+      name: att.type === 'image'
+        ? `${msg.channel}_image.${att.mediaType.split('/')[1] || 'jpg'}`
+        : (att.name || `${msg.channel}_file`),
       mediaType: att.mediaType,
       data: att.data,
     }));
-    const savedFiles = saveInboundAttachments(agentAttachments);
+    const { saved: savedFiles, accepted: acceptedAttachments } = saveInboundAttachments(agentAttachments);
 
     // Stable convId per customer (not per message)
     const convId = `channel-${agentKey}`;
@@ -1404,7 +1439,7 @@ export class ChannelManager {
           this.processQueue();
         }
       },
-      agentAttachments,
+      acceptedAttachments,
       savedFiles,
       { botName, humanName },
       recentMessages,

package/supervisor/channels/telegram.ts

@@ -20,10 +20,14 @@ const POLL_TIMEOUT_S = 25;          // long-poll hold time
 const MAX_MESSAGE_CHARS = 4096;     // Telegram hard limit per sendMessage
 const TYPING_REFRESH_MS = 5_000;    // Telegram "typing" expires ~5s
 
-/** Image extracted from an inbound Telegram message. */
-export interface TelegramImageAttachment {
+/** Media attachment extracted from an inbound Telegram message.
+ *  `type: 'image'` → inline vision; `type: 'file'` → a document the agent reads from disk. */
+export interface TelegramMediaAttachment {
+  type: 'image' | 'file';
   mediaType: string;
   data: string; // base64
+  /** Original filename — present for documents, absent for photos. */
+  name?: string;
 }
 
 /** Normalized inbound message handed to the ChannelManager. */
@@ -37,7 +41,7 @@ export interface TelegramInbound {
   text: string;
   isGroup: boolean;
   messageId?: number;
-  images?: TelegramImageAttachment[];
+  attachments?: TelegramMediaAttachment[];
 }
 
 export type OnTelegramMessage = (msg: TelegramInbound) => void;
@@ -236,13 +240,27 @@ export class TelegramChannel implements ChannelProvider {
       : (from.username || undefined);
 
     let rawText: string = message.text || message.caption || '';
-    const images: TelegramImageAttachment[] = [];
+    const attachments: TelegramMediaAttachment[] = [];
 
-    // Photo: download the largest available size.
+    // Photo: download the largest available size. Derive the real mediaType from the CDN
+    // file extension (Telegram stores PNG/JPEG/WebP as-is) — default to image/jpeg only when unknown.
     if (Array.isArray(message.photo) && message.photo.length > 0) {
       const largest = message.photo[message.photo.length - 1];
       const img = await this.downloadFile(largest.file_id).catch(() => null);
-      if (img) images.push({ mediaType: 'image/jpeg', data: img.toString('base64') });
+      if (img) attachments.push({ type: 'image', mediaType: mimeFromPath(img.filePath, 'image/jpeg'), data: img.buffer.toString('base64') });
+    }
+
+    // Document: download the binary and forward as a file the agent reads from disk.
+    if (message.document?.file_id) {
+      const doc = await this.downloadFile(message.document.file_id).catch(() => null);
+      if (doc) {
+        attachments.push({
+          type: 'file',
+          mediaType: message.document.mime_type || mimeFromPath(doc.filePath, 'application/octet-stream'),
+          data: doc.buffer.toString('base64'),
+          name: message.document.file_name || undefined,
+        });
+      }
     }
 
     // Voice note / audio: download + transcribe.
@@ -252,9 +270,9 @@ export class TelegramChannel implements ChannelProvider {
         await this.sendMessage(chatId, 'Voice transcription is off — add an OpenAI API key in your Bloby chat settings (the three-dots menu) to enable it.');
         return;
       }
-      const buf = await this.downloadFile(voice.file_id).catch(() => null);
-      if (buf) {
-        const transcript = await this.transcribe(buf.toString('base64')).catch(() => null);
+      const got = await this.downloadFile(voice.file_id).catch(() => null);
+      if (got) {
+        const transcript = await this.transcribe(got.buffer.toString('base64')).catch(() => null);
         if (transcript) {
           rawText = transcript;
           log.info(`[telegram] Transcribed voice: "${rawText.slice(0, 80)}"`);
@@ -265,12 +283,23 @@ export class TelegramChannel implements ChannelProvider {
       }
     }
 
-    if (!rawText && images.length === 0) return;
-    if (!rawText && images.length > 0) rawText = '(image)';
+    // Nothing usable extracted. If the message DID carry media we couldn't handle
+    // (sticker, video, location, contact, …), tell the user instead of dropping it silently.
+    if (!rawText && attachments.length === 0) {
+      const hadUnsupportedMedia = !!(message.sticker || message.video || message.video_note ||
+        message.animation || message.location || message.contact || message.poll || message.dice);
+      if (hadUnsupportedMedia) {
+        await this.sendMessage(chatId, "Sorry, I can't read that type of message yet — try sending text, a photo, or a document.");
+      }
+      return;
+    }
+    if (!rawText && attachments.length > 0) {
+      rawText = attachments.some((a) => a.type === 'image') ? '(image)' : '(document)';
+    }
 
     const text = escapeMessageText(rawText);
 
-    log.info(`[telegram] Message from ${fromUserId} (chat=${chatId}, group=${isGroup}, images=${images.length}): ${text.slice(0, 80)}`);
+    log.info(`[telegram] Message from ${fromUserId} (chat=${chatId}, group=${isGroup}, media=${attachments.length}): ${text.slice(0, 80)}`);
 
     this.onMessage({
       chatId,
@@ -279,12 +308,13 @@ export class TelegramChannel implements ChannelProvider {
       text,
       isGroup,
       messageId: message.message_id,
-      images: images.length > 0 ? images : undefined,
+      attachments: attachments.length > 0 ? attachments : undefined,
     });
   }
 
-  /** Resolve a Telegram file_id to its bytes (getFile → download from the file CDN). */
-  private async downloadFile(fileId: string): Promise<Buffer | null> {
+  /** Resolve a Telegram file_id to its bytes (getFile → download from the file CDN).
+   *  Also returns the CDN file_path so callers can derive an extension/mediaType. */
+  private async downloadFile(fileId: string): Promise<{ buffer: Buffer; filePath: string } | null> {
     const file = await this.call('getFile', { file_id: fileId });
     const filePath = file?.file_path;
     if (!filePath) return null;
@@ -292,7 +322,7 @@ export class TelegramChannel implements ChannelProvider {
     if (!r.ok) throw new Error(`file download HTTP ${r.status}`);
     const buf = Buffer.from(await r.arrayBuffer());
     log.info(`[telegram] Downloaded file (${Math.round(buf.length / 1024)}KB)`);
-    return buf;
+    return { buffer: buf, filePath };
   }
 
   /** Call a Bot API method, returning `result` or throwing on `ok:false`. */
@@ -336,6 +366,17 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/** Best-effort mime type from a file path's extension; returns `fallback` when unknown.
+ *  Used for Telegram photos/documents where the API doesn't always supply a mime_type. */
+function mimeFromPath(filePath: string | undefined, fallback: string): string {
+  const ext = (filePath?.split('.').pop() || '').toLowerCase();
+  const map: Record<string, string> = {
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
+    pdf: 'application/pdf', zip: 'application/zip', txt: 'text/plain', csv: 'text/csv', json: 'application/json',
+  };
+  return map[ext] || fallback;
+}
+
 /** Split a long message into <=limit-char chunks, preferring newline boundaries. */
 function splitMessage(text: string, limit: number): string[] {
   if (text.length <= limit) return [text];

package/supervisor/channels/types.ts

@@ -23,9 +23,12 @@ export interface ChannelConfig {
 }
 
 export interface InboundMessageAttachment {
-  type: 'image';
+  /** 'image' → inline vision block; 'file' → any document the agent reads from disk. */
+  type: 'image' | 'file';
   mediaType: string;
   data: string; // base64
+  /** Original filename when the channel provides one (WhatsApp/Telegram documents). */
+  name?: string;
 }
 
 export interface InboundMessage {

package/supervisor/channels/whatsapp.ts

@@ -24,16 +24,21 @@ import type { ChannelProvider, ChannelStatus, ChannelType } from './types.js';
 
 const AUTH_DIR = path.join(DATA_DIR, 'channels', 'whatsapp', 'auth');
 
-/** Image attachment extracted from a WhatsApp message */
-export interface WhatsAppImageAttachment {
+/** Media attachment extracted from a WhatsApp message.
+ *  `type: 'image'` → inline vision; `type: 'file'` → a document the agent reads from disk. */
+export interface WhatsAppMediaAttachment {
+  type: 'image' | 'file';
   mediaType: string;
   data: string; // base64
+  /** Original filename — present for documents (WhatsApp supplies it), absent for images. */
+  name?: string;
 }
 
 /** Callback when a new message arrives.
  * - sender: who sent it (phone JID, translated from LID where possible)
  * - chatJid: the conversation identifier (group JID for groups, peer JID for 1:1) — reply to this
  * - isGroup: true when the chat is a WhatsApp group (@g.us)
+ * - media: image and/or document attachments extracted from the message
  * - inboundKey: original Baileys message key — used to react/quote/ack the user's message
  */
 export type OnWhatsAppMessage = (
@@ -44,7 +49,7 @@ export type OnWhatsAppMessage = (
   isSelfChat: boolean,
   chatJid: string,
   isGroup: boolean,
-  images?: WhatsAppImageAttachment[],
+  media?: WhatsAppMediaAttachment[],
   inboundKey?: WAMessageKey,
 ) => void;
 
@@ -576,7 +581,7 @@ export class WhatsAppChannel implements ChannelProvider {
 
         // Extract text — or transcribe audio if it's a voice note
         let rawText = this.extractText(msg.message);
-        const images: WhatsAppImageAttachment[] = [];
+        const media: WhatsAppMediaAttachment[] = [];
 
         // Download image if present
         if (this.isImageMessage(msg.message)) {
@@ -584,13 +589,32 @@ export class WhatsAppChannel implements ChannelProvider {
             const buffer = await downloadMediaMessage(msg, 'buffer', {}) as Buffer;
             const mimeType = this.getImageMimeType(msg.message) || 'image/jpeg';
             const base64 = buffer.toString('base64');
-            images.push({ mediaType: mimeType, data: base64 });
+            media.push({ type: 'image', mediaType: mimeType, data: base64 });
             log.info(`[whatsapp] Downloaded image (${Math.round(buffer.length / 1024)}KB, ${mimeType})`);
           } catch (err: any) {
             log.warn(`[whatsapp] Image download failed: ${err.message}`);
           }
         }
 
+        // Download document if present (PDF, docx, zip, etc.) — the binary is downloaded
+        // here (the caption, if any, is already covered by extractText above).
+        const docInfo = this.getDocumentInfo(msg.message);
+        if (docInfo) {
+          try {
+            const buffer = await downloadMediaMessage(msg, 'buffer', {}) as Buffer;
+            const base64 = buffer.toString('base64');
+            media.push({
+              type: 'file',
+              mediaType: docInfo.mimetype || 'application/octet-stream',
+              data: base64,
+              name: docInfo.fileName,
+            });
+            log.info(`[whatsapp] Downloaded document (${Math.round(buffer.length / 1024)}KB, ${docInfo.mimetype || 'unknown'}, ${docInfo.fileName || 'unnamed'})`);
+          } catch (err: any) {
+            log.warn(`[whatsapp] Document download failed: ${err.message}`);
+          }
+        }
+
         if (!rawText && this.isAudioMessage(msg.message)) {
           // Voice note / audio — download and transcribe
           if (!this.transcribe) {
@@ -616,11 +640,11 @@ export class WhatsAppChannel implements ChannelProvider {
           }
         }
 
-        // Skip if no text AND no images; otherwise default text for image-only
+        // Skip if no text AND no media; otherwise default text for media-only
         // messages. Collapsing both branches also narrows `rawText` to `string`.
         if (!rawText) {
-          if (images.length === 0) continue;
-          rawText = '(image)';
+          if (media.length === 0) continue;
+          rawText = media.some((m) => m.type === 'image') ? '(image)' : '(document)';
         }
 
         // Escape special characters to prevent prompt injection via message content
@@ -663,7 +687,7 @@ export class WhatsAppChannel implements ChannelProvider {
         const ownsParticipant = !participant || participantResolved === this.ownPhoneJid;
         const isSelfChat = !isGroup && ownsChat && ownsParticipant;
 
-        log.info(`[whatsapp] Message from ${sender} (chat=${chatJid}, group=${isGroup}, fromMe=${fromMe}, selfChat=${isSelfChat}, images=${images.length}): ${text.slice(0, 80)}`);
+        log.info(`[whatsapp] Message from ${sender} (chat=${chatJid}, group=${isGroup}, fromMe=${fromMe}, selfChat=${isSelfChat}, media=${media.length}): ${text.slice(0, 80)}`);
 
         this.onMessage(
           sender,
@@ -673,7 +697,7 @@ export class WhatsAppChannel implements ChannelProvider {
           isSelfChat,
           chatJid,
           isGroup,
-          images.length > 0 ? images : undefined,
+          media.length > 0 ? media : undefined,
           msg.key,
         );
       }
@@ -692,6 +716,10 @@ export class WhatsAppChannel implements ChannelProvider {
     if (message.imageMessage?.caption) return message.imageMessage.caption;
     if (message.videoMessage?.caption) return message.videoMessage.caption;
     if (message.documentMessage?.caption) return message.documentMessage.caption;
+    // Captioned documents arrive wrapped in documentWithCaptionMessage.
+    if (message.documentWithCaptionMessage?.message?.documentMessage?.caption) {
+      return message.documentWithCaptionMessage.message.documentMessage.caption;
+    }
 
     // View-once wrappers
     if (message.viewOnceMessage?.message) return this.extractText(message.viewOnceMessage.message);
@@ -729,6 +757,25 @@ export class WhatsAppChannel implements ChannelProvider {
     return null;
   }
 
+  /** Extract document metadata (mimetype + fileName) from a message, unwrapping the
+   *  common containers. Returns null when there is no document.
+   *
+   *  WhatsApp wraps a captioned document in `documentWithCaptionMessage.message.documentMessage`
+   *  while a bare document is `documentMessage` directly — both must resolve. (The actual binary
+   *  is fetched via downloadMediaMessage on the outer `msg`, which Baileys unwraps itself.) */
+  private getDocumentInfo(message: any): { mimetype?: string; fileName?: string } | null {
+    if (!message) return null;
+    const doc =
+      message.documentMessage ||
+      message.documentWithCaptionMessage?.message?.documentMessage ||
+      message.viewOnceMessage?.message?.documentMessage ||
+      message.viewOnceMessageV2?.message?.documentMessage ||
+      message.ephemeralMessage?.message?.documentMessage ||
+      message.ephemeralMessage?.message?.documentWithCaptionMessage?.message?.documentMessage;
+    if (!doc) return null;
+    return { mimetype: doc.mimetype || undefined, fileName: doc.fileName || undefined };
+  }
+
   /** Check if a message contains audio (voice note or audio file) */
   private isAudioMessage(message: any): boolean {
     if (!message) return false;

package/supervisor/chat/src/components/Chat/AudioBubble.tsx

@@ -23,7 +23,7 @@ export default function AudioBubble({ audioData }: Props) {
   // Historical audio is stored as an /api/files/* path, which a native Audio element
   // can't fetch (the Bearer token can't ride on the request) — resolve it to a blob URL
   // fetched with auth. data: URLs (freshly-recorded clips) pass straight through.
-  const resolvedAudioUrl = useAuthedFileUrl(audioData);
+  const { url: resolvedAudioUrl } = useAuthedFileUrl(audioData);
 
   // Create Audio element once the source URL is ready
   useEffect(() => {

package/supervisor/chat/src/components/Chat/AuthedImage.tsx

@@ -1,3 +1,4 @@
+import { ImageOff } from 'lucide-react';
 import { useAuthedFileUrl } from '../../lib/authedFile';
 
 interface Props {
@@ -11,11 +12,23 @@ interface Props {
  * An `<img>` for `/api/files/*` attachments. The file is fetched with the auth token
  * (see `useAuthedFileUrl`) and rendered from a blob URL, because a native `<img src>`
  * request can't carry the Bearer token that `/api/files` now requires. While the fetch
- * is in flight (or if it failed) a subtle pulsing placeholder is shown in its place so
- * the layout doesn't jump.
+ * is in flight a subtle pulsing placeholder is shown in its place so the layout doesn't
+ * jump; if it failed (deleted / 401 / 5xx) a "broken image" fallback is shown instead.
  */
 export default function AuthedImage({ src, alt, className, onClick }: Props) {
-  const resolvedSrc = useAuthedFileUrl(src);
+  const { url: resolvedSrc, status } = useAuthedFileUrl(src);
+
+  if (status === 'error') {
+    return (
+      <div
+        className={`${className ?? ''} flex items-center justify-center bg-black/10 text-muted-foreground/50`}
+        onClick={onClick}
+        title={alt || 'Image not found'}
+      >
+        <ImageOff className="h-5 w-5" />
+      </div>
+    );
+  }
 
   if (!resolvedSrc) {
     return <div className={`${className ?? ''} bg-white/10 animate-pulse`} onClick={onClick} />;

package/supervisor/chat/src/components/Chat/BlobyImageCard.tsx

@@ -18,7 +18,7 @@ export default function BlobyImageCard({ src, alt }: Props) {
   // `src` may be a same-origin /api/files/* path (needs the auth token, which a native
   // <img> can't send) or an external URL — useAuthedFileUrl only fetches+authes the
   // former and passes external URLs through untouched (so the token never leaves origin).
-  const resolvedSrc = useAuthedFileUrl(src);
+  const { url: resolvedSrc, status } = useAuthedFileUrl(src);
 
   const handleDownload = async () => {
     try {
@@ -37,7 +37,7 @@ export default function BlobyImageCard({ src, alt }: Props) {
     }
   };
 
-  if (failed) {
+  if (failed || status === 'error') {
     return (
       <div className="my-2 flex items-center gap-2.5 px-3.5 py-2.5 rounded-xl border border-border/30 bg-black/10 text-muted-foreground/50 text-xs">
         <ImageOff className="h-4 w-4 shrink-0" />

package/supervisor/chat/src/components/Chat/ImageLightbox.tsx

@@ -1,17 +1,26 @@
 import { useCallback, useEffect } from 'react';
 import { motion, AnimatePresence } from 'framer-motion';
-import { ChevronLeft, ChevronRight, X, Download } from 'lucide-react';
+import { ChevronLeft, ChevronRight, X, Download, ImageOff } from 'lucide-react';
 import { authFetch } from '../../lib/auth';
 import { useAuthedFileUrl } from '../../lib/authedFile';
 
+/** One lightbox entry: the (possibly data:/`/api/files`) URL plus the human filename,
+ *  so downloads and alt text use the real name rather than a URL stamp. */
+export interface LightboxImage {
+  url: string;
+  name?: string;
+}
+
 interface Props {
-  images: string[];
+  images: LightboxImage[];
   index: number;
   onClose: () => void;
   onNavigate: (index: number) => void;
 }
 
 export default function ImageLightbox({ images, index, onClose, onNavigate }: Props) {
+  const current = images[index];
+
   const goPrev = useCallback(() => {
     if (index > 0) onNavigate(index - 1);
   }, [index, onNavigate]);
@@ -22,7 +31,7 @@ export default function ImageLightbox({ images, index, onClose, onNavigate }: Pr
 
   // /api/files/* needs the auth token, which a native <img src> can't send — resolve
   // the currently-shown image to a blob URL fetched with the Authorization header.
-  const resolvedSrc = useAuthedFileUrl(images[index]);
+  const { url: resolvedSrc, status } = useAuthedFileUrl(current?.url);
 
   useEffect(() => {
     const handleKey = (e: KeyboardEvent) => {
@@ -50,18 +59,18 @@ export default function ImageLightbox({ images, index, onClose, onNavigate }: Pr
             onClick={async (e) => {
               e.stopPropagation();
               try {
-                const res = await authFetch(images[index]);
+                const res = await authFetch(current.url);
                 const blob = await res.blob();
                 const url = URL.createObjectURL(blob);
                 const a = document.createElement('a');
                 a.href = url;
-                a.download = images[index].split('/').pop() || 'image';
+                a.download = current.name || current.url.split('/').pop() || 'image';
                 document.body.appendChild(a);
                 a.click();
                 document.body.removeChild(a);
                 URL.revokeObjectURL(url);
               } catch {
-                window.open(images[index], '_blank');
+                window.open(current.url, '_blank');
               }
             }}
             className="p-2 rounded-full bg-white/10 hover:bg-white/20 transition-colors text-white"
@@ -105,10 +114,18 @@ export default function ImageLightbox({ images, index, onClose, onNavigate }: Pr
         )}
 
         {/* Image */}
-        {resolvedSrc ? (
+        {status === 'error' ? (
+          <div
+            className="flex flex-col items-center gap-2 rounded-lg bg-white/5 px-8 py-10 text-white/50"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <ImageOff className="h-10 w-10" />
+            <span className="text-sm">{current?.name || 'Image not found'}</span>
+          </div>
+        ) : resolvedSrc ? (
           <img
             src={resolvedSrc}
-            alt=""
+            alt={current?.name || ''}
             className="max-h-[85vh] max-w-[90vw] object-contain rounded-lg"
             onClick={(e) => e.stopPropagation()}
           />