@adecore/agents 0.23.1 → 0.24.1

package/src/chat/chat-session.ts

@@ -1,15 +1,16 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import type {
     ChatAttachment,
-    ChatAssistantItem,
     ChatCheckpointDiff,
     ChatEvent,
+    ChatGoalAction,
     ChatInfo,
     ChatItem,
     ChatQueuedMessage,
     ChatQuoteSource,
     ChatSkill,
     ChatSubagentItem,
+    ChatToolItem,
     ChatTurnItem,
     ChatUiAnswer,
     ChatUiChoiceOrigin,
@@ -18,10 +19,8 @@ import type {
     ModelSelection,
     RuntimeMode
 } from '@adecore/agent-contracts';
-import { GeneratedImageInputSchema, notResumedNote } from '@adecore/agent-contracts';
-import { resolveUiChoice, UI_FENCE_LANGUAGE, UiFailure, uiHasFence, uiMayReferenceHost } from '@adecore/intelligent-ui';
-import type { UiCompileOptions } from '@adecore/intelligent-ui/compiler';
-import { UiStream, type UiStreamPreview } from '@adecore/intelligent-ui/stream';
+import { HOST_TASK_ORIGIN, notResumedNote } from '@adecore/agent-contracts';
+import { resolveUiChoice, UI_FENCE_LANGUAGE, UiFailure } from '@adecore/intelligent-ui';
 import type { ChatProvider } from '../providers/provider.ts';
 import type { LimitsUpdate } from '../usage/limits/normalize.ts';
 import type { BackendEvent, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
@@ -34,6 +33,7 @@ import { isMainAgentOutput, ThreadProjector } from './projector.ts';
 import { readableAssistantText } from './readable-text.ts';
 import type { SubagentSettlement } from './subagent-settlement.ts';
 import { ChatThread } from './thread.ts';
+import { UiReplies, type UiReplyHost } from './ui-replies.ts';
 import { errorText } from '../error-text.ts';
 import { systemClock, type OutboxClock } from '../outbox/outbox-worker.ts';
 
@@ -84,10 +84,7 @@ export interface ChatSessionOptions {
     checkpoints?: TurnCheckpoints;
     // The info string of the host's UI fences; `UI_FENCE_LANGUAGE` without one.
     uiFenceLanguage?: string;
-    ui?: {
-        schemas: UiCompileOptions['querySchemas'];
-        observe(item: ChatAssistantItem, final: boolean): void;
-    };
+    ui?: UiReplyHost;
     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;
@@ -117,8 +114,6 @@ export interface LimitResumeHooks {
 
 // Claude Code names a session about six seconds after its first prompt, and a first turn can run for minutes.
 const TITLE_RECHECK_MS = 10_000;
-// Longer than any fence line or the name of a tag a scan looks for, so a match never falls between two deltas.
-const UI_SCAN_OVERLAP = 64;
 
 export interface ChatSendExtras {
     uiChoice?: ChatUiChoiceOrigin;
@@ -206,40 +201,35 @@ 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>();
     private readonly capturedUiAccess: Map<string, unknown>;
-    // How much of a streaming reply's text the fence and host scans already covered, so a delta scans only its tail.
-    private readonly uiScanned = new Map<string, number>();
-    private readonly uiReferencing = new Set<string>();
-    private readonly uiAttachments = new Map<string | null, string | undefined>();
-    private readonly uiFenceLanguage: string;
+    private readonly uiReplies: UiReplies;
 
     constructor(options: ChatSessionOptions) {
         this.options = options;
-        this.uiFenceLanguage = options.uiFenceLanguage ?? UI_FENCE_LANGUAGE;
         this.pendingPreambles = options.preambles ?? [];
         this.capturedUiAccess = new Map(Object.entries(options.uiAccess ?? {}));
         this.thread = new ChatThread(options.info, options.items);
         this.projector = new ThreadProjector(this.thread, { providerName: options.provider.name });
+        this.uiReplies = new UiReplies({
+            thread: this.thread,
+            fenceLanguage: options.uiFenceLanguage ?? UI_FENCE_LANGUAGE,
+            clock: options.clock ?? systemClock,
+            ...(options.ui ? { host: options.ui } : {}),
+            emit: (event) => options.emit(event),
+            repair: (note) => {
+                if (!this.pendingPreambles.includes(note)) {
+                    this.pendingPreambles = [...this.pendingPreambles, note];
+                }
+            }
+        });
     }
 
     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;
+        return this.uiReplies.previews();
     }
 
     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;
-        });
+        return this.uiReplies.previewItems(items);
     }
 
     get id(): string {
@@ -267,7 +257,37 @@ export class ChatSession {
     get busy(): boolean {
         const turnId = this.thread.info.activeTurnId;
         const turn = turnId ? this.thread.get(turnId) : undefined;
-        return turnId !== null && (turn?.kind !== 'turn' || turn.origin !== 'agent');
+        // A turn the CLI opened toward a goal is the goal's own: a message waits for it like for any turn of the person's.
+        return turnId !== null && (turn?.kind !== 'turn' || turn.origin !== 'agent' || this.goalWorks());
+    }
+
+    /* Whether the CLI works toward a goal, which goes on in turns of its own until the goal is met, paused or cleared. */
+    private goalWorks(): boolean {
+        return this.thread.info.goal?.status === 'active';
+    }
+
+    /*
+     * Pauses, resumes or clears the chat's goal. A CLI with calls for it takes them at once, even while a goal
+     * turn runs; resuming an idle goal and clearing a goal of a CLI without them go out as `/goal` in a turn of
+     * their own, which a goal turn still running is in the way of.
+     */
+    async goal(action: ChatGoalAction): Promise<void> {
+        const supported = this.options.provider.capabilities.goals;
+        if (supported === undefined || (supported === 'command' && action !== 'clear')) {
+            throw new ChatError('chat-unsupported', `${this.options.provider.name} cannot ${action} a goal`);
+        }
+        if (this.thread.info.goal === undefined) {
+            throw new ChatError('goal-not-found', 'This chat has no goal');
+        }
+        const backend = this.backend;
+        if (supported === 'native' && backend?.goal && backend.running && (action !== 'resume' || this.busy)) {
+            await backend.goal(action);
+            return;
+        }
+        if (this.busy) {
+            throw new ChatError('chat-busy', 'Stop the turn that works toward the goal first');
+        }
+        this.send(`/goal ${action}`);
     }
 
     /* The next process uses these settings; live work keeps the process it started in. */
@@ -456,6 +476,8 @@ export class ChatSession {
             extras.delivery !== 'steer' ||
             this.info.queuePaused ||
             text.startsWith('/') ||
+            // A goal runs as turns of its own; a message waits for the one running instead of joining it.
+            this.goalWorks() ||
             !this.busy ||
             !turnId ||
             !backend?.steerTurn ||
@@ -599,6 +621,10 @@ export class ChatSession {
     private dispatch(text: string, extras: ChatSendExtras, requestedTurnId?: string): void {
         this.pauseQueue(false);
         this.settleAgentTurn();
+        // A goal that was met has said what it had to; the next message of the person leaves it behind.
+        if (this.thread.info.goal?.status === 'complete') {
+            this.emit([this.thread.patchInfo({ goal: undefined })]);
+        }
         const { preamble, note } = this.contextNote(text);
         // 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);
@@ -723,6 +749,22 @@ export class ChatSession {
         return true;
     }
 
+    /*
+     * Marks the chat as waiting on a person for something the host asks beside the CLI, such as a
+     * card a verb holds its call for. The chat reads `needs-you` until every key is released.
+     */
+    holdForPerson(key: string): void {
+        if (this.thread.hold(key)) {
+            this.emit([this.thread.setStatus(this.thread.statusFor(this.thread.info.activeTurnId))]);
+        }
+    }
+
+    releaseHold(key: string): void {
+        if (this.thread.release(key) && this.thread.info.status === 'needs-you') {
+            this.emit([this.thread.setStatus(this.thread.statusFor(this.thread.info.activeTurnId))]);
+        }
+    }
+
     /*
      * Starts the chat over: the CLI goes, and the next send starts one without a session to resume.
      * The thread resets at once; the returned promise lets the host wait for pending attachment
@@ -759,6 +801,7 @@ export class ChatSession {
                 queuePaused: false,
                 background: [],
                 delegating: undefined,
+                goal: undefined,
                 effectiveRuntimeMode: undefined,
                 permissionMode: undefined,
                 slashCommands: [],
@@ -1149,7 +1192,7 @@ export class ChatSession {
             const settled =
                 item.kind === 'turn' && item.state === 'running'
                     ? { ...item, state: 'aborted' as const, endedAt: now }
-                    : item.kind === 'subagent' && item.origin !== 'ruimte' && item.status === 'running'
+                    : item.kind === 'subagent' && item.origin !== HOST_TASK_ORIGIN && item.status === 'running'
                       ? { ...item, status: 'failed' as const, finishedAt: now }
                       : settleStoredItem(item, null);
             if (settled !== item) {
@@ -1174,9 +1217,30 @@ export class ChatSession {
         this.options.persist();
     }
 
+    /*
+     * Ends the CLI and keeps the conversation: the next message starts a fresh process that resumes it,
+     * and with it the skills, plugins and servers the CLI reads at its start. Refused while a turn runs or
+     * the process still holds work, a request or a background command, since those would end with it.
+     */
+    restart(): Promise<void> {
+        if (this.thread.info.activeTurnId !== null || this.processInUse()) {
+            throw new ChatError('chat-busy', `Chat ${this.id} is still working; stop it before restarting its agent session`);
+        }
+        this.clearStartWarning();
+        this.clearWorkflowWarnings();
+        const backend = this.backend;
+        this.backend = null;
+        this.starting = null;
+        this.launchedSelection = null;
+        // What the init frame of the process that goes announced; a skill added since would be filtered out by it.
+        this.emit([this.thread.patchInfo({ running: false, effectiveRuntimeMode: undefined, permissionMode: undefined, skills: undefined })]);
+        this.options.persist();
+        return backend?.dispose() ?? Promise.resolve();
+    }
+
     /* Ends the process and stops listening to it, as the host goes down; the thread stays as it is. */
     freeze(): void {
-        this.clearUi();
+        this.uiReplies.clear();
         this.clearStartWarning();
         this.clearWorkflowWarnings();
         this.frozen = true;
@@ -1185,7 +1249,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.uiReplies.clear();
         this.clearStartWarning();
         this.clearWorkflowWarnings();
         if (this.titleTimer !== null) {
@@ -1351,7 +1415,9 @@ export class ChatSession {
     /* Marks every running subagent of the CLI's own as stopped, for a person stopping the turn together with them. */
     markSubagentsStopped(): void {
         this.markStopped(
-            this.thread.list().filter((item): item is ChatSubagentItem => item.kind === 'subagent' && item.status === 'running' && item.origin !== 'ruimte')
+            this.thread
+                .list()
+                .filter((item): item is ChatSubagentItem => item.kind === 'subagent' && item.status === 'running' && item.origin !== HOST_TASK_ORIGIN)
         );
     }
 
@@ -1650,7 +1716,7 @@ export class ChatSession {
     }
 
     private processInUse(): boolean {
-        return this.hasNativeWork() || this.thread.pending().length > 0 || this.awaitingBackgroundReport;
+        return this.hasNativeWork() || this.thread.pending().length > 0 || this.awaitingBackgroundReport || this.goalWorks();
     }
 
     private replacementWaits(): boolean {
@@ -1696,6 +1762,7 @@ export class ChatSession {
             saveGeneratedImage: this.options.saveGeneratedImage,
             instructions: this.options.instructions?.() ?? null,
             resumeNote: this.options.resumeNote?.() ?? null,
+            ...(info.goal === undefined ? {} : { goal: info.goal }),
             ...(folders.length > 0 ? { folders } : {}),
             ...(this.options.spawn ? { spawn: this.options.spawn } : {})
         };
@@ -1822,7 +1889,7 @@ export class ChatSession {
         }
         this.emit(projected);
         this.trackSubagentOwner(generation, event);
-        this.watchWorkflows(event);
+        this.watchWorkflows(generation, event);
         if (isMainAgentOutput(event)) {
             this.spokenTurnId = this.thread.info.activeTurnId;
         }
@@ -1892,56 +1959,58 @@ export class ChatSession {
         this.workflowWarnings.clear();
     }
 
-    private watchWorkflows(event: BackendEvent): void {
-        if (
-            !['tool.started', 'tool.progress', 'tool.output', 'tool.done', 'workflow.progress', 'task.started', 'task.done', 'exit', 'failed'].includes(
-                event.type
-            )
-        ) {
+    private watchWorkflows(generation: number, event: BackendEvent): void {
+        if (event.type === 'tool.output' || event.type === 'tool.progress') {
+            // These come by the thousand, and only the call they name can be a workflow they move.
+            const item = this.projector.itemOf(generation, event.ref);
+            if (item?.kind === 'tool' && item.name === 'Workflow') {
+                this.watchWorkflow(item, true);
+            }
+            return;
+        }
+        if (!['tool.started', 'tool.done', 'workflow.progress', 'task.started', 'task.done', 'exit', 'failed'].includes(event.type)) {
             return;
         }
-        const clock = this.options.clock ?? systemClock;
         const ref = 'ref' in event ? event.ref : null;
         for (const item of this.thread.list()) {
-            if (item.kind !== 'tool' || item.name !== 'Workflow') {
-                continue;
-            }
-            const existing = this.workflowWarnings.get(item.id);
-            const progress =
-                ref === item.toolUseId &&
-                ['workflow.progress', 'tool.started', 'tool.progress', 'tool.output', 'tool.done', 'task.started'].includes(event.type);
-            if (item.state !== 'running' || progress) {
-                if (existing !== undefined) {
-                    clock.clearTimeout(existing);
-                    this.workflowWarnings.delete(item.id);
-                }
-            }
-            if (item.state !== 'running' || (!progress && existing !== undefined) || (!progress && item.workflow?.stalledAt !== undefined)) {
-                continue;
+            if (item.kind === 'tool' && item.name === 'Workflow') {
+                this.watchWorkflow(item, ref === item.toolUseId && ['workflow.progress', 'tool.started', 'tool.done', 'task.started'].includes(event.type));
             }
-            if (progress) {
-                this.emit([
-                    this.thread.upsert({
-                        ...item,
-                        workflow: { name: null, phases: [], agents: [], ...item.workflow, lastProgressAt: clock.now(), stalledAt: undefined }
-                    })
-                ]);
+        }
+    }
+
+    private watchWorkflow(item: ChatToolItem, progress: boolean): void {
+        const clock = this.options.clock ?? systemClock;
+        const existing = this.workflowWarnings.get(item.id);
+        if (item.state !== 'running' || progress) {
+            if (existing !== undefined) {
+                clock.clearTimeout(existing);
+                this.workflowWarnings.delete(item.id);
             }
-            this.workflowWarnings.set(
-                item.id,
-                clock.setTimeout(() => {
-                    this.workflowWarnings.delete(item.id);
-                    const current = this.thread.get(item.id);
-                    if (this.frozen || current?.kind !== 'tool' || current.state !== 'running') {
-                        return;
-                    }
-                    this.emit([
-                        this.thread.upsert({ ...current, workflow: { name: null, phases: [], agents: [], ...current.workflow, stalledAt: clock.now() } })
-                    ]);
-                    this.options.persist();
-                }, 5 * 60_000)
-            );
         }
+        if (item.state !== 'running' || (!progress && existing !== undefined) || (!progress && item.workflow?.stalledAt !== undefined)) {
+            return;
+        }
+        if (progress) {
+            this.emit([
+                this.thread.upsert({
+                    ...item,
+                    workflow: { name: null, phases: [], agents: [], ...item.workflow, lastProgressAt: clock.now(), stalledAt: undefined }
+                })
+            ]);
+        }
+        this.workflowWarnings.set(
+            item.id,
+            clock.setTimeout(() => {
+                this.workflowWarnings.delete(item.id);
+                const current = this.thread.get(item.id);
+                if (this.frozen || current?.kind !== 'tool' || current.state !== 'running') {
+                    return;
+                }
+                this.emit([this.thread.upsert({ ...current, workflow: { name: null, phases: [], agents: [], ...current.workflow, stalledAt: clock.now() } })]);
+                this.options.persist();
+            }, 5 * 60_000)
+        );
     }
 
     /* Whether the CLI that reports was started on a pick standing for the same window as the chat's own. */
@@ -2050,129 +2119,9 @@ export class ChatSession {
 
     private emit(events: ChatEvent[]): void {
         const delegating = this.delegatingChange(events);
-        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.
-     */
-    private unscannedUiText(item: ChatAssistantItem, whole: boolean): string {
-        const scanned = whole ? 0 : (this.uiScanned.get(item.id) ?? 0);
-        this.uiScanned.set(item.id, item.text.length);
-        if (scanned === 0 || scanned > item.text.length) {
-            return item.text;
-        }
-        const line = item.text.lastIndexOf('\n', scanned - 1) + 1;
-        const from = Math.max(line, scanned - UI_SCAN_OVERLAP);
-        return from === line ? item.text.slice(from) : `\0${item.text.slice(from)}`;
-    }
-
-    private forgetUiScan(item: ChatAssistantItem): void {
-        if (!item.streaming) {
-            this.uiScanned.delete(item.id);
-            this.uiReferencing.delete(item.id);
-        }
-    }
-
-    /* Looked up once per turn, and again only after one of its tool calls changed. */
-    private latestUiAttachment(turnId: string | null): string | undefined {
-        if (this.uiAttachments.has(turnId)) {
-            return this.uiAttachments.get(turnId);
-        }
-        const attachment = this.findUiAttachment(turnId);
-        this.uiAttachments.set(turnId, attachment);
-        return attachment;
-    }
-
-    private findUiAttachment(turnId: string | null): string | undefined {
-        for (const item of this.thread.list().toReversed()) {
-            if (item.kind !== 'tool' || item.turnId !== turnId || item.name !== 'ImageGeneration' || item.state !== 'done') {
-                continue;
-            }
-            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();
+        for (const event of delegating === null ? events : [...events, delegating]) {
+            this.uiReplies.pass(event);
         }
-        this.uiStreams.clear();
-        this.uiCompiled.clear();
-        this.uiScanned.clear();
-        this.uiReferencing.clear();
-        this.uiAttachments.clear();
     }
 
     /* Said on the info as well as by the rows, since a client with the thread closed sees only the info. */

package/src/chat/chat-store.ts

@@ -1,5 +1,5 @@
 import { mkdirSync } from 'node:fs';
-import { mkdir, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { mkdir, open, readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { ChatInfoSchema, ChatItemSchema, type ChatInfo, type ChatItem } from '@adecore/agent-contracts';
 import { z } from 'zod';
@@ -57,6 +57,7 @@ function logName(chatId: string): string {
     return `${encodeURIComponent(chatId)}.log`;
 }
 
+// `settled` reads the info from the head of the record, so it stays the first key.
 function recordBody(
     info: ChatInfo,
     items: ChatItem[],
@@ -223,6 +224,19 @@ export class ChatStore {
         return (await this.readSnapshot(chatId)) === UNREADABLE;
     }
 
+    /*
+     * Whether the chat has neither a turn in flight nor a resume after a limit, by the info its record
+     * starts with and the last one its log wrote, without parsing the thread. False whenever that
+     * cannot be told so cheaply, which leaves the decision to `read`.
+     */
+    async settled(chatId: string): Promise<boolean> {
+        if (!settledInfo(await leadingInfo(join(this.dir, recordFileName(chatId))))) {
+            return false;
+        }
+        const last = lastLoggedInfo((await readOrNull(this.logPath(chatId))) ?? '');
+        return last === undefined || settledInfo(last);
+    }
+
     private async readSnapshot(chatId: string): Promise<z.infer<typeof RecordSchema> | typeof UNREADABLE | null> {
         const raw = await readOrNull(join(this.dir, recordFileName(chatId)));
         if (raw === null) {
@@ -253,6 +267,95 @@ export class ChatStore {
 
 const UNREADABLE = Symbol('unreadable');
 
+const RECORD_HEAD = Buffer.from('{"info":{');
+const HEAD_CHUNK_BYTES = 16384;
+const QUOTE = 0x22;
+const BACKSLASH = 0x5c;
+const OPEN_BRACE = 0x7b;
+const CLOSE_BRACE = 0x7d;
+
+/*
+ * The info a record starts with, read only as far as it goes; undefined for a record that is missing,
+ * starts otherwise (an older or hand-edited one) or ends before its info does. Scanning bytes is safe
+ * in UTF-8, where no byte of a multibyte character equals a quote, a backslash or a brace.
+ */
+async function leadingInfo(path: string): Promise<unknown> {
+    let handle: Awaited<ReturnType<typeof open>>;
+    try {
+        handle = await open(path, 'r');
+    } catch (e) {
+        if (isNotFound(e)) {
+            return undefined;
+        }
+        throw e;
+    }
+    try {
+        let head = Buffer.alloc(0);
+        let at = RECORD_HEAD.length;
+        let depth = 1;
+        let inString = false;
+        let escaped = false;
+        const chunk = Buffer.alloc(HEAD_CHUNK_BYTES);
+        let { bytesRead } = await handle.read(chunk, 0, chunk.length, 0);
+        while (bytesRead > 0) {
+            head = Buffer.concat([head, chunk.subarray(0, bytesRead)]);
+            if (!head.subarray(0, RECORD_HEAD.length).equals(RECORD_HEAD.subarray(0, Math.min(head.length, RECORD_HEAD.length)))) {
+                return undefined;
+            }
+            for (; at < head.length; at++) {
+                const byte = head[at]!;
+                if (escaped) {
+                    escaped = false;
+                } else if (inString) {
+                    escaped = byte === BACKSLASH;
+                    inString = byte !== QUOTE;
+                } else if (byte === QUOTE) {
+                    inString = true;
+                } else if (byte === OPEN_BRACE) {
+                    depth += 1;
+                } else if (byte === CLOSE_BRACE) {
+                    depth -= 1;
+                    if (depth === 0) {
+                        return parseOrUndefined(head.subarray(RECORD_HEAD.length - 1, at + 1).toString('utf8'));
+                    }
+                }
+            }
+            ({ bytesRead } = await handle.read(chunk, 0, chunk.length, head.length));
+        }
+        return undefined;
+    } finally {
+        await handle.close();
+    }
+}
+
+/* The info of the last info or reset line in a log, unvalidated; undefined when no line carries one. */
+function lastLoggedInfo(raw: string): unknown {
+    const lines = raw.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        // Most lines are items and deltas, which are larger and never carry this key.
+        if (!lines[i]!.includes('"info"')) {
+            continue;
+        }
+        const event = (parseOrUndefined(lines[i]!) as { event?: { type?: unknown; info?: unknown } } | null | undefined)?.event;
+        if (event?.type === 'info' || event?.type === 'reset') {
+            return event.info;
+        }
+    }
+    return undefined;
+}
+
+function settledInfo(info: unknown): boolean {
+    return typeof info === 'object' && info !== null && (info as { activeTurnId?: unknown }).activeTurnId === null && !('resumeAt' in info);
+}
+
+function parseOrUndefined(text: string): unknown {
+    try {
+        return JSON.parse(text);
+    } catch {
+        return undefined;
+    }
+}
+
 async function exists(path: string): Promise<boolean> {
     try {
         await stat(path);