narraeon 0.5.2 → 0.5.3

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

@@ -1,7 +1,10 @@
+import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
+import { PlayCallChainError } from "./PlayCallChainError.js";
+import { preparePlayerRevisionTrace, prepareForkTrace, restorePlayDocuments, independentContextCopy, } from "./PlayTraceRetention.js";
 import { currentPlayPrompt, recordedPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
 import { comparePromptPrefixes } from "../prompt/WorldPromptDiagnostics.js";
 import { createHash } from "node:crypto";
-import { completedPlayerRounds, continuationNotice, isPlayerRoundMarker, playerInputAppend, toolStepNotice, } from "./PlayContinuity.js";
+import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepNotice, } from "./PlayContinuity.js";
 import { renderFreshContextCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { renderWriteSizeAdvice, readDeclaredWorldClock, } from "../prompt/WorldMaintenanceReport.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
@@ -13,6 +16,8 @@ import { FileNativePlayDocuments, fingerprintControl, } from "./PlayDocumentTool
 const callChainToolNames = new Set([
     "state_list",
     "history_list",
+    "history_search",
+    "history_read",
     // Kept executable only for contexts whose frozen tool universe contains it.
     "context_list",
     "context_search",
@@ -23,12 +28,7 @@ const callChainToolNames = new Set([
     "world_checkpoint",
 ]);
 const projectedEventTail = 40;
-export class PlayCallChainError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "PlayCallChainError";
-    }
-}
+export { PlayCallChainError } from "./PlayCallChainError.js";
 /**
  * The production play loop: one durable logical context, no Runtime-authored
  * adjudication/narration phases. Responses with tool calls are intermediate
@@ -625,8 +625,7 @@ export class PlayCallChain {
             : null;
         const timelineGeneration = playerRevisionTimelineGeneration(input.source.timelineGeneration, request.operationId, request.worldId, request.continuation);
         const requestFingerprint = playerRevisionRequestFingerprint(request, input.selectedEvent.committedHead, restoresHead);
-        const prefixEvents = structuredClone(sourceContext.events.slice(0, input.selectedEventIndex));
-        const transcript = transcriptThroughEvents(sourceContext.transcript, prefixEvents);
+        const traceRetention = preparePlayerRevisionTrace(sourceContext, input.selectedEventIndex);
         const outcome = await this.#worlds.reviseTimeline({
             operationId: request.operationId,
             worldId: request.worldId,
@@ -636,33 +635,17 @@ export class PlayCallChain {
             replacementText: request.replacementText,
             requestFingerprint,
         });
-        const events = [
-            ...prefixEvents,
-            {
-                id: input.selectedEvent.id,
-                kind: "player",
-                exchangeId: request.replacementExchangeId,
-                text: request.replacementText,
-                context: input.selectedEvent.context,
-                committedHead: outcome.head,
-            },
-        ];
-        const completedKeys = completedToolKeys(prefixEvents);
         const [baseline, selected, binding] = await Promise.all([
             this.#worlds.recoverEndpoint(request.worldId, sourceContext.baselineHead),
             this.#worlds.recoverEndpoint(request.worldId, restoresHead),
             this.#worlds.bindPlayCallChain(request.worldId),
         ]);
-        transcript.push(...playerInputAppend({
-            history: Object.fromEntries(selected.history.map(({ messageId, exactText }) => [
-                messageId,
-                exactText,
-            ])),
-            checkpoint: selected.narrativeCheckpoint,
+        const continuedTrace = traceRetention.withReplacement(selected, {
+            head: outcome.head,
+            exchangeId: request.replacementExchangeId,
             text: request.replacementText,
             locale: this.#compiler.locale,
-            checkpointAvailable: sourceContext.tools.some(({ name }) => name === "world_checkpoint"),
-        }));
+        });
         if (binding.parentHead !== outcome.head)
             throw new PlayCallChainError("The timeline revision was committed, but current-world materialization has not reached the new endpoint.");
         if (request.continuation === "fresh_context") {
@@ -673,7 +656,7 @@ export class PlayCallChain {
                 sourceContext,
                 sourceContexts: input.sourceContexts,
                 selectedContextIndex: input.selectedContextIndex,
-                prefixEvents,
+                traceRetention,
                 baseline,
                 selected,
                 binding,
@@ -694,9 +677,8 @@ export class PlayCallChain {
                 playCallChain: projectView(revised),
             };
         }
-        const documents = restorePlayDocuments(binding.files, sourceContext, prefixEvents);
         const revised = {
-            continuityContextId: sourceContext.continuityContextId ?? sourceContext.chainId,
+            ...continuedTrace.atEndpoint({ baseline, selected, binding }),
             schemaVersion: 3,
             kind: "play_call_chain",
             chainId: playerRevisionChainId(sourceContext.chainId, request.operationId, request.worldId, request.continuation),
@@ -706,44 +688,7 @@ export class PlayCallChain {
                 ? null
                 : input.sourceContexts[input.selectedContextIndex - 1].chainId,
             timelineGeneration,
-            baselineHead: sourceContext.baselineHead,
-            baselineHistoryLength: sourceContext.baselineHistoryLength ?? baseline.history.length,
             parentHead: outcome.head,
-            promptRuns: playPromptRunsThroughEvents(sourceContext, events),
-            ...(sourceContext.presetFiles === undefined
-                ? {}
-                : { presetFiles: structuredClone(sourceContext.presetFiles) }),
-            playPreset: structuredClone(sourceContext.playPreset),
-            ...(sourceContext.followups === undefined
-                ? {}
-                : { followups: structuredClone(sourceContext.followups) }),
-            ...(sourceContext.playPresetScriptsEnabled === undefined
-                ? {}
-                : {
-                    playPresetScriptsEnabled: sourceContext.playPresetScriptsEnabled,
-                }),
-            ...(sourceContext.modelBinding === undefined
-                ? {}
-                : { modelBinding: structuredClone(sourceContext.modelBinding) }),
-            status: "ready",
-            canRetry: false,
-            bootstrap: structuredClone(sourceContext.bootstrap),
-            tools: structuredClone(sourceContext.tools),
-            transcript,
-            events,
-            completedTools: sourceContext.completedTools
-                .filter(({ key }) => completedKeys.has(key))
-                .map((item) => structuredClone(item)),
-            documentAuthorizationCheckpoints: authorizationCheckpointsThroughEvents(sourceContext, events, documents.authorizationCheckpoint()),
-            changedDocuments: changedDocumentsAtHead(sourceContext.changedDocuments, baseline.state, selected.state),
-            nextMaterials: structuredClone(binding.additionalMaterials),
-            nextEventId: Math.max(0, ...events.map(({ id }) => id)) + 1,
-            exchange: Math.max(0, ...prefixEvents
-                .filter((event) => event.kind === "assistant" && event.status === "completed")
-                .map(({ exchange }) => exchange)),
-            lastRequest: null,
-            lastRequestAttempt: 0,
-            lastFailure: null,
             updatedAt: Date.now(),
         };
         await this.#worlds.playTimeline.persist(structuredClone(revised));
@@ -797,12 +742,14 @@ export class PlayCallChain {
         let previousChainId = input.selectedContextIndex === 0
             ? null
             : input.sourceContexts[input.selectedContextIndex - 1].chainId;
-        if (input.prefixEvents.length > 0) {
-            const prefixTranscript = transcriptThroughEvents(sourceContext.transcript, input.prefixEvents);
-            const completedKeys = completedToolKeys(input.prefixEvents);
-            const documents = restorePlayDocuments(input.binding.files, sourceContext, input.prefixEvents);
+        const retainedPrefix = input.traceRetention.pagePrefixAtEndpoint({
+            baseline: input.baseline,
+            selected: input.selected,
+            binding: input.binding,
+        });
+        if (retainedPrefix !== null) {
             const prefix = {
-                continuityContextId: sourceContext.continuityContextId ?? sourceContext.chainId,
+                ...retainedPrefix,
                 schemaVersion: 3,
                 kind: "play_call_chain",
                 chainId: derivedChainId(sourceContext.chainId, "timeline-revision-prefix:" + request.operationId, request.worldId),
@@ -810,42 +757,7 @@ export class PlayCallChain {
                 previousContexts: [],
                 previousChainId,
                 timelineGeneration: input.timelineGeneration,
-                baselineHead: sourceContext.baselineHead,
-                baselineHistoryLength: sourceContext.baselineHistoryLength ?? input.baseline.history.length,
                 parentHead: input.restoresHead,
-                promptRuns: playPromptRunsThroughEvents(sourceContext, input.prefixEvents),
-                ...(sourceContext.presetFiles === undefined
-                    ? {}
-                    : { presetFiles: structuredClone(sourceContext.presetFiles) }),
-                playPreset: structuredClone(sourceContext.playPreset),
-                ...(sourceContext.followups === undefined
-                    ? {}
-                    : { followups: structuredClone(sourceContext.followups) }),
-                ...(sourceContext.playPresetScriptsEnabled === undefined
-                    ? {}
-                    : {
-                        playPresetScriptsEnabled: sourceContext.playPresetScriptsEnabled,
-                    }),
-                ...(sourceContext.modelBinding === undefined
-                    ? {}
-                    : { modelBinding: structuredClone(sourceContext.modelBinding) }),
-                status: "ready",
-                canRetry: false,
-                bootstrap: structuredClone(sourceContext.bootstrap),
-                tools: structuredClone(sourceContext.tools),
-                transcript: prefixTranscript,
-                events: structuredClone(input.prefixEvents),
-                completedTools: sourceContext.completedTools
-                    .filter(({ key }) => completedKeys.has(key))
-                    .map((item) => structuredClone(item)),
-                documentAuthorizationCheckpoints: authorizationCheckpointsThroughEvents(sourceContext, input.prefixEvents, documents.authorizationCheckpoint()),
-                changedDocuments: changedDocumentsAtHead(sourceContext.changedDocuments, input.baseline.state, input.selected.state),
-                nextMaterials: structuredClone(input.selected.additionalMaterials),
-                nextEventId: Math.max(0, ...input.prefixEvents.map(({ id }) => id)) + 1,
-                exchange: completedAssistantExchange(input.prefixEvents),
-                lastRequest: null,
-                lastRequestAttempt: 0,
-                lastFailure: null,
                 updatedAt: Date.now(),
             };
             await this.#worlds.playTimeline.persistDetached(structuredClone(prefix));
@@ -928,20 +840,14 @@ export class PlayCallChain {
                 ? input.targetWorldId
                 : input.sourceWorldId, input.sourceHead),
         ]);
-        const selectsCompleteContext = input.sourceEvents.length === sourceContext.events.length;
-        // A complete context already defines the selected trace closure. Preserve
-        // its model transcript verbatim instead of reconstructing it from the
-        // independently persisted page-event projection.
-        const transcript = selectsCompleteContext
-            ? structuredClone(sourceContext.transcript)
-            : transcriptThroughEvents(sourceContext.transcript, input.sourceEvents);
-        const completedKeys = selectsCompleteContext
-            ? null
-            : completedToolKeys(input.sourceEvents);
-        const events = structuredClone(input.sourceEvents);
+        const traceRetention = prepareForkTrace(sourceContext, input.sourceEvents);
         const derivedBinding = input.targetBinding ??
             (await this.#worlds.bindPlayCallChain(input.targetWorldId));
-        const derivedDocuments = restorePlayDocuments(derivedBinding.files, sourceContext, input.sourceEvents);
+        const retainedTrace = traceRetention.atEndpoint({
+            baseline,
+            selected,
+            binding: derivedBinding,
+        });
         const now = Date.now();
         const timelineGeneration = this.#worlds.playTimeline.newGeneration();
         let previousChainId = null;
@@ -971,7 +877,7 @@ export class PlayCallChain {
             previousChainId = chainId;
         }
         const derived = {
-            continuityContextId: sourceContext.continuityContextId ?? sourceContext.chainId,
+            ...retainedTrace,
             schemaVersion: 3,
             kind: "play_call_chain",
             chainId: derivedChainId(sourceContext.chainId, input.branchIdentity, input.targetWorldId),
@@ -979,44 +885,7 @@ export class PlayCallChain {
             previousContexts: [],
             previousChainId,
             timelineGeneration,
-            baselineHead: sourceContext.baselineHead,
-            baselineHistoryLength: sourceContext.baselineHistoryLength ?? baseline.history.length,
             parentHead: input.sourceHead,
-            promptRuns: playPromptRunsThroughEvents(sourceContext, events),
-            ...(sourceContext.presetFiles === undefined
-                ? {}
-                : { presetFiles: structuredClone(sourceContext.presetFiles) }),
-            playPreset: structuredClone(sourceContext.playPreset),
-            ...(sourceContext.followups === undefined
-                ? {}
-                : { followups: structuredClone(sourceContext.followups) }),
-            ...(sourceContext.playPresetScriptsEnabled === undefined
-                ? {}
-                : {
-                    playPresetScriptsEnabled: sourceContext.playPresetScriptsEnabled,
-                }),
-            ...(sourceContext.modelBinding === undefined
-                ? {}
-                : { modelBinding: structuredClone(sourceContext.modelBinding) }),
-            status: "ready",
-            canRetry: false,
-            bootstrap: structuredClone(sourceContext.bootstrap),
-            tools: structuredClone(sourceContext.tools),
-            transcript,
-            events,
-            completedTools: sourceContext.completedTools
-                .filter(({ key }) => completedKeys === null || completedKeys.has(key))
-                .map((item) => structuredClone(item)),
-            documentAuthorizationCheckpoints: authorizationCheckpointsThroughEvents(sourceContext, events, derivedDocuments.authorizationCheckpoint()),
-            changedDocuments: changedDocumentsAtHead(sourceContext.changedDocuments, baseline.state, selected.state),
-            nextMaterials: structuredClone(derivedBinding.additionalMaterials),
-            nextEventId: Math.max(0, ...events.map(({ id }) => id)) + 1,
-            exchange: Math.max(0, ...events
-                .filter((event) => event.kind === "assistant" && event.status === "completed")
-                .map(({ exchange }) => exchange)),
-            lastRequest: null,
-            lastRequestAttempt: 0,
-            lastFailure: null,
             updatedAt: now,
         };
         if (input.targetWorldRoot === undefined)
@@ -2117,7 +1986,11 @@ function prepareTool(session, working, exchange, call, locale) {
                             failureKind: "protocol",
                             markdown: "world_checkpoint requires an empty argument object.",
                         }
-                    : session.documents.execute(call, session.history);
+                    : session.documents.execute(call, session.history, {
+                        historyScope: session.worldId,
+                        locale,
+                        legacyHistoryTools: hasLegacyHistoryTools(currentPlayPrompt(session).tools),
+                    });
         }
         catch (error) {
             result = {
@@ -2178,53 +2051,6 @@ function mergeChangedDocuments(session, changes) {
             session.changedDocuments[index] = projected;
     }
 }
-function restorePlayDocuments(files, context, events) {
-    const documents = new FileNativePlayDocuments(files);
-    try {
-        const checkpoint = documentAuthorizationThroughEvents(context, events);
-        const runs = playPromptRunsThroughEvents(context, events);
-        if (checkpoint === undefined || runs.length > 0)
-            documents.bindBootstrap(currentPlayPrompt({ ...context, promptRuns: runs }).bootstrap);
-        if (checkpoint !== undefined)
-            documents.restoreAuthorizationCheckpoint(checkpoint.authorization);
-    }
-    catch (error) {
-        throw new PlayCallChainError(`Call-chain document authorization could not be restored: ${error instanceof Error ? error.message : "invalid checkpoint"}。`);
-    }
-    return documents;
-}
-function documentAuthorizationThroughEvents(context, events) {
-    const checkpoints = context.documentAuthorizationCheckpoints;
-    if (checkpoints === undefined || checkpoints.length === 0)
-        return undefined;
-    const selectedEventIds = new Set(events.map(({ id }) => id));
-    const selected = checkpoints.findLast(({ afterEventId }) => afterEventId === 0 || selectedEventIds.has(afterEventId));
-    // Legacy V1 records had no durable dynamic authorization. If the selected
-    // prefix predates their first lazily-written checkpoint, retain the exact
-    // old recovery behavior and rebuild only bootstrap authorization.
-    return selected === undefined ? undefined : structuredClone(selected);
-}
-function independentContextCopy(source) {
-    const context = structuredClone(source);
-    context.continuityContextId ??= source.chainId;
-    delete context.derivedFrom;
-    delete context.branchedBeforePlayer;
-    return context;
-}
-function authorizationCheckpointsThroughEvents(context, events, fallback) {
-    const eventIds = new Set(events.map(({ id }) => id));
-    const selected = (context.documentAuthorizationCheckpoints ?? [])
-        .filter(({ afterEventId }) => afterEventId === 0 || eventIds.has(afterEventId))
-        .map((checkpoint) => structuredClone(checkpoint));
-    if (selected.length > 0)
-        return selected;
-    return [
-        {
-            afterEventId: Math.max(0, ...events.map(({ id }) => id)),
-            authorization: structuredClone(fallback),
-        },
-    ];
-}
 function projectContext(context) {
     return {
         chainId: context.chainId,
@@ -2343,86 +2169,6 @@ function eventsThroughHead(events, head) {
             end += 1;
     return structuredClone(events.slice(0, end));
 }
-function transcriptThroughEvents(transcript, events) {
-    const result = [];
-    let cursor = 0;
-    for (const [index, event] of events.entries()) {
-        if (event.kind === "player") {
-            const marker = transcript[cursor];
-            if (isPlayerRoundMarker(marker)) {
-                result.push(structuredClone(marker));
-                cursor += 1;
-            }
-            const item = transcript[cursor];
-            if (item?.kind !== "player" || item.text !== event.text)
-                throw new PlayCallChainError("Source call-chain events do not match the model transcript, so a fork cannot be created safely.");
-            result.push(structuredClone(item));
-            cursor += 1;
-            continue;
-        }
-        if (event.kind === "assistant" && event.status === "completed") {
-            const notice = transcript[cursor];
-            const hasContinuationNotice = notice?.kind === "runtime_notice" && notice.notice === "continuation";
-            const item = transcript[cursor + (hasContinuationNotice ? 1 : 0)];
-            const hasToolCall = events
-                .slice(index + 1)
-                .find((candidate) => candidate.kind === "player" ||
-                candidate.kind === "assistant" ||
-                candidate.kind === "tool_call");
-            const recorded = event.text.trim().length > 0 ||
-                hasToolCall?.kind === "tool_call" ||
-                item?.kind === "assistant";
-            if (!recorded)
-                continue;
-            if (item?.kind !== "assistant" || item.text !== event.text)
-                throw new PlayCallChainError("Source call-chain responses do not match the model transcript, so a fork cannot be created safely.");
-            // A continuation notice belongs to the generation it precedes, never
-            // to a fork ending at the previously completed narrative.
-            if (hasContinuationNotice) {
-                result.push(structuredClone(notice));
-                cursor += 1;
-            }
-            result.push(structuredClone(item));
-            cursor += 1;
-            continue;
-        }
-        if (event.kind === "tool_result") {
-            const item = transcript[cursor];
-            if (item?.kind !== "tool" || item.toolCallId !== event.callId)
-                throw new PlayCallChainError("Source call-chain tool results do not match the model transcript, so a fork cannot be created safely.");
-            result.push(structuredClone(item));
-            cursor += 1;
-            // A tool-step notice follows the entire settled batch and remains part
-            // of its closure even when the selected endpoint stops at that batch.
-            const notice = transcript[cursor];
-            if (notice?.kind === "runtime_notice" && notice.notice === "tool_step") {
-                result.push(structuredClone(notice));
-                cursor += 1;
-            }
-        }
-    }
-    return result;
-}
-function completedToolKeys(events) {
-    const keys = new Set();
-    let exchange = null;
-    for (const event of events) {
-        if (event.kind === "player")
-            exchange = null;
-        else if (event.kind === "assistant")
-            exchange = event.exchange;
-        else if (event.kind === "tool_call" && exchange !== null)
-            keys.add(`${exchange}:${event.callId}`);
-    }
-    return keys;
-}
-function changedDocumentsAtHead(changes, baseline, selected) {
-    const before = new Map(baseline.map((file) => [file.path, file.contents]));
-    const after = new Map(selected.map((file) => [file.path, file.contents]));
-    return changes
-        .filter(({ path }) => after.has(path) && before.get(path) !== after.get(path))
-        .map((change) => structuredClone(change));
-}
 function derivedChainId(sourceChainId, branchIdentity, targetWorldId) {
     return `play-branch-${createHash("sha256")
         .update(`${sourceChainId}\0${branchIdentity}\0${targetWorldId}`)
@@ -2473,11 +2219,6 @@ function playerRevisionTimelineGeneration(sourceGeneration, operationId, worldId
         .digest("hex")
         .slice(0, 40)}`;
 }
-function completedAssistantExchange(events) {
-    return Math.max(0, ...events
-        .filter((event) => event.kind === "assistant" && event.status === "completed")
-        .map(({ exchange }) => exchange));
-}
 function historyEntries(history) {
     return Object.entries(history).map(([path, contents]) => ({
         path,

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

@@ -0,0 +1,6 @@
+export class PlayCallChainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlayCallChainError";
+    }
+}

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

@@ -1,3 +1,5 @@
+import { HistoryQuery, historyInputs } from "../history/HistoryQuery.js";
+import { renderHistoryMessage, renderHistoryInjectionNotice, } from "../history/HistoryRendering.js";
 /** Narrative history contains only committed original inputs and final prose. */
 export function completedPlayerRounds(history) {
     let pending = false;
@@ -68,21 +70,24 @@ export function playerInputAppend(input) {
         { kind: "player", text: input.text },
     ];
 }
-export function checkpointReplayBlocks(history, checkpoint, locale) {
-    const entries = checkpointHistory(history, checkpoint);
-    if (entries.length === 0)
+export function checkpointReplayBlocks(history, checkpoint, locale, excluded = new Set(), snapshot = new HistoryQuery("checkpoint-replay", historyInputs(Object.entries(history).map(([path, contents]) => ({ path, contents }))))) {
+    const eligible = checkpointHistory(history, checkpoint);
+    if (eligible.length === 0)
         return [];
+    const ids = new Set(eligible.filter(([id]) => !excluded.has(id)).map(([id]) => id));
+    const entries = snapshot.messages.filter(({ id }) => ids.has(id));
     const zh = locale === "zh-CN";
     return [
         {
             source: "runtime:checkpoint-history:notice",
-            markdown: zh
+            markdown: (zh
                 ? "# 检查点后的已提交原文\n\n以下是当前时间线上最近一次已生效检查点之后的玩家原文与最终主持叙事；尚无检查点时从世界起点选取，开场白除外。部分结果可能已写入当前文档；这些记录用于核对连续性，不代表需要再次执行其中的事件。当前明确的世界修订优先，不能用旧叙事推翻修订。"
-                : "# Committed history after the checkpoint\n\nThese are the current timeline’s original player inputs and final narratives after its last effective checkpoint (or the world origin if none, excluding the opening). Some results may already be in current documents. These records support continuity, not repeated execution. Explicit current world corrections take precedence over old narrative.",
+                : "# Committed history after the checkpoint\n\nThese are the current timeline’s original player inputs and final narratives after its last effective checkpoint (or the world origin if none, excluding the opening). Some results may already be in current documents. These records support continuity, not repeated execution. Explicit current world corrections take precedence over old narrative.") +
+                `\n\n${renderHistoryInjectionNotice(snapshot.messages.length, entries, "checkpoint", locale)}`,
         },
-        ...entries.map(([id, text]) => ({
-            source: `runtime:checkpoint-history:${id}`,
-            markdown: `## ${id.endsWith(".player") ? (zh ? "玩家原文" : "Player input") : zh ? "主持叙事" : "Host narrative"}\n\n${text}`,
+        ...entries.map((message) => ({
+            source: `runtime:checkpoint-history:${message.id}`,
+            markdown: renderHistoryMessage(message, locale),
         })),
     ];
 }