@adecore/agents 0.17.0-beta.2 → 0.18.0

package/dist/chat/attachment-store.d.ts

@@ -5,6 +5,6 @@ export declare class AttachmentStore {
     constructor(home: string);
     save(chatId: string, upload: ChatAttachmentUpload): Promise<ChatAttachment>;
     removeAll(chatId: string): Promise<void>;
-    private folder;
+    folderOf(chatId: string): string;
 }
 export declare function migrateInlineAttachments(chatId: string, record: unknown, store: AttachmentStore): Promise<unknown | null>;

package/dist/chat/attachment-store.js

@@ -44,7 +44,7 @@ export class AttachmentStore {
         const bytes = Buffer.from(upload.data, 'base64');
         const mime = attachmentImageMime(upload) ?? upload.mime;
         const id = randomBytes(8).toString('hex');
-        const folder = this.folder(chatId);
+        const folder = this.folderOf(chatId);
         await mkdir(folder, { recursive: true, mode: 0o700 });
         const path = join(folder, `${id}.${extensionFor(upload.name, mime)}`);
         await writeFile(path, bytes, { mode: 0o600 });
@@ -52,9 +52,10 @@ export class AttachmentStore {
     }
     /* Everything a chat attached; used when the chat itself is deleted. */
     async removeAll(chatId) {
-        await rm(this.folder(chatId), { recursive: true, force: true });
+        await rm(this.folderOf(chatId), { recursive: true, force: true });
     }
-    folder(chatId) {
+    /* Where the files of one chat are; a store that keeps more of a chat's files beside them writes them here. */
+    folderOf(chatId) {
         return join(this.dir, encodeURIComponent(chatId));
     }
 }

package/dist/chat/chat-core.d.ts

@@ -1,4 +1,4 @@
-import { type AgentKind, type ChatAttachment, type ChatAttachResult, type ChatAttachmentUpload, type ChatBookmark, type ChatCheckpointDiff, type ChatConfigurePayload, type ChatCreatePayload, type ChatEvent, type ChatHistoryResult, type ChatInfo, type ChatItem, type ChatQueuedMessage, type ChatSkill, type ChatSubagentPayload, type ChatSubagentResult, type ChatTurnItem, type ModelSelection, type RuntimeMode } from '@adecore/agent-contracts';
+import { type AgentKind, type ChatAttachment, type ChatAttachResult, type ChatAttachmentUpload, type ChatBookmark, type ChatCheckpointDiff, type ChatConfigurePayload, type ChatCreatePayload, type ChatEvent, type ChatHistoryResult, type ChatInfo, type ChatItem, type ChatQueuedMessage, type ChatSkill, type ChatSubagentPayload, type ChatSubagentResult, type ChatTurnItem, type ChatVisual, type ModelSelection, type RuntimeMode } from '@adecore/agent-contracts';
 import { ClientSinks } from '../client-sinks.ts';
 import type { AgentEvent, AgentSink } from '../events.ts';
 import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
@@ -18,6 +18,7 @@ import { ComposerPreferences } from './composer-preferences.ts';
 import { DeltaCoalescer } from './delta-coalescer.ts';
 import { type BackgroundWork } from './background-work.ts';
 import { SubagentReader, type SubagentReaderOptions } from './subagent-reader.ts';
+import type { VisualInput, VisualStore } from './visual-store.ts';
 export interface InterruptedRun {
     chatId: string;
     turnId: string;
@@ -36,6 +37,7 @@ export interface ChatCoreOptions {
     skills?: SkillIndex;
     attachments: AttachmentStore;
     bookmarks?: BookmarkStore;
+    visuals?: VisualStore;
     onLimits?: (update: LimitsUpdate) => void;
     claudeTitles?: {
         forSession(agentSessionId: string, projectsDir: string): Promise<string | null>;
@@ -56,6 +58,7 @@ export declare class ChatCore {
     protected readonly providers: ProviderRegistry;
     protected readonly store: ChatStore | null;
     protected readonly bookmarks: BookmarkStore | null;
+    protected readonly visuals: VisualStore | null;
     protected readonly accounts: AccountLaunches | null;
     protected readonly attachments: AttachmentStore;
     protected readonly env: Record<string, string>;
@@ -224,6 +227,10 @@ export declare class ChatCore {
     renameBookmark(chatId: string, itemId: string, name: string): Promise<ChatBookmark[]>;
     removeBookmark(chatId: string, itemId: string): Promise<ChatBookmark[]>;
     private requireBookmarks;
+    publishVisual(chatId: string, input: VisualInput): Promise<ChatVisual>;
+    listVisuals(chatId: string): Promise<ChatVisual[]>;
+    removeVisual(chatId: string, visualId: string): Promise<ChatVisual[]>;
+    private requireVisuals;
     history(chatId: string, cursor: string, limit?: number): ChatHistoryResult;
     detach(chatId: string, clientId: string): void;
     detachAll(clientId: string): void;

package/dist/chat/chat-core.js

@@ -46,6 +46,7 @@ export class ChatCore {
     providers;
     store;
     bookmarks;
+    visuals;
     accounts;
     attachments;
     env;
@@ -86,6 +87,7 @@ export class ChatCore {
         this.providers = options.providers;
         this.store = options.store ?? null;
         this.bookmarks = options.bookmarks ?? null;
+        this.visuals = options.visuals ?? null;
         this.accounts = options.accounts ?? null;
         this.attachments = options.attachments;
         this.checkpoints = options.checkpoints ?? null;
@@ -103,12 +105,17 @@ export class ChatCore {
         this.spawn = options.spawn ?? null;
         this.codexClient = options.codexClient ?? null;
         this.env = definedEnv(options.env ?? process.env);
-        // Only whoever reads the thread has anything to point a bookmark at, so the list goes where the thread goes.
+        // Only whoever reads the thread has anything to point a bookmark at or to place a visual in, so the lists go where the thread goes.
         this.bookmarks?.listen((chatId, bookmarks) => {
             for (const clientId of this.attached.get(chatId) ?? []) {
                 this.sinks.to(clientId, { event: 'chat.bookmarks', payload: { chatId, bookmarks } });
             }
         });
+        this.visuals?.listen((chatId, visuals) => {
+            for (const clientId of this.attached.get(chatId) ?? []) {
+                this.sinks.to(clientId, { event: 'chat.visuals', payload: { chatId, visuals } });
+            }
+        });
         this.claudeProjectsDir =
             options.subagents?.claudeProjectsDir ?? usageRoots(options.env ?? process.env).find((root) => root.provider === 'claude')?.path ?? '';
         this.subagents = new SubagentReader({
@@ -362,18 +369,22 @@ export class ChatCore {
             : { info: session.info, ...session.thread.history(historyLimit), pending: session.thread.pending(), seq: log.seq };
     }
     /*
-     * `attach` with the chat's bookmarks. They are read before the client joins, so a change written
-     * after the read reaches it as `chat.bookmarks` and never falls between the two. A file that
-     * cannot be read leaves the list out rather than the thread.
+     * `attach` with the chat's bookmarks and visuals. They are read before the client joins, so a
+     * change written after the read reaches it as `chat.bookmarks` or `chat.visuals` and never falls
+     * between the two. A file that cannot be read leaves its list out rather than the thread.
      */
     async attachWithBookmarks(chatId, clientId, historyLimit, since) {
         this.require(chatId);
-        const bookmarks = await this.bookmarks?.read(chatId).catch((e) => {
-            console.error(`The bookmarks of chat ${chatId} could not be read:`, errorText(e));
+        const unreadable = (what) => (e) => {
+            console.error(`The ${what} of chat ${chatId} could not be read:`, errorText(e));
             return undefined;
-        });
+        };
+        const [bookmarks, visuals] = await Promise.all([
+            this.bookmarks?.read(chatId).catch(unreadable('bookmarks')),
+            this.visuals?.list(chatId).catch(unreadable('visuals'))
+        ]);
         const result = this.attach(chatId, clientId, historyLimit, since);
-        return bookmarks === undefined ? result : { ...result, bookmarks };
+        return { ...result, ...(bookmarks === undefined ? {} : { bookmarks }), ...(visuals === undefined ? {} : { visuals }) };
     }
     /* Marks a message of the chat's own thread; a message that already has one keeps it. */
     addBookmark(chatId, itemId, name) {
@@ -397,6 +408,33 @@ export class ChatCore {
         }
         return this.bookmarks;
     }
+    /*
+     * Publishes a page an agent made in a chat, for an app's own agent command. Without a `turnId` it
+     * belongs to the turn that is running, if one is. The chat may be one nobody loaded.
+     */
+    async publishVisual(chatId, input) {
+        const visuals = this.requireVisuals();
+        await this.loaded(chatId);
+        if (!(await this.hasStored(chatId))) {
+            throw new ChatError('chat-not-found', `No chat ${chatId}`);
+        }
+        const turnId = input.turnId ?? this.chats.get(chatId)?.info.activeTurnId ?? undefined;
+        return visuals.publish(chatId, turnId === undefined ? input : { ...input, turnId });
+    }
+    /* The visuals of a chat in the order they were published. */
+    listVisuals(chatId) {
+        return this.requireVisuals().list(chatId);
+    }
+    removeVisual(chatId, visualId) {
+        this.require(chatId);
+        return this.requireVisuals().remove(chatId, visualId);
+    }
+    requireVisuals() {
+        if (!this.visuals) {
+            throw new ChatError('chat-unsupported', 'This host keeps no visuals');
+        }
+        return this.visuals;
+    }
     history(chatId, cursor, limit) {
         const session = this.require(chatId);
         this.coalescers.get(chatId)?.flush();
@@ -510,7 +548,7 @@ export class ChatCore {
         const attachments = await Promise.all(uploads.map((upload) => this.attachments.save(chatId, upload)));
         return session.send(text, { ...extras, ...(attachments.length > 0 ? { attachments } : {}) });
     }
-    /* The file behind an attachment id: what this chat's thread or queue says it is. */
+    /* The file behind an attachment id: what this chat's thread or queue says it is, or a visual's page. */
     attachment(chatId, id) {
         const session = this.chats.get(chatId);
         if (!session) {
@@ -528,7 +566,7 @@ export class ChatCore {
                 return found;
             }
         }
-        return null;
+        return this.visuals?.attachment(chatId, id) ?? null;
     }
     unqueue(chatId, messageId) {
         const message = this.require(chatId).unqueue(messageId);
@@ -554,7 +592,7 @@ export class ChatCore {
         }
         session.compact();
     }
-    /* Empties the thread and drops the CLI's session and the chat's bookmarks; `force` stops a turn that is in the way. */
+    /* Empties the thread and drops the CLI's session and the chat's bookmarks and visuals; `force` stops a turn that is in the way. */
     async clear(chatId, force = false) {
         const session = this.require(chatId);
         if (session.busy && !force) {
@@ -567,7 +605,13 @@ export class ChatCore {
         // A debounced write still waiting holds the old thread and must not land after the empty one.
         this.cancelWaiting(chatId);
         // Folded right away: every line before the reset describes a thread that is gone.
-        await Promise.all([this.persistNow(chatId, true), this.attachments.removeAll(chatId), this.bookmarks?.removeChat(chatId), cleared]);
+        await Promise.all([
+            this.persistNow(chatId, true),
+            this.attachments.removeAll(chatId),
+            this.bookmarks?.removeChat(chatId),
+            this.visuals?.removeChat(chatId),
+            cleared
+        ]);
     }
     /* Stops the running turn; with `subagents` also marks the CLI's own subagents stopped, which that turn no longer waits on. */
     cancel(chatId, subagents = false) {
@@ -596,7 +640,7 @@ export class ChatCore {
             throw new ChatError('request-not-found', `No question to dismiss under ${itemId}`);
         }
     }
-    /* Removes a chat: its CLI, its record, its log, its attachments and its bookmarks. */
+    /* Removes a chat: its CLI, its record, its log, its attachments, its bookmarks and its visuals. */
     async kill(chatId) {
         await this.loaded(chatId);
         const session = this.require(chatId);
@@ -619,7 +663,13 @@ export class ChatCore {
         const snapshot = session.thread.snapshot();
         this.forgotten(chatId);
         await writing;
-        await Promise.all([this.store?.delete(chatId), this.attachments.removeAll(chatId), this.bookmarks?.removeChat(chatId), this.removed(chatId, snapshot)]);
+        await Promise.all([
+            this.store?.delete(chatId),
+            this.attachments.removeAll(chatId),
+            this.bookmarks?.removeChat(chatId),
+            this.visuals?.removeChat(chatId),
+            this.removed(chatId, snapshot)
+        ]);
     }
     /*
      * Ends the CLI of a chat and keeps its thread. A chat nobody loaded has no CLI to end, and a host

package/dist/chat/chat-store.js

@@ -8,6 +8,7 @@ import { isBookmarkFileName } from './bookmark-store.js';
 import { migrateInlineAttachments } from './attachment-store.js';
 import { parseLog } from './chat-log.js';
 import { ChatThread } from './thread.js';
+import { isVisualFileName } from './visual-store.js';
 import { recordFileName } from '../record-directory.js';
 // zod strips what it does not know inside the info and the items, so a file written by an older build
 // (with `interactionMode`, say) still parses and loses only the dropped field. A record without `seq`
@@ -62,8 +63,8 @@ export class ChatStore {
             throw e;
         }
         const ids = names
-            // A chat's bookmarks, and whatever a host keeps per chat, sit beside its record under names that also end in .json.
-            .filter((name) => (name.endsWith('.json') && !isBookmarkFileName(name) && !this.isSidecar(name)) || name.endsWith('.log'))
+            // A chat's bookmarks and visuals, and whatever a host keeps per chat, sit beside its record under names that also end in .json.
+            .filter((name) => (name.endsWith('.json') && !isBookmarkFileName(name) && !isVisualFileName(name) && !this.isSidecar(name)) || name.endsWith('.log'))
             .map((name) => decodeURIComponent(name.replace(/\.(json|log)$/, '')));
         return [...new Set(ids)];
     }

package/dist/chat/errors.d.ts

@@ -1,4 +1,4 @@
 import { CodedError } from '../coded-error.ts';
-export type ChatErrorCode = 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'task-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks';
+export type ChatErrorCode = 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'task-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks' | 'visual-invalid' | 'visual-too-large';
 export declare class ChatError<TCode extends string = ChatErrorCode> extends CodedError<TCode> {
 }

package/dist/chat/visual-store.d.ts

@@ -0,0 +1,35 @@
+import { type ChatAttachment, type ChatVisual } from '@adecore/agent-contracts';
+import type { AttachmentStore } from './attachment-store.ts';
+export declare function visualFileName(chatId: string): string;
+export declare function isVisualFileName(name: string): boolean;
+export interface VisualInput {
+    title: string;
+    html: string;
+    maxHeight?: number;
+    heights?: ReadonlyArray<readonly [number, number]>;
+    turnId?: string;
+}
+export interface VisualStoreOptions {
+    now?: () => number;
+}
+export type VisualListener = (chatId: string, visuals: ChatVisual[]) => void;
+export declare class VisualStore {
+    readonly dir: string;
+    private readonly attachments;
+    private readonly now;
+    private readonly writes;
+    private readonly listeners;
+    private readonly known;
+    constructor(home: string, attachments: AttachmentStore, options?: VisualStoreOptions);
+    listen(listener: VisualListener): () => void;
+    list(chatId: string): Promise<ChatVisual[]>;
+    publish(chatId: string, input: VisualInput): Promise<ChatVisual>;
+    remove(chatId: string, visualId: string): Promise<ChatVisual[]>;
+    removeChat(chatId: string): Promise<void>;
+    copyChat(fromChatId: string, toChatId: string, keep?: (visual: ChatVisual) => boolean): Promise<ChatVisual[]>;
+    attachment(chatId: string, visualId: string): ChatAttachment | null;
+    pagePath(chatId: string, visualId: string): string;
+    private tell;
+    private readFile;
+    private writeFile;
+}

package/dist/chat/visual-store.js

@@ -0,0 +1,230 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ChatVisualsSchema, injectVisualBootstrap, VISUAL_LIMITS } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { isNotFound, writeAtomic } from '../fs.js';
+import { KeyedSerializer } from '../serializer.js';
+import { ChatError } from './errors.js';
+const SUFFIX = '.visuals.json';
+const VisualFileSchema = z.object({ version: z.literal(1), visuals: ChatVisualsSchema });
+export function visualFileName(chatId) {
+    return `${encodeURIComponent(chatId)}${SUFFIX}`;
+}
+/* Whether a name in the chats folder is a visuals file, which the chat records beside it must not count as a chat. */
+export function isVisualFileName(name) {
+    return name.endsWith(SUFFIX);
+}
+const MIB = 1024 * 1024;
+function mebibytes(bytes) {
+    return `${(bytes / MIB).toFixed(1)} MiB`;
+}
+function refuse(code, message) {
+    throw new ChatError(code, message);
+}
+function isSize(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/* The input as it is kept, or a refusal that tells the agent what to change. */
+function checked(input) {
+    const title = typeof input.title === 'string' ? input.title.trim() : '';
+    if (title === '') {
+        refuse('visual-invalid', 'A visual needs a title; give it a short one that says what the page shows');
+    }
+    if (title.length > VISUAL_LIMITS.title) {
+        refuse('visual-invalid', `The title has ${title.length} characters; keep it to ${VISUAL_LIMITS.title} or fewer`);
+    }
+    if (typeof input.html !== 'string' || input.html.trim() === '') {
+        refuse('visual-invalid', 'The page is empty; pass one self-contained HTML document');
+    }
+    const maxHeight = input.maxHeight ?? VISUAL_LIMITS.maxHeight;
+    if (!isSize(maxHeight) || maxHeight < VISUAL_LIMITS.minHeight || maxHeight > VISUAL_LIMITS.maxHeight) {
+        refuse('visual-invalid', `The maximum height must be from ${VISUAL_LIMITS.minHeight} to ${VISUAL_LIMITS.maxHeight} CSS pixels; leave it out for ${VISUAL_LIMITS.maxHeight}`);
+    }
+    const heights = input.heights ?? [];
+    if (!Array.isArray(heights) ||
+        heights.length > VISUAL_LIMITS.heights ||
+        heights.some((pair) => !Array.isArray(pair) || !isSize(pair[0]) || !isSize(pair[1]) || pair[0] <= 0 || pair[1] < 0)) {
+        refuse('visual-invalid', `Measured heights are at most ${VISUAL_LIMITS.heights} pairs of [width, height] in CSS pixels, with a positive width`);
+    }
+    // One measurement per width, the last one given, ascending as `visualFrameHeight` reads them.
+    const byWidth = new Map(heights.map((pair) => [Math.max(1, Math.round(pair[0])), Math.ceil(pair[1])]));
+    const sorted = [...byWidth].sort((a, b) => a[0] - b[0]);
+    return { title, html: input.html, maxHeight: Math.round(maxHeight), heights: sorted.length === 0 ? undefined : sorted };
+}
+function tooLarge(bytes) {
+    return refuse('visual-too-large', `The page is ${mebibytes(bytes)} and a visual may be at most ${mebibytes(VISUAL_LIMITS.bytes)}; ` +
+        'load libraries from a public CDN URL and refer to large images by their http(s) URL instead of inlining them');
+}
+/*
+ * The visuals of every chat. The list of a chat is one file beside its record under `<home>/chats`;
+ * each page is a file in the chat's attachment folder, `<id>.html`, so whatever serves an attachment
+ * serves a page by its id unchanged. One chain per chat puts a publish and a removal after each other,
+ * and every change is told to the listeners from inside that chain.
+ */
+export class VisualStore {
+    dir;
+    attachments;
+    now;
+    writes = new KeyedSerializer();
+    listeners = new Set();
+    // The lists last read or written, so an attachment lookup, which cannot wait, finds a page.
+    known = new Map();
+    constructor(home, attachments, options = {}) {
+        this.dir = join(home, 'chats');
+        this.attachments = attachments;
+        this.now = options.now ?? Date.now;
+    }
+    listen(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /* The visuals of one chat in the order they were published, after any write still on its way. */
+    list(chatId) {
+        return this.writes.run(chatId, () => this.readFile(chatId));
+    }
+    /* Stores a page with its bootstrap and adds it to the chat at the host's current time. */
+    async publish(chatId, input) {
+        const { title, html, maxHeight, heights } = checked(input);
+        // Before the bootstrap is added, so a page far too large is never copied first.
+        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
+            tooLarge(Buffer.byteLength(html, 'utf8'));
+        }
+        const page = Buffer.from(injectVisualBootstrap(html), 'utf8');
+        if (page.byteLength > VISUAL_LIMITS.bytes) {
+            tooLarge(page.byteLength);
+        }
+        const turnId = typeof input.turnId === 'string' && input.turnId !== '' ? input.turnId : undefined;
+        return this.writes.run(chatId, async () => {
+            const visuals = await this.readFile(chatId);
+            const visual = {
+                id: randomBytes(8).toString('hex'),
+                title,
+                at: this.now(),
+                maxHeight,
+                ...(heights === undefined ? {} : { heights }),
+                size: page.byteLength,
+                ...(turnId === undefined ? {} : { turnId })
+            };
+            await mkdir(this.attachments.folderOf(chatId), { recursive: true, mode: 0o700 });
+            await writeAtomic(this.pagePath(chatId, visual.id), page);
+            const next = [...visuals, visual];
+            try {
+                await this.writeFile(chatId, next);
+            }
+            catch (e) {
+                await rm(this.pagePath(chatId, visual.id), { force: true });
+                throw e;
+            }
+            this.tell(chatId, next);
+            return visual;
+        });
+    }
+    /* Takes a visual and its page away; one that is already gone changes nothing. */
+    remove(chatId, visualId) {
+        return this.writes.run(chatId, async () => {
+            const visuals = await this.readFile(chatId);
+            if (!visuals.some((visual) => visual.id === visualId)) {
+                return visuals;
+            }
+            const next = visuals.filter((visual) => visual.id !== visualId);
+            await this.writeFile(chatId, next);
+            await rm(this.pagePath(chatId, visualId), { force: true });
+            this.tell(chatId, next);
+            return next;
+        });
+    }
+    /* The visuals go with the chat or with a clear of it. A list that no longer parses goes too, since nothing could show it again. */
+    removeChat(chatId) {
+        return this.writes.run(chatId, async () => {
+            const visuals = await this.readFile(chatId).catch(() => null);
+            await rm(join(this.dir, visualFileName(chatId)), { force: true });
+            await Promise.all((visuals ?? []).map((visual) => rm(this.pagePath(chatId, visual.id), { force: true })));
+            this.known.delete(chatId);
+            if (visuals === null || visuals.length > 0) {
+                this.tell(chatId, []);
+            }
+        });
+    }
+    /*
+     * Gives a fork the visuals `keep` picks, every one without it, each with a page of its own, so
+     * removing either chat leaves the other's pages where they are. A page that is gone is left out.
+     */
+    async copyChat(fromChatId, toChatId, keep = () => true) {
+        const kept = (await this.list(fromChatId)).filter(keep);
+        if (kept.length === 0) {
+            return this.list(toChatId);
+        }
+        return this.writes.run(toChatId, async () => {
+            const copied = [];
+            await mkdir(this.attachments.folderOf(toChatId), { recursive: true, mode: 0o700 });
+            for (const visual of kept) {
+                const page = await readFile(this.pagePath(fromChatId, visual.id)).catch((e) => {
+                    if (isNotFound(e)) {
+                        return null;
+                    }
+                    throw e;
+                });
+                if (page !== null) {
+                    await writeAtomic(this.pagePath(toChatId, visual.id), page);
+                    copied.push(visual);
+                }
+            }
+            const existing = await this.readFile(toChatId);
+            const ids = new Set(existing.map((visual) => visual.id));
+            const next = [...existing, ...copied.filter((visual) => !ids.has(visual.id))];
+            await this.writeFile(toChatId, next);
+            this.tell(toChatId, next);
+            return next;
+        });
+    }
+    /* A page as an attachment of its chat, from the lists this store has seen; null for one it does not know. */
+    attachment(chatId, visualId) {
+        const visual = this.known.get(chatId)?.find((candidate) => candidate.id === visualId);
+        if (!visual) {
+            return null;
+        }
+        return { id: visual.id, name: `${visual.title}.html`, mime: 'text/html', size: visual.size, path: this.pagePath(chatId, visual.id) };
+    }
+    pagePath(chatId, visualId) {
+        return join(this.attachments.folderOf(chatId), `${visualId}.html`);
+    }
+    tell(chatId, visuals) {
+        for (const listener of this.listeners) {
+            listener(chatId, visuals);
+        }
+    }
+    async readFile(chatId) {
+        let raw;
+        try {
+            raw = await readFile(join(this.dir, visualFileName(chatId)), 'utf8');
+        }
+        catch (e) {
+            if (isNotFound(e)) {
+                this.known.delete(chatId);
+                return [];
+            }
+            throw e;
+        }
+        // A file that does not parse is refused rather than read as empty, which the next write would make true.
+        const parsed = VisualFileSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            throw new Error(`The visuals file of chat ${chatId} is not valid: ${parsed.error.issues[0]?.message ?? 'unknown problem'}`);
+        }
+        this.known.set(chatId, parsed.data.visuals);
+        return parsed.data.visuals;
+    }
+    async writeFile(chatId, visuals) {
+        const path = join(this.dir, visualFileName(chatId));
+        if (visuals.length === 0) {
+            await rm(path, { force: true });
+            this.known.delete(chatId);
+            return;
+        }
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await writeAtomic(path, JSON.stringify({ version: 1, visuals }));
+        this.known.set(chatId, [...visuals]);
+    }
+}

package/dist/host/handlers.js

@@ -70,6 +70,7 @@ export function chatHandlers(chats, providers) {
         'chat.addBookmark': async (payload) => ({ bookmarks: await chats.addBookmark(payload.chatId, payload.itemId, payload.name) }),
         'chat.renameBookmark': async (payload) => ({ bookmarks: await chats.renameBookmark(payload.chatId, payload.itemId, payload.name) }),
         'chat.removeBookmark': async (payload) => ({ bookmarks: await chats.removeBookmark(payload.chatId, payload.itemId) }),
+        'chat.removeVisual': async (payload) => ({ visuals: await chats.removeVisual(payload.chatId, payload.visualId) }),
         'chat.kill': async (payload) => {
             await chats.kill(payload.chatId);
             return {};

package/dist/host/wiring.js

@@ -3,6 +3,7 @@ import { BookmarkStore } from '../chat/bookmark-store.js';
 import { ChatCore } from '../chat/chat-core.js';
 import { ChatStore } from '../chat/chat-store.js';
 import { suggestChatTitle } from '../chat/chat-title.js';
+import { VisualStore } from '../chat/visual-store.js';
 import { ClaudeTitleReader } from '../chat/claude-title.js';
 import { DEFAULT_CODEX_CLIENT } from '../chat/codex-transport.js';
 import { definedEnv } from '../providers/accounts/launch.js';
@@ -58,6 +59,7 @@ export function wireAgents(options) {
         store: new ChatStore(options.dataDir, { attachments }),
         attachments,
         bookmarks: new BookmarkStore(options.dataDir),
+        visuals: new VisualStore(options.dataDir, attachments),
         env,
         ...(options.systemNote === undefined ? {} : { instructions: options.systemNote }),
         ...(options.command ? { command: options.command } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.17.0-beta.2",
+  "version": "0.18.0",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -20,7 +20,7 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.17.0-beta.2",
+    "@adecore/agent-contracts": "0.18.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/chat/attachment-store.ts

@@ -50,7 +50,7 @@ export class AttachmentStore {
         const bytes = Buffer.from(upload.data, 'base64');
         const mime = attachmentImageMime(upload) ?? upload.mime;
         const id = randomBytes(8).toString('hex');
-        const folder = this.folder(chatId);
+        const folder = this.folderOf(chatId);
         await mkdir(folder, { recursive: true, mode: 0o700 });
         const path = join(folder, `${id}.${extensionFor(upload.name, mime)}`);
         await writeFile(path, bytes, { mode: 0o600 });
@@ -59,10 +59,11 @@ export class AttachmentStore {
 
     /* Everything a chat attached; used when the chat itself is deleted. */
     async removeAll(chatId: string): Promise<void> {
-        await rm(this.folder(chatId), { recursive: true, force: true });
+        await rm(this.folderOf(chatId), { recursive: true, force: true });
     }
 
-    private folder(chatId: string): string {
+    /* Where the files of one chat are; a store that keeps more of a chat's files beside them writes them here. */
+    folderOf(chatId: string): string {
         return join(this.dir, encodeURIComponent(chatId));
     }
 }

package/src/chat/chat-core.ts

@@ -19,6 +19,7 @@ import {
     type ChatSubagentPayload,
     type ChatSubagentResult,
     type ChatTurnItem,
+    type ChatVisual,
     type ModelSelection,
     type RuntimeMode
 } from '@adecore/agent-contracts';
@@ -54,6 +55,7 @@ import { DeltaCoalescer } from './delta-coalescer.ts';
 import { ChatError } from './errors.ts';
 import { commandLabel, isBackgroundWork, runsInBackground, type BackgroundWork } from './background-work.ts';
 import { SubagentReader, type SubagentReaderOptions } from './subagent-reader.ts';
+import type { VisualInput, VisualStore } from './visual-store.ts';
 
 /* A turn that was running when the host went down, and the attempt that would take it up again. */
 export interface InterruptedRun {
@@ -115,6 +117,8 @@ export interface ChatCoreOptions {
     // Where the files people attach are written.
     attachments: AttachmentStore;
     bookmarks?: BookmarkStore;
+    // Pages agents publish in a chat; their files go in the same attachment folders.
+    visuals?: VisualStore;
     // What a running turn says about the plan its CLI runs on; the usage monitor takes it from here.
     onLimits?: (update: LimitsUpdate) => void;
     // Where Claude Code's own name for a session is read, in the projects folder of the chat's account; the other CLIs write none down.
@@ -151,6 +155,7 @@ export class ChatCore {
     protected readonly providers: ProviderRegistry;
     protected readonly store: ChatStore | null;
     protected readonly bookmarks: BookmarkStore | null;
+    protected readonly visuals: VisualStore | null;
     protected readonly accounts: AccountLaunches | null;
     protected readonly attachments: AttachmentStore;
     protected readonly env: Record<string, string>;
@@ -192,6 +197,7 @@ export class ChatCore {
         this.providers = options.providers;
         this.store = options.store ?? null;
         this.bookmarks = options.bookmarks ?? null;
+        this.visuals = options.visuals ?? null;
         this.accounts = options.accounts ?? null;
         this.attachments = options.attachments;
         this.checkpoints = options.checkpoints ?? null;
@@ -209,12 +215,17 @@ export class ChatCore {
         this.spawn = options.spawn ?? null;
         this.codexClient = options.codexClient ?? null;
         this.env = definedEnv(options.env ?? process.env);
-        // Only whoever reads the thread has anything to point a bookmark at, so the list goes where the thread goes.
+        // Only whoever reads the thread has anything to point a bookmark at or to place a visual in, so the lists go where the thread goes.
         this.bookmarks?.listen((chatId, bookmarks) => {
             for (const clientId of this.attached.get(chatId) ?? []) {
                 this.sinks.to(clientId, { event: 'chat.bookmarks', payload: { chatId, bookmarks } });
             }
         });
+        this.visuals?.listen((chatId, visuals) => {
+            for (const clientId of this.attached.get(chatId) ?? []) {
+                this.sinks.to(clientId, { event: 'chat.visuals', payload: { chatId, visuals } });
+            }
+        });
         this.claudeProjectsDir =
             options.subagents?.claudeProjectsDir ?? usageRoots(options.env ?? process.env).find((root) => root.provider === 'claude')?.path ?? '';
         this.subagents = new SubagentReader({
@@ -492,18 +503,22 @@ export class ChatCore {
     }
 
     /*
-     * `attach` with the chat's bookmarks. They are read before the client joins, so a change written
-     * after the read reaches it as `chat.bookmarks` and never falls between the two. A file that
-     * cannot be read leaves the list out rather than the thread.
+     * `attach` with the chat's bookmarks and visuals. They are read before the client joins, so a
+     * change written after the read reaches it as `chat.bookmarks` or `chat.visuals` and never falls
+     * between the two. A file that cannot be read leaves its list out rather than the thread.
      */
     async attachWithBookmarks(chatId: string, clientId: string, historyLimit?: number, since?: number): Promise<ChatAttachResult> {
         this.require(chatId);
-        const bookmarks = await this.bookmarks?.read(chatId).catch((e: unknown) => {
-            console.error(`The bookmarks of chat ${chatId} could not be read:`, errorText(e));
+        const unreadable = (what: string) => (e: unknown) => {
+            console.error(`The ${what} of chat ${chatId} could not be read:`, errorText(e));
             return undefined;
-        });
+        };
+        const [bookmarks, visuals] = await Promise.all([
+            this.bookmarks?.read(chatId).catch(unreadable('bookmarks')),
+            this.visuals?.list(chatId).catch(unreadable('visuals'))
+        ]);
         const result = this.attach(chatId, clientId, historyLimit, since);
-        return bookmarks === undefined ? result : { ...result, bookmarks };
+        return { ...result, ...(bookmarks === undefined ? {} : { bookmarks }), ...(visuals === undefined ? {} : { visuals }) };
     }
 
     /* Marks a message of the chat's own thread; a message that already has one keeps it. */
@@ -532,6 +547,37 @@ export class ChatCore {
         return this.bookmarks;
     }
 
+    /*
+     * Publishes a page an agent made in a chat, for an app's own agent command. Without a `turnId` it
+     * belongs to the turn that is running, if one is. The chat may be one nobody loaded.
+     */
+    async publishVisual(chatId: string, input: VisualInput): Promise<ChatVisual> {
+        const visuals = this.requireVisuals();
+        await this.loaded(chatId);
+        if (!(await this.hasStored(chatId))) {
+            throw new ChatError('chat-not-found', `No chat ${chatId}`);
+        }
+        const turnId = input.turnId ?? this.chats.get(chatId)?.info.activeTurnId ?? undefined;
+        return visuals.publish(chatId, turnId === undefined ? input : { ...input, turnId });
+    }
+
+    /* The visuals of a chat in the order they were published. */
+    listVisuals(chatId: string): Promise<ChatVisual[]> {
+        return this.requireVisuals().list(chatId);
+    }
+
+    removeVisual(chatId: string, visualId: string): Promise<ChatVisual[]> {
+        this.require(chatId);
+        return this.requireVisuals().remove(chatId, visualId);
+    }
+
+    private requireVisuals(): VisualStore {
+        if (!this.visuals) {
+            throw new ChatError('chat-unsupported', 'This host keeps no visuals');
+        }
+        return this.visuals;
+    }
+
     history(chatId: string, cursor: string, limit?: number): ChatHistoryResult {
         const session = this.require(chatId);
         this.coalescers.get(chatId)?.flush();
@@ -657,7 +703,7 @@ export class ChatCore {
         return session.send(text, { ...extras, ...(attachments.length > 0 ? { attachments } : {}) });
     }
 
-    /* The file behind an attachment id: what this chat's thread or queue says it is. */
+    /* The file behind an attachment id: what this chat's thread or queue says it is, or a visual's page. */
     attachment(chatId: string, id: string): ChatAttachment | null {
         const session = this.chats.get(chatId);
         if (!session) {
@@ -675,7 +721,7 @@ export class ChatCore {
                 return found;
             }
         }
-        return null;
+        return this.visuals?.attachment(chatId, id) ?? null;
     }
 
     unqueue(chatId: string, messageId: string): ChatQueuedMessage {
@@ -706,7 +752,7 @@ export class ChatCore {
         session.compact();
     }
 
-    /* Empties the thread and drops the CLI's session and the chat's bookmarks; `force` stops a turn that is in the way. */
+    /* Empties the thread and drops the CLI's session and the chat's bookmarks and visuals; `force` stops a turn that is in the way. */
     async clear(chatId: string, force = false): Promise<void> {
         const session = this.require(chatId);
         if (session.busy && !force) {
@@ -719,7 +765,13 @@ export class ChatCore {
         // A debounced write still waiting holds the old thread and must not land after the empty one.
         this.cancelWaiting(chatId);
         // Folded right away: every line before the reset describes a thread that is gone.
-        await Promise.all([this.persistNow(chatId, true), this.attachments.removeAll(chatId), this.bookmarks?.removeChat(chatId), cleared]);
+        await Promise.all([
+            this.persistNow(chatId, true),
+            this.attachments.removeAll(chatId),
+            this.bookmarks?.removeChat(chatId),
+            this.visuals?.removeChat(chatId),
+            cleared
+        ]);
     }
 
     /* Stops the running turn; with `subagents` also marks the CLI's own subagents stopped, which that turn no longer waits on. */
@@ -754,7 +806,7 @@ export class ChatCore {
         }
     }
 
-    /* Removes a chat: its CLI, its record, its log, its attachments and its bookmarks. */
+    /* Removes a chat: its CLI, its record, its log, its attachments, its bookmarks and its visuals. */
     async kill(chatId: string): Promise<void> {
         await this.loaded(chatId);
         const session = this.require(chatId);
@@ -777,7 +829,13 @@ export class ChatCore {
         const snapshot = session.thread.snapshot();
         this.forgotten(chatId);
         await writing;
-        await Promise.all([this.store?.delete(chatId), this.attachments.removeAll(chatId), this.bookmarks?.removeChat(chatId), this.removed(chatId, snapshot)]);
+        await Promise.all([
+            this.store?.delete(chatId),
+            this.attachments.removeAll(chatId),
+            this.bookmarks?.removeChat(chatId),
+            this.visuals?.removeChat(chatId),
+            this.removed(chatId, snapshot)
+        ]);
     }
 
     /*

package/src/chat/chat-store.ts

@@ -8,6 +8,7 @@ import { isBookmarkFileName } from './bookmark-store.ts';
 import { migrateInlineAttachments, type AttachmentStore } from './attachment-store.ts';
 import { parseLog, type ChatLogLine } from './chat-log.ts';
 import { ChatThread } from './thread.ts';
+import { isVisualFileName } from './visual-store.ts';
 import { recordFileName } from '../record-directory.ts';
 
 // zod strips what it does not know inside the info and the items, so a file written by an older build
@@ -98,8 +99,10 @@ export class ChatStore {
             throw e;
         }
         const ids = names
-            // A chat's bookmarks, and whatever a host keeps per chat, sit beside its record under names that also end in .json.
-            .filter((name) => (name.endsWith('.json') && !isBookmarkFileName(name) && !this.isSidecar(name)) || name.endsWith('.log'))
+            // A chat's bookmarks and visuals, and whatever a host keeps per chat, sit beside its record under names that also end in .json.
+            .filter(
+                (name) => (name.endsWith('.json') && !isBookmarkFileName(name) && !isVisualFileName(name) && !this.isSidecar(name)) || name.endsWith('.log')
+            )
             .map((name) => decodeURIComponent(name.replace(/\.(json|log)$/, '')));
         return [...new Set(ids)];
     }

package/src/chat/errors.ts

@@ -19,7 +19,10 @@ export type ChatErrorCode =
     // What a bookmark is refused with.
     | 'item-not-found'
     | 'bookmark-not-found'
-    | 'too-many-bookmarks';
+    | 'too-many-bookmarks'
+    // What publishing a visual is refused with; the message says what to change.
+    | 'visual-invalid'
+    | 'visual-too-large';
 
 /* A host that refuses more than a chat does widens the codes with its own. */
 export class ChatError<TCode extends string = ChatErrorCode> extends CodedError<TCode> {}

package/src/chat/visual-store.ts

@@ -0,0 +1,278 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ChatVisualsSchema, injectVisualBootstrap, VISUAL_LIMITS, type ChatAttachment, type ChatVisual, type VisualHeight } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { isNotFound, writeAtomic } from '../fs.ts';
+import { KeyedSerializer } from '../serializer.ts';
+import type { AttachmentStore } from './attachment-store.ts';
+import { ChatError } from './errors.ts';
+
+const SUFFIX = '.visuals.json';
+
+const VisualFileSchema = z.object({ version: z.literal(1), visuals: ChatVisualsSchema });
+
+export function visualFileName(chatId: string): string {
+    return `${encodeURIComponent(chatId)}${SUFFIX}`;
+}
+
+/* Whether a name in the chats folder is a visuals file, which the chat records beside it must not count as a chat. */
+export function isVisualFileName(name: string): boolean {
+    return name.endsWith(SUFFIX);
+}
+
+/* What an agent hands over: the page as it wrote it, which gets its bootstrap here. */
+export interface VisualInput {
+    title: string;
+    html: string;
+    // CSS pixels; absent, the largest a frame may be.
+    maxHeight?: number;
+    // `[width, height]` in CSS pixels, from a host that measured the page before publishing it.
+    heights?: ReadonlyArray<readonly [number, number]>;
+    turnId?: string;
+}
+
+export interface VisualStoreOptions {
+    // The clock `at` is stamped with, which has to be the one the thread's `createdAt` comes from.
+    now?: () => number;
+}
+
+export type VisualListener = (chatId: string, visuals: ChatVisual[]) => void;
+
+const MIB = 1024 * 1024;
+
+function mebibytes(bytes: number): string {
+    return `${(bytes / MIB).toFixed(1)} MiB`;
+}
+
+function refuse(code: 'visual-invalid' | 'visual-too-large', message: string): never {
+    throw new ChatError(code, message);
+}
+
+function isSize(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+
+/* The input as it is kept, or a refusal that tells the agent what to change. */
+function checked(input: VisualInput): { title: string; html: string; maxHeight: number; heights: VisualHeight[] | undefined } {
+    const title = typeof input.title === 'string' ? input.title.trim() : '';
+    if (title === '') {
+        refuse('visual-invalid', 'A visual needs a title; give it a short one that says what the page shows');
+    }
+    if (title.length > VISUAL_LIMITS.title) {
+        refuse('visual-invalid', `The title has ${title.length} characters; keep it to ${VISUAL_LIMITS.title} or fewer`);
+    }
+    if (typeof input.html !== 'string' || input.html.trim() === '') {
+        refuse('visual-invalid', 'The page is empty; pass one self-contained HTML document');
+    }
+    const maxHeight = input.maxHeight ?? VISUAL_LIMITS.maxHeight;
+    if (!isSize(maxHeight) || maxHeight < VISUAL_LIMITS.minHeight || maxHeight > VISUAL_LIMITS.maxHeight) {
+        refuse(
+            'visual-invalid',
+            `The maximum height must be from ${VISUAL_LIMITS.minHeight} to ${VISUAL_LIMITS.maxHeight} CSS pixels; leave it out for ${VISUAL_LIMITS.maxHeight}`
+        );
+    }
+    const heights = input.heights ?? [];
+    if (
+        !Array.isArray(heights) ||
+        heights.length > VISUAL_LIMITS.heights ||
+        heights.some((pair) => !Array.isArray(pair) || !isSize(pair[0]) || !isSize(pair[1]) || pair[0] <= 0 || pair[1] < 0)
+    ) {
+        refuse('visual-invalid', `Measured heights are at most ${VISUAL_LIMITS.heights} pairs of [width, height] in CSS pixels, with a positive width`);
+    }
+    // One measurement per width, the last one given, ascending as `visualFrameHeight` reads them.
+    const byWidth = new Map(heights.map((pair): [number, number] => [Math.max(1, Math.round(pair[0])), Math.ceil(pair[1])]));
+    const sorted = [...byWidth].sort((a, b) => a[0] - b[0]);
+    return { title, html: input.html, maxHeight: Math.round(maxHeight), heights: sorted.length === 0 ? undefined : sorted };
+}
+
+function tooLarge(bytes: number): never {
+    return refuse(
+        'visual-too-large',
+        `The page is ${mebibytes(bytes)} and a visual may be at most ${mebibytes(VISUAL_LIMITS.bytes)}; ` +
+            'load libraries from a public CDN URL and refer to large images by their http(s) URL instead of inlining them'
+    );
+}
+
+/*
+ * The visuals of every chat. The list of a chat is one file beside its record under `<home>/chats`;
+ * each page is a file in the chat's attachment folder, `<id>.html`, so whatever serves an attachment
+ * serves a page by its id unchanged. One chain per chat puts a publish and a removal after each other,
+ * and every change is told to the listeners from inside that chain.
+ */
+export class VisualStore {
+    readonly dir: string;
+    private readonly attachments: AttachmentStore;
+    private readonly now: () => number;
+    private readonly writes = new KeyedSerializer();
+    private readonly listeners = new Set<VisualListener>();
+    // The lists last read or written, so an attachment lookup, which cannot wait, finds a page.
+    private readonly known = new Map<string, ChatVisual[]>();
+
+    constructor(home: string, attachments: AttachmentStore, options: VisualStoreOptions = {}) {
+        this.dir = join(home, 'chats');
+        this.attachments = attachments;
+        this.now = options.now ?? Date.now;
+    }
+
+    listen(listener: VisualListener): () => void {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+
+    /* The visuals of one chat in the order they were published, after any write still on its way. */
+    list(chatId: string): Promise<ChatVisual[]> {
+        return this.writes.run(chatId, () => this.readFile(chatId));
+    }
+
+    /* Stores a page with its bootstrap and adds it to the chat at the host's current time. */
+    async publish(chatId: string, input: VisualInput): Promise<ChatVisual> {
+        const { title, html, maxHeight, heights } = checked(input);
+        // Before the bootstrap is added, so a page far too large is never copied first.
+        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
+            tooLarge(Buffer.byteLength(html, 'utf8'));
+        }
+        const page = Buffer.from(injectVisualBootstrap(html), 'utf8');
+        if (page.byteLength > VISUAL_LIMITS.bytes) {
+            tooLarge(page.byteLength);
+        }
+        const turnId = typeof input.turnId === 'string' && input.turnId !== '' ? input.turnId : undefined;
+        return this.writes.run(chatId, async () => {
+            const visuals = await this.readFile(chatId);
+            const visual: ChatVisual = {
+                id: randomBytes(8).toString('hex'),
+                title,
+                at: this.now(),
+                maxHeight,
+                ...(heights === undefined ? {} : { heights }),
+                size: page.byteLength,
+                ...(turnId === undefined ? {} : { turnId })
+            };
+            await mkdir(this.attachments.folderOf(chatId), { recursive: true, mode: 0o700 });
+            await writeAtomic(this.pagePath(chatId, visual.id), page);
+            const next = [...visuals, visual];
+            try {
+                await this.writeFile(chatId, next);
+            } catch (e) {
+                await rm(this.pagePath(chatId, visual.id), { force: true });
+                throw e;
+            }
+            this.tell(chatId, next);
+            return visual;
+        });
+    }
+
+    /* Takes a visual and its page away; one that is already gone changes nothing. */
+    remove(chatId: string, visualId: string): Promise<ChatVisual[]> {
+        return this.writes.run(chatId, async () => {
+            const visuals = await this.readFile(chatId);
+            if (!visuals.some((visual) => visual.id === visualId)) {
+                return visuals;
+            }
+            const next = visuals.filter((visual) => visual.id !== visualId);
+            await this.writeFile(chatId, next);
+            await rm(this.pagePath(chatId, visualId), { force: true });
+            this.tell(chatId, next);
+            return next;
+        });
+    }
+
+    /* The visuals go with the chat or with a clear of it. A list that no longer parses goes too, since nothing could show it again. */
+    removeChat(chatId: string): Promise<void> {
+        return this.writes.run(chatId, async () => {
+            const visuals = await this.readFile(chatId).catch(() => null);
+            await rm(join(this.dir, visualFileName(chatId)), { force: true });
+            await Promise.all((visuals ?? []).map((visual) => rm(this.pagePath(chatId, visual.id), { force: true })));
+            this.known.delete(chatId);
+            if (visuals === null || visuals.length > 0) {
+                this.tell(chatId, []);
+            }
+        });
+    }
+
+    /*
+     * Gives a fork the visuals `keep` picks, every one without it, each with a page of its own, so
+     * removing either chat leaves the other's pages where they are. A page that is gone is left out.
+     */
+    async copyChat(fromChatId: string, toChatId: string, keep: (visual: ChatVisual) => boolean = () => true): Promise<ChatVisual[]> {
+        const kept = (await this.list(fromChatId)).filter(keep);
+        if (kept.length === 0) {
+            return this.list(toChatId);
+        }
+        return this.writes.run(toChatId, async () => {
+            const copied: ChatVisual[] = [];
+            await mkdir(this.attachments.folderOf(toChatId), { recursive: true, mode: 0o700 });
+            for (const visual of kept) {
+                const page = await readFile(this.pagePath(fromChatId, visual.id)).catch((e: unknown) => {
+                    if (isNotFound(e)) {
+                        return null;
+                    }
+                    throw e;
+                });
+                if (page !== null) {
+                    await writeAtomic(this.pagePath(toChatId, visual.id), page);
+                    copied.push(visual);
+                }
+            }
+            const existing = await this.readFile(toChatId);
+            const ids = new Set(existing.map((visual) => visual.id));
+            const next = [...existing, ...copied.filter((visual) => !ids.has(visual.id))];
+            await this.writeFile(toChatId, next);
+            this.tell(toChatId, next);
+            return next;
+        });
+    }
+
+    /* A page as an attachment of its chat, from the lists this store has seen; null for one it does not know. */
+    attachment(chatId: string, visualId: string): ChatAttachment | null {
+        const visual = this.known.get(chatId)?.find((candidate) => candidate.id === visualId);
+        if (!visual) {
+            return null;
+        }
+        return { id: visual.id, name: `${visual.title}.html`, mime: 'text/html', size: visual.size, path: this.pagePath(chatId, visual.id) };
+    }
+
+    pagePath(chatId: string, visualId: string): string {
+        return join(this.attachments.folderOf(chatId), `${visualId}.html`);
+    }
+
+    private tell(chatId: string, visuals: ChatVisual[]): void {
+        for (const listener of this.listeners) {
+            listener(chatId, visuals);
+        }
+    }
+
+    private async readFile(chatId: string): Promise<ChatVisual[]> {
+        let raw: string;
+        try {
+            raw = await readFile(join(this.dir, visualFileName(chatId)), 'utf8');
+        } catch (e) {
+            if (isNotFound(e)) {
+                this.known.delete(chatId);
+                return [];
+            }
+            throw e;
+        }
+        // A file that does not parse is refused rather than read as empty, which the next write would make true.
+        const parsed = VisualFileSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            throw new Error(`The visuals file of chat ${chatId} is not valid: ${parsed.error.issues[0]?.message ?? 'unknown problem'}`);
+        }
+        this.known.set(chatId, parsed.data.visuals);
+        return parsed.data.visuals;
+    }
+
+    private async writeFile(chatId: string, visuals: readonly ChatVisual[]): Promise<void> {
+        const path = join(this.dir, visualFileName(chatId));
+        if (visuals.length === 0) {
+            await rm(path, { force: true });
+            this.known.delete(chatId);
+            return;
+        }
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await writeAtomic(path, JSON.stringify({ version: 1, visuals }));
+        this.known.set(chatId, [...visuals]);
+    }
+}

package/src/host/handlers.ts

@@ -99,6 +99,7 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
         'chat.addBookmark': async (payload) => ({ bookmarks: await chats.addBookmark(payload.chatId, payload.itemId, payload.name) }),
         'chat.renameBookmark': async (payload) => ({ bookmarks: await chats.renameBookmark(payload.chatId, payload.itemId, payload.name) }),
         'chat.removeBookmark': async (payload) => ({ bookmarks: await chats.removeBookmark(payload.chatId, payload.itemId) }),
+        'chat.removeVisual': async (payload) => ({ visuals: await chats.removeVisual(payload.chatId, payload.visualId) }),
         'chat.kill': async (payload) => {
             await chats.kill(payload.chatId);
             return {};

package/src/host/wiring.ts

@@ -5,6 +5,7 @@ import { ChatCore, type ChatCoreOptions } from '../chat/chat-core.ts';
 import type { SpawnChatProcess } from '../chat/chat-process.ts';
 import { ChatStore } from '../chat/chat-store.ts';
 import { suggestChatTitle } from '../chat/chat-title.ts';
+import { VisualStore } from '../chat/visual-store.ts';
 import type { ClaudeBackendOptions } from '../chat/claude-backend.ts';
 import { ClaudeTitleReader } from '../chat/claude-title.ts';
 import { DEFAULT_CODEX_CLIENT, type CodexClientInfo } from '../chat/codex-transport.ts';
@@ -24,7 +25,7 @@ import { cliEnvironment, type CliEnvironmentPolicy } from './environment.ts';
 import { accountHandlers, chatHandlers, usageHandlers, type AgentHandlers } from './handlers.ts';
 
 export interface AgentWiringOptions<Core extends ChatCore = ChatCore> {
-    // Where the chats, their attachments and bookmarks, the accounts and the usage index are kept.
+    // Where the chats, their attachments, bookmarks and visuals, the accounts and the usage index are kept.
     dataDir: string;
     // The environment the CLIs start in; absent, this process's own through `cliEnvironment`.
     env?: Record<string, string | undefined>;
@@ -103,6 +104,7 @@ export function wireAgents<Core extends ChatCore = ChatCore>(options: AgentWirin
         store: new ChatStore(options.dataDir, { attachments }),
         attachments,
         bookmarks: new BookmarkStore(options.dataDir),
+        visuals: new VisualStore(options.dataDir, attachments),
         env,
         ...(options.systemNote === undefined ? {} : { instructions: options.systemNote }),
         ...(options.command ? { command: options.command } : {}),