narraeon 0.5.2 → 0.5.4

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

@@ -1,3 +1,7 @@
+import { HistoryQuery, historyInputs, historySelectionMatches, } from "../history/HistoryQuery.js";
+import { renderHistoryMessage, renderHistoryInjectionNotice, historyRoleLabel, } from "../history/HistoryRendering.js";
+import { historyUseGuidance } from "../../shared/history-use-guidance.js";
+import { hasLegacyHistoryTools } from "./FileNativeToolRegistry.js";
 import { effectiveFollowupDefinitions } from "../play/OrderedFollowups.js";
 import { legacyAuthorPrompts } from "../play/FileNativePlayPresetStore.js";
 import { builtinAuthorPrompts, authoringMechanics, } from "../../shared/ordered-author-prompts.js";
@@ -35,20 +39,24 @@ const runtimeContracts = {
 - A document marked \`full body injected\` in the material-coverage report already has its complete writable body in the request and carries write authorization. Do not read it again merely to confirm body structure, check body fields, or “be safe.” context_read additionally exposes the current title, summary, and aliases. world_patch preserves metadata fields omitted from set_metadata, so do not read merely to copy unchanged metadata. Read only when a decision depends on unseen metadata or material the report says is not covered.
 - A YAML world_patch locator may mix map keys and zero-based array indexes; remove deletes exactly one existing key or array item. Retire an entity that should leave future frame catalogs with world_retire instead of destroying its document; retired documents remain listed, readable, referenceable, and restorable.
 - Zero literal-search matches do not prove that a fact does not exist. Tools, directories, documents, archives, searches, matches, handles, Runtime, and failure processes are private adjudication details. Player-visible narrative must not mention internal phrases such as “nothing was found.” When information is insufficient, preserve uncertainty inside the world instead of inventing an internal process.
-- World-write tools change only an uncommitted working copy. Their changes are not official world facts until Runtime accepts and completes the commit.`,
+- World-write tools change only an uncommitted working copy. Their changes are not official world facts until Runtime accepts and completes the commit.
+
+${historyUseGuidance("en")}`,
         operation: `# Runtime call-chain rules
 
 - A response with no tool calls may contain player-visible story text and finish the current call-chain step.
-- A response that calls any tool is an intermediate tool step. Do not include player-visible story text in that response. After receiving all tool results, return the story in a later response with no tool calls.
+- A response that calls any tool is an intermediate step; its text is retained in native continuation and diagnostics without being 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.
 - Obey only the real tool definitions attached to this request. A tool that is not defined cannot be called.
 - Runtime performs state commits and saves follow-up artifacts. Tool exchanges and internal processing must never appear in player-visible content.`,
         shell: `# Runtime play boundary
 
-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 and must not contain player-visible story text; continue from the tool results, then finish in a later tool-free response.
+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 its final narrative commits. 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.
 
-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.`,
+${historyUseGuidance("en")}`,
     },
     "zh-CN": {
         play: `# Runtime 权限边界
@@ -62,25 +70,31 @@ Runtime executes only real tool definitions, file validation, and authority comm
 - 材料覆盖报告标为 \`已注入完整正文\` 的文档，其完整可写正文已经在本次请求里，写入资格同样已经具备。不要为确认正文结构、核对正文字段或“保险起见”重读它。context_read 会额外显示当前 title、summary 和 aliases；world_patch 会保留 set_metadata 中未提供的元数据字段，因此不要只为照抄未改变的元数据而读取。只有后续决策确实依赖尚未显示的元数据，或材料覆盖报告未覆盖的内容时才读。
 - YAML world_patch 的 locator 可混合 map key 与从 0 开始的数组下标；remove 只删除一个精确的已有键或数组项。对象需要退出后续 frame catalog 时用 world_retire 退役，不要销毁文档；退役文档仍可列出、读取、引用和恢复。
 - 字面搜索 0 命中不证明事实不存在。工具、目录、文档、档案、检索、命中、句柄、Runtime 及失败过程只供私下裁决；玩家可见叙事不得出现“没搜到／没找到资料”等内部措辞。信息不足时保持世界内的不确定性，不编造内部过程。
-- 世界写入工具只修改尚未提交的工作副本；Runtime 接受并完成提交前，这些修改都不是正式世界事实。`,
+- 世界写入工具只修改尚未提交的工作副本；Runtime 接受并完成提交前，这些修改都不是正式世界事实。
+
+${historyUseGuidance("zh-CN")}`,
         operation: `# Runtime 调用链规则
 
 - 不调用工具的响应可以输出玩家可见故事正文，并结束当前调用链步骤。
-- 只要响应调用了任何工具，它就是工具中间步；该响应不要输出玩家可见故事正文。收到全部工具结果后，再用一个不调用工具的后续响应完成叙事。
+- 只要响应调用了任何工具，它就是中间步；其中的文字保留在原生续传与诊断中，不展示或提交为最终故事。收到全部工具结果后，根据回执在后续无工具响应中呈现本轮尚未展示的内容，并与已提交状态一致。
 - 只服从当前请求的真实工具定义；没有定义的工具不可调用。
 - 状态提交与后置产物保存由 Runtime 执行。工具交换与内部处理过程不得混入玩家可见内容。`,
         shell: `# Runtime 游玩边界
 
-非空且不调用工具的响应会结束本次玩家提交触发的模型／工具循环。只要响应调用了任何工具，它就是工具中间步，不得同时输出玩家可见故事正文；先根据工具结果继续，再用一个不调用工具的后续响应结束。
+非空且不调用工具的响应会结束本次玩家提交触发的模型／工具循环。只要响应调用了任何工具，它就是工具中间步，其中的文字尚未展示或提交为最终故事。收到全部工具结果后，根据回执在后续无工具响应中呈现本轮尚未展示的内容，并与已提交状态一致。
 
-下一次玩家提交可以选择“全新上下文”；旧模型 transcript 不会进入那个请求。新上下文会补入最近一次已生效 world_checkpoint 之后的全部已提交玩家原文与最终叙事，不含工具、推理和开场白。检查点登记只在其最终叙事提交后生效。具体保存时机由作者提示规定。
+下一次玩家提交可以选择“全新上下文”；旧模型 transcript 不会进入那个请求。新上下文会补入最近一次已生效 world_checkpoint 之后的全部已提交玩家原文与最终叙事，不含工具、推理和开场白。检查点登记仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。正常回复无需检查点，登记不结束世界内事件，也不自动切换上下文。具体保存时机由作者提示规定。
 
-Runtime 只执行真实工具定义、文件校验和权威提交；本段不规定故事、人称、文风、玩家代理权或状态语义。`,
+Runtime 只执行真实工具定义、文件校验和权威提交；本段不规定故事、人称、文风、玩家代理权或状态语义。
+
+${historyUseGuidance("zh-CN")}`,
     },
 };
 const playCallChainToolNames = new Set([
     "state_list",
     "history_list",
+    "history_search",
+    "history_read",
     "context_search",
     "context_read",
     "world_patch",
@@ -251,11 +265,14 @@ export class FileNativePromptCompiler {
         return rendered.markdown;
     }
     /** The same selection used by bootstrap, without model or host instructions. */
-    inspectWorldMaterials(world) {
+    inspectWorldMaterials(world, playerInputPlacement) {
         const frame = readYamlRecord(snapshotFiles(world.documentSnapshot)["control/frame.yaml"], "world frame");
         requireFormat(frame, "narraeon.world-frame/v1", "world frame");
         const coverage = [];
-        const materials = resolveContext({ world }, frame, world.documentSnapshot, coverage, this.#locale);
+        const materials = resolveContext({
+            world,
+            ...(playerInputPlacement === undefined ? {} : { playerInputPlacement }),
+        }, frame, world.documentSnapshot, coverage, this.#locale);
         if (world.documentMaintenanceUnavailableReason !== undefined) {
             materials.push({
                 key: "runtime:document-write-positions",
@@ -368,10 +385,24 @@ export class FileNativePromptCompiler {
      */
     compilePlayCallChain(input, binding) {
         const presetCompilation = this.compilePlayPreset(input, binding);
-        const toolUniverse = presetCompilation.toolUniverse.filter(({ name }) => playCallChainToolNames.has(name));
-        const selectedMessages = binding.definition.playPrompts === undefined
+        const frozenTools = input.frozenWorldContext?.toolUniverse ?? input.frozenWorldContext?.tools;
+        const toolUniverse = frozenTools !== undefined && hasLegacyHistoryTools(frozenTools)
+            ? structuredClone(frozenTools)
+            : presetCompilation.toolUniverse.filter(({ name }) => playCallChainToolNames.has(name));
+        const initialMessages = binding.definition.playPrompts === undefined
             ? playCallChainNarrativeGuidance(presetCompilation.bootstrap.logicalMessages, binding)
             : presetCompilation.bootstrap.logicalMessages;
+        const selectedMessages = frozenTools !== undefined && hasLegacyHistoryTools(frozenTools)
+            ? initialMessages.map((message) => {
+                if (message.role !== "runtime_system")
+                    return message;
+                const blocks = message.blocks.map((block) => ({
+                    ...block,
+                    markdown: block.markdown.replace(historyUseGuidance(this.#locale), historyUseGuidance(this.#locale, true)),
+                }));
+                return { ...message, blocks, markdown: joinBlocks(blocks) };
+            })
+            : initialMessages;
         // Instructions keep author order; initial reads follow as protocol tool results.
         const logicalMessages = [
             ...selectedMessages.filter(({ role }) => role !== "world_context" && role !== "player_input"),
@@ -544,7 +575,7 @@ export class FileNativePromptCompiler {
                     : { maintenance: frozen.maintenance }),
             });
         }
-        const materials = this.inspectWorldMaterials(input.world);
+        const materials = this.inspectWorldMaterials(input.world, input.playerInputPlacement);
         const snapshot = input.world.documentSnapshot;
         const declaredDirectories = materials.coverage
             .filter(({ slot }) => slot === "catalog")
@@ -863,7 +894,7 @@ function withoutAppendedContextGenesis(input) {
         if (material.kind !== "history_message" &&
             material.kind !== "history_commit")
             return true;
-        const matches = Object.keys(history).filter((key) => historyMaterialMatches(material, key));
+        const matches = Object.keys(history).filter((key) => historySelectionMatches(material, key));
         // Invalid references still reach the compiler's required-slot validation.
         return matches.length === 0 || matches.some((key) => !excluded.has(key));
     });
@@ -872,7 +903,7 @@ function withoutAppendedContextGenesis(input) {
         world: {
             ...input.world,
             additionalMaterials,
-            history: Object.fromEntries(Object.entries(history).filter(([key]) => !excluded.has(key))),
+            history,
         },
     };
 }
@@ -1276,9 +1307,15 @@ function resolveContext(input, worldFrame, snapshot, coverage, locale) {
     // The model's own list must yield to every author slot, however the frame
     // happens to order them, so resolve it last and splice it back into place.
     let additionalMaterialsAt = null;
-    const replay = input.world.replayHistory === true
-        ? checkpointReplayBlocks(input.world.history ?? {}, input.world.narrativeCheckpoint, locale)
+    const history = new HistoryQuery("prompt-compilation", historyInputs(Object.entries(input.world.history ?? {}).map(([path, contents]) => ({
+        path,
+        contents,
+    }))));
+    const excluded = new Set(input.world.historyAlreadyAppended ?? []);
+    const checkpointEntries = input.world.replayHistory === true
+        ? checkpointHistory(input.world.history ?? {}, input.world.narrativeCheckpoint)
         : [];
+    const replayEntries = checkpointEntries.filter(([id]) => !excluded.has(id));
     for (const entry of context) {
         const selectionStart = selected.length;
         const slot = isRecord(entry) && isRecord(entry.slot) ? entry.slot : null;
@@ -1290,10 +1327,10 @@ function resolveContext(input, worldFrame, snapshot, coverage, locale) {
             resolveReferenceTargets(slot, snapshot, selected, coverage, locale);
         else if (slot.kind === "catalog")
             resolveCatalog(slot, snapshot, selected, coverage, locale);
-        else if (slot.kind === "history" && replay.length > 0)
+        else if (slot.kind === "history" && checkpointEntries.length > 0)
             continue;
         else if (slot.kind === "history")
-            resolveRecentHistory(slot, input.world.history ?? {}, selected, coverage, locale);
+            resolveRecentHistory(slot, history, selected, coverage, locale, excluded);
         else if (slot.kind === "additional_materials")
             additionalMaterialsAt ??= {
                 selected: selected.length,
@@ -1318,9 +1355,13 @@ function resolveContext(input, worldFrame, snapshot, coverage, locale) {
             source: "runtime:player-view-bindings",
             markdown: bindings,
         });
-    if (replay.length > 0) {
-        const entries = checkpointHistory(input.world.history ?? {}, input.world.narrativeCheckpoint);
-        selected.push(...replay.map((block, index) => ({
+    if (checkpointEntries.length > 0) {
+        const selectedIds = new Set(selected.flatMap(({ key }) => key.startsWith("history_message:")
+            ? [key.slice("history_message:".length)]
+            : []));
+        const entries = replayEntries.filter(([id]) => !selectedIds.has(id));
+        const deduplicatedReplay = checkpointReplayBlocks(input.world.history ?? {}, input.world.narrativeCheckpoint, locale, new Set([...excluded, ...selectedIds]), history);
+        selected.push(...deduplicatedReplay.map((block, index) => ({
             ...block,
             key: index === 0
                 ? "history:checkpoint-notice"
@@ -1339,7 +1380,7 @@ function resolveContext(input, worldFrame, snapshot, coverage, locale) {
     if (additionalMaterialsAt !== null) {
         const withMaterials = [...selected];
         const materialCoverage = [];
-        resolveAdditionalMaterials(input.world.additionalMaterials, snapshot, input.world.history ?? {}, withMaterials, materialCoverage, locale);
+        resolveAdditionalMaterials(input.world.additionalMaterials, snapshot, history, withMaterials, materialCoverage, locale, excluded, input.playerInputPlacement === "append");
         selected.splice(additionalMaterialsAt.selected, 0, ...withMaterials.slice(selected.length).map((material) => ({
             ...material,
             ...(additionalMaterialsAt?.slotId === undefined
@@ -1518,7 +1559,7 @@ function validCatalogDirectory(directory) {
  * every detail into a world document, so recent history remains an explicit
  * source alongside the current state.
  */
-function resolveRecentHistory(slot, history, selected, coverage, locale) {
+function resolveRecentHistory(slot, history, selected, coverage, locale, excluded) {
     const recent = Number(slot.recent ?? 2);
     if (!Number.isInteger(recent) || recent < 1 || recent > 32)
         throw new PromptCompilationError("world_frame_invalid", "history slot recent must be an integer from 1 to 32");
@@ -1526,15 +1567,15 @@ function resolveRecentHistory(slot, history, selected, coverage, locale) {
     // in commit order. Its keys are semantic message IDs, not sortable file
     // names: lexical sorting would put `message.genesis` after every numbered
     // message and `message.9` after `message.15`.
-    const ordered = Object.entries(history).filter(([ref]) => !ref.endsWith("message.genesis.narrator"));
-    const chosen = ordered.slice(-recent);
+    const ordered = history.messages.filter(({ isOpening }) => !isOpening);
+    const chosen = ordered.slice(-recent).filter(({ id }) => !excluded.has(id));
     if (chosen.length === 0) {
         selected.push({
             key: "history:empty",
             source: "slot:history:empty",
             markdown: locale === "zh-CN"
-                ? "# 最近已提交对话\n\n（空：当前世界没有更早的玩家原文或主持叙事；无需为寻找上一条记录调用历史检索工具。）"
-                : "# Recent committed conversation\n\n(Empty: this world has no earlier player input or host narrative. Do not call history tools merely to look for a previous message.)",
+                ? `# 最近已提交对话\n\n${renderHistoryInjectionNotice(history.messages.length, [], "recent", locale)}\n（本次没有可注入的非开场白原文：可能只有开场白，或近期材料已在原生对话中。无需为寻找上一条记录例行调用历史检索工具。）`
+                : `# Recent committed conversation\n\n${renderHistoryInjectionNotice(history.messages.length, [], "recent", locale)}\n(No non-opening originals selected for injection: only the opening exists, or recent entries are already in native conversation. Do not call history tools merely to look for a previous message.)`,
         });
         coverage.push({
             slot: "history",
@@ -1545,27 +1586,35 @@ function resolveRecentHistory(slot, history, selected, coverage, locale) {
         });
         return;
     }
-    for (const [index, [ref, text]] of chosen.entries()) {
+    const missing = chosen.filter(({ id }) => overlappingSelection(selected, `history_message:${id}`) === null);
+    if (missing.length > 0)
+        selected.push({
+            key: "history:recent-notice",
+            source: "slot:history:notice",
+            markdown: renderHistoryInjectionNotice(history.messages.length, missing, "recent", locale),
+        });
+    for (const [index, message] of missing.entries()) {
+        const ref = message.id;
         const key = `history_message:${ref}`;
         if (overlappingSelection(selected, key) !== null)
             continue;
         selected.push({
             key,
             source: `slot:history:${ref}`,
-            markdown: renderHistoryMessage(ref, text, locale),
+            markdown: renderHistoryMessage(message, locale),
         });
         coverage.push({
             slot: "history",
             source: locale === "zh-CN"
-                ? `${historyMessageLabel(ref, locale)}（最近记录 ${index + 1}/${chosen.length}）`
-                : `${historyMessageLabel(ref, locale)} (recent ${index + 1}/${chosen.length})`,
+                ? `${historyRoleLabel(message, locale)}（最近记录 ${index + 1}/${chosen.length}）`
+                : `${historyRoleLabel(message, locale)} (recent ${index + 1}/${chosen.length})`,
             status: "resolved",
             complete: true,
             continuation: "history_list",
         });
     }
 }
-function resolveAdditionalMaterials(materials, snapshot, history, selected, coverage, locale) {
+function resolveAdditionalMaterials(materials, snapshot, history, selected, coverage, locale, excluded, excludeOpening) {
     if (materials.length > 32)
         throw new PromptCompilationError("material_limit_exceeded", "Additional material exceeds 32 items");
     for (const material of materials) {
@@ -1580,21 +1629,27 @@ function resolveAdditionalMaterials(materials, snapshot, history, selected, cove
             const ref = material.kind === "history_message"
                 ? material.message
                 : material.commit;
-            const matches = Object.entries(history).filter(([key]) => historyMaterialMatches(material, key));
+            const matches = history.messages.filter(({ id }) => historySelectionMatches(material, id));
             if (matches.length === 0)
                 throw new PromptCompilationError("required_slot_missing", `Additional history material does not exist: ${ref}`);
-            const missing = matches.filter(([id]) => !selected.some(({ key }) => key === `history_message:${id}`));
+            const missing = matches.filter(({ id, isOpening }) => !excluded.has(id) &&
+                !(excludeOpening && isOpening) &&
+                !selected.some(({ key }) => key === `history_message:${id}`));
             if (missing.length === 0)
                 continue;
-            selected.push(...missing.map(([id, text]) => ({
-                key: `history_message:${id}`,
-                source: `slot:additional_materials:${id}`,
-                markdown: renderHistoryMessage(id, text, locale),
+            selected.push({
+                key: `history:additional-notice:${selected.length}`,
+                source: "slot:additional_materials:history-notice",
+                markdown: renderHistoryInjectionNotice(history.messages.length, missing, "additional", locale),
+            }, ...missing.map((message) => ({
+                key: `history_message:${message.id}`,
+                source: `slot:additional_materials:${message.id}`,
+                markdown: renderHistoryMessage(message, locale),
             })));
             coverage.push({
                 slot: "additional_materials",
                 source: matches.length === 1
-                    ? historyMessageLabel(matches[0][0], locale)
+                    ? historyRoleLabel(matches[0], locale)
                     : locale === "zh-CN"
                         ? `已选历史提交（${matches.length} 条）`
                         : `selected history commit (${matches.length} messages)`,
@@ -1605,32 +1660,6 @@ function resolveAdditionalMaterials(materials, snapshot, history, selected, cove
         }
     }
 }
-function historyMaterialMatches(material, key) {
-    if (material.kind === "history_message")
-        return (historyMaterialIdentity(key) === historyMaterialIdentity(material.message));
-    const ref = material.commit;
-    return ref.startsWith("commit:")
-        ? historyMaterialIdentity(key).startsWith(`message.${ref.slice(7)}.`)
-        : ref === "genesis"
-            ? historyMaterialIdentity(key).startsWith("message.genesis.")
-            : key.startsWith(ref.replace(/^@?history-commit-/u, "history-message-").concat("-"));
-}
-function historyMaterialIdentity(ref) {
-    const value = ref.replace(/^@?(?:history-message-)?/u, "");
-    return (/(?:^|\.)(message\.(?:genesis|[0-9]+)(?:\.[0-9]+)?\.(?:player|narrator))$/u.exec(value)?.[1] ?? value);
-}
-function renderHistoryMessage(ref, text, locale) {
-    return `## ${historyMessageLabel(ref, locale)}\n\n${text.trim()}`;
-}
-function historyMessageLabel(ref, locale) {
-    if (ref.endsWith("message.genesis.narrator"))
-        return locale === "zh-CN" ? "开场白" : "Opening";
-    if (/(?:^|\.)message\.[^.]+(?:\.[0-9]+)?\.player$|(?:^|-)player(?:-|$)/u.test(ref))
-        return locale === "zh-CN" ? "玩家原文" : "Player input";
-    if (/(?:^|\.)message\.[^.]+(?:\.[0-9]+)?\.narrator$|(?:^|-)narrator(?:-|$)/u.test(ref))
-        return locale === "zh-CN" ? "主持叙事" : "Host narrative";
-    return locale === "zh-CN" ? "已提交消息" : "Committed message";
-}
 function addNodeSelection(target, locator, slot, required, snapshot, selected, coverage, dedupe = false, locale = defaultAppLocale) {
     let exactLocator = null;
     if (isRecord(locator) && Array.isArray(locator.yaml)) {

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

@@ -1,3 +1,4 @@
+import { historyUseGuidance } from "../../shared/history-use-guidance.js";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 /**
  * Runtime-owned prompt tool registry.
@@ -9,6 +10,8 @@ import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 export const registeredRuntimeToolNames = [
     "state_list",
     "history_list",
+    "history_search",
+    "history_read",
     "context_search",
     "context_read",
     "world_patch",
@@ -19,7 +22,7 @@ export const registeredRuntimeToolNames = [
     "artifact_clear",
 ];
 /** Changes only when the executable Runtime tool universe or schemas change. */
-export const runtimeToolRegistryRevision = "runtime-tools-v8";
+export const runtimeToolRegistryRevision = "runtime-tools-v9";
 export function defaultRuntimeToolDefinitionStrategy(provider) {
     return provider === "openai_responses"
         ? "native_allowed_subset"
@@ -95,17 +98,45 @@ function createToolDefinitions(locale) {
             }, ["parent"]),
         },
         history_list: {
-            description: descriptions.history_list,
+            description: descriptions.history_list + " " + historyUseGuidance(locale),
             inputSchema: object({
-                order: { enum: ["newest_first", "oldest_first"] },
-                cursor: { type: ["string", "null"] },
+                before: string,
+                after: string,
                 limit: { type: "integer", minimum: 1, maximum: 100 },
-            }, ["order"]),
+                cursor: string,
+            }, []),
+        },
+        history_search: {
+            description: descriptions.history_search + " " + historyUseGuidance(locale),
+            inputSchema: object({
+                queries: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 5,
+                    items: { type: "string", minLength: 1, maxLength: 256 },
+                },
+                match: { enum: ["any", "all"] },
+                order: { enum: ["newest_first", "oldest_first"] },
+                caseSensitive: { type: "boolean" },
+                after: string,
+                before: string,
+                limit: { type: "integer", minimum: 1, maximum: 50 },
+                cursor: string,
+            }, []),
+        },
+        history_read: {
+            description: descriptions.history_read + " " + historyUseGuidance(locale),
+            inputSchema: object({
+                latest: { type: "integer", minimum: 1, maximum: 21 },
+                ref: string,
+                before: { type: "integer", minimum: 0, maximum: 20 },
+                after: { type: "integer", minimum: 0, maximum: 20 },
+            }, []),
         },
         context_search: {
             description: descriptions.context_search,
             inputSchema: object({
-                source: { enum: ["state", "history"] },
+                source: { const: "state" },
                 query: { type: "string", minLength: 1, maxLength: 256 },
                 caseSensitive: { type: "boolean" },
                 within: string,
@@ -208,11 +239,13 @@ function createToolDefinitions(locale) {
 }
 const toolDescriptions = {
     en: {
-        world_checkpoint: "Declare that the necessary state maintenance for this turn is complete and suggest starting a fresh context. No arguments. Registration becomes effective only when this turn’s final tool-free response commits, including that response in the checkpoint. This is your declaration, not Runtime verification or an automatic context switch. Further tool calls are allowed before the final nonempty tool-free response.",
+        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.",
         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: "List handles for committed history messages known to Runtime. order must be newest_first or oldest_first. A cursor is valid only for the same committed-history snapshot, order, and limit. Pass returned @history-message-* handles to context_read. This tool never lists the mutable state directory.",
-        context_search: "Search literal source text in state or history. Zero matches means only that the supplied text had no literal match; it does not prove that a world fact does not exist. Player-visible narrative must not recount the search process. within accepts only an @document or @dir-* handle returned by Runtime.",
-        context_read: "Read the complete content of an @document, @node, or @history-message-* handle previously returned by Runtime. The read heading, metadata boundaries, body boundaries, scope, and completion marker in the result are not source text. set_metadata may include only the fields that must change; Runtime preserves omitted metadata fields. Update the writable body between the boundaries with locators. YAML bodies omit the $document technical header; Markdown bodies begin at the document's level-one heading. Results are never truncated or paginated. Never pass file paths, natural-language names, or an invented world/... value.",
+        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.",
+        history_read: "Read complete committed originals on the current timeline, never summarized, truncated or body-paginated. Use {latest:N} alone (1–21 messages), or {ref,before,after} with defaults before=after=0 and sum at most 20; do not mix modes. Ref may come directly from Runtime prompt injections or tools without listing first. Windows are always oldest to newest, including the anchor. earlier/later are immediately outside this window and can be the next ref with before/after to avoid rereading. Boundaries and empty history are normal. Counts are messages, not turns; 21 long messages can produce large output.",
+        context_search: "Search literal source text in state documents. Use source=state; committed history uses history_search. Zero matches means only that the supplied text had no literal match; it does not prove that a world fact does not exist. Player-visible narrative must not recount the search process. within accepts only an @document or @dir-* handle returned by Runtime.",
+        context_read: "Read the complete content of an @document or @node handle previously returned by Runtime. The read heading, metadata boundaries, body boundaries, scope, and completion marker in the result are not source text. set_metadata may include only the fields that must change; Runtime preserves omitted metadata fields. Update the writable body between the boundaries with locators. YAML bodies omit the $document technical header; Markdown bodies begin at the document's level-one heading. Results are never truncated or paginated. Never pass file paths, natural-language names, or an invented world/... value.",
         world_patch: 'Update a document that has been read precisely or whose complete body was injected with write authorization. target must be an @short-ref. When title, summary, or aliases are stale, use set_metadata and include only the title, summary, or aliases that must change. At least one is required; Runtime preserves omitted fields from the current candidate document. A YAML edit uses locator:{yaml:["field","child"]}, for example {op:"replace",locator:{yaml:["status"]},value:"new value"}. Locator segments address map keys or a zero-based array index; remove deletes exactly the existing key or array item at its locator. A YAML value may reference a whole document only as {$ref:"@short-ref"}; the short reference must come from a Runtime list, read, or create result. Never invent a document id. If no handle is available, use ordinary text when semantically correct or call world_create first and use its returned @short-ref. To add an item to the end of an existing sequence, use append with the locator pointing to that sequence; add creates only a map key or list index that does not exist. A Markdown locator excludes the document level-one heading: {markdown:["Responsibilities"]} points exactly to ## Responsibilities, and replace_section.markdown must begin with the same heading at the same level. Use replace_preamble for text after the level-one heading and before the first level-two heading; send only that text. Use replace_body to replace the whole Markdown body and retain the original level-one heading. Success reports only whether the document changed and does not echo the body. Call context_read again only when a later decision depends on Runtime\'s exact serialized body or current metadata. Do not use path, JSON Pointer, set, or a file name.',
         world_create: 'Create a document inside a Runtime-known state directory. parent must be an @dir-* handle supplied by the initial directory index or state_list, such as @dir-/characters; catalog directories declared by the frozen world frame remain available when empty, and @dir-/ is the root. A syntactically valid but unknown directory is rejected. refHint is a lowercase ASCII short-reference hint, not a world/ path. A YAML body may reference a whole document only as {$ref:"@short-ref"}, and the short reference must come from a Runtime list, read, or create result. Never invent a document id.',
         world_retire: "Retire or restore an exact state document without deleting its narrative record. target must be an @short-ref that was read precisely or injected completely. retired:true removes the document from future frame catalog injection but keeps it listed, searchable, readable, referenceable, and restorable; retired:false restores catalog participation. This changes catalog participation, not explicit full-document injection or character activity; use world_patch for ordinary location or field changes.",
@@ -220,11 +253,13 @@ 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: "声明本轮必要状态已整理完成，并建议玩家在此开启全新上下文。参数为空对象。登记仅在本轮最终无工具响应提交后生效，检查点包含该响应。这是 AI 的整理声明，不是 Runtime 完整性认证，也不会自动切换上下文。最终非空且无工具调用的响应之前，仍可继续调用工具。",
+        world_checkpoint: "登记整理声明与历史重放边界，参数为空对象。仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；全新上下文补入边界之后的已提交玩家原文与最终叙事。玩家可自行选择全新上下文，登记不切换上下文，也不结束世界内事件。正常回复无需检查点，登记后仍可继续工具调用；Runtime 不认证语义整理完整。",
         state_list: "列出 Runtime 已知的文档与状态目录句柄。状态根目录的 parent 使用 @dir-/；继续下级时使用初始目录索引或 state_list 返回的 @dir-*；已有句柄无需再次列目录确认。冻结世界 frame 声明的 catalog 目录即使为空，也会继续列出并可用。cursor 只对同一状态快照、parent 和 limit 有效。返回的文档句柄交给 context_read；本工具不列出已提交历史。",
-        history_list: "列出 Runtime 已知的已提交历史消息句柄。order 必须是 newest_first 或 oldest_first；cursor 只对同一历史快照、order 和 limit 有效。返回的 @history-message-* 交给 context_read；本工具不列出可变状态目录。",
-        context_search: "在 state 或 history 的原文字面中搜索。0 命中只表示给定文本没有字面命中，不证明世界事实不存在；玩家可见叙事不得复述搜索过程。within 只能使用 Runtime 已返回的 @文档或 @dir-* 句柄。",
-        context_read: "完整读取 Runtime 先前返回的 @文档、@节点或 @history-message-* 句柄。结果中的读取标题、元信息边界、正文边界、范围和完整标记不属于源文；set_metadata 可以只提交需要改变的字段，Runtime 会保留未提供的元数据字段。中间的可写正文用 locator 更新。YAML 正文不含 $document 技术头，Markdown 正文从文档 # 一级标题开始。结果不会截断或分页。不要传文件路径、自然语言名称或自行拼造的 world/...。",
+        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须重新查询。",
+        history_read: "完整读取当前时间线已提交原文，无摘要、无截断、无正文分页。{latest:N}单独读取最近1–21条；或{ref,before,after}，before／after默认0且合计最多20；两模式互斥。ref可直接使用Runtime提示词注入或工具结果的历史句柄，不必先列举。窗口始终由旧到新且包含锚点。earlier／later是窗口外紧邻句柄，可作为下一次ref并配before／after避免重复读取；边界与空历史正常。数量单位是消息而非回合；21条长消息仍可能产生大量输出。",
+        context_search: "在状态文档原文字面中搜索，source只能为state；已提交历史使用history_search。0 命中只表示给定文本没有字面命中，不证明世界事实不存在；玩家可见叙事不得复述搜索过程。within 只能使用 Runtime 已返回的 @文档或 @dir-* 句柄。",
+        context_read: "完整读取 Runtime 先前返回的 @文档或@节点句柄。结果中的读取标题、元信息边界、正文边界、范围和完整标记不属于源文；set_metadata 可以只提交需要改变的字段，Runtime 会保留未提供的元数据字段。中间的可写正文用 locator 更新。YAML 正文不含 $document 技术头，Markdown 正文从文档 # 一级标题开始。结果不会截断或分页。不要传文件路径、自然语言名称或自行拼造的 world/...。",
         world_patch: '更新已精确读取，或已随写入资格注入完整正文的文档。target 必须使用 @短引用；文档 title、summary 或 aliases 过时时使用 set_metadata，只提供需要改变的 title、summary 或 aliases。至少提供一项；未提供的字段由 Runtime 从当前候选文档保留。YAML edit 使用 locator:{yaml:["字段","子字段"]}，例如 {op:"replace",locator:{yaml:["情况"]},value:"新值"}。locator 的每一段可以定位 map key 或从 0 开始的数组下标；remove 只删除 locator 精确指向的已有键或数组项。YAML value 需要引用整份文档时只能写 {$ref:"@短引用"}，短引用必须来自 Runtime 的 list、read 或 create 结果；不得自行编造文档 id。没有可用句柄时，根据语义使用普通文本，或先 world_create 后使用其返回的 @短引用。向已存在的 sequence 末尾加一项必须使用 append 并把 locator 指向该 sequence；add 只创建尚不存在的 map key 或 list index。Markdown locator 不包含文档 # 一级标题：{markdown:["职责"]} 精确指向 ## 职责，replace_section.markdown 必须从同级同名标题开始。修改 # 标题下、第一个 ## 前的文字用 replace_preamble（只传该段文字）；替换整个 Markdown 正文用 replace_body，且 markdown 必须保留原 # 一级标题。成功结果只报告文档是否发生变化，不回显正文；只有后续决策依赖 Runtime 序列化后的精确正文或当前元数据时才重新 context_read。不要使用 path、JSON Pointer、set 或文件名。',
         world_create: '在 Runtime 已知的状态目录中创建文档。parent 必须是初始目录索引或 state_list 列出的 @dir-*，例如 @dir-/characters；冻结世界 frame 声明的 catalog 目录为空时仍然可用，根目录使用 @dir-/。只有句柄形式正确但 Runtime 并不知道的目录会被拒绝。refHint 是小写 ASCII 短引用，不要传 world/ 路径。YAML body 需要引用整份文档时只能写 {$ref:"@短引用"}，且短引用必须来自 Runtime 的 list、read 或 create 结果；不得自行编造文档 id。',
         world_retire: "让一份精确状态文档退役或恢复，而不销毁叙事记录。target 必须是已精确读取或已完整注入的 @短引用。retired:true 会让文档不再进入后续 frame catalog 注入，但仍可列出、搜索、读取、引用和恢复；retired:false 恢复 catalog 参与。它只改变 catalog 参与，不取消显式全文注入、不冻结人物活动；普通位置或字段变化仍用 world_patch。",
@@ -232,3 +267,12 @@ const toolDescriptions = {
         artifact_clear: "清除本次后置请求预先声明且允许 clear 的产物投影；不能选择频道、key 或其他输出契约。",
     },
 };
+export function hasLegacyHistoryTools(tools) {
+    return tools.some(({ name, inputSchema }) => {
+        const schema = inputSchema;
+        return (name === "context_list" ||
+            (name === "history_list" && schema.properties?.order !== undefined) ||
+            (name === "context_search" &&
+                schema.properties?.source?.enum?.includes("history") === true));
+    });
+}

package/dist/node/shared/default-play-prompts.js

@@ -15,11 +15,13 @@ export const defaultNarrationPromptZhCN = `# 玩家可见叙事规则
 
 本轮新发生且玩家能感知的结果，要成为具体可读的事：物品怎样递接、人物如何离开、态度变化怎样在话语或行动中显露。文档中补录旧结果、去重和整理不要求再次演出。界面数值不能代替事件表现，叙事也不能与当前值冲突。未向玩家表露的判断和场外事实无需用旁白揭露。
 
-具体表演细节随最终叙事保存，可按需追溯；不要假定每次请求自动带着全部旧段落。必须持续保存的结果按状态维护政策处理，不能只留在检查点收尾原文中。
+具体表演细节随最终叙事保存，可按需追溯；不要假定每次请求自动带着全部旧段落。必须持续保存的结果按状态维护政策处理，不能只留在检查点覆盖的最终原文中。
 
 ## 停在哪里
 
-在当前行动与反应形成有内容的局面、或下一次关键选择需要玩家时停笔。具体人物动作、原话或环境变化都可以承接下一段；有意义的沉默、独处、休息和等待也可以自然结束。不要为了结尾形式让 NPC 硬添动作、邀请或承诺。
+先按本次玩家授权和互动需要确定停笔位置。持续活动中，新反馈会影响玩家如何接话、调整或继续时，呈现反馈并留下回应机会，即使不涉及重大决定。开始按腿、教学或交谈不默认授权包办全过程；普通走路、敲门、递送的连带动作可以自然完成，明确要求略过过程或做到某个终点时则在授权内推进。
+
+当前行动与反应形成有内容的局面便可以停笔；具体动作、原话或环境变化都可以承接下一段，有意义的沉默、独处、休息和等待也可以自然结束。回复结束与截至此刻整理完成都不要求世界内事件结束，检查点适应停笔位置。不要为了结尾形式让 NPC 硬添动作、邀请或承诺。
 
 避免“轮到你了”“你打算怎么做”及把同一句套话改成“众人等你开口”的机械交接，也不要在结尾列选项或重复总结局势。真正发生的注视或等待可以描写，不必强行消除。
 
@@ -29,7 +31,7 @@ export const defaultNarrationPromptZhCN = `# 玩家可见叙事规则
 
 本次只有世界外查询或维护时，按请求简洁回答或说明整理结果，不为满足小说形式添加动作、对话或时间推进。混合请求中的维护要求不成为角色台词或行动。
 
-玩家的关键决定仍归玩家；表现自然感官与动作细节不能替他表达立场、感情、同意或承诺。已经提交的行动不能用一句普通改口当作从未发生。
+玩家的决定与回应仍归玩家；表现自然感官与动作细节不能替他表达立场、感情、同意或承诺。已经提交的行动不能用一句普通改口当作从未发生。
 `;
 export const defaultNarrationPromptEn = `# Player-visible narrative rules
 
@@ -41,11 +43,13 @@ When there is new player input, naturally stage its explicit action or dialogue
 
 Make new perceivable outcomes this turn concrete: an object handed over, a person leaving, an attitude expressed through words or action. Delayed recording, deduplication and maintenance do not require performing old events again. Interface values do not replace dramatization, and prose must agree with current values. Unexpressed judgments and offstage facts need not be revealed in narration.
 
-Specific performance details are saved with final narrative and can be retrieved when needed; do not assume every request automatically includes every earlier passage. Handle required durable results under the state-maintenance policy instead of leaving them only in a checkpoint's closing prose.
+Specific performance details are saved with final narrative and can be retrieved when needed; do not assume every request automatically includes every earlier passage. Handle required durable results under the state-maintenance policy instead of leaving them only in the final prose covered by a checkpoint.
 
 ## Where to stop
 
-Stop when the action and reactions form a meaningful situation or a consequential choice needs the player. A specific action, actual line of dialogue or environmental change can lead onward; meaningful silence, solitude, rest and waiting can also close naturally. Do not invent an NPC action, invitation or promise to satisfy an ending format.
+First choose where to stop from the player's authorization and the interaction's needs. During an ongoing activity, when new feedback could affect how the player replies, adjusts or continues, present it and leave room to respond even without a consequential decision. Starting a leg massage, lesson or conversation does not by itself authorize the entire activity; ordinary supporting actions in walking, knocking or delivering can complete naturally. Explicit requests to skip the process or reach an endpoint allow advancement within that authorization.
+
+You may stop once action and reactions form a meaningful situation. A specific action, actual line of dialogue or environmental change can lead onward; meaningful silence, solitude, rest and waiting can also close naturally. Ending a reply or consolidating records through this moment does not require ending the in-world event; fit checkpoint maintenance to the stopping point. Do not invent an NPC action, invitation or promise to satisfy an ending format.
 
 Avoid mechanical handoffs such as “Your turn”, “What do you do?” or their stock substitute “Everyone waits for you to speak”. Do not end by listing options or repeating a situation summary. Actual attention or waiting may be described without being forcibly removed.
 
@@ -55,7 +59,7 @@ In-world narrative uses only the novel's prose, in several natural paragraphs if
 
 If this request is solely out-of-world inquiry or maintenance, answer or explain the consolidation briefly as requested without adding actions, dialogue or time passage to satisfy novel form. Maintenance instructions within a mixed request do not become character speech or actions.
 
-Consequential decisions belong to the player. Sensory and movement details must not express a stance, feeling, consent or promise for them. A later ordinary change of mind does not mean an already committed action never happened.
+Decisions and responses belong to the player. Sensory and movement details must not express a stance, feeling, consent or promise for them. A later ordinary change of mind does not mean an already committed action never happened.
 `;
 export const defaultNarrationPrompt = defaultNarrationPromptEn;
 export function defaultNarrationPromptForLocale(locale) {