@adecore/agents 0.20.1 → 0.21.1

package/dist/chat/chat-session.js

@@ -1,14 +1,19 @@
-import { randomUUID } from 'node:crypto';
-import { notResumedNote } from '@adecore/agent-contracts';
+import { createHash, randomUUID } from 'node:crypto';
+import { GeneratedImageInputSchema, notResumedNote } from '@adecore/agent-contracts';
+import { resolveUiChoice, UI_FENCE_LANGUAGE, UiFailure, uiHasFence, uiMayReferenceHost } from '@adecore/intelligent-ui';
+import { UiStream } from '@adecore/intelligent-ui/stream';
 import { commandLabel, isBackgroundWork, reportsOnBackgroundWork, runningInBackground } from './background-work.js';
 import { ChatError } from './errors.js';
 import { limitedTurn, limitResumeAt, limitResumeWake } from './limit-resume.js';
 import { isMainAgentOutput, ThreadProjector } from './projector.js';
+import { readableAssistantText } from './readable-text.js';
 import { ChatThread } from './thread.js';
 import { errorText } from '../error-text.js';
 import { systemClock } from '../outbox/outbox-worker.js';
 // 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;
 /* One per limited turn, so a second fork of the same turn writes no second note. */
 function continuedNoteId(turnId) {
     return `continued-${turnId}`;
@@ -70,12 +75,38 @@ export class ChatSession {
     pendingPreambles;
     submission = null;
     steering = new Set();
+    uiStreams = new Map();
+    uiCompiled = new Map();
+    capturedUiAccess;
+    // How much of a streaming reply's text the fence and host scans already covered, so a delta scans only its tail.
+    uiScanned = new Map();
+    uiReferencing = new Set();
+    uiAttachments = new Map();
+    uiFenceLanguage;
     constructor(options) {
         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 });
     }
+    get uiPreviews() {
+        const events = [];
+        for (const [itemId, preview] of this.uiCompiled) {
+            const item = this.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.uiCompiled.get(item.id);
+            return item.kind === 'assistant' && preview?.textLength === item.text.length ? { ...item, ui: preview.blocks } : item;
+        });
+    }
     get id() {
         return this.thread.info.chatId;
     }
@@ -148,6 +179,7 @@ export class ChatSession {
                 turnId,
                 text,
                 createdAt: Date.now(),
+                ...(extras.uiChoice ? { uiChoice: extras.uiChoice } : {}),
                 ...(extras.mentions?.length ? { mentions: extras.mentions } : {}),
                 ...(extras.skills?.length ? { skills: extras.skills } : {}),
                 ...(extras.chats?.length ? { chats: extras.chats } : {}),
@@ -161,6 +193,91 @@ export class ChatSession {
         this.dispatch(text, extras, turnId);
         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) {
+        return this.capturedUiAccess.get(itemId);
+    }
+    setUiAccess(itemId, access) {
+        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() {
+        return Object.fromEntries([...this.capturedUiAccess].filter(([itemId]) => this.thread.get(itemId) !== undefined));
+    }
+    updateUiQueries(itemId, uiQueries) {
+        const item = this.thread.get(itemId);
+        if (this.frozen || item?.kind !== 'assistant' || item.parentToolUseId) {
+            return;
+        }
+        this.thread.upsert({ ...item, uiQueries });
+        this.options.emit({ type: 'delta', itemId, text: '', uiQueries });
+        this.options.persistSoon();
+    }
+    choose(payload, queries = {}) {
+        const item = this.thread.get(payload.itemId);
+        const block = item?.kind === 'assistant' && !item.streaming && !item.parentToolUseId ? item.ui?.find((block) => block.id === payload.blockId) : undefined;
+        if (item?.kind !== 'assistant' || !block?.revision || block.revision !== payload.revision) {
+            throw new ChatError('stale-ui-block', 'This completed UI block is no longer available at the requested revision');
+        }
+        const sameBlock = (origin) => origin?.itemId === item.id && origin.blockId === block.id && origin.revision === block.revision;
+        let previous = item.uiAnswers?.[block.id];
+        if (previous?.revision !== block.revision) {
+            previous = undefined;
+        }
+        // The message is logged first: a crash before its answer marker must not send it a second time.
+        if (!previous) {
+            const sent = this.thread.list().find((entry) => entry.kind === 'user' && sameBlock(entry.uiChoice));
+            const queued = this.queue.find((entry) => sameBlock(entry.uiChoice));
+            const origin = sent?.kind === 'user' ? sent.uiChoice : queued?.uiChoice;
+            const turnId = sent?.turnId ?? queued?.turnId;
+            if (origin && turnId) {
+                previous = { ...origin, turnId, queued: !sent };
+                this.recordUiAnswer(previous);
+            }
+        }
+        if (previous) {
+            if (previous.choiceId !== payload.choiceId) {
+                throw new ChatError('ui-already-answered', 'This UI block was already answered');
+            }
+            return { queued: previous.queued, turnId: previous.turnId };
+        }
+        let selected;
+        try {
+            selected = resolveUiChoice(block, payload.choiceId, payload.values, queries);
+        }
+        catch (error) {
+            throw new ChatError(error instanceof UiFailure ? error.code : 'refused-choice', error instanceof Error ? error.message : 'This choice could not be read');
+        }
+        const origin = {
+            itemId: item.id,
+            blockId: block.id,
+            revision: block.revision,
+            choiceId: payload.choiceId,
+            label: selected.label,
+            sourceAt: item.createdAt,
+            older: this.thread.list().findLast((entry) => entry.kind === 'assistant' && !entry.parentToolUseId)?.id !== item.id,
+            values: selected.values,
+            at: Date.now()
+        };
+        const result = this.send(selected.context, { uiChoice: origin });
+        this.recordUiAnswer({ ...origin, ...result });
+        return result;
+    }
+    recordUiAnswer(answer) {
+        const item = this.thread.get(answer.itemId);
+        if (item?.kind !== 'assistant') {
+            return;
+        }
+        if (JSON.stringify(item.uiAnswers?.[answer.blockId]) === JSON.stringify(answer)) {
+            return;
+        }
+        this.options.emit(this.thread.upsert({ ...item, uiAnswers: { ...item.uiAnswers, [answer.blockId]: answer } }));
+        this.options.persist();
+    }
     sendInput(text, extras = {}) {
         return this.submitInput(text, extras);
     }
@@ -289,7 +406,7 @@ export class ChatSession {
         this.sendAfterReplacement = false;
         this.pauseQueue(false);
         this.setQueue(rest);
-        this.dispatch(next.text, { mentions: next.mentions, skills: next.skills, chats: next.chats, attachments: next.attachments }, next.turnId);
+        this.dispatch(next.text, { mentions: next.mentions, skills: next.skills, chats: next.chats, attachments: next.attachments, uiChoice: next.uiChoice }, next.turnId);
     }
     dispatch(text, extras, requestedTurnId) {
         this.pauseQueue(false);
@@ -298,7 +415,10 @@ export class ChatSession {
         // A slash command must stay the first thing the CLI reads, as `contextNote` keeps it.
         const references = text.startsWith('/') || !this.options.references ? { ids: [], note: null } : this.options.references(extras.chats);
         const turnId = this.openTurn(text, note, { ...extras, chats: references.ids }, requestedTurnId);
-        const said = [preamble, references.note].filter((part) => part !== null);
+        const choiceNote = extras.uiChoice
+            ? `The person chose ${JSON.stringify(extras.uiChoice.label)} from your UI reply. Their message is the visible context of that choice.`
+            : null;
+        const said = [preamble, references.note, choiceNote].filter((part) => part !== null);
         const input = {
             text,
             preamble: said.length === 0 ? null : said.join('\n\n'),
@@ -410,14 +530,14 @@ export class ChatSession {
     }
     /*
      * Starts the chat over: the CLI goes, and the next send starts one without a session to resume.
-     * A turn in the way is refused unless forced, and a forced clear does not wait for it to end,
-     * since the turn disappears with the thread anyway. Writing the empty thread is the caller's.
+     * The thread resets at once; the returned promise lets the host wait for pending attachment
+     * writes before removing their files. Writing the empty thread is the caller's.
      */
     clear(force) {
         if (this.busy && !force) {
             throw new ChatError('chat-busy', `Chat ${this.id} is still working on the previous message`);
         }
-        void this.dispose();
+        const ended = this.dispose();
         this.generation = nextGeneration();
         this.projector.reset();
         // The fresh CLI hears what the host tells it at launch, as it would on a first turn.
@@ -456,6 +576,7 @@ export class ChatSession {
                 }
             })
         ]);
+        return ended;
     }
     /*
      * A thread read from disk cannot still be streaming or waiting, so whatever was open is closed,
@@ -836,6 +957,7 @@ export class ChatSession {
     }
     /* Ends the process and stops listening to it, as the host goes down; the thread stays as it is. */
     freeze() {
+        this.clearUi();
         this.clearStartWarning();
         this.clearWorkflowWarnings();
         this.frozen = true;
@@ -843,6 +965,7 @@ export class ChatSession {
     }
     /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL. */
     dispose() {
+        this.clearUi();
         this.clearStartWarning();
         this.clearWorkflowWarnings();
         if (this.titleTimer !== null) {
@@ -988,10 +1111,24 @@ export class ChatSession {
             const skills = extras.skills?.length ? extras.skills : undefined;
             const chats = extras.chats?.length ? extras.chats : undefined;
             const attachments = extras.attachments?.length ? extras.attachments : undefined;
-            events.push(this.thread.upsert({ id: newId('user'), kind: 'user', createdAt: now, turnId, text, mentions, skills, chats, attachments }));
+            events.push(this.thread.upsert({
+                id: newId('user'),
+                kind: 'user',
+                createdAt: now,
+                turnId,
+                text,
+                mentions,
+                skills,
+                chats,
+                attachments,
+                ...(extras.uiChoice ? { uiChoice: extras.uiChoice } : {})
+            }));
         }
         events.push(this.thread.patchInfo({ status: this.thread.statusFor(turnId), activeTurnId: turnId }));
         this.emit(events);
+        if (extras.uiChoice) {
+            this.recordUiAnswer({ ...extras.uiChoice, turnId, queued: false });
+        }
         // On disk before the CLI answers, so a host that goes down mid-turn still shows the question.
         this.options.persist();
         return turnId;
@@ -1206,6 +1343,7 @@ export class ChatSession {
             runtimeMode: info.runtimeMode,
             resume: info.agentSessionId,
             generation,
+            saveGeneratedImage: this.options.saveGeneratedImage,
             instructions: this.options.instructions?.() ?? null,
             resumeNote: this.options.resumeNote?.() ?? null,
             ...(folders.length > 0 ? { folders } : {}),
@@ -1486,7 +1624,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;
@@ -1536,9 +1674,121 @@ export class ChatSession {
     }
     emit(events) {
         const delegating = this.delegatingChange(events);
-        for (const event of delegating === null ? events : [...events, delegating]) {
-            this.options.emit(event);
+        for (let event of delegating === null ? events : [...events, delegating]) {
+            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 && !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) => {
+                        this.uiCompiled.set(item.id, preview);
+                        this.options.emit({ type: 'delta', itemId: item.id, text: '', ui: preview.blocks, textLength: preview.textLength });
+                    }
+                });
+                this.uiStreams.set(item.id, stream);
+            }
+            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
+                    .finish(item.text, latestAttachment)
+                    .map((block) => ({ ...block, revision: createHash('sha256').update(JSON.stringify(block)).digest('hex') }));
+                this.uiStreams.delete(item.id);
+                this.uiCompiled.delete(item.id);
+                const diagnostics = [...new Set(ui.flatMap((block) => block.diagnostics.map((diagnostic) => diagnostic.message)))].slice(0, 6);
+                if (diagnostics.length > 0) {
+                    const repair = `Your last ${this.uiFenceLanguage} block had these diagnostics: ${diagnostics.join(' ')} Use the catalog's supported props and components.`.slice(0, 1200);
+                    if (!this.pendingPreambles.includes(repair)) {
+                        this.pendingPreambles = [...this.pendingPreambles, repair];
+                    }
+                }
+                const current = this.thread.get(item.id);
+                const completed = { ...item, ui, ...(current?.kind === 'assistant' && current.uiQueries ? { uiQueries: current.uiQueries } : {}) };
+                event = this.thread.upsert(completed);
+                this.options.emit(event);
+                this.options.ui?.observe(completed, true);
+            }
+            else {
+                this.options.emit(event);
+                stream.update(item.text, latestAttachment);
+            }
+        }
+    }
+    /*
+     * 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.
+     */
+    unscannedUiText(item, whole) {
+        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)}`;
+    }
+    forgetUiScan(item) {
+        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. */
+    latestUiAttachment(turnId) {
+        if (this.uiAttachments.has(turnId)) {
+            return this.uiAttachments.get(turnId);
+        }
+        const attachment = this.findUiAttachment(turnId);
+        this.uiAttachments.set(turnId, attachment);
+        return attachment;
+    }
+    findUiAttachment(turnId) {
+        for (const item of this.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;
+    }
+    clearUi() {
+        for (const stream of this.uiStreams.values()) {
+            stream.dispose();
         }
+        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. */
     delegatingChange(events) {

package/dist/chat/chat-store.d.ts

@@ -8,6 +8,7 @@ export interface ChatRecord {
     seq: number;
     resetSeq: number;
     preambles: string[];
+    uiAccess: Record<string, unknown>;
     extras: ChatRecordExtras;
     lines: ChatLogLine[];
 }
@@ -28,8 +29,8 @@ export declare class ChatStore {
     list(): Promise<string[]>;
     has(chatId: string): Promise<boolean>;
     discardLog(chatId: string): Promise<number>;
-    write(chatId: string, info: ChatInfo, items: ChatItem[], at?: ChatSeq, preambles?: readonly string[], extras?: ChatRecordExtras): Promise<number>;
-    writeSync(chatId: string, info: ChatInfo, items: ChatItem[], at?: ChatSeq, preambles?: readonly string[], extras?: ChatRecordExtras): void;
+    write(chatId: string, info: ChatInfo, items: ChatItem[], at?: ChatSeq, preambles?: readonly string[], extras?: ChatRecordExtras, uiAccess?: Readonly<Record<string, unknown>>): Promise<number>;
+    writeSync(chatId: string, info: ChatInfo, items: ChatItem[], at?: ChatSeq, preambles?: readonly string[], extras?: ChatRecordExtras, uiAccess?: Readonly<Record<string, unknown>>): void;
     read(chatId: string): Promise<ChatRecord | null>;
     unreadable(chatId: string): Promise<boolean>;
     private readSnapshot;

package/dist/chat/chat-store.js

@@ -19,17 +19,40 @@ 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']);
 function extrasOf(record) {
     return Object.fromEntries(Object.entries(record).filter(([key]) => !OWN_KEYS.has(key)));
 }
 function logName(chatId) {
     return `${encodeURIComponent(chatId)}.log`;
 }
-function recordBody(info, items, at, preambles, extras) {
-    return JSON.stringify({ info, items, ...at, ...(preambles.length === 0 ? {} : { preambles }), ...withoutOwnKeys(extras) });
+function recordBody(info, items, at, preambles, extras, uiAccess) {
+    return JSON.stringify({
+        info,
+        items,
+        ...at,
+        ...(preambles.length === 0 ? {} : { preambles }),
+        ...(Object.keys(uiAccess).length === 0 ? {} : { uiAccess }),
+        ...withoutOwnKeys(extras)
+    });
+}
+/* A record from before `uiAccess` kept the access inside each reply's `uiQueries`, which the item schema now drops. */
+function liftUiAccess(record) {
+    if (typeof record !== 'object' || record === null || 'uiAccess' in record || !Array.isArray(record.items)) {
+        return record;
+    }
+    const uiAccess = {};
+    for (const item of record.items) {
+        const queries = item?.uiQueries;
+        if (typeof queries === 'object' && queries !== null && 'access' in queries) {
+            uiAccess[String(item.id)] = queries.access;
+        }
+    }
+    return Object.keys(uiAccess).length === 0 ? record : { ...record, uiAccess };
 }
 function withoutOwnKeys(extras) {
     return Object.fromEntries(Object.entries(extras).filter(([key]) => !OWN_KEYS.has(key)));
@@ -80,8 +103,8 @@ export class ChatStore {
         return lines.at(-1)?.seq ?? 0;
     }
     /* Answers how many bytes the record took, which is what tells a caller whether writing it is cheap. */
-    async write(chatId, info, items, at = { seq: 0, resetSeq: 0 }, preambles = [], extras = {}) {
-        const body = recordBody(info, items, at, preambles, extras);
+    async write(chatId, info, items, at = { seq: 0, resetSeq: 0 }, preambles = [], extras = {}, uiAccess = {}) {
+        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;
@@ -90,9 +113,9 @@ export class ChatStore {
      * The same write without a turn of the event loop. A `bun --watch` reload restarts the module
      * before an awaited write comes back, so a shutdown has to put the threads down synchronously.
      */
-    writeSync(chatId, info, items, at = { seq: 0, resetSeq: 0 }, preambles = [], extras = {}) {
+    writeSync(chatId, info, items, at = { seq: 0, resetSeq: 0 }, preambles = [], extras = {}, uiAccess = {}) {
         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`). */
     async read(chatId) {
@@ -117,7 +140,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: extrasOf(snapshot),
+            lines
+        };
     }
     /*
      * Whether a record is on disk that this host cannot read: one a newer version wrote, one cut short,
@@ -146,7 +177,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;
     }
     async delete(chatId) {
@@ -199,5 +230,5 @@ function fromLogAlone(lines) {
             resetSeq = line.seq;
         }
     }
-    return { ...thread.snapshot(), seq: 0, resetSeq, preambles: [], extras: {}, lines };
+    return { ...thread.snapshot(), seq: 0, resetSeq, preambles: [], uiAccess: {}, extras: {}, lines };
 }

package/dist/chat/codex-backend.d.ts

@@ -9,6 +9,7 @@ export declare class CodexBackend implements ChatBackend {
     readonly acknowledgesTurns = true;
     private promptId;
     private readonly launch;
+    private imageWrites;
     private readonly host;
     private readonly protocol;
     private readonly client;
@@ -50,4 +51,5 @@ export declare class CodexBackend implements ChatBackend {
     private handleFrame;
     private handleExit;
     private emit;
+    private storeImage;
 }

package/dist/chat/codex-backend.js

@@ -39,6 +39,7 @@ export class CodexBackend {
     acknowledgesTurns = true;
     promptId = null;
     launch;
+    imageWrites = null;
     host;
     protocol;
     client;
@@ -321,7 +322,7 @@ export class CodexBackend {
     dispose() {
         const transport = this.transport;
         this.transport = null;
-        return transport?.dispose() ?? Promise.resolve();
+        return Promise.all([transport?.dispose(), this.imageWrites]).then(() => undefined);
     }
     /* A request whose failure the person has to hear about, since it is the turn that cannot go on. */
     request(method, params, accepted) {
@@ -381,6 +382,55 @@ export class CodexBackend {
             this.interruptOwed = false;
             this.promptId = null;
         }
+        if (event.type === 'image.generated' || this.imageWrites !== null) {
+            const pending = (this.imageWrites ?? Promise.resolve()).then(async () => {
+                if (event.type === 'image.generated') {
+                    await this.storeImage(event);
+                }
+                else {
+                    this.host.onEvent(event);
+                }
+            });
+            this.imageWrites = pending;
+            void pending
+                .finally(() => {
+                if (this.imageWrites === pending) {
+                    this.imageWrites = null;
+                }
+            })
+                .catch(() => undefined);
+            return;
+        }
         this.host.onEvent(event);
     }
+    async storeImage(event) {
+        const input = { revisedPrompt: event.revisedPrompt, transparentBackground: event.transparentBackground };
+        let attachment;
+        try {
+            if (!this.launch.saveGeneratedImage) {
+                throw new Error('This machine cannot save generated images');
+            }
+            attachment = await this.launch.saveGeneratedImage(event.ref, event.upload);
+        }
+        catch (error) {
+            this.host.onEvent({ type: 'tool.started', ref: event.ref, name: 'ImageGeneration', input, parentRef: null });
+            this.host.onEvent({ type: 'tool.done', ref: event.ref, output: errorText(error), state: 'error' });
+            return;
+        }
+        this.host.onEvent({
+            type: 'tool.started',
+            ref: event.ref,
+            name: 'ImageGeneration',
+            input: {
+                ...input,
+                attachment: {
+                    ...attachment,
+                    ...(event.width === undefined ? {} : { width: event.width }),
+                    ...(event.height === undefined ? {} : { height: event.height })
+                }
+            },
+            parentRef: null
+        });
+        this.host.onEvent({ type: 'tool.done', ref: event.ref, output: null, state: 'done' });
+    }
 }

package/dist/chat/codex-protocol.js

@@ -1,3 +1,4 @@
+import { generatedImage } from './generated-image.js';
 import { readCodexLimits } from '../usage/limits/normalize.js';
 import { codexRuntimeMode } from '../providers/codex.js';
 import { cleanTitle } from '../title-file.js';
@@ -567,7 +568,7 @@ export class CodexProtocol {
                     events.push({ type: 'question.requested', requestId: ref, questions, async: true });
                     return;
                 }
-                this.text(ref, str(item.text) ?? '', completed, events);
+                this.text(ref, str(item.text) ?? '', completed, events, str(item.phase) ?? undefined);
                 return;
             }
             case 'plan':
@@ -616,6 +617,32 @@ export class CodexProtocol {
             case 'dynamicToolCall':
                 this.tool(ref, str(item.tool) ?? 'tool', item.arguments ?? {}, completed, textOf(item.contentItems), item.success !== false, events);
                 return;
+            case 'imageGeneration': {
+                const revisedPrompt = str(item.revisedPrompt) ?? undefined;
+                const transparentBackground = typeof item.transparentBackground === 'boolean' ? item.transparentBackground : undefined;
+                const input = {
+                    ...(revisedPrompt === undefined ? {} : { revisedPrompt }),
+                    ...(transparentBackground === undefined ? {} : { transparentBackground })
+                };
+                if (!completed) {
+                    this.tool(ref, 'ImageGeneration', input, false, '', true, events);
+                    return;
+                }
+                try {
+                    if (item.failure || item.status !== 'completed') {
+                        throw new Error(isRecord(item.failure) ? (str(item.failure.message) ?? 'Image generation failed') : (str(item.failure) ?? 'Image generation failed'));
+                    }
+                    const image = generatedImage(str(item.result) ?? '', revisedPrompt);
+                    events.push({ type: 'image.generated', ref, ...image, ...input });
+                }
+                catch (error) {
+                    this.tool(ref, 'ImageGeneration', input, true, error instanceof Error ? error.message : 'Image generation failed', false, events);
+                }
+                return;
+            }
+            case 'imageView':
+                this.tool(ref, 'ImageView', { path: str(item.path) ?? '' }, completed, '', true, events);
+                return;
             case 'webSearch': {
                 const action = isRecord(item.action) ? item.action : {};
                 this.tool(ref, 'WebSearch', { query: str(item.query) ?? str(action.query) ?? '' }, completed, '', true, events);
@@ -683,8 +710,8 @@ export class CodexProtocol {
         }
         return null;
     }
-    text(ref, text, completed, events) {
-        events.push(completed ? { type: 'text.done', ref, text } : { type: 'text.delta', ref, text });
+    text(ref, text, completed, events, phase) {
+        events.push({ type: completed ? 'text.done' : 'text.delta', ref, text, ...(phase === undefined ? {} : { phase }) });
     }
     /*
      * An agent Codex spawned, as a spawnAgent call reports it. It works in a thread of its own, so this row

package/dist/chat/delta-coalescer.js

@@ -16,7 +16,7 @@ export class DeltaCoalescer {
         this.tickMs = tickMs;
     }
     push(event) {
-        if (event.type !== 'delta') {
+        if (event.type !== 'delta' || event.uiQueries !== undefined) {
             this.flush();
             this.send(event);
             return;

package/dist/chat/errors.d.ts

@@ -1,4 +1,4 @@
 import { CodedError } from '../coded-error.ts';
-export type ChatErrorCode = 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'task-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks' | 'visual-invalid' | 'visual-too-large';
+export type ChatErrorCode = 'refused-query' | 'stale-ui-query' | 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'task-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks' | 'visual-invalid' | 'visual-too-large';
 export declare class ChatError<TCode extends string = ChatErrorCode> extends CodedError<TCode> {
 }