narraeon 0.7.7 → 0.7.9

package/dist/node/runtime/authoring/AuthoringRequestSnapshot.js

@@ -1,4 +1,15 @@
 import { isPlayPresetBinding, } from "../play/FileNativePlayPresetStore.js";
+export function isAuthoringPreloadRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (Object.keys(record).length === 3 &&
+        typeof record.revision === "string" &&
+        Array.isArray(record.worldDocumentIds) &&
+        record.worldDocumentIds.every((id) => typeof id === "string") &&
+        Array.isArray(record.opaquePaths) &&
+        record.opaquePaths.every((path) => typeof path === "string"));
+}
 export function validAuthoringRequests(value, validPrompt, session) {
     if (!Array.isArray(value) ||
         value.length === 0 ||
@@ -14,7 +25,9 @@ export function validAuthoringRequests(value, validPrompt, session) {
         if (typeof raw !== "object" || raw === null || Array.isArray(raw))
             return false;
         const item = raw;
-        if (Object.keys(item).length !== 4 ||
+        const keys = Object.keys(item).length;
+        if ((keys !== 4 && !(keys === 5 && "preload" in item)) ||
+            (item.preload !== undefined && !isAuthoringPreloadRecord(item.preload)) ||
             typeof item.requestId !== "string" ||
             !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/u.test(item.requestId) ||
             ids.has(item.requestId) ||

package/dist/node/runtime/history/HistoryRendering.js

@@ -1,5 +1,15 @@
 import { isDeepStrictEqual } from "node:util";
 import { parseDocument } from "yaml";
+/** Scope and total only; ordering and continuation rules live in tool descriptions. */
+function compactHeader(total, locale) {
+    const zh = locale === "zh-CN";
+    return `Scope: ${zh ? "当前时间线" : "current timeline"}\n${zh ? "本次读取快照消息总数" : "Snapshot total messages"}: ${total}`;
+}
+/** Position, role and ref only; role=x would repeat the localized role label. */
+function compactMessageLabel(message, locale) {
+    const zh = locale === "zh-CN";
+    return `${zh ? "位置" : "position"} ${message.position} · ${historyRoleLabel(message, locale)}${message.isOpening ? " · isOpening=true" : ""} · ${message.ref} · ${message.length} Unicode code points`;
+}
 /** Shared metadata keeps injected refs and tool results directly navigable. */
 export function historyMessageLabel(message, locale) {
     const zh = locale === "zh-CN";
@@ -58,18 +68,26 @@ export function renderHistoryResult(result, locale = "en", legacyRead = false) {
     if (result.kind === "list")
         return {
             ok: true,
-            markdown: `# ${zh ? "已提交历史列表" : "Committed history listing"}\n\n${header}\nOrder: oldest_first (${zh ? "页内始终由旧到新" : "every page oldest to newest"})\n${result.messages
+            markdown: `# ${zh ? "已提交历史列表" : "Committed history listing"}\n\n${compactHeader(result.total, locale)}\n${result.messages
                 .map((message) => {
                 const preview = Array.from(message.text).slice(0, 120).join("");
-                return `### ${historyMessageLabel(message, locale)}\n${message.length} Unicode code points\n${renderHistoryBackground(message.background, locale)}[${zh ? "部分原文预览" : "Partial original preview"}]\n${preview}\n[${message.length > 120 ? (zh ? "预览有省略" : "preview omitted remaining text") : zh ? "预览结束" : "preview ends"}]`;
+                const omitted = message.length > 120
+                    ? `\n${zh ? "…（预览省略）" : "…(preview omitted)"}`
+                    : "";
+                return `### ${compactMessageLabel(message, locale)}${renderHistoryBackground(message.background, locale, false)}\n${preview}${omitted}`;
             })
-                .join("\n\n") || (zh ? "（空页）" : "(empty page)")}\n\n---\n${zh ? "本页位置／条数" : "Page positions / count"}: ${range(result.messages)} / ${result.messages.length}\n${cursorLine("earlierCursor", result.earlierCursor)}\n${cursorLine("laterCursor", result.laterCursor)}\n${zh ? "续页只传 {cursor}。" : "Continue with only {cursor}."}${result.messages.length === 0 && result.anchor !== null ? `\n${zh ? "可从锚点转向浏览" : "Browse from the anchor in the other direction"}: {before:"${result.anchor}"} / {after:"${result.anchor}"}` : ""}`,
+                .join("\n\n") || (zh ? "（空页）" : "(empty page)")}\n\n---\n${zh ? "本页位置／条数" : "Page positions / count"}: ${range(result.messages)} / ${result.messages.length}\n${cursorLine("earlierCursor", result.earlierCursor)}\n${cursorLine("laterCursor", result.laterCursor)}${result.messages.length === 0 && result.anchor !== null ? `\n${zh ? "可从锚点转向浏览" : "Browse from the anchor in the other direction"}: {before:"${result.anchor}"} / {after:"${result.anchor}"}` : ""}`,
         };
     if (result.kind === "read")
         return {
             ok: true,
             markdown: `# ${zh ? "完整历史原文" : "Complete history originals"}\n\n${header}\nMode: ${result.mode}${result.center === null ? "" : `\nCenter: ${result.center}`}\nOrder: oldest_first\n${zh ? "实际位置" : "Actual positions"}: ${range(result.messages)}\n${zh ? "每条正文完整，无摘要、无截断" : "Each body is complete, without summary or truncation"}\n\n${result.messages.map((message) => renderHistoryMessage(message, locale)).join("\n\n") || (zh ? "（历史为空）" : "(empty history)")}\n\n---\n${cursorLine("earlier", result.earlier)}\n${cursorLine("later", result.later)}\n${result.earlier === null ? (zh ? "已到历史开头。" : "At the history beginning.") : legacyRead ? `context_read {ref:"${result.earlier}"}` : zh ? "向前不重复读取：history_read {ref:earlier,before:N}。" : "Read earlier without repeating this window: history_read {ref:earlier,before:N}."}\n${result.later === null ? (zh ? "已到历史结尾。" : "At the history end.") : legacyRead ? `context_read {ref:"${result.later}"}` : zh ? "向后不重复读取：history_read {ref:later,after:N}。" : "Read later without repeating this window: history_read {ref:later,after:N}."}\n${legacyRead ? (zh ? "按需逐条读取相邻原文。" : "Read adjacent originals one at a time as needed.") : zh ? "按需小步扩展；21 条消息不代表固定输出体积。" : "Expand in small windows as needed; 21 messages do not imply a fixed output size."}`,
         };
+    if (!result.legacy)
+        return {
+            ok: true,
+            markdown: `# ${zh ? "历史字面搜索" : "History literal search"}\n\n${compactHeader(result.total, locale)}\n${zh ? "搜索位置范围（排除边界）" : "Search position range (boundaries excluded)"}: ${result.range.start === null ? "empty" : `${result.range.start}..${result.range.end}`}\n${zh ? "查询词" : "Queries"}: ${JSON.stringify(result.queries)}\n${zh ? "命中消息总数" : "Total matching messages"}: ${result.matches}\n\n${result.messages.map(({ message, hits, fragments, omittedMatches }) => `### ${compactMessageLabel(message, locale)}${renderHistoryBackground(message.background, locale, false)}${zh ? "逐词命中次数" : "Matches per query"}: ${hits.map(({ query, count }) => `${JSON.stringify(query)}: ${count}`).join("; ")}\n${fragments.map((fragment) => `[${zh ? "部分原文片段" : "Partial original fragment"}: ${fragment.start}..${fragment.end}${fragment.omittedBefore ? "; prefix omitted" : ""}${fragment.omittedAfter ? "; suffix omitted" : ""}]\n${fragment.text}`).join("\n")}${omittedMatches ? `\n${zh ? "另有命中未展示；可完整读取核实。" : "Additional matches omitted; read the complete original to verify."}` : ""}`).join("\n\n") || (zh ? "零字面命中不证明事件没有发生；可改词、从 all 放宽为 any 或读取相邻上下文。" : "Zero literal matches do not prove an event never happened. Try other words, relax all to any, or read nearby context.")}\n\n---\n${cursorLine("nextCursor", result.nextCursor)}`,
+        };
     return {
         ok: true,
         markdown: `# ${zh ? "历史字面搜索" : "History literal search"}\n\n${header}${result.within === null ? "" : `\nLegacy selected scope: ${result.within}`}\n${zh ? "搜索位置范围（排除边界）" : "Search position range (boundaries excluded)"}: ${result.range.start === null ? "empty" : `${result.range.start}..${result.range.end}`}\nOrder: ${result.order}\nMatch: ${result.match} (${zh ? "同一消息内" : "within one message"})\nNormalization: NFKC${result.caseSensitive ? " (case sensitive)" : " + case folding (locale und)"}\n${zh ? "查询词" : "Queries"}: ${JSON.stringify(result.queries)}\n${zh ? "命中消息总数" : "Total matching messages"}: ${result.matches}\n\n${result.messages.map(({ message, hits, fragments, omittedMatches }) => `### ${historyMessageLabel(message, locale)}\n${message.length} Unicode code points\n${renderHistoryBackground(message.background, locale)}${zh ? "逐词命中次数" : "Matches per query"}: ${hits.map(({ query, count }) => `${JSON.stringify(query)}: ${count}`).join("; ")}\n${fragments.map((fragment) => `[${zh ? "部分原文片段" : "Partial original fragment"}: ${fragment.start}..${fragment.end}${fragment.omittedBefore ? "; prefix omitted" : ""}${fragment.omittedAfter ? "; suffix omitted" : ""}]\n${fragment.text}\n[${zh ? "片段结束" : "fragment ends"}]`).join("\n")}\n${omittedMatches ? (zh ? "另有命中未展示；可完整读取核实。" : "Additional matches omitted; read the complete original to verify.") : zh ? "全部命中均在所示片段内。" : "All matches are covered by these fragments."}`).join("\n\n") || (result.legacy ? (zh ? "零字面命中不证明事件没有发生；可改用其他 query 或读取相邻原文。" : "Zero literal matches do not prove an event never happened. Try another query or read adjacent originals.") : zh ? "零字面命中不证明事件没有发生；可改词、从 all 放宽为 any 或读取相邻上下文。" : "Zero literal matches do not prove an event never happened. Try other words, relax all to any, or read nearby context.")}\n\n---\n${cursorLine(result.legacy ? "Next-page cursor" : "nextCursor", result.nextCursor)}\n${result.legacy ? (zh ? "续页保留原source=history、query、caseSensitive、within与limit并使用返回cursor。" : "Legacy continuation keeps the original source=history, query, caseSensitive, within and limit with the returned cursor.") : zh ? "续页只传 {cursor}；已有原文足以判断时停止检索。all 仅限同一消息；相邻消息可改用 any 后读前后文。" : "Continue with only {cursor}; stop when the originals suffice. all applies to one message; use any then read context for terms in adjacent messages."}`,
@@ -87,7 +105,7 @@ function localizedRecovery(result, zh) {
     return `参数不符合要求，请按工具定义修正。${result.recovery}`;
 }
 /** Every result carries its own annotation; no implicit neighboring inheritance. */
-export function renderHistoryBackground(background, locale) {
+export function renderHistoryBackground(background, locale, withNotice = true) {
     if (background === undefined)
         return "";
     const zh = locale === "zh-CN";
@@ -99,10 +117,11 @@ export function renderHistoryBackground(background, locale) {
     const notice = zh
         ? "历史背景仅说明采集位置的状态，不是当前世界状态；回忆、梦境或段内局部时间结合原文解释，不认证事实或授予角色知识。"
         : "Historical background describes the captured state, not current world state; interpret memories, dreams and local times with the original text. It does not certify facts or grant character knowledge.";
+    const suffix = withNotice ? `\n${notice}` : "";
     if (background.kind === "snapshot" ||
         equalBackground(background.before, background.after))
-        return `\n${zh ? "历史背景" : "Historical background"}:${node(background.kind === "snapshot" ? background.value : background.before)}\n${notice}\n`;
-    return `\n${zh ? "推进前背景" : "Background before advancement"}:${node(background.before)}\n${zh ? "推进后背景" : "Background after advancement"}:${node(background.after)}\n${notice}\n`;
+        return `\n${zh ? "历史背景" : "Historical background"}:${node(background.kind === "snapshot" ? background.value : background.before)}${suffix}\n`;
+    return `\n${zh ? "推进前背景" : "Background before advancement"}:${node(background.before)}\n${zh ? "推进后背景" : "Background after advancement"}:${node(background.after)}${suffix}\n`;
 }
 function equalBackground(before, after) {
     if (before === after)

package/dist/node/runtime/history/HistoryTools.js

@@ -0,0 +1,31 @@
+import { HistoryQuery, historyInputs } from "./HistoryQuery.js";
+import { renderHistoryResult } from "./HistoryRendering.js";
+export const historyToolNames = [
+    "history_list",
+    "history_search",
+    "history_read",
+];
+export function isHistoryToolName(name) {
+    return historyToolNames.includes(name);
+}
+export function historyEntries(history, backgrounds = {}) {
+    return Object.entries(history).map(([path, contents]) => ({
+        path,
+        contents,
+        ...(backgrounds[path] === undefined
+            ? {}
+            : { background: structuredClone(backgrounds[path]) }),
+    }));
+}
+/** Read-only committed-history navigation shared by play and world revision. */
+export function createHistoryQuery(scope, entries) {
+    return new HistoryQuery(scope, historyInputs(entries));
+}
+export function runHistoryTool(query, call, locale) {
+    const result = call.name === "history_search"
+        ? query.search(call.arguments)
+        : call.name === "history_read"
+            ? query.read(call.arguments)
+            : query.list(call.arguments);
+    return renderHistoryResult(result, locale);
+}

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

@@ -2,6 +2,7 @@ import { projectLegacyModelBindingFailure } from "./LegacyModelBindingFailure.js
 import { dispatchFailureEnding, emptyResponseEnding, lastEndingCancelled, noContinuationEnding, PlayAdvanceLifecycle, settlementFailureEnding, } from "./PlayAdvanceLifecycle.js";
 import { isResolutionTool, resolutionMarkdown, resolutionToolNames, resolveTabletop, seededRandom, } from "./TabletopResolution.js";
 import { captureNarrativeOrigin, snapshotBackground, narrativeBackground, } from "../history/HistoryBackground.js";
+import { historyEntries } from "../history/HistoryTools.js";
 import { isDeepStrictEqual } from "node:util";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
 import { renderToolAliasNote, resolveToolName, } from "../prompt/ToolNameAlias.js";
@@ -2163,6 +2164,9 @@ function duplicatePlayerExchange(session, exchangeId, playerText, context) {
 }
 function mergeChangedDocuments(session, changes) {
     for (const change of changes) {
+        // Play and continuity writes never remove a document; only world-revision apply does.
+        if (change.kind === "delete")
+            continue;
         const projected = {
             kind: change.kind,
             ref: `@${change.stableShortRef}`,
@@ -2346,15 +2350,6 @@ function revisionTimelineGeneration(sourceGeneration, operationId, worldId, cont
         .digest("hex")
         .slice(0, 40)}`;
 }
-function historyEntries(history, backgrounds = {}) {
-    return Object.entries(history).map(([path, contents]) => ({
-        path,
-        contents,
-        ...(backgrounds[path] === undefined
-            ? {}
-            : { background: structuredClone(backgrounds[path]) }),
-    }));
-}
 function operationId(chainId, key) {
     return `play-${createHash("sha256")
         .update(`${chainId}\0${key}`)

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

@@ -671,15 +671,15 @@ function knownStateDirectory(snapshot, directory, declaredDirectories) {
     return snapshot.files.some(({ path }) => path.startsWith(logicalPrefix));
 }
 function executeStateList(snapshot, args, declaredDirectories) {
+    // Frozen sessions may still send obsolete cursor/limit; directories are
+    // listed in full, so those keys are accepted and ignored.
     if (!record(args) ||
         !hasOnlyToolKeys(args, ["parent", "cursor", "limit"]) ||
         typeof args.parent !== "string" ||
-        parseStateDirectoryHandle(args.parent) === null ||
-        (args.limit !== undefined && typeof args.limit !== "number") ||
-        !validOptionalCursor(args.cursor))
+        parseStateDirectoryHandle(args.parent) === null)
         return {
             ok: false,
-            markdown: "# Runtime argument error\n\nstate_list requires an @dir-* parent returned by Runtime and accepts only cursor and limit in addition; use history_list for committed history.",
+            markdown: "# Runtime argument error\n\nstate_list requires an @dir-* parent returned by Runtime; use history_list for committed history.",
         };
     return executeContextList(snapshot, { ...args, source: "state" }, declaredDirectories);
 }
@@ -699,19 +699,11 @@ function executeContextList(snapshot, args, declaredDirectories = []) {
             (args.order !== "newest_first" && args.order !== "oldest_first"));
     if (!hasOnlyToolKeys(args, allowedKeys) ||
         invalidStateShape ||
-        invalidHistoryShape ||
-        (args.limit !== undefined && typeof args.limit !== "number") ||
-        !validOptionalCursor(args.cursor))
+        invalidHistoryShape)
         return {
             ok: false,
             markdown: "# Runtime argument error\n\nstate must use an @dir-* parent returned by the Runtime and omit order; history must use newest_first or oldest_first order and omit parent.",
         };
-    const limit = typeof args.limit === "number" ? args.limit : 20;
-    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nlimit must be between 1 and 100.",
-        };
     if (args.source === "state") {
         const parent = args.parent;
         const directory = parseStateDirectoryHandle(parent);
@@ -722,32 +714,38 @@ function executeContextList(snapshot, args, declaredDirectories = []) {
                 ok: false,
                 markdown: "# Runtime argument error\n\nThe parent is not a Runtime-known state directory; call state_list and descend only through its returned directory handles.",
             };
-        const result = snapshot.query({
-            kind: "catalog",
-            directory,
-            includeRetired: true,
-            declaredDirectories,
-            limit,
-            ...(typeof args.cursor === "string" || args.cursor === null
-                ? { cursor: args.cursor }
-                : {}),
-        });
-        if (result.kind === "error")
-            return renderStateQueryFailure(result);
-        if (result.kind !== "catalog")
-            return unexpectedStateQueryResult();
-        const entries = result.entries.map((entry) => {
-            if (entry.kind === "directory") {
-                const relative = entry.logicalPath.slice(`${snapshot.logicalRoot}/`.length);
-                return `- Directory ${stateDirectoryHandle(relative)}`;
-            }
-            if (entry.document === undefined)
-                return "- Damaged document (currently not addressable)";
-            return `- Document @${entry.document.shortRef} · ${entry.document.title} · ${entry.document.codec.toUpperCase()} · ${entry.document.summary}${entry.document.retired ? " · retired" : ""}${entry.status === "damaged" ? " · needs repair" : ""}`;
-        });
+        const entries = [];
+        let complete = true;
+        let cursor = null;
+        do {
+            const result = snapshot.query({
+                kind: "catalog",
+                directory,
+                includeRetired: true,
+                declaredDirectories,
+                limit: 100,
+                ...(cursor === null ? {} : { cursor }),
+            });
+            if (result.kind === "error")
+                return renderStateQueryFailure(result);
+            if (result.kind !== "catalog")
+                return unexpectedStateQueryResult();
+            if (result.coverage.status !== "complete")
+                complete = false;
+            entries.push(...result.entries.map((entry) => {
+                if (entry.kind === "directory") {
+                    const relative = entry.logicalPath.slice(`${snapshot.logicalRoot}/`.length);
+                    return `- Directory ${stateDirectoryHandle(relative)}`;
+                }
+                if (entry.document === undefined)
+                    return "- Damaged document (currently not addressable)";
+                return `- Document @${entry.document.shortRef} · ${entry.document.title} · ${entry.document.codec.toUpperCase()} · ${entry.document.summary}${entry.document.retired ? " · retired" : ""}${entry.status === "damaged" ? " · needs repair" : ""}`;
+            }));
+            cursor = result.page.nextCursor;
+        } while (cursor !== null);
         return {
             ok: true,
-            markdown: `# Directory listing\n\nScope: state · ${parent}\nCoverage: ${result.coverage.status === "complete" ? "complete" : "partial"}\n${entries.join("\n") || "(empty)"}\n\n---\nThis page: ${result.page.start}..${result.page.end} / ${result.page.total} items\nComplete: ${result.page.complete ? "yes" : "no"}${result.page.nextCursor === null ? "" : `\nNext-page cursor: ${result.page.nextCursor}`}`,
+            markdown: `# Directory listing\n\nScope: state · ${parent}\nCoverage: ${complete ? "complete" : "partial"}\n${entries.join("\n") || "(empty)"}\n\n---\nComplete: yes`,
         };
     }
     return toolFailure("Use history_list for committed history.");

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

@@ -148,15 +148,13 @@ export class FileNativePromptCompiler {
             playPreset: input.playPreset,
             modelBinding: input.modelBinding,
             tools: input.tools,
+            ...(input.preload === undefined ? {} : { preload: input.preload }),
         });
     }
     compileWorldRevision(input) {
         const identity = this.#locale === "zh-CN"
             ? `# 当前修订世界\n\n${input.worldTitle}`
             : `# World being revised\n\n${input.worldTitle}`;
-        const boundary = this.#locale === "zh-CN"
-            ? "# 世界修订工作树边界\n\n随附工具只读写当前锁定 epoch 的 state/* 与 control/* 工作树。成功工具调用尚未进入世界 Authority；只有玩家点击应用才会整体提交并解锁。"
-            : "# World-revision worktree boundary\n\nThe attached tools read and write only state/* and control/* in the current locked epoch. Successful tool calls do not enter world Authority until the player applies the complete revision and unlocks it.";
         return this.#compileAuthoringConversation({
             identity: {
                 source: "world-revision:title",
@@ -165,10 +163,7 @@ export class FileNativePromptCompiler {
                         ? `\n\nEpoch: ${input.epoch.id}\nBase: ${input.epoch.baseHead}`
                         : ""),
             },
-            boundary: {
-                source: "runtime:world-revision-worktree-boundary",
-                markdown: boundary,
-            },
+            boundary: null,
             runtimeSource: "runtime:builtin/world-revision",
             target: "world-revision",
             gameplay: input.gameplay,
@@ -177,6 +172,7 @@ export class FileNativePromptCompiler {
             playPreset: input.playPreset,
             modelBinding: input.modelBinding,
             tools: input.tools,
+            ...(input.preload === undefined ? {} : { preload: input.preload }),
         });
     }
     #compileAuthoringConversation(input) {
@@ -185,7 +181,7 @@ export class FileNativePromptCompiler {
         const logicalMessages = [];
         const ordered = input.playPreset.definition.authorPrompts ??
             legacyAuthorPrompts(input.playPreset.definition);
-        const catalog = builtinAuthorPrompts(this.#locale);
+        const catalog = builtinAuthorPrompts(this.#locale, input.target);
         for (const entry of ordered) {
             if (entry.kind === "world" || !entry.enabled)
                 continue;
@@ -210,7 +206,7 @@ export class FileNativePromptCompiler {
             if (builtin?.id === "author.target")
                 blocks = [
                     input.identity,
-                    input.boundary,
+                    ...(input.boundary === null ? [] : [input.boundary]),
                     ...(input.gameplay.mode === "tabletop"
                         ? [
                             tabletopAuthoringRulesBlock(input.gameplay, input.target, this.#locale),
@@ -238,6 +234,20 @@ export class FileNativePromptCompiler {
                 blocks,
             });
         }
+        // Preloaded material follows every author prompt so the stable prefix stays byte-identical.
+        if (input.preload !== undefined && input.preload.length > 0) {
+            const preloadBlocks = input.preload.map(({ source, markdown }) => ({
+                source,
+                markdown,
+            }));
+            logicalMessages.push({
+                messageRole: "system",
+                promptId: "runtime.preload",
+                role: "world_context",
+                markdown: joinBlocks(preloadBlocks),
+                blocks: preloadBlocks,
+            });
+        }
         const tools = structuredClone(input.tools);
         const toolStrategy = this.#toolStrategyOverride ??
             defaultRuntimeToolDefinitionStrategy(input.modelBinding.provider);
@@ -870,9 +880,13 @@ function settingImprovementPresetReference(binding, locale, target, gameplay) {
                 return [
                     {
                         ...worldInstructionPlaceholder,
-                        markdown: locale === "zh-CN"
-                            ? "世界指令在此展开；frame 选定材料仅在全新游玩上下文中作为初始工具结果提供。请通过本轮创作工具检查实际内容。"
-                            : "World instructions expand here; frame-selected material is supplied as an initial tool result only for a fresh play context. Inspect actual content through the current authoring tools.",
+                        markdown: revision
+                            ? locale === "zh-CN"
+                                ? "世界指令在此展开；启用块原文见本请求的 Runtime 预载。"
+                                : "World instructions expand here; enabled block text appears in this request's Runtime preload."
+                            : locale === "zh-CN"
+                                ? "世界指令在此展开；frame 选定材料仅在全新游玩上下文中作为初始工具结果提供。请通过本轮创作工具检查实际内容。"
+                                : "World instructions expand here; frame-selected material is supplied as an initial tool result only for a fresh play context. Inspect actual content through the current authoring tools.",
                     },
                 ];
             if (entry.kind === "tail" || !entry.enabled)
@@ -949,11 +963,13 @@ function settingImprovementPresetReference(binding, locale, target, gameplay) {
             : "Player-visible narrative semantics", locale === "zh-CN"
             ? "这些块只在未来游玩生成玩家可见正文时生效；不得把它们当作本轮 YAML 或 Markdown 设定正文的范文。"
             : "These blocks apply only when future play produces player-visible story. Do not use them as prose models for YAML or Markdown setting documents in this conversation.", narrativeBlocks),
-        settingImprovementReferenceGroup(locale === "zh-CN"
-            ? "本轮提示（每次发送的尾部）"
-            : "Turn guide (per-send suffix)", locale === "zh-CN"
-            ? "这些行在每次游玩发送时追加在玩家输入之后，由已启用块的尾部行按同一顺序拼成；它们是提醒，不是世界事实。"
-            : "These lines are appended after the player input on every play send, assembled from the enabled blocks' turn-guide lines in the same order. They are reminders, not world facts.", turnGuideBlocks),
+        revision
+            ? null
+            : settingImprovementReferenceGroup(locale === "zh-CN"
+                ? "本轮提示（每次发送的尾部）"
+                : "Turn guide (per-send suffix)", locale === "zh-CN"
+                ? "这些行在每次游玩发送时追加在玩家输入之后，由已启用块的尾部行按同一顺序拼成；它们是提醒，不是世界事实。"
+                : "These lines are appended after the player input on every play send, assembled from the enabled blocks' turn-guide lines in the same order. They are reminders, not world facts.", turnGuideBlocks),
     ].filter((group) => group !== null);
     return [
         heading,

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

@@ -134,11 +134,7 @@ function createToolDefinitions(locale) {
         ...resolutionDefinitions(locale),
         state_list: {
             description: descriptions.state_list,
-            inputSchema: object({
-                parent: string,
-                cursor: { type: ["string", "null"] },
-                limit: { type: "integer", minimum: 1, maximum: 100 },
-            }, ["parent"]),
+            inputSchema: object({ parent: string }, ["parent"]),
         },
         history_list: {
             description: descriptions.history_list,
@@ -294,8 +290,8 @@ function resolutionDefinitions(locale) {
 const toolDescriptions = {
     en: {
         world_checkpoint: "Register a gap between events and suggest that the player start a fresh context here. Arguments must be an empty object. The effect and replay scope are defined by the tools-and-settlement rules; when to register is defined by the checkpoint policy. Consolidation and maintenance do not require this tool; do not advance the story to register a checkpoint.",
-        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.",
+        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. Each call returns the whole directory with Complete: yes. 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 in Authority acceptance order, not story dates. limit defaults to 20 (1–100 messages). Previews are only the first 120 Unicode code points. Historical background describes the captured state, not current world state; interpret memories, dreams and local times with the original text, and it does not certify facts or grant character knowledge. 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.",
@@ -308,8 +304,8 @@ const toolDescriptions = {
     },
     "zh-CN": {
         world_checkpoint: "登记事件间隙，向玩家建议从这里开始全新上下文。参数为空对象。生效条件与补入范围见“工具与响应结算”；何时登记见检查点政策。整理与归并不需要调用本工具；不要为了登记而推进剧情。",
-        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可直接使用，无需再次列举；位置不是身份或回合数。",
+        state_list: "列出 Runtime 已知的文档与状态目录句柄。状态根目录的 parent 使用 @dir-/；继续下级时使用初始目录索引或 state_list 返回的 @dir-*；已有句柄无需再次列目录确认。冻结世界 frame 声明的 catalog 目录即使为空，也会继续列出并可用。每次调用整份返回该目录，末尾 Complete: yes。返回的文档句柄交给 context_read；本工具不列出已提交历史。",
+        history_list: "浏览当前时间线已提交历史。无锚点时取最新一页；before 或 after 只能选一个，取锚点紧邻前／后的一页且不含锚点。页内始终由旧到新。limit 默认20，整数1–100。排序依据是 Authority 接受顺序，不代表故事内日期。历史背景仅说明采集位置的状态，不是当前世界状态；回忆、梦境或段内局部时间结合原文解释，不认证事实或授予角色知识。预览仅含前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-* 句柄。",