@agentshouse/kit 0.2.1-c23b83622c698 → 0.2.1-c23bd93c02c83

package/dist/conversations.js

@@ -1,19 +1,47 @@
 import { client, } from '@agentclientprotocol/sdk';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { unlessAborted } from './abort.js';
-import { killMarked, startAdapter, TURN_ENDED, TURN_STARTED } from './acp.js';
-import { blocksOf, firstChange } from './blocks.js';
+import { startAdapter } from './acp.js';
 import { openBridge } from './bridge.js';
 import { CLIS } from './clis.js';
-import { placeFiles } from './files.js';
+import { answeredFailure, readerFor } from './events.js';
+import { placeFiles, uploadBytes } from './files.js';
 import { agentBase } from './home.js';
 import { instructions } from './instructions.js';
+import { Parts } from './parts.js';
+import { killMarked, Scope } from './scope.js';
 import { holdSecretInput } from './secret-input.js';
 import { createHowWeWork } from './skills.js';
 import { transcribe } from './transcription.js';
+import { workFor } from './work.js';
 const KILLED = 'the conversation was killed';
+const REFUSED = 'the CLI refused the prompt';
+const NO_CONNECTION = "the Kit could not open this conversation's connection";
+const NO_START = "the Agent's CLI did not start";
+const NO_SESSION = "the Agent's CLI did not open a session";
+const NO_RESUME = "the Agent's CLI could not resume this conversation";
+const NO_SETTINGS = "the Agent's CLI refused the Agent's model, mode or effort";
+class NotStarted extends Error {
+}
+async function step(reason, work) {
+    try {
+        return await work;
+    }
+    catch (error) {
+        throw new NotStarted(reason, { cause: error });
+    }
+}
+const EXIT_PLAN_MODE = {
+    parse(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error('_x.ai/exit_plan_mode needs an object');
+        }
+        return value;
+    },
+};
+export const CONVERSATION_INPUTS = new Set(['open', 'message', 'interrupt', 'kill', 'option', 'answer']);
 function causeOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -23,34 +51,44 @@ function answerMessage(request, response) {
 function logged(error) {
     process.stderr.write(`kit: ${causeOf(error)}\n`);
 }
-function stop(bridge) {
-    killMarked(`HOUSE_BRIDGE=${bridge.env.HOUSE_BRIDGE}`);
+function refusal(conversation, error) {
+    if (conversation.kills > 0)
+        return KILLED;
+    const cause = error instanceof NotStarted ? `${error.message}: ${causeOf(error.cause)}` : causeOf(error);
+    logged(new Error(`conversation ${conversation.id} did not start: ${cause}`));
+    return causeOf(error);
+}
+function marker(bridge) {
+    return `HOUSE_BRIDGE=${bridge.env.HOUSE_BRIDGE}`;
 }
 class Turn {
     id = randomUUID();
-    text = '';
-    segment = null;
+    parts;
     admitted = false;
-    notes = [];
-    sent = [];
-    unsentFrom = null;
-    draftSequence = 0;
-    planSequence = 0;
-    entries = null;
     questions = 0;
     secrets = 0;
-    prompt = null;
+    prompted = false;
     ended = false;
+    images = 0;
+    uploads = [];
+    constructor(emit) {
+        this.parts = new Parts(emit);
+    }
 }
 class Conversation {
     id;
     running = null;
+    session = null;
     turn = null;
     commands = null;
-    jobs = new Set();
-    queued = [];
-    late = [];
+    context = null;
+    leftovers = new Set();
+    waiting = [];
+    sending = null;
+    subagents = new Map();
+    held = [];
     opening = null;
+    prompted = null;
     kills = 0;
     killed = new AbortController();
     interrupts = 0;
@@ -77,8 +115,11 @@ export class Conversations {
     questions = new Map();
     carrying = 0;
     reporting = 0;
+    watched = false;
     constructor(kit) {
         this.kit = kit;
+        // A process or a durable schedule ends without a report, so the Kit looks at both again every two seconds.
+        setInterval(() => this.look(), 2_000);
     }
     input(input) {
         this.carrying++;
@@ -88,14 +129,17 @@ export class Conversations {
                 if (input.kind === 'kill') {
                     conversation.kills++;
                     conversation.killed.abort(new Error(KILLED));
+                    for (const waiting of conversation.waiting.splice(0))
+                        waiting.settle({ refused: KILLED });
                     this.halt(conversation);
                 }
                 if (input.kind === 'interrupt') {
                     conversation.interrupts++;
                     conversation.interrupted.abort();
                 }
-                const work = conversation.queue.then(() => this.carry(conversation, input));
-                conversation.queue = work.catch(() => undefined);
+                const handled = conversation.queue.then(() => this.carry(conversation, input));
+                conversation.queue = handled.catch(() => undefined);
+                const work = handled.then(({ ack }) => ack);
                 this.acks.set(input.input_id, work);
                 return work;
             })();
@@ -113,15 +157,39 @@ export class Conversations {
         for (const conversation of this.conversations.values()) {
             const turn = conversation.turn;
             const asking = turn !== null && turn.questions > 0 && turn.secrets === 0;
-            if (conversation.jobs.size > 0 || conversation.open > (asking ? 1 : 0))
+            if (conversation.open > (asking ? 1 : 0))
                 return false;
         }
-        return true;
+        const conversations = [...this.conversations.values()];
+        if (conversations.some((conversation) => conversation.running?.work.busy()))
+            return false;
+        return !conversations.some((conversation) => conversation.running?.scope.working() || [...conversation.leftovers].some((scope) => scope.working()));
+    }
+    quiet() {
+        return this.idle() && [...this.conversations.values()].every((conversation) => conversation.open === 0);
+    }
+    look() {
+        for (const conversation of this.conversations.values()) {
+            for (const scope of conversation.leftovers) {
+                if (!scope.empty())
+                    continue;
+                scope.close();
+                conversation.leftovers.delete(scope);
+            }
+        }
+        this.kit.changed();
     }
     opened() {
+        this.watched = false;
+    }
+    watching(watched) {
+        const resend = watched && !this.watched;
+        this.watched = watched;
+        if (!resend)
+            return;
         for (const conversation of this.conversations.values()) {
             if (conversation.turn !== null)
-                conversation.turn.unsentFrom = 0;
+                this.replay(conversation, conversation.turn);
         }
     }
     conversation(id) {
@@ -134,7 +202,7 @@ export class Conversations {
     }
     async carry(conversation, input) {
         if (input.kind === 'open')
-            return this.open(conversation, input);
+            return { ack: Promise.resolve(await this.open(conversation, input)) };
         if (input.kind === 'message')
             return this.message(conversation, input);
         if (input.kind === 'interrupt') {
@@ -144,6 +212,7 @@ export class Conversations {
         }
         if (input.kind === 'kill') {
             await this.kill(conversation);
+            await conversation.sending;
             if (--conversation.kills === 0)
                 conversation.killed = new AbortController();
         }
@@ -152,54 +221,91 @@ export class Conversations {
         if (input.kind === 'answer') {
             const question = this.questions.get(String(input.interaction_id));
             if (question === undefined) {
-                return this.message(conversation, { ...input, text: answerMessage(input.request, input.response), files: [], first: false });
+                const text = answerMessage(input.request, input.response);
+                return this.message(conversation, { ...input, text, files: [], first: false });
             }
             question.answer(input.response);
         }
-        return {};
+        return { ack: Promise.resolve({}) };
     }
     async open(conversation, input) {
         if (conversation.running !== null)
             return {};
         try {
-            return { provider_session_id: await this.start(conversation, await this.route(conversation, input.agent_id), null) };
+            return { provider_session_id: await this.start(conversation, await this.route(conversation, input.agent_id), null, true) };
         }
         catch (error) {
-            return { refused: causeOf(error) };
+            return { refused: refusal(conversation, error) };
         }
     }
     async message(conversation, input) {
-        let ack = {};
-        const prompt = [];
+        const content = [{ type: 'text', text: String(input.text) }];
+        let route;
         try {
-            const route = await this.route(conversation, input.agent_id);
+            route = await this.route(conversation, input.agent_id);
             const files = input.files;
             const paths = await placeFiles(this.kit.house, route.working_directory, files, conversation.killed.signal);
             const lines = await this.transcribed(conversation, files, paths);
+            if (lines.length > 0)
+                content.push({ type: 'text', text: lines.join('\n') });
+            if (conversation.kills > 0)
+                throw new Error(KILLED);
+        }
+        catch (error) {
+            return { ack: Promise.resolve({ refused: refusal(conversation, error) }) };
+        }
+        return {
+            ack: new Promise((settle) => {
+                conversation.waiting.push({ input, route, content, settle });
+                this.next(conversation);
+            }),
+        };
+    }
+    next(conversation) {
+        if (conversation.sending !== null || conversation.open > 0)
+            return;
+        const waiting = conversation.waiting.shift();
+        if (waiting === undefined)
+            return;
+        conversation.sending = this.send(conversation, waiting).finally(() => {
+            conversation.sending = null;
+            this.next(conversation);
+        });
+    }
+    async send(conversation, waiting) {
+        const { input } = waiting;
+        let ack = {};
+        let started = false;
+        const prompt = [];
+        try {
             if (conversation.running === null) {
-                const opened = await this.start(conversation, route, input.provider_session_id);
-                if (input.provider_session_id === null)
-                    ack = { provider_session_id: opened };
+                const stored = conversation.session ?? input.provider_session_id;
+                const empty = input.first === true && conversation.prompted !== stored;
+                started = (await this.start(conversation, waiting.route, stored, empty)) !== stored;
+            }
+            const session = conversation.running.sessionId;
+            if (started || (input.first === true && session !== input.provider_session_id)) {
+                ack = { provider_session_id: session };
             }
             if (input.first === true) {
                 prompt.push({
                     type: 'text',
-                    text: await instructions(conversation.running.bridge, route.base_instructions, await this.kit.copies.mapping()),
+                    text: await instructions(conversation.running.bridge, waiting.route.base_instructions, await this.kit.copies.mapping()),
                 });
             }
-            prompt.push({ type: 'text', text: String(input.text) });
-            if (lines.length > 0)
-                prompt.push({ type: 'text', text: lines.join('\n') });
             if (conversation.kills > 0)
                 throw new Error(KILLED);
         }
         catch (error) {
-            if ('provider_session_id' in ack)
+            if (started) {
+                conversation.session = null;
                 await this.kill(conversation);
-            return { refused: conversation.kills > 0 ? KILLED : causeOf(error) };
+            }
+            waiting.settle({ refused: refusal(conversation, error) });
+            return;
         }
-        this.prompt(conversation, prompt);
-        return ack;
+        this.prompt(conversation, [...prompt, ...waiting.content]);
+        waiting.settle(ack);
     }
     async transcribed(conversation, files, paths) {
         const lines = [];
@@ -209,7 +315,7 @@ export class Conversations {
                 continue;
             try {
                 const text = await transcribe(path, AbortSignal.any([conversation.killed.signal, conversation.interrupted.signal]));
-                if (text !== '')
+                if (text !== null && text !== '')
                     lines.push(`Transcript: ${text}`);
             }
             catch (error) {
@@ -229,11 +335,13 @@ export class Conversations {
     }
     halt(conversation) {
         if (conversation.opening !== null)
-            stop(conversation.opening);
+            killMarked(marker(conversation.opening));
+        for (const scope of conversation.leftovers)
+            scope.kill();
         if (conversation.running === null)
             return;
         conversation.running.killed = true;
-        stop(conversation.running.bridge);
+        conversation.running.scope.kill();
     }
     async kill(conversation) {
         const running = conversation.running;
@@ -245,6 +353,7 @@ export class Conversations {
         if (running === null)
             return;
         try {
+            running.reader.requested(option, value);
             const answered = await running.adapter.connection.agent.request('session/set_config_option', {
                 sessionId: running.sessionId,
                 configId: option,
@@ -253,6 +362,7 @@ export class Conversations {
             this.options(conversation, answered.configOptions);
         }
         catch (error) {
+            running.reader.refused(option);
             logged(error);
         }
     }
@@ -269,41 +379,46 @@ export class Conversations {
         }
         return route;
     }
-    async start(conversation, route, sessionId) {
+    async start(conversation, route, sessionId, empty) {
+        const reader = readerFor(route.kind);
+        reader.session = sessionId;
         const app = client({ name: '@agentshouse/kit' })
-            .onNotification('session/update', ({ params }) => this.update(conversation, params))
-            .onNotification(TURN_STARTED, (params) => params, () => void this.started(conversation))
-            .onNotification(TURN_ENDED, (params) => params, () => this.ended(conversation))
             .onRequest('session/request_permission', ({ params, signal }) => this.ask(conversation, 'session/request_permission', params, false, signal))
-            .onRequest('elicitation/create', ({ params, signal }) => this.ask(conversation, 'elicitation/create', params, asksSecret(params), signal));
+            .onRequest('elicitation/create', ({ params, signal }) => this.ask(conversation, 'elicitation/create', params, asksSecret(params), signal))
+            .onRequest('_x.ai/exit_plan_mode', EXIT_PLAN_MODE, ({ params, signal }) => this.ask(conversation, '_x.ai/exit_plan_mode', params, false, signal));
         const cli = await unlessAborted(this.kit.agents.cli(route.kind), conversation.killed.signal);
-        const bridge = await openBridge(this.kit.house, this.kit.copies, conversation.id, conversation.killed.signal);
+        const bridge = await step(NO_CONNECTION, openBridge(this.kit.house, this.kit.copies, conversation.id, conversation.killed.signal));
         if (conversation.kills > 0) {
             bridge.close();
             throw new Error(KILLED);
         }
         conversation.opening = bridge;
+        const work = workFor(route.kind, route.working_directory, () => this.kit.changed());
+        const scope = new Scope(marker(bridge), randomUUID(), cli);
         try {
             await unlessAborted(createHowWeWork(bridge), conversation.killed.signal);
-            await CLIS[route.kind].allowHouse();
-            const adapter = await startAdapter(route.kind, cli, route.working_directory, app, (job) => this.job(conversation, job), bridge.env);
+            await CLIS[route.kind].allowHouse(bridge.env.PATH);
+            const streamed = await step(NO_CONNECTION, work.open(cli));
+            const adapter = await step(NO_START, startAdapter(route.kind, cli, route.working_directory, app, (message) => {
+                work.read(message);
+                this.read(conversation, reader, message);
+            }, { ...bridge.env, ...streamed }, undefined, scope));
             void adapter.exited.then(() => bridge.close());
             const agent = adapter.connection.agent;
             const cwd = route.working_directory;
-            const _meta = CLIS[route.kind].sessionMeta;
-            const opened = sessionId === null
-                ? await agent.request('session/new', { cwd, mcpServers: [], _meta })
-                : { ...(await agent.request('session/resume', { sessionId, cwd, mcpServers: [], _meta })), sessionId };
-            const running = {
-                adapter,
-                bridge,
-                sessionId: opened.sessionId,
-                killed: false,
-                queues: CLIS[route.kind].queues,
-                phase: CLIS[route.kind].phase,
-            };
-            const options = await this.launchSettings(running, route, opened.configOptions ?? []);
+            const _meta = CLIS[route.kind].sessionMeta(bridge.env.HOUSE_BRIDGE, conversation.id);
+            const resumed = sessionId === null ? null : await this.resume(conversation, route.kind, adapter, { sessionId, cwd, mcpServers: [], _meta }, empty);
+            const opened = resumed ?? (await step(NO_SESSION, agent.request('session/new', { cwd, mcpServers: [], _meta })));
+            reader.session = opened.sessionId;
+            if (opened.sessionId !== sessionId && CLIS[route.kind].renames) {
+                const prompt = [{ type: 'text', text: `/rename ${conversation.id}` }];
+                await step(NO_SESSION, agent.request('session/prompt', { sessionId: opened.sessionId, prompt }));
+            }
+            const running = { adapter, bridge, sessionId: opened.sessionId, killed: false, reader, work, scope };
+            const options = await step(NO_SETTINGS, this.launchSettings(running, route, opened.configOptions ?? []));
+            void work.settled().then(() => scope.record());
             conversation.running = running;
+            conversation.session = running.sessionId;
             this.kit.send({ type: 'process', conversation_id: conversation.id, running: true });
             if (conversation.commands !== null)
                 this.commands(conversation, conversation.commands);
@@ -312,7 +427,9 @@ export class Conversations {
             return running.sessionId;
         }
         catch (error) {
-            stop(bridge);
+            scope.kill();
+            work.close();
+            conversation.leftovers.add(scope);
             bridge.close();
             throw conversation.kills > 0 ? new Error(KILLED) : error;
         }
@@ -320,6 +437,18 @@ export class Conversations {
             conversation.opening = null;
         }
     }
+    async resume(conversation, kind, adapter, request, empty) {
+        try {
+            return { ...(await adapter.connection.agent.request('session/resume', request)), sessionId: request.sessionId };
+        }
+        catch (error) {
+            if (!empty || conversation.kills > 0 || !CLIS[kind].unknownSession(error)) {
+                throw new NotStarted(NO_RESUME, { cause: error });
+            }
+            logged(new Error(`conversation ${conversation.id} opens a new session: ${NO_RESUME}: ${causeOf(error)}`));
+            return null;
+        }
+    }
     async launchSettings(running, route, offered) {
         let options = offered;
         const settings = [
@@ -331,6 +460,7 @@ export class Conversations {
             if (value === null)
                 continue;
             const option = options.find((candidate) => candidate.category === category);
+            running.reader.requested(option?.id ?? category, value);
             const answered = await running.adapter.connection.agent.request('session/set_config_option', {
                 sessionId: running.sessionId,
                 configId: option?.id ?? category,
@@ -344,19 +474,23 @@ export class Conversations {
         const running = conversation.running;
         if (running?.adapter !== adapter)
             return;
+        this.detach(conversation, running);
+        if (conversation.turn !== null) {
+            this.end(conversation, conversation.turn, { failed: running.killed ? KILLED : cause });
+        }
+        this.next(conversation);
+        this.kit.changed();
+    }
+    detach(conversation, running) {
+        running.work.close();
+        conversation.leftovers.add(running.scope);
         conversation.running = null;
         conversation.commands = null;
-        conversation.jobs.clear();
-        conversation.queued.length = 0;
         for (const [id, question] of this.questions) {
             if (question.conversation === conversation)
                 this.questions.delete(id);
         }
         this.kit.send({ type: 'process', conversation_id: conversation.id, running: false });
-        if (conversation.turn !== null) {
-            this.end(conversation, conversation.turn, { failed: running.killed ? KILLED : cause });
-        }
-        this.kit.changed();
     }
     commands(conversation, commands) {
         conversation.commands = commands;
@@ -371,7 +505,7 @@ export class Conversations {
     }
     deliver(conversation, turn, event, body) {
         this.reporting++;
-        const delivered = conversation.reports.then(() => this.kit.house.deliver(`/kit/conversations/${conversation.id}/turns/${turn.id}/${event}`, body));
+        const delivered = conversation.reports.then(async () => this.kit.house.deliver(`/kit/conversations/${conversation.id}/turns/${turn.id}/${event}`, await body));
         conversation.reports = delivered
             .catch(() => undefined)
             .finally(() => {
@@ -380,120 +514,89 @@ export class Conversations {
         });
         return delivered;
     }
-    report(conversation) {
-        const turn = new Turn();
-        conversation.open++;
-        void this.deliver(conversation, turn, 'started', {})
-            .then(() => this.admitted(conversation, turn))
-            .catch(logged);
-        return turn;
+    write(conversation, turn, operation) {
+        if (!turn.admitted || turn.ended || !this.watched)
+            return;
+        this.kit.send({ type: 'turn', conversation_id: conversation.id, turn_id: turn.id, ...operation });
     }
-    admitted(conversation, turn) {
-        turn.admitted = true;
-        for (const note of turn.notes.splice(0))
-            this.kit.send(note);
-        turn.unsentFrom = 0;
-        this.draft(conversation, turn);
-        if (turn.entries !== null)
-            this.plan(conversation, turn);
+    replay(conversation, turn) {
+        for (const operation of turn.parts.operations())
+            this.write(conversation, turn, operation);
     }
     begin(conversation) {
-        const turn = this.report(conversation);
+        const turn = new Turn((operation) => this.write(conversation, turn, operation));
+        conversation.open++;
+        void this.deliver(conversation, turn, 'started', {})
+            .then(() => {
+            turn.admitted = true;
+            this.replay(conversation, turn);
+        })
+            .catch(logged);
         conversation.turn = turn;
+        if (conversation.context !== null)
+            turn.parts.measure(conversation.context);
+        for (const part of conversation.held.splice(0))
+            turn.parts.start(part);
         this.kit.changed();
         return turn;
     }
-    finish(conversation, turn) {
-        if (turn.ended)
-            return;
-        const segment = turn.segment;
-        turn.segment = null;
-        if (segment?.phase === 'note')
-            this.note(conversation, turn, segment.text);
-        else if (segment !== null)
-            this.answer(conversation, turn, segment.text);
-        this.end(conversation, turn, { text: turn.text });
-    }
-    end(conversation, turn, outcome) {
+    end(conversation, turn, failed, notice = null) {
         if (turn.ended)
             return;
+        if (conversation.turn === turn) {
+            for (const event of conversation.running?.reader.closeTurn() ?? [])
+                this.apply(conversation, turn, event);
+        }
+        if (notice !== null)
+            turn.parts.start({ type: 'marker', marker: 'retry', text: notice });
         turn.ended = true;
         conversation.open--;
         if (conversation.turn === turn)
             conversation.turn = null;
-        void this.deliver(conversation, turn, 'ended', outcome).catch(logged);
-        const late = conversation.open === 0 ? conversation.late.shift() : undefined;
-        if (late !== undefined)
-            this.failed(conversation, late);
+        const body = Promise.allSettled(turn.uploads).then(() => ({
+            parts: turn.parts.saved(),
+            context: turn.parts.context,
+            ...failed,
+        }));
+        void this.deliver(conversation, turn, 'ended', body).catch(logged);
+        this.next(conversation);
         this.kit.changed();
     }
-    failed(conversation, cause) {
-        if (conversation.open > 0)
-            conversation.late.push(cause);
-        else
-            this.end(conversation, this.report(conversation), { failed: cause });
-    }
     prompt(conversation, prompt) {
         const running = conversation.running;
-        const sent = { turn: null };
-        if (running.queues && (conversation.turn !== null || conversation.queued.length > 0)) {
-            conversation.queued.push(sent);
-        }
-        else {
-            this.attach(conversation.turn ?? this.begin(conversation), sent);
-        }
-        running.adapter.connection.agent.request('session/prompt', { sessionId: running.sessionId, prompt }).then(() => this.answered(conversation, sent, null), async (error) => {
-            if (!running.adapter.connection.signal.aborted) {
-                this.answered(conversation, sent, causeOf(error));
-                if (conversation.open === 0 && conversation.running === running)
-                    stop(running.bridge);
+        const turn = this.begin(conversation);
+        turn.prompted = true;
+        conversation.prompted = running.sessionId;
+        running.adapter.connection.agent.request('session/prompt', { sessionId: running.sessionId, prompt }).then((answer) => {
+            const notice = answeredFailure(answer);
+            const failed = notice ?? (answer.stopReason === 'refusal' ? REFUSED : null);
+            this.end(conversation, turn, failed === null ? null : { failed }, notice);
+        }, async (error) => {
+            if (running.adapter.connection.signal.aborted) {
+                this.end(conversation, turn, { failed: running.killed ? KILLED : await running.adapter.exited });
             }
-            else if (sent.turn !== null) {
-                this.end(conversation, sent.turn, { failed: running.killed ? KILLED : await running.adapter.exited });
+            else {
+                if (conversation.open === 1 && conversation.running === running) {
+                    running.scope.kill();
+                    this.detach(conversation, running);
+                }
+                this.end(conversation, turn, { failed: causeOf(error) });
             }
         });
     }
-    attach(turn, sent) {
-        turn.prompt = sent;
-        sent.turn = turn;
-    }
-    answered(conversation, sent, failed) {
-        const turn = sent.turn;
-        if (turn === null) {
-            const queued = conversation.queued.indexOf(sent);
-            if (queued < 0)
-                return;
-            conversation.queued.splice(queued, 1);
-            if (failed !== null)
-                this.failed(conversation, failed);
-        }
-        else if (failed !== null) {
-            if (turn.ended)
-                this.failed(conversation, failed);
-            else
-                this.end(conversation, turn, { failed });
-        }
-        else if (turn.prompt === sent) {
-            this.finish(conversation, turn);
-        }
-    }
     started(conversation) {
-        if (conversation.turn !== null)
-            return conversation.turn;
-        const turn = this.begin(conversation);
-        const queued = conversation.queued.shift();
-        if (queued !== undefined)
-            this.attach(turn, queued);
-        return turn;
+        return conversation.turn ?? this.begin(conversation);
     }
     ended(conversation) {
         const turn = conversation.turn;
         if (turn === null)
             return;
-        if (turn.prompt === null) {
-            this.finish(conversation, turn);
+        if (!turn.prompted) {
+            this.end(conversation, turn, null);
         }
         else {
+            for (const event of conversation.running?.reader.closeTurn() ?? [])
+                this.apply(conversation, turn, event);
             conversation.turn = null;
             this.kit.changed();
         }
@@ -542,101 +645,102 @@ export class Conversations {
         if (content !== null)
             this.questions.get(interactionId)?.answer({ action: 'accept', content });
     }
-    update(conversation, notification) {
-        const update = notification.update;
-        if (update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text') {
-            this.chunk(conversation, this.started(conversation), update, update.content.text);
-        }
-        else if (update.sessionUpdate === 'plan') {
-            const turn = this.started(conversation);
-            this.close(conversation, turn);
-            turn.entries = update.entries;
-            this.plan(conversation, turn);
-        }
-        else if (update.sessionUpdate === 'tool_call') {
-            this.close(conversation, this.started(conversation));
-        }
-        else if (update.sessionUpdate === 'agent_thought_chunk') {
-            const turn = this.started(conversation);
-            if (turn.segment?.messageId !== (update.messageId ?? null))
-                this.close(conversation, turn);
-        }
-        else if (update.sessionUpdate === 'available_commands_update') {
-            this.commands(conversation, update.availableCommands);
-        }
-        else if (update.sessionUpdate === 'config_option_update') {
-            this.options(conversation, update.configOptions);
-        }
+    read(conversation, reader, message) {
+        for (const event of reader.read(message))
+            this.event(conversation, event);
     }
-    job(conversation, job) {
-        if (job.running)
-            conversation.jobs.add(job.id);
-        else
-            conversation.jobs.delete(job.id);
-        this.kit.changed();
+    event(conversation, event) {
+        switch (event.kind) {
+            case 'started':
+                this.started(conversation);
+                return;
+            case 'ended':
+                this.ended(conversation);
+                return;
+            case 'commands':
+                this.commands(conversation, event.commands);
+                return;
+            case 'options':
+                this.options(conversation, event.options);
+                return;
+            case 'context':
+                conversation.context = { used: event.used, window: event.window };
+                conversation.turn?.parts.measure(conversation.context);
+                return;
+            case 'subagent-done':
+                this.subagentDone(conversation, event.id, event.result);
+                return;
+            case 'marker':
+            case 'image':
+                if (conversation.turn !== null)
+                    break;
+                if (event.kind === 'marker' && event.marker === 'job')
+                    conversation.held.push({ type: 'marker', marker: 'job', text: event.text });
+                return;
+        }
+        this.apply(conversation, this.started(conversation), event);
     }
-    chunk(conversation, turn, chunk, text) {
-        const phase = conversation.running?.phase(chunk) ?? null;
-        const messageId = chunk.messageId ?? null;
-        if (turn.segment?.messageId !== messageId || turn.segment.phase !== phase)
-            this.close(conversation, turn);
-        if (phase === 'answer') {
-            this.answer(conversation, turn, text);
-            return;
+    apply(conversation, turn, event) {
+        switch (event.kind) {
+            case 'text':
+            case 'reasoning':
+                turn.parts.write(event.kind, event.id, event.text);
+                return;
+            case 'command':
+                turn.parts.command();
+                return;
+            case 'subagent': {
+                const index = turn.parts.start({ type: 'subagent', description: event.description, status: 'running', result: null });
+                conversation.subagents.set(event.id, { description: event.description, turn, index });
+                return;
+            }
+            case 'message':
+                turn.parts.start({ type: 'message', command: event.command, target: event.target });
+                return;
+            case 'marker':
+                turn.parts.start({ type: 'marker', marker: event.marker, text: event.text });
+                return;
+            case 'plan':
+                turn.parts.plan(event.entries);
+                return;
+            case 'image':
+                turn.uploads.push(this.image(conversation, turn, turn.parts.reserve(), event.data, event.mediaType));
+                this.kit.changed();
+                return;
         }
-        turn.segment ??= { messageId, phase, text: '' };
-        turn.segment.text += text;
     }
-    close(conversation, turn) {
-        const segment = turn.segment;
-        if (segment === null)
+    subagentDone(conversation, id, result) {
+        const subagent = conversation.subagents.get(id);
+        if (subagent === undefined)
             return;
-        turn.segment = null;
-        this.note(conversation, turn, segment.text);
-    }
-    note(conversation, turn, text) {
-        if (text.trim() === '')
+        conversation.subagents.delete(id);
+        if (subagent.turn === conversation.turn) {
+            subagent.turn.parts.done(subagent.index, result);
             return;
-        const note = { type: 'working-note', conversation_id: conversation.id, note_id: randomUUID(), text };
-        if (turn.admitted)
-            this.kit.send(note);
+        }
+        const part = { type: 'subagent', description: subagent.description, status: 'done', result };
+        if (conversation.turn === null)
+            conversation.held.push(part);
         else
-            turn.notes.push(note);
-    }
-    answer(conversation, turn, text) {
-        turn.text += text;
-        this.draft(conversation, turn);
-    }
-    draft(conversation, turn) {
-        const blocks = blocksOf(turn.text);
-        const from = Math.min(firstChange(turn.sent, blocks), turn.unsentFrom ?? Infinity);
-        const sent = this.kit.send({
-            type: 'draft',
-            conversation_id: conversation.id,
-            turn_id: turn.id,
-            sequence: turn.draftSequence + 1,
-            from,
-            blocks: blocks.slice(from),
-        });
-        if (sent) {
-            turn.draftSequence++;
-            turn.sent = blocks;
-            turn.unsentFrom = null;
+            conversation.turn.parts.start(part);
+    }
+    async image(conversation, turn, reserved, data, mediaType) {
+        const bytes = Buffer.from(data, 'base64');
+        const name = `image-${++turn.images}.${mediaType.split('/')[1]}`;
+        try {
+            const declared = (await this.deliver(conversation, turn, 'images', {
+                name,
+                media_type: mediaType,
+                bytes: bytes.length,
+                sha256: createHash('sha256').update(bytes).digest('hex'),
+            }));
+            const saved = declared.upload === undefined ? declared : await uploadBytes(declared.upload, bytes);
+            if (saved.save.status !== 'saved')
+                throw new Error(saved.save.failure ?? saved.save.status);
+            turn.parts.arrive({ type: 'image', file: saved.version, name, media_type: mediaType }, reserved);
         }
-        else {
-            turn.unsentFrom = from;
+        catch (error) {
+            turn.parts.arrive({ type: 'marker', marker: 'retry', text: `${name} was not saved: ${causeOf(error)}` }, reserved);
         }
     }
-    plan(conversation, turn) {
-        const sent = this.kit.send({
-            type: 'plan',
-            conversation_id: conversation.id,
-            turn_id: turn.id,
-            sequence: turn.planSequence + 1,
-            from: 0,
-            steps: turn.entries.map((entry) => ({ label: entry.content, priority: entry.priority, status: entry.status })),
-        });
-        if (sent)
-            turn.planSequence++;
-    }
 }