Keep assistant image previews stable through live delivery and reload

docs/api/rest.md

@@ -605,6 +605,28 @@ durable entries and can advance without visible messages. Use returned cursors;
 do not derive them from message IDs. `limit` bounds source entries, not displayed
 messages.
 
+The web Agent starts with one cursorless `limit=100` window and renders it in
+chronological order, initially positioned at its newest end. `hasMore` on this
+window or a `before` page means **older** source entries exist; on an `after`
+page it means **newer** entries remain. Each **Load older messages** action fetches
+one `before=<beforeCursor>&limit=100` page, even if that page has no visible rows.
+Older pages do not advance the live replay/read cursor or overwrite newer copies
+of the same message. Initial loading never walks forward from zero or drains
+older history. Reconnect recovery still follows `after` from the accepted live
+cursor. Aborted/replaced room sessions discard late responses.
+
+Web unread counts cover loaded public replies. A `+` suffix (or a dot when no
+loaded reply is known unread) indicates that earlier messages may also be unread;
+the API does not supply an exact total for unloaded history. Observing the latest
+end in a focused visible conversation marks it read through that rendered cursor,
+including earlier unloaded history. Fetching or reading older pages does not
+acknowledge newer replies. An internal-only window with no rendered public
+messages does not acknowledge history; older loading remains an explicit action.
+Initial source-entry/network work is bounded; retained
+messages/DOM grow with explicit older loads and live updates. Offscreen web rows
+use CSS `content-visibility: auto`, which skips rendering work while retaining
+chronological DOM, selection, find and accessibility; it is not DOM virtualization.
+
 ### `POST /v1/agent/messages`
 
 Body: `{ "content": "Check the oven", "requestId": "client-generated-uuid" }`.
@@ -686,11 +708,54 @@ Global `SYBIL_AGENT_ATTACHMENT_QUOTA_BYTES` defaults to 1 GiB. Concurrent reserv
 
 Release requires native `SYBIL_AGENT_AUTH_MODE=token` with nonempty `SYBIL_AGENT_API_KEY`, plus backend `ADMIN_TOKEN` and matching server-side `SYBIL_AGENT_API_KEY` / `SYBIL_AGENT_BASE_URL`. Native open mode cannot advertise/store/download attachments. A runtime containing attachment records/files refuses open startup; raw/model APIs and sockets are protected in token mode. An open Sybil proxy also refuses access to an attachment-capable native runtime, rather than exposing its history through a private server credential. Explicit text-only open development remains supported with an open/legacy runtime lacking attachment capability. Native keys never enter browser/iOS payloads. No insecure development opt-in is enabled.
 
-The runtime source is built into its container: rebuild it with pinned busboy/sharp dependencies for the target Node/Linux platform before release. The deployed open auth mode must be changed separately; no deployed config or mount is modified by this implementation. Backend and web must be upgraded with runtime capability/auth configured before clients advertise uploads.
+The runtime source is built into its container: rebuild it with pinned busboy/sharp dependencies for the target Node/Linux platform before release. Deployment must use native token auth and matching backend credentials before clients advertise attachments; no additional public mount is needed.
 
 Browser drafts retain upload IDs and completed descriptors across pane changes and reload. Incomplete uploads require reselection of the original filename/type/size and, once network delivery has begun, matching SHA-256 bytes; retries reuse uploadId. Sending persists the attachment-bearing outbox before clearing the draft. Message confirmation requires the same ordered attachment IDs in receipts and canonical echoes. Mismatched echoes must retain local attachments and delivery errors; they are not acknowledgement of a file submission.
 
 
+### Assistant image output (v1)
+
+The independent optional capability `capabilities.assistantImages: {"version":1}`
+advertises the runtime's root-only `output_image` tool. It does **not** enable input
+upload controls; those still require `capabilities.attachments.version == 1`.
+Authenticated downloads accept either supported capability. Open proxies refuse
+history and socket access if either private attachment capability is advertised.
+Capability absence does not hide previously stored assistant image messages.
+
+The agent invokes `output_image({path, uploadId, filename?, caption?})` with a stable
+UUID retry identity and a local persistent raster exported beneath the workspace's
+`artifacts/` or `downloads/` directory. It copies validated bytes into the existing
+attachment store and publishes one durable assistant message. This is an internal
+agent tool, with no browser/iOS publishing endpoint or client-supplied role.
+Workers cannot publish through it. No URL fetch, remote image proxy, file execution
+or implicit forwarding of native tool image blocks is performed. Generation is
+available only when a separate generation provider/tool is actually installed.
+
+Output uses the same original-byte/hash/quota limits (PNG/JPEG/GIF/WebP, 6 MiB,
+50 million pixels, 16,384 pixels per axis), authenticated content route and backup
+policy as uploads. Sources must be confined regular files without symlink/hardlink
+substitution or private path segments. Upload IDs are bound to output provenance;
+conflicting arguments fail and identical retries retain their message/attachment IDs.
+Retries reuse the stored snapshot even if the original source moves or changes;
+publishing changed bytes requires a new upload UUID.
+
+Public output rows have `id: "outbound:<entryId>"`, `role: "assistant"`,
+`metadata.kind: "message"`, `metadata.status: "complete"`, and
+`metadata.agentAttachments` containing image descriptors. `content` is the optional
+caption, otherwise an empty string; attachment-only rows remain visible. Descriptors
+contain only `id`, `kind`, safe `filename`, `mimeType`, `sizeBytes` and `sha256`.
+They contain no workspace/source path, URL, credential, or image bytes. The public
+tool row redacts output tool arguments/results; internal task/submission provenance
+stays in the existing durable outbox.
+
+Web/iOS automatically render assistant rasters in fixed preview frames, retrieving
+only authenticated ID-based originals, checking size and SHA-256, rejecting
+redirects, and offering retry/download. Web limits downloads to two at a time and
+uses revocable blob URLs. Clients discard assistant descriptor paths and unsupported
+types. Agent Markdown cannot load images; external links remain explicit navigation.
+Image-bearing push alerts use **You have a new message.**, including when a caption
+exists, and never include attachment names, paths, bytes or URLs.
+
 ## Agent push notifications (v1)
 
 All push/config/presence routes require a configured `ADMIN_TOKEN` and bearer authentication; open development mode returns 503. Missing/wrong bearer returns 401/403. Bodies are limited to 16 KiB, responses use `Cache-Control: no-store`, invalid bodies return 400, and unavailable configuration returns 503. Do not put credentials, device tokens or subscription endpoints into URLs. Ownership is one **shared authenticated personal principal**, derived on the server from the configured credential generation. Anyone possessing that shared token has authority over all its installations; UUIDs identify installations and do not create per-human isolation. No `ownerId` is accepted. Changing `ADMIN_TOKEN` invalidates all prior push opt-ins. Protect the SQLite database/backups because endpoint credentials are stored there.

docs/api/streaming-chat.md

@@ -337,8 +337,34 @@ The proxy closes upstream sockets when browsers leave or Sybil shuts down.
 History remains durable in Sybil Agent. Shared read position is separate from delivery:
 update `GET`/`PUT /v1/agent/read-state` only when messages have actually been viewed.
 
+The web client first accepts source-bound read state and one recent REST history
+window, then authenticates this socket with that window's `cursor`. Initial
+`hasMore` refers to older history and does not trigger a forward replay from zero.
+Older pages load on demand using a separate `beforeCursor`; delayed older pages
+preserve live edits and never change the socket replay position. Reconnects and
+foreground catch-up use the last accepted live cursor as before. Incoming output
+follows the viewport only while it is pinned to the newest end; older prepends and
+dynamic heights preserve the reader's keyed row. Only a focused, visible, settled
+latest view acknowledges the rendered cursor, marking the conversation read
+through that point. See [web history windows and unread counts](rest.md#get-v1agentmessages)
+for unloaded-history count semantics and rendering limits.
+
 ### Agent attachment history, queued activity and replay
 
+Assistant image output uses the same `messages` frames and durable history rows,
+with `role: "assistant"`, `id: "outbound:<entryId>"`, `metadata.kind: "message"`,
+`metadata.status: "complete"`, and `metadata.agentAttachments`. Each image descriptor
+contains `id`, `kind: "image"`, `filename`, `mimeType`, `sizeBytes` and `sha256` only;
+there is no source/workspace path or URL. An omitted caption yields empty `content`;
+clients must retain this image-only row. Merge/replay by the unchanged message ID,
+render authenticated image bytes inline in a fixed frame, and retain loaded history
+even if the optional `capabilities.assistantImages.version: 1` is absent later.
+That capability does not authorize input uploads. Native tool image blocks are not
+automatically forwarded; the root agent explicitly calls `output_image`. Public
+output tool rows redact arguments/results, and Agent Markdown does not fetch images.
+See [assistant image output](./rest.md#assistant-image-output-v1) for publishing,
+retry, auth and generic push-preview semantics. No new socket event is introduced.
+
 Uploads and attached sends use REST, as specified in [rest.md](./rest.md#agent-attachments-v1). WebSocket authentication, event types, stable message IDs, cursor semantics and raw tool rows are unchanged. Capability discovery is optional `GET /v1/agent` → `capabilities.attachments.version: 1`; absence disables new attachment sends. Upgrade/authenticate the native runtime and backend before advertising it.
 
 Both `messages.messages[]` and `activity.activity.queuedMessages[]` carry attachment descriptors under **`metadata.agentAttachments`**, distinct from ordinary chat's inline `metadata.attachments`:

server/src/agent-attachments.ts

@@ -18,11 +18,12 @@ export type AgentProxyJson = (path: string, method?: string, body?: unknown, sig
 function apiError(statusCode: number, code: string, message: string) {
   return Object.assign(new Error(message), { statusCode, code });
 }
-export async function requireAgentAttachments(proxyJson: AgentProxyJson, signal?: AbortSignal) {
+export async function requireAgentAttachments(proxyJson: AgentProxyJson, signal?: AbortSignal, download = false) {
   if (!env.ADMIN_TOKEN) throw apiError(503, 'attachments_unavailable', 'Attachments require authenticated Sybil access.');
   const descriptor = await proxyJson('/api/conversations/root', 'GET', undefined, signal);
-  const value = descriptor.data as { capabilities?: { attachments?: { version?: number } } } | null;
+  const value = descriptor.data as { capabilities?: { attachments?: { version?: number }; assistantImages?: { version?: number } } } | null;
-  if (descriptor.status !== 200 || value?.capabilities?.attachments?.version !== 1)
+  if (descriptor.status !== 200 || !(value?.capabilities?.attachments?.version === 1
+    || (download && value?.capabilities?.assistantImages?.version === 1)))
     throw apiError(503, 'attachments_unavailable', 'The Agent does not currently support authenticated attachments.');
 }
 
@@ -52,7 +53,7 @@ export async function registerAgentAttachmentRoutes(app: FastifyInstance, option
       if (req.raw.aborted || reply.raw.destroyed) { release(); controller.signal.throwIfAborted(); }
       if (uploading && Number(req.headers['content-length'] || 0) > AGENT_UPLOAD_LIMIT)
         throw apiError(413, 'attachment_limit_exceeded', 'Upload request exceeds its size limit.');
-      await requireAgentAttachments(options.proxyJson, controller.signal);
+      await requireAgentAttachments(options.proxyJson, controller.signal, !uploading);
       controller.signal.throwIfAborted();
     });
     routes.addHook('onResponse', async req => { transfers.get(req)?.release(); });

server/src/agent-push-preview.ts

@@ -14,7 +14,8 @@ export type MessageText = (message: PublicMessage) => Promise<string>;
 const Page = z.object({ conversationId: z.string(), cursor: Cursor, beforeCursor: Cursor,
   messages: z.array(z.unknown()).max(1000) });
 const Message = z.object({ id: z.string(), role: z.literal('assistant'), content: z.string(),
-  metadata: z.object({ kind: z.literal('message'), status: z.literal('complete'), entryId: z.number().int().safe() }) });
+  metadata: z.object({ kind: z.literal('message'), status: z.literal('complete'), entryId: z.number().int().safe(),
+    agentAttachments: z.unknown().optional() }) });
 
 /** Resolve only an already eligible candidate from one immutable root public entry. */
 export function createMessageText(upstream: { baseUrl: string; apiKey?: string }): MessageText {
@@ -47,7 +48,10 @@ export function createMessageText(upstream: { baseUrl: string; apiKey?: string }
     const matches = page.messages.filter(value => value && typeof value === 'object' && 'id' in value && value.id === candidate.messageId);
     const message = matches.length === 1 ? Message.safeParse(matches[0]) : undefined;
     if (!message?.success || message.data.metadata.entryId !== Number(candidate.cursor)) throw new Error('Public Agent message unavailable');
-    // Never inspect metadata, tool results, activity, reasoning blocks or linked resources for text.
+    // Attachment messages use the generic alert. Never expose captions, filenames,
+    // paths, image data or linked resources in an image notification.
+    if (message.data.metadata.agentAttachments !== undefined) return '';
+    // Never inspect tool results, activity, reasoning blocks or linked resources for text.
     return message.data.content;
   };
 }

server/src/agent.ts

@@ -43,8 +43,8 @@ export async function registerAgentRoutes(app: FastifyInstance, options: AgentOp
       const response = await fetch(new URL('/api/conversations/root', baseUrl), {
         headers: { 'X-Sybil-Client': 'backend-proxy-v1', Authorization: `Bearer ${apiKey}` }, signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000), redirect: 'error',
       });
-      const descriptor = await response.json() as { capabilities?: { attachments?: unknown } };
+      const descriptor = await response.json() as { capabilities?: { attachments?: unknown; assistantImages?: unknown } };
-      if (!response.ok || descriptor?.capabilities?.attachments) throw new Error('Private runtime');
+      if (!response.ok || descriptor?.capabilities?.attachments || descriptor?.capabilities?.assistantImages) throw new Error('Private runtime');
     } catch { throw Object.assign(new Error('Authenticated Sybil access is required for this Agent runtime.'), { statusCode: 503, code: 'attachments_unavailable' }); }
   };
   const proxyJson = async (path: string, method = 'GET', body?: unknown, signal?: AbortSignal) => {
@@ -53,6 +53,7 @@ export async function registerAgentRoutes(app: FastifyInstance, options: AgentOp
     let response: Response;
     try {
       response = await fetch(new URL(path, baseUrl), { method,
+        redirect: 'error',
         headers: { 'X-Sybil-Client': 'backend-proxy-v1', Authorization: `Bearer ${apiKey}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000),
       });

server/tests/agent-attachments.test.ts

@@ -20,14 +20,14 @@ const [{ registerAgentRoutes }, { env }] = await Promise.all([import('../src/age
 const auth = { authorization: `Bearer ${process.env.ADMIN_TOKEN}` }, key = 'runtime-private-test-key';
 const file = { id:'att_12345678-1234-4234-8234-123456789abc',kind:'text',filename:'résumé.txt',mimeType:'text/plain',sizeBytes:4,sha256:'a'.repeat(64),workspacePath:'/data/workspace/uploads/att_12345678-1234-4234-8234-123456789abc/résumé.txt' };
 const bodies: any[] = [];
-let capable=true, badReceipt=false, errorStatus=0, uploadCalls=0;
+let capable=true, assistantImages=false, badReceipt=false, errorStatus=0, uploadCalls=0;
 let holdDescriptor=false, holdDownload=false;const held:ServerResponse[]=[], closed:ServerResponse[]=[];
 const source=createServer(async(req,res)=>{
   assert.equal(req.headers.authorization,`Bearer ${key}`);
   const chunks: Buffer[]=[];
   try { for await(const chunk of req) chunks.push(chunk); } catch { return; }
   const bytes=Buffer.concat(chunks);res.setHeader('Content-Type','application/json');
-  if(req.url==='/api/conversations/root'){if(holdDescriptor){held.push(res);res.once('close',()=>closed.push(res));return;}res.end(JSON.stringify({id:'1',...(capable?{capabilities:{attachments:{version:1}}}:{})}));return;}
+  if(req.url==='/api/conversations/root'){if(holdDescriptor){held.push(res);res.once('close',()=>closed.push(res));return;}res.end(JSON.stringify({id:'1',capabilities:{...(capable?{attachments:{version:1}}:{}),...(assistantImages?{assistantImages:{version:1}}:{})}}));return;}
   if(errorStatus){res.statusCode=errorStatus;res.end(JSON.stringify({error:true,message:'Storage quota reached',statusCode:errorStatus,code:'attachment_quota_exceeded',remainingBytes:12,quotaBytes:1024,requiredBytes:99}));return;}
   if(req.url?.endsWith('/attachments')){uploadCalls++;assert.match(req.headers['content-type']!,/^multipart\/form-data; boundary=/);assert.ok(bytes.includes(Buffer.from('résumé.txt')));bodies.push(bytes.toString());res.statusCode=201;res.end(JSON.stringify({attachment:file}));return;}
   if(req.url?.endsWith('/content')){if(holdDownload){held.push(res);res.once('close',()=>closed.push(res));return;}res.writeHead(200,{'Content-Type':'text/plain; charset=utf-8','Content-Length':'4','Content-Disposition':"attachment; filename=notes.txt; filename*=UTF-8''notes.txt"});res.end('data');return;}
@@ -57,6 +57,22 @@ test('multipart forwards Unicode filename/uploadId with private auth; quota deta
   assert.equal((await app.inject({url:'/v1/agent/attachments/not-an-id/content',headers:auth})).statusCode,404);
 });
 
+test('assistant-only capability allows authenticated retrieval without granting input uploads or open history',async()=>{
+  capable=false;assistantImages=true;
+  const saved=env.ADMIN_TOKEN;
+  try {
+    const descriptor=(await app.inject({url:'/v1/agent',headers:auth})).json();
+    assert.deepEqual(descriptor.capabilities,{assistantImages:{version:1}});
+    assert.equal((await fetch(base+`/v1/agent/attachments/${file.id}/content`,{headers:auth})).status,200);
+    assert.equal((await fetch(base+`/v1/agent/attachments/${file.id}/content`)).status,401);
+    assert.equal((await fetch(base+'/v1/agent/attachments',{method:'POST',headers:auth,body:form()})).status,503);
+    assert.equal((await app.inject({method:'POST',url:'/v1/agent/messages',headers:auth,payload:{content:'',requestId:'assistant-only',attachments:[{id:file.id}]}})).statusCode,503);
+    assert.equal((await app.inject({method:'POST',url:'/v1/agent/output_image',headers:auth,payload:{path:'https://never-fetch.invalid/image'}})).statusCode,404);
+    env.ADMIN_TOKEN=undefined;
+    for(const url of ['/v1/agent','/v1/agent/messages',`/v1/agent/attachments/${file.id}/content`]) assert.equal((await app.inject({url})).statusCode,503);
+  } finally {env.ADMIN_TOKEN=saved;capable=true;assistantImages=false;}
+});
+
 test('ID-only sends require matching receipts; history retains attachment metadata and raw tools',async()=>{
   const payload={content:'',requestId:'send',attachments:[{id:file.id}]};
   assert.equal((await app.inject({method:'POST',url:'/v1/agent/messages',headers:auth,payload})).statusCode,202);assert.deepEqual(bodies.at(-1),{...payload,channel:'sybil',whenBusy:'followUp',wait:false});

server/tests/agent-push-preview.test.ts

@@ -41,6 +41,11 @@ test('preview lookup uses only the exact eligible completed root assistant conte
   ]) { page = invalid; await assert.rejects(load(candidate)); }
   page = { ...original, messages: [{ ...message, content: '' }] };
   assert.equal(await load(candidate), '', 'empty content never borrows metadata, tool output or reasoning');
+  page = { ...original, messages: [{ ...message, content: 'Caption stays inside authenticated chat.', metadata: { ...message.metadata,
+    agentAttachments: [{ filename: 'private-name.png', workspacePath: '/private/source.png', url: 'https://never-fetch.invalid/image' }] } }] };
+  const imageText = await load(candidate);
+  assert.equal(imageText, '', 'image captions and metadata use only a generic notification');
+  assert.deepEqual(JSON.parse(previewPayload(imageText, body => ({ body }), 4096).toString()), { body: 'You have a new message.' });
   const before = requests.length;
   for (const messageId of ['tool:1:11', 'outbound:12', 'https://never-fetch.invalid/', 'entry:11:0/../../state']) {
     await assert.rejects(load({ ...candidate, messageId }));

web/src/App.tsx

@@ -3554,7 +3554,7 @@ export default function App() {
               type="button"
               data-testid="agent-sidebar-item"
               aria-current={isAgentMode ? "page" : undefined}
-              aria-label={`Sybil Agent${agentRoom.unreadCount ? `, ${agentRoom.unreadCount} unread messages` : ""}${isAgentBusy ? ", working" : ""}`}
+              aria-label={`Sybil Agent${agentRoom.unreadCount ? `, ${agentRoom.unreadCount}${agentRoom.unreadCountIsPartial ? " or more" : ""} unread messages` : agentRoom.unreadCountIsPartial ? ", earlier messages may be unread" : ""}${isAgentBusy ? ", working" : ""}`}
               onClick={() => {
                 setContextMenu(null);
                 setError(null);
@@ -3580,9 +3580,9 @@ export default function App() {
                 <span className="block truncate text-sm font-semibold">Sybil Agent</span>
               </span>
               {isAgentBusy ? <LoaderCircle className="h-4 w-4 shrink-0 animate-spin text-cyan-200" aria-label="Agent working" /> : null}
-              {agentRoom.unreadCount > 0 ? (
+              {agentRoom.unreadCount > 0 || agentRoom.unreadCountIsPartial ? (
                 <span data-testid="agent-unread-badge" className="flex h-5 min-w-5 shrink-0 items-center justify-center rounded-full bg-cyan-200 px-1.5 text-[11px] font-bold tabular-nums text-slate-950">
-                  {agentRoom.unreadCount}
+                  {agentRoom.unreadCount ? `${agentRoom.unreadCount}${agentRoom.unreadCountIsPartial ? "+" : ""}` : "•"}
                 </span>
               ) : null}
             </button>

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) => {
+  const retrieve = useCallback(async (show: boolean) => {
-    if (busy) return;
+    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}
+    {!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}
-    {preview ? <img className="agent-attachment__preview" src={preview} alt={file.filename} /> : 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

@@ -45,6 +45,32 @@
 .agent-room__entry {
   flex-shrink:0;
   min-width:0;
+  /* Retain chronological DOM/selection/a11y; skip offscreen layout and paint.
+     This is not DOM virtualization. Remember measured heights when skipped. */
+  content-visibility:auto;
+  contain-intrinsic-size:auto 160px;
+}
+
+.agent-room__history {
+  display:grid;
+  justify-items:center;
+  gap:8px;
+  flex-shrink:0;
+  color:hsl(255 19% 70%);
+  font-size:12px;
+}
+
+.agent-room__history button {
+  border:1px solid hsl(267 75% 73%/.2);
+  border-radius:8px;
+  padding:8px 14px;
+  background:hsl(261 52% 20%/.56);
+  cursor:pointer;
+}
+
+.agent-room__history button:disabled {
+  cursor:wait;
+  opacity:.65;
 }
 
 .agent-room__day {
@@ -450,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: 480px; max-width: 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

@@ -1,4 +1,5 @@
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";
+import { memo } from "preact/compat";
 import { Clock3, LoaderCircle, Menu, Paperclip, X, RefreshCw, SendHorizontal, WifiOff } from "lucide-preact";
 import type { Message } from "@/lib/api";
 import type { AgentRoomHookResult } from "@/hooks/use-agent-room";
@@ -49,7 +50,7 @@ function toolName(value: unknown) {
   return typeof value === "string" ? value.replace(/_/g, " ") : "Tool";
 }
 
-function AgentBubble({ message, animate, onRetry, download }: { message: Message; animate: boolean; onRetry: (id: string) => void; download: AgentRoomHookResult["downloadAttachment"] }) {
+const AgentBubble = memo(function AgentBubble({ message, animate, onRetry, download }: { message: Message; animate: boolean; onRetry: (id: string) => void; download: AgentRoomHookResult["downloadAttachment"] }) {
   const own = message.role === "user";
   const info = metadata(message);
   const status = typeof info.status === "string" ? info.status : "complete";
@@ -60,8 +61,8 @@ function AgentBubble({ message, animate, onRetry, download }: { message: Message
       {!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 />}
+          {own ? <p className="agent-room__plain-message">{message.content}</p> : <MarkdownContent markdown={message.content} openLinksInNewTab allowImages={false} />}
-          {agentAttachments(message.metadata).map(file => <AgentAttachmentCard key={file.id} file={file} download={download} />)}
+          {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">
@@ -77,7 +78,7 @@ function AgentBubble({ message, animate, onRetry, download }: { message: Message
       </div>
     </article>
   );
-}
+});
 
 export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Props) {
   const [draft, setDraft] = useState(savedDraft);
@@ -98,6 +99,7 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
   const entryAnimationsRef = useRef(new Set<Animation>());
   const typingHeightRef = useRef(0);
   const historyReadyRef = useRef(!room.isLoading);
+  const historyBeforeRef = useRef(room.historyBeforeCursor);
   const scrollerRef = useRef<HTMLDivElement>(null);
   const timelineRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -130,9 +132,20 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
     const element = scrollerRef.current;
     if (!element || pinnedRef.current) { anchorRef.current = null; return; }
     const top = element.getBoundingClientRect().top;
-    // Anchor to layout, independently of the bubble's entrance transform.
+    // Find the first visible row without laying out every offscreen message.
-    const node = Array.from(element.querySelectorAll<HTMLElement>("[data-agent-entry-id]")).find(item => item.getBoundingClientRect().bottom > top + 8);
+    const entries = element.querySelectorAll<HTMLElement>("[data-agent-entry-id]");
-    anchorRef.current = node ? { id: node.dataset.agentEntryId!, offset: node.getBoundingClientRect().top - top } : null;
+    // Probe row boxes without measuring every skipped subtree in a long history.
+    let low = 0, high = entries.length;
+    while (low < high) {
+      const mid = (low + high) >>> 1;
+      if (entries[mid].getBoundingClientRect().bottom <= top + 8) low = mid + 1;
+      else high = mid;
+    }
+    const node = entries[low];
+    // The first row can lose its day separator when older rows arrive. Anchor
+    // the message itself so that changing that separator cannot shift its text.
+    const message = node?.querySelector<HTMLElement>("[data-agent-message-id]");
+    anchorRef.current = node && message ? { id: node.dataset.agentEntryId!, offset: message.getBoundingClientRect().top - top } : null;
   };
   const restoreViewport = () => {
     const element = scrollerRef.current;
@@ -140,11 +153,14 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
     if (pinnedRef.current) element.scrollTop = element.scrollHeight;
     else if (anchorRef.current) {
       const anchor = anchorRef.current;
-      const node = Array.from(element.querySelectorAll<HTMLElement>("[data-agent-entry-id]")).find(item => item.dataset.agentEntryId === anchor.id);
+      const node = element.querySelector<HTMLElement>(`[data-agent-entry-id="${CSS.escape(anchor.id)}"]`);
-      if (node) element.scrollTop += node.getBoundingClientRect().top - element.getBoundingClientRect().top - anchor.offset;
+      const message = node?.querySelector<HTMLElement>("[data-agent-message-id]");
+      if (message) element.scrollTop += message.getBoundingClientRect().top - element.getBoundingClientRect().top - anchor.offset;
     }
     restoredScrollTopRef.current = element.scrollTop;
-    rememberAnchor();
+    // Keep the user's key/offset through successive intrinsic-size corrections.
+    // Recapturing here can anchor a newly revealed older row while its neighbors
+    // are still being measured, causing the original reading position to drift.
     scheduleRead();
   };
   const jumpToLatest = () => {
@@ -195,7 +211,7 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
 
   useLayoutEffect(() => {
     restoreViewport();
-  }, [room.messages, room.isTyping, room.activity?.state, room.isLoading, isVisible]);
+  }, [room.messages, room.isTyping, room.activity?.state, room.isLoading, room.isLoadingOlder, room.olderError, room.hasOlder, isVisible]);
 
   useEffect(() => {
     mountedRef.current = true;
@@ -229,10 +245,10 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
     setDraft(value);
   };
 
-  const retryMessage = (id: string) => {
+  const retryMessage = useCallback((id: string) => {
     // Admission errors remain attached to their own bubble.
     void room.retryMessage(id).catch(() => {});
-  };
+  }, [room.retryMessage]);
   const submit = () => {
     const content = draftRef.current.trim();
     if ((!content && !uploads.length) || pendingUploads || (uploads.length && !room.attachmentCapability)) return;
@@ -245,9 +261,14 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
 
   const messages = useMemo(() => {
     const transcript = agentTranscriptMessages(room.messages);
+    const historyChanged = historyBeforeRef.current !== room.historyBeforeCursor;
+    historyBeforeRef.current = room.historyBeforeCursor;
     let previousDay = "";
-    for (const message of transcript) {
+    let lastSeen = -1;
-      if (!seenMessageIdsRef.current.has(message.id) && historyReadyRef.current && !room.isLoading) {
+    transcript.forEach((message, index) => { if (seenMessageIdsRef.current.has(message.id)) lastSeen = index; });
+    for (const [index, message] of transcript.entries()) {
+      // Historical prepends keep their measured space; only new tail rows enter.
+      if (index > lastSeen && !(historyChanged && lastSeen < 0) && !seenMessageIdsRef.current.has(message.id) && historyReadyRef.current && !room.isLoading) {
         enteringMessageIdsRef.current.add(message.id);
       }
       seenMessageIdsRef.current.add(message.id);
@@ -263,7 +284,7 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
         </div>
       );
     });
-  }, [room.messages, room.isLoading, room.retryMessage, room.downloadAttachment]);
+  }, [room.messages, room.isLoading, room.historyBeforeCursor, room.retryMessage, room.downloadAttachment]);
 
   const activity = room.activity;
   const running = room.isTyping;
@@ -309,6 +330,12 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
         >
           <div ref={timelineRef} className="agent-room__timeline">
             {room.isLoading && !messages.length ? <div className="agent-room__empty" role="status"><LoaderCircle className="h-5 w-5 animate-spin" aria-hidden="true" /><span className="sr-only">Loading conversation</span></div> : null}
+            {room.hasOlder ? <div className="agent-room__history">
+              <button type="button" disabled={room.isLoadingOlder} onClick={() => {
+                pinnedRef.current = false; rememberAnchor(); room.loadOlder();
+              }}>{room.isLoadingOlder ? "Loading older messages…" : "Load older messages"}</button>
+              {room.olderError ? <span role="alert">{room.olderError} Try loading again.</span> : null}
+            </div> : null}
             {messages}
             {running ? <div className="agent-room__typing" role="status" aria-live="polite"><span className="agent-room__typing-dots" aria-hidden="true"><i /><i /><i /></span><span>{workingLabel}</span>{(activity?.backgroundWorkers || 0) > 1 ? <span className="agent-room__worker-count">{activity!.backgroundWorkers} workers</span> : null}</div> : null}
             {!running && waiting && activity?.wait ? <div className="agent-room__waiting" role="status"><Clock3 size={13} /><span>Checking back at {timeFormat.format(new Date(activity.wait.due))}</span></div> : null}

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);
+    return renderMarkdown(prepared, openLinksInNewTab, allowImages);
-  }, [markdown, mode, openLinksInNewTab, resolveCitationIndex]);
+  }, [markdown, mode, openLinksInNewTab, resolveCitationIndex, allowImages]);
 
   return <div className={cn("md-content", className)} dangerouslySetInnerHTML={{ __html: html }} />;
 }

web/src/hooks/use-agent-room.ts

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks"
 import { getApiBaseUrl, getAuthToken, type Message } from "@/lib/api";
 import {
   AGENT_ADMISSION_STORAGE_KEY, AgentRoomClient, agentAuthFrame, agentDisplayMessages, agentUnreadCount,
-  applyAgentEvent, applyAgentReadState,
+  applyAgentEvent, applyAgentReadState, applyAgentHistoryPage, agentUnreadCountIsPartial,
   createAgentReadSession, createAgentRoomState, parseAgentRoomEvent, syncAgentHistory,
   type AgentActivity, type AgentRoomState,
 } from "@/lib/agent-room";
@@ -16,6 +16,7 @@ export type AgentRoomConnection = "connecting" | "connected" | "reconnecting" |
 export type AgentRoomHookResult = {
   messages: Message[]; activity: AgentActivity | null; unreadCount: number;
   connection: AgentRoomConnection; error: string | null; isLoading: boolean; isTyping: boolean;
+  hasOlder: boolean; historyBeforeCursor: string | null; isLoadingOlder: boolean; olderError: string | null; loadOlder(): void; unreadCountIsPartial: boolean;
   attachmentCapability?: AgentAttachmentCapability;
   uploadAttachment(file: File, uploadId: string, signal: AbortSignal): Promise<AgentAttachment>;
   downloadAttachment(file: AgentAttachment, signal?: AbortSignal): Promise<Blob>;
@@ -33,6 +34,9 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
   const [attachmentCapability, setAttachmentCapability] = useState<AgentAttachmentCapability>();
   const [error, setError] = useState<string | null>(null);
   const [isLoading, setLoading] = useState(enabled);
+  const [isLoadingOlder, setLoadingOlder] = useState(false);
+  const [olderError, setOlderError] = useState<string | null>(null);
+  const older = useRef<(() => Promise<void>) | null>(null);
   const [revision, setRevision] = useState(0);
   const client = useRef<AgentRoomClient | null>(null);
   const [, renderUploads] = useState(0);
@@ -81,9 +85,10 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
   }
 
   useEffect(() => {
+    setLoadingOlder(false); setOlderError(null);
     if (!enabled) {
       sourceMismatch.current = false;
-      client.current = null; mark.current = null; setAttachmentCapability(undefined);
+      client.current = null; mark.current = null; older.current = null; setAttachmentCapability(undefined);
       update(() => createAgentRoomState()); setLoading(false); setConnection("offline"); setError(null);
       return;
     }
@@ -96,6 +101,7 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
     let reconnectAttempt = 0;
     let started = false;
     let maintaining = false;
+    let loadingOlder = false;
     let lastPacket = Date.now();
     let socketAuthenticated = false;
     let authFailed = false;
@@ -110,7 +116,7 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
         setView({ room: next, isTyping });
       },
     });
-    setLoading(current.current.conversationId === null); setConnection("connecting"); setError(null);
+    setLoading(!current.current.historyLoaded); setConnection("connecting"); setError(null);
     const reportError = (failure: unknown) => { if (active && !controller.signal.aborted) setError(errorText(failure)); };
     const readSession = createAgentReadSession({
       initial: current.current,
@@ -119,6 +125,7 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
         sourceChanged = true; sourceMismatch.current = true; mark.current = null;
         clearTimeout(reconnectTimer); clearTimeout(startupTimer); clearTimeout(socketTimeout);
         presenter.dispose(); controller.abort(); socket?.close();
+        older.current = null; setLoadingOlder(false);
         setError(failure.message); setConnection("offline"); setLoading(false);
       },
       apply: read => {
@@ -139,6 +146,22 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
       const descriptor = await api.descriptor(controller.signal);
       if (active && !sourceChanged) { setAttachmentCapability(descriptor.capabilities?.attachments?.version === 1 ? descriptor.capabilities.attachments : undefined); presenter.push({ type: "activity", conversationId: descriptor.id, activity: descriptor.activity }); }
     };
+    older.current = async () => {
+      const before = current.current.beforeCursor;
+      if (!active || sourceChanged || !started || loadingOlder || !current.current.hasOlder || before === null) return;
+      loadingOlder = true; setLoadingOlder(true); setOlderError(null);
+      try {
+        const page = await api.history(before, controller.signal);
+        if (!active || sourceChanged || controller.signal.aborted) return;
+        presenter.update(state => applyAgentHistoryPage(state, page, before));
+        presenter.flush();
+      } catch (failure) {
+        if (active && !sourceChanged && !controller.signal.aborted) setOlderError(errorText(failure));
+      } finally {
+        loadingOlder = false;
+        if (active && !sourceChanged) setLoadingOlder(false);
+      }
+    };
 
     const connect = () => {
       if (!active || authFailed || sourceChanged) return;
@@ -191,9 +214,11 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
     const start = async () => {
       try {
         await Promise.all([refreshRead(), refreshActivity()]);
-        // The first start begins at zero, not the latest page. Unread counts
+        if (!current.current.historyLoaded) {
-        // therefore include older public replies even after a long absence.
+          const page = await api.history(undefined, controller.signal);
-        await catchUp(!started);
+          if (!active || sourceChanged || controller.signal.aborted) return;
+          presenter.update(state => applyAgentHistoryPage(state, page));
+        } else await catchUp(!started);
         if (!active || sourceChanged) return;
         presenter.flush();
         started = true; setLoading(false); connect();
@@ -231,18 +256,19 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
       window.removeEventListener("focus", focus); document.removeEventListener("visibilitychange", focus);
       socket?.close();
       if (client.current === api) client.current = null;
-      mark.current = null;
+      mark.current = null; older.current = null;
     };
   }, [enabled, revision, update]);
 
   const renderedCursor = room.cursor;
   const renderedSourceId = room.sourceId;
+  const hasRenderedHistory = room.messages.some(message => message.role === "user" || message.role === "assistant");
   const markRead = useCallback(() => {
-    if (!enabled || isLoading) return;
+    if (!enabled || isLoading || !hasRenderedHistory) return;
     // This callback belongs to this rendered snapshot. Reading current.current
     // here would incorrectly mark a socket message that has not rendered yet.
     mark.current?.(renderedCursor, renderedSourceId);
-  }, [enabled, isLoading, renderedCursor, renderedSourceId]);
+  }, [enabled, isLoading, hasRenderedHistory, renderedCursor, renderedSourceId]);
   const sendMessage = useCallback(async (content: string, attachments?: AgentAttachment[], onPersisted?: () => void) => {
     if (!enabled || !outbox.current) throw new Error("Agent connection is unavailable.");
     await outbox.current.send(content, attachments, () => { uploadQueue.current!.clear(); onPersisted?.(); });
@@ -263,7 +289,9 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
     if (sourceMismatch.current) { window.location.reload(); return; }
     setRevision(value => value + 1);
   }, []);
+  const loadOlder = useCallback(() => { void older.current?.(); }, []);
   const messages = useMemo(() => outbox.current?.display(agentDisplayMessages(room)) || agentDisplayMessages(room), [room.messages, room.activity, outboxRevision]);
   return { messages: enabled ? messages : [], activity: room.activity, unreadCount: agentUnreadCount(room), connection, error, isLoading,
+    hasOlder: room.hasOlder, historyBeforeCursor: room.beforeCursor, isLoadingOlder, olderError, loadOlder, unreadCountIsPartial: agentUnreadCountIsPartial(room),
     attachmentCapability, uploadQueue: uploadQueue.current!, uploadAttachment, downloadAttachment, isTyping: enabled && view.isTyping, sendMessage, retryMessage, markRead, retry };
 }

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,12 +18,13 @@ 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 = {
   conversationId: string | null; messages: Message[]; cursor: string;
   readCursor: string; activity: AgentActivity | null;
+  historyLoaded: boolean; beforeCursor: string | null; hasOlder: boolean;
   /** undefined before the first read snapshot; null pins a legacy source-less session. */
   sourceId?: string | null;
 };
@@ -84,6 +85,7 @@ export function mergeAgentMessages(previous: readonly Message[], incoming: reado
 }
 export const createAgentRoomState = (): AgentRoomState => ({
   conversationId: null, messages: [], cursor: "0", readCursor: "0", activity: null,
+  historyLoaded: false, beforeCursor: null, hasOlder: false,
 });
 export class AgentReadSourceChangedError extends Error {
   constructor() { super("Agent history changed. Reload the page before marking messages read."); this.name = "AgentReadSourceChangedError"; }
@@ -102,6 +104,25 @@ export function applyAgentPage(state: AgentRoomState, page: AgentMessagesPage):
   const cursor = page.cursor === null ? state.cursor : advanceAgentCursor(state.cursor, page.cursor);
   return { ...state, conversationId: page.conversationId, messages: mergeAgentMessages(state.messages, page.messages), cursor };
 }
+/** Recent/older windows have their own boundary; live replay never moves it. */
+export function applyAgentHistoryPage(state: AgentRoomState, page: AgentMessagesPage, before?: string): AgentRoomState {
+  // A retired or repeated older request cannot overwrite a newer window.
+  if (before !== undefined && before !== state.beforeCursor) return state;
+  const boundary = page.beforeCursor === null ? null : normalizeAgentCursor(page.beforeCursor);
+  const cursor = page.cursor === null ? null : normalizeAgentCursor(page.cursor);
+  if (page.hasMore && (boundary === null || boundary === "0"
+    || (before !== undefined && BigInt(boundary) >= BigInt(before)))) throw new Error("Agent older history did not advance its cursor.");
+  if (before !== undefined && ((cursor !== null && BigInt(cursor) >= BigInt(before))
+    || (boundary !== null && BigInt(boundary) > BigInt(before)))) throw new Error("Agent older history returned an invalid boundary.");
+  const next = applyAgentPage(state, page);
+  return { ...next, historyLoaded: true, beforeCursor: boundary, hasOlder: page.hasMore,
+    // Older snapshots must not replace newer socket edits or advance delivery/read state.
+    ...(before === undefined ? {} : { cursor: state.cursor, messages: mergeAgentMessages(page.messages, state.messages) }),
+  };
+}
+export function agentUnreadCountIsPartial(state: AgentRoomState): boolean {
+  return state.hasOlder && state.beforeCursor !== null && BigInt(state.readCursor) + 1n < BigInt(state.beforeCursor);
+}
 export function applyAgentReadState(state: AgentRoomState, read: AgentReadState): AgentRoomState {
   const sourceId = readSource(state, read);
   return { ...state, sourceId, readCursor: advanceAgentCursor(state.readCursor, read.cursor) };
@@ -154,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);
@@ -178,6 +201,9 @@ export class AgentRoomClient {
   messages(after: string, signal?: AbortSignal): Promise<AgentMessagesPage> {
     return this.request(`/messages?${new URLSearchParams({ after: normalizeAgentCursor(after), limit: "200" })}`, { signal });
   }
+  history(before?: string, signal?: AbortSignal): Promise<AgentMessagesPage> {
+    return this.request(`/messages?${new URLSearchParams({ ...(before === undefined ? {} : { before: normalizeAgentCursor(before) }), limit: "100" })}`, { signal });
+  }
   readState(signal?: AbortSignal): Promise<AgentReadState> { return this.request("/read-state", { signal }); }
   markRead(cursor: string, signal?: AbortSignal, sourceId?: string | null): Promise<AgentReadState> {
     return this.request("/read-state", { method: "PUT", body: JSON.stringify({ cursor: normalizeAgentCursor(cursor), ...(agentPushSourceId(sourceId) ? { sourceId } : {}) }), signal });
@@ -199,12 +225,46 @@ export class AgentRoomClient {
   }
   async download(attachment: AgentAttachment, signal?: AbortSignal): Promise<Blob> {
     const file = parseAgentAttachment(attachment), headers = new Headers(), token = this.token();
+    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) { const error = await response.json().catch(() => null); throw new Error(error?.message || "Attachment download failed."); }
+      if (!response.ok) { await response.body?.cancel(); throw new Error("Attachment download failed. Retry the download."); }
-    const blob = await response.blob();
+      const reader = response.body?.getReader();
-    if (blob.size !== file.sizeBytes || blob.size > 8 * 1024 * 1024) throw new Error("Attachment download was incomplete.");
+      if (!reader) throw new Error("Attachment download was incomplete.");
-    return blob;
+      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.browser.mjs

@@ -11,13 +11,15 @@ const browser=await chromium.launch({executablePath:process.env.CHROME_EXECUTABL
   ...(process.env.BROWSER_NO_SANDBOX === '1' ? {args:['--no-sandbox']} : {})});
 const context=await browser.newContext({viewport:{width:1200,height:900},permissions:['clipboard-write']});
 await context.addInitScript(()=>localStorage.setItem('sybil_admin_token','browser-fixture-token'));
-const page=await context.newPage(), errors=[], uploads=[], sends=[], downloads=[];
+const page=await context.newPage(), errors=[], uploads=[], sends=[], downloads=[], trackingRequests=[];
 page.on('pageerror',e=>errors.push(e.stack || e.message));
 const cap={version:1,maxCount:8,maxTotalBytes:33554432,maxImageBytes:6291456,maxFileBytes:8388608,imageMimeTypes:['image/png','image/jpeg','image/gif','image/webp'],quotaBytes:1073741824,usedBytes:0,remainingBytes:1073741824,maxConcurrentUploads:2,maxConcurrentDecodes:1};
 const idle={state:'idle',isThinking:false,queued:0,backgroundWorkers:0,tools:[],queuedMessages:[]};
-let failedUpload=true, failedSend=true, live, cursor=0;const history=[];
+let failedUpload=true, failedSend=true, live, cursor=0, inputAttachments=true;const history=[];
 const image=Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a2ioAAAAASUVORK5CYII=','base64');
 const attachment=(name='notes.txt')=>({id:`att_12345678-1234-4234-8234-${name==='picture.png'?'123456789abd':'123456789abc'}`,filename:name,mimeType:name==='picture.png'?'image/png':'text/plain',kind:name==='picture.png'?'image':'text',sizeBytes:name==='picture.png'?image.length:4,sha256:createHash('sha256').update(name==='picture.png'?image:Buffer.from('data')).digest('hex'),workspacePath:`/data/workspace/uploads/test/${name}`});
+const assistantImage={...attachment('picture.png'),id:'att_12345678-1234-4234-8234-123456789abe',filename:'assistant.png'};delete assistantImage.workspacePath;
+await page.route('https://never-fetch.invalid/**',async route=>{trackingRequests.push(route.request().url());await route.abort();});
 await page.route('**/api/**',async route=>{
  const req=route.request(),url=new URL(req.url()),p=url.pathname,m=req.method();let value;
  if(p.startsWith('/api/v1/agent'))assert.equal(req.headers().authorization,'Bearer browser-fixture-token');
@@ -26,7 +28,7 @@ await page.route('**/api/**',async route=>{
   if(failedUpload){failedUpload=false;await route.fulfill({status:507,json:{message:'Storage quota reached',code:'attachment_quota_exceeded'}});return;}
   await route.fulfill({status:201,json:{attachment:attachment(body.includes('picture.png')?'picture.png':'notes.txt')}});return;
  }
- if(p.endsWith('/content')){downloads.push(req.url());await route.fulfill({contentType:p.includes('789abd')?'image/png':'text/plain',body:p.includes('789abd')?image:'data'});return;}
+ if(p.endsWith('/content')){downloads.push(req.url());const isImage=p.includes('789abd')||p.includes('789abe');await route.fulfill({contentType:isImage?'image/png':'text/plain',body:isImage?image:'data'});return;}
  if(p.endsWith('/agent/messages')&&m==='POST'){
   const body=req.postDataJSON();sends.push(body);
   if(failedSend){failedSend=false;await route.fulfill({status:503,json:{message:'Temporarily unavailable'}});return;}
@@ -37,7 +39,7 @@ await page.route('**/api/**',async route=>{
  }
  if(p.endsWith('/agent/messages'))value={conversationId:'1',messages:history,cursor:String(cursor),beforeCursor:null,hasMore:false};
  else if(p.endsWith('/read-state'))value={cursor:String(cursor),updatedAt:null};
- else if(p.endsWith('/agent'))value={id:'1',title:'Sybil Agent',activity:idle,capabilities:{attachments:cap},protocol:'pi-room.v1',websocket:'/v1/agent/ws'};
+ else if(p.endsWith('/agent'))value={id:'1',title:'Sybil Agent',activity:idle,capabilities:{...(inputAttachments?{attachments:cap}:{}),assistantImages:{version:1}},protocol:'pi-room.v1',websocket:'/v1/agent/ws'};
  else if(p.includes('session'))value={mode:'token',authenticated:true};
  else if(p.endsWith('/tools')||p.endsWith('/chat-tools'))value={tools:[]};
  else if(p.endsWith('/models'))value={models:[],providers:{}};
@@ -75,7 +77,28 @@ try{
  await page.getByText('Uploaded',{exact:true}).waitFor();await page.getByRole('button',{name:'Remove notes.txt'}).click();
  await page.locator('.agent-room__composer-area').evaluate(el=>{const data=new DataTransfer();data.items.add(new File(['data'],'notes.txt',{type:'text/plain'}));el.dispatchEvent(new DragEvent('drop',{dataTransfer:data,bubbles:true,cancelable:true}));});
  await page.getByText('Uploaded',{exact:true}).waitFor();
+ await page.getByRole('button',{name:'Remove notes.txt'}).click();
+ // Assistant image-only messages use authenticated bytes automatically, with no source path.
+ const assistant={id:'outbound:900',role:'assistant',createdAt:new Date().toISOString(),content:'',metadata:{kind:'message',status:'complete',entryId:++cursor,agentAttachments:[assistantImage]}};history.push(assistant);
+ live.send(JSON.stringify({type:'messages',conversationId:'1',messages:[assistant],cursor:String(cursor),beforeCursor:String(cursor),hasMore:false}));
+ const assistantBubble=page.locator('[data-agent-message-id="outbound:900"]'),inlineImage=assistantBubble.locator('.agent-attachment__preview');
+ await inlineImage.waitFor();await inlineImage.evaluate(img=>img.decode());
+ assert.ok((await inlineImage.getAttribute('src')).startsWith('blob:'));
+ assert.equal(await assistantBubble.getByRole('button',{name:'Preview',exact:true}).count(),0);
+ assert.equal(await assistantBubble.locator('.agent-attachment__path').count(),0);
+ const tracking={id:'outbound:901',role:'assistant',createdAt:new Date().toISOString(),content:'Remote images must not load.\n\n![tracking](https://never-fetch.invalid/markdown.png) <img src="https://never-fetch.invalid/html.png">',metadata:{kind:'message',status:'complete',entryId:++cursor}};history.push(tracking);
+ live.send(JSON.stringify({type:'messages',conversationId:'1',messages:[tracking],cursor:String(cursor),beforeCursor:String(cursor),hasMore:false}));
+ await page.getByText('Remote images must not load.',{exact:true}).waitFor();
+ assert.equal(await page.locator('[data-agent-message-id="outbound:901"] .md-content img').count(),0);
+ // An output-only capability must preserve history without enabling input controls.
+ inputAttachments=false;await page.reload({waitUntil:'networkidle'});await page.locator('[data-testid="agent-sidebar-item"]').click();
+ await inlineImage.waitFor();await inlineImage.evaluate(img=>img.decode());
+ assert.equal(await assistantBubble.count(),1);assert.equal(await page.locator('.agent-attachment__preview').count(),1);
+ assert.ok((await inlineImage.getAttribute('src')).startsWith('blob:'));
+ assert.equal(await page.getByRole('button',{name:'Attach files',exact:true}).count(),0);
+ assert.equal(await page.getByLabel('Choose attachments').count(),0);
+ assert.deepEqual(trackingRequests,[],'Neither live nor historical Markdown/HTML image markup fetches remote bytes');
  await page.setViewportSize({width:390,height:844});if(process.env.ATTACHMENT_SCREENSHOT)await page.screenshot({path:process.env.ATTACHMENT_SCREENSHOT});
  assert.equal(await page.evaluate(()=>document.documentElement.scrollWidth>window.innerWidth),false);
- assert.deepEqual(errors,[]);console.log('PASS browser picker/retry/quota/remove, file-only send/reload, authenticated preview/download, copy, paste/drop, mobile layout');
+ assert.deepEqual(errors,[]);console.log('PASS browser picker/retry/quota/remove, file-only send/reload, authenticated preview/download, copy, paste/drop, assistant image-only live/history, output-only capability, blocked Markdown/HTML images, mobile layout');
 }finally{await context.close();await browser.close();}

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

web/tests/agent-room.test.mjs

@@ -4,6 +4,7 @@ import {
   AgentRoomClient, AgentReadSourceChangedError, advanceAgentCursor, agentAuthFrame, agentDisplayMessages, agentUnreadCount,
   applyAgentEvent, applyAgentPage, applyAgentReadState, createAgentReadSession, createAgentReadWriter,
   createAgentRoomState, mergeAgentMessages, normalizeAgentCursor, parseAgentRoomEvent, syncAgentHistory,
+  applyAgentHistoryPage, agentUnreadCountIsPartial,
 } from "../src/lib/agent-room.ts";
 import { createAgentOptimisticOutbox } from "../src/lib/agent-optimistic-outbox.ts";
 
@@ -32,7 +33,7 @@ test("tool starts and results merge across replay without downgrading completed
   assert.equal(messages[0].createdAt, start.createdAt);
 });
 
-test("initial synchronization reads every page including invisible entries and counts only unread assistant messages", async () => {
+test("forward recovery reads every missing page including invisible entries and counts only unread assistant messages", async () => {
   const requests = [];
   const responses = [page("2", [message(1), message(2, "user")], true), page("4", [], true), page("7", [message(5), message(6, "tool"), message(7)], false)];
   let state = createAgentRoomState();
@@ -47,6 +48,78 @@ test("initial synchronization reads every page including invisible entries and c
   assert.equal(agentUnreadCount(state), 1);
 });
 
+test("recent history is one cursorless window and older history uses the returned source boundary", async () => {
+  const requests = [];
+  const client = new AgentRoomClient({ fetch: async (url, options) => {
+    requests.push({ url, signal: options.signal });
+    return new Response(JSON.stringify({ ...page("1200", [message(1200)], true), beforeCursor: "1101" }));
+  } });
+  const controller = new AbortController();
+  let state = applyAgentHistoryPage(createAgentRoomState(), await client.history(undefined, controller.signal));
+  assert.equal(requests.length, 1, "hasMore must not drain old history");
+  assert.equal(requests[0].url, "/api/v1/agent/messages?limit=100");
+  assert.equal(requests[0].signal, controller.signal);
+  assert.equal(state.historyLoaded, true);
+  assert.equal(state.cursor, "1200");
+  assert.equal(state.beforeCursor, "1101", "boundary is not derived from visible message 1200");
+  assert.equal(state.hasOlder, true);
+  await client.history(state.beforeCursor, controller.signal);
+  assert.equal(requests[1].url, "/api/v1/agent/messages?before=1101&limit=100");
+});
+
+test("delayed older pages preserve newer edits, live cursor, source and read state", () => {
+  let state = applyAgentHistoryPage(sourceRoom(), { ...page("100", [message(100)], true), beforeCursor: "90" });
+  state = applyAgentPage(state, page("110", [message(100, "assistant", { content: "New streamed text" }), message(110)]));
+  const next = applyAgentHistoryPage(state, { ...page("89", [message(80), message(100, "assistant", { content: "Old snapshot" })], true), beforeCursor: "70" }, "90");
+  assert.equal(next.messages.find(m => m.id === "entry:100").content, "New streamed text");
+  assert.equal(next.cursor, "110");
+  assert.equal(next.readCursor, "90");
+  assert.equal(next.sourceId, sourceA);
+  assert.equal(next.beforeCursor, "70");
+  assert.equal(next.hasOlder, true);
+  assert.equal(applyAgentHistoryPage(next, page("89", [message(80)], false), "90"), next, "retired boundary cannot replace the next window");
+});
+
+test("empty internal pages advance older boundaries without chasing another page or moving read state", () => {
+  const initial = applyAgentHistoryPage(createAgentRoomState(), { ...page("1200", [], true), beforeCursor: "1101" });
+  assert.equal(initial.historyLoaded, true);
+  assert.equal(initial.messages.length, 0);
+  const next = applyAgentHistoryPage(initial, { ...page("1100", [], true), beforeCursor: "1001" }, "1101");
+  assert.equal(next.beforeCursor, "1001");
+  assert.equal(next.cursor, "1200");
+  assert.equal(next.readCursor, "0");
+  assert.equal(next.hasOlder, true);
+  const end = applyAgentHistoryPage(next, { ...page("0"), beforeCursor: "1001" }, "1001");
+  assert.equal(end.hasOlder, false);
+  assert.equal(end.cursor, "1200");
+});
+
+test("malformed or stalled older pages cannot change history or delivery boundaries", () => {
+  const state = applyAgentHistoryPage(createAgentRoomState(), { ...page("100", [message(100)], true), beforeCursor: "90" });
+  for (const bad of [
+    { ...page("89", [], true), beforeCursor: "90" },
+    { ...page("89", [], true), beforeCursor: null },
+    { ...page("91", [], false), beforeCursor: "80" },
+    { ...page("89", [], false), beforeCursor: "91" },
+    { ...page("bad", [], false), beforeCursor: "80" },
+  ]) assert.throws(() => applyAgentHistoryPage(state, bad, "90"), /cursor|boundary/);
+  assert.throws(() => applyAgentHistoryPage(state, { ...page("89"), conversationId: "different" }, "90"), /conversation changed/);
+  assert.equal(state.beforeCursor, "90");
+  assert.equal(state.cursor, "100");
+});
+
+test("unread counts disclose unknown older replies until reading the latest rendered window", () => {
+  let state = applyAgentHistoryPage(createAgentRoomState(), { ...page("1200", [message(1199), message(1200, "user")], true), beforeCursor: "1101" });
+  assert.equal(agentUnreadCount(state), 1);
+  assert.equal(agentUnreadCountIsPartial(state), true);
+  state = applyAgentReadState(state, { cursor: "1100", updatedAt: null });
+  assert.equal(agentUnreadCountIsPartial(state), false);
+  assert.equal(agentUnreadCount(state), 1);
+  state = applyAgentReadState(state, { cursor: "1200", updatedAt: null });
+  assert.equal(agentUnreadCount(state), 0);
+  assert.equal(state.hasOlder, true, "reading latest does not fetch or discard older pages");
+});
+
 test("queued user messages keep stable IDs and disappear if withdrawn or promoted", () => {
   const pending = message(1, "user", { id: "inbound:sybil:request1", metadata: { kind: "message", status: "queued" } });
   let state = applyAgentEvent(createAgentRoomState(), { type: "activity", conversationId: "1", activity: activity([pending]) });

web/tests/agent-transcript.browser.mjs

@@ -0,0 +1,250 @@
+import assert from 'node:assert/strict';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+// Local production preview; all APIs/sockets are synthetic and external requests are blocked.
+// PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs WEB_TEST_URL=http://127.0.0.1:5196
+// TRANSCRIPT_EVIDENCE=/tmp/evidence TRANSCRIPT_BASELINE=1 node tests/agent-transcript.browser.mjs
+const { chromium } = await import(process.env.PLAYWRIGHT_MODULE || 'playwright');
+const target = new URL(process.env.WEB_TEST_URL || 'http://127.0.0.1:5196/');
+assert.ok(target.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(target.hostname));
+const baseline = process.env.TRANSCRIPT_BASELINE === '1';
+const evidence = process.env.TRANSCRIPT_EVIDENCE;
+if (evidence) await mkdir(evidence, { recursive: true });
+const browser = await chromium.launch({ headless: true, executablePath: process.env.CHROME_EXECUTABLE || undefined });
+const context = await browser.newContext({ viewport: { width: 1280, height: 900 }, serviceWorkers: 'block' });
+const page = await context.newPage();
+const errors = [], requests = [], reads = [], socketCursors = [];
+page.on('pageerror', error => errors.push(error.message));
+const idle = { state: 'idle', isThinking: false, queued: 0, backgroundWorkers: 0, tools: [], queuedMessages: [] };
+const sourceId = '00000000-0000-4000-8000-000000000001';
+const row = (id, content) => ({ id: `entry:${id}`, role: id % 3 ? 'assistant' : 'user',
+  createdAt: new Date(Date.UTC(2026, 9, 16, 0, 0, id)).toISOString(),
+  content: content || `Fixture message ${id}\n\n${'Synthetic transcript text for delayed loading. '.repeat(id % 11 === 0 ? 30 : 3)}`,
+  metadata: { kind: 'message', entryId: id, status: 'complete' } });
+const history = Array.from({ length: 1200 }, (_, i) => row(i + 1));
+let live, readCursor = '0', failOlder = false, imageBytes, emptyRecent = false;
+const start = performance.now();
+const elapsed = () => Math.round(performance.now() - start);
+await context.addInitScript(() => {
+  localStorage.clear(); sessionStorage.clear();
+  window.fixtureTiming = {};
+  const sample = () => {
+    const scroller = document.querySelector('.agent-room__scroll');
+    if (scroller) {
+      const box = scroller.getBoundingClientRect();
+      const visible = [...scroller.querySelectorAll('[data-agent-message-id]')].filter(e => {
+        const r = e.getBoundingClientRect(); return r.bottom > box.top && r.top < box.bottom;
+      });
+      if (visible.length && !window.fixtureTiming.first) window.fixtureTiming.first = { ms: performance.now(), ids: visible.map(e => e.dataset.agentMessageId) };
+      if (visible.some(e => e.dataset.agentMessageId === 'entry:1200') && !window.fixtureTiming.latestMs) window.fixtureTiming.latestMs = performance.now();
+    }
+    if (!window.fixtureTiming.latestMs) requestAnimationFrame(sample);
+  };
+  requestAnimationFrame(sample);
+});
+await page.route('**/*', async route => {
+  const req = route.request(), url = new URL(req.url());
+  if (url.origin !== target.origin) return route.abort();
+  if (!url.pathname.startsWith('/api/')) return route.continue();
+  const path = url.pathname, method = req.method();
+  assert.equal(req.headers().authorization, undefined, 'Fixture must never use a real credential');
+  let value;
+  if (path.endsWith('/content')) {
+    await new Promise(resolve => setTimeout(resolve, 600));
+    return route.fulfill({ contentType: 'image/png', body: imageBytes });
+  } else if (path.endsWith('/agent/messages')) {
+    assert.equal(method, 'GET', 'Fixture must not send messages');
+    const after = url.searchParams.get('after'), before = url.searchParams.get('before'), limit = Number(url.searchParams.get('limit') || 200);
+    const record = { query: url.search, requestedMs: elapsed() }; requests.push(record);
+    await new Promise(resolve => setTimeout(resolve, before ? 1600 : 800));
+    if (before && failOlder) { failOlder = false; return route.fulfill({ status: 503, json: { message: 'Fixture older page unavailable' } }); }
+    const eligible = history.filter(m => after !== null ? m.metadata.entryId > Number(after) : before !== null ? m.metadata.entryId < Number(before) : true);
+    const messages = after !== null ? eligible.slice(0, limit) : eligible.slice(-limit);
+    value = { conversationId: 'fixture-room', messages, cursor: String(messages.at(-1)?.metadata.entryId ?? after ?? 0),
+      beforeCursor: messages.length ? String(messages[0].metadata.entryId) : null, hasMore: eligible.length > messages.length };
+    if (emptyRecent && before === null && after === null) value.messages = [];
+    Object.assign(record, { responseMs: elapsed(), rows: messages.length, bytes: Buffer.byteLength(JSON.stringify(value)) });
+  } else if (path.endsWith('/read-state')) {
+    if (method === 'PUT') { readCursor = req.postDataJSON().cursor; reads.push({ cursor: readCursor, ms: elapsed() }); }
+    value = { cursor: readCursor, sourceId, updatedAt: null };
+  } else if (path.endsWith('/agent')) value = { id: 'fixture-room', title: 'Sybil Agent', activity: idle, protocol: 'pi-room.v1', websocket: '/v1/agent/ws' };
+  else if (path.endsWith('/auth/session')) value = { authenticated: true, mode: 'open' };
+  else if (path.endsWith('/models')) value = { models: [], providers: {} };
+  else if (path.endsWith('/tools') || path.endsWith('/chat-tools')) value = { tools: [] };
+  else value = [];
+  await route.fulfill({ json: value });
+});
+await page.routeWebSocket('**/api/v1/agent/ws', socket => {
+  live = socket;
+  socket.onMessage(raw => { const frame = JSON.parse(String(raw)); if (frame.type === 'auth') {
+    assert.equal(frame.token, null); socketCursors.push(frame.after);
+    socket.send(JSON.stringify({ type: 'ready', conversationId: 'fixture-room' }));
+  } });
+});
+const send = messages => {
+  for (const message of messages) { const index = history.findIndex(m => m.id === message.id); if (index < 0) history.push(message); else history[index] = message; }
+  live.send(JSON.stringify({ type: 'messages', conversationId: 'fixture-room', messages,
+    cursor: String(messages.at(-1).metadata.entryId), beforeCursor: String(messages[0].metadata.entryId), hasMore: false }));
+};
+const position = () => page.locator('.agent-room__scroll').evaluate(el => ({ top: el.scrollTop, distance: el.scrollHeight - el.scrollTop - el.clientHeight,
+  rows: el.querySelectorAll('[data-agent-entry-id]').length }));
+const anchor = () => page.locator('.agent-room__scroll').evaluate(el => {
+  const top = el.getBoundingClientRect().top;
+  const entry = [...el.querySelectorAll('[data-agent-entry-id]')].find(e => e.getBoundingClientRect().bottom > top + 8);
+  return { id: entry.dataset.agentEntryId, offset: entry.querySelector('[data-agent-message-id]').getBoundingClientRect().top - top };
+});
+const anchorDrift = saved => page.locator('.agent-room__scroll').evaluate((el, saved) => {
+  const entry = [...el.querySelectorAll('[data-agent-entry-id]')].find(e => e.dataset.agentEntryId === saved.id);
+  return entry.querySelector('[data-agent-message-id]').getBoundingClientRect().top - el.getBoundingClientRect().top - saved.offset;
+}, saved);
+const metrics = { mode: baseline ? 'before' : 'after', fixtureRows: 1200, pageDelayMs: 800, olderDelayMs: 1600 };
+try {
+  await page.goto(new URL('/?agent=root', target).href, { waitUntil: 'domcontentloaded' });
+  await page.locator('[data-testid="agent-sidebar-item"]').click();
+  await page.waitForFunction(() => window.fixtureTiming?.first);
+  if (evidence) await page.screenshot({ path: `${evidence}/${metrics.mode}-first.png` });
+  await page.waitForFunction(() => window.fixtureTiming?.latestMs, { timeout: 20000 });
+  await page.getByRole('status').filter({ hasText: /^Connected$/ }).waitFor();
+  await page.waitForTimeout(400);
+  Object.assign(metrics, await page.evaluate(() => window.fixtureTiming), { initial: await position(), initialRequests: requests.map(r => ({ ...r })), socketCursors: [...socketCursors] });
+  if (evidence) await page.screenshot({ path: `${evidence}/${metrics.mode}-latest.png` });
+  if (!baseline) {
+    assert.equal(requests.length, 1, 'No eager older/forward chain on initial load');
+    assert.equal(new URLSearchParams(requests[0].query).has('after'), false);
+    assert.equal(socketCursors[0], '1200');
+    assert.ok(metrics.initial.rows <= 100);
+    assert.ok(metrics.initial.distance < 2);
+    await page.waitForTimeout(1800);
+    assert.equal(requests.length, 1, 'Idle initial view must not drain history');
+    await page.locator('.agent-room__scroll').evaluate(el => { el.scrollTop = 0; });
+    await page.waitForTimeout(150);
+    const saved = await anchor(), readBefore = readCursor;
+    await page.getByRole('button', { name: 'Load older messages', exact: true }).click();
+    send([row(1201)]);
+    await page.waitForTimeout(500);
+    assert.equal(readCursor, readBefore, 'Incoming while reading must stay unread');
+    metrics.incomingDriftPx = await anchorDrift(saved);
+    await page.getByRole('button', { name: 'Load older messages', exact: true }).waitFor();
+    await page.waitForTimeout(400);
+    metrics.prependDriftPx = await anchorDrift(saved);
+    metrics.afterPrepend = await position();
+    assert.ok(Math.abs(metrics.incomingDriftPx) < 2);
+    assert.ok(Math.abs(metrics.prependDriftPx) < 2);
+    assert.equal(readCursor, readBefore);
+    assert.equal(requests.length, 2, 'One user action loads one older page');
+    assert.equal(await page.locator('[data-agent-entry-id="entry:1001"] [data-animation="enter"]').count(), 0);
+    const beforeGrowth = await anchor();
+    send([row(1201, 'Dynamic streamed content.\n\n'.repeat(80))]);
+    await page.waitForTimeout(350);
+    metrics.streamingReadingDriftPx = await anchorDrift(beforeGrowth);
+    assert.ok(Math.abs(metrics.streamingReadingDriftPx) < 2);
+    await page.locator('.agent-room__scroll').evaluate(el => { el.scrollTop = el.scrollHeight; });
+    await page.waitForTimeout(250);
+    send([row(1201, 'Dynamic streamed content continues.\n\n'.repeat(100))]);
+    await page.waitForTimeout(400);
+    metrics.streamingPinnedDistancePx = (await position()).distance;
+    assert.ok(metrics.streamingPinnedDistancePx < 2);
+    const order = await page.locator('.agent-room__timeline').evaluate(el => {
+      const ids = [...el.querySelectorAll('[data-agent-entry-id]')].map(e => Number(e.dataset.agentEntryId.split(':')[1]));
+      const range = document.createRange(); range.selectNodeContents(el);
+      return { ids, text: range.toString(), direction: getComputedStyle(el).flexDirection,
+        skipped: [...el.querySelectorAll('[data-agent-message-id]')].filter(e => !e.checkVisibility({ contentVisibilityAuto: true })).length };
+    });
+    assert.deepEqual(order.ids, [...order.ids].sort((a, b) => a - b));
+    assert.ok(order.text.indexOf('Fixture message 1001') < order.text.indexOf('Fixture message 1200'));
+    assert.equal(order.direction, 'column');
+    assert.equal(await page.getByRole('button', { name: /latest/i }).count(), 0);
+    metrics.skippedOffscreenRows = order.skipped;
+    assert.ok(order.skipped > 0, 'Offscreen rows should skip layout/paint');
+    const ax = await page.locator('.agent-room__scroll').ariaSnapshot();
+    assert.ok(ax.includes('Fixture message 1001') && ax.includes('Fixture message 1200'));
+    assert.ok(ax.indexOf('Fixture message 1001') < ax.indexOf('Fixture message 1200'));
+
+    // Authenticated attachment bytes are synthetic, delayed, and never fetched off origin.
+    imageBytes = Buffer.from(await page.evaluate(() => {
+      const canvas = document.createElement('canvas'); canvas.width = 240; canvas.height = 180;
+      const ctx = canvas.getContext('2d'); ctx.fillStyle = '#8974da'; ctx.fillRect(0, 0, 240, 180);
+      return canvas.toDataURL('image/png').split(',')[1];
+    }), 'base64');
+    const file = { id: 'att_12345678-1234-4234-8234-123456789abc', filename: 'fixture.png', mimeType: 'image/png', kind: 'image',
+      sizeBytes: imageBytes.length, sha256: createHash('sha256').update(imageBytes).digest('hex') };
+    send([{ ...row(1202), metadata: { ...row(1202).metadata, agentAttachments: [file] } }]);
+    await page.waitForTimeout(500);
+    await page.getByRole('button', { name: 'Preview', exact: true }).click();
+    await page.locator('.agent-attachment__preview').waitFor();
+    await page.waitForTimeout(250);
+    metrics.attachmentPinnedDistancePx = (await position()).distance;
+    assert.ok(metrics.attachmentPinnedDistancePx < 2);
+    send([row(1203, 'Following the delayed attachment.\n\n'.repeat(60))]);
+    await page.waitForTimeout(500);
+    await page.locator('.agent-room__scroll').evaluate(el => {
+      const entry = el.querySelector('[data-agent-entry-id="entry:1203"]');
+      el.scrollTop += entry.getBoundingClientRect().top - el.getBoundingClientRect().top + 80;
+    });
+    await page.waitForTimeout(200);
+    const attachmentAnchor = await anchor();
+    // Collapse an earlier preview while reading the following message.
+    await page.getByRole('button', { name: 'Hide preview', exact: true }).evaluate(el => el.click());
+    await page.waitForTimeout(300);
+    metrics.attachmentReadingDriftPx = await anchorDrift(attachmentAnchor);
+    assert.ok(Math.abs(metrics.attachmentReadingDriftPx) < 2);
+
+    // A failed older page is locally retryable without clearing the recent window.
+    await page.locator('.agent-room__scroll').evaluate(el => { el.scrollTop = 0; });
+    await page.waitForTimeout(200);
+    const rowsBeforeFailure = (await position()).rows;
+    failOlder = true;
+    await page.getByRole('button', { name: 'Load older messages', exact: true }).click();
+    await page.getByRole('alert').filter({ hasText: 'Fixture older page unavailable' }).waitFor();
+    assert.equal((await position()).rows, rowsBeforeFailure);
+    const socketsBefore = socketCursors.length;
+    await page.getByRole('button', { name: 'Load older messages', exact: true }).click();
+    await page.waitForTimeout(150);
+    live.close({ code: 1012, reason: 'Fixture reconnect' });
+    await page.getByRole('button', { name: 'Reconnect to Sybil Agent', exact: true }).click();
+    await page.waitForTimeout(2200);
+    assert.ok(socketCursors.length > socketsBefore);
+    assert.equal(socketCursors.at(-1), '1203');
+    assert.equal((await position()).rows, rowsBeforeFailure, 'Retired older response must not publish into the new session');
+    assert.equal(await page.getByRole('alert').count(), 0);
+    await page.locator('.agent-room__scroll').evaluate(el => { el.scrollTop = 0; });
+    await page.getByRole('button', { name: 'Load older messages', exact: true }).click();
+    await page.waitForFunction(() => document.querySelector('[data-agent-entry-id="entry:901"]'));
+    metrics.retiredOlderIgnored = true;
+    metrics.olderFailureRetry = true;
+    assert.equal(requests.filter(r => r.query.includes('after=0')).length, 0);
+    await page.locator('.agent-room__scroll').evaluate(el => { el.scrollTop = el.scrollHeight; });
+    await page.waitForTimeout(200);
+    await page.setViewportSize({ width: 390, height: 844 });
+    await page.waitForTimeout(400);
+    metrics.mobilePinnedDistancePx = (await position()).distance;
+    assert.ok(metrics.mobilePinnedDistancePx < 2);
+    assert.equal(await page.evaluate(() => document.documentElement.scrollWidth > innerWidth), false);
+    assert.equal(await page.getByRole('button', { name: /latest/i }).count(), 0);
+    if (evidence) await page.screenshot({ path: `${evidence}/after-mobile.png` });
+    // A source window can contain only internal entries. It stays bounded and
+    // must not mark unloaded public history read or animate an older prepend.
+    emptyRecent = true; readCursor = '0';
+    const requestsBeforeEmpty = requests.length;
+    await page.setViewportSize({ width: 1280, height: 900 });
+    await page.goto(new URL('/?agent=root', target).href, { waitUntil: 'domcontentloaded' });
+    await page.locator('[data-testid="agent-sidebar-item"]').click();
+    await page.getByRole('button', { name: 'Load older messages', exact: true }).waitFor();
+    await page.waitForTimeout(1000);
+    assert.equal((await position()).rows, 0);
+    assert.equal(requests.length, requestsBeforeEmpty + 1);
+    assert.equal(readCursor, '0');
+    await page.getByRole('button', { name: 'Load older messages', exact: true }).click();
+    await page.waitForFunction(() => document.querySelectorAll('[data-agent-entry-id]').length > 0);
+    assert.equal(await page.locator('[data-animation="enter"]').count(), 0);
+    metrics.internalOnlyWindowBounded = true;
+    metrics.internalOnlyWindowUnacknowledged = true;
+  }
+  assert.deepEqual(errors, []);
+  metrics.requests = requests; metrics.reads = reads; metrics.errors = errors;
+  if (evidence) await writeFile(`${evidence}/${metrics.mode}.json`, JSON.stringify(metrics, null, 2));
+  console.log(JSON.stringify(metrics, null, 2));
+} catch (error) {
+  console.error(JSON.stringify({ metrics, requests, errors, body: (await page.locator('body').innerText()).slice(0, 1800) }));
+  throw error;
+} finally { await context.close(); await browser.close(); }