Support durable assistant image attachments in Agent clients

web/src/components/agent/agent-attachment.tsx

@@ -1,19 +1,20 @@
-import { useEffect, useRef, useState } from "preact/hooks";
+import { useCallback, useEffect, useRef, useState } from "preact/hooks";
 import { Copy, Download, FileText, Image, LoaderCircle } from "lucide-preact";
 import { attachmentSize, type AgentAttachment } from "@/lib/agent-attachments";
 
-type Props = { file: AgentAttachment; download(file: AgentAttachment, signal?: AbortSignal): Promise<Blob> };
+type Props = { file: AgentAttachment; inline?: boolean; download(file: AgentAttachment, signal?: AbortSignal): Promise<Blob> };
 /** Authenticated bytes only; no native credential, remote href, or public file serving. */
-export function AgentAttachmentCard({ file, download }: Props) {
+export function AgentAttachmentCard({ file, download, inline = false }: Props) {
   const [preview, setPreview] = useState<string>();
   const [error, setError] = useState<string>();
   const [busy, setBusy] = useState(false);
   const [copied, setCopied] = useState(false);
   const controller = useRef<AbortController>();
-  useEffect(() => () => { controller.current?.abort(); }, []);
+  const transferring = useRef(false);
   useEffect(() => () => { if (preview) URL.revokeObjectURL(preview); }, [preview]);
-  const retrieve = async (show: boolean) => {
-    if (busy) return;
+  const retrieve = useCallback(async (show: boolean) => {
+    if (transferring.current) return;
+    transferring.current = true;
     const request = new AbortController(); controller.current = request; setBusy(true); setError(undefined);
     try {
       const blob = await download(file, request.signal); if (request.signal.aborted) return;
@@ -24,14 +25,22 @@ export function AgentAttachmentCard({ file, download }: Props) {
         setTimeout(() => URL.revokeObjectURL(url), 1000);
       }
     } catch (failure) { if (!request.signal.aborted) setError(failure instanceof Error ? failure.message : "Download failed."); }
-    finally { if (!request.signal.aborted) setBusy(false); }
-  };
+    finally { if (controller.current === request) { transferring.current = false; if (!request.signal.aborted) setBusy(false); } }
+  }, [download, file.id, file.sha256, file.mimeType, file.kind, file.sizeBytes, file.filename]);
+  useEffect(() => {
+    setPreview(undefined); setError(undefined); setBusy(false); transferring.current = false;
+    if (inline && file.kind === "image") void retrieve(true);
+    return () => { controller.current?.abort(); };
+  }, [inline, retrieve]);
   return <div className="agent-attachment">
     <div className="agent-attachment__title"><FileText size={15} /><span>{file.filename}</span><small>{attachmentSize(file.sizeBytes)}</small></div>
-    {file.workspacePath ? <div className="agent-attachment__path"><code title={file.workspacePath}>{file.workspacePath}</code><button type="button" aria-label={`Copy path for ${file.filename}`} title={copied ? "Copied" : "Copy workspace path"} onClick={() => { void navigator.clipboard.writeText(file.workspacePath!).then(() => setCopied(true)).catch(() => setError("Could not copy the path.")); }}><Copy size={13} /></button></div> : null}
-    {preview ? <img className="agent-attachment__preview" src={preview} alt={file.filename} /> : null}
+    {!inline && file.workspacePath ? <div className="agent-attachment__path"><code title={file.workspacePath}>{file.workspacePath}</code><button type="button" aria-label={`Copy path for ${file.filename}`} title={copied ? "Copied" : "Copy workspace path"} onClick={() => { void navigator.clipboard.writeText(file.workspacePath!).then(() => setCopied(true)).catch(() => setError("Could not copy the path.")); }}><Copy size={13} /></button></div> : null}
+    {inline ? <div className="agent-attachment__image-frame" aria-busy={busy}>
+      {preview ? <img className="agent-attachment__preview" src={preview} alt={file.filename} onError={() => { setPreview(undefined); setError("Image could not be displayed."); }} />
+        : <span role="status">{error ? "Image unavailable" : "Loading image…"}</span>}
+    </div> : preview ? <img className="agent-attachment__preview" src={preview} alt={file.filename} /> : null}
     <div className="agent-attachment__actions">
-      {file.kind === "image" ? <button type="button" disabled={busy} onClick={() => preview ? setPreview(undefined) : void retrieve(true)}><Image size={13} />{preview ? "Hide preview" : "Preview"}</button> : null}
+      {file.kind === "image" && (!inline || error) ? <button type="button" disabled={busy} onClick={() => preview ? setPreview(undefined) : void retrieve(true)}><Image size={13} />{inline ? "Retry image" : preview ? "Hide preview" : "Preview"}</button> : null}
       <button type="button" disabled={busy} onClick={() => void retrieve(false)}>{busy ? <LoaderCircle size={13} className="animate-spin" /> : <Download size={13} />}Download</button>
     </div>
     {error ? <span className="agent-attachment__error" role="alert">{error} Retry using the buttons above.</span> : null}

web/src/components/agent/agent-conversation.css

@@ -476,4 +476,6 @@
 .agent-attachment__actions button { display: flex; align-items: center; gap: 5px; color: #ddd6fe; }
 .agent-attachment__actions button:disabled { opacity: .5; }
 .agent-attachment__preview { display: block; max-height: 260px; max-width: 100%; margin-top: 8px; border-radius: 6px; }
+.agent-attachment__image-frame { display: flex; align-items: center; justify-content: center; height: 260px; width: min(480px, 100%); margin-top: 8px; }
+.agent-attachment__image-frame .agent-attachment__preview { width: 100%; height: 100%; object-fit: contain; margin: 0; }
 .agent-attachment__error { display: block; width: 100%; color: #fda4af; font-size: 12px; margin-top: 5px; }

web/src/components/agent/agent-conversation.tsx

@@ -61,8 +61,8 @@ const AgentBubble = memo(function AgentBubble({ message, animate, onRetry, downl
       {!own ? <span className="agent-room__message-avatar" aria-hidden="true"><img src="/character-still.png" alt="" draggable={false} /></span> : null}
       <div className="agent-room__message-content">
         <div className={`message-bubble${own ? " message-bubble--user" : ""}`}>
-          {own ? <p className="agent-room__plain-message">{message.content}</p> : <MarkdownContent markdown={message.content} openLinksInNewTab />}
-          {agentAttachments(message.metadata).map(file => <AgentAttachmentCard key={file.id} file={file} download={download} />)}
+          {own ? <p className="agent-room__plain-message">{message.content}</p> : <MarkdownContent markdown={message.content} openLinksInNewTab allowImages={false} />}
+          {agentAttachments(message.metadata, message.role).map(file => <AgentAttachmentCard key={file.id} file={file} download={download} inline={message.role === "assistant"} />)}
         </div>
         {own && failed && typeof info.error === "string" ? <div className="agent-attachment__error" role="alert">{info.error}</div> : null}
         <div className="agent-room__message-meta">

web/src/components/markdown/markdown-content.tsx

@@ -11,6 +11,8 @@ type Props = {
   mode?: MarkdownMode;
   resolveCitationIndex?: (href: string) => number | undefined;
   openLinksInNewTab?: boolean;
+  /** Agent images are delivered only through authenticated attachment IDs. */
+  allowImages?: boolean;
 };
 
 function replaceMarkdownLinksWithCitationTokens(markdown: string, resolveCitationIndex?: (href: string) => number | undefined) {
@@ -35,24 +37,28 @@ function setNewTabLinkAttributes(currentNode: Element) {
   currentNode.setAttribute("rel", "noopener noreferrer");
 }
 
-function renderMarkdown(markdown: string, openLinksInNewTab: boolean) {
+function renderMarkdown(markdown: string, openLinksInNewTab: boolean, allowImages: boolean) {
   const rawHtml = marked.parse(markdown, { gfm: true, breaks: true, renderer: markdownRenderer }) as string;
-  if (!openLinksInNewTab) return DOMPurify.sanitize(rawHtml, { ADD_ATTR: ["class", "target", "rel"] });
+  const config = { ADD_ATTR: ["class", "target", "rel"], ...(!allowImages ? {
+    FORBID_TAGS: ["img", "picture", "source", "video", "audio", "svg", "math", "style"],
+    FORBID_ATTR: ["style", "srcset", "background", "poster"],
+  } : {}) };
+  if (!openLinksInNewTab) return DOMPurify.sanitize(rawHtml, config);
 
   DOMPurify.addHook("afterSanitizeAttributes", setNewTabLinkAttributes);
   try {
-    return DOMPurify.sanitize(rawHtml, { ADD_ATTR: ["class", "target", "rel"] });
+    return DOMPurify.sanitize(rawHtml, config);
   } finally {
     DOMPurify.removeHook("afterSanitizeAttributes", setNewTabLinkAttributes);
   }
 }
 
-export function MarkdownContent({ markdown, className, mode = "default", resolveCitationIndex, openLinksInNewTab = false }: Props) {
+export function MarkdownContent({ markdown, className, mode = "default", resolveCitationIndex, openLinksInNewTab = false, allowImages = true }: Props) {
   const html = useMemo(() => {
     const prepared =
       mode === "citationTokens" ? replaceMarkdownLinksWithCitationTokens(markdown, resolveCitationIndex) : markdown;
-    return renderMarkdown(prepared, openLinksInNewTab);
-  }, [markdown, mode, openLinksInNewTab, resolveCitationIndex]);
+    return renderMarkdown(prepared, openLinksInNewTab, allowImages);
+  }, [markdown, mode, openLinksInNewTab, resolveCitationIndex, allowImages]);
 
   return <div className={cn("md-content", className)} dangerouslySetInnerHTML={{ __html: html }} />;
 }

web/src/lib/agent-attachments.ts

@@ -19,10 +19,23 @@ export function parseAgentAttachment(value: unknown): AgentAttachment {
   return { id: item.id, kind: item.kind, filename: item.filename, mimeType: item.mimeType, sizeBytes: item.sizeBytes, sha256: item.sha256,
     ...(item.workspacePath ? { workspacePath: item.workspacePath } : {}) };
 }
-export function agentAttachments(metadata: unknown): AgentAttachment[] {
+export function agentAttachments(metadata: unknown, role = "user"): AgentAttachment[] {
+  if (role !== "user" && role !== "assistant") return [];
   const values = (metadata as { agentAttachments?: unknown } | null)?.agentAttachments;
   if (!Array.isArray(values) || values.length > 8) return [];
-  try { return values.map(parseAgentAttachment); } catch { return []; }
+  try {
+    const files = values.map(value => {
+      // Source paths are not part of the assistant output contract, even if an
+      // older/malformed server supplies one. Only the ID authorizes retrieval.
+      const file = parseAgentAttachment(role === "assistant" ? { ...value, workspacePath: undefined } : value);
+      if (role === "assistant" && (file.kind !== "image" || !["image/png", "image/jpeg", "image/gif", "image/webp"].includes(file.mimeType)
+        || file.sizeBytes > 6 * 1024 * 1024 || file.filename.length > 255 || /[\\/\u0000-\u001f\u007f]/.test(file.filename)))
+        throw new Error("Invalid assistant image.");
+      return file;
+    });
+    if (new Set(files.map(file => file.id)).size !== files.length || files.reduce((total, file) => total + file.sizeBytes, 0) > 32 * 1024 * 1024) return [];
+    return files;
+  } catch { return []; }
 }
 export function attachmentCaption(content: string, files: AgentAttachment[]): string {
   return content.trim() ? content : `Attached: ${files.map(file => file.filename).join(", ")}.`;

web/src/lib/agent-room-presentation.ts

@@ -20,7 +20,7 @@ export type AgentRoomPresenterOptions = {
   typingDelayMs?: number;
   clock?: Scheduler;
 };
-const quietTools = new Set(['user_message', 'notify_parent', 'clock_wait', 'event_decision']);
+const quietTools = new Set(['user_message', 'output_image', 'notify_parent', 'clock_wait', 'event_decision']);
 const data = (message: Message): Record<string, unknown> => message.metadata && typeof message.metadata === 'object'
   && !Array.isArray(message.metadata) ? message.metadata as Record<string, unknown> : {};
 const entryId = (message: Message): bigint | undefined => {

web/src/lib/agent-room.ts

@@ -18,7 +18,7 @@ export type AgentMessagesPage = {
 };
 export type AgentDescriptor = {
   id: string; title: string; model: string; activity: AgentActivity;
-  websocket: string; protocol: string; capabilities?: { attachments?: AgentAttachmentCapability };
+  websocket: string; protocol: string; capabilities?: { attachments?: AgentAttachmentCapability; assistantImages?: { version: 1 } };
 };
 export type AgentReadState = { cursor: string; updatedAt: string | null; sourceId?: string | null };
 export type AgentRoomState = {
@@ -175,6 +175,8 @@ export class AgentRoomClient {
   private readonly baseUrl: string;
   private readonly fetcher: typeof globalThis.fetch;
   private readonly token: () => string | null;
+  private activeDownloads = 0;
+  private readonly downloadWaiters = new Set<() => void>();
   constructor(options: AgentRoomClientOptions = {}) {
     this.baseUrl = (options.baseUrl || "/api").replace(/\/+$/, "");
     this.fetcher = (options.fetch || globalThis.fetch).bind(globalThis);
@@ -223,12 +225,46 @@ export class AgentRoomClient {
   }
   async download(attachment: AgentAttachment, signal?: AbortSignal): Promise<Blob> {
     const file = parseAgentAttachment(attachment), headers = new Headers(), token = this.token();
-    if (token) headers.set("Authorization", `Bearer ${token}`);
-    const response = await this.fetcher(`${this.baseUrl}/v1/agent/attachments/${encodeURIComponent(file.id)}/content`, { headers, signal, cache: "no-store", redirect: "error" });
-    if (!response.ok) { const error = await response.json().catch(() => null); throw new Error(error?.message || "Attachment download failed."); }
-    const blob = await response.blob();
-    if (blob.size !== file.sizeBytes || blob.size > 8 * 1024 * 1024) throw new Error("Attachment download was incomplete.");
-    return blob;
+    signal?.throwIfAborted();
+    while (this.activeDownloads >= 2) {
+      await new Promise<void>((resolve, reject) => {
+        const cleanup = () => { this.downloadWaiters.delete(wake); signal?.removeEventListener("abort", abort); };
+        const wake = () => { cleanup(); resolve(); };
+        const abort = () => { cleanup(); reject(signal?.reason || new Error("Download canceled.")); };
+        this.downloadWaiters.add(wake); signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) abort();
+      });
+      signal?.throwIfAborted();
+    }
+    this.activeDownloads++;
+    try {
+      if (token !== this.token()) throw new Error("Authentication changed. Retry the download.");
+      if (token) headers.set("Authorization", `Bearer ${token}`);
+      const response = await this.fetcher(`${this.baseUrl}/v1/agent/attachments/${encodeURIComponent(file.id)}/content`, { headers, signal, cache: "no-store", redirect: "error" });
+      if (!response.ok) { await response.body?.cancel(); throw new Error("Attachment download failed. Retry the download."); }
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error("Attachment download was incomplete.");
+      const bytes = new Uint8Array(file.sizeBytes); let size = 0;
+      try {
+        for (;;) {
+          const { done, value } = await reader.read(); if (done) break;
+          signal?.throwIfAborted();
+          if (size + value.length > bytes.length) throw new Error("Attachment download exceeds its size limit.");
+          bytes.set(value, size); size += value.length;
+        }
+      } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+      if (size !== file.sizeBytes) throw new Error("Attachment download was incomplete.");
+      const sha256 = [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map(n => n.toString(16).padStart(2, "0")).join("");
+      if (sha256 !== file.sha256) throw new Error("Attachment checksum did not match.");
+      if (file.kind === "image" && response.headers.get("content-type")?.split(";")[0].trim() !== file.mimeType)
+        throw new Error("Attachment image type did not match.");
+      signal?.throwIfAborted();
+      if (token !== this.token()) throw new Error("Authentication changed. Retry the download.");
+      return new Blob([bytes], { type: response.headers.get("content-type") || "application/octet-stream" });
+    } finally {
+      this.activeDownloads--;
+      this.downloadWaiters.values().next().value?.();
+    }
   }
   websocketUrl(pageUrl: string): string {
     const url = new URL(`${this.baseUrl}/v1/agent/ws`, pageUrl);

web/tests/agent-attachments.test.mjs

@@ -5,11 +5,48 @@ import { createAgentUploadQueue, agentAttachments, parseAgentAttachment } from '
 import { AgentRoomClient } from '../src/lib/agent-room.ts';
 import { createAgentOptimisticOutbox } from '../src/lib/agent-optimistic-outbox.ts';
 import { agentTranscriptMessages } from '../src/lib/agent-room-presentation.ts';
+import { createAgentRoomState, applyAgentEvent, mergeAgentMessages } from '../src/lib/agent-room.ts';
 const file = { id:'att_12345678-1234-4234-8234-123456789abc',kind:'text',filename:'notes.txt',mimeType:'text/plain',sizeBytes:4,sha256:createHash('sha256').update('data').digest('hex'),workspacePath:'/data/workspace/uploads/att_12345678-1234-4234-8234-123456789abc/notes.txt' };
 const cap = {version:1,maxCount:8,maxTotalBytes:32*1024*1024,maxImageBytes:6*1024*1024,maxFileBytes:8*1024*1024,imageMimeTypes:['image/png','image/jpeg','image/gif','image/webp']};
 const tick=()=>new Promise(r=>setTimeout(r,0));
 const waitFor=async check=>{const until=Date.now()+5000;while(!check()){assert.ok(Date.now()<until,'async condition timed out');await tick();}};
 
+test('assistant images retain stable live/history identity, omit paths, and never enable input capability',async()=>{
+  const image={...file,kind:'image',mimeType:'image/png',filename:'image.png',url:'https://never-fetch.invalid/image'};
+  const safe={...image};delete safe.workspacePath;delete safe.url;
+  const message={id:'outbound:42',role:'assistant',content:'',createdAt:new Date().toISOString(),metadata:{kind:'message',status:'complete',entryId:42,agentAttachments:[image]}};
+  const page={type:'messages',conversationId:'1',messages:[message],cursor:'42',beforeCursor:'42',hasMore:false};
+  const live=applyAgentEvent(createAgentRoomState(),page);
+  assert.deepEqual(agentAttachments(live.messages[0].metadata,'assistant'),[safe]);
+  const history=mergeAgentMessages(live.messages,[structuredClone(message)]);
+  assert.equal(history.length,1);assert.equal(history[0].id,'outbound:42');
+  assert.deepEqual(agentAttachments(history[0].metadata,'assistant'),[safe]);
+  assert.equal(agentTranscriptMessages(history).length,1,'image-only assistant bubble remains visible');
+  for(const invalid of [{...image,kind:'file'},{...image,mimeType:'image/svg+xml'},{...image,sizeBytes:6*1024*1024+1},{...image,filename:'/private/source.png'}])
+    assert.deepEqual(agentAttachments({agentAttachments:[invalid]},'assistant'),[]);
+  assert.deepEqual(agentAttachments(message.metadata,'tool'),[]);
+  assert.deepEqual(agentAttachments({agentAttachments:[image,image]},'assistant'),[]);
+  const descriptor={capabilities:{assistantImages:{version:1}}};
+  const queue=createAgentUploadQueue({capability:()=>descriptor.capabilities.attachments,changed:()=>{},upload:async()=>{throw new Error('Must not upload');}});
+  assert.throws(()=>queue.add([new File(['data'],'notes.txt')]),/not available/);queue.dispose();
+});
+
+test('downloads bound concurrent bytes, validate hashes/types, cancel queued work, and reject changed credentials',async()=>{
+  const complete=[];let calls=0,token='one';
+  const client=new AgentRoomClient({token:()=>token,fetch:async()=>{calls++;return new Promise(resolve=>complete.push(resolve));}});
+  const a=client.download(file), b=client.download(file), cancel=new AbortController();
+  const canceled=client.download(file,cancel.signal);const canceledAssertion=assert.rejects(canceled);cancel.abort();
+  await canceledAssertion;assert.equal(calls,2);
+  complete.shift()(new Response('data'));await a;
+  const c=client.download(file);assert.equal(calls,3);
+  complete.shift()(new Response('evil'));await assert.rejects(b,/checksum/);
+  token='two';complete.shift()(new Response('data'));await assert.rejects(c,/Authentication changed/);
+  const huge=new AgentRoomClient({fetch:async()=>new Response('data-exceeds-receipt')});
+  await assert.rejects(huge.download(file),/size limit/);
+  const wrongType=new AgentRoomClient({fetch:async()=>new Response('data',{headers:{'content-type':'text/html'}})});
+  await assert.rejects(wrongType.download({...file,kind:'image',mimeType:'image/png'}),/type did not match/);
+});
+
 test('composer gates unsupported servers, count/type/size and batches before upload; preserves retry ID and remove races',async()=>{
   let capability, attempts=[], next=0, changed=0, finish;
   const queue=createAgentUploadQueue({capability:()=>capability,newId:()=>`upload-${++next}`,changed:()=>changed++,upload:async(_file,id,signal)=>{attempts.push({id,signal});if(attempts.length===1)throw new Error('Quota full');return new Promise(resolve=>finish=resolve);}});