@adecore/agents 0.20.1 → 0.21.0

package/src/chat/chat-session.ts

@@ -1,6 +1,7 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import type {
     ChatAttachment,
+    ChatAssistantItem,
     ChatCheckpointDiff,
     ChatEvent,
     ChatInfo,
@@ -9,10 +10,17 @@ import type {
     ChatSkill,
     ChatSubagentItem,
     ChatTurnItem,
+    ChatUiAnswer,
+    ChatUiChoiceOrigin,
+    ChatUiChoicePayload,
+    ChatUiQueryState,
     ModelSelection,
     RuntimeMode
 } from '@adecore/agent-contracts';
-import { notResumedNote } from '@adecore/agent-contracts';
+import { GeneratedImageInputSchema, notResumedNote } from '@adecore/agent-contracts';
+import { resolveUiChoice, UiFailure } 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';
 import type { LimitsUpdate } from '../usage/limits/normalize.ts';
 import type { BackendEvent, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
@@ -58,6 +66,7 @@ export interface ChatSessionOptions {
     /* The environment of the CLI under the chat's account, asked at every start; throws for an account that cannot start. */
     env(account: string | undefined): Record<string, string>;
     spawn?: SpawnChatProcess;
+    saveGeneratedImage?: BackendLaunch['saveGeneratedImage'];
     // What the agent is told at the start of every process, and what of it a resumed thread hears again; see `BackendLaunch`.
     instructions?(): string | null;
     resumeNote?(): string | null;
@@ -67,6 +76,10 @@ export interface ChatSessionOptions {
     references?: ChatReferences;
     // Trees per turn, so a settled turn can show what the working tree holds against its start.
     checkpoints?: TurnCheckpoints;
+    ui?: {
+        schemas: UiCompileOptions['querySchemas'];
+        observe(item: ChatAssistantItem, final: boolean): void;
+    };
     emit(event: ChatEvent): void;
     /* What a turn said about the plan it runs on. It belongs to the machine, so it leaves the chat. */
     onLimits?(update: LimitsUpdate): void;
@@ -98,6 +111,7 @@ export interface LimitResumeHooks {
 const TITLE_RECHECK_MS = 10_000;
 
 export interface ChatSendExtras {
+    uiChoice?: ChatUiChoiceOrigin;
     delivery?: 'steer' | 'queue';
     mentions?: string[];
     skills?: string[];
@@ -177,6 +191,8 @@ export class ChatSession {
     private pendingPreambles: readonly string[];
     private submission: { turnId: string; input: TurnInput } | null = null;
     private readonly steering = new Set<string>();
+    private readonly uiStreams = new Map<string, UiStream>();
+    private readonly uiCompiled = new Map<string, UiStreamPreview>();
 
     constructor(options: ChatSessionOptions) {
         this.options = options;
@@ -185,6 +201,24 @@ export class ChatSession {
         this.projector = new ThreadProjector(this.thread, { providerName: options.provider.name });
     }
 
+    get uiPreviews(): ChatEvent[] {
+        const events: ChatEvent[] = [];
+        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: ChatItem[]): ChatItem[] {
+        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(): string {
         return this.thread.info.chatId;
     }
@@ -265,6 +299,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 } : {}),
@@ -279,6 +314,83 @@ export class ChatSession {
         return { queued: false, turnId };
     }
 
+    updateUiQueries(itemId: string, uiQueries: ChatUiQueryState): void {
+        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: ChatUiChoicePayload, queries: Readonly<Record<string, unknown>> = {}): { queued: boolean; turnId: string } {
+        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: ChatUiChoiceOrigin | undefined) =>
+            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: ChatUiChoiceOrigin = {
+            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;
+    }
+
+    private recordUiAnswer(answer: ChatUiAnswer): void {
+        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: string, extras: ChatSendExtras = {}): Promise<{ queued: boolean; turnId: string }> {
         return this.submitInput(text, extras);
     }
@@ -415,7 +527,11 @@ 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
+        );
     }
 
     private dispatch(text: string, extras: ChatSendExtras, requestedTurnId?: string): void {
@@ -425,7 +541,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 is string => 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 is string => part !== null);
         const input = {
             text,
             preamble: said.length === 0 ? null : said.join('\n\n'),
@@ -544,14 +663,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: boolean): void {
+    clear(force: boolean): Promise<void> {
         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.
@@ -590,6 +709,7 @@ export class ChatSession {
                 }
             })
         ]);
+        return ended;
     }
 
     /*
@@ -994,6 +1114,7 @@ export class ChatSession {
 
     /* Ends the process and stops listening to it, as the host goes down; the thread stays as it is. */
     freeze(): void {
+        this.clearUi();
         this.clearStartWarning();
         this.clearWorkflowWarnings();
         this.frozen = true;
@@ -1002,6 +1123,7 @@ export class ChatSession {
 
     /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL. */
     dispose(): Promise<void> {
+        this.clearUi();
         this.clearStartWarning();
         this.clearWorkflowWarnings();
         if (this.titleTimer !== null) {
@@ -1159,10 +1281,26 @@ 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;
@@ -1392,6 +1530,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 } : {}),
@@ -1743,9 +1882,82 @@ export class ChatSession {
 
     private emit(events: ChatEvent[]): void {
         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();
+            }
+            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;
+            }
+            let stream = this.uiStreams.get(item.id);
+            if (!stream && !item.text.includes('ruimte-ui')) {
+                this.options.emit(event);
+                continue;
+            }
+            if (!stream) {
+                stream = new UiStream({
+                    querySchemas: this.options.ui?.schemas,
+                    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);
+            }
+            this.options.ui?.observe(item, false);
+            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 ruimte-ui 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);
+            }
+        }
+    }
+
+    private latestUiAttachment(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;
+            }
+            const input = GeneratedImageInputSchema.safeParse(item.input);
+            if (input.success && input.data.attachment?.mime.startsWith('image/')) {
+                return input.data.attachment.id;
+            }
+        }
+        return undefined;
+    }
+
+    private clearUi(): void {
+        for (const stream of this.uiStreams.values()) {
+            stream.dispose();
         }
+        this.uiStreams.clear();
+        this.uiCompiled.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/codex-backend.ts

@@ -48,6 +48,7 @@ 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;
@@ -351,7 +352,7 @@ export class CodexBackend implements ChatBackend {
     dispose(): Promise<void> {
         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. */
@@ -415,6 +416,54 @@ export class CodexBackend implements ChatBackend {
             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);
     }
+
+    private async storeImage(event: Extract<BackendEvent, { type: 'image.generated' }>): Promise<void> {
+        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/src/chat/codex-protocol.ts

@@ -1,3 +1,4 @@
+import { generatedImage } from './generated-image.ts';
 import type { ChatFileChange, ChatQuestion, ChatTurnLimit, UsageWindow } from '@adecore/agent-contracts';
 import { readCodexLimits } from '../usage/limits/normalize.ts';
 import { codexRuntimeMode } from '../providers/codex.ts';
@@ -632,7 +633,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':
@@ -705,6 +706,33 @@ 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);
@@ -775,8 +803,8 @@ export class CodexProtocol {
         return null;
     }
 
-    private text(ref: string, text: string, completed: boolean, events: BackendEvent[]): void {
-        events.push(completed ? { type: 'text.done', ref, text } : { type: 'text.delta', ref, text });
+    private text(ref: string, text: string, completed: boolean, events: BackendEvent[], phase?: string): void {
+        events.push({ type: completed ? 'text.done' : 'text.delta', ref, text, ...(phase === undefined ? {} : { phase }) });
     }
 
     /*

package/src/chat/delta-coalescer.ts

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

package/src/chat/errors.ts

@@ -1,6 +1,8 @@
 import { CodedError } from '../coded-error.ts';
 
 export type ChatErrorCode =
+    | 'refused-query'
+    | 'stale-ui-query'
     | 'history-expired'
     | 'chat-not-found'
     // A record on disk this version cannot read, which is never written over.

package/src/chat/fake-codex.ts

@@ -197,6 +197,40 @@ export function fakeCodexWith(options: FakeCodexOptions): FakeCli {
                 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/src/chat/generated-image.ts

@@ -0,0 +1,88 @@
+import { ChatAttachmentUploadSchema, type ChatAttachmentUpload } from '@adecore/agent-contracts';
+
+interface ImageInfo {
+    mime: string;
+    extension: string;
+    width?: number;
+    height?: number;
+}
+
+function imageInfo(bytes: Buffer): ImageInfo | null {
+    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: string, prompt?: string): { upload: ChatAttachmentUpload; width?: number; height?: number } {
+    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 }) };
+}