@markusylisiurunen/tau 0.3.32 → 0.3.34

package/dist/host/local_session_host.js

@@ -2,9 +2,12 @@ import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { resolvePromptTemplateWithBackend } from "../core/config/index.js";
 import { ChatRuntime } from "../core/runtime/chat_runtime.js";
+import { SUBAGENT_ACTIVITY_FACET_KIND } from "../core/subagents/types.js";
+import { appendUsageLogEntry, getUsageCostTotal, getUsageTotals, } from "../core/usage/logs.js";
 import { filterProjectPathAutocompleteEntries, loadProjectPathAutocompleteEntriesWithBackend, } from "../core/utils/project_files.js";
 import { hasAutoCompactionContinuationMetadata, isTauUserMessageHidden, } from "../core/utils/user_metadata.js";
 import { applySessionProtocolDelta, createSessionProtocolDeltaMessage, createSessionProtocolEphemeralMessage, } from "../protocol/session_protocol.js";
+import { LEGACY_SESSION_CONTEXT_EPOCH } from "../store/session_snapshot_migrations.js";
 import { ClientToolBroker } from "./client_tool_broker.js";
 import { createExecutionEnvironmentSubagentRuntimeResolver } from "./execution_runtime.js";
 import { HostedEphemeralAgentSession } from "./hosted_ephemeral_agent_session.js";
@@ -61,12 +64,20 @@ export class LocalSessionHost {
         try {
             const recovered = normalizeRecoveredSnapshot(snapshot);
             hostedSession = await this.createLocalSessionHandle(executionEnvironment, recovered.snapshot, undefined, recovered.changed);
-            hostedSession.session.restoreState({
-                sessionId: recovered.snapshot.sessionId,
+            const agentRecovery = hostedSession.runtime.restoreState({
+                agentId: recovered.snapshot.sessionId,
+                revision: recovered.snapshot.agentState.revision,
+                contextEpoch: recovered.snapshot.agentState.contextEpoch,
                 historyEntries: recovered.snapshot.messages.flatMap((entry) => entry.modelVisible && isCoreMessage(entry.message)
                     ? [{ id: entry.id, message: entry.message }]
                     : []),
+                ...(recovered.snapshot.agentState.usageCheckpoint
+                    ? { usageCheckpoint: { ...recovered.snapshot.agentState.usageCheckpoint } }
+                    : {}),
             });
+            if (recovered.changed || agentRecovery.recoveredToolResults.length > 0) {
+                await hostedSession.persistRecoveredAgentState(agentRecovery);
+            }
             return hostedSession;
         }
         catch (error) {
@@ -98,10 +109,11 @@ export class LocalSessionHost {
         return this.createLocalSessionHandleFromRuntimeContext(executionEnvironment, runtimeContext, bootstrap, catalog, committedSnapshot, forceNextSnapshotRevision);
     }
     createLocalSessionHandleFromRuntimeContext(executionEnvironment, runtimeContext, bootstrap, catalog, committedSnapshot, forceNextSnapshotRevision = false) {
+        let hostedSession;
         const runtime = ChatRuntime.create({
             persona: bootstrap.persona,
-            toolRegistry: runtimeContext.toolRegistry,
-            clientToolDefinitions: (sessionId) => this.clientToolBroker.getToolDefinitions(sessionId),
+            backend: executionEnvironment.getToolExecutionBackend(),
+            clientTools: (sessionId) => this.clientToolBroker.getToolDefinitions(sessionId),
             modelResolver: bootstrap.modelResolver,
             resolveSubagentRuntime: createExecutionEnvironmentSubagentRuntimeResolver({
                 executionEnvironment,
@@ -110,13 +122,16 @@ export class LocalSessionHost {
             }),
             promptContext: runtimeContext.promptBootstrap.promptContext,
             environment: this.sessionOptions.environment,
+            eventSink: async (event) => await hostedSession.enqueueRuntimeEvent(event),
+            subagentEventSink: async (event) => await hostedSession.recordSubagentEvent(event),
             initialPromptComposition: committedSnapshot
                 ? promptCompositionFromSnapshot(committedSnapshot)
                 : undefined,
-            config: bootstrap.config,
+            config: bootstrap.config ?? {},
+            recordUsage: this.sessionOptions.recordUsage,
             deps: this.sessionOptions.deps,
         });
-        const hostedSession = new LocalHostedSessionHandle(runtime, runtimeContext.promptBootstrap, catalog, bootstrap, this.sessionOptions.includeAgentContext, executionEnvironment, this.store, committedSnapshot, forceNextSnapshotRevision, (session) => this.sessions.delete(session));
+        hostedSession = new LocalHostedSessionHandle(runtime, runtimeContext.promptBootstrap, catalog, bootstrap, this.sessionOptions.includeAgentContext, executionEnvironment, this.store, committedSnapshot, forceNextSnapshotRevision, this.sessionOptions.recordUsage ?? appendUsageLogEntry, (session) => this.sessions.delete(session));
         this.sessions.add(hostedSession);
         return hostedSession;
     }
@@ -304,6 +319,7 @@ class LocalHostedSessionHandle {
     includeAgentContext;
     executionEnvironment;
     store;
+    recordUsage;
     removeFromHost;
     session;
     committedSessionId;
@@ -324,7 +340,6 @@ class LocalHostedSessionHandle {
     ephemeralAgentSessions = new Map();
     pathAutocompleteCache;
     pathAutocompleteLoad;
-    unsubscribeSubagentEvent;
     runtimeEventQueue = Promise.resolve();
     snapshotQueue = Promise.resolve();
     snapshotGeneration = 0;
@@ -337,7 +352,7 @@ class LocalHostedSessionHandle {
     costTotal = 0;
     forceNextSnapshotRevision;
     disposed = false;
-    constructor(runtime, promptBootstrap, catalog, bootstrap, includeAgentContext, executionEnvironment, store, committedSnapshot, forceNextSnapshotRevision = false, removeFromHost = () => { }) {
+    constructor(runtime, promptBootstrap, catalog, bootstrap, includeAgentContext, executionEnvironment, store, committedSnapshot, forceNextSnapshotRevision, recordUsage, removeFromHost = () => { }) {
         this.runtime = runtime;
         this.promptBootstrap = promptBootstrap;
         this.catalog = catalog;
@@ -345,8 +360,9 @@ class LocalHostedSessionHandle {
         this.includeAgentContext = includeAgentContext;
         this.executionEnvironment = executionEnvironment;
         this.store = store;
+        this.recordUsage = recordUsage;
         this.removeFromHost = removeFromHost;
-        this.session = runtime.session;
+        this.session = runtime;
         this.committedSessionId = committedSnapshot?.sessionId ?? this.session.sessionId;
         this.committedSnapshot = committedSnapshot
             ? cloneSessionProtocolSnapshot(committedSnapshot)
@@ -356,9 +372,6 @@ class LocalHostedSessionHandle {
             : undefined;
         this.forceNextSnapshotRevision = forceNextSnapshotRevision;
         this.restoreProtocolState(committedSnapshot);
-        this.unsubscribeSubagentEvent = this.session.onSubagentEvent((event) => {
-            void this.enqueueRuntimeEvent(event).catch(() => undefined);
-        });
     }
     get isTurnRunning() {
         return this.runtime.isTurnRunning;
@@ -386,11 +399,9 @@ class LocalHostedSessionHandle {
     }
     async record(options) {
         this.assertActive();
-        const userHistoryEntryId = this.session.addUserText(options.text, options.historyEntryId ? { historyEntryId: options.historyEntryId } : undefined);
-        const snapshot = await this.commitSnapshot();
-        this.emitSnapshotReset("user-message", snapshot);
+        const userHistoryEntryId = await this.session.commitUserText(options.text, options.historyEntryId ? { historyEntryId: options.historyEntryId } : undefined);
         return {
-            snapshot,
+            snapshot: await this.snapshot(),
             userHistoryEntryId,
         };
     }
@@ -414,14 +425,8 @@ class LocalHostedSessionHandle {
         }
         let lastAssistantMessage;
         try {
-            const result = await this.runtime.runTurn({
-                onEvent: async (event) => {
-                    if (event.type === "assistant_final") {
-                        lastAssistantMessage = event.message;
-                    }
-                    await this.enqueueRuntimeEvent(event);
-                },
-            });
+            const result = await this.runtime.runTurn();
+            lastAssistantMessage = result.finalMessage;
             if (result.aborted && this.draftAssistantMessage) {
                 await this.interruptDraftAssistantMessage();
             }
@@ -469,6 +474,33 @@ class LocalHostedSessionHandle {
         this.assertActive();
         return this.runtime.cancelTurnBoundaryStop();
     }
+    steer(text) {
+        this.assertActive();
+        if (!this.activeTurnPromise) {
+            throw new Error("cannot steer without an active turn");
+        }
+        const submission = this.runtime.steer(text);
+        return {
+            id: submission.id,
+            applied: submission.applied.then(async (association) => {
+                await this.commitSnapshot();
+                return { userHistoryEntryId: association.historyEntryId };
+            }),
+            result: submission.result.then(async (association) => {
+                const turn = turnOutcomeFromResult(association.result, association.result.finalMessage);
+                this.turnOutcomes.set(association.historyEntryId, turn);
+                await this.emitSnapshotResetIfChanged("assistant-message");
+                return {
+                    userHistoryEntryId: association.historyEntryId,
+                    turn,
+                };
+            }),
+        };
+    }
+    cancelSteering() {
+        this.assertActive();
+        return this.runtime.cancelSteering();
+    }
     async exec(options) {
         return await this.runExec(options.execId, options.signal, async (signal) => {
             const backend = this.executionEnvironment.getToolExecutionBackend();
@@ -505,26 +537,32 @@ class LocalHostedSessionHandle {
     }
     async setReasoning(reasoning) {
         this.assertActive();
-        const fromRevision = this.committedSnapshot?.revision;
-        this.runtime.setReasoning(reasoning);
-        this.bootstrap.persona.settings.reasoning = reasoning;
-        const snapshot = await this.commitSnapshot();
-        if (fromRevision === undefined) {
-            this.emitSnapshotReset("configuration", snapshot);
-        }
-        else if (snapshot.revision !== fromRevision) {
-            this.emitDelta(createSessionProtocolDeltaMessage({
-                sessionId: snapshot.sessionId,
-                fromRevision: snapshot.revision - 1,
-                toRevision: snapshot.revision,
-                reason: "configuration",
-                delta: {
-                    type: "snapshot.patch",
-                    changes: [{ type: "settings.set", settings: snapshot.settings }],
-                },
-            }));
-        }
-        return { revision: snapshot.revision, settings: snapshot.settings };
+        const write = this.runtimeEventQueue
+            .catch(() => undefined)
+            .then(async () => {
+            const fromRevision = this.committedSnapshot?.revision;
+            this.runtime.setReasoning(reasoning);
+            this.bootstrap.persona.settings.reasoning = reasoning;
+            const snapshot = await this.commitSnapshot();
+            if (fromRevision === undefined) {
+                this.emitSnapshotReset("configuration", snapshot);
+            }
+            else if (snapshot.revision !== fromRevision) {
+                this.emitDelta(createSessionProtocolDeltaMessage({
+                    sessionId: snapshot.sessionId,
+                    fromRevision,
+                    toRevision: snapshot.revision,
+                    reason: "configuration",
+                    delta: {
+                        type: "snapshot.patch",
+                        changes: [{ type: "settings.set", settings: snapshot.settings }],
+                    },
+                }));
+            }
+            return { revision: snapshot.revision, settings: snapshot.settings };
+        });
+        this.runtimeEventQueue = write.then(() => undefined, () => undefined);
+        return await write;
     }
     async setPersona(personaId) {
         this.assertActive();
@@ -665,29 +703,6 @@ class LocalHostedSessionHandle {
             };
         });
     }
-    async pruneToolResults(options) {
-        return await this.runMaintenance(async (signal) => {
-            const result = await this.session.pruneToolResults({
-                strategy: options.strategy,
-                fraction: options.fraction,
-                ...(options.guidance !== undefined ? { guidance: options.guidance } : {}),
-                signal,
-            });
-            signal.throwIfAborted();
-            this.reconcileProjections({ prunedToolResults: result.prunedToolResults });
-            const snapshot = await this.commitSnapshot();
-            this.emitSnapshotReset("maintenance", snapshot);
-            return {
-                snapshot,
-                message: result.message,
-                noop: result.noop,
-                bashResultsPruned: result.bashResultsPruned,
-                editCallsPruned: result.editCallsPruned,
-                editResultsPruned: result.editResultsPruned,
-                bytesPruned: result.bytesPruned,
-            };
-        });
-    }
     async runMaintenance(operation) {
         this.assertActive();
         return await this.runActiveWork(operation);
@@ -729,22 +744,18 @@ class LocalHostedSessionHandle {
     }
     async rewindToHistoryEntryId(historyEntryId) {
         this.assertActive();
-        const result = this.session.rewindToHistoryEntryId(historyEntryId);
+        const result = await this.session.rewindToHistoryEntryId(historyEntryId);
         if (!result) {
             throw new Error("rewind failed");
         }
-        await this.runtimeEventQueue;
-        this.reconcileProjections({ removeMissingAgents: true });
-        const snapshot = await this.commitSnapshot();
-        this.emitSnapshotReset("maintenance", snapshot);
         return {
-            snapshot,
+            snapshot: await this.snapshot(),
             ...result,
         };
     }
-    async terminateSubagent(subagentId) {
+    async interruptSubagent(subagentId) {
         this.assertActive();
-        return { found: await this.session.terminateSubagent(subagentId) };
+        return { found: await this.session.interruptSubagent(subagentId) };
     }
     async createEphemeralContext(options) {
         this.assertActive();
@@ -753,12 +764,12 @@ class LocalHostedSessionHandle {
             contextId,
             persona: this.runtime.persona,
             config: this.bootstrap.config ?? {},
-            modelResolver: this.bootstrap.modelResolver,
             discoveredSkills: this.bootstrap.discoveredSkills,
             includeAgentContext: this.includeAgentContext,
             executionEnvironment: this.executionEnvironment,
             instructions: options.instructions,
             tools: options.tools,
+            recordUsage: this.recordUsage,
             emitUpdate: (threadId, update) => {
                 this.emitEphemeral(createSessionProtocolEphemeralMessage({
                     sessionId: this.session.sessionId,
@@ -793,7 +804,28 @@ class LocalHostedSessionHandle {
     }
     async snapshot() {
         this.assertActive();
-        return await this.commitSnapshot();
+        return this.runtime.isTurnRunning && this.committedSnapshot
+            ? await this.commitProjectedSnapshot()
+            : await this.commitSnapshot();
+    }
+    async persistRecoveredAgentState(recovery) {
+        this.assertActive();
+        for (const recovered of recovery.recoveredToolResults) {
+            const tool = this.tools.get(recovered.message.toolCallId);
+            if (!tool || tool.status === "streaming") {
+                continue;
+            }
+            this.tools.set(tool.id, tool.status === "queued" || tool.status === "running"
+                ? {
+                    ...tool,
+                    status: "cancelled",
+                    finishedAt: recovered.message.timestamp,
+                    resultMessageId: recovered.historyEntryId,
+                    error: "Tool completion status is unknown after session recovery.",
+                }
+                : { ...tool, resultMessageId: recovered.historyEntryId });
+        }
+        await this.commitSnapshot();
     }
     async dispose() {
         if (!this.disposePromise) {
@@ -815,12 +847,6 @@ class LocalHostedSessionHandle {
             errors.push(error);
         }
         this.disposed = true;
-        try {
-            this.unsubscribeSubagentEvent();
-        }
-        catch (error) {
-            errors.push(error);
-        }
         for (const session of this.ephemeralAgentSessions.values()) {
             try {
                 session.dispose();
@@ -854,10 +880,17 @@ class LocalHostedSessionHandle {
         this.snapshotQueue = write.catch(() => undefined);
         return await write;
     }
-    async commitSnapshotWithRevision(revision) {
+    async commitProjectedSnapshot() {
         const write = this.snapshotQueue
             .catch(() => undefined)
-            .then(() => this.writeSnapshotWithRevision(revision));
+            .then(() => this.writeProjectedSnapshot());
+        this.snapshotQueue = write.catch(() => undefined);
+        return await write;
+    }
+    async commitSnapshotPatch(reason, changes) {
+        const write = this.snapshotQueue
+            .catch(() => undefined)
+            .then(() => this.writeSnapshotPatch(reason, changes));
         this.snapshotQueue = write.catch(() => undefined);
         return await write;
     }
@@ -882,23 +915,47 @@ class LocalHostedSessionHandle {
         }
         return cloneSessionProtocolSnapshot(this.updateCommittedSnapshotAfterWrite(snapshot));
     }
-    async writeSnapshotWithRevision(revision) {
+    async writeProjectedSnapshot() {
         this.assertNotDisposed();
         const generation = this.snapshotGeneration;
-        const draft = this.buildSnapshotDraft();
-        await this.switchSnapshotSession(draft.sessionId);
-        const snapshot = {
-            ...draft,
-            revision,
-        };
+        const current = this.committedSnapshot;
+        if (!current) {
+            return await this.writeSnapshot();
+        }
+        const snapshot = cloneSessionProtocolSnapshot(current);
+        if (this.persistedSnapshot && isDeepStrictEqual(this.persistedSnapshot, snapshot)) {
+            return snapshot;
+        }
         await this.store.commitSessionSnapshot(snapshot, {
             expectedRevision: this.persistedSnapshot?.revision ?? 0,
         });
         this.persistedSnapshot = cloneSessionProtocolSnapshot(snapshot);
         if (generation !== this.snapshotGeneration) {
-            return await this.writeSnapshot();
+            return await this.writeProjectedSnapshot();
         }
-        return cloneSessionProtocolSnapshot(this.updateCommittedSnapshotAfterWrite(snapshot));
+        return cloneSessionProtocolSnapshot(this.committedSnapshot ?? snapshot);
+    }
+    async writeSnapshotPatch(reason, changes) {
+        this.assertNotDisposed();
+        const current = this.committedSnapshot;
+        if (!current) {
+            throw new Error("cannot persist a session patch without a committed snapshot");
+        }
+        const delta = createSessionProtocolDeltaMessage({
+            sessionId: current.sessionId,
+            fromRevision: current.revision,
+            toRevision: current.revision + 1,
+            reason,
+            delta: { type: "snapshot.patch", changes },
+        });
+        const snapshot = applySessionProtocolDelta(current, delta);
+        await this.store.commitSessionSnapshot(snapshot, {
+            expectedRevision: this.persistedSnapshot?.revision ?? 0,
+        });
+        this.persistedSnapshot = cloneSessionProtocolSnapshot(snapshot);
+        this.committedSnapshot = cloneSessionProtocolSnapshot(snapshot);
+        this.snapshotGeneration += 1;
+        return delta;
     }
     async switchSnapshotSession(sessionId) {
         if (this.committedSessionId === sessionId) {
@@ -944,7 +1001,6 @@ class LocalHostedSessionHandle {
             }
         }
         const operationIds = new Set(this.timelineExtras.filter((item) => item.type === "operation").map((item) => item.id));
-        const prunedByToolId = new Map((options.prunedToolResults ?? []).map((result) => [result.toolCallId, result.content]));
         for (const [id, facet] of this.facets) {
             const subjectExists = facet.subject.type === "session" ||
                 (facet.subject.type === "message" && messageIds.has(facet.subject.id)) ||
@@ -953,26 +1009,21 @@ class LocalHostedSessionHandle {
                 (facet.subject.type === "operation" && operationIds.has(facet.subject.id));
             if (!subjectExists) {
                 this.facets.delete(id);
-                continue;
-            }
-            if (facet.subject.type === "tool") {
-                const toolCallId = facet.subject.id;
-                const content = prunedByToolId.get(toolCallId);
-                if (content !== undefined && facet.kind === "tau.tool-ui-events") {
-                    this.facets.set(id, {
-                        ...facet,
-                        data: {
-                            events: [{ type: "tool_pruned", toolCallId, content }],
-                        },
-                    });
-                }
             }
         }
     }
     buildSnapshotDraft() {
         const messages = this.buildProtocolMessages();
+        const agentState = this.session.snapshot();
         return {
             sessionId: this.session.sessionId,
+            agentState: {
+                revision: agentState.revision,
+                contextEpoch: agentState.contextEpoch,
+                ...(agentState.usageCheckpoint
+                    ? { usageCheckpoint: { ...agentState.usageCheckpoint } }
+                    : {}),
+            },
             lifecycle: this.runtime.isTurnRunning ? "running" : "idle",
             costTotal: this.costTotal,
             settings: {
@@ -1113,7 +1164,14 @@ class LocalHostedSessionHandle {
         const { revision, ...current } = this.committedSnapshot;
         return JSON.stringify(current) === JSON.stringify(next) ? revision : revision + 1;
     }
-    enqueueRuntimeEvent(event) {
+    async recordSubagentEvent(event) {
+        const write = this.runtimeEventQueue
+            .catch(() => undefined)
+            .then(() => this.recordSubagentUiEvent(event));
+        this.runtimeEventQueue = write.catch(() => undefined);
+        return await write;
+    }
+    async enqueueRuntimeEvent(event) {
         const write = this.runtimeEventQueue
             .catch(() => undefined)
             .then(() => this.recordRuntimeEvent(event));
@@ -1128,6 +1186,17 @@ class LocalHostedSessionHandle {
         }
         changes.push({ type: "tool.remove", id: tool.id });
     }
+    agentStateChange() {
+        const state = this.session.snapshot();
+        return {
+            type: "agent-state.set",
+            agentState: {
+                revision: state.revision,
+                contextEpoch: state.contextEpoch,
+                ...(state.usageCheckpoint ? { usageCheckpoint: { ...state.usageCheckpoint } } : {}),
+            },
+        };
+    }
     async recordRuntimeEvent(event) {
         switch (event.type) {
             case "assistant_start": {
@@ -1241,44 +1310,116 @@ class LocalHostedSessionHandle {
                 });
                 return;
             }
+            case "user_message":
+                await this.emitPatch("user-message", [
+                    this.agentStateChange(),
+                    {
+                        type: "message.append",
+                        message: {
+                            id: event.historyEntryId,
+                            state: "committed",
+                            modelVisible: true,
+                            message: event.message,
+                        },
+                        timelineItem: timelineItemForMessage(event.historyEntryId),
+                    },
+                ], { persist: true });
+                return;
+            case "history_rewound":
+                this.reconcileProjections({ removeMissingAgents: true });
+                await this.emitSnapshotResetIfChanged("maintenance");
+                return;
             case "assistant_final": {
                 this.draftAssistantMessage = undefined;
-                this.messageStates.delete(event.historyEntryId);
+                const messageState = event.message.stopReason === "aborted" ? "interrupted" : "committed";
+                if (messageState === "committed") {
+                    this.messageStates.delete(event.historyEntryId);
+                }
+                else {
+                    this.messageStates.set(event.historyEntryId, messageState);
+                }
+                const lifecycle = this.runtime.isTurnRunning
+                    ? "running"
+                    : "idle";
                 const toolChanges = this.syncToolRunsFromAssistantMessage(event.historyEntryId, event.message);
-                this.costTotal += event.message.usage?.cost?.total ?? 0;
+                const usage = getUsageTotals(event.message.usage);
+                const cost = getUsageCostTotal(event.message.usage);
+                this.costTotal += cost;
+                this.recordUsage({
+                    timestamp: event.message.timestamp,
+                    sessionId: this.sessionId,
+                    personaId: event.personaId,
+                    provider: event.message.provider,
+                    model: event.message.model,
+                    api: event.message.api,
+                    reasoningEffort: event.reasoningEffort,
+                    usage,
+                    cost: { total: cost },
+                    agent: { type: "main" },
+                });
                 await this.emitPatch("assistant-message", [
+                    this.agentStateChange(),
                     { type: "cost.set", costTotal: this.costTotal },
                     {
                         type: "message.replace",
                         message: {
                             id: event.historyEntryId,
-                            state: "committed",
+                            state: messageState,
                             modelVisible: true,
                             message: event.message,
                         },
                     },
+                    ...(this.committedSnapshot?.lifecycle !== lifecycle
+                        ? [{ type: "lifecycle.set", lifecycle }]
+                        : []),
                     ...toolChanges,
                 ]);
                 return;
             }
+            case "tool_run_queued":
+            case "tool_run_blocked":
+            case "tool_run_started":
+            case "tool_run_finished": {
+                const existing = this.tools.get(event.toolCallId);
+                if (!existing || existing.status === "streaming") {
+                    throw new Error(`missing completed protocol tool run for '${event.toolCallId}'`);
+                }
+                const nextTool = {
+                    ...existing,
+                    status: event.type === "tool_run_queued"
+                        ? "queued"
+                        : event.type === "tool_run_blocked"
+                            ? "blocked"
+                            : event.type === "tool_run_started"
+                                ? "running"
+                                : event.outcome,
+                    ...(event.type === "tool_run_started" || event.type === "tool_run_finished"
+                        ? { startedAt: existing.startedAt ?? event.timestamp }
+                        : {}),
+                    ...(event.type === "tool_run_blocked" || event.type === "tool_run_finished"
+                        ? { finishedAt: event.timestamp }
+                        : {}),
+                };
+                this.tools.set(nextTool.id, nextTool);
+                await this.emitPatch("tool-run", [{ type: "tool.set", tool: structuredClone(nextTool) }]);
+                return;
+            }
             case "tool_result": {
                 const existing = this.tools.get(event.message.toolCallId);
                 if (existing?.status === "streaming") {
                     throw new Error(`tool result arrived before '${event.message.toolCallId}' completed`);
                 }
                 if (existing) {
+                    if (existing.status === "queued" || existing.status === "running") {
+                        throw new Error(`tool result arrived before '${event.message.toolCallId}' finished`);
+                    }
                     const nextTool = {
                         ...existing,
-                        status: existing.status === "blocked"
-                            ? "blocked"
-                            : event.message.isError
-                                ? "failed"
-                                : "succeeded",
-                        finishedAt: event.message.timestamp,
                         resultMessageId: event.historyEntryId,
                     };
                     this.tools.set(nextTool.id, nextTool);
                     await this.emitPatch("tool-result", [
+                        this.agentStateChange(),
                         {
                             type: "message.append",
                             message: {
@@ -1294,6 +1435,7 @@ class LocalHostedSessionHandle {
                     return;
                 }
                 await this.emitPatch("tool-result", [
+                    this.agentStateChange(),
                     {
                         type: "message.append",
                         message: {
@@ -1309,6 +1451,7 @@ class LocalHostedSessionHandle {
             }
             case "tool_recovery": {
                 const changes = [
+                    this.agentStateChange(),
                     {
                         type: "message.append",
                         message: {
@@ -1324,14 +1467,11 @@ class LocalHostedSessionHandle {
                     if (!existing || existing.status === "streaming") {
                         throw new Error(`missing completed protocol tool run for '${toolResult.toolCallId}'`);
                     }
+                    if (existing.status === "queued" || existing.status === "running") {
+                        throw new Error(`tool recovery arrived before '${toolResult.toolCallId}' finished`);
+                    }
                     const nextTool = {
                         ...existing,
-                        status: existing.status === "blocked"
-                            ? "blocked"
-                            : toolResult.isError
-                                ? "failed"
-                                : "succeeded",
-                        finishedAt: toolResult.timestamp,
                     };
                     this.tools.set(nextTool.id, nextTool);
                     changes.push({ type: "tool.set", tool: structuredClone(nextTool) });
@@ -1374,11 +1514,15 @@ class LocalHostedSessionHandle {
                 this.reconcileProjections();
                 await this.emitSnapshotReset("maintenance", await this.commitSnapshot());
                 return;
-            case "tool_ui":
-                await this.recordToolUiEvent(event.uiEvent);
+            case "tool_activity":
+                await this.recordToolUiEvent(event.activity);
                 return;
-            case "subagent_ui":
-                await this.recordSubagentUiEvent(event.event);
+            case "turn_started":
+            case "turn_finished":
+            case "tool_call_admitted":
+            case "model_retry_scheduled":
+            case "model_retry_started":
+            case "usage_checkpoint":
                 return;
         }
     }
@@ -1399,47 +1543,20 @@ class LocalHostedSessionHandle {
             data: { events: [...events, structuredClone(event)] },
         };
         this.facets.set(facet.id, facet);
-        const tool = this.updateToolRunFromUiEvent(existingTool, event);
+        const tool = {
+            ...existingTool,
+            facetIds: existingTool.facetIds.includes(facetId)
+                ? existingTool.facetIds
+                : [...existingTool.facetIds, facetId],
+        };
         this.tools.set(tool.id, tool);
         await this.emitPatch("tool-run", [
             { type: "tool.set", tool },
             { type: "facet.set", facet: structuredClone(facet) },
-        ]);
-    }
-    updateToolRunFromUiEvent(tool, event) {
-        if (tool.status === "streaming") {
-            throw new Error(`tool UI event '${event.type}' arrived before tool call completion`);
-        }
-        const next = {
-            ...tool,
-            facetIds: tool.facetIds.includes(`tool-ui-${tool.toolCallId}`)
-                ? tool.facetIds
-                : [...tool.facetIds, `tool-ui-${tool.toolCallId}`],
-        };
-        if (event.type.endsWith("_started") || event.type === "tool_call_queued") {
-            next.status = event.type === "tool_call_queued" ? "queued" : "running";
-            next.startedAt ??= Date.now();
-        }
-        else if (event.type.endsWith("_blocked")) {
-            next.status = "blocked";
-            next.finishedAt = Date.now();
-        }
-        else if (event.type.endsWith("_finished")) {
-            next.status = "status" in event && event.status === "error" ? "failed" : "succeeded";
-            next.finishedAt = Date.now();
-        }
-        else if (event.type === "bash_aborted") {
-            next.status = "cancelled";
-            next.finishedAt = Date.now();
-        }
-        return next;
+        ], { persist: false });
     }
     async recordSubagentUiEvent(event) {
-        const existing = "id" in event ? this.agents.get(event.id) : this.agents.get(event.state.id);
-        const agent = agentRunFromSubagentEvent(event, existing);
-        if (!agent) {
-            return;
-        }
+        const agent = agentRunFromSubagentEvent(event);
         const previousCost = this.agentCostTotals.get(agent.id) ?? 0;
         this.costTotal += Math.max(0, agent.costTotal - previousCost);
         this.agentCostTotals.set(agent.id, agent.costTotal);
@@ -1447,10 +1564,27 @@ class LocalHostedSessionHandle {
             return;
         }
         this.agents.set(agent.id, agent);
-        await this.emitPatch("agent-run", [
+        const changes = [
             { type: "cost.set", costTotal: this.costTotal },
             { type: "agent.set", agent: structuredClone(agent) },
-        ]);
+        ];
+        const facetId = `subagent-activity-${agent.id}`;
+        if (event.type === "subagent_activity") {
+            const facet = {
+                id: facetId,
+                subject: { type: "agent", id: agent.id },
+                kind: SUBAGENT_ACTIVITY_FACET_KIND,
+                version: 1,
+                data: { text: event.text },
+            };
+            this.facets.set(facet.id, facet);
+            changes.push({ type: "facet.set", facet: structuredClone(facet) });
+        }
+        else if ((event.type === "subagent_run_started" || event.type === "subagent_finished") &&
+            this.facets.delete(facetId)) {
+            changes.push({ type: "facet.remove", id: facetId });
+        }
+        await this.emitPatch("agent-run", changes, event.type === "subagent_activity" ? { persist: false } : {});
     }
     buildAssistantPartialChanges(previousDraft, nextDraft) {
         if (!previousDraft) {
@@ -1476,33 +1610,31 @@ class LocalHostedSessionHandle {
             return;
         }
         if (!this.committedSnapshot) {
+            if (options.persist === false) {
+                const snapshot = { ...this.buildSnapshotDraft(), revision: 1 };
+                this.committedSnapshot = snapshot;
+                this.snapshotGeneration += 1;
+                this.emitSnapshotReset(reason, snapshot);
+                return;
+            }
             const snapshot = await this.commitSnapshot();
             this.emitSnapshotReset(reason, snapshot);
             return;
         }
-        const fromRevision = this.committedSnapshot.revision;
-        const toRevision = fromRevision + 1;
+        if (options.persist !== false) {
+            this.emitDelta(await this.commitSnapshotPatch(reason, changes));
+            return;
+        }
         const delta = createSessionProtocolDeltaMessage({
             sessionId: this.committedSnapshot.sessionId,
-            fromRevision,
-            toRevision,
+            fromRevision: this.committedSnapshot.revision,
+            toRevision: this.committedSnapshot.revision + 1,
             reason,
             delta: { type: "snapshot.patch", changes },
         });
-        if (options.persist === false) {
-            this.committedSnapshot = applySessionProtocolDelta(this.committedSnapshot, delta);
-            this.snapshotGeneration += 1;
-            this.emitDelta(delta);
-            return;
-        }
-        const snapshot = await this.commitSnapshotWithRevision(toRevision);
-        this.emitDelta(createSessionProtocolDeltaMessage({
-            sessionId: delta.sessionId,
-            fromRevision,
-            toRevision: snapshot.revision,
-            reason,
-            delta: { type: "snapshot.patch", changes },
-        }));
+        this.committedSnapshot = applySessionProtocolDelta(this.committedSnapshot, delta);
+        this.snapshotGeneration += 1;
+        this.emitDelta(delta);
     }
     emitSnapshotReset(reason, snapshot) {
         this.emitDelta(createSessionProtocolDeltaMessage({
@@ -1576,27 +1708,7 @@ class LocalHostedSessionHandle {
             return;
         }
         const interruptedMessage = createInterruptedAssistantMessage(draft, this.runtime.persona.model);
-        this.session.addMessage(interruptedMessage, { historyEntryId: draft.id });
-        this.messageStates.set(draft.id, "interrupted");
-        this.draftAssistantMessage = undefined;
-        const changes = [
-            {
-                type: "message.replace",
-                message: {
-                    id: draft.id,
-                    state: "interrupted",
-                    modelVisible: true,
-                    message: interruptedMessage,
-                },
-            },
-            { type: "lifecycle.set", lifecycle: "idle" },
-        ];
-        for (const tool of this.tools.values()) {
-            if (tool.status === "streaming" && tool.origin.messageId === draft.id) {
-                this.removeToolRun(tool, changes);
-            }
-        }
-        await this.emitPatch("assistant-stream", changes);
+        await this.session.commitInterruptedAssistant(interruptedMessage, draft.id);
     }
     async cleanupFailedTurn() {
         if (this.draftAssistantMessage) {
@@ -1610,6 +1722,9 @@ function turnOutcomeFromResult(result, assistantMessage) {
     if (result.blocked) {
         return { status: "blocked", ...result.blocked };
     }
+    if (result.limitReached) {
+        return { status: "failed", stopReason: "error", errorMessage: result.limitReached.message };
+    }
     if (result.aborted || assistantMessage?.stopReason === "aborted") {
         return { status: "aborted", stopReason: "aborted" };
     }
@@ -1688,8 +1803,14 @@ function getAssistantDraftBlockText(message, type) {
 }
 function normalizeRecoveredSnapshot(snapshot) {
     const recovered = cloneSessionProtocolSnapshot(snapshot);
-    let changed = recovered.lifecycle !== "idle";
+    const legacyAgentState = recovered.agentState.contextEpoch === LEGACY_SESSION_CONTEXT_EPOCH;
+    let changed = recovered.lifecycle !== "idle" || legacyAgentState;
     recovered.lifecycle = "idle";
+    if (Object.keys(recovered.agents).length > 0) {
+        changed = true;
+        recovered.agents = {};
+        recovered.facets = Object.fromEntries(Object.entries(recovered.facets).filter(([, facet]) => facet.subject.type !== "agent"));
+    }
     const streamingToolIds = new Set(Object.values(recovered.tools)
         .filter((tool) => tool.status === "streaming")
         .map((tool) => tool.id));
@@ -1698,11 +1819,13 @@ function normalizeRecoveredSnapshot(snapshot) {
         recovered.tools = Object.fromEntries(Object.entries(recovered.tools).filter(([id]) => !streamingToolIds.has(id)));
         recovered.facets = Object.fromEntries(Object.entries(recovered.facets).filter(([, facet]) => facet.subject.type !== "tool" || !streamingToolIds.has(facet.subject.id)));
     }
+    let recoveredAgentHistory = false;
     recovered.messages = recovered.messages.map((message) => {
         if (message.state !== "draft" || message.message.role !== "assistant") {
             return message;
         }
         changed = true;
+        recoveredAgentHistory = true;
         return {
             id: message.id,
             state: "interrupted",
@@ -1710,7 +1833,16 @@ function normalizeRecoveredSnapshot(snapshot) {
             message: createInterruptedAssistantMessageFromModelSnapshot(message, recovered.bootstrap.model),
         };
     });
-    return { snapshot: recovered, changed };
+    if (recoveredAgentHistory) {
+        recovered.agentState = {
+            revision: recovered.agentState.revision + 1,
+            contextEpoch: recovered.agentState.contextEpoch,
+            ...(recovered.agentState.usageCheckpoint
+                ? { usageCheckpoint: { ...recovered.agentState.usageCheckpoint } }
+                : {}),
+        };
+    }
+    return { snapshot: recovered, changed, legacyAgentState };
 }
 function promptCompositionFromSnapshot(snapshot) {
     const systemMessage = snapshot.messages[0];
@@ -1798,48 +1930,8 @@ function createInterruptedAssistantMessageFromModelSnapshot(draft, model) {
         timestamp: draft.message.timestamp,
     };
 }
-function agentRunFromSubagentEvent(event, existing) {
-    const state = event.type === "subagent_spawned" || event.type === "subagent_finished"
-        ? event.state
-        : undefined;
-    if (event.type === "subagent_progress" && existing) {
-        return {
-            ...existing,
-            costTotal: event.costTotal,
-            turns: event.turns,
-            toolCalls: event.toolCalls,
-            usage: { ...event.usage },
-            progress: event.text,
-        };
-    }
-    if (event.type === "subagent_abort_requested" && existing) {
-        return { ...existing, abortRequested: true };
-    }
-    if (!state) {
-        return undefined;
-    }
-    return {
-        id: state.id,
-        name: state.name,
-        title: state.title,
-        status: state.status === "success"
-            ? "succeeded"
-            : state.status === "error"
-                ? "failed"
-                : state.status === "aborted"
-                    ? "cancelled"
-                    : "running",
-        ...(state.modelLabel !== undefined ? { modelLabel: state.modelLabel } : {}),
-        costTotal: state.costTotal,
-        turns: state.turns,
-        toolCalls: state.toolCalls,
-        usage: { ...state.usage },
-        startedAt: state.startedAt,
-        ...(state.finishedAt !== undefined ? { finishedAt: state.finishedAt } : {}),
-        abortRequested: state.abortRequested,
-        ...(state.finalText !== undefined ? { finalText: state.finalText } : {}),
-        ...(state.error !== undefined ? { error: state.error } : {}),
-    };
+function agentRunFromSubagentEvent(event) {
+    return structuredClone(event.state);
 }
 function cloneResolvedBootstrap(bootstrap) {
     return {