@adecore/agents 0.20.1 → 0.21.1

package/dist/chat/fake-codex.js

@@ -169,6 +169,39 @@ export function fakeCodexWith(options) {
                 turnCompleted('failed', "You've hit your usage limit.", 'usageLimitExceeded');
                 return;
             }
+            if (text.startsWith('image:')) {
+                const scenario = text.slice(6);
+                const entry = item('imageGeneration', {
+                    status: 'inProgress',
+                    result: '',
+                    savedPath: '/never-read-generated-image.png',
+                    revisedPrompt: 'A rabbit',
+                    transparentBackground: true
+                });
+                started(entry);
+                const result = scenario === 'empty'
+                    ? ''
+                    : scenario === 'invalid'
+                        ? 'not base64'
+                        : scenario === 'not-image'
+                            ? Buffer.from('text').toString('base64')
+                            : scenario === 'too-large'
+                                ? Buffer.alloc(10 * 1024 * 1024 + 1).toString('base64')
+                                : 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=';
+                const done = {
+                    ...entry,
+                    status: scenario === 'failed' ? 'failed' : 'completed',
+                    result,
+                    ...(scenario === 'failed' ? { failure: { message: 'Image generation failed' } } : {})
+                };
+                completed(done);
+                if (scenario === 'replay') {
+                    completed(done);
+                }
+                agentMessage('Here is the generated image.');
+                turnCompleted('completed');
+                return;
+            }
             if (text === 'slow') {
                 slow = true;
                 started(item('agentMessage', { text: '', phase: 'final_answer', memoryCitation: null, delivery: null, questions: null }));

package/dist/chat/generated-image.d.ts

@@ -0,0 +1,6 @@
+import { type ChatAttachmentUpload } from '@adecore/agent-contracts';
+export declare function generatedImage(data: string, prompt?: string): {
+    upload: ChatAttachmentUpload;
+    width?: number;
+    height?: number;
+};

package/dist/chat/generated-image.js

@@ -0,0 +1,74 @@
+import { ChatAttachmentUploadSchema } from '@adecore/agent-contracts';
+function imageInfo(bytes) {
+    if (bytes.length >= 33 &&
+        bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) &&
+        bytes.readUInt32BE(8) === 13 &&
+        bytes.toString('ascii', 12, 16) === 'IHDR') {
+        return { mime: 'image/png', extension: 'png', width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+    }
+    if (bytes.length >= 13 && /GIF8[79]a/.test(bytes.toString('ascii', 0, 6))) {
+        return { mime: 'image/gif', extension: 'gif', width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+    }
+    if (bytes.length >= 20 &&
+        bytes.toString('ascii', 0, 4) === 'RIFF' &&
+        bytes.toString('ascii', 8, 12) === 'WEBP' &&
+        bytes.readUInt32LE(4) + 8 === bytes.length) {
+        const kind = bytes.toString('ascii', 12, 16);
+        if (kind === 'VP8X' && bytes.length >= 30) {
+            return { mime: 'image/webp', extension: 'webp', width: bytes.readUIntLE(24, 3) + 1, height: bytes.readUIntLE(27, 3) + 1 };
+        }
+        if (kind === 'VP8 ' && bytes.length >= 30 && bytes.subarray(23, 26).equals(Buffer.from([157, 1, 42]))) {
+            return { mime: 'image/webp', extension: 'webp', width: bytes.readUInt16LE(26) & 0x3fff, height: bytes.readUInt16LE(28) & 0x3fff };
+        }
+        if (kind === 'VP8L' && bytes.length >= 25 && bytes[20] === 0x2f) {
+            const size = bytes.readUInt32LE(21);
+            return { mime: 'image/webp', extension: 'webp', width: (size & 0x3fff) + 1, height: ((size >> 14) & 0x3fff) + 1 };
+        }
+        return null;
+    }
+    if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) {
+        let offset = 2;
+        while (offset + 4 <= bytes.length && bytes[offset] === 255) {
+            const marker = bytes[offset + 1];
+            if (marker === 218 || marker === 217) {
+                break;
+            }
+            if (marker === 255) {
+                offset++;
+                continue;
+            }
+            const size = bytes.readUInt16BE(offset + 2);
+            if (size < 2 || offset + 2 + size > bytes.length) {
+                return null;
+            }
+            if ([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207].includes(marker) && size >= 8) {
+                return { mime: 'image/jpeg', extension: 'jpg', width: bytes.readUInt16BE(offset + 7), height: bytes.readUInt16BE(offset + 5) };
+            }
+            offset += size + 2;
+        }
+    }
+    return null;
+}
+export function generatedImage(data, prompt) {
+    const parsed = ChatAttachmentUploadSchema.safeParse({ name: 'image', mime: 'application/octet-stream', data });
+    if (!parsed.success) {
+        throw new Error('The generated image is empty, invalid base64 or exceeds 10 MiB');
+    }
+    const bytes = Buffer.from(data, 'base64');
+    // Buffer's decoder accepts malformed padding and trailing bits; the protocol requires canonical base64.
+    if (bytes.toString('base64') !== data) {
+        throw new Error('The generated image contains invalid base64');
+    }
+    const info = imageInfo(bytes);
+    if (info === null || (info.width !== undefined && info.width === 0) || (info.height !== undefined && info.height === 0)) {
+        throw new Error('The generated bytes are not a supported image');
+    }
+    const stem = (prompt ?? '')
+        .normalize('NFKD')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 80)
+        .toLowerCase() || 'generated-image';
+    const upload = { name: `${stem}.${info.extension}`, mime: info.mime, data };
+    return { upload, ...(info.width === undefined ? {} : { width: info.width }), ...(info.height === undefined ? {} : { height: info.height }) };
+}

package/dist/chat/projector.js

@@ -150,7 +150,7 @@ export class ThreadProjector {
                 break;
             case 'text.delta':
                 this.closeThinking(events);
-                this.appendText(this.itemId(generation, event.ref), event.text, events);
+                this.appendText(this.itemId(generation, event.ref), event.text, events, event.phase);
                 break;
             case 'text.done': {
                 if (event.parentRef) {
@@ -168,6 +168,12 @@ export class ThreadProjector {
                     createdAt: existing?.createdAt ?? this.now(),
                     turnId: existing?.turnId ?? info.activeTurnId,
                     text: event.text,
+                    ...(existing?.kind === 'assistant' ? { uiAnswers: existing.uiAnswers, uiQueries: existing.uiQueries } : {}),
+                    ...(event.phase === undefined
+                        ? existing?.kind === 'assistant' && existing.phase !== undefined
+                            ? { phase: existing.phase }
+                            : {}
+                        : { phase: event.phase }),
                     streaming: false
                 }));
                 break;
@@ -452,7 +458,7 @@ export class ThreadProjector {
             events.push(this.thread.upsert({ ...item, streaming: false, endedAt: this.now() }));
         }
     }
-    appendText(id, text, events) {
+    appendText(id, text, events, phase) {
         const existing = this.thread.get(id);
         if (!existing) {
             events.push(this.thread.upsert({
@@ -461,6 +467,7 @@ export class ThreadProjector {
                 createdAt: this.now(),
                 turnId: this.thread.info.activeTurnId,
                 text,
+                ...(phase === undefined ? {} : { phase }),
                 streaming: true
             }));
             return;

package/dist/chat/readable-text.d.ts

@@ -0,0 +1,2 @@
+import type { ChatAssistantItem } from '@adecore/agent-contracts';
+export declare function readableAssistantText(item: Pick<ChatAssistantItem, 'text' | 'ui' | 'uiQueries'>): string;

package/dist/chat/readable-text.js

@@ -0,0 +1,16 @@
+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) {
+    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/dist/chat/thread.js

@@ -82,6 +82,12 @@ export class ChatThread {
                 break;
             case 'delta':
                 this.appendText(event.itemId, event.text);
+                if (event.uiQueries) {
+                    const item = this.items.get(event.itemId);
+                    if (item?.kind === 'assistant') {
+                        this.items.set(item.id, { ...item, uiQueries: event.uiQueries });
+                    }
+                }
                 break;
             case 'info':
                 this.info = event.info;

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

@@ -0,0 +1,49 @@
+import type { z } from 'zod';
+import type { ChatUiLinkPayload, ChatUiLinkReading, ChatAssistantItem, ChatInfo, ChatUiChoicePayload, ChatUiQueryPayload, ChatUiQueryReading } from '@adecore/agent-contracts';
+import { type UiValue } from '@adecore/intelligent-ui';
+import { type UiLinkTarget } from '@adecore/intelligent-ui/links';
+import type { ChatSession } from './chat-session.ts';
+import { ChatError } from './errors.ts';
+export interface ChatUiSource {
+    args: z.ZodType;
+    result: z.ZodType;
+    authorize(info: ChatInfo, access: unknown, args: Record<string, UiValue>): Promise<void>;
+    read(info: ChatInfo, args: Record<string, UiValue>, signal: AbortSignal, access: unknown): Promise<unknown>;
+}
+export interface ChatUiHost {
+    capture(info: ChatInfo): Promise<unknown>;
+    sources: Readonly<Record<string, ChatUiSource>>;
+    link?(info: ChatInfo, access: unknown, target: UiLinkTarget): Promise<ChatUiLinkReading>;
+}
+declare class UiQueryError extends ChatError<string> {
+    readonly reason: string;
+    constructor(code: string, reason: string, message: string);
+}
+export declare class ChatUiRefusal extends UiQueryError {
+    constructor(code: string, reason: string);
+}
+export declare class ChatUiQueries {
+    readonly schemas: Record<string, z.ZodType>;
+    private readonly captures;
+    private readonly freezing;
+    private readonly cache;
+    private readonly latest;
+    private readonly reading;
+    private readonly attempts;
+    private readonly active;
+    private totalActive;
+    private readonly host;
+    constructor(host: ChatUiHost);
+    observe(session: ChatSession, item: ChatAssistantItem, final: boolean): void;
+    private access;
+    private storedBlock;
+    private stored;
+    query(session: ChatSession, payload: ChatUiQueryPayload): Promise<ChatUiQueryReading>;
+    choiceValues(session: ChatSession, payload: ChatUiChoicePayload | ChatUiLinkPayload): Promise<Record<string, unknown>>;
+    link(session: ChatSession, payload: ChatUiLinkPayload): Promise<ChatUiLinkReading>;
+    forget(chatId: string): void;
+    private evict;
+    private linkReading;
+    private failure;
+}
+export {};

package/dist/chat/ui-queries.js

@@ -0,0 +1,358 @@
+import { randomUUID } from 'node:crypto';
+import { copyUiValue, UI_HOST_LIMITS, UiBudget, uiMayReferenceHost } from '@adecore/intelligent-ui';
+import { UiLinkResolutionSchema, uiLinkTargets } from '@adecore/intelligent-ui/links';
+import { uiQueryArguments, uiQueryFallback } from '@adecore/intelligent-ui/query';
+import { ChatError } from './errors.js';
+/*
+ * A failure a client can say in its own words: `reason` is a code that stays the same across versions,
+ * the message is the fallback for a client that does not know the code.
+ */
+class UiQueryError extends ChatError {
+    reason;
+    constructor(code, reason, message) {
+        super(code, message);
+        this.reason = reason;
+    }
+}
+/*
+ * What a host's `authorize`, `read` or `link` throws to say why with a code: `code` reaches the reading's
+ * `code` and should stay the same across versions, `reason` is the plain sentence a client shows without it.
+ */
+export class ChatUiRefusal extends UiQueryError {
+    constructor(code, reason) {
+        super('refused-query', code, reason);
+    }
+}
+const MAX_QUERY_BYTES = 64 * 1024;
+const MAX_SNAPSHOT_BYTES = 128 * 1024;
+const READ_TIMEOUT_MS = 8_000;
+// A changed input reads at once, but a query never reads more often than this across its inputs.
+const INPUT_READ_MS = 250;
+export class ChatUiQueries {
+    schemas;
+    captures = new Map();
+    freezing = new Set();
+    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();
+    reading = new Map();
+    attempts = new Map();
+    active = new Map();
+    totalActive = 0;
+    host;
+    constructor(host) {
+        this.host = host;
+        this.schemas = Object.fromEntries(Object.entries(host.sources).map(([name, source]) => [name, source.args]));
+    }
+    observe(session, item, final) {
+        const key = `${session.id}:${item.id}`;
+        // Once a capture started, every delta of a streaming reply would scan its whole text again for nothing.
+        const captured = this.captures.has(key) || item.uiQueries?.authorChatId === session.id;
+        if (!captured && !uiMayReferenceHost(item.text) && !item.ui?.some((block) => Object.keys(block.queries).length)) {
+            return;
+        }
+        const capture = this.access(session, item);
+        if (!final || !item.ui?.length) {
+            return;
+        }
+        if (this.freezing.has(key)) {
+            return;
+        }
+        this.freezing.add(key);
+        void capture
+            .then(async () => {
+            for (const block of (item.ui ?? []).slice(0, 16)) {
+                const current = session.thread.get(item.id);
+                if (current?.kind !== 'assistant' || current.ui?.find((entry) => entry.id === block.id)?.revision !== block.revision) {
+                    return;
+                }
+                if (current.uiQueries?.blocks[block.id]?.revision === block.revision) {
+                    continue;
+                }
+                const readings = Object.create(null);
+                const values = Object.create(null);
+                for (const name of Object.keys(block.queries).slice(0, UI_HOST_LIMITS.queries)) {
+                    const reading = await this.query(session, {
+                        chatId: session.id,
+                        itemId: item.id,
+                        blockId: block.id,
+                        revision: block.revision,
+                        query: name
+                    });
+                    readings[name] = reading;
+                    if (reading.state === 'fresh') {
+                        values[name] = reading.value;
+                    }
+                }
+                const links = Object.create(null);
+                if (this.host.link) {
+                    const targets = uiLinkTargets(block, {}, values);
+                    const access = await this.access(session, current);
+                    for (const [id, target] of Object.entries(targets).slice(0, UI_HOST_LIMITS.links)) {
+                        try {
+                            links[id] = this.linkReading(await this.host.link(session.info, access, target));
+                        }
+                        catch (error) {
+                            links[id] = { state: 'plain', ...this.failure(error) };
+                        }
+                    }
+                }
+                const latest = session.thread.get(item.id);
+                if (latest?.kind !== 'assistant' || !latest.uiQueries || latest.ui?.find((entry) => entry.id === block.id)?.revision !== block.revision) {
+                    return;
+                }
+                const names = Object.entries(block.queries)
+                    .map(([name, query]) => `${name}: ${query.source}`)
+                    .join(', ');
+                const failures = Object.entries(readings)
+                    .filter(([, reading]) => reading.state !== 'fresh')
+                    .map(([name, reading]) => `${name}: ${reading.reason}`)
+                    .join('\n');
+                const frozen = {
+                    revision: block.revision,
+                    readings,
+                    links,
+                    fallback: `${uiQueryFallback(block, values).slice(0, 8192)}${names ? `\nSources: ${names}` : ''}${failures ? `\n${failures}` : ''}`
+                };
+                const blocks = { ...latest.uiQueries.blocks, [block.id]: frozen };
+                if (Buffer.byteLength(JSON.stringify(blocks)) > MAX_SNAPSHOT_BYTES) {
+                    frozen.readings = Object.fromEntries(Object.keys(readings).map((name) => [
+                        name,
+                        { state: 'failed', readAt: Date.now(), code: 'snapshot-too-large', reason: 'The frozen query values are too large.' }
+                    ]));
+                    frozen.links = Object.fromEntries(Object.keys(links).map((id) => [id, { state: 'plain', code: 'link-unchecked', reason: 'This link must be checked again.' }]));
+                    frozen.fallback = `${block.fallback.slice(0, 2048)}\nSources: ${names}\nThe frozen query values are too large.`;
+                }
+                if (Buffer.byteLength(JSON.stringify(blocks)) > MAX_SNAPSHOT_BYTES) {
+                    delete blocks[block.id];
+                }
+                session.updateUiQueries(item.id, { ...latest.uiQueries, blocks });
+            }
+        })
+            .catch(() => { })
+            .finally(() => this.freezing.delete(key));
+    }
+    /* The writer's access for a reply, captured once; null where it was denied or is unavailable. */
+    access(session, item) {
+        const key = `${session.id}:${item.id}`;
+        const existing = this.captures.get(key);
+        if (existing) {
+            return existing;
+        }
+        if (item.uiQueries?.authorChatId === session.id) {
+            return Promise.resolve(session.uiAccess(item.id) ?? null);
+        }
+        // A pending capture is persisted as denied, so a restart cannot widen the writer's rights.
+        session.setUiAccess(item.id, null);
+        session.updateUiQueries(item.id, { authorChatId: session.id, blocks: {} });
+        const captured = this.host
+            .capture(session.info)
+            .then((access) => {
+            const captured = copyUiValue(access, new UiBudget());
+            if (Buffer.byteLength(JSON.stringify(captured)) > 32 * 1024) {
+                throw new Error('The UI access snapshot is too large.');
+            }
+            session.setUiAccess(item.id, captured);
+            return captured;
+        })
+            .catch(() => null)
+            .finally(() => this.captures.delete(key));
+        this.captures.set(key, captured);
+        return captured;
+    }
+    storedBlock(session, payload) {
+        const item = session.thread.get(payload.itemId);
+        const block = item?.kind === 'assistant' && !item.streaming && !item.parentToolUseId ? item.ui?.find((entry) => entry.id === payload.blockId) : undefined;
+        if (item?.kind !== 'assistant' || !block?.complete || block.revision !== payload.revision) {
+            throw new UiQueryError('stale-ui-block', 'block-stale', 'This completed UI block is no longer available.');
+        }
+        return { item, block };
+    }
+    stored(session, payload) {
+        const { item, block } = this.storedBlock(session, payload);
+        if (!Object.hasOwn(block.queries, payload.query) || Object.keys(block.queries).length > UI_HOST_LIMITS.queries) {
+            throw new UiQueryError('refused-query', 'query-undeclared', 'This block does not declare an allowed query.');
+        }
+        const name = block.queries[payload.query].source;
+        if (!Object.hasOwn(this.host.sources, name)) {
+            throw new UiQueryError('refused-query', 'source-unregistered', 'This query source is not registered.');
+        }
+        return { item, block, source: this.host.sources[name] };
+    }
+    async query(session, payload) {
+        let args;
+        let source;
+        let block;
+        let item;
+        let authorAccess;
+        try {
+            ({ source, block, item } = this.stored(session, payload));
+            args = uiQueryArguments(block, payload.query, payload.values);
+            args = source.args.parse(args);
+            authorAccess = await this.access(session, item);
+            if (authorAccess === null) {
+                throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
+            }
+            await source.authorize(session.info, authorAccess, args);
+        }
+        catch (error) {
+            return { state: 'refused', readAt: Date.now(), ...this.failure(error) };
+        }
+        const key = JSON.stringify([session.id, item.id, block.id, block.revision, payload.query, args]);
+        const cached = this.cache.get(this.latest.get(key) ?? '');
+        if (cached && Date.now() - cached.reading.readAt < UI_HOST_LIMITS.refreshMilliseconds) {
+            return cached.reading;
+        }
+        const pending = this.reading.get(key);
+        if (pending) {
+            return pending;
+        }
+        const identity = JSON.stringify([session.id, item.id, block.id, block.revision, payload.query]);
+        const now = Date.now();
+        if (now - (this.attempts.get(key) ?? -Infinity) < UI_HOST_LIMITS.refreshMilliseconds ||
+            now - (this.attempts.get(identity) ?? -Infinity) < INPUT_READ_MS) {
+            return { state: 'failed', readAt: now, code: 'refresh-limit', reason: 'This query may refresh once every ten seconds.' };
+        }
+        if ((this.active.get(session.id) ?? 0) >= 2 || this.totalActive >= 16) {
+            return { state: 'failed', readAt: now, code: 'busy', reason: 'Too many UI queries are being read.' };
+        }
+        this.attempts.set(key, now);
+        this.attempts.set(identity, now);
+        while (this.attempts.size > 256) {
+            this.attempts.delete(this.attempts.keys().next().value);
+        }
+        this.active.set(session.id, (this.active.get(session.id) ?? 0) + 1);
+        this.totalActive++;
+        const controller = new AbortController();
+        const work = Promise.resolve().then(() => source.read(session.info, args, controller.signal, authorAccess));
+        const timeout = setTimeout(() => controller.abort(), READ_TIMEOUT_MS);
+        timeout.unref?.();
+        const read = Promise.race([
+            work,
+            new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(new UiQueryError('refused-query', 'timed-out', 'The UI query timed out.')), {
+                once: true
+            }))
+        ])
+            .then((result) => {
+            const value = copyUiValue(source.result.parse(result), new UiBudget());
+            if (Buffer.byteLength(JSON.stringify(value)) > MAX_QUERY_BYTES) {
+                throw new 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.latest.set(key, reading.readId);
+            while (this.cache.size > 128) {
+                this.evict(this.cache.keys().next().value);
+            }
+            return reading;
+        })
+            .catch((error) => ({ state: 'failed', readAt: Date.now(), ...this.failure(error) }))
+            .finally(() => {
+            clearTimeout(timeout);
+            this.reading.delete(key);
+        });
+        // Timed-out sources still occupy their slot until their actual work ends.
+        void work
+            .catch(() => { })
+            .finally(() => {
+            const count = (this.active.get(session.id) ?? 1) - 1;
+            if (count) {
+                this.active.set(session.id, count);
+            }
+            else {
+                this.active.delete(session.id);
+            }
+            this.totalActive--;
+        });
+        this.reading.set(key, read);
+        return read;
+    }
+    /* The issued value of every query the block declares, each checked against the read id the person saw. */
+    async choiceValues(session, payload) {
+        const item = session.thread.get(payload.itemId);
+        const block = item?.kind === 'assistant' ? item.ui?.find((entry) => entry.id === payload.blockId) : undefined;
+        if (!block || item?.kind !== 'assistant' || ('choiceId' in payload && item.uiAnswers?.[block.id]?.revision === payload.revision)) {
+            return {};
+        }
+        const names = Object.keys(block.queries);
+        const values = Object.create(null);
+        if (names.length === 0) {
+            return values;
+        }
+        const access = await this.access(session, item);
+        if (access === null) {
+            throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
+        }
+        for (const name of names) {
+            const { source } = this.stored(session, { ...payload, query: name });
+            const args = source.args.parse(uiQueryArguments(block, name, payload.values));
+            await source.authorize(session.info, access, args);
+            const readId = payload.reads !== undefined && Object.hasOwn(payload.reads, name) ? payload.reads[name] : undefined;
+            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
+                : cached?.key === key
+                    ? cached.reading
+                    : snapshot?.readId === readId && JSON.stringify(args) === JSON.stringify(source.args.parse(uiQueryArguments(block, name)))
+                        ? snapshot
+                        : undefined;
+            if (!reading || reading.state !== 'fresh') {
+                throw new UiQueryError('stale-ui-query', 'stale-read', 'Refresh this query before sending its choice.');
+            }
+            values[name] = reading.value;
+        }
+        return values;
+    }
+    async link(session, payload) {
+        try {
+            if (!this.host.link) {
+                throw new UiQueryError('refused-query', 'links-unsupported', 'This host does not provide UI links.');
+            }
+            const { item, block } = this.storedBlock(session, payload);
+            if (!item.uiQueries) {
+                throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
+            }
+            const access = await this.access(session, item);
+            if (access === null) {
+                throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
+            }
+            const queries = await this.choiceValues(session, payload);
+            const target = uiLinkTargets(block, payload.values, queries)[payload.nodeId];
+            if (!target) {
+                throw new UiQueryError('refused-query', 'link-unsupported', 'This visible node is not a supported link.');
+            }
+            return this.linkReading(await this.host.link(session.info, access, target));
+        }
+        catch (error) {
+            return { state: 'plain', ...this.failure(error) };
+        }
+    }
+    forget(chatId) {
+        for (const [id, cached] of this.cache) {
+            if (cached.chatId === chatId) {
+                this.evict(id);
+            }
+        }
+    }
+    evict(readId) {
+        const cached = this.cache.get(readId);
+        this.cache.delete(readId);
+        if (cached && this.latest.get(cached.key) === readId) {
+            this.latest.delete(cached.key);
+        }
+    }
+    linkReading(value) {
+        const reading = UiLinkResolutionSchema.parse(copyUiValue(value, new UiBudget()));
+        if (reading.state === 'chip' && !reading.target) {
+            throw new Error('The host did not resolve a link target.');
+        }
+        return reading;
+    }
+    failure(error) {
+        const reason = (error instanceof Error ? error.message : 'This query could not be read.').slice(0, 240);
+        return error instanceof UiQueryError ? { reason, code: error.reason } : { reason };
+    }
+}

package/dist/host/handlers.js

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

package/dist/tasks/task-coordinator.js

@@ -1,12 +1,16 @@
 import { abortedByMachine, clipText } from '@adecore/agent-contracts';
 import { BACKGROUND_COMMAND_LIMIT_MS, commandLabel, isBackgroundWork, runningInBackground, runsInBackground } from '../chat/background-work.js';
+import { readableAssistantText } from '../chat/readable-text.js';
 import { errorText } from '../error-text.js';
 // A child's answer is its last word of the turn; the thinking and the tools before it are not the result.
 function answerOf(items, turnId) {
     for (let i = items.length - 1; i >= 0; i--) {
         const item = items[i];
-        if (item.kind === 'assistant' && item.turnId === turnId && !item.parentToolUseId && item.text.trim() !== '') {
-            return item.text.trim();
+        if (item.kind === 'assistant' && item.turnId === turnId && !item.parentToolUseId) {
+            const text = readableAssistantText(item).trim();
+            if (text !== '') {
+                return text;
+            }
         }
     }
     return null;

package/package.json

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