@markusylisiurunen/tau 0.3.37 → 0.3.39

package/dist/host/local_session_host.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { resolvePromptTemplateWithBackend } from "../core/config/index.js";
+import { assistantHistoryEntries, toolHistoryEntry, userHistoryEntry, } from "../core/history/transcript.js";
 import { ChatRuntime } from "../core/runtime/chat_runtime.js";
 import { formatSteeringUserMessage } from "../core/runtime/steering.js";
 import { buildGoalContinuationText, prependGoalPolicy } from "../core/session/goal.js";
@@ -15,17 +16,22 @@ import { createExecutionEnvironmentSubagentRuntimeResolver } from "./execution_r
 import { HostedEphemeralAgentSession } from "./hosted_ephemeral_agent_session.js";
 import { SessionExecBusyError, SessionRetryUnavailableError, } from "./session_host.js";
 const PATH_AUTOCOMPLETE_CACHE_TTL_MS = 5_000;
+const HISTORY_UNAVAILABLE_NOTICE_ID = "notice-history-unavailable";
 export class LocalSessionHost {
     sessions = new Set();
     sessionRecoveryPromises = new Map();
     store;
+    history;
+    historyRemote;
     clientToolBroker = new ClientToolBroker();
     sessionOptions;
     shutdownPromise;
     shuttingDown = false;
     constructor(options) {
-        const { store, ...sessionOptions } = options;
+        const { store, history, historyRemote, ...sessionOptions } = options;
         this.store = store;
+        this.history = history;
+        this.historyRemote = historyRemote;
         this.sessionOptions = sessionOptions;
     }
     registerClientTools(options) {
@@ -108,9 +114,9 @@ export class LocalSessionHost {
             agentContextFiles: bootstrap.config?.agentContextFiles ?? [],
         });
         const catalog = createContentCatalogSnapshot(bootstrap);
-        return this.createLocalSessionHandleFromRuntimeContext(executionEnvironment, runtimeContext, bootstrap, catalog, committedSnapshot, forceNextSnapshotRevision);
+        return this.createLocalSessionHandleFromRuntimeContext(executionEnvironment, runtimeContext, bootstrap, catalog, committedSnapshot, createParams, forceNextSnapshotRevision);
     }
-    createLocalSessionHandleFromRuntimeContext(executionEnvironment, runtimeContext, bootstrap, catalog, committedSnapshot, forceNextSnapshotRevision = false) {
+    async createLocalSessionHandleFromRuntimeContext(executionEnvironment, runtimeContext, bootstrap, catalog, committedSnapshot, createParams, forceNextSnapshotRevision = false) {
         let hostedSession;
         const runtime = ChatRuntime.create({
             persona: bootstrap.persona,
@@ -131,6 +137,7 @@ export class LocalSessionHost {
                 createGoal: async (objective) => await hostedSession.createGoal(objective),
                 updateGoal: async (update) => await hostedSession.updateGoal(update),
             },
+            history: this.history.query(this.historyRemote),
             initialPromptComposition: committedSnapshot
                 ? promptCompositionFromSnapshot(committedSnapshot)
                 : undefined,
@@ -138,7 +145,18 @@ export class LocalSessionHost {
             recordUsage: this.sessionOptions.recordUsage,
             deps: this.sessionOptions.deps,
         });
-        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));
+        const attributes = committedSnapshot?.attributes ?? createParams?.attributes;
+        if (!attributes) {
+            throw new Error("session attributes are required");
+        }
+        const createdAt = committedSnapshot?.createdAt ?? this.sessionOptions.environment.now();
+        hostedSession = new LocalHostedSessionHandle(runtime, runtimeContext.promptBootstrap, catalog, bootstrap, this.sessionOptions.includeAgentContext, executionEnvironment, this.store, this.history, this.historyRemote, attributes, createdAt, committedSnapshot, forceNextSnapshotRevision, this.sessionOptions.recordUsage ?? appendUsageLogEntry, (session) => this.sessions.delete(session));
+        const historyFailure = this.history.registerSession({
+            sessionId: committedSnapshot?.sessionId ?? hostedSession.sessionId,
+            attributes,
+            createdAt,
+        }, this.historyRemote);
+        await hostedSession.recordHistoryFailure(historyFailure);
         this.sessions.add(hostedSession);
         return hostedSession;
     }
@@ -295,6 +313,13 @@ export class LocalSessionHost {
             }
         }
         this.sessions.clear();
+        await this.history.flush();
+        try {
+            this.history.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
         if (errors.length > 0) {
             throw new AggregateError(errors, "failed to shut down local session host");
         }
@@ -326,6 +351,10 @@ class LocalHostedSessionHandle {
     includeAgentContext;
     executionEnvironment;
     store;
+    history;
+    historyRemote;
+    attributes;
+    createdAt;
     recordUsage;
     removeFromHost;
     session;
@@ -347,9 +376,7 @@ class LocalHostedSessionHandle {
     ephemeralAgentSessions = new Map();
     pathAutocompleteCache;
     pathAutocompleteLoad;
-    runtimeEventQueue = Promise.resolve();
-    snapshotQueue = Promise.resolve();
-    snapshotGeneration = 0;
+    mutationQueue = Promise.resolve();
     activeWorkAbortControllers = new Set();
     activeWorkPromises = new Set();
     activeExecAbortControllers = new Map();
@@ -362,7 +389,7 @@ class LocalHostedSessionHandle {
     pendingGoalCommit;
     forceNextSnapshotRevision;
     disposed = false;
-    constructor(runtime, promptBootstrap, catalog, bootstrap, includeAgentContext, executionEnvironment, store, committedSnapshot, forceNextSnapshotRevision, recordUsage, removeFromHost = () => { }) {
+    constructor(runtime, promptBootstrap, catalog, bootstrap, includeAgentContext, executionEnvironment, store, history, historyRemote, attributes, createdAt, committedSnapshot, forceNextSnapshotRevision, recordUsage, removeFromHost = () => { }) {
         this.runtime = runtime;
         this.promptBootstrap = promptBootstrap;
         this.catalog = catalog;
@@ -370,6 +397,10 @@ class LocalHostedSessionHandle {
         this.includeAgentContext = includeAgentContext;
         this.executionEnvironment = executionEnvironment;
         this.store = store;
+        this.history = history;
+        this.historyRemote = historyRemote;
+        this.attributes = attributes;
+        this.createdAt = createdAt;
         this.recordUsage = recordUsage;
         this.removeFromHost = removeFromHost;
         this.session = runtime;
@@ -447,8 +478,10 @@ class LocalHostedSessionHandle {
     async startGoal(objective) {
         const goal = this.buildNewGoal(objective);
         return await this.runLogicalTurn(async (logicalTurn) => {
-            this.goal = goal;
-            this.pendingGoalCommit = goal;
+            await this.enqueueMutation(() => {
+                this.goal = goal;
+                this.pendingGoalCommit = goal;
+            });
             try {
                 const { userHistoryEntryId } = await this.record({
                     text: prependGoalPolicy(goal.objective, goal),
@@ -466,8 +499,10 @@ class LocalHostedSessionHandle {
             }
             catch (error) {
                 if (this.pendingGoalCommit === goal) {
-                    this.goal = null;
-                    this.pendingGoalCommit = undefined;
+                    await this.enqueueMutation(() => {
+                        this.goal = null;
+                        this.pendingGoalCommit = undefined;
+                    });
                 }
                 else {
                     await this.blockActiveGoal().catch(() => undefined);
@@ -527,6 +562,9 @@ class LocalHostedSessionHandle {
         if (userMessage && hasGoalTurnMetadata(userMessage.message)) {
             throw new SessionRetryUnavailableError("goal-controlled turns cannot be retried; resume a blocked goal or start a new goal");
         }
+        if (!userMessage || !(await this.session.prepareRetry(userMessage.id))) {
+            throw new SessionRetryUnavailableError("no user turn is available to retry");
+        }
         return await this.runTurn();
     }
     async runLogicalTurn(execute) {
@@ -549,7 +587,7 @@ class LocalHostedSessionHandle {
                 this.rejectBufferedLogicalSteering(logicalTurn, new Error("steering was not applied before the logical turn ended"));
                 this.activeTurnPromise = undefined;
                 this.activeLogicalTurn = undefined;
-                await this.emitSnapshotResetIfChanged("assistant-message");
+                await this.enqueueSnapshotResetIfChanged("assistant-message");
             }
         }
     }
@@ -584,20 +622,22 @@ class LocalHostedSessionHandle {
                 }
                 const initialOutcome = turnOutcomeFromResult(result, result.finalMessage);
                 const terminalOutcome = turnOutcomeFromResult(terminalResult, terminalResult.finalMessage);
-                this.turnOutcomes.set(userMessage.id, initialOutcome);
-                for (const steering of committedSteering) {
-                    this.turnOutcomes.set(steering.historyEntryId, initialOutcome);
-                }
-                if (this.goal?.status === "active") {
-                    goalRootHistoryEntryId ??= rootUserMessage.id;
-                }
-                if (goalRootHistoryEntryId) {
-                    this.turnOutcomes.set(goalRootHistoryEntryId, terminalOutcome);
-                }
-                if (terminalOutcome.status !== "completed") {
-                    await this.blockActiveGoal();
-                }
-                await this.emitSnapshotResetIfChanged("assistant-message");
+                await this.enqueueMutation(async () => {
+                    this.turnOutcomes.set(userMessage.id, initialOutcome);
+                    for (const steering of committedSteering) {
+                        this.turnOutcomes.set(steering.historyEntryId, initialOutcome);
+                    }
+                    if (this.goal?.status === "active") {
+                        goalRootHistoryEntryId ??= rootUserMessage.id;
+                    }
+                    if (goalRootHistoryEntryId) {
+                        this.turnOutcomes.set(goalRootHistoryEntryId, terminalOutcome);
+                    }
+                    if (terminalOutcome.status !== "completed" && this.goal?.status === "active") {
+                        this.goal = { ...this.goal, status: "blocked" };
+                    }
+                    await this.emitSnapshotResetIfChanged("assistant-message");
+                });
                 this.resolveCommittedLogicalSteering(committedSteering, initialOutcome);
                 if (logicalTurn.cancellationRequested) {
                     return await this.cancelLogicalTurn(rootUserMessage.id);
@@ -612,8 +652,7 @@ class LocalHostedSessionHandle {
             }
             catch (error) {
                 this.rejectCommittedLogicalSteering(committedSteering, error);
-                await this.cleanupFailedTurn().catch(() => undefined);
-                await this.blockActiveGoal().catch(() => undefined);
+                await this.cleanupFailedTurn(rootUserMessage.id, committedSteering, error).catch(() => undefined);
                 throw error;
             }
         }
@@ -645,7 +684,7 @@ class LocalHostedSessionHandle {
             ...(this.activeTurnPromise ? [this.activeTurnPromise] : []),
             ...this.activeWorkPromises,
         ]);
-        await this.runtimeEventQueue;
+        await this.mutationQueue;
     }
     requestTurnBoundaryStop() {
         this.assertActive();
@@ -731,9 +770,7 @@ class LocalHostedSessionHandle {
     }
     async setReasoning(reasoning) {
         this.assertActive();
-        const write = this.runtimeEventQueue
-            .catch(() => undefined)
-            .then(async () => {
+        return await this.enqueueMutation(async () => {
             const fromRevision = this.committedSnapshot?.revision;
             this.runtime.setReasoning(reasoning);
             this.bootstrap.persona.settings.reasoning = reasoning;
@@ -755,8 +792,6 @@ class LocalHostedSessionHandle {
             }
             return { revision: snapshot.revision, settings: snapshot.settings };
         });
-        this.runtimeEventQueue = write.then(() => undefined, () => undefined);
-        return await write;
     }
     async setPersona(personaId) {
         this.assertActive();
@@ -774,23 +809,25 @@ class LocalHostedSessionHandle {
             includeAgentContext: this.includeAgentContext,
             agentContextFiles: runtimeConfig.config.agentContextFiles ?? [],
         });
-        this.runtime.setRuntimeConfig(runtimeConfig.config, runtimeConfig.bootstrap.modelResolver.resolveModel);
-        this.runtime.updatePromptContext(runtimeContext.promptBootstrap.promptContext);
-        this.runtime.setPersona(selectedPersona, {
-            skillsBlock: runtimeContext.promptBootstrap.promptContext.skillsBlock,
+        return await this.enqueueMutation(async () => {
+            this.runtime.setRuntimeConfig(runtimeConfig.config, runtimeConfig.bootstrap.modelResolver.resolveModel);
+            this.runtime.updatePromptContext(runtimeContext.promptBootstrap.promptContext);
+            this.runtime.setPersona(selectedPersona, {
+                skillsBlock: runtimeContext.promptBootstrap.promptContext.skillsBlock,
+            });
+            this.bootstrap = {
+                persona: clonePersona(selectedPersona),
+                discoveredSkills: structuredClone(runtimeConfig.skills),
+                personas: personas.map(clonePersona),
+                prompts: structuredClone(runtimeConfig.prompts),
+                modelResolver: runtimeConfig.bootstrap.modelResolver.resolveModel,
+                config: runtimeConfig.config,
+            };
+            this.catalog = createContentCatalogSnapshot(this.bootstrap);
+            const snapshot = await this.commitSnapshot();
+            this.emitSnapshotReset("configuration", snapshot);
+            return snapshot;
         });
-        this.bootstrap = {
-            persona: clonePersona(selectedPersona),
-            discoveredSkills: structuredClone(runtimeConfig.skills),
-            personas: personas.map(clonePersona),
-            prompts: structuredClone(runtimeConfig.prompts),
-            modelResolver: runtimeConfig.bootstrap.modelResolver.resolveModel,
-            config: runtimeConfig.config,
-        };
-        this.catalog = createContentCatalogSnapshot(this.bootstrap);
-        const snapshot = await this.commitSnapshot();
-        this.emitSnapshotReset("configuration", snapshot);
-        return snapshot;
     }
     async reload() {
         this.assertActive();
@@ -808,32 +845,34 @@ class LocalHostedSessionHandle {
             includeAgentContext: this.includeAgentContext,
             agentContextFiles: runtimeConfig.config.agentContextFiles ?? [],
         });
-        this.runtime.setRuntimeConfig(runtimeConfig.config, runtimeConfig.bootstrap.modelResolver.resolveModel);
-        this.runtime.updatePromptContext(runtimeContext.promptBootstrap.promptContext);
-        this.runtime.setPersona(nextPersona, {
-            skillsBlock: runtimeContext.promptBootstrap.promptContext.skillsBlock,
+        return await this.enqueueMutation(async () => {
+            this.runtime.setRuntimeConfig(runtimeConfig.config, runtimeConfig.bootstrap.modelResolver.resolveModel);
+            this.runtime.updatePromptContext(runtimeContext.promptBootstrap.promptContext);
+            this.runtime.setPersona(nextPersona, {
+                skillsBlock: runtimeContext.promptBootstrap.promptContext.skillsBlock,
+            });
+            this.bootstrap = {
+                persona: clonePersona(nextPersona),
+                discoveredSkills: structuredClone(runtimeConfig.skills),
+                personas: personas.map(clonePersona),
+                prompts: structuredClone(runtimeConfig.prompts),
+                modelResolver: runtimeConfig.bootstrap.modelResolver.resolveModel,
+                config: runtimeConfig.config,
+            };
+            this.catalog = createContentCatalogSnapshot(this.bootstrap);
+            const unknownSkillWarnings = runtimeContext.promptBootstrap.unknownSkills.map((skill) => `unknown skill enabled by persona '${nextPersona.id}': ${skill}`);
+            const snapshot = await this.commitSnapshot();
+            this.emitSnapshotReset("configuration", snapshot);
+            return {
+                snapshot,
+                warnings: [...runtimeConfig.warnings, ...unknownSkillWarnings],
+                counts: {
+                    personas: runtimeConfig.personas.length,
+                    prompts: runtimeConfig.prompts.length,
+                    skills: runtimeConfig.skills.length,
+                },
+            };
         });
-        this.bootstrap = {
-            persona: clonePersona(nextPersona),
-            discoveredSkills: structuredClone(runtimeConfig.skills),
-            personas: personas.map(clonePersona),
-            prompts: structuredClone(runtimeConfig.prompts),
-            modelResolver: runtimeConfig.bootstrap.modelResolver.resolveModel,
-            config: runtimeConfig.config,
-        };
-        this.catalog = createContentCatalogSnapshot(this.bootstrap);
-        const unknownSkillWarnings = runtimeContext.promptBootstrap.unknownSkills.map((skill) => `unknown skill enabled by persona '${nextPersona.id}': ${skill}`);
-        const snapshot = await this.commitSnapshot();
-        this.emitSnapshotReset("configuration", snapshot);
-        return {
-            snapshot,
-            warnings: [...runtimeConfig.warnings, ...unknownSkillWarnings],
-            counts: {
-                personas: runtimeConfig.personas.length,
-                prompts: runtimeConfig.prompts.length,
-                skills: runtimeConfig.skills.length,
-            },
-        };
     }
     normalizeReloadedPersona(persona) {
         return clonePersona(persona);
@@ -886,15 +925,16 @@ class LocalHostedSessionHandle {
                 signal,
             });
             signal.throwIfAborted();
-            await this.runtimeEventQueue;
-            this.reconcileProjections();
-            const snapshot = await this.commitSnapshot();
-            this.emitSnapshotReset("maintenance", snapshot);
-            return {
-                snapshot,
-                compactionMessage: result.compactionMessage,
-                includedLastAssistant: result.includedLastAssistant,
-            };
+            return await this.enqueueMutation(async () => {
+                this.reconcileProjections();
+                const snapshot = await this.commitSnapshot();
+                this.emitSnapshotReset("maintenance", snapshot);
+                return {
+                    snapshot,
+                    compactionMessage: result.compactionMessage,
+                    includedLastAssistant: result.includedLastAssistant,
+                };
+            });
         });
     }
     async runMaintenance(operation) {
@@ -998,28 +1038,36 @@ class LocalHostedSessionHandle {
     }
     async snapshot() {
         this.assertActive();
-        return this.runtime.isTurnRunning && this.committedSnapshot
+        return await this.enqueueMutation(async () => this.runtime.isTurnRunning && this.committedSnapshot
             ? await this.commitProjectedSnapshot()
-            : await this.commitSnapshot();
+            : 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.",
+        await this.enqueueMutation(async () => {
+            const recoveredTools = [];
+            for (const recovered of recovery.recoveredToolResults) {
+                const tool = this.tools.get(recovered.message.toolCallId);
+                if (!tool || tool.status === "streaming") {
+                    continue;
                 }
-                : { ...tool, resultMessageId: recovered.historyEntryId });
-        }
-        await this.commitSnapshot();
+                const nextTool = 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 };
+                this.tools.set(tool.id, nextTool);
+                recoveredTools.push({ tool: nextTool, result: recovered });
+            }
+            await this.commitSnapshot();
+            for (const { tool, result } of recoveredTools) {
+                await this.appendToolHistory(tool, result.historyEntryId, result.message);
+            }
+        });
     }
     async dispose() {
         if (!this.disposePromise) {
@@ -1081,15 +1129,10 @@ class LocalHostedSessionHandle {
         return { objective: normalized, status: "active" };
     }
     async setGoal(goal) {
-        const previousGoal = structuredClone(this.goal);
-        this.goal = structuredClone(goal);
-        try {
+        await this.enqueueMutation(async () => {
             await this.emitPatch("goal", [{ type: "goal.set", goal: structuredClone(goal) }]);
-        }
-        catch (error) {
-            this.goal = previousGoal;
-            throw error;
-        }
+            this.goal = structuredClone(goal);
+        });
     }
     async blockActiveGoal() {
         if (this.goal?.status === "active") {
@@ -1174,37 +1217,21 @@ class LocalHostedSessionHandle {
     }
     async cancelLogicalTurn(rootHistoryEntryId, committedSteering = []) {
         const outcome = abortedTurnOutcome();
-        this.turnOutcomes.set(rootHistoryEntryId, outcome);
-        for (const steering of committedSteering) {
-            this.turnOutcomes.set(steering.historyEntryId, outcome);
-        }
-        await this.blockActiveGoal();
-        await this.emitSnapshotResetIfChanged("assistant-message");
+        await this.enqueueMutation(async () => {
+            this.turnOutcomes.set(rootHistoryEntryId, outcome);
+            for (const steering of committedSteering) {
+                this.turnOutcomes.set(steering.historyEntryId, outcome);
+            }
+            if (this.goal?.status === "active") {
+                this.goal = { ...this.goal, status: "blocked" };
+            }
+            await this.emitSnapshotResetIfChanged("assistant-message");
+        });
         this.resolveCommittedLogicalSteering(committedSteering, outcome);
         return outcome;
     }
     async commitSnapshot() {
-        const write = this.snapshotQueue.catch(() => undefined).then(() => this.writeSnapshot());
-        this.snapshotQueue = write.catch(() => undefined);
-        return await write;
-    }
-    async commitProjectedSnapshot() {
-        const write = this.snapshotQueue
-            .catch(() => undefined)
-            .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;
-    }
-    async writeSnapshot() {
         this.assertNotDisposed();
-        const generation = this.snapshotGeneration;
         const draft = this.buildSnapshotDraft();
         await this.switchSnapshotSession(draft.sessionId);
         const snapshot = {
@@ -1218,17 +1245,14 @@ class LocalHostedSessionHandle {
             expectedRevision: this.persistedSnapshot?.revision ?? 0,
         });
         this.persistedSnapshot = cloneSessionProtocolSnapshot(snapshot);
-        if (generation !== this.snapshotGeneration) {
-            return await this.writeSnapshot();
-        }
-        return cloneSessionProtocolSnapshot(this.updateCommittedSnapshotAfterWrite(snapshot));
+        this.committedSnapshot = cloneSessionProtocolSnapshot(snapshot);
+        return cloneSessionProtocolSnapshot(snapshot);
     }
-    async writeProjectedSnapshot() {
+    async commitProjectedSnapshot() {
         this.assertNotDisposed();
-        const generation = this.snapshotGeneration;
         const current = this.committedSnapshot;
         if (!current) {
-            return await this.writeSnapshot();
+            return await this.commitSnapshot();
         }
         const snapshot = cloneSessionProtocolSnapshot(current);
         if (this.persistedSnapshot && isDeepStrictEqual(this.persistedSnapshot, snapshot)) {
@@ -1238,12 +1262,9 @@ class LocalHostedSessionHandle {
             expectedRevision: this.persistedSnapshot?.revision ?? 0,
         });
         this.persistedSnapshot = cloneSessionProtocolSnapshot(snapshot);
-        if (generation !== this.snapshotGeneration) {
-            return await this.writeProjectedSnapshot();
-        }
-        return cloneSessionProtocolSnapshot(this.committedSnapshot ?? snapshot);
+        return snapshot;
     }
-    async writeSnapshotPatch(reason, changes) {
+    async commitSnapshotPatch(reason, changes) {
         this.assertNotDisposed();
         const current = this.committedSnapshot;
         if (!current) {
@@ -1262,7 +1283,6 @@ class LocalHostedSessionHandle {
         });
         this.persistedSnapshot = cloneSessionProtocolSnapshot(snapshot);
         this.committedSnapshot = cloneSessionProtocolSnapshot(snapshot);
-        this.snapshotGeneration += 1;
         return delta;
     }
     async switchSnapshotSession(sessionId) {
@@ -1276,13 +1296,6 @@ class LocalHostedSessionHandle {
         this.committedSnapshot = undefined;
         this.persistedSnapshot = undefined;
     }
-    updateCommittedSnapshotAfterWrite(snapshot) {
-        if (!this.committedSnapshot || this.committedSnapshot.revision < snapshot.revision) {
-            this.committedSnapshot = cloneSessionProtocolSnapshot(snapshot);
-            this.snapshotGeneration += 1;
-        }
-        return this.committedSnapshot;
-    }
     reconcileProjections(options = {}) {
         const messageIds = new Set(this.session.rawHistoryEntries.map((entry) => entry.id));
         messageIds.add("system");
@@ -1325,6 +1338,8 @@ class LocalHostedSessionHandle {
         const agentState = this.session.snapshot();
         return {
             sessionId: this.session.sessionId,
+            attributes: structuredClone(this.attributes),
+            createdAt: this.createdAt,
             agentState: {
                 revision: agentState.revision,
                 contextEpoch: agentState.contextEpoch,
@@ -1440,7 +1455,8 @@ class LocalHostedSessionHandle {
         for (const [id, facet] of Object.entries(snapshot.facets)) {
             this.facets.set(id, structuredClone(facet));
         }
-        this.draftAssistantMessage = snapshot.messages.find((message) => message.state === "draft");
+        const historyEntryIds = new Set(this.session.rawHistoryEntries.map((entry) => entry.id));
+        this.draftAssistantMessage = snapshot.messages.find((message) => message.state === "draft" && !historyEntryIds.has(message.id));
         this.messageStates.clear();
         this.turnOutcomes.clear();
         for (const message of snapshot.messages) {
@@ -1452,6 +1468,24 @@ class LocalHostedSessionHandle {
             }
         }
     }
+    enqueueMutation(mutation) {
+        const result = this.mutationQueue
+            .catch(() => undefined)
+            .then(async () => {
+            try {
+                return await mutation();
+            }
+            catch (error) {
+                if (this.committedSnapshot) {
+                    this.goal = structuredClone(this.committedSnapshot.goal);
+                    this.restoreProtocolState(this.committedSnapshot);
+                }
+                throw error;
+            }
+        });
+        this.mutationQueue = result.then(() => undefined, () => undefined);
+        return result;
+    }
     assertActive() {
         if (this.disposing || this.disposed) {
             throw new Error(`session is shut down: ${this.committedSessionId}`);
@@ -1474,23 +1508,13 @@ class LocalHostedSessionHandle {
         return JSON.stringify(current) === JSON.stringify(next) ? revision : revision + 1;
     }
     async recordSubagentEvent(event) {
-        const write = this.runtimeEventQueue
-            .catch(() => undefined)
-            .then(() => this.recordSubagentUiEvent(event));
-        this.runtimeEventQueue = write.catch(() => undefined);
-        return await write;
+        await this.enqueueMutation(() => this.recordSubagentUiEvent(event));
     }
     async enqueueRuntimeEvent(event) {
-        const write = this.runtimeEventQueue
-            .catch(() => undefined)
-            .then(() => this.recordRuntimeEvent(event));
-        this.runtimeEventQueue = write.catch(() => undefined);
-        return write;
+        await this.enqueueMutation(() => this.recordRuntimeEvent(event));
     }
     async commitSteeringTurnOutcome(historyEntryId, turn) {
-        const write = this.runtimeEventQueue
-            .catch(() => undefined)
-            .then(async () => {
+        await this.enqueueMutation(async () => {
             this.turnOutcomes.set(historyEntryId, turn);
             const message = this.committedSnapshot?.messages.find((candidate) => candidate.id === historyEntryId);
             if (!message) {
@@ -1506,8 +1530,6 @@ class LocalHostedSessionHandle {
                 },
             ]);
         });
-        this.runtimeEventQueue = write.catch(() => undefined);
-        await write;
     }
     removeToolRun(tool, changes) {
         this.tools.delete(tool.id);
@@ -1517,6 +1539,43 @@ class LocalHostedSessionHandle {
         }
         changes.push({ type: "tool.remove", id: tool.id });
     }
+    async recordHistoryFailure(reason) {
+        if (!reason || this.timelineExtras.some((item) => item.id === HISTORY_UNAVAILABLE_NOTICE_ID)) {
+            return;
+        }
+        const item = {
+            type: "notice",
+            id: HISTORY_UNAVAILABLE_NOTICE_ID,
+            notice: {
+                severity: "warn",
+                text: `Session history is unavailable: ${reason}. This session will continue without durable history recording or recall.`,
+                timestamp: Date.now(),
+            },
+        };
+        this.timelineExtras.push(item);
+        await this.emitPatch("notice", [{ type: "timeline.append", item: structuredClone(item) }]);
+    }
+    async appendToolHistory(tool, resultHistoryEntryId, result) {
+        const callMessage = this.committedSnapshot?.messages.find((message) => message.id === tool.call.messageId);
+        const call = callMessage?.message.role === "assistant"
+            ? callMessage.message.content[tool.call.contentIndex]
+            : undefined;
+        if (call?.type !== "toolCall" || call.id !== tool.toolCallId) {
+            throw new Error(`missing transcript tool call '${tool.toolCallId}'`);
+        }
+        if (tool.status === "queued" || tool.status === "running") {
+            throw new Error(`transcript tool call '${tool.toolCallId}' is not terminal`);
+        }
+        await this.recordHistoryFailure(this.history.append(this.sessionId, [
+            toolHistoryEntry({
+                callHistoryEntryId: tool.call.messageId,
+                resultHistoryEntryId,
+                call,
+                result,
+                outcome: tool.status,
+            }),
+        ], this.historyRemote));
+    }
     agentStateChange() {
         const state = this.session.snapshot();
         return {
@@ -1659,6 +1718,7 @@ class LocalHostedSessionHandle {
                         timelineItem: timelineItemForMessage(event.historyEntryId),
                     },
                 ], { persist: true });
+                await this.recordHistoryFailure(this.history.append(this.sessionId, [userHistoryEntry(event.historyEntryId, event.message)], this.historyRemote));
                 if (pendingGoal && this.pendingGoalCommit === pendingGoal) {
                     this.pendingGoalCommit = undefined;
                 }
@@ -1667,6 +1727,7 @@ class LocalHostedSessionHandle {
             case "history_rewound":
                 this.reconcileProjections({ removeMissingAgents: true });
                 await this.emitSnapshotResetIfChanged("maintenance");
+                await this.recordHistoryFailure(this.history.truncateFromSources(this.sessionId, event.removedEntryIds, this.historyRemote));
                 return;
             case "assistant_final": {
                 this.draftAssistantMessage = undefined;
@@ -1713,6 +1774,7 @@ class LocalHostedSessionHandle {
                         : []),
                     ...toolChanges,
                 ]);
+                await this.recordHistoryFailure(this.history.append(this.sessionId, assistantHistoryEntries(event.historyEntryId, event.message), this.historyRemote));
                 return;
             }
             case "tool_run_queued":
@@ -1771,6 +1833,7 @@ class LocalHostedSessionHandle {
                         },
                         { type: "tool.set", tool: structuredClone(nextTool) },
                     ]);
+                    await this.appendToolHistory(existing, event.historyEntryId, event.message);
                     return;
                 }
                 await this.emitPatch("tool-result", [
@@ -1801,6 +1864,7 @@ class LocalHostedSessionHandle {
                         },
                     },
                 ];
+                const historyTools = [];
                 for (const toolResult of event.toolResults) {
                     const existing = this.tools.get(toolResult.toolCallId);
                     if (!existing || existing.status === "streaming") {
@@ -1814,8 +1878,12 @@ class LocalHostedSessionHandle {
                     };
                     this.tools.set(nextTool.id, nextTool);
                     changes.push({ type: "tool.set", tool: structuredClone(nextTool) });
+                    historyTools.push({ tool: existing, result: toolResult });
                 }
                 await this.emitPatch("recovery", changes);
+                for (const { tool, result } of historyTools) {
+                    await this.appendToolHistory(tool, event.historyEntryId, result);
+                }
                 return;
             }
             case "notice": {
@@ -1952,7 +2020,6 @@ class LocalHostedSessionHandle {
             if (options.persist === false) {
                 const snapshot = { ...this.buildSnapshotDraft(), revision: 1 };
                 this.committedSnapshot = snapshot;
-                this.snapshotGeneration += 1;
                 this.emitSnapshotReset(reason, snapshot);
                 return;
             }
@@ -1972,7 +2039,6 @@ class LocalHostedSessionHandle {
             delta: { type: "snapshot.patch", changes },
         });
         this.committedSnapshot = applySessionProtocolDelta(this.committedSnapshot, delta);
-        this.snapshotGeneration += 1;
         this.emitDelta(delta);
     }
     emitSnapshotReset(reason, snapshot) {
@@ -1984,6 +2050,9 @@ class LocalHostedSessionHandle {
             delta: { type: "snapshot.reset", snapshot },
         }));
     }
+    async enqueueSnapshotResetIfChanged(reason) {
+        await this.enqueueMutation(() => this.emitSnapshotResetIfChanged(reason));
+    }
     async emitSnapshotResetIfChanged(reason) {
         const previousRevision = this.committedSnapshot?.revision;
         const snapshot = await this.commitSnapshot();
@@ -2049,14 +2118,51 @@ class LocalHostedSessionHandle {
         const interruptedMessage = createInterruptedAssistantMessage(draft, this.runtime.persona.model);
         await this.session.commitInterruptedAssistant(interruptedMessage, draft.id);
     }
-    async cleanupFailedTurn() {
+    async cleanupFailedTurn(rootHistoryEntryId, committedSteering, error) {
         if (this.draftAssistantMessage) {
-            await this.interruptDraftAssistantMessage();
-            return;
-        }
-        await this.emitSnapshotResetIfChanged("assistant-message");
+            await this.interruptDraftAssistantMessage().catch(() => undefined);
+        }
+        const diagnostic = formatErrorDiagnostic(error);
+        await this.enqueueMutation(async () => {
+            const outcome = {
+                status: "failed",
+                stopReason: "error",
+                errorMessage: diagnostic,
+            };
+            this.turnOutcomes.set(rootHistoryEntryId, outcome);
+            for (const steering of committedSteering) {
+                this.turnOutcomes.set(steering.historyEntryId, outcome);
+            }
+            if (this.goal?.status === "active") {
+                this.goal = { ...this.goal, status: "blocked" };
+            }
+            const timestamp = Date.now();
+            for (const [id, tool] of this.tools) {
+                if (tool.status !== "queued" && tool.status !== "running") {
+                    continue;
+                }
+                this.tools.set(id, {
+                    ...tool,
+                    status: "cancelled",
+                    finishedAt: timestamp,
+                    error: `Turn failed before tool completion: ${diagnostic}`,
+                });
+            }
+            await this.emitSnapshotResetIfChanged("assistant-message");
+        });
     }
 }
+function formatErrorDiagnostic(error) {
+    const messages = [];
+    const seen = new Set();
+    let current = error;
+    while (current !== undefined && !seen.has(current)) {
+        seen.add(current);
+        messages.push(current instanceof Error ? current.message : String(current));
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return messages.filter((message, index) => message && message !== messages[index - 1]).join(": ");
+}
 function abortedTurnOutcome() {
     return { status: "aborted", stopReason: "aborted" };
 }