narraeon 0.5.5 → 0.5.7

package/dist/node/runtime/play/PlayCallChain.js

@@ -1,3 +1,7 @@
+import { projectLegacyModelBindingFailure } from "./LegacyModelBindingFailure.js";
+import { classifyPlayFailure } from "./PlayFailure.js";
+import { captureNarrativeOrigin, snapshotBackground, narrativeBackground, } from "../history/HistoryBackground.js";
+import { isDeepStrictEqual } from "node:util";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
 import { PlayCallChainError } from "./PlayCallChainError.js";
 import { preparePlayerRevisionTrace, prepareForkTrace, restorePlayDocuments, independentContextCopy, } from "./PlayTraceRetention.js";
@@ -8,7 +12,7 @@ import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepN
 import { renderFreshContextCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { renderWriteSizeAdvice, readDeclaredWorldClock, } from "../prompt/WorldMaintenanceReport.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
-import { equalModelHostBinding, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, modelHostFailureRequiresFreshContext, } from "../model/ModelHost.js";
+import { equalModelHostBinding, ModelHostBindingMismatchError, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, modelHostFailureRequiresFreshContext, } from "../model/ModelHost.js";
 import { FileNativePromptCompiler, } from "../prompt/FileNativePromptCompiler.js";
 import { parsePlayPresetFiles, } from "./FileNativePlayPresetStore.js";
 import { runPlayFollowupRequests, } from "./PlayFollowupRequests.js";
@@ -88,6 +92,7 @@ export class PlayCallChain {
                 documentSnapshot: documents.snapshot,
                 additionalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                 narrativeCheckpoint: binding.narrativeCheckpoint,
                 documentMaintenance,
                 documentMaintenanceUnavailableReason: documents.maintenanceWarning,
@@ -144,7 +149,7 @@ export class PlayCallChain {
             lastFailure: null,
             updatedAt: now,
             documents,
-            history: historyEntries(binding.history),
+            history: historyEntries(binding.history, binding.historyBackgrounds),
             narrativeCheckpoint: binding.narrativeCheckpoint,
             completedToolMap: new Map(),
             persistenceCursor: {
@@ -159,6 +164,7 @@ export class PlayCallChain {
         this.#active.set(session.chainId, session);
         this.#worldChains.set(session.worldId, session.chainId);
         await this.#persist(session);
+        await this.#worlds.completeArchiveFreshContext(session.worldId);
         return this.#submitPlayer(session, input.exchangeId, input.playerText, "fresh", input.modelHost, signal, input.observer);
     }
     async append(input) {
@@ -166,6 +172,8 @@ export class PlayCallChain {
     }
     async #append(input, signal) {
         validateIdentity(input.exchangeId, "exchange ID");
+        if (await this.#worlds.archiveNeedsFreshContext(input.worldId))
+            throw new PlayCallChainError("This world was imported from a backup; start a fresh context before continuing.");
         const session = await this.#requireChain(input.worldId, input.chainId);
         await this.#assertCurrentHead(session);
         assertSessionModelHostBinding(session, input.modelHost);
@@ -175,6 +183,11 @@ export class PlayCallChain {
             if (session.status === "interrupted") {
                 if (!session.canRetry || session.lastRequest === null)
                     throw new PlayCallChainError("The current model context cannot continue; use a fresh context.");
+                // Pre-snapshot requests have only a binding fingerprint. Do not invent
+                // their original encoding settings from a newly selected connection.
+                if (session.lastRequest.modelConfig === undefined &&
+                    !equalModelHostBinding(session.modelBinding, input.modelHost.binding()))
+                    throw new PlayCallChainError("This older saved request has no model configuration snapshot. Restore its original settings to retry it, or start a fresh context.");
                 return this.#dispatch(session, input.modelHost, structuredClone(session.lastRequest), session.lastRequestAttempt + 1, signal, input.observer);
             }
             await this.#refreshPrompt(session, input);
@@ -182,8 +195,10 @@ export class PlayCallChain {
             const last = session.transcript.at(-1);
             if (last?.kind === "assistant" &&
                 last.toolCalls.length === 0 &&
-                last.text.trim().length > 0)
+                last.text.trim().length > 0) {
+                session.narrativeOrigin = await this.#captureOrigin(session);
                 session.transcript.push(continuationNotice(this.#compiler.locale));
+            }
             return this.#dispatch(session, input.modelHost, createRequest(session, input.modelHost, session.exchange), 1, signal, input.observer);
         }
         if (duplicatePlayerExchange(session, input.exchangeId, input.playerText, "append"))
@@ -213,6 +228,7 @@ export class PlayCallChain {
                 documentSnapshot: session.documents.snapshot,
                 additionalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                 narrativeCheckpoint: binding.narrativeCheckpoint,
             },
             playerInputPlacement: "append",
@@ -221,7 +237,7 @@ export class PlayCallChain {
         }, playPreset);
         // The native conversation already contains successful writes and exact reads.
         // Rebinding initial coverage here would incorrectly reauthorize stale scopes.
-        session.history = historyEntries(binding.history);
+        session.history = historyEntries(binding.history, binding.historyBackgrounds);
         session.narrativeCheckpoint = binding.narrativeCheckpoint;
         session.nextMaterials = structuredClone(binding.additionalMaterials);
         (session.promptRuns ??= []).push({
@@ -458,7 +474,8 @@ export class PlayCallChain {
             chainId: session.chainId,
             baselineHead: session.baselineHead,
             parentHead: session.parentHead,
-            stale: session.parentHead !== worldHead,
+            stale: session.parentHead !== worldHead ||
+                (await this.#worlds.archiveNeedsFreshContext(worldId)),
             playPreset: structuredClone(recordedPlayPrompt(session).playPreset),
             updatedAt: session.updatedAt,
             bootstrap: {
@@ -471,17 +488,25 @@ export class PlayCallChain {
     async deriveWorld(input) {
         const result = await this.#worlds.deriveWorld({
             ...input,
-            stageTarget: async ({ targetWorldRoot, targetWorldId, binding }) => {
+            stageTarget: async ({ targetWorldRoot, targetWorldId, binding, sourceHead, }) => {
                 await this.stageForkToDerivedWorld({
                     sourceWorldId: input.sourceWorldId,
-                    sourceHead: input.sourceHead,
+                    sourceHead,
                     targetWorldId,
                     targetWorldRoot,
                     targetBinding: binding,
+                    ...(input.retainCompleteTimeline
+                        ? { retainCompleteTimeline: true }
+                        : {}),
+                    ...(input.identityPrefix === "import"
+                        ? { markImportedContexts: true }
+                        : {}),
                 });
             },
         });
-        if ((await this.inspectWorld(result.world.worldId)) === null)
+        if (input.targetDataRoot === undefined &&
+            input.publish !== false &&
+            (await this.inspectWorld(result.world.worldId)) === null)
             await this.forkToDerivedWorld({
                 sourceWorldId: input.sourceWorldId,
                 sourceHead: input.sourceHead,
@@ -517,10 +542,14 @@ export class PlayCallChain {
         if (source === null)
             return null;
         const sourceContexts = await this.#worlds.playTimeline.readAllContexts(input.sourceWorldId);
-        const selectedContextIndex = sourceContexts.findIndex(({ events }) => eventsThroughHead(events, input.sourceHead) !== null);
+        const selectedContextIndex = input.retainCompleteTimeline
+            ? sourceContexts.length - 1
+            : sourceContexts.findIndex(({ events }) => eventsThroughHead(events, input.sourceHead) !== null);
         if (selectedContextIndex < 0)
             return null;
-        const sourceEvents = eventsThroughHead(sourceContexts[selectedContextIndex].events, input.sourceHead);
+        const sourceEvents = input.retainCompleteTimeline
+            ? sourceContexts[selectedContextIndex].events
+            : eventsThroughHead(sourceContexts[selectedContextIndex].events, input.sourceHead);
         return this.#forkSelectionToDerivedWorld({
             sourceWorldId: input.sourceWorldId,
             sourceContexts,
@@ -531,6 +560,8 @@ export class PlayCallChain {
             branchIdentity: input.sourceHead,
             targetWorldRoot: input.targetWorldRoot,
             targetBinding: input.targetBinding,
+            ...(input.retainCompleteTimeline ? { retainCompleteTimeline: true } : {}),
+            ...(input.markImportedContexts ? { markImportedContexts: true } : {}),
         });
     }
     /**
@@ -598,6 +629,9 @@ export class PlayCallChain {
         if (selectedContextIndex < 0)
             throw new PlayCallChainError("The model context to revise does not exist.");
         const sourceContext = sourceContexts[selectedContextIndex];
+        if (input.continuation === "continue_context" &&
+            sourceContext.importedFromArchive)
+            throw new PlayCallChainError("This model context was imported from a backup; start a fresh context before continuing.");
         const selectedEventIndex = sourceContext.events.findIndex((event) => event.id === input.eventId);
         const selectedEvent = sourceContext.events[selectedEventIndex];
         if (selectedEventIndex < 0 ||
@@ -640,11 +674,10 @@ export class PlayCallChain {
             this.#worlds.recoverEndpoint(request.worldId, restoresHead),
             this.#worlds.bindPlayCallChain(request.worldId),
         ]);
-        const continuedTrace = traceRetention.withReplacement(selected, {
+        const continuedTrace = traceRetention.withReplacement({
             head: outcome.head,
             exchangeId: request.replacementExchangeId,
             text: request.replacementText,
-            locale: this.#compiler.locale,
         });
         if (binding.parentHead !== outcome.head)
             throw new PlayCallChainError("The timeline revision was committed, but current-world materialization has not reached the new endpoint.");
@@ -666,6 +699,7 @@ export class PlayCallChain {
                 freshPreparation,
             });
             await this.#worlds.playTimeline.persist(structuredClone(revised));
+            await this.#worlds.completeArchiveFreshContext(request.worldId);
             const activeId = this.#worldChains.get(request.worldId);
             if (activeId !== undefined)
                 this.#active.delete(activeId);
@@ -719,6 +753,7 @@ export class PlayCallChain {
                 documentSnapshot: documents.snapshot,
                 additionalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                 narrativeCheckpoint: binding.narrativeCheckpoint,
                 documentMaintenance,
                 documentMaintenanceUnavailableReason: documents.maintenanceWarning,
@@ -788,13 +823,11 @@ export class PlayCallChain {
             canRetry: false,
             bootstrap: structuredClone(fresh.bootstrap),
             tools: structuredClone(fresh.tools),
-            transcript: playerInputAppend({
-                history: fresh.binding.history,
-                checkpoint: fresh.binding.narrativeCheckpoint,
-                text: request.replacementText,
-                locale: this.#compiler.locale,
-                checkpointAvailable: fresh.tools.some(({ name }) => name === "world_checkpoint"),
-            }),
+            narrativeOrigin: captureNarrativeOrigin(WorldDocumentStore.open({
+                layout: "world_state",
+                files: Object.entries(input.binding.files).map(([path, contents]) => ({ path, contents })),
+            }), 1),
+            transcript: playerInputAppend(request.replacementText),
             events: [
                 {
                     id: 1,
@@ -832,22 +865,30 @@ export class PlayCallChain {
         if (input.targetWorldRoot === undefined &&
             (await this.#worlds.currentHead(input.targetWorldId)) !== input.sourceHead)
             throw new PlayCallChainError("The forked world's Authority does not match the selected history endpoint, so the call chain cannot be written.");
-        const [baseline, selected] = await Promise.all([
-            this.#worlds.recoverEndpoint(input.targetWorldRoot === undefined
-                ? input.targetWorldId
-                : input.sourceWorldId, sourceContext.baselineHead),
-            this.#worlds.recoverEndpoint(input.targetWorldRoot === undefined
-                ? input.targetWorldId
-                : input.sourceWorldId, input.sourceHead),
-        ]);
-        const traceRetention = prepareForkTrace(sourceContext, input.sourceEvents);
-        const derivedBinding = input.targetBinding ??
-            (await this.#worlds.bindPlayCallChain(input.targetWorldId));
-        const retainedTrace = traceRetention.atEndpoint({
-            baseline,
-            selected,
-            binding: derivedBinding,
-        });
+        let retainedTrace;
+        if (input.retainCompleteTimeline) {
+            // A backup retains the current page closure, even when its last context
+            // precedes a correction or contains an uncommitted response diagnostic.
+            retainedTrace = independentContextCopy(sourceContext);
+        }
+        else {
+            const [baseline, selected] = await Promise.all([
+                this.#worlds.recoverEndpoint(input.targetWorldRoot === undefined
+                    ? input.targetWorldId
+                    : input.sourceWorldId, sourceContext.baselineHead),
+                this.#worlds.recoverEndpoint(input.targetWorldRoot === undefined
+                    ? input.targetWorldId
+                    : input.sourceWorldId, input.sourceHead),
+            ]);
+            const traceRetention = prepareForkTrace(sourceContext, input.sourceEvents);
+            const derivedBinding = input.targetBinding ??
+                (await this.#worlds.bindPlayCallChain(input.targetWorldId));
+            retainedTrace = traceRetention.atEndpoint({
+                baseline,
+                selected,
+                binding: derivedBinding,
+            });
+        }
         const now = Date.now();
         const timelineGeneration = this.#worlds.playTimeline.newGeneration();
         let previousChainId = null;
@@ -857,6 +898,7 @@ export class PlayCallChain {
             const chainId = derivedChainId(context.chainId, `prefix:${input.branchIdentity}:${index}`, input.targetWorldId);
             const previousContext = {
                 ...independentContextCopy(context),
+                ...(input.markImportedContexts ? { importedFromArchive: true } : {}),
                 schemaVersion: 3,
                 kind: "play_call_chain",
                 worldId: input.targetWorldId,
@@ -873,11 +915,15 @@ export class PlayCallChain {
                     targetWorldRoot: input.targetWorldRoot,
                     source: context,
                     target: previousContext,
+                    ...(input.retainCompleteTimeline
+                        ? { retainCompleteContext: true }
+                        : {}),
                 });
             previousChainId = chainId;
         }
         const derived = {
             ...retainedTrace,
+            ...(input.markImportedContexts ? { importedFromArchive: true } : {}),
             schemaVersion: 3,
             kind: "play_call_chain",
             chainId: derivedChainId(sourceContext.chainId, input.branchIdentity, input.targetWorldId),
@@ -885,7 +931,9 @@ export class PlayCallChain {
             previousContexts: [],
             previousChainId,
             timelineGeneration,
-            parentHead: input.sourceHead,
+            parentHead: input.retainCompleteTimeline
+                ? sourceContext.parentHead
+                : input.sourceHead,
             updatedAt: now,
         };
         if (input.targetWorldRoot === undefined)
@@ -896,6 +944,9 @@ export class PlayCallChain {
                 targetWorldRoot: input.targetWorldRoot,
                 source: sourceContext,
                 target: structuredClone(derived),
+                ...(input.retainCompleteTimeline
+                    ? { retainCompleteContext: true }
+                    : {}),
             });
         if (input.targetWorldRoot !== undefined) {
             const retainedContexts = [
@@ -928,21 +979,28 @@ export class PlayCallChain {
             this.#active.delete(activeId);
         this.#worldChains.delete(worldId);
     }
+    async #captureOrigin(session) {
+        const binding = await this.#worlds.bindPlayCallChain(session.worldId);
+        if (binding.parentHead !== session.parentHead)
+            throw new PlayCallChainError("World advanced before background capture; use a fresh context.");
+        return captureNarrativeOrigin(WorldDocumentStore.open({
+            layout: "world_state",
+            files: Object.entries(binding.files).map(([path, contents]) => ({
+                path,
+                contents,
+            })),
+        }), session.nextEventId);
+    }
     async #submitPlayer(session, exchangeId, playerText, context, modelHost, signal, observer) {
         if (duplicatePlayerExchange(session, exchangeId, playerText, context))
             return projectView(session);
         if (session.status === "running")
             throw new PlayCallChainError("The call chain is waiting for the model to return.");
+        session.narrativeOrigin = await this.#captureOrigin(session);
         const exchange = session.exchange + 1;
         const nextRequest = createRequest(session, modelHost, exchange, [
             ...session.transcript,
-            ...playerInputAppend({
-                history: Object.fromEntries(session.history.map(({ path, contents }) => [path, contents])),
-                checkpoint: session.narrativeCheckpoint,
-                text: playerText,
-                locale: this.#compiler.locale,
-                checkpointAvailable: currentPlayPrompt(session).tools.some(({ name }) => name === "world_checkpoint"),
-            }),
+            ...playerInputAppend(playerText),
         ]);
         const operationKey = `player:${exchangeId}`;
         const playerOperationId = operationId(session.chainId, operationKey);
@@ -950,6 +1008,7 @@ export class PlayCallChain {
             schemaVersion: 1,
             kind: "play_advance",
             advanceKind: "player",
+            narrativeOrigin: structuredClone(session.narrativeOrigin),
             playContext: session.continuityContextId ?? session.chainId,
             worldId: session.worldId,
             chainId: session.chainId,
@@ -981,14 +1040,17 @@ export class PlayCallChain {
             const message = error instanceof Error
                 ? error.message
                 : "Failed to write the original player text.";
+            const failureKind = classifyPlayFailure(error, false);
             session.events.push({
                 id: session.nextEventId++,
                 kind: "failure",
                 message,
+                failureKind,
             });
             session.status = "interrupted";
             session.canRetry = false;
             session.lastFailure = message;
+            session.lastFailureKind = failureKind;
             await this.#persist(session);
             await this.#worlds.playAdvances.markSettled(advance, session.parentHead);
             throw new PlayCallChainError(message);
@@ -1003,7 +1065,17 @@ export class PlayCallChain {
             operationId: advance.operationId,
             worldId: session.worldId,
             parentHead: advance.parentHead,
-            historyAppend: [{ role: "player", exactText: advance.playerText }],
+            historyAppend: [
+                {
+                    role: "player",
+                    exactText: advance.playerText,
+                    ...(advance.narrativeOrigin?.value == null
+                        ? {}
+                        : {
+                            background: snapshotBackground(advance.narrativeOrigin.value),
+                        }),
+                },
+            ],
             nextMaterials: structuredClone(session.nextMaterials),
             stateChanges: [],
         });
@@ -1031,6 +1103,10 @@ export class PlayCallChain {
         session.nextEventId = advance.eventId + 1;
         session.parentHead = outcome.head;
         appendCommittedHistory(session, outcome.head, outcome.historyAppend);
+        if (advance.narrativeOrigin === undefined)
+            delete session.narrativeOrigin;
+        else
+            session.narrativeOrigin = structuredClone(advance.narrativeOrigin);
         session.exchange = advance.exchange;
         session.lastRequest = structuredClone(advance.nextRequest);
         session.lastRequestAttempt = 0;
@@ -1038,6 +1114,7 @@ export class PlayCallChain {
         session.canRetry = true;
         session.lastFailure =
             "The player message is committed; the frozen model request is ready to continue.";
+        session.lastFailureKind = "retryable";
         await this.#persist(session);
         crashAtPlayAdvanceEdge("after_timeline_settled");
         await this.#worlds.playAdvances.markSettled(advance, outcome.head);
@@ -1167,7 +1244,11 @@ export class PlayCallChain {
                 : { providerState: response.providerState }),
             toolCalls: structuredClone(calls),
         };
+        const background = visibleText
+            ? narrativeBackground(advance.narrativeOrigin, session.documents.snapshot)
+            : undefined;
         return {
+            ...(background === undefined ? {} : { background }),
             assistantEvent,
             playContext: session.continuityContextId ?? session.chainId,
             ...(worldClock === undefined || stateChanges.length === 0
@@ -1226,6 +1307,9 @@ export class PlayCallChain {
                         {
                             role: "narrator",
                             exactText: settlement.assistantEvent.text,
+                            ...(settlement.background === undefined
+                                ? {}
+                                : { background: settlement.background }),
                         },
                     ]
                     : [],
@@ -1287,7 +1371,7 @@ export class PlayCallChain {
                 const binding = await this.#worlds.bindPlayCallChain(session.worldId);
                 session.documents = new FileNativePlayDocuments(binding.files);
                 session.documents.restoreAuthorizationCheckpoint(settlement.authorizationCheckpoint);
-                session.history = historyEntries(binding.history);
+                session.history = historyEntries(binding.history, binding.historyBackgrounds);
                 session.nextMaterials = structuredClone(binding.additionalMaterials);
             }
             mergeChangedDocuments(session, settlement.stateChanges);
@@ -1297,6 +1381,7 @@ export class PlayCallChain {
         session.exchange = Math.max(session.exchange, advance.exchange);
         session.canRetry = false;
         session.lastFailure = null;
+        delete session.lastFailureKind;
         let result;
         if (settlement.assistantEvent.continuation !== "available") {
             const message = "The complete model response has no provider-native continuation payload; use a fresh context.";
@@ -1304,20 +1389,25 @@ export class PlayCallChain {
                 id: session.nextEventId++,
                 kind: "failure",
                 message,
+                failureKind: "context_unavailable",
             });
             session.status = "interrupted";
             session.lastFailure = message;
+            session.lastFailureKind = "context_unavailable";
             result = { kind: "terminal", status: "interrupted" };
         }
         else if (hasToolCalls) {
             session.exchange += 1;
             const nextRequest = createRequestWithMaxOutputTokens(session, session.lastRequest?.maxOutputTokens ?? 1, session.exchange);
+            if (session.lastRequest?.modelConfig !== undefined)
+                nextRequest.modelConfig = structuredClone(session.lastRequest.modelConfig);
             session.lastRequest = structuredClone(nextRequest);
             session.lastRequestAttempt = 0;
             session.status = "interrupted";
             session.canRetry = true;
             session.lastFailure =
                 "The completed tool response is settled; its frozen continuation request is ready.";
+            session.lastFailureKind = "retryable";
             result = { kind: "continue", nextRequest };
         }
         else {
@@ -1328,8 +1418,10 @@ export class PlayCallChain {
                     id: session.nextEventId++,
                     kind: "failure",
                     message,
+                    failureKind: "other",
                 });
                 session.lastFailure = message;
+                session.lastFailureKind = "other";
             }
             result = { kind: "terminal", status: session.status };
         }
@@ -1353,7 +1445,7 @@ export class PlayCallChain {
         return this.#settleResponseAdvance(session, advance, current.settlementPrepared.settlement);
     }
     async #dispatch(session, modelHost, firstRequest, firstAttempt, signal, observer) {
-        let request = structuredClone(firstRequest);
+        let request = modelHost.freezeRequest?.(firstRequest) ?? structuredClone(firstRequest);
         let attempt = firstAttempt;
         for (;;) {
             this.#setInvocationAbortable(session.chainId, true);
@@ -1363,6 +1455,7 @@ export class PlayCallChain {
             session.status = "running";
             session.canRetry = false;
             session.lastFailure = null;
+            delete session.lastFailureKind;
             session.lastRequest = structuredClone(request);
             session.lastRequestAttempt = attempt;
             const responseExchange = request.exchange ?? session.exchange;
@@ -1382,6 +1475,9 @@ export class PlayCallChain {
                 schemaVersion: 1,
                 kind: "play_advance",
                 advanceKind: "response",
+                ...(session.narrativeOrigin === undefined
+                    ? {}
+                    : { narrativeOrigin: structuredClone(session.narrativeOrigin) }),
                 worldId: session.worldId,
                 chainId: session.chainId,
                 advanceId: responseOperationId,
@@ -1451,20 +1547,31 @@ export class PlayCallChain {
                 const message = error instanceof Error
                     ? error.message
                     : "The model request was interrupted.";
-                session.events.push({
-                    id: session.nextEventId++,
-                    kind: error instanceof ModelHostCancelledError
-                        ? "cancellation"
-                        : "failure",
-                    message,
-                });
                 session.status = "interrupted";
-                const requiresFreshContext = error instanceof ModelHostContinuationError ||
+                const requiresFreshContext = error instanceof ModelHostBindingMismatchError ||
+                    error instanceof ModelHostContinuationError ||
                     error instanceof ModelHostOutcomeUnknownError ||
                     modelHostFailureRequiresFreshContext(error);
                 session.canRetry =
                     !requiresFreshContext && error instanceof ModelHostFailureError;
                 session.lastFailure = message;
+                if (error instanceof ModelHostCancelledError) {
+                    delete session.lastFailureKind;
+                    session.events.push({
+                        id: session.nextEventId++,
+                        kind: "cancellation",
+                        message,
+                    });
+                }
+                else {
+                    session.lastFailureKind = classifyPlayFailure(error, session.canRetry);
+                    session.events.push({
+                        id: session.nextEventId++,
+                        kind: "failure",
+                        message,
+                        failureKind: session.lastFailureKind,
+                    });
+                }
                 await this.#persist(session);
                 await this.#worlds.playAdvances.markSettled(advance, session.parentHead);
                 this.#notifySnapshot(observer, session);
@@ -1582,14 +1689,17 @@ export class PlayCallChain {
                             },
                         ],
                     });
+                const failureKind = classifyPlayFailure(error, false);
                 session.events.push({
                     id: session.nextEventId++,
                     kind: "failure",
                     message,
+                    failureKind,
                 });
                 session.status = "interrupted";
                 session.canRetry = false;
                 session.lastFailure = message;
+                session.lastFailureKind = failureKind;
                 await this.#persist(session);
                 this.#notifySnapshot(observer, session);
                 return projectView(session);
@@ -1613,6 +1723,7 @@ export class PlayCallChain {
         session.lastRequest = structuredClone(request);
         session.lastRequestAttempt = Math.max(0, attempt - 1);
         session.lastFailure = message;
+        delete session.lastFailureKind;
         await this.#persist(session);
         if (advance !== undefined)
             await this.#worlds.playAdvances.markSettled(advance, session.parentHead);
@@ -1784,7 +1895,7 @@ export class PlayCallChain {
             documentAuthorizationCheckpoints: persisted.documentAuthorizationCheckpoints?.map((checkpoint) => structuredClone(checkpoint)) ?? [],
             nextMaterials: structuredClone(binding.additionalMaterials),
             documents,
-            history: historyEntries(binding.history),
+            history: historyEntries(binding.history, binding.historyBackgrounds),
             narrativeCheckpoint: binding.narrativeCheckpoint,
             completedToolMap: new Map(persisted.completedTools.map((item) => [
                 item.key,
@@ -1832,14 +1943,21 @@ export class PlayCallChain {
             : canRetry
                 ? "The service stopped before model dispatch; the frozen request can be retried."
                 : "The service stopped before preparing a model request; use a fresh context.";
+        const failureKind = dispatchMayHaveStarted
+            ? "outcome_unknown"
+            : canRetry
+                ? "retryable"
+                : "other";
         session.events.push({
             id: session.nextEventId++,
             kind: "failure",
             message,
+            failureKind,
         });
         session.status = "interrupted";
         session.canRetry = canRetry;
         session.lastFailure = message;
+        session.lastFailureKind = failureKind;
         await this.#persist(session);
     }
     async #assertCurrentHead(session) {
@@ -1874,7 +1992,8 @@ function followupOperationId(session) {
     return `${session.chainId}:followup:${session.parentHead}`;
 }
 function createRequest(session, modelHost, exchange, appended = session.transcript) {
-    return createRequestWithMaxOutputTokens(session, modelHost.binding().maxOutputTokens, exchange, appended);
+    const request = createRequestWithMaxOutputTokens(session, modelHost.binding().maxOutputTokens, exchange, appended);
+    return modelHost.freezeRequest?.(request) ?? request;
 }
 function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, appended = session.transcript) {
     return {
@@ -1935,11 +2054,18 @@ function appendCommittedHistory(session, head, messages) {
         const path = `message.${sequence}.${index + 1}.${message.role}`;
         const existing = session.history.find((item) => item.path === path);
         if (existing !== undefined) {
-            if (existing.contents !== message.exactText)
+            if (existing.contents !== message.exactText ||
+                !isDeepStrictEqual(existing.background, message.background))
                 throw new PlayCallChainError("Recovered Authority history conflicts with the call-chain history.");
             continue;
         }
-        session.history.push({ path, contents: message.exactText });
+        session.history.push({
+            path,
+            contents: message.exactText,
+            ...(message.background === undefined
+                ? {}
+                : { background: structuredClone(message.background) }),
+        });
     }
 }
 function prepareTool(session, working, exchange, call, locale) {
@@ -2052,7 +2178,9 @@ function mergeChangedDocuments(session, changes) {
     }
 }
 function projectContext(context) {
+    const response = context.events.findLast((event) => event.kind === "assistant" && event.status === "completed");
     return {
+        ...(context.importedFromArchive ? { requiresFreshContext: true } : {}),
         chainId: context.chainId,
         baselineHead: context.baselineHead,
         ...(context.baselineHistoryLength === undefined
@@ -2060,6 +2188,22 @@ function projectContext(context) {
             : { baselineHistoryLength: context.baselineHistoryLength }),
         parentHead: context.parentHead,
         playPreset: structuredClone(recordedPlayPrompt(context).playPreset),
+        ...(context.modelBinding === undefined
+            ? {}
+            : {
+                contextWindowTokens: context.lastRequest?.modelConfig?.contextWindowTokens ??
+                    context.modelBinding.contextWindowTokens,
+            }),
+        ...(response?.kind !== "assistant"
+            ? {}
+            : {
+                latestCompletedResponse: {
+                    id: response.id,
+                    ...(response.usage === undefined
+                        ? {}
+                        : { usage: structuredClone(response.usage) }),
+                },
+            }),
         status: context.status,
         canRetry: context.canRetry,
         events: context.events
@@ -2067,6 +2211,9 @@ function projectContext(context) {
             .map((event) => projectActivityEvent(event)),
         changedDocuments: structuredClone(context.changedDocuments),
         lastFailure: context.lastFailure,
+        ...(context.lastFailureKind === undefined
+            ? {}
+            : { lastFailureKind: context.lastFailureKind }),
         updatedAt: context.updatedAt,
     };
 }
@@ -2074,7 +2221,7 @@ function projectActivityEvent(event) {
     if (event.kind === "player" ||
         event.kind === "failure" ||
         event.kind === "cancellation")
-        return structuredClone(event);
+        return structuredClone(projectLegacyModelBindingFailure(event));
     if (event.kind === "assistant") {
         const { reasoning, toolFragment, usage, ...summary } = event;
         void reasoning;
@@ -2219,10 +2366,13 @@ function playerRevisionTimelineGeneration(sourceGeneration, operationId, worldId
         .digest("hex")
         .slice(0, 40)}`;
 }
-function historyEntries(history) {
+function historyEntries(history, backgrounds = {}) {
     return Object.entries(history).map(([path, contents]) => ({
         path,
         contents,
+        ...(backgrounds[path] === undefined
+            ? {}
+            : { background: structuredClone(backgrounds[path]) }),
     }));
 }
 function operationId(chainId, key) {
@@ -2237,7 +2387,8 @@ function assertModelHostBinding(frozen, modelHost) {
 function assertSessionModelHostBinding(session, modelHost) {
     if (session.modelBinding === undefined)
         throw new PlayCallChainError("This model context predates durable provider continuation bindings; start a fresh context.");
-    assertModelHostBinding(session.modelBinding, modelHost);
+    if (session.modelBinding.provider !== modelHost.binding().provider)
+        throw new PlayCallChainError("The selected model protocol differs from this context. Switch back to its original protocol to continue, or start a fresh context.", "model_protocol_mismatch");
 }
 function validateIdentity(value, label) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u.test(value))