@adecore/agents 0.23.1 → 0.24.1

package/src/chat/fixtures/claude-2.1.296-goal.json

@@ -0,0 +1,136 @@
+{
+    "version": "Claude Code 2.1.296",
+    "capturedAt": "2026-10-13",
+    "source": "Live stream-json of `/goal` with a condition the first answer could not meet: the synthetic command output, the replayed command, the model, one Stop hook check that sent it on, the model again and the one result of the whole run. Stream events, hooks, rate limits and command lifecycle frames are left out; the result keeps only the fields the protocol reads.",
+    "frames": [
+        {
+            "type": "assistant",
+            "message": {
+                "id": "45a12f9c-8626-4da5-9f0f-9879c170fef2",
+                "model": "<synthetic>",
+                "role": "assistant",
+                "type": "message",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "Goal set: the assistant has written the word banana in two separate turns (the first reply alone is not enough)"
+                    }
+                ],
+                "stop_reason": "end_turn"
+            },
+            "parent_tool_use_id": null,
+            "local_command_source": "<local-command-stdout>Goal set: the assistant has written the word banana in two separate turns (the first reply alone is not enough)</local-command-stdout>",
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "uuid": "4753b572-aaf8-43bc-b7bb-eb4030430804",
+            "timestamp": "2026-10-13T09:43:32.152Z",
+            "local_command_run": {
+                "command": "goal",
+                "args": "the assistant has written the word banana in two separate turns (the first reply alone is not enough)"
+            }
+        },
+        {
+            "type": "user",
+            "message": {
+                "role": "user",
+                "content": "<command-name>/goal</command-name>\n            <command-message>goal</command-message>\n            <command-args>the assistant has written the word banana in two separate turns (the first reply alone is not enough)</command-args>"
+            },
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "parent_tool_use_id": null,
+            "uuid": "33333333-3333-4333-8333-333333333333",
+            "timestamp": "2026-10-13T09:43:32.152Z",
+            "isReplay": true
+        },
+        {
+            "type": "assistant",
+            "message": {
+                "id": "msg_011Cfz262XsUozZNFziQzpGU",
+                "model": "claude-haiku-5-5",
+                "role": "assistant",
+                "type": "message",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "Doel gezet: ik schrijf het woord \"banana\" in twee afzonderlijke beurten. Deze beurt is de eerste.\n\nbanana"
+                    }
+                ],
+                "stop_reason": null
+            },
+            "parent_tool_use_id": null,
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "uuid": "a0d5b0da-923a-4773-b445-69e36a20e7bb",
+            "timestamp": "2026-10-13T09:43:36.760Z",
+            "user_message_uuid": "33333333-3333-4333-8333-333333333333",
+            "user_message_uuids": [
+                "33333333-3333-4333-8333-333333333333"
+            ]
+        },
+        {
+            "type": "user",
+            "message": {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "Stop hook feedback:\n[the assistant has written the word banana in two separate turns (the first reply alone is not enough)]: Only one assistant turn containing 'banana' is present in the transcript: the reply that says \"Deze beurt is de eerste.\" followed by \"banana\". The condition requires a second separate turn with 'banana', which has not yet occurred."
+                    }
+                ]
+            },
+            "parent_tool_use_id": null,
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "uuid": "74b573ca-adc9-4c37-a896-bae663eebec6",
+            "timestamp": "2026-10-13T09:43:38.202Z",
+            "isSynthetic": true
+        },
+        {
+            "type": "system",
+            "subtype": "status",
+            "status": "compacting",
+            "compact_output_chars": 0,
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "uuid": "074fe795-5f3a-459b-93a7-3d8f81d280b1"
+        },
+        {
+            "type": "system",
+            "subtype": "status",
+            "status": null,
+            "compact_result": "failed",
+            "compact_error": "too_few_groups",
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "uuid": "3ebbf7de-b187-43fd-b1ec-3c48d4c589d6"
+        },
+        {
+            "type": "assistant",
+            "message": {
+                "id": "msg_011Cfz26UGBv5G733tMq9wHX",
+                "model": "claude-haiku-5-5",
+                "role": "assistant",
+                "type": "message",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "banana"
+                    }
+                ],
+                "stop_reason": null
+            },
+            "parent_tool_use_id": null,
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "uuid": "26b88636-94fa-441a-b072-33e8707fb68b",
+            "timestamp": "2026-10-13T09:43:39.450Z"
+        },
+        {
+            "type": "result",
+            "subtype": "success",
+            "is_error": false,
+            "num_turns": 2,
+            "stop_reason": "end_turn",
+            "session_id": "0d328a18-28f2-48af-af0f-017ad89c26a2",
+            "total_cost_usd": 0.017004325,
+            "result": "banana",
+            "uuid": "64ed92e3-abde-4aeb-b0a8-3bf75fc10a6e",
+            "user_message_uuids": [
+                "33333333-3333-4333-8333-333333333333"
+            ]
+        }
+    ]
+}

package/src/chat/fixtures/claude-projects/-work-demo/5f1c2a9e-0b7d-4c1e-9a53-3e2f8d6b7a10.jsonl

@@ -0,0 +1,2 @@
+{"parentUuid":null,"isSidechain":false,"userType":"external","entrypoint":"sdk-cli","cwd":"/work/demo","sessionId":"5f1c2a9e-0b7d-4c1e-9a53-3e2f8d6b7a10","version":"2.1.273","gitBranch":"main","type":"user","message":{"role":"user","content":"Survey the docs folder and say what is missing."},"uuid":"m-0001","timestamp":"2026-09-16T08:58:19.900Z"}
+{"parentUuid":"m-0001","isSidechain":false,"userType":"external","entrypoint":"sdk-cli","cwd":"/work/demo","sessionId":"5f1c2a9e-0b7d-4c1e-9a53-3e2f8d6b7a10","version":"2.1.273","gitBranch":"main","type":"assistant","message":{"id":"msg_main_1","role":"assistant","content":[{"type":"tool_use","id":"toolu_01ParentAgentCall","name":"Agent","input":{"description":"Survey the docs","prompt":"Survey the docs folder and say what is missing.","subagent_type":"general-purpose"}}],"stop_reason":"tool_use"},"uuid":"m-0002","timestamp":"2026-09-16T08:58:20.500Z"}

package/src/chat/index.ts

@@ -0,0 +1,49 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { AttachmentStore } from './attachment-store.ts';
+export type { BackendLaunch, TurnInput, ApprovalDecision, BackendEvent, BackendHost, ChatBackend } from './backend.ts';
+export { runningInBackground, type BackgroundWork } from './background-work.ts';
+export { BookmarkStore, type BookmarkListener } from './bookmark-store.ts';
+export { type InterruptedRun, type ChatCoreHooks, type ChatCoreOptions, ChatCore } from './chat-core.ts';
+export { COMPACT_ABOVE_BYTES, type ChatLogLine } from './chat-log.ts';
+export {
+    type ChatSpawnOptions,
+    type SpawnChatProcess,
+    spawnChatProcess,
+    MAX_LINE_LENGTH,
+    LineSplitter,
+    ChatChild,
+    type ChatProcess,
+    type ChatChildOptions
+} from './chat-process.ts';
+export {
+    type PromptNotes,
+    type ChatReferences,
+    type ResumeWords,
+    ChatSession,
+    type TurnCheckpoints,
+    type ChatSessionOptions,
+    type LimitResumeHooks,
+    type ChatSendExtras,
+    type ResumeDecision
+} from './chat-session.ts';
+export { type ChatRecordExtras, type ChatRecord, ChatStore, type ChatSeq, type ChatStoreOptions } from './chat-store.ts';
+export { suggestChatTitle, type ChatTitleInput } from './chat-title.ts';
+export type { ClaudeBackendOptions } from './claude-backend.ts';
+export { ClaudeTitleReader } from './claude-title.ts';
+export { spokenText, claudeProjectSlug, findClaudeSession } from './claude-transcript.ts';
+export type { CodexBackendOptions } from './codex-backend.ts';
+export { forkThreadOnce, type ThreadItemsParams, type CodexProcessSpec, type ThreadForkParams } from './codex-thread.ts';
+export type { CodexClientInfo } from './codex-transport.ts';
+export type { ComposerPreference } from './composer-preferences.ts';
+export { type ChatErrorCode, ChatError } from './errors.ts';
+export { type SessionFs, type ExternalSession, listClaudeSessions, listCodexSessions, nodeSessionFs } from './external-sessions.ts';
+export { limitedTurn, limitResumeAt } from './limit-resume.ts';
+export { readableAssistantText } from './readable-text.ts';
+export type { SubagentChat, SubagentReaderOptions } from './subagent-reader.ts';
+export type { SubagentSettlement } from './subagent-settlement.ts';
+export { searchThreadItems, type ThreadHit, type ThreadSearchOptions } from './thread-search.ts';
+export { ChatThread } from './thread.ts';
+export { type ChatUiSource, type ChatUiHost, ChatUiRefusal } from './ui-queries.ts';
+export { visualFileName, VisualStore, type VisualInput, type VisualStoreOptions, type VisualListener } from './visual-store.ts';
+export { type WakeChat, chatOpener, type ChatOpenerDeps } from './wake-chat.ts';
+export { type SkillRootOptions, SkillIndex } from '../skills.ts';

package/src/chat/projector.ts

@@ -8,6 +8,7 @@ import type {
     ChatToolProgress,
     ChatTurnLimit
 } from '@adecore/agent-contracts';
+import { isRecord } from '@adecore/agent-contracts';
 import { clipText } from '@adecore/agent-contracts/text';
 import type { BackendEvent } from './backend.ts';
 import { estimateContextBreakdown } from './context-breakdown.ts';
@@ -40,10 +41,6 @@ function startsAgentTurn(event: BackendEvent): boolean {
     return isMainAgentOutput(event) || ((event.type === 'approval.requested' || event.type === 'question.requested') && event.background !== true);
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function str(value: unknown): string | null {
     return typeof value === 'string' ? value : null;
 }
@@ -381,6 +378,13 @@ export class ThreadProjector {
             case 'model':
                 events.push(this.thread.patchInfo({ model: event.model }));
                 break;
+            case 'goal': {
+                const goal = event.goal ?? undefined;
+                if (JSON.stringify(goal) !== JSON.stringify(info.goal)) {
+                    events.push(this.thread.patchInfo({ goal }));
+                }
+                break;
+            }
             case 'note':
                 events.push(this.note(event.level, event.text));
                 break;
@@ -467,6 +471,11 @@ export class ThreadProjector {
         return event.type === 'tool.started' && this.thread.get(this.itemId(generation, event.ref)) !== undefined;
     }
 
+    /* The item a ref of that generation names, without a walk through the thread. */
+    itemOf(generation: number, ref: string): ChatItem | undefined {
+        return this.thread.get(this.itemId(generation, ref));
+    }
+
     private itemId(generation: number, ref: string): string {
         return `${generation}:${ref}`;
     }

package/src/chat/request-summary.ts

@@ -1,8 +1,11 @@
-import { CHAT_REQUEST_LIMITS, type ChatApprovalItem, type ChatQuestionItem, type ChatRequestApproval, type ChatRequestSummary } from '@adecore/agent-contracts';
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+import {
+    isRecord,
+    CHAT_REQUEST_LIMITS,
+    type ChatApprovalItem,
+    type ChatQuestionItem,
+    type ChatRequestApproval,
+    type ChatRequestSummary
+} from '@adecore/agent-contracts';
 
 function str(value: unknown): string | null {
     return typeof value === 'string' ? value : null;

package/src/chat/subagent-settlement.ts

@@ -1,12 +1,9 @@
 import { open, stat } from 'node:fs/promises';
+import { isRecord } from '@adecore/agent-contracts';
 
 // The end of a transcript is all the question needs; a final line longer than this reads as undecided.
 const TAIL_BYTES = 1024 * 1024;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 /* How a subagent's own transcript says it ended: when, and the text of its last message. */
 export interface SubagentSettlement {
     finishedAt: number | null;

package/src/chat/thread.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
+import { appendToolOutput } from '@adecore/agent-contracts/text';
 import { ChatError } from './errors.ts';
 import { requestSummaries } from './request-summary.ts';
 
@@ -13,6 +14,8 @@ export class ChatThread {
     private readonly order: string[] = [];
     private historyGeneration = randomUUID();
     private readonly indices = new Map<string, number>();
+    // What the host asks a person beside the CLI's own requests, such as a card a verb waits on.
+    private readonly holds = new Set<string>();
 
     constructor(info: ChatInfo, items: ChatItem[] = []) {
         this.info = info;
@@ -63,17 +66,33 @@ export class ChatThread {
         }
         if (item?.kind === 'tool' && item.state === 'running') {
             const progress = item.progress ?? { startedAt: null, description: null, output: null };
-            this.items.set(itemId, { ...item, progress: { ...progress, output: (progress.output ?? '') + text } });
+            this.items.set(itemId, { ...item, progress: { ...progress, output: appendToolOutput(progress.output, text) } });
             return { type: 'delta', itemId, text };
         }
         return null;
     }
 
+    /* While the host holds the chat for a person, a turn that runs reads as waiting on them. */
     patchInfo(patch: Partial<ChatInfo>): ChatEvent {
-        this.info = { ...this.info, ...patch };
+        const held = patch.status === 'running' && this.holds.size > 0 ? { ...patch, status: 'needs-you' as const } : patch;
+        this.info = { ...this.info, ...held };
         return { type: 'info', info: this.info };
     }
 
+    /* False when the key held the chat already. */
+    hold(key: string): boolean {
+        if (this.holds.has(key)) {
+            return false;
+        }
+        this.holds.add(key);
+        return true;
+    }
+
+    /* False when the key did not hold the chat. */
+    release(key: string): boolean {
+        return this.holds.delete(key);
+    }
+
     /* Empties the thread; the info carries on with the patch on top. */
     reset(patch: Partial<ChatInfo>): ChatEvent {
         this.items.clear();
@@ -118,7 +137,7 @@ export class ChatThread {
 
     /* A request can outlive the turn it came in, when work the CLI runs beside its turns asked it. */
     statusFor(activeTurnId: string | null): AgentStatus {
-        if (this.pending().length > 0) {
+        if (this.pending().length > 0 || this.holds.size > 0) {
             return 'needs-you';
         }
         return activeTurnId === null ? 'idle' : 'running';

package/src/chat/ui-queries.ts

@@ -31,6 +31,8 @@ export interface ChatUiHost {
 
 interface CachedReading {
     key: string;
+    // The key without the arguments: one query of one block, whatever it was read with.
+    identity: string;
     chatId: string;
     reading: ChatUiQueryReading;
 }
@@ -71,6 +73,8 @@ export class ChatUiQueries {
     private readonly cache = new Map<string, CachedReading>();
     // The read id of the newest reading per cache key, which a remount or a second client is answered with.
     private readonly latest = new Map<string, string>();
+    // The read id of the newest reading per query identity, whose options are the ones a person picks from.
+    private readonly newest = new Map<string, string>();
     private readonly reading = new Map<string, Promise<ChatUiQueryReading>>();
     private readonly attempts = new Map<string, number>();
     private readonly active = new Map<string, number>();
@@ -237,7 +241,7 @@ export class ChatUiQueries {
         let authorAccess: unknown;
         try {
             ({ source, block, item } = this.stored(session, payload));
-            args = uiQueryArguments(block, payload.query, payload.values);
+            args = uiQueryArguments(block, payload.query, payload.values, {}, this.heldValues(session, item, block));
             args = source.args.parse(args) as Record<string, UiValue>;
             authorAccess = await this.access(session, item);
             if (authorAccess === null) {
@@ -292,8 +296,9 @@ export class ChatUiQueries {
                     throw new UiQueryError('refused-query', 'result-too-large', 'The UI query result is too large.');
                 }
                 const reading: ChatUiQueryReading = { state: 'fresh', value, readId: randomUUID(), readAt: Date.now() };
-                this.cache.set(reading.readId!, { key, chatId: session.id, reading });
+                this.cache.set(reading.readId!, { key, identity, chatId: session.id, reading });
                 this.latest.set(key, reading.readId!);
+                this.newest.set(identity, reading.readId!);
                 while (this.cache.size > 128) {
                     this.evict(this.cache.keys().next().value!);
                 }
@@ -336,14 +341,31 @@ export class ChatUiQueries {
         if (access === null) {
             throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
         }
+        const frozen = item.uiQueries?.blocks[block.id];
+        const readIdOf = (name: string): string | undefined =>
+            payload.reads !== undefined && Object.hasOwn(payload.reads, name) ? payload.reads[name] : undefined;
+        // What the person saw, by the read ids it names; each one is checked against its arguments below.
+        const seen: Record<string, unknown> = Object.create(null);
+        for (const name of names) {
+            const readId = readIdOf(name);
+            const cached = readId === undefined ? undefined : this.cache.get(readId);
+            const reading =
+                cached?.identity === JSON.stringify([session.id, item.id, block.id, block.revision, name])
+                    ? cached.reading
+                    : frozen?.revision === block.revision
+                      ? frozen?.readings[name]
+                      : undefined;
+            if (readId !== undefined && reading?.readId === readId && reading.state === 'fresh') {
+                seen[name] = reading.value;
+            }
+        }
         for (const name of names) {
             const { source } = this.stored(session, { ...payload, query: name });
-            const args = source.args.parse(uiQueryArguments(block, name, payload.values)) as Record<string, UiValue>;
+            const args = source.args.parse(uiQueryArguments(block, name, payload.values, {}, seen)) as Record<string, UiValue>;
             await source.authorize(session.info, access, args);
-            const readId = payload.reads !== undefined && Object.hasOwn(payload.reads, name) ? payload.reads[name] : undefined;
+            const readId = readIdOf(name);
             const key = JSON.stringify([session.id, item.id, block.id, block.revision, name, args]);
             const cached = readId === undefined ? undefined : this.cache.get(readId);
-            const frozen = item.uiQueries?.blocks[block.id];
             const snapshot = frozen?.revision === block.revision ? frozen?.readings[name] : undefined;
             const reading =
                 readId === undefined
@@ -399,6 +421,25 @@ export class ChatUiQueries {
         if (cached && this.latest.get(cached.key) === readId) {
             this.latest.delete(cached.key);
         }
+        if (cached && this.newest.get(cached.identity) === readId) {
+            this.newest.delete(cached.identity);
+        }
+    }
+
+    /* The newest fresh value of every query of a block, or the frozen one, for checking an input chosen from what they read. */
+    private heldValues(session: ChatSession, item: ChatAssistantItem, block: UiBlock): Record<string, unknown> {
+        const frozen = item.uiQueries?.blocks[block.id];
+        const values: Record<string, unknown> = Object.create(null);
+        for (const name of Object.keys(block.queries)) {
+            const readId = this.newest.get(JSON.stringify([session.id, item.id, block.id, block.revision, name]));
+            const reading =
+                (readId === undefined ? undefined : this.cache.get(readId)?.reading) ??
+                (frozen?.revision === block.revision ? frozen?.readings[name] : undefined);
+            if (reading?.state === 'fresh') {
+                values[name] = reading.value;
+            }
+        }
+        return values;
     }
 
     private linkReading(value: unknown): ChatUiLinkReading {

package/src/chat/ui-replies.ts

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import { GeneratedImageInputSchema, type ChatAssistantItem, type ChatEvent, type ChatItem } from '@adecore/agent-contracts';
+import { uiHasFence, uiMayReferenceHost } from '@adecore/intelligent-ui';
+import type { UiCompileOptions } from '@adecore/intelligent-ui/compiler';
+import { UiStream, type UiStreamPreview } from '@adecore/intelligent-ui/stream';
+import type { OutboxClock } from '../outbox/outbox-worker.ts';
+import type { ChatThread } from './thread.ts';
+
+// Longer than any fence line or the name of a tag a scan looks for, so a match never falls between two deltas.
+const UI_SCAN_OVERLAP = 64;
+
+/* What a host answers about the UI blocks of a reply: the schemas of its query sources, and a look at each reply that may read them. */
+export interface UiReplyHost {
+    schemas: UiCompileOptions['querySchemas'];
+    observe(item: ChatAssistantItem, final: boolean): void;
+}
+
+export interface UiRepliesOptions {
+    thread: ChatThread;
+    fenceLanguage: string;
+    clock: OutboxClock;
+    host?: UiReplyHost;
+    emit(event: ChatEvent): void;
+    // What the agent hears in front of its next prompt about a block that compiled with diagnostics.
+    repair(note: string): void;
+}
+
+/*
+ * The UI blocks in the replies of a chat's main agent: every event of the chat passes through here on
+ * its way out, and a reply with a UI fence in it is compiled as it streams, with a preview per delta
+ * and the finished blocks on the item once it settles.
+ */
+export class UiReplies {
+    private readonly options: UiRepliesOptions;
+    private readonly streams = new Map<string, UiStream>();
+    private readonly compiled = new Map<string, UiStreamPreview>();
+    // How much of a streaming reply's text the fence and host scans already covered, so a delta scans only its tail.
+    private readonly scanned = new Map<string, number>();
+    private readonly referencing = new Set<string>();
+    private readonly attachments = new Map<string | null, string | undefined>();
+
+    constructor(options: UiRepliesOptions) {
+        this.options = options;
+    }
+
+    /* The preview of every reply still streaming, as deltas, for a client that attached in the middle of one. */
+    previews(): ChatEvent[] {
+        const events: ChatEvent[] = [];
+        for (const [itemId, preview] of this.compiled) {
+            const item = this.options.thread.get(itemId);
+            if (item?.kind === 'assistant' && item.streaming && item.text.length === preview.textLength) {
+                events.push({ type: 'delta', itemId, text: '', ui: preview.blocks, textLength: preview.textLength });
+            }
+        }
+        return events;
+    }
+
+    previewItems(items: ChatItem[]): ChatItem[] {
+        return items.map((item) => {
+            const preview = this.compiled.get(item.id);
+            return item.kind === 'assistant' && preview?.textLength === item.text.length ? { ...item, ui: preview.blocks } : item;
+        });
+    }
+
+    /* Hands one event of the chat on, with the blocks of a reply it finished in place of its fences. */
+    pass(event: ChatEvent): void {
+        const { thread, emit } = this.options;
+        if (event.type === 'reset') {
+            this.clear();
+        }
+        if (event.type === 'item' && event.item.kind === 'tool') {
+            this.attachments.delete(event.item.turnId);
+        }
+        const item = event.type === 'item' ? event.item : event.type === 'delta' ? thread.get(event.itemId) : null;
+        if (item?.kind !== 'assistant' || item.parentToolUseId) {
+            emit(event);
+            return;
+        }
+        const tail = this.unscannedText(item, event.type === 'item');
+        if (uiMayReferenceHost(tail)) {
+            this.referencing.add(item.id);
+        }
+        let stream = this.streams.get(item.id);
+        if (!stream && !uiHasFence(tail, this.options.fenceLanguage)) {
+            this.forgetScan(item);
+            emit(event);
+            return;
+        }
+        if (!stream) {
+            stream = new UiStream({
+                querySchemas: this.options.host?.schemas,
+                fenceLanguage: this.options.fenceLanguage,
+                id: item.id,
+                clock: this.options.clock,
+                emit: (preview) => {
+                    this.compiled.set(item.id, preview);
+                    emit({ type: 'delta', itemId: item.id, text: '', ui: preview.blocks, textLength: preview.textLength });
+                }
+            });
+            this.streams.set(item.id, stream);
+        }
+        if (this.referencing.has(item.id)) {
+            this.options.host?.observe(item, false);
+        }
+        this.forgetScan(item);
+        const latestAttachment = this.latestAttachment(item.turnId);
+        if (event.type !== 'item' || item.streaming) {
+            emit(event);
+            stream.update(item.text, latestAttachment);
+            return;
+        }
+        const ui = stream
+            .finish(item.text, latestAttachment)
+            .map((block) => ({ ...block, revision: createHash('sha256').update(JSON.stringify(block)).digest('hex') }));
+        this.streams.delete(item.id);
+        this.compiled.delete(item.id);
+        const diagnostics = [...new Set(ui.flatMap((block) => block.diagnostics.map((diagnostic) => diagnostic.message)))].slice(0, 6);
+        if (diagnostics.length > 0) {
+            this.options.repair(
+                `Your last ${this.options.fenceLanguage} block had these diagnostics: ${diagnostics.join(' ')} Use the catalog's supported props and components.`.slice(
+                    0,
+                    1200
+                )
+            );
+        }
+        const current = thread.get(item.id);
+        const completed = { ...item, ui, ...(current?.kind === 'assistant' && current.uiQueries ? { uiQueries: current.uiQueries } : {}) };
+        emit(thread.upsert(completed));
+        this.options.host?.observe(completed, true);
+    }
+
+    clear(): void {
+        for (const stream of this.streams.values()) {
+            stream.dispose();
+        }
+        this.streams.clear();
+        this.compiled.clear();
+        this.scanned.clear();
+        this.referencing.clear();
+        this.attachments.clear();
+    }
+
+    /*
+     * The text a scan has not covered yet, from the start of the line the last scan ended in, since a fence
+     * is one line; a long line is cut short, behind a character no fence or tag can follow.
+     */
+    private unscannedText(item: ChatAssistantItem, whole: boolean): string {
+        const scanned = whole ? 0 : (this.scanned.get(item.id) ?? 0);
+        this.scanned.set(item.id, item.text.length);
+        if (scanned === 0 || scanned > item.text.length) {
+            return item.text;
+        }
+        const line = item.text.lastIndexOf('\n', scanned - 1) + 1;
+        const from = Math.max(line, scanned - UI_SCAN_OVERLAP);
+        return from === line ? item.text.slice(from) : `\0${item.text.slice(from)}`;
+    }
+
+    private forgetScan(item: ChatAssistantItem): void {
+        if (!item.streaming) {
+            this.scanned.delete(item.id);
+            this.referencing.delete(item.id);
+        }
+    }
+
+    /* Looked up once per turn, and again only after one of its tool calls changed. */
+    private latestAttachment(turnId: string | null): string | undefined {
+        if (this.attachments.has(turnId)) {
+            return this.attachments.get(turnId);
+        }
+        const attachment = this.findAttachment(turnId);
+        this.attachments.set(turnId, attachment);
+        return attachment;
+    }
+
+    private findAttachment(turnId: string | null): string | undefined {
+        for (const item of this.options.thread.list().toReversed()) {
+            if (item.kind !== 'tool' || item.turnId !== turnId || item.name !== 'ImageGeneration' || item.state !== 'done') {
+                continue;
+            }
+            const input = GeneratedImageInputSchema.safeParse(item.input);
+            if (input.success && input.data.attachment?.mime.startsWith('image/')) {
+                return input.data.attachment.id;
+            }
+        }
+        return undefined;
+    }
+}

package/src/context/index.ts

@@ -0,0 +1,26 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { field, refusalBody, refusalRows, type ParsedRefusal, parseRefusalBody } from './refusal.ts';
+export {
+    VerbRefusal,
+    type VerbCallBase,
+    type VerbHelp,
+    type Verb,
+    type Action,
+    type Noun,
+    type ContextVerb,
+    type VerbEntry,
+    DRY_RUN_FLAG,
+    REVISION_FLAG,
+    DRY_RUN_PREVIEW,
+    summaryLines,
+    createVerbRegistry,
+    lengthOf,
+    requiredField,
+    orNote,
+    type ArgsSpec,
+    type VerbSpec,
+    type NounSpec,
+    type HelpTopic,
+    type HelpSpec,
+    type VerbRegistry
+} from './verb.ts';