@adecore/agents 0.20.0 → 0.21.0

package/dist/chat/ui-queries.js

@@ -0,0 +1,311 @@
+import { randomUUID } from 'node:crypto';
+import { copyUiValue, UiBudget } from '@adecore/intelligent-ui';
+import { UiLinkResolutionSchema, uiLinkTargets } from '@adecore/intelligent-ui/links';
+import { uiQueryArguments, uiQueryFallback } from '@adecore/intelligent-ui/query';
+import { ChatError } from './errors.js';
+const MAX_QUERY_BYTES = 64 * 1024;
+const MAX_SNAPSHOT_BYTES = 128 * 1024;
+const MAX_QUERIES = 8;
+const REFRESH_MS = 10_000;
+const READ_TIMEOUT_MS = 8_000;
+export class ChatUiQueries {
+    schemas;
+    captures = new Map();
+    freezing = new Set();
+    cache = new Map();
+    reading = new Map();
+    attempts = new Map();
+    active = new Map();
+    totalActive = 0;
+    host;
+    constructor(host) {
+        this.host = host;
+        this.schemas = Object.fromEntries(Object.entries(host.sources).map(([name, source]) => [name, source.args]));
+    }
+    observe(session, item, final) {
+        if (!item.text.includes('@Query') && !/<(?:File|Diff|Commit|Node)\b/.test(item.text) && !item.ui?.some((block) => Object.keys(block.queries).length)) {
+            return;
+        }
+        const capture = this.access(session, item);
+        if (!final || !item.ui?.length) {
+            return;
+        }
+        const key = `${session.id}:${item.id}`;
+        if (this.freezing.has(key)) {
+            return;
+        }
+        this.freezing.add(key);
+        void capture
+            .then(async () => {
+            for (const block of (item.ui ?? []).slice(0, 16)) {
+                const current = session.thread.get(item.id);
+                if (current?.kind !== 'assistant' || current.ui?.find((entry) => entry.id === block.id)?.revision !== block.revision) {
+                    return;
+                }
+                if (current.uiQueries?.blocks[block.id]?.revision === block.revision) {
+                    continue;
+                }
+                const readings = Object.create(null);
+                const values = Object.create(null);
+                for (const name of Object.keys(block.queries).slice(0, MAX_QUERIES)) {
+                    const reading = await this.query(session, {
+                        chatId: session.id,
+                        itemId: item.id,
+                        blockId: block.id,
+                        revision: block.revision,
+                        query: name
+                    });
+                    readings[name] = reading;
+                    if (reading.state === 'fresh') {
+                        values[name] = reading.value;
+                    }
+                }
+                const links = Object.create(null);
+                if (this.host.link) {
+                    const targets = uiLinkTargets(block, {}, values);
+                    const access = await this.access(session, current);
+                    for (const [id, target] of Object.entries(targets).slice(0, 64)) {
+                        try {
+                            links[id] = this.linkReading(await this.host.link(session.info, access.access, target));
+                        }
+                        catch (error) {
+                            links[id] = { state: 'plain', reason: this.reason(error) };
+                        }
+                    }
+                }
+                const latest = session.thread.get(item.id);
+                if (latest?.kind !== 'assistant' || !latest.uiQueries || latest.ui?.find((entry) => entry.id === block.id)?.revision !== block.revision) {
+                    return;
+                }
+                const names = Object.entries(block.queries)
+                    .map(([name, query]) => `${name}: ${query.source}`)
+                    .join(', ');
+                const failures = Object.entries(readings)
+                    .filter(([, reading]) => reading.state !== 'fresh')
+                    .map(([name, reading]) => `${name}: ${reading.reason}`)
+                    .join('\n');
+                const frozen = {
+                    revision: block.revision,
+                    readings,
+                    links,
+                    fallback: `${uiQueryFallback(block, values).slice(0, 8192)}${names ? `\nSources: ${names}` : ''}${failures ? `\n${failures}` : ''}`
+                };
+                const blocks = { ...latest.uiQueries.blocks, [block.id]: frozen };
+                if (Buffer.byteLength(JSON.stringify(blocks)) > MAX_SNAPSHOT_BYTES) {
+                    frozen.readings = Object.fromEntries(Object.keys(readings).map((name) => [
+                        name,
+                        { state: 'failed', readAt: Date.now(), reason: 'The frozen query values are too large.' }
+                    ]));
+                    frozen.links = Object.fromEntries(Object.keys(links).map((id) => [id, { state: 'plain', reason: 'This link must be checked again.' }]));
+                    frozen.fallback = `${block.fallback.slice(0, 2048)}\nSources: ${names}\nThe frozen query values are too large.`;
+                }
+                if (Buffer.byteLength(JSON.stringify(blocks)) > MAX_SNAPSHOT_BYTES) {
+                    delete blocks[block.id];
+                }
+                session.updateUiQueries(item.id, { ...latest.uiQueries, blocks });
+            }
+        })
+            .catch(() => { })
+            .finally(() => this.freezing.delete(key));
+    }
+    access(session, item) {
+        const key = `${session.id}:${item.id}`;
+        const existing = this.captures.get(key);
+        if (existing) {
+            return existing;
+        }
+        if (item.uiQueries?.authorChatId === session.id) {
+            return Promise.resolve(item.uiQueries);
+        }
+        // A pending capture is persisted as denied, so a restart cannot widen the writer's rights.
+        session.updateUiQueries(item.id, { authorChatId: session.id, access: null, blocks: {} });
+        const captured = this.host
+            .capture(session.info)
+            .then((access) => {
+            const captured = copyUiValue(access, new UiBudget());
+            if (Buffer.byteLength(JSON.stringify(captured)) > 32 * 1024) {
+                throw new Error('The UI access snapshot is too large.');
+            }
+            const state = { authorChatId: session.id, access: captured, blocks: {} };
+            session.updateUiQueries(item.id, state);
+            return state;
+        })
+            .catch(() => ({ authorChatId: session.id, access: null, blocks: {} }))
+            .finally(() => this.captures.delete(key));
+        this.captures.set(key, captured);
+        return captured;
+    }
+    storedBlock(session, payload) {
+        const item = session.thread.get(payload.itemId);
+        const block = item?.kind === 'assistant' && !item.streaming && !item.parentToolUseId ? item.ui?.find((entry) => entry.id === payload.blockId) : undefined;
+        if (item?.kind !== 'assistant' || !block?.complete || block.revision !== payload.revision) {
+            throw new ChatError('stale-ui-block', 'This completed UI block is no longer available.');
+        }
+        return { item, block };
+    }
+    stored(session, payload) {
+        const { item, block } = this.storedBlock(session, payload);
+        if (!Object.hasOwn(block.queries, payload.query) || Object.keys(block.queries).length > MAX_QUERIES) {
+            throw new ChatError('refused-query', 'This block does not declare an allowed query.');
+        }
+        const name = block.queries[payload.query].source;
+        if (!Object.hasOwn(this.host.sources, name)) {
+            throw new ChatError('refused-query', 'This query source is not registered.');
+        }
+        return { item, block, source: this.host.sources[name] };
+    }
+    async query(session, payload) {
+        let args;
+        let source;
+        let block;
+        let item;
+        let authorAccess;
+        try {
+            ({ source, block, item } = this.stored(session, payload));
+            args = uiQueryArguments(block, payload.query, payload.values);
+            args = source.args.parse(args);
+            const access = await this.access(session, item);
+            if (access.access === null) {
+                throw new ChatError('refused-query', 'The writer’s original access is unavailable.');
+            }
+            authorAccess = access.access;
+            await source.authorize(session.info, authorAccess, args);
+        }
+        catch (error) {
+            return { state: 'refused', readAt: Date.now(), reason: this.reason(error) };
+        }
+        const key = JSON.stringify([session.id, item.id, block.id, block.revision, payload.query, args]);
+        const cached = [...this.cache.values()].find((entry) => entry.key === key);
+        if (cached && Date.now() - cached.reading.readAt < REFRESH_MS) {
+            return cached.reading;
+        }
+        const pending = this.reading.get(key);
+        if (pending) {
+            return pending;
+        }
+        const identity = JSON.stringify([session.id, item.id, block.id, block.revision, payload.query]);
+        if (Date.now() - (this.attempts.get(identity) ?? 0) < REFRESH_MS) {
+            return { state: 'failed', readAt: Date.now(), reason: 'This query may refresh once every ten seconds.' };
+        }
+        if ((this.active.get(session.id) ?? 0) >= 2 || this.totalActive >= 16) {
+            return { state: 'failed', readAt: Date.now(), reason: 'Too many UI queries are being read.' };
+        }
+        this.attempts.set(identity, Date.now());
+        while (this.attempts.size > 128) {
+            this.attempts.delete(this.attempts.keys().next().value);
+        }
+        this.active.set(session.id, (this.active.get(session.id) ?? 0) + 1);
+        this.totalActive++;
+        const controller = new AbortController();
+        const work = Promise.resolve().then(() => source.read(session.info, args, controller.signal, authorAccess));
+        const timeout = setTimeout(() => controller.abort(), READ_TIMEOUT_MS);
+        timeout.unref?.();
+        const read = Promise.race([
+            work,
+            new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(new Error('The UI query timed out.')), { once: true }))
+        ])
+            .then((result) => {
+            const value = copyUiValue(source.result.parse(result), new UiBudget());
+            if (Buffer.byteLength(JSON.stringify(value)) > MAX_QUERY_BYTES) {
+                throw new Error('The UI query result is too large.');
+            }
+            const reading = { state: 'fresh', value, readId: randomUUID(), readAt: Date.now() };
+            this.cache.set(reading.readId, { key, chatId: session.id, reading });
+            while (this.cache.size > 128) {
+                this.cache.delete(this.cache.keys().next().value);
+            }
+            return reading;
+        })
+            .catch((error) => ({ state: 'failed', readAt: Date.now(), reason: this.reason(error) }))
+            .finally(() => {
+            clearTimeout(timeout);
+            this.reading.delete(key);
+        });
+        // Timed-out sources still occupy their slot until their actual work ends.
+        void work
+            .catch(() => { })
+            .finally(() => {
+            const count = (this.active.get(session.id) ?? 1) - 1;
+            if (count) {
+                this.active.set(session.id, count);
+            }
+            else {
+                this.active.delete(session.id);
+            }
+            this.totalActive--;
+        });
+        this.reading.set(key, read);
+        return read;
+    }
+    async choiceValues(session, payload) {
+        const item = session.thread.get(payload.itemId);
+        const block = item?.kind === 'assistant' ? item.ui?.find((entry) => entry.id === payload.blockId) : undefined;
+        if (!block || item?.kind !== 'assistant' || ('choiceId' in payload && item.uiAnswers?.[block.id]?.revision === payload.revision)) {
+            return {};
+        }
+        const values = Object.create(null);
+        for (const name of Object.keys(payload.reads ?? {})) {
+            const identity = { ...payload, query: name };
+            const { source } = this.stored(session, identity);
+            const args = source.args.parse(uiQueryArguments(block, name, payload.values));
+            const access = await this.access(session, item);
+            await source.authorize(session.info, access.access, args);
+            const key = JSON.stringify([session.id, item.id, block.id, block.revision, name, args]);
+            const readId = payload.reads[name];
+            const cached = this.cache.get(readId);
+            const frozen = item.uiQueries?.blocks[block.id];
+            const snapshot = frozen?.revision === block.revision ? frozen?.readings[name] : undefined;
+            const reading = cached?.key === key
+                ? cached.reading
+                : snapshot?.readId === readId && JSON.stringify(args) === JSON.stringify(source.args.parse(uiQueryArguments(block, name)))
+                    ? snapshot
+                    : undefined;
+            if (!reading || reading.state !== 'fresh') {
+                throw new ChatError('stale-ui-query', 'Refresh this query before sending its choice.');
+            }
+            values[name] = reading.value;
+        }
+        return values;
+    }
+    async link(session, payload) {
+        try {
+            if (!this.host.link) {
+                throw new ChatError('refused-query', 'This host does not provide UI links.');
+            }
+            const { item, block } = this.storedBlock(session, payload);
+            if (!item.uiQueries) {
+                throw new ChatError('refused-query', 'The writer’s original access is unavailable.');
+            }
+            const access = await this.access(session, item);
+            if (access.access === null) {
+                throw new ChatError('refused-query', 'The writer’s original access is unavailable.');
+            }
+            const queries = await this.choiceValues(session, payload);
+            const target = uiLinkTargets(block, payload.values, queries)[payload.nodeId];
+            if (!target) {
+                throw new ChatError('refused-query', 'This visible node is not a supported link.');
+            }
+            return this.linkReading(await this.host.link(session.info, access.access, target));
+        }
+        catch (error) {
+            return { state: 'plain', reason: this.reason(error) };
+        }
+    }
+    forget(chatId) {
+        for (const [id, cached] of this.cache) {
+            if (cached.chatId === chatId) {
+                this.cache.delete(id);
+            }
+        }
+    }
+    linkReading(value) {
+        const reading = UiLinkResolutionSchema.parse(copyUiValue(value, new UiBudget()));
+        if (reading.state === 'chip' && !reading.target) {
+            throw new Error('The host did not resolve a link target.');
+        }
+        return reading;
+    }
+    reason(error) {
+        return (error instanceof Error ? error.message : 'This query could not be read.').slice(0, 240);
+    }
+}

package/dist/host/handlers.js

@@ -31,7 +31,10 @@ export function chatHandlers(chats, providers) {
             chats.detach(payload.chatId, clientId);
             return {};
         },
-        'chat.send': (payload) => chats.send(payload.chatId, payload.text, { mentions: payload.mentions, skills: payload.skills, chats: payload.chats }, payload.attachments),
+        'chat.send': (payload) => chats.send(payload.chatId, payload.text, { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats }, payload.attachments),
+        'chat.uiChoice': (payload) => chats.choose(payload),
+        'ui.link': (payload, clientId) => chats.linkUi(payload, clientId),
+        'ui.query': (payload, clientId) => chats.queryUi(payload, clientId),
         'chat.unqueue': (payload) => ({ message: chats.unqueue(payload.chatId, payload.messageId) }),
         'chat.sendNow': (payload) => {
             chats.sendNow(payload.chatId, payload.messageId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -20,13 +20,14 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.20.0",
+    "@adecore/agent-contracts": "0.21.0",
+    "@adecore/intelligent-ui": "0.21.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",
-    "typescript": "^7.0.2",
-    "@types/node": "^26.6.3"
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2"
   },
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",

package/src/chat/attachment-store.ts

@@ -1,5 +1,5 @@
-import { randomBytes } from 'node:crypto';
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { createHash, randomBytes } from 'node:crypto';
+import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
 import { attachmentImageMime, type ChatAttachment, type ChatAttachmentUpload } from '@adecore/agent-contracts';
 
@@ -57,6 +57,42 @@ export class AttachmentStore {
         return { id, name: upload.name, mime, size: bytes.byteLength, path };
     }
 
+    async saveGenerated(chatId: string, ref: string, upload: ChatAttachmentUpload): Promise<ChatAttachment> {
+        const id = createHash('sha256').update(`codex-image:${ref}`).digest('hex');
+        const bytes = Buffer.from(upload.data, 'base64');
+        const folder = this.folderOf(chatId);
+        await mkdir(folder, { recursive: true, mode: 0o700 });
+        const path = join(folder, `${id}.${extensionFor('', upload.mime)}`);
+        const temporary = join(folder, `.${id}-${randomBytes(8).toString('hex')}.tmp`);
+        try {
+            await writeFile(temporary, bytes, { mode: 0o600, flag: 'wx' });
+            try {
+                // Publish complete bytes without replacing an image another replay has already saved.
+                await link(temporary, path);
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+                    throw error;
+                }
+                const previous = await readFile(path);
+                if (!previous.equals(bytes)) {
+                    throw new Error('The generated image id already belongs to another image');
+                }
+            }
+        } finally {
+            await rm(temporary, { force: true });
+        }
+        return { id, name: upload.name, mime: upload.mime, size: bytes.byteLength, path };
+    }
+
+    async copy(chatId: string, attachment: ChatAttachment): Promise<ChatAttachment> {
+        const bytes = await readFile(attachment.path);
+        const folder = this.folderOf(chatId);
+        await mkdir(folder, { recursive: true, mode: 0o700 });
+        const path = join(folder, `${createHash('sha256').update(attachment.id).digest('hex')}.${extensionFor(attachment.name, attachment.mime)}`);
+        await writeFile(path, bytes, { mode: 0o600 });
+        return { ...attachment, path };
+    }
+
     /* Everything a chat attached; used when the chat itself is deleted. */
     async removeAll(chatId: string): Promise<void> {
         await rm(this.folderOf(chatId), { recursive: true, force: true });

package/src/chat/backend.ts

@@ -1,5 +1,6 @@
 import type {
     ChatAttachment,
+    ChatAttachmentUpload,
     ChatFileChange,
     ChatQuestion,
     ChatSkill,
@@ -42,6 +43,7 @@ export interface BackendLaunch {
     folders?: readonly string[];
     // How the CLI is started; a test runs a fake in the same process, everything else spawns it.
     spawn?: SpawnChatProcess;
+    saveGeneratedImage?(ref: string, upload: ChatAttachmentUpload): Promise<ChatAttachment>;
 }
 
 export interface TurnInput {
@@ -78,9 +80,19 @@ export type BackendEvent =
     // The CLI renamed its thread, for a protocol that says so.
     | { type: 'title'; title: string }
     | { type: 'permissions'; permissionMode: string; effectiveRuntimeMode?: RuntimeMode }
-    | { type: 'text.delta'; ref: string; text: string }
+    | { type: 'text.delta'; ref: string; text: string; phase?: string }
     // `parentRef` is set for text a subagent wrote; it belongs to that agent's row, not to the thread.
-    | { type: 'text.done'; ref: string; text: string; parentRef?: string | null }
+    | { type: 'text.done'; ref: string; text: string; parentRef?: string | null; phase?: string }
+    // Bytes are consumed by the backend before anything reaches the thread or its log.
+    | {
+          type: 'image.generated';
+          ref: string;
+          upload: ChatAttachmentUpload;
+          width?: number;
+          height?: number;
+          revisedPrompt?: string;
+          transparentBackground?: boolean;
+      }
     // What the model thought before it answered; consecutive blocks become one thinking item.
     | { type: 'thinking.delta'; ref: string; text: string }
     | { type: 'thinking.done'; ref: string; text: string }
@@ -175,6 +187,8 @@ export interface ChatBackend {
     // Starts the process if it has not started; resolves once the CLI can take a turn.
     start(): Promise<void>;
     sendTurn(input: TurnInput): void;
+    // Resolves after native acceptance; false means the turn ended before the input could join it.
+    steerTurn?(input: TurnInput): Promise<boolean>;
     compact(): void;
     interrupt(): void;
     // False when nothing waits under that id, so the caller can answer the client with an error.

package/src/chat/chat-core.ts

@@ -2,6 +2,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import {
     ChatAttachmentUploadsSchema,
+    generatedImageAttachment,
     type AgentKind,
     type ChatAttachment,
     type ChatAttachResult,
@@ -15,6 +16,9 @@ import {
     type ChatInfo,
     type ChatItem,
     type ChatQueuedMessage,
+    type ChatUiChoicePayload,
+    type ChatUiQueryPayload,
+    type ChatUiLinkPayload,
     type ChatSkill,
     type ChatSubagentPayload,
     type ChatSubagentResult,
@@ -23,6 +27,7 @@ import {
     type ModelSelection,
     type RuntimeMode
 } from '@adecore/agent-contracts';
+import { ChatUiQueries, type ChatUiHost } from './ui-queries.ts';
 import { ClientSinks } from '../client-sinks.ts';
 import { errorText } from '../error-text.ts';
 import type { AgentEvent, AgentSink } from '../events.ts';
@@ -96,6 +101,7 @@ const DEFAULT_RESUME_WORDS: ResumeWords = {
 };
 
 export interface ChatCoreOptions {
+    intelligentUi?: ChatUiHost;
     providers: ProviderRegistry;
     // Where the threads are kept; without it a chat lives as long as the process.
     store?: ChatStore;
@@ -168,6 +174,7 @@ export class ChatCore {
     /* Where Claude Code keeps the projects of its default account on this machine; empty when it has none. */
     readonly claudeProjectsDir: string;
     readonly composerPreferences = new ComposerPreferences();
+    private readonly uiQueries: ChatUiQueries | null;
     private readonly checkpoints: TurnCheckpoints | null;
     private readonly instructions: string | null;
     private readonly skillIndex: SkillIndex;
@@ -194,6 +201,7 @@ export class ChatCore {
     private readonly limitResume: ChatCoreOptions['limitResume'] | null;
 
     constructor(options: ChatCoreOptions) {
+        this.uiQueries = options.intelligentUi ? new ChatUiQueries(options.intelligentUi) : null;
         this.providers = options.providers;
         this.store = options.store ?? null;
         this.bookmarks = options.bookmarks ?? null;
@@ -390,6 +398,7 @@ export class ChatCore {
         const references = this.referencesFor(payload.chatId);
         const session = new ChatSession({
             info,
+            ...(this.uiQueries ? { ui: { schemas: this.uiQueries.schemas, observe: (item, final) => this.uiQueries!.observe(session, item, final) } } : {}),
             items: stored?.items ?? [],
             preambles: stored?.preambles ?? [],
             provider,
@@ -400,6 +409,7 @@ export class ChatCore {
                 this.accounts?.launched?.(kind, chatAccount);
                 return env;
             },
+            saveGeneratedImage: (ref, upload) => this.attachments.saveGenerated(payload.chatId, ref, upload),
             instructions: () => this.instructionsFor(payload.chatId),
             resumeNote: () => this.resumeNoteFor(payload.chatId),
             folders: () => this.foldersFor(payload.chatId),
@@ -495,11 +505,16 @@ export class ChatCore {
         const log = this.logs.get(chatId)!;
         const events = since === undefined ? null : log.after(since);
         if (events !== null) {
-            return { info: session.info, items: [], events, seq: log.seq };
+            return { info: session.info, items: [], events: [...events, ...session.uiPreviews], seq: log.seq };
         }
-        return historyLimit === undefined
-            ? { ...session.thread.snapshot(), seq: log.seq }
-            : { info: session.info, ...session.thread.history(historyLimit), pending: session.thread.pending(), seq: log.seq };
+        const page = historyLimit === undefined ? session.thread.snapshot() : session.thread.history(historyLimit);
+        return {
+            ...page,
+            info: session.info,
+            items: session.previewItems(page.items),
+            ...(historyLimit === undefined ? {} : { pending: session.previewItems(session.thread.pending()) }),
+            seq: log.seq
+        };
     }
 
     /*
@@ -700,7 +715,32 @@ export class ChatCore {
             throw new ChatError('invalid-attachments', checked.error.issues[0]!.message);
         }
         const attachments = await Promise.all(uploads.map((upload) => this.attachments.save(chatId, upload)));
-        return session.send(text, { ...extras, ...(attachments.length > 0 ? { attachments } : {}) });
+        return session.sendInput(text, { ...extras, ...(attachments.length > 0 ? { attachments } : {}) });
+    }
+
+    async linkUi(payload: ChatUiLinkPayload, clientId: string) {
+        if (!this.attached.get(payload.chatId)?.has(clientId) || !this.uiQueries) {
+            throw new ChatError('refused-query', 'Attach to the chat before resolving its UI links.');
+        }
+        return this.uiQueries.link(this.require(payload.chatId), payload);
+    }
+
+    async queryUi(payload: ChatUiQueryPayload, clientId: string) {
+        if (!this.attached.get(payload.chatId)?.has(clientId)) {
+            throw new ChatError('refused-query', 'Attach to the chat before reading its UI queries.');
+        }
+        if (!this.uiQueries) {
+            throw new ChatError('refused-query', 'This host does not provide UI query sources.');
+        }
+        return this.uiQueries.query(this.require(payload.chatId), payload);
+    }
+
+    async choose(payload: ChatUiChoicePayload): Promise<{ queued: boolean; turnId: string }> {
+        const session = this.require(payload.chatId);
+        const queries = await this.uiQueries?.choiceValues(session, payload);
+        const result = session.choose(payload, queries);
+        await this.persisted(payload.chatId);
+        return result;
     }
 
     /* The file behind an attachment id: what this chat's thread or queue says it is, or a visual's page. */
@@ -710,7 +750,8 @@ export class ChatCore {
             return null;
         }
         for (const item of session.thread.list()) {
-            const found = item.kind === 'user' ? item.attachments?.find((attachment) => attachment.id === id) : undefined;
+            const generated = generatedImageAttachment(item);
+            const found = item.kind === 'user' ? item.attachments?.find((attachment) => attachment.id === id) : generated?.id === id ? generated : null;
             if (found) {
                 return found;
             }
@@ -759,7 +800,7 @@ export class ChatCore {
             throw new ChatError('chat-busy', `Chat ${chatId} is still working on the previous message`);
         }
         await this.clearing(chatId);
-        session.clear(force);
+        const ended = session.clear(force);
         // Before the record is written, so what it takes along from the record is gone from the write as well.
         const cleared = this.cleared(chatId);
         // A debounced write still waiting holds the old thread and must not land after the empty one.
@@ -767,7 +808,7 @@ export class ChatCore {
         // 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),
+            ended.then(() => this.attachments.removeAll(chatId)),
             this.bookmarks?.removeChat(chatId),
             this.visuals?.removeChat(chatId),
             cleared
@@ -812,8 +853,9 @@ export class ChatCore {
         const session = this.require(chatId);
         // A write already out would put the record back after the delete.
         const writing = this.writes.get(chatId);
-        void session.dispose();
+        const ended = session.dispose();
         this.subagents.releaseChat(chatId);
+        this.uiQueries?.forget(chatId);
         this.coalescers.get(chatId)?.dispose();
         this.coalescers.delete(chatId);
         this.logs.get(chatId)?.close();
@@ -829,6 +871,7 @@ export class ChatCore {
         const snapshot = session.thread.snapshot();
         this.forgotten(chatId);
         await writing;
+        await ended;
         await Promise.all([
             this.store?.delete(chatId),
             this.attachments.removeAll(chatId),
@@ -1162,6 +1205,14 @@ export class ChatCore {
     }
 
     private emit(chatId: string, event: ChatEvent): void {
+        if (event.type === 'delta' && event.ui !== undefined) {
+            // Previews follow all pending text but have no log position or observer side effects.
+            this.coalescers.get(chatId)?.flush();
+            for (const clientId of this.attached.get(chatId) ?? []) {
+                this.sinks.to(clientId, { event: 'chat.event', payload: { chatId, event } });
+            }
+            return;
+        }
         this.activity.set(chatId, Date.now());
         let coalescer = this.coalescers.get(chatId);
         if (!coalescer) {