narraeon 0.7.5 → 0.7.7

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

@@ -5,8 +5,10 @@ import { stateDirectoryHandle, parseStateDirectoryHandle, } from "../world/State
 import { renderDocumentWritePosition } from "../prompt/WorldMaintenanceReport.js";
 import { stringify } from "yaml";
 import { renderPlayerViewBindings } from "../world/PlayerViewBindings.js";
+import { coerceToolArguments, renderCoercionNote, } from "../model/ToolArgumentCoercion.js";
+import { runtimeToolInputSchema } from "../prompt/FileNativeToolRegistry.js";
 import { PromptCompilationError, } from "../prompt/FileNativePromptCompiler.js";
-import {} from "../world/WorldDocumentStore.js";
+import { formatWorldDocumentLocator, } from "../world/WorldDocumentStore.js";
 import { acceptWorldStateRevision, beginWorldStateRevision, fileNativeStateChanges, worldDocumentRevisionFailureMessage, } from "../world/WorldStateRevision.js";
 class PlayDocumentToolFailure extends Error {
     failureKind;
@@ -76,6 +78,19 @@ export class FileNativePlayDocuments {
         return authorizeResolvedRead(this.#reads, this.#candidate.snapshot, shortRef, locator);
     }
     execute(call, history, options = {}) {
+        const schema = runtimeToolInputSchema(call.name);
+        if (schema === null)
+            return this.#dispatch(call, history, options);
+        const repaired = coerceToolArguments(schema, call.arguments);
+        const result = this.#dispatch({ ...call, arguments: repaired.arguments }, history, options);
+        if (repaired.coerced.length === 0 || result.markdown === undefined)
+            return result;
+        return {
+            ...result,
+            markdown: `${result.markdown}\n\n${renderCoercionNote(repaired.coerced, options.locale ?? "en")}`,
+        };
+    }
+    #dispatch(call, history, options) {
         let historyQuery;
         const query = () => (historyQuery ??= new HistoryQuery(options.historyScope ?? "local-document-context", historyInputs(history)));
         const render = (result) => renderHistoryResult(result, options.locale ?? "en");
@@ -232,6 +247,8 @@ function documentDescriptorByRef(snapshot, ref) {
     return result.kind === "read_document" && result.ok ? result.document : null;
 }
 function applyPlayCandidatePatch(candidate, reads, args) {
+    if (record(args) && typeof args.edits === "string")
+        return toolFailure("world_patch.edits must be a JSON array of 1 to 32 edits, not a string.");
     if (!record(args) ||
         typeof args.target !== "string" ||
         !Array.isArray(args.edits) ||
@@ -257,10 +274,12 @@ function applyPlayCandidatePatch(candidate, reads, args) {
                 },
             ],
         });
+        if (!revised.ok && revised.editOutcomes.length > 0)
+            throw new PlayDocumentToolFailure(`world_patch applied none of its edits to @${ref}. ${formatEditNotes(revised.editOutcomes)}`, "candidate");
         if (!revised.ok || revised.snapshotStatus !== "usable")
             throw new PlayDocumentToolFailure(worldDocumentRevisionFailureMessage(revised.diagnostics), "candidate");
         const changed = revised.changes.length > 0;
-        const receipt = formatToolRevisionReceipt(target.shortRef, revised.changes);
+        const receipt = formatToolRevisionReceipt(target.shortRef, revised.changes, revised.editOutcomes);
         const previousSnapshot = candidate.snapshot;
         acceptWorldStateRevision(candidate, revised);
         carryWriteAuthorizations(previousSnapshot, candidate, reads, revised.changes);
@@ -336,12 +355,41 @@ function authorizationsAfterEdits(authorization, edits) {
     }
     return authorization;
 }
-function formatToolRevisionReceipt(shortRef, changes) {
+function formatToolRevisionReceipt(shortRef, changes, outcomes) {
     if (changes.length > 1)
         throw new Error("A world_patch revision must affect only its target document");
-    return changes.length === 1
-        ? `@${shortRef} pending write`
-        : `@${shortRef} unchanged`;
+    const failed = outcomes.filter(({ status }) => status === "failed").length;
+    const parts = [
+        changes.length === 1
+            ? `@${shortRef} pending write`
+            : `@${shortRef} unchanged`,
+    ];
+    if (failed > 0)
+        parts.push(`${outcomes.length - failed}/${outcomes.length} edits applied`);
+    else if (outcomes.some(({ status }) => status === "no_op"))
+        parts.push(`${outcomes.length} edits applied`);
+    const notes = formatEditNotes(outcomes);
+    if (notes !== "")
+        parts.push(notes);
+    if (failed > 0)
+        parts.push("applied edits are not resent; send again only the edits listed above");
+    return parts.join(" · ");
+}
+/** Lists only the edits that did not apply cleanly: failed ones and no-ops. */
+function formatEditNotes(outcomes) {
+    return outcomes
+        .flatMap(({ editIndex, status, diagnostic }) => {
+        if (status === "applied" || diagnostic === undefined)
+            return [];
+        const label = `edit #${editIndex + 1}`;
+        if (status === "no_op")
+            return [`${label} no-op: ${diagnostic.message}`];
+        const location = diagnostic.locator
+            ? ` (${formatWorldDocumentLocator(diagnostic.locator)})`
+            : "";
+        return [`${label}${location}: ${diagnostic.message}`];
+    })
+        .join(" · ");
 }
 function applyPlayCandidateRetirement(candidate, reads, args) {
     if (!record(args) ||
@@ -419,6 +467,8 @@ function applyPlayCandidateCreate(candidate, authorizations, args, declaredDirec
         const parentDirectory = record(args) && typeof args.parent === "string"
             ? parseStateDirectoryHandle(args.parent)
             : null;
+        if (record(args) && typeof args.aliases === "string")
+            throw new PlayDocumentToolFailure("world_create.aliases must be a JSON array of strings, not a string");
         if (!record(args) ||
             typeof args.parent !== "string" ||
             parentDirectory === null ||

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

@@ -6,7 +6,7 @@ import { effectiveFollowupDefinitions } from "../play/OrderedFollowups.js";
 import { legacyAuthorPrompts } from "../play/FileNativePlayPresetStore.js";
 import { builtinAuthorPrompts, authoringMechanics, } from "../../shared/ordered-author-prompts.js";
 import { builtinPlayPrompts, orderedPromptScope, orderedPromptTurnGuide, promptScopeApplies, } from "../../shared/ordered-play-prompts.js";
-import { turnGuideHeader, turnGuideText, } from "../../shared/turn-guide.js";
+import { turnGuideHeader, turnGuideText, turnGuideWithTurnNote, } from "../../shared/turn-guide.js";
 import { parseOrderedPlayPrompts } from "../play/OrderedPlayPrompts.js";
 import { renderDocumentWritePosition } from "./WorldMaintenanceReport.js";
 import { parseDocument } from "yaml";
@@ -43,7 +43,7 @@ const runtimeContracts = {
 
 - Use only tools attached to the current request. Read results state their scope, cursor, and completeness. Directories must use @dir-* handles returned by Runtime; documents and history must use @handles returned by Runtime. Never substitute a world/ path or natural-language name for a handle.
 - 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.
+- A YAML world_patch locator may mix map keys and zero-based array indexes. add and replace upsert: they write whether or not the target exists, and an index past the end appends. remove deletes one existing key or array item; a missing target is a no-op the receipt reports. Each edit settles on its own: a failed edit is skipped and the others still apply, so when a receipt lists failed edits, send again only those. 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.
 
@@ -74,7 +74,7 @@ ${historyUseGuidance("en")}`,
 
 - 只使用请求随附的工具；读取结果会明确范围、cursor 与完整性。目录只能使用 Runtime 返回的 @dir-*，文档和历史只能使用 Runtime 返回的 @句柄，不要把 world/路径或自然语言名称冒充句柄。
 - 材料覆盖报告标为 \`已注入完整正文\` 的文档，其完整可写正文已经在本次请求里，写入资格同样已经具备。不要为确认正文结构、核对正文字段或“保险起见”重读它。context_read 会额外显示当前 title、summary 和 aliases；world_patch 会保留 set_metadata 中未提供的元数据字段，因此不要只为照抄未改变的元数据而读取。只有后续决策确实依赖尚未显示的元数据，或材料覆盖报告未覆盖的内容时才读。
-- YAML world_patch 的 locator 可混合 map key 与从 0 开始的数组下标；remove 只删除一个精确的已有键或数组项。对象需要退出后续 frame catalog 时用 world_retire 退役，不要销毁文档；退役文档仍可列出、读取、引用和恢复。
+- YAML world_patch 的 locator 可混合 map key 与从 0 开始的数组下标。add 与 replace 是 upsert：无论目标是否存在都写入，数组下标达到或超过长度时追加。remove 只删除一个精确的已有键或数组项；目标不存在时为无操作，回执会注明。每条 edit 独立结算：失败的 edit 被跳过，其余照常生效；回执列出失败项时，只补发列出的 edit。对象需要退出后续 frame catalog 时用 world_retire 退役，不要销毁文档；退役文档仍可列出、读取、引用和恢复。
 - 字面搜索 0 命中不证明事实不存在。工具、目录、文档、档案、检索、命中、句柄、Runtime 及失败过程只供私下裁决；玩家可见叙事不得出现“没搜到／没找到资料”等内部措辞。信息不足时保持世界内的不确定性，不编造内部过程。
 - 世界写入工具只修改尚未提交的工作副本；Runtime 接受并完成提交前，这些修改都不是正式世界事实。
 
@@ -568,12 +568,12 @@ export class FileNativePromptCompiler {
             append("player_input", [
                 { source: "player:input", markdown: effective.playerInput },
             ]);
-        const turnGuide = turnGuideLines.length === 0
+        const turnGuide = turnGuideWithTurnNote(this.#locale, turnGuideLines.length === 0
             ? undefined
             : {
                 text: turnGuideText(this.#locale, turnGuideLines),
                 lines: turnGuideLines,
-            };
+            }, effective.turnNote);
         scanRuntimeLeakage([
             ...logicalMessages,
             ...(turnGuide === undefined

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

@@ -11,6 +11,11 @@ import { resolutionCheckToolForScheme, resolutionToolDefinition, resolutionToolN
  * Tools that every current play and authoring surface may expose. Resolution
  * tools are registered below but never enter a surface until a per-world
  * selection (Phase 2) includes them.
+ *
+ * No declared name may end in `_<another declared name>`: a provider-mangled
+ * `mcp__<server>__<word>_<name>` is restored by that suffix (see
+ * ToolNameAlias.ts), so such a pair would make the restoration ambiguous.
+ * tests/runtime/tool-name-alias.test.ts enforces this across all surfaces.
  */
 export const baseRuntimeToolNames = [
     "state_list",
@@ -70,6 +75,16 @@ export function runtimeToolsForNames(names, locale = defaultAppLocale) {
         inputSchema: toolDefinitions[name].inputSchema,
     }));
 }
+/**
+ * The original Runtime input schema of a registered tool. Argument repair reads
+ * this, not the portable wire projection, so every array or object position is
+ * exactly what Runtime validates.
+ */
+export function runtimeToolInputSchema(name, locale = defaultAppLocale) {
+    if (!isRegisteredRuntimeToolName(name))
+        return null;
+    return createToolDefinitions(locale)[name].inputSchema;
+}
 /**
  * Return a Provider-portable root-object schema for a Runtime-owned tool.
  *
@@ -113,6 +128,8 @@ function createToolDefinitions(locale) {
         },
     }, ["yaml"]);
     const markdownLocator = object({ markdown: { type: "array", items: { type: "string" }, minItems: 1 } }, ["markdown"]);
+    // add_section takes [] to add a new top-level section at the end of the body.
+    const markdownParentLocator = object({ markdown: { type: "array", items: { type: "string" } } }, ["markdown"]);
     const definitions = {
         ...resolutionDefinitions(locale),
         state_list: {
@@ -194,10 +211,15 @@ function createToolDefinitions(locale) {
                                 "locator",
                             ]),
                             object({
-                                op: { enum: ["replace_section", "add_section"] },
+                                op: { const: "replace_section" },
                                 locator: markdownLocator,
                                 markdown: { type: "string" },
                             }, ["op", "locator", "markdown"]),
+                            object({
+                                op: { const: "add_section" },
+                                locator: markdownParentLocator,
+                                markdown: { type: "string" },
+                            }, ["op", "locator", "markdown"]),
                             object({
                                 op: { const: "rename_section" },
                                 locator: markdownLocator,
@@ -278,7 +300,7 @@ const toolDescriptions = {
         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_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. add and replace are upserts: each writes its value whether or not the target exists, creating missing parent maps, and an array index at or past the end appends. remove deletes the existing key or array item at its locator; a missing target is a no-op that the receipt reports. 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. 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; when that heading does not exist yet, replace_section adds it under its parent. add_section adds a child under the locator heading, and locator [] with a level-two markdown heading adds a new top-level section at the end of the body. 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. Each edit settles on its own: a failed edit is skipped and the others still apply. Success reports whether the document changed; when the receipt lists failed edits, the applied ones are already written, so send again only the listed edits. It 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.",
         artifact_emit: "Submit an artifact declared in advance for this follow-up request. Supply only the output name and payload; Runtime fixes the channel, key, content type, renderer, retention policy, and authority meaning in the contract.",
@@ -292,7 +314,7 @@ const toolDescriptions = {
         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_patch: '更新已精确读取，或已随写入资格注入完整正文的文档。target 必须使用 @短引用；文档 title、summary 或 aliases 过时时使用 set_metadata，只提供需要改变的 title、summary 或 aliases。至少提供一项；未提供的字段由 Runtime 从当前候选文档保留。YAML edit 使用 locator:{yaml:["字段","子字段"]}，例如 {op:"replace",locator:{yaml:["情况"]},value:"新值"}。locator 的每一段可以定位 map key 或从 0 开始的数组下标。add 与 replace 都是 upsert：无论目标是否已存在都写入，缺失的父级 map 会被创建，数组下标达到或超过长度时追加到末尾。remove 只删除 locator 精确指向的已有键或数组项；目标不存在时视为无操作，回执会注明。YAML value 需要引用整份文档时只能写 {$ref:"@短引用"}，短引用必须来自 Runtime 的 list、read 或 create 结果；不得自行编造文档 id。没有可用句柄时，根据语义使用普通文本，或先 world_create 后使用其返回的 @短引用。向已存在的 sequence 末尾加一项必须使用 append 并把 locator 指向该 sequence。Markdown locator 不包含文档 # 一级标题：{markdown:["职责"]} 精确指向 ## 职责，replace_section.markdown 必须从同级同名标题开始；该标题尚不存在时，replace_section 会把它新增到父级之下。add_section 在 locator 标题之下新增子小节；locator 为 [] 且 markdown 以二级标题开始时，则在正文末尾新增顶层小节。修改 # 标题下、第一个 ## 前的文字用 replace_preamble（只传该段文字）；替换整个 Markdown 正文用 replace_body，且 markdown 必须保留原 # 一级标题。每条 edit 独立结算：失败的 edit 被跳过，其余照常生效。成功结果只报告文档是否发生变化；回执列出失败的 edit 时，已生效的 edit 不要重发，只补上列出的 edit。不回显正文；只有后续决策依赖 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。",
         artifact_emit: "提交本次后置请求预先声明的产物。只能传 output name 与 payload；频道、key、内容类型、renderer、保存策略和权威含义由 Runtime contract 固定。",

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

@@ -0,0 +1,14 @@
+export function resolveToolName(called, provided) {
+    if (provided.includes(called))
+        return { kind: "exact", name: called };
+    const candidates = provided.filter((name) => called.length > name.length && called.endsWith(`_${name}`));
+    if (candidates.length === 1)
+        return { kind: "alias", name: candidates[0], declared: called };
+    return { kind: "rejected", candidates };
+}
+/** The Runtime note appended to a result whose call was restored by alias. */
+export function renderToolAliasNote(declared, name, locale) {
+    return locale === "zh-CN"
+        ? `Runtime 说明："${declared}" 不是本次提供的工具，已按 "${name}" 执行。请使用声明的工具名。`
+        : `Runtime note: "${declared}" is not a declared tool; it was executed as "${name}". Call tools by their declared names.`;
+}

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

@@ -14,70 +14,3 @@ export function worldMaterialCoverage(coverage) {
     });
     return { fullInjected, nodeInjected, catalogSummary, injectedSelections };
 }
-export function renderFreshContextCoverage(snapshot, coverage, shortRef, locale = "en") {
-    const exposure = worldMaterialCoverage(coverage);
-    const full = exposure.fullInjected.has(shortRef);
-    const nodes = exposure.nodeInjected.has(shortRef);
-    const summary = exposure.catalogSummary.has(shortRef);
-    const zh = locale === "zh-CN";
-    const scope = full
-        ? zh
-            ? "完整正文"
-            : "full body"
-        : nodes
-            ? zh
-                ? "指定节点"
-                : "selected nodes"
-            : summary
-                ? zh
-                    ? "仅目录摘要"
-                    : "catalog summary only"
-                : zh
-                    ? "不直接注入，需要按需读取"
-                    : "not directly injected; read on demand";
-    const lines = [
-        `${zh ? "如果现在新开上下文" : "If a fresh context started now"}: ${scope}${nodes && !full && summary ? (zh ? "，以及目录摘要" : " and catalog summary") : ""}`,
-    ];
-    if (!full && nodes) {
-        const scopes = exposure.injectedSelections.filter((entry) => entry.shortRef === shortRef && entry.locator !== null);
-        lines.push(`${zh ? "节点范围" : "Node scopes"}: ${scopes.map(({ locator }) => JSON.stringify(locator)).join(", ")}`);
-    }
-    if (!full && summary) {
-        const read = snapshot.query({
-            kind: "read_document",
-            document: { shortRef },
-        });
-        if (read.kind === "read_document")
-            lines.push(`${zh ? "摘要" : "Summary"}: ${read.document.summary}`);
-    }
-    if (!full && !nodes && !summary) {
-        const references = exposure.injectedSelections.flatMap((selection) => {
-            const read = snapshot.query({
-                kind: "read_document",
-                document: { shortRef: selection.shortRef },
-            });
-            const locator = selection.locator ??
-                (read.kind === "read_document" && read.codec === "yaml"
-                    ? { yaml: [] }
-                    : null);
-            if (locator === null)
-                return [];
-            const node = snapshot.query({
-                kind: "select_node",
-                document: { shortRef: selection.shortRef },
-                locator,
-            });
-            return node.kind === "select_node" &&
-                node.references.some(({ target }) => target.shortRef === shortRef)
-                ? [`@${selection.shortRef}`]
-                : [];
-        });
-        if (references.length > 0)
-            lines.push(`${zh ? "已注入材料中的直接引用来自" : "Direct reference in injected material"}: ${[...new Set(references)].join(", ")}`);
-        else if (coverage.some(({ status }) => status === "paged_catalog"))
-            lines.push(zh
-                ? "目录仍有后续页，可使用 state_list 继续查找。"
-                : "Catalogs have further pages; use state_list to continue discovery.");
-    }
-    return lines.join("\n");
-}

package/dist/node/runtime/setting/SettingAuthoringTransaction.js

@@ -2,10 +2,12 @@ import { isPackageFollowupControlPath } from "../content/PackageFollowups.js";
 import { renderWorldMaintenanceReport } from "../prompt/WorldMaintenanceReport.js";
 import { listWorldDocuments as listQueryableWorldDocuments } from "../prompt/WorldMaintenanceReport.js";
 import { defaultAppLocale } from "../../protocol/appPreferences.js";
-import { gameplayLabel, gameplayPath, readGameplay, } from "../../protocol/gameplay.js";
+import { fictionGameplay, gameplayLabel, gameplayPath, readGameplay, } from "../../protocol/gameplay.js";
 import { isScalar, isSeq, parseDocument, stringify } from "yaml";
 import { tabletopSchemeReceipt } from "../play/TabletopRules.js";
 import { inspectContentPackageCurrentTree } from "../content/FileNativeContentTree.js";
+import { coerceToolArguments, renderCoercionNote, } from "../model/ToolArgumentCoercion.js";
+import { renderToolAliasNote, resolveToolName, } from "../prompt/ToolNameAlias.js";
 import { worldMaterialCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { WorldDocumentStore, } from "../world/WorldDocumentStore.js";
 export const settingImprovementToolNames = [
@@ -434,11 +436,20 @@ export class SettingAuthoringTransaction {
         };
     }
     execute(calls) {
-        const normalized = calls.map((call) => normalizeCall(call, this.#surface));
+        const normalized = calls.map((call) => normalizeCall(call, this.#surface, this.#locale));
         const results = [];
         const responseBase = this.files();
         let lastSuccessfulWrite = -1;
         for (const call of normalized) {
+            if (call.rejection !== undefined) {
+                results.push({
+                    toolCallId: call.id,
+                    markdown: `# Runtime tool rejected\n\n${call.rejection}`,
+                    isError: true,
+                    changes: [],
+                });
+                continue;
+            }
             const before = this.files();
             const unavailable = unavailableArgument(this.#surface, call.arguments, this.#locale);
             if (unavailable !== null) {
@@ -466,6 +477,20 @@ export class SettingAuthoringTransaction {
             // model only needs what this tool response changed.
             settled.markdown = `${settled.markdown}\n\n${renderAutomaticReview(this.#review, fileDiff(responseBase, this.#snapshot.files), this.#snapshot, this.#surface, this.#locale)}`;
         }
+        normalized.forEach((call, index) => {
+            const notes = [
+                ...(call.coerced.length === 0
+                    ? []
+                    : [renderCoercionNote(call.coerced, this.#locale)]),
+                ...(call.alias === undefined
+                    ? []
+                    : [renderToolAliasNote(call.alias, call.name, this.#locale)]),
+            ];
+            if (notes.length === 0)
+                return;
+            const result = results[index];
+            result.markdown = `${result.markdown}\n\n${notes.join("\n\n")}`;
+        });
         return results;
     }
     #executeRead(call) {
@@ -758,14 +783,41 @@ class SettingAuthoringError extends Error {
         this.name = "SettingAuthoringError";
     }
 }
-function normalizeCall(call, surface) {
+function normalizeCall(call, surface, locale) {
+    const cloned = isRecord(call.arguments)
+        ? structuredClone(call.arguments)
+        : {};
+    const definitions = authoringToolDefinitions(surface, locale, fictionGameplay);
+    const provided = definitions.map(({ name }) => name);
+    const resolved = resolveToolName(call.name, provided);
+    if (resolved.kind === "rejected")
+        return {
+            id: call.id,
+            name: call.name,
+            operation: null,
+            arguments: cloned,
+            coerced: [],
+            rejection: unknownToolMessage(call.name, provided, locale),
+        };
+    const name = resolved.name;
+    const schema = definitions.find((definition) => definition.name === name)?.inputSchema;
+    const repaired = schema === undefined
+        ? { arguments: cloned, coerced: [] }
+        : coerceToolArguments(schema, cloned);
     return {
         id: call.id,
-        name: call.name,
-        operation: authoringOperation(surface, call.name),
-        arguments: isRecord(call.arguments) ? structuredClone(call.arguments) : {},
+        name,
+        operation: authoringOperation(surface, name),
+        arguments: repaired.arguments,
+        coerced: repaired.coerced,
+        ...(resolved.kind === "alias" ? { alias: resolved.declared } : {}),
     };
 }
+function unknownToolMessage(name, provided, locale) {
+    return locale === "zh-CN"
+        ? `${name} 不是本界面提供的工具。可用工具：${provided.join(", ")}。`
+        : `${name} is not a tool on this surface. Available tools: ${provided.join(", ")}.`;
+}
 function isReadOperation(operation) {
     return operation === "list" || operation === "search" || operation === "read";
 }
@@ -1474,6 +1526,8 @@ function requiredSettingRef(value, locale) {
     return value;
 }
 function requiredAliases(value) {
+    if (typeof value === "string")
+        throw new SettingAuthoringError("aliases must be a JSON array of at most 16 strings, not a string");
     if (!Array.isArray(value) ||
         value.length > 16 ||
         !value.every((item) => typeof item === "string" &&
@@ -1508,6 +1562,8 @@ function assertNoLiteralUnicodeEscapes(value, locale) {
     walk(value);
 }
 function requiredYamlLocatorPath(value, name) {
+    if (typeof value === "string")
+        throw new SettingAuthoringError(`${name} must be a JSON array of map keys or zero-based array indexes, not a string`);
     if (!Array.isArray(value) ||
         value.length === 0 ||
         !value.every((item) => (typeof item === "string" && item.length > 0) ||