@adecore/agents 0.23.1 → 0.24.0

package/dist/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/dist/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/dist/chat/index.d.ts

@@ -0,0 +1,29 @@
+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/dist/chat/index.js

@@ -0,0 +1,23 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { AttachmentStore } from './attachment-store.js';
+export { runningInBackground } from './background-work.js';
+export { BookmarkStore } from './bookmark-store.js';
+export { ChatCore } from './chat-core.js';
+export { COMPACT_ABOVE_BYTES } from './chat-log.js';
+export { spawnChatProcess, MAX_LINE_LENGTH, LineSplitter, ChatChild } from './chat-process.js';
+export { ChatSession } from './chat-session.js';
+export { ChatStore } from './chat-store.js';
+export { suggestChatTitle } from './chat-title.js';
+export { ClaudeTitleReader } from './claude-title.js';
+export { spokenText, claudeProjectSlug, findClaudeSession } from './claude-transcript.js';
+export { forkThreadOnce } from './codex-thread.js';
+export { ChatError } from './errors.js';
+export { listClaudeSessions, listCodexSessions, nodeSessionFs } from './external-sessions.js';
+export { limitedTurn, limitResumeAt } from './limit-resume.js';
+export { readableAssistantText } from './readable-text.js';
+export { searchThreadItems } from './thread-search.js';
+export { ChatThread } from './thread.js';
+export { ChatUiRefusal } from './ui-queries.js';
+export { visualFileName, VisualStore } from './visual-store.js';
+export { chatOpener } from './wake-chat.js';
+export { SkillIndex } from '../skills.js';

package/dist/chat/projector.d.ts

@@ -1,4 +1,4 @@
-import type { ChatEvent, ChatSubagentUsage } from '@adecore/agent-contracts';
+import type { ChatEvent, ChatItem, ChatSubagentUsage } from '@adecore/agent-contracts';
 import type { BackendEvent } from './backend.ts';
 import type { ChatThread } from './thread.ts';
 export declare function isMainAgentOutput(event: BackendEvent): boolean;
@@ -29,6 +29,7 @@ export declare class ThreadProjector {
     private settleOpenItems;
     private outlivesTurn;
     private restatesCall;
+    itemOf(generation: number, ref: string): ChatItem | undefined;
     private itemId;
     private appendThinking;
     private closeThinking;

package/dist/chat/projector.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@adecore/agent-contracts';
 import { clipText } from '@adecore/agent-contracts/text';
 import { estimateContextBreakdown } from './context-breakdown.js';
 /*
@@ -25,9 +26,6 @@ export function isMainAgentOutput(event) {
 function startsAgentTurn(event) {
     return isMainAgentOutput(event) || ((event.type === 'approval.requested' || event.type === 'question.requested') && event.background !== true);
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function str(value) {
     return typeof value === 'string' ? value : null;
 }
@@ -333,6 +331,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;
@@ -417,6 +422,10 @@ export class ThreadProjector {
     restatesCall(generation, event) {
         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, ref) {
+        return this.thread.get(this.itemId(generation, ref));
+    }
     itemId(generation, ref) {
         return `${generation}:${ref}`;
     }

package/dist/chat/request-summary.js

@@ -1,7 +1,4 @@
-import { CHAT_REQUEST_LIMITS } from '@adecore/agent-contracts';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+import { isRecord, CHAT_REQUEST_LIMITS } from '@adecore/agent-contracts';
 function str(value) {
     return typeof value === 'string' ? value : null;
 }

package/dist/chat/subagent-settlement.js

@@ -1,9 +1,7 @@
 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) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /* The report an agent handed back with `SubagentHandback` before its last message, which then only points at it. */
 function handbackBefore(lines, end) {
     for (let i = end - 1; i >= 0; i--) {

package/dist/chat/thread.d.ts

@@ -5,6 +5,7 @@ export declare class ChatThread {
     private readonly order;
     private historyGeneration;
     private readonly indices;
+    private readonly holds;
     constructor(info: ChatInfo, items?: ChatItem[]);
     get(id: string): ChatItem | undefined;
     list(): ChatItem[];
@@ -16,6 +17,8 @@ export declare class ChatThread {
     upsert(item: ChatItem): ChatEvent;
     appendText(itemId: string, text: string): ChatEvent | null;
     patchInfo(patch: Partial<ChatInfo>): ChatEvent;
+    hold(key: string): boolean;
+    release(key: string): boolean;
     reset(patch: Partial<ChatInfo>): ChatEvent;
     apply(event: ChatEvent): void;
     setStatus(status: AgentStatus): ChatEvent;

package/dist/chat/thread.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { appendToolOutput } from '@adecore/agent-contracts/text';
 import { ChatError } from './errors.js';
 import { requestSummaries } from './request-summary.js';
 /*
@@ -11,6 +12,8 @@ export class ChatThread {
     order = [];
     historyGeneration = randomUUID();
     indices = new Map();
+    // What the host asks a person beside the CLI's own requests, such as a card a verb waits on.
+    holds = new Set();
     constructor(info, items = []) {
         this.info = info;
         for (const item of items) {
@@ -55,15 +58,29 @@ 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) {
-        this.info = { ...this.info, ...patch };
+        const held = patch.status === 'running' && this.holds.size > 0 ? { ...patch, status: 'needs-you' } : patch;
+        this.info = { ...this.info, ...held };
         return { type: 'info', info: this.info };
     }
+    /* False when the key held the chat already. */
+    hold(key) {
+        if (this.holds.has(key)) {
+            return false;
+        }
+        this.holds.add(key);
+        return true;
+    }
+    /* False when the key did not hold the chat. */
+    release(key) {
+        return this.holds.delete(key);
+    }
     /* Empties the thread; the info carries on with the patch on top. */
     reset(patch) {
         this.items.clear();
@@ -105,7 +122,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) {
-        if (this.pending().length > 0) {
+        if (this.pending().length > 0 || this.holds.size > 0) {
             return 'needs-you';
         }
         return activeTurnId === null ? 'idle' : 'running';

package/dist/chat/ui-queries.d.ts

@@ -28,6 +28,7 @@ export declare class ChatUiQueries {
     private readonly freezing;
     private readonly cache;
     private readonly latest;
+    private readonly newest;
     private readonly reading;
     private readonly attempts;
     private readonly active;
@@ -43,6 +44,7 @@ export declare class ChatUiQueries {
     link(session: ChatSession, payload: ChatUiLinkPayload): Promise<ChatUiLinkReading>;
     forget(chatId: string): void;
     private evict;
+    private heldValues;
     private linkReading;
     private failure;
 }

package/dist/chat/ui-queries.js

@@ -35,6 +35,8 @@ export class ChatUiQueries {
     cache = new Map();
     // The read id of the newest reading per cache key, which a remount or a second client is answered with.
     latest = new Map();
+    // The read id of the newest reading per query identity, whose options are the ones a person picks from.
+    newest = new Map();
     reading = new Map();
     attempts = new Map();
     active = new Map();
@@ -187,7 +189,7 @@ export class ChatUiQueries {
         let authorAccess;
         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);
             authorAccess = await this.access(session, item);
             if (authorAccess === null) {
@@ -239,8 +241,9 @@ export class ChatUiQueries {
                 throw new UiQueryError('refused-query', 'result-too-large', '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 });
+            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);
             }
@@ -283,14 +286,29 @@ 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) => 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 = 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));
+            const args = source.args.parse(uiQueryArguments(block, name, payload.values, {}, seen));
             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
                 ? undefined
@@ -343,6 +361,23 @@ 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. */
+    heldValues(session, item, block) {
+        const frozen = item.uiQueries?.blocks[block.id];
+        const values = 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;
     }
     linkReading(value) {
         const reading = UiLinkResolutionSchema.parse(copyUiValue(value, new UiBudget()));

package/dist/chat/ui-replies.d.ts

@@ -0,0 +1,33 @@
+import { type ChatAssistantItem, type ChatEvent, type ChatItem } from '@adecore/agent-contracts';
+import type { UiCompileOptions } from '@adecore/intelligent-ui/compiler';
+import type { OutboxClock } from '../outbox/outbox-worker.ts';
+import type { ChatThread } from './thread.ts';
+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;
+    repair(note: string): void;
+}
+export declare class UiReplies {
+    private readonly options;
+    private readonly streams;
+    private readonly compiled;
+    private readonly scanned;
+    private readonly referencing;
+    private readonly attachments;
+    constructor(options: UiRepliesOptions);
+    previews(): ChatEvent[];
+    previewItems(items: ChatItem[]): ChatItem[];
+    pass(event: ChatEvent): void;
+    clear(): void;
+    private unscannedText;
+    private forgetScan;
+    private latestAttachment;
+    private findAttachment;
+}

package/dist/chat/ui-replies.js

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+import { GeneratedImageInputSchema } from '@adecore/agent-contracts';
+import { uiHasFence, uiMayReferenceHost } from '@adecore/intelligent-ui';
+import { UiStream } from '@adecore/intelligent-ui/stream';
+// 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;
+/*
+ * 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 {
+    options;
+    streams = new Map();
+    compiled = new Map();
+    // How much of a streaming reply's text the fence and host scans already covered, so a delta scans only its tail.
+    scanned = new Map();
+    referencing = new Set();
+    attachments = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /* The preview of every reply still streaming, as deltas, for a client that attached in the middle of one. */
+    previews() {
+        const events = [];
+        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) {
+        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) {
+        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() {
+        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.
+     */
+    unscannedText(item, whole) {
+        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)}`;
+    }
+    forgetScan(item) {
+        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. */
+    latestAttachment(turnId) {
+        if (this.attachments.has(turnId)) {
+            return this.attachments.get(turnId);
+        }
+        const attachment = this.findAttachment(turnId);
+        this.attachments.set(turnId, attachment);
+        return attachment;
+    }
+    findAttachment(turnId) {
+        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/dist/context/index.d.ts

@@ -0,0 +1,2 @@
+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';

package/dist/context/index.js

@@ -0,0 +1,3 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { field, refusalBody, refusalRows, parseRefusalBody } from './refusal.js';
+export { VerbRefusal, DRY_RUN_FLAG, REVISION_FLAG, DRY_RUN_PREVIEW, summaryLines, createVerbRegistry, lengthOf, requiredField, orNote } from './verb.js';