narraeon 0.5.5 → 0.5.7

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

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

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

@@ -28,16 +28,7 @@ export function checkpointHistory(history, checkpoint) {
         .slice(cutoff + 1)
         .filter(([id]) => !id.includes("message.genesis"));
 }
-export function playerRoundMarker(rounds, hasCheckpoint, locale) {
-    const markdown = locale === "zh-CN"
-        ? `距上次检查点已完成 ${rounds} 回合。${hasCheckpoint ? "" : "当前尚无检查点，以世界起点计数。"}`
-        : `Completed player rounds since the last checkpoint: ${rounds}.${hasCheckpoint ? "" : " No checkpoint yet; counting from the world origin."}`;
-    return {
-        kind: "runtime_notice",
-        notice: "checkpoint_rounds",
-        text: `${locale === "zh-CN" ? "[Runtime 回合提示]" : "[Runtime round marker]"}\n${markdown}`,
-    };
-}
+/** Retain released markers when reconstructing frozen transcript prefixes. */
 export function isPlayerRoundMarker(item) {
     return item?.kind === "runtime_notice" && item.notice === "checkpoint_rounds";
 }
@@ -59,16 +50,8 @@ export function toolStepNotice(locale) {
             : "[Runtime settlement]\nThe previous response called tools, so its text has not yet been displayed or committed as final story. The tools have settled as their receipts state. Use those receipts to present this turn’s still-unshown content in nonempty final prose with no tool calls, consistent with committed state. Tool settlement does not require advancing the story beyond that content.",
     };
 }
-export function playerInputAppend(input) {
-    return [
-        ...(input.text.trim().length > 0 && input.checkpointAvailable
-            ? [
-                playerRoundMarker(completedPlayerRounds(input.history) -
-                    (input.checkpoint?.completedPlayerRounds ?? 0), input.checkpoint !== undefined, input.locale),
-            ]
-            : []),
-        { kind: "player", text: input.text },
-    ];
+export function playerInputAppend(text) {
+    return [{ kind: "player", text }];
 }
 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);

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

@@ -0,0 +1,20 @@
+import { ModelHostBindingMismatchError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, modelHostFailureRequiresFreshContext, } from "../model/ModelHost.js";
+/** Classification does not grant permission to replay a request. */
+export function classifyPlayFailure(error, canRetry) {
+    if (error instanceof ModelHostOutcomeUnknownError)
+        return "outcome_unknown";
+    if (error instanceof ModelHostContinuationError ||
+        error instanceof ModelHostBindingMismatchError)
+        return "context_unavailable";
+    if (error instanceof ModelHostFailureError) {
+        if (typeof error.details === "object" &&
+            error.details !== null &&
+            "code" in error.details &&
+            error.details.code === "model_output_limit")
+            return "output_limit";
+        if (modelHostFailureRequiresFreshContext(error))
+            return "context_limit";
+        return canRetry ? "retryable" : "provider_error";
+    }
+    return canRetry ? "retryable" : "other";
+}

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

@@ -1,3 +1,4 @@
+import { captureNarrativeOrigin } from "../history/HistoryBackground.js";
 import { FileNativePlayDocuments, } from "./PlayDocumentTools.js";
 import { currentPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
 import { isPlayerRoundMarker, playerInputAppend } from "./PlayContinuity.js";
@@ -12,7 +13,7 @@ export function preparePlayerRevisionTrace(source, eventIndex) {
     const player = source.events[eventIndex];
     return {
         // This append precedes the operation's materialization check, as before.
-        withReplacement(selected, replacement) {
+        withReplacement(replacement) {
             const events = [
                 ...prefix,
                 {
@@ -26,16 +27,7 @@ export function preparePlayerRevisionTrace(source, eventIndex) {
             ];
             const continuedTranscript = [
                 ...transcript,
-                ...playerInputAppend({
-                    history: Object.fromEntries(selected.history.map(({ messageId, exactText }) => [
-                        messageId,
-                        exactText,
-                    ])),
-                    checkpoint: selected.narrativeCheckpoint,
-                    text: replacement.text,
-                    locale: replacement.locale,
-                    checkpointAvailable: source.tools.some(({ name }) => name === "world_checkpoint"),
-                }),
+                ...playerInputAppend(replacement.text),
             ];
             return {
                 atEndpoint(endpoint) {
@@ -93,7 +85,9 @@ function assembleRetainedTrace(source, endpoint, selection) {
         ? null
         : completedToolKeys(selection.toolEvents);
     const documents = restorePlayDocuments(endpoint.binding.files, source, selection.authorizationEvents);
+    const lastEvent = selection.events.at(-1);
     return {
+        ...(source.importedFromArchive ? { importedFromArchive: true } : {}),
         continuityContextId: source.continuityContextId ?? source.chainId,
         baselineHead: source.baselineHead,
         baselineHistoryLength: source.baselineHistoryLength ?? endpoint.baseline.history.length,
@@ -111,6 +105,11 @@ function assembleRetainedTrace(source, endpoint, selection) {
         ...(source.modelBinding === undefined
             ? {}
             : { modelBinding: structuredClone(source.modelBinding) }),
+        ...(lastEvent?.kind === "player" || lastEvent?.kind === "tool_result"
+            ? {
+                narrativeOrigin: captureNarrativeOrigin(documents.snapshot, lastEvent.kind === "player" ? lastEvent.id : lastEvent.id + 1),
+            }
+            : {}),
         status: "ready",
         canRetry: false,
         bootstrap: structuredClone(source.bootstrap),

package/dist/node/runtime/prompt/FileNativePromptCompiler.js

@@ -8,10 +8,12 @@ import { builtinAuthorPrompts, authoringMechanics, } from "../../shared/ordered-
 import { builtinPlayPrompts, } from "../../shared/ordered-play-prompts.js";
 import { parseOrderedPlayPrompts } from "../play/OrderedPlayPrompts.js";
 import { renderDocumentWritePosition } from "./WorldMaintenanceReport.js";
-import { parseDocument, stringify } from "yaml";
+import { parseDocument } from "yaml";
+import { renderWorldYamlSource } from "../world/WorldYamlRendering.js";
+export { renderWorldYamlSource } from "../world/WorldYamlRendering.js";
 import { measureWorldMaterials, refreshMaintenanceTotals, } from "./WorldMaintenanceReport.js";
 import { renderPlayerViewBindings } from "../world/PlayerViewBindings.js";
-import { checkpointHistory, checkpointReplayBlocks, playerInputAppend, isPlayerRoundMarker, } from "../play/PlayContinuity.js";
+import { checkpointHistory, checkpointReplayBlocks, } from "../play/PlayContinuity.js";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 import { WorldDocumentStore, } from "../world/WorldDocumentStore.js";
 import { defaultRuntimeToolDefinitionStrategy, registeredRuntimeToolNames, runtimeToolsForNames, } from "./FileNativeToolRegistry.js";
@@ -52,7 +54,7 @@ ${historyUseGuidance("en")}`,
 
 A nonempty tool-free response ends the model/tool loop started by the current player submission. A response that calls any tool is an intermediate step; its text has not yet been displayed or committed as final story. After all tool results, use the receipts to present this turn's still-unshown content in a later tool-free response consistent with committed state.
 
-The player's next submission may choose a fresh context; the old model transcript will not enter that request. Fresh contexts include all committed original player inputs and final narratives after the last effective world_checkpoint, excluding tools, reasoning, and the opening. A checkpoint declaration takes effect only after the subsequent nonempty tool-free final prose successfully commits, including that prose in its boundary; further tool calls may follow registration. Normal replies need no checkpoint; registration neither ends an in-world event nor switches context. Author instructions decide save timing.
+The player's next submission may choose a fresh context; the old model transcript will not enter that request. Fresh contexts include all committed original player inputs and final narratives after the last effective world_checkpoint, excluding tools, reasoning, and the opening. A checkpoint declaration takes effect only after the subsequent nonempty tool-free final prose successfully commits, including that prose in its boundary; further tool calls may follow registration. Registration neither ends an in-world event nor switches context. Author instructions decide save timing.
 
 Runtime executes only real tool definitions, file validation, and authority commits. This block does not define story content, point of view, style, player agency, or state semantics.
 
@@ -83,7 +85,7 @@ ${historyUseGuidance("zh-CN")}`,
 
 非空且不调用工具的响应会结束本次玩家提交触发的模型／工具循环。只要响应调用了任何工具，它就是工具中间步，其中的文字尚未展示或提交为最终故事。收到全部工具结果后，根据回执在后续无工具响应中呈现本轮尚未展示的内容，并与已提交状态一致。
 
-下一次玩家提交可以选择“全新上下文”；旧模型 transcript 不会进入那个请求。新上下文会补入最近一次已生效 world_checkpoint 之后的全部已提交玩家原文与最终叙事，不含工具、推理和开场白。检查点登记仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。正常回复无需检查点，登记不结束世界内事件，也不自动切换上下文。具体保存时机由作者提示规定。
+下一次玩家提交可以选择“全新上下文”；旧模型 transcript 不会进入那个请求。新上下文会补入最近一次已生效 world_checkpoint 之后的全部已提交玩家原文与最终叙事，不含工具、推理和开场白。检查点登记仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。登记不结束世界内事件，也不自动切换上下文。具体保存时机由作者提示规定。
 
 Runtime 只执行真实工具定义、文件校验和权威提交；本段不规定故事、人称、文风、玩家代理权或状态语义。
 
@@ -371,11 +373,11 @@ export class FileNativePromptCompiler {
         const playCompilation = playPreset === undefined
             ? undefined
             : this.compilePlayCallChain(input, playPreset);
-        return promptPreview(input, playPreset, playCompilation?.bootstrap ?? this.compileBootstrap(input), playCompilation, this.#locale);
+        return promptPreview(input, playPreset, playCompilation?.bootstrap ?? this.compileBootstrap(input), playCompilation);
     }
     previewPlayPreset(input, playPreset) {
         const playCompilation = this.compilePlayPreset(input, playPreset);
-        return promptPreview(input, playPreset, playCompilation.bootstrap, playCompilation, this.#locale);
+        return promptPreview(input, playPreset, playCompilation.bootstrap, playCompilation);
     }
     /**
      * Compile the production play surface. The selected preset contributes its
@@ -907,14 +909,7 @@ function withoutAppendedContextGenesis(input) {
         },
     };
 }
-function promptPreview(input, playPreset, compilation, playCompilation, locale = defaultAppLocale) {
-    const marker = playerInputAppend({
-        history: input.world.history ?? {},
-        checkpoint: input.world.narrativeCheckpoint,
-        text: input.playerInput,
-        locale,
-        checkpointAvailable: playCompilation?.toolUniverse.some(({ name }) => name === "world_checkpoint") ?? false,
-    })[0];
+function promptPreview(input, playPreset, compilation, playCompilation) {
     const result = {
         diagnosticBinding: {
             endpoint: input.endpoint.id,
@@ -935,17 +930,6 @@ function promptPreview(input, playPreset, compilation, playCompilation, locale =
                 initialAppend: {
                     logical: { kind: "player", text: input.playerInput },
                     provider: { role: "user", content: input.playerInput },
-                    ...(isPlayerRoundMarker(marker)
-                        ? {
-                            beforePlayer: {
-                                logical: marker,
-                                provider: {
-                                    role: "user",
-                                    content: marker.text,
-                                },
-                            },
-                        }
-                        : {}),
                 },
             }
             : {}),
@@ -1250,45 +1234,11 @@ function renderSnapshotDocument(snapshot, selector) {
         markdown: renderYamlDocument(read.descriptor, selected.node.value),
     };
 }
-/**
- * Serialize a YAML node exactly the way context_read does, so what bootstrap
- * injects is what a later read would hand back. Internal document ids become
- * the @shortRef handles the model can actually pass to a tool.
- */
-export function renderWorldYamlSource(value) {
-    return stringify(promptYamlValue(value), {
-        indent: 2,
-        lineWidth: 0,
-    }).trimEnd();
-}
 function renderYamlDocument(descriptor, value) {
     if (!isRecord(value))
         throw new PromptCompilationError("world_document_query_failed", "YAML world-document root node must be a map");
     return `## ${descriptor.title} [ref: @${descriptor.shortRef} · YAML]\n\n> ${descriptor.summary}\n\n${renderWorldYamlSource(value)}`;
 }
-function projectedReference(value) {
-    if (!isRecord(value) ||
-        Object.keys(value).length !== 2 ||
-        typeof value.$ref !== "string" ||
-        !isRecord(value.target))
-        return null;
-    return typeof value.target.shortRef === "string"
-        ? { shortRef: value.target.shortRef }
-        : null;
-}
-function promptYamlValue(value) {
-    const reference = projectedReference(value);
-    if (reference !== null)
-        return { $ref: `@${reference.shortRef}` };
-    if (Array.isArray(value))
-        return value.map(promptYamlValue);
-    if (isRecord(value))
-        return Object.fromEntries(Object.entries(value).map(([key, child]) => [
-            key,
-            promptYamlValue(child),
-        ]));
-    return value;
-}
 function throwQueryFailure(failure, operation) {
     throw new PromptCompilationError("world_document_query_failed", `World-document snapshot could not complete the ${operation} query`, {
         requestKind: failure.requestKind,
@@ -1310,6 +1260,9 @@ function resolveContext(input, worldFrame, snapshot, coverage, locale) {
     const history = new HistoryQuery("prompt-compilation", historyInputs(Object.entries(input.world.history ?? {}).map(([path, contents]) => ({
         path,
         contents,
+        ...(input.world.historyBackgrounds?.[path] === undefined
+            ? {}
+            : { background: input.world.historyBackgrounds[path] }),
     }))));
     const excluded = new Set(input.world.historyAlreadyAppended ?? []);
     const checkpointEntries = input.world.replayHistory === true

package/dist/node/runtime/prompt/FileNativeToolRegistry.js

@@ -239,7 +239,7 @@ function createToolDefinitions(locale) {
 }
 const toolDescriptions = {
     en: {
-        world_checkpoint: "Register a consolidation declaration and a history-replay boundary. No arguments. Registration takes effect only after the subsequent nonempty tool-free final prose successfully commits, and includes that prose. A fresh context replays committed player inputs and final narratives after this boundary. The player may choose a fresh context; registration neither switches context nor ends an in-world event. Normal replies need no checkpoint. Further tool calls may follow registration; Runtime does not verify semantic completeness.",
+        world_checkpoint: "Register a gap between events: the previous event has naturally settled at this turn's stopping point, or the scene has actually changed, suggesting that the player start a fresh context here. Arguments must be an empty object. Registration takes effect only after the subsequent nonempty tool-free final prose successfully commits, and includes that prose. A fresh context replays only committed player inputs and final narratives after this boundary, so save still-needed outcomes before registration. Consolidation and maintenance do not require this tool. Do not advance the story to register a checkpoint; registration neither switches context nor ends an in-world event. Further tool calls may follow registration; Runtime does not verify semantic completeness.",
         state_list: "List document and state directory handles known to Runtime. parent must be @dir-/ for the state root or an @dir-* handle from the initial directory index or an earlier state_list result; no preliminary listing is needed for an already supplied handle. Catalog directories declared by the frozen world frame remain listed and usable when empty. A cursor is valid only for the same state snapshot, parent, and limit. Pass returned document handles to context_read. This tool never lists committed history.",
         history_list: "Browse committed history on the current timeline. Omit anchors for the latest page; use only before or after with a Runtime ref (including refs in injected history) for the immediately adjacent page, excluding the anchor. Every page is oldest to newest. limit defaults to 20 (1–100 messages). Previews are only the first 120 Unicode code points. Use independent earlierCursor/laterCursor with {cursor} alone; no first-query parameters on continuation. Cursors bind world, tool, query and immutable ordered history. After history_changed rerun the query. Opening messages are queryable. Read full originals with history_read; positions are snapshot locations, not identities or turns.",
         history_search: "Search committed originals on the current timeline with queries: 1–5 nonempty literal strings (max 256 code points each); no query alias or semantic filters. match defaults to any, or all within one message. NFKC normalization always applies; caseSensitive defaults to false (locale-und case folding), normalized duplicate queries collapse. order defaults to newest_first, or oldest_first. limit defaults to 10 (1–50 matching messages). Optional after/before refs exclude timeline boundaries independently of order; after must precede before. Each result has at most 3 partial original fragments, query occurrence counts and complete-original length. Read a hit and nearby context with history_read. Continue with {cursor} alone; history_changed requires a new query.",
@@ -253,7 +253,7 @@ const toolDescriptions = {
         artifact_clear: "Clear the projection of an artifact that this follow-up declared in advance and explicitly allows to be cleared. The call cannot choose a channel, key, or any other output contract.",
     },
     "zh-CN": {
-        world_checkpoint: "登记整理声明与历史重放边界，参数为空对象。仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；全新上下文补入边界之后的已提交玩家原文与最终叙事。玩家可自行选择全新上下文，登记不切换上下文，也不结束世界内事件。正常回复无需检查点，登记后仍可继续工具调用；Runtime 不认证语义整理完整。",
+        world_checkpoint: "登记事件间隙：上一事件已在本轮停笔位置自然告一段落，或场景已实际转换，建议玩家从这里开始全新上下文。参数为空对象。仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；全新上下文只补入边界之后的已提交玩家原文与最终叙事，因此登记前应已保存后续仍需要的结果。整理与归并不需要调用本工具。不要为了登记而推进剧情；登记不切换上下文，也不结束世界内事件。登记后仍可继续工具调用；Runtime 不认证语义完整。",
         state_list: "列出 Runtime 已知的文档与状态目录句柄。状态根目录的 parent 使用 @dir-/；继续下级时使用初始目录索引或 state_list 返回的 @dir-*；已有句柄无需再次列目录确认。冻结世界 frame 声明的 catalog 目录即使为空，也会继续列出并可用。cursor 只对同一状态快照、parent 和 limit 有效。返回的文档句柄交给 context_read；本工具不列出已提交历史。",
         history_list: "浏览当前时间线已提交历史。无锚点时取最新一页；before 或 after 只能选一个，取锚点紧邻前／后的一页且不含锚点。页内始终由旧到新。limit 默认20，整数1–100。预览仅含前120个Unicode码点；完整原文用history_read。earlierCursor／laterCursor独立翻页，续页只传{cursor}，不可混用首次参数。游标绑定世界、工具、查询和有序历史快照；history_changed须重新查询。开场白可查询。提示词注入中的ref可直接使用，无需再次列举；位置不是身份或回合数。",
         history_search: "搜索当前时间线已提交原文。queries必填：1–5个非空字面词，每词最多256个Unicode码点，不接受query别名或语义筛选。match默认any，all限于同一消息。始终NFKC规范化，caseSensitive默认false（locale-und大小写折叠），规范化重复词合并。order默认newest_first，可选oldest_first；limit默认10，整数1–50条命中消息。after／before始终按时间线先后排除边界，after必须早于before，与结果排序无关。每项最多3个部分原文片段、逐词命中次数及完整原文长度；可用history_read读取前后文。续页只传{cursor}；history_changed须重新查询。",

package/dist/node/runtime/world/FileNativeAuthorityV3.js

@@ -1,3 +1,4 @@
+import { isHistoryBackground, } from "../history/HistoryBackground.js";
 import { createHash, randomUUID } from "node:crypto";
 import { link, mkdir, open, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -799,7 +800,10 @@ function assertHead(value) {
 }
 function isHistoryMessage(value) {
     if (!isRecord(value) ||
-        !hasExactKeys(value, ["messageId", "role", "exactText"]) ||
+        !hasExactKeys(value, ["messageId", "role", "exactText"], ["background"]) ||
+        (value.background !== undefined &&
+            (!isHistoryBackground(value.background) ||
+                (value.role === "player" && value.background.kind !== "snapshot"))) ||
         typeof value.messageId !== "string" ||
         (value.role !== "player" && value.role !== "narrator") ||
         typeof value.exactText !== "string")
@@ -912,9 +916,8 @@ function validRelativePath(path) {
             .split("/")
             .some((part) => part === "" || part === "." || part === ".."));
 }
-function hasExactKeys(value, keys) {
-    return (Object.keys(value).length === keys.length &&
-        keys.every((key) => Object.hasOwn(value, key)));
+function hasExactKeys(value, keys, optional = []) {
+    return (Object.keys(value).every((key) => keys.includes(key) || optional.includes(key)) && keys.every((key) => Object.hasOwn(value, key)));
 }
 function isNarrativeCheckpoint(value, effective) {
     if (!isRecord(value) ||

package/dist/node/runtime/world/FileNativeHistoryProjection.js

@@ -1,4 +1,15 @@
 import { createHash } from "node:crypto";
+export function historyBackgroundRecord(messages) {
+    return Object.fromEntries(messages.flatMap((message) => message.background === undefined
+        ? []
+        : [[message.messageId, structuredClone(message.background)]]));
+}
+export function projectHistoryBackgrounds(messages) {
+    return Object.entries(historyBackgroundRecord(messages)).map(([id, background]) => ({
+        path: `${id}.json`,
+        contents: `${JSON.stringify(background)}\n`,
+    }));
+}
 export function fileNativeHistoryMessageIdFromProjectionPath(path) {
     const match = /^(\d{8})-(\d+)-(player|narrator)-[a-f0-9]{12}\.md$/u.exec(path);
     if (match === null)