@adecore/agents 0.21.0 → 0.21.2

package/src/chat/chat-session.ts

@@ -18,7 +18,7 @@ import type {
     RuntimeMode
 } from '@adecore/agent-contracts';
 import { GeneratedImageInputSchema, notResumedNote } from '@adecore/agent-contracts';
-import { resolveUiChoice, UiFailure } from '@adecore/intelligent-ui';
+import { resolveUiChoice, UI_FENCE_LANGUAGE, UiFailure, 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 { ChatProvider } from '../providers/provider.ts';
@@ -30,6 +30,7 @@ import type { ChatTitleInput } from './chat-title.ts';
 import { ChatError } from './errors.ts';
 import { limitedTurn, limitResumeAt, limitResumeWake } from './limit-resume.ts';
 import { isMainAgentOutput, ThreadProjector } from './projector.ts';
+import { readableAssistantText } from './readable-text.ts';
 import type { SubagentSettlement } from './subagent-settlement.ts';
 import { ChatThread } from './thread.ts';
 import { errorText } from '../error-text.ts';
@@ -60,6 +61,8 @@ export interface ChatSessionOptions {
     items?: ChatItem[];
     // Said once, in front of the next real prompt, and kept in the record until then (a fork's note for its agent).
     preambles?: string[];
+    // The access a UI host captured per reply, from the record; never on the wire.
+    uiAccess?: Readonly<Record<string, unknown>>;
     provider: ChatProvider;
     // The executable and leading arguments; a test points this at a fake CLI.
     command: string[];
@@ -76,6 +79,8 @@ export interface ChatSessionOptions {
     references?: ChatReferences;
     // Trees per turn, so a settled turn can show what the working tree holds against its start.
     checkpoints?: TurnCheckpoints;
+    // The info string of the host's UI fences; `UI_FENCE_LANGUAGE` without one.
+    uiFenceLanguage?: string;
     ui?: {
         schemas: UiCompileOptions['querySchemas'];
         observe(item: ChatAssistantItem, final: boolean): void;
@@ -109,6 +114,8 @@ export interface LimitResumeHooks {
 
 // Claude Code names a session about six seconds after its first prompt, and a first turn can run for minutes.
 const TITLE_RECHECK_MS = 10_000;
+// 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;
 
 export interface ChatSendExtras {
     uiChoice?: ChatUiChoiceOrigin;
@@ -193,10 +200,18 @@ export class ChatSession {
     private readonly steering = new Set<string>();
     private readonly uiStreams = new Map<string, UiStream>();
     private readonly uiCompiled = new Map<string, UiStreamPreview>();
+    private readonly capturedUiAccess: Map<string, unknown>;
+    // How much of a streaming reply's text the fence and host scans already covered, so a delta scans only its tail.
+    private readonly uiScanned = new Map<string, number>();
+    private readonly uiReferencing = new Set<string>();
+    private readonly uiAttachments = new Map<string | null, string | undefined>();
+    private readonly uiFenceLanguage: string;
 
     constructor(options: ChatSessionOptions) {
         this.options = options;
+        this.uiFenceLanguage = options.uiFenceLanguage ?? UI_FENCE_LANGUAGE;
         this.pendingPreambles = options.preambles ?? [];
+        this.capturedUiAccess = new Map(Object.entries(options.uiAccess ?? {}));
         this.thread = new ChatThread(options.info, options.items);
         this.projector = new ThreadProjector(this.thread, { providerName: options.provider.name });
     }
@@ -314,6 +329,24 @@ export class ChatSession {
         return { queued: false, turnId };
     }
 
+    /* What a UI host captured for a reply; null where the capture was denied or is still out, undefined where none started. */
+    uiAccess(itemId: string): unknown {
+        return this.capturedUiAccess.get(itemId);
+    }
+
+    setUiAccess(itemId: string, access: unknown): void {
+        if (this.frozen) {
+            return;
+        }
+        this.capturedUiAccess.set(itemId, access);
+        this.options.persistSoon();
+    }
+
+    /* The captured access of the replies still in the thread, for the record. */
+    get uiAccessRecord(): Record<string, unknown> {
+        return Object.fromEntries([...this.capturedUiAccess].filter(([itemId]) => this.thread.get(itemId) !== undefined));
+    }
+
     updateUiQueries(itemId: string, uiQueries: ChatUiQueryState): void {
         const item = this.thread.get(itemId);
         if (this.frozen || item?.kind !== 'assistant' || item.parentToolUseId) {
@@ -1828,7 +1861,7 @@ export class ChatSession {
         this.naming = true;
         const turnId = done[0]!.id;
         const answer = items
-            .map((item) => (item.kind === 'assistant' && item.turnId === turnId ? item.text : ''))
+            .map((item) => (item.kind === 'assistant' && item.turnId === turnId ? readableAssistantText(item) : ''))
             .filter((text) => text !== '')
             .join('\n\n');
         const agentSessionId = this.thread.info.agentSessionId;
@@ -1886,19 +1919,28 @@ export class ChatSession {
             if (event.type === 'reset') {
                 this.clearUi();
             }
+            if (event.type === 'item' && event.item.kind === 'tool') {
+                this.uiAttachments.delete(event.item.turnId);
+            }
             const item = event.type === 'item' ? event.item : event.type === 'delta' ? this.thread.get(event.itemId) : null;
             if (item?.kind !== 'assistant' || item.parentToolUseId) {
                 this.options.emit(event);
                 continue;
             }
+            const tail = this.unscannedUiText(item, event.type === 'item');
+            if (uiMayReferenceHost(tail)) {
+                this.uiReferencing.add(item.id);
+            }
             let stream = this.uiStreams.get(item.id);
-            if (!stream && !item.text.includes('ruimte-ui')) {
+            if (!stream && !uiHasFence(tail, this.uiFenceLanguage)) {
+                this.forgetUiScan(item);
                 this.options.emit(event);
                 continue;
             }
             if (!stream) {
                 stream = new UiStream({
                     querySchemas: this.options.ui?.schemas,
+                    fenceLanguage: this.uiFenceLanguage,
                     id: item.id,
                     clock: this.options.clock ?? systemClock,
                     emit: (preview) => {
@@ -1908,7 +1950,10 @@ export class ChatSession {
                 });
                 this.uiStreams.set(item.id, stream);
             }
-            this.options.ui?.observe(item, false);
+            if (this.uiReferencing.has(item.id)) {
+                this.options.ui?.observe(item, false);
+            }
+            this.forgetUiScan(item);
             const latestAttachment = this.latestUiAttachment(item.turnId);
             if (event.type === 'item' && !item.streaming) {
                 const ui = stream
@@ -1919,7 +1964,7 @@ export class ChatSession {
                 const diagnostics = [...new Set(ui.flatMap((block) => block.diagnostics.map((diagnostic) => diagnostic.message)))].slice(0, 6);
                 if (diagnostics.length > 0) {
                     const repair =
-                        `Your last ruimte-ui block had these diagnostics: ${diagnostics.join(' ')} Use the catalog's supported props and components.`.slice(
+                        `Your last ${this.uiFenceLanguage} block had these diagnostics: ${diagnostics.join(' ')} Use the catalog's supported props and components.`.slice(
                             0,
                             1200
                         );
@@ -1939,7 +1984,39 @@ export class ChatSession {
         }
     }
 
+    /*
+     * 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 unscannedUiText(item: ChatAssistantItem, whole: boolean): string {
+        const scanned = whole ? 0 : (this.uiScanned.get(item.id) ?? 0);
+        this.uiScanned.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 forgetUiScan(item: ChatAssistantItem): void {
+        if (!item.streaming) {
+            this.uiScanned.delete(item.id);
+            this.uiReferencing.delete(item.id);
+        }
+    }
+
+    /* Looked up once per turn, and again only after one of its tool calls changed. */
     private latestUiAttachment(turnId: string | null): string | undefined {
+        if (this.uiAttachments.has(turnId)) {
+            return this.uiAttachments.get(turnId);
+        }
+        const attachment = this.findUiAttachment(turnId);
+        this.uiAttachments.set(turnId, attachment);
+        return attachment;
+    }
+
+    private findUiAttachment(turnId: string | null): string | undefined {
         for (const item of this.thread.list().toReversed()) {
             if (item.kind !== 'tool' || item.turnId !== turnId || item.name !== 'ImageGeneration' || item.state !== 'done') {
                 continue;
@@ -1958,6 +2035,9 @@ export class ChatSession {
         }
         this.uiStreams.clear();
         this.uiCompiled.clear();
+        this.uiScanned.clear();
+        this.uiReferencing.clear();
+        this.uiAttachments.clear();
     }
 
     /* Said on the info as well as by the rows, since a client with the thread closed sees only the info. */

package/src/chat/chat-store.ts

@@ -4,12 +4,12 @@ import { join } from 'node:path';
 import { ChatInfoSchema, ChatItemSchema, type ChatInfo, type ChatItem } from '@adecore/agent-contracts';
 import { z } from 'zod';
 import { isNotFound, writeAtomic, writeAtomicSync } from '../fs.ts';
-import { isBookmarkFileName } from './bookmark-store.ts';
+import { recordFileName } from '../record-directory.ts';
 import { migrateInlineAttachments, type AttachmentStore } from './attachment-store.ts';
+import { isBookmarkFileName } from './bookmark-store.ts';
 import { parseLog, type ChatLogLine } from './chat-log.ts';
 import { ChatThread } from './thread.ts';
 import { isVisualFileName } from './visual-store.ts';
-import { recordFileName } from '../record-directory.ts';
 
 // zod strips what it does not know inside the info and the items, so a file written by an older build
 // (with `interactionMode`, say) still parses and loses only the dropped field. A record without `seq`
@@ -20,15 +20,17 @@ const RecordSchema = z.looseObject({
     seq: z.number().int().nonnegative().optional(),
     resetSeq: z.number().int().nonnegative().optional(),
     // Never on the wire: what goes in front of the next real prompt, once (a fork's note for its agent).
-    preambles: z.array(z.string()).optional()
+    preambles: z.array(z.string()).optional(),
+    // Never on the wire: the access a UI host captured for each reply that reads it, by item id.
+    uiAccess: z.record(z.string(), z.unknown()).optional()
 });
 
-const OWN_KEYS = new Set(['info', 'items', 'seq', 'resetSeq', 'preambles']);
+const OWN_KEYS = new Set(['info', 'items', 'seq', 'resetSeq', 'preambles', 'uiAccess']);
 
 /* What a host keeps in a chat's record beside the thread; it never reaches the wire. */
 export type ChatRecordExtras = Record<string, unknown>;
 
-function extrasOf(record: Record<string, unknown>): ChatRecordExtras {
+function withoutOwnKeys(record: Record<string, unknown>): ChatRecordExtras {
     return Object.fromEntries(Object.entries(record).filter(([key]) => !OWN_KEYS.has(key)));
 }
 
@@ -39,6 +41,7 @@ export interface ChatRecord {
     seq: number;
     resetSeq: number;
     preambles: string[];
+    uiAccess: Record<string, unknown>;
     extras: ChatRecordExtras;
     // The log as it is on disk, for the lines an attach with `since` may still be answered from.
     lines: ChatLogLine[];
@@ -54,12 +57,37 @@ function logName(chatId: string): string {
     return `${encodeURIComponent(chatId)}.log`;
 }
 
-function recordBody(info: ChatInfo, items: ChatItem[], at: ChatSeq, preambles: readonly string[], extras: ChatRecordExtras): string {
-    return JSON.stringify({ info, items, ...at, ...(preambles.length === 0 ? {} : { preambles }), ...withoutOwnKeys(extras) });
+function recordBody(
+    info: ChatInfo,
+    items: ChatItem[],
+    at: ChatSeq,
+    preambles: readonly string[],
+    extras: ChatRecordExtras,
+    uiAccess: Readonly<Record<string, unknown>>
+): string {
+    return JSON.stringify({
+        info,
+        items,
+        ...at,
+        ...(preambles.length === 0 ? {} : { preambles }),
+        ...(Object.keys(uiAccess).length === 0 ? {} : { uiAccess }),
+        ...withoutOwnKeys(extras)
+    });
 }
 
-function withoutOwnKeys(extras: ChatRecordExtras): ChatRecordExtras {
-    return Object.fromEntries(Object.entries(extras).filter(([key]) => !OWN_KEYS.has(key)));
+/* A record from before `uiAccess` kept the access inside each reply's `uiQueries`, which the item schema now drops. */
+function liftUiAccess(record: unknown): unknown {
+    if (typeof record !== 'object' || record === null || 'uiAccess' in record || !Array.isArray((record as { items?: unknown }).items)) {
+        return record;
+    }
+    const uiAccess: Record<string, unknown> = {};
+    for (const item of (record as { items: unknown[] }).items) {
+        const queries = (item as { uiQueries?: unknown } | null)?.uiQueries;
+        if (typeof queries === 'object' && queries !== null && 'access' in queries) {
+            uiAccess[String((item as { id: unknown }).id)] = queries.access;
+        }
+    }
+    return Object.keys(uiAccess).length === 0 ? record : { ...record, uiAccess };
 }
 
 export interface ChatStoreOptions {
@@ -127,9 +155,10 @@ export class ChatStore {
         items: ChatItem[],
         at: ChatSeq = { seq: 0, resetSeq: 0 },
         preambles: readonly string[] = [],
-        extras: ChatRecordExtras = {}
+        extras: ChatRecordExtras = {},
+        uiAccess: Readonly<Record<string, unknown>> = {}
     ): Promise<number> {
-        const body = recordBody(info, items, at, preambles, extras);
+        const body = recordBody(info, items, at, preambles, extras, uiAccess);
         await mkdir(this.dir, { recursive: true, mode: 0o700 });
         await writeAtomic(join(this.dir, recordFileName(chatId)), body);
         return body.length;
@@ -145,10 +174,11 @@ export class ChatStore {
         items: ChatItem[],
         at: ChatSeq = { seq: 0, resetSeq: 0 },
         preambles: readonly string[] = [],
-        extras: ChatRecordExtras = {}
+        extras: ChatRecordExtras = {},
+        uiAccess: Readonly<Record<string, unknown>> = {}
     ): void {
         mkdirSync(this.dir, { recursive: true, mode: 0o700 });
-        writeAtomicSync(join(this.dir, recordFileName(chatId)), recordBody(info, items, at, preambles, extras));
+        writeAtomicSync(join(this.dir, recordFileName(chatId)), recordBody(info, items, at, preambles, extras, uiAccess));
     }
 
     /* Null for a chat with nothing on disk to make it of, and for one whose record does not parse (see `unreadable`). */
@@ -174,7 +204,15 @@ export class ChatStore {
                 resetSeq = line.seq;
             }
         }
-        return { ...thread.snapshot(), seq, resetSeq, preambles: snapshot.preambles ?? [], extras: extrasOf(snapshot), lines };
+        return {
+            ...thread.snapshot(),
+            seq,
+            resetSeq,
+            preambles: snapshot.preambles ?? [],
+            uiAccess: snapshot.uiAccess ?? {},
+            extras: withoutOwnKeys(snapshot),
+            lines
+        };
     }
 
     /*
@@ -204,7 +242,7 @@ export class ChatStore {
                 await writeAtomic(join(this.dir, recordFileName(chatId)), JSON.stringify(migrated));
             }
         }
-        const parsed = RecordSchema.safeParse(record);
+        const parsed = RecordSchema.safeParse(liftUiAccess(record));
         return parsed.success ? parsed.data : UNREADABLE;
     }
 
@@ -260,5 +298,5 @@ function fromLogAlone(lines: ChatLogLine[]): ChatRecord | null {
             resetSeq = line.seq;
         }
     }
-    return { ...thread.snapshot(), seq: 0, resetSeq, preambles: [], extras: {}, lines };
+    return { ...thread.snapshot(), seq: 0, resetSeq, preambles: [], uiAccess: {}, extras: {}, lines };
 }

package/src/chat/chat-title.ts

@@ -1,7 +1,7 @@
 import type { AgentKind } from '@adecore/agent-contracts';
-import { cleanTitle } from '../title-file.ts';
 import type { ProviderRegistry } from '../providers/registry.ts';
 import { runProcess } from '../run-process.ts';
+import { cleanTitle } from '../title-file.ts';
 
 // Enough of a conversation to name it; the rest of a long prompt or answer says nothing a title needs.
 const MAX_PROMPT_CHARS = 2000;
@@ -19,10 +19,7 @@ function cap(text: string, limit: number): string {
     return text.length <= limit ? text : `${text.slice(0, limit)}...`;
 }
 
-/*
- * What the CLI is asked. JSON again, as for a commit message: a model left to write freely opens
- * with a sentence, and that sentence would become the name of the node.
- */
+/* JSON, since a model left to write freely opens with a sentence, and that sentence would become the name. */
 export function buildTitlePrompt(prompt: string, answer: string): string {
     return [
         'Write a short title for the conversation below, as a person would name it in a list of chats.',
@@ -42,9 +39,8 @@ export function buildTitlePrompt(prompt: string, answer: string): string {
 }
 
 /*
- * The title out of what the CLI printed, or null. Strict on purpose, unlike a commit message: a run
- * that holds no `{"title": "..."}` object printed something other than a title, and a derived name
- * is better than a stray line of it.
+ * Strict on purpose: a run that holds no `{"title": "..."}` object printed something other than a
+ * title, and a derived name is better than a stray line of it.
  */
 export function parseTitle(output: string): string | null {
     const start = [...output.matchAll(/\{\s*"title"/g)].at(-1)?.index;

package/src/chat/claude-backend.ts

@@ -1,5 +1,5 @@
-import { errorText } from '../error-text.ts';
 import { randomUUID } from 'node:crypto';
+import { errorText } from '../error-text.ts';
 import { claudeArgs, claudeEnv, promptPrefix } from '../providers/claude.ts';
 import type { ApprovalDecision, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
 import { ChatChild } from './chat-process.ts';
@@ -71,12 +71,10 @@ export class ClaudeBackend implements ChatBackend {
     }
 
     sendTurn(input: TurnInput): void {
-        // The prefix is what the CLI must see first (ultrathink), then the note about the links, then what was typed.
-        const prefix = `${promptPrefix(this.launch.selection)}${input.preamble === null ? '' : `${input.preamble}\n\n`}`;
         const promptId = input.promptId ?? randomUUID();
         this.active = true;
         this.protocol.beginPrompt(promptId);
-        this.write(buildUserMessage({ text: input.text, attachments: input.attachments, prefix, skills: input.skills, promptId }));
+        this.write(this.userMessage(input, promptId));
     }
 
     steerTurn(input: TurnInput): Promise<boolean> {
@@ -88,8 +86,7 @@ export class ClaudeBackend implements ChatBackend {
             this.steers.set(promptId, { resolve, reject });
             this.protocol.beginSteer(promptId);
             try {
-                const prefix = `${promptPrefix(this.launch.selection)}${input.preamble === null ? '' : `${input.preamble}\n\n`}`;
-                this.write(buildUserMessage({ text: input.text, attachments: input.attachments, prefix, skills: input.skills, promptId }));
+                this.write(this.userMessage(input, promptId));
             } catch (error) {
                 this.steers.delete(promptId);
                 reject(error instanceof Error ? error : new Error(errorText(error)));
@@ -147,6 +144,12 @@ export class ClaudeBackend implements ChatBackend {
         return child?.end() ?? Promise.resolve();
     }
 
+    private userMessage(input: TurnInput, promptId: string): Record<string, unknown> {
+        // What the CLI must see first (ultrathink), then the preamble, then what was typed.
+        const prefix = `${promptPrefix(this.launch.selection)}${input.preamble === null ? '' : `${input.preamble}\n\n`}`;
+        return buildUserMessage({ text: input.text, attachments: input.attachments, prefix, skills: input.skills, promptId });
+    }
+
     private async readLines(child: ChatChild): Promise<void> {
         const reader = child.process.stdout.getReader();
         const decoder = new TextDecoder();

package/src/chat/claude-title.ts

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { usageRoots } from '../usage/roots.ts';
 import { cleanTitle, readLines } from '../title-file.ts';
+import { usageRoots } from '../usage/roots.ts';
 
 interface Progress {
     offset: number;

package/src/chat/claude-transcript.ts

@@ -5,8 +5,8 @@ import type { ChatHistoryResult, ChatItem } from '@adecore/agent-contracts';
 import { readLines } from '../title-file.ts';
 import { ClaudeProtocol } from './claude-protocol.ts';
 import { readingThread, settledReading } from './subagent-projection.ts';
-import type { ChatThread } from './thread.ts';
 import type { ThreadProjector } from './projector.ts';
+import type { ChatThread } from './thread.ts';
 
 const CHUNK_BYTES = 4 * 1024 * 1024;
 

package/src/chat/codex-backend.ts

@@ -1,11 +1,11 @@
 import { accessSync, constants } from 'node:fs';
 import { attachmentImageMime, type ChatSkill } from '@adecore/agent-contracts';
+import { errorText } from '../error-text.ts';
 import { codexServiceTier, codexThreadOptions } from '../providers/codex.ts';
 import type { ApprovalDecision, BackendEvent, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
 import { CodexProtocol } from './codex-protocol.ts';
-import { attachmentNote } from './input.ts';
 import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo, type CodexFrame } from './codex-transport.ts';
-import { errorText } from '../error-text.ts';
+import { attachmentNote } from './input.ts';
 
 function textInput(text: string) {
     return [{ type: 'text', text, text_elements: [] }];
@@ -46,18 +46,15 @@ export interface CodexBackendOptions {
  */
 export class CodexBackend implements ChatBackend {
     readonly acknowledgesTurns = true;
-    private promptId: string | null = null;
     private readonly launch: BackendLaunch;
-    private imageWrites: Promise<void> | null = null;
     private readonly host: BackendHost;
     private readonly protocol: CodexProtocol;
     private readonly client: CodexClientInfo;
+    private promptId: string | null = null;
+    private imageWrites: Promise<void> | null = null;
     private transport: CodexTransport | null = null;
     private threadId = '';
-    /*
-     * Codex 0.154 ignores developer instructions on `thread/resume` (measured), so a thread started
-     * before anything was linked would never hear of its links; the first prompt of a resumed process says so instead.
-     */
+    // Codex 0.154 ignores developer instructions on `thread/resume` (measured), so the first prompt of a resumed process carries them.
     private contextPending: string | null = null;
     private imageInputSupported: boolean | null = null;
     /* A turn asked for that Codex has not named yet; `turn/interrupt` needs that name. */

package/src/chat/codex-protocol.ts

@@ -172,7 +172,7 @@ function elicitationInput(meta: Frame): Frame {
     return input;
 }
 
-// Every spent window must reset; one unknown reset keeps resuming a person's choice.
+// The latest reset of every spent window; one without a known reset leaves resuming to a person.
 function spentUntil(windows: readonly UsageWindow[]): number | null {
     const spent = windows.filter((window) => window.used >= 1);
     if (spent.length === 0 || spent.some((window) => window.resetsAt === null)) {

package/src/chat/codex-thread.ts

@@ -1,10 +1,10 @@
 import type { ChatItem } from '@adecore/agent-contracts';
+import { errorText } from '../error-text.ts';
 import type { SpawnChatProcess } from './chat-process.ts';
 import { CodexProtocol } from './codex-protocol.ts';
 import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo } from './codex-transport.ts';
 import { ChatError } from './errors.ts';
 import { readingThread, settledReading } from './subagent-projection.ts';
-import { errorText } from '../error-text.ts';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -116,14 +116,15 @@ async function nthTurnId(transport: CodexTransport, threadId: string, turns: num
     let seen = 0;
     let cursor: string | null = null;
     do {
-        const page = await transport.request('thread/turns/list', { threadId, limit: 100, sortDirection: 'asc', ...(cursor === null ? {} : { cursor }) });
-        const data = isRecord(page) && Array.isArray(page.data) ? page.data.filter(isRecord) : [];
-        for (const turn of data) {
+        const page = parseThreadItemsPage(
+            await transport.request('thread/turns/list', { threadId, limit: 100, sortDirection: 'asc', ...(cursor === null ? {} : { cursor }) })
+        );
+        for (const turn of page.entries) {
             if (++seen === turns) {
                 return typeof turn.id === 'string' ? turn.id : null;
             }
         }
-        cursor = isRecord(page) && typeof page.nextCursor === 'string' && page.nextCursor !== '' ? page.nextCursor : null;
+        cursor = page.nextCursor;
     } while (cursor !== null);
     return null;
 }

package/src/chat/composer-preferences.ts

@@ -15,9 +15,8 @@ interface Held {
 
 /*
  * What each connected client says a new chat starts with, for the chats the host starts with no
- * client mounting them. Held per socket like the approval switch: a machine never remembers a
- * person's pick after that person's client is gone, so with nobody connected a chat gets the
- * host's own defaults.
+ * client mounting them. Held per client only, so with nobody connected a chat gets the host's own
+ * defaults rather than the pick of a person who left.
  */
 export class ComposerPreferences {
     private readonly byClient = new Map<string, Held>();

package/src/chat/limit-resume.ts

@@ -5,13 +5,8 @@ export const LIMIT_RETRY_DELAYS_MS: readonly number[] = [60_000, 5 * 60_000, 15
 
 /* The last turn of a thread, when it stopped on a limit. */
 export function limitedTurn(items: readonly ChatItem[]): (ChatTurnItem & { limit: ChatTurnLimit }) | null {
-    for (let i = items.length - 1; i >= 0; i--) {
-        const item = items[i]!;
-        if (item.kind === 'turn') {
-            return item.state === 'error' && item.limit !== undefined ? (item as ChatTurnItem & { limit: ChatTurnLimit }) : null;
-        }
-    }
-    return null;
+    const last = items.findLast((item) => item.kind === 'turn');
+    return last?.kind === 'turn' && last.state === 'error' && last.limit !== undefined ? (last as ChatTurnItem & { limit: ChatTurnLimit }) : null;
 }
 
 /* How many turns in a row, up to and including this one, stopped on a limit: the tries a person did not step in between. */

package/src/chat/readable-text.ts

@@ -0,0 +1,18 @@
+import type { ChatAssistantItem } from '@adecore/agent-contracts';
+import { uiFallbackText } from '@adecore/intelligent-ui/text';
+
+/*
+ * An assistant's words as another agent or a person outside the thread reads them: each UI block becomes
+ * its text fallback, with the first query values when they were frozen for the block as stored. It works
+ * from the stored block ranges, so it holds whatever fence language the host compiled.
+ */
+export function readableAssistantText(item: Pick<ChatAssistantItem, 'text' | 'ui' | 'uiQueries'>): string {
+    if (!item.ui?.length) {
+        return item.text;
+    }
+    const blocks = item.ui.map((block) => {
+        const frozen = item.uiQueries?.blocks[block.id];
+        return frozen && frozen.revision === block.revision ? { ...block, fallback: frozen.fallback } : block;
+    });
+    return uiFallbackText(item.text, blocks);
+}

package/src/chat/thread.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
+import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
 import { ChatError } from './errors.ts';
 import { requestSummaries } from './request-summary.ts';
-import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
 
 /*
  * The state of one chat as the client sees it. Every mutation answers the event that describes