narraeon 0.7.5 → 0.7.6

package/dist/node/protocol/v1.js

@@ -353,6 +353,10 @@ function validateRequestFields(request) {
     if (request.type === "play.timeline.detail" &&
         (!Number.isSafeInteger(request.eventId) || Number(request.eventId) < 1))
         throw new V1ProtocolError("invalid_request", "play.timeline.detail.eventId is invalid");
+    if ("turnNote" in request &&
+        request.turnNote !== undefined &&
+        typeof request.turnNote !== "string")
+        throw new V1ProtocolError("invalid_request", "turnNote is invalid");
     if (request.type === "play.chain.revise-player" &&
         request.continuation !== "continue_context" &&
         request.continuation !== "fresh_context")

package/dist/node/runtime/V1Runtime.js

@@ -458,6 +458,9 @@ export class V1Runtime {
                     }), `content:${request.packageId}.message.genesis.narrator`, "content-preview"),
                     playerInputPlacement: "append",
                     playerInput: request.playerInput,
+                    ...(request.turnNote === undefined
+                        ? {}
+                        : { turnNote: request.turnNote }),
                     modelBinding: modelHost.binding(),
                 }, playPreset);
                 const tools = structuredClone(preview.compilation.toolUniverse ?? preview.compilation.tools);
@@ -669,6 +672,9 @@ export class V1Runtime {
                     eventId: request.eventId,
                     replacementExchangeId: request.replacementExchangeId,
                     replacementText: request.replacementText,
+                    ...(request.turnNote === undefined
+                        ? {}
+                        : { turnNote: request.turnNote }),
                 };
                 const result = await playCall(async () => {
                     await this.#worlds.assertWorldRevisionUnlocked(request.worldId);
@@ -695,6 +701,9 @@ export class V1Runtime {
                     chainId: request.chainId,
                     exchangeId: request.exchangeId,
                     playerText: request.playerText,
+                    ...(request.turnNote === undefined
+                        ? {}
+                        : { turnNote: request.turnNote }),
                     hostBinding,
                     playPreset,
                     modelBinding,
@@ -712,6 +721,9 @@ export class V1Runtime {
                         chainId: request.chainId,
                         exchangeId: request.exchangeId,
                         playerText: request.playerText,
+                        ...(request.turnNote === undefined
+                            ? {}
+                            : { turnNote: request.turnNote }),
                         modelHost: await this.#modelHost(),
                         resolvePrompt: () => this.#continuousBinding(),
                         ...(playCallChainObserver === undefined

package/dist/node/runtime/model/ToolArgumentCoercion.js

@@ -0,0 +1,138 @@
+/** Root arguments are depth 0; parsing and descent stop after two levels. */
+const maxCoercionDepth = 2;
+export function coerceToolArguments(schema, args) {
+    const coerced = [];
+    const value = coerceValue(schema, args, "", 0, coerced);
+    return { arguments: value, coerced };
+}
+/**
+ * Renders the Runtime note appended to a tool result whose arguments were
+ * parsed. It tells the model its arguments were repaired, so the next call
+ * can send native JSON values.
+ */
+export function renderCoercionNote(paths, locale) {
+    const names = paths.map((path) => `"${path}"`).join(", ");
+    return locale === "zh-CN"
+        ? `Runtime 说明：以下参数以 JSON 字符串到达，本次已解析后执行：${names}。请以 JSON 数组或对象的原生值发送，不要用字符串。`
+        : `Runtime note: these arguments arrived as JSON strings and were parsed for this call: ${names}. Send array and object arguments as native JSON values, not strings.`;
+}
+function coerceValue(schema, value, path, depth, coerced) {
+    const type = definiteType(schema);
+    let current = value;
+    if ((type === "array" || type === "object") &&
+        typeof current === "string" &&
+        depth > 0 &&
+        depth <= maxCoercionDepth) {
+        const parsed = parseJson(current);
+        if (matchesType(type, parsed)) {
+            current = parsed;
+            coerced.push(path);
+        }
+    }
+    if (depth >= maxCoercionDepth)
+        return current;
+    if (type === "array" && isArray(current)) {
+        const items = itemsSchema(schema);
+        if (items === undefined)
+            return current;
+        let next = current;
+        current.forEach((element, index) => {
+            const repaired = coerceValue(items, element, `${path}[${index}]`, depth + 1, coerced);
+            if (repaired !== element) {
+                if (next === current)
+                    next = [...current];
+                next[index] = repaired;
+            }
+        });
+        return next;
+    }
+    if (type === "object" && isRecord(current)) {
+        let next = current;
+        for (const key of Object.keys(current)) {
+            const property = propertySchema(schema, key);
+            if (property === undefined)
+                continue;
+            const repaired = coerceValue(property, current[key], path === "" ? key : `${path}.${key}`, depth + 1, coerced);
+            if (repaired !== current[key]) {
+                if (next === current)
+                    next = { ...current };
+                next[key] = repaired;
+            }
+        }
+        return next;
+    }
+    return current;
+}
+/** The single type a schema position admits, or undefined when it is not definite. */
+function definiteType(schema) {
+    if (!isRecord(schema))
+        return undefined;
+    if (schema.type !== undefined) {
+        if (typeof schema.type === "string")
+            return schema.type;
+        if (Array.isArray(schema.type) &&
+            schema.type.length === 1 &&
+            typeof schema.type[0] === "string")
+            return schema.type[0];
+        return undefined;
+    }
+    const branches = Array.isArray(schema.oneOf)
+        ? schema.oneOf
+        : Array.isArray(schema.anyOf)
+            ? schema.anyOf
+            : undefined;
+    if (branches === undefined || branches.length === 0)
+        return undefined;
+    const types = branches.map(definiteType);
+    const first = types[0];
+    return first !== undefined && types.every((type) => type === first)
+        ? first
+        : undefined;
+}
+function itemsSchema(schema) {
+    return isRecord(schema.items) && !Array.isArray(schema.items)
+        ? schema.items
+        : undefined;
+}
+/**
+ * A property schema is taken directly from `properties`, or from oneOf/anyOf
+ * branches only when every branch that declares the key declares it the same.
+ */
+function propertySchema(schema, key) {
+    if (isRecord(schema.properties) && isRecord(schema.properties[key]))
+        return schema.properties[key];
+    const branches = Array.isArray(schema.oneOf)
+        ? schema.oneOf
+        : Array.isArray(schema.anyOf)
+            ? schema.anyOf
+            : [];
+    const declared = branches
+        .map((branch) => isRecord(branch) && isRecord(branch.properties)
+        ? branch.properties[key]
+        : undefined)
+        .filter((property) => property !== undefined);
+    if (declared.length === 0)
+        return undefined;
+    const serialized = declared.map((property) => JSON.stringify(property));
+    return serialized.every((text) => text === serialized[0]) &&
+        isRecord(declared[0])
+        ? declared[0]
+        : undefined;
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function matchesType(type, value) {
+    return type === "array" ? Array.isArray(value) : isRecord(value);
+}
+function isArray(value) {
+    return Array.isArray(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -948,7 +948,8 @@ function assertPlayEvent(value) {
     if (value.kind === "tool_call") {
         if (typeof value.callId !== "string" ||
             typeof value.name !== "string" ||
-            typeof value.replayed !== "boolean")
+            typeof value.replayed !== "boolean" ||
+            !validOptionalString(value.executedName))
             throw new Error("Tool-call timeline event has an invalid shape");
         return;
     }
@@ -960,7 +961,8 @@ function assertPlayEvent(value) {
             typeof value.name !== "string" ||
             typeof value.ok !== "boolean" ||
             typeof value.markdown !== "string" ||
-            typeof value.replayed !== "boolean")
+            typeof value.replayed !== "boolean" ||
+            !validOptionalString(value.executedName))
             throw new Error("Tool-result timeline event has an invalid shape");
         return;
     }
@@ -1014,6 +1016,7 @@ function assertTimelineEventSummary(value) {
         if (typeof value.callId !== "string" ||
             typeof value.name !== "string" ||
             typeof value.replayed !== "boolean" ||
+            !validOptionalString(value.executedName) ||
             value.detailsAvailable !== true)
             throw new Error("Tool-call timeline summary has an invalid shape");
         return;
@@ -1026,6 +1029,7 @@ function assertTimelineEventSummary(value) {
             typeof value.name !== "string" ||
             typeof value.ok !== "boolean" ||
             typeof value.replayed !== "boolean" ||
+            !validOptionalString(value.executedName) ||
             value.detailsAvailable !== true)
             throw new Error("Tool-result timeline summary has an invalid shape");
         return;

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

@@ -1,8 +1,6 @@
 import { createHash } from "node:crypto";
 import { isMap, isSeq, parseDocument } from "yaml";
-import { builtinPlayPrompts, isPromptMessageRole, promptGroups, } from "../../shared/ordered-play-prompts.js";
-/** One turn-guide line: no line breaks, bounded length; empty clears a builtin default. */
-const turnGuideLine = /^[^\r\n\0]{0,1000}$/u;
+import { builtinPlayPrompts, isPromptMessageRole, isTurnGuideLine, promptGroups, } from "../../shared/ordered-play-prompts.js";
 const promptName = /^[^\r\n\0]{1,160}$/u;
 /** The same strict permission gate is used by portable imports and structured saves. */
 export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"), worldRequired = true) {
@@ -33,8 +31,7 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
             key === "id" ||
             key === "kind") && keys.every((key) => Object.hasOwn(item, key));
         const validTurnGuide = item.turnGuide === undefined ||
-            (typeof item.turnGuide === "string" &&
-                turnGuideLine.test(item.turnGuide));
+            (typeof item.turnGuide === "string" && isTurnGuideLine(item.turnGuide));
         const turnGuide = typeof item.turnGuide === "string" ? { turnGuide: item.turnGuide } : {};
         if (item.kind === "world" && exact(["id", "kind"])) {
             worlds++;
@@ -47,7 +44,7 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
             item.name.trim().length > 0 &&
             promptName.test(item.name) &&
             typeof item.body === "string" &&
-            turnGuideLine.test(item.body) &&
+            isTurnGuideLine(item.body) &&
             typeof item.enabled === "boolean")
             return [
                 {

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

@@ -4,11 +4,14 @@ import { isResolutionTool, resolutionMarkdown, resolutionToolNames, resolveTable
 import { captureNarrativeOrigin, snapshotBackground, narrativeBackground, } from "../history/HistoryBackground.js";
 import { isDeepStrictEqual } from "node:util";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
+import { renderToolAliasNote, resolveToolName, } from "../prompt/ToolNameAlias.js";
 import { PlayCallChainError } from "./PlayCallChainError.js";
 import { preparePlayerRevisionTrace, prepareForkTrace, restorePlayDocuments, independentContextCopy, } from "./PlayTraceRetention.js";
 import { cloneSharingPromptRuns, currentPlayPrompt, recordedPlayPrompt, playPromptRunsThroughEvents, promptRunStrings, sharePromptRun, } from "./PlayPromptRun.js";
 import { comparePromptPrefixes } from "../prompt/WorldPromptDiagnostics.js";
 import { createHash, randomBytes } from "node:crypto";
+import { isTurnGuideLine } from "../../shared/ordered-play-prompts.js";
+import { turnGuideWithTurnNote } from "../../shared/turn-guide.js";
 import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepNotice, turnGuideNotice, } from "./PlayContinuity.js";
 import { renderFreshContextCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { renderWriteSizeAdvice, readDeclaredWorldClock, } from "../prompt/WorldMaintenanceReport.js";
@@ -103,6 +106,7 @@ export class PlayCallChain {
         validateIdentity(input.chainId, "call-chain ID");
         validateIdentity(input.exchangeId, "exchange ID");
         validatePlayerText(input.playerText);
+        validTurnNote(input.turnNote);
         assertModelHostBinding(input.modelBinding, input.modelHost);
         // Only a resubmission to the current context needs that context loaded.
         await this.#worlds.ensureCurrentStorage(input.worldId);
@@ -152,6 +156,7 @@ export class PlayCallChain {
             canRetry: false,
             bootstrap: fresh.bootstrap,
             tools: fresh.tools,
+            ...turnNoteField(validTurnNote(input.turnNote)),
             transcript: [],
             events: [],
             completedTools: [],
@@ -243,6 +248,9 @@ export class PlayCallChain {
                 return this.#dispatch(session, input.modelHost, structuredClone(session.lastRequest), session.lastRequestAttempt + 1, signal, input.observer);
             }
             await this.#refreshPrompt(session, input);
+            // Each dispatch carries exactly the request the client sent with it; a
+            // continuation without one must not inherit the previous turn's line.
+            setTurnNote(session, validTurnNote(input.turnNote));
             session.exchange += 1;
             const last = session.transcript.at(-1);
             if (last?.kind === "assistant" &&
@@ -251,7 +259,7 @@ export class PlayCallChain {
                 session.narrativeOrigin = await this.#captureOrigin(session);
                 session.transcript.push(continuationNotice(this.#compiler.locale));
             }
-            return this.#dispatch(session, input.modelHost, createRequest(session, input.modelHost, session.exchange), 1, signal, input.observer);
+            return this.#dispatch(session, input.modelHost, createRequest(session, input.modelHost, session.exchange, this.#compiler.locale), 1, signal, input.observer);
         }
         if (duplicatePlayerExchange(session, input.exchangeId, input.playerText, "append"))
             return projectView(session);
@@ -260,6 +268,7 @@ export class PlayCallChain {
                 ? "The call chain has an incomplete model response; clear the input and append a continuation, or use a fresh context."
                 : "The call chain was interrupted; use a fresh context.");
         await this.#refreshPrompt(session, input);
+        setTurnNote(session, validTurnNote(input.turnNote));
         return this.#submitPlayer(session, input.exchangeId, input.playerText, "append", input.modelHost, signal, input.observer);
     }
     async #refreshPrompt(session, input) {
@@ -746,6 +755,7 @@ export class PlayCallChain {
             eventId: input.eventId,
             replacementExchangeId: input.replacementExchangeId,
             replacementText: input.replacementText,
+            ...turnNoteField(validTurnNote(input.turnNote)),
             continuation: input.continuation,
             restoresHead: playerRevisionRestoresHead(sourceContext, eventIndex),
             discardChainIds: contexts
@@ -854,6 +864,7 @@ export class PlayCallChain {
                 previousContexts: [],
                 previousChainId,
                 timelineGeneration,
+                ...turnNoteField(intent.turnNote),
                 parentHead: head,
                 updatedAt: Date.now(),
             };
@@ -974,6 +985,7 @@ export class PlayCallChain {
                 revision: input.freshContext.playPreset.revision,
             },
             followups: structuredClone(fresh.followups),
+            ...turnNoteField(input.intent.turnNote),
             playPresetScriptsEnabled: input.freshContext.playPreset.scriptsEnabled,
             presetFiles: structuredClone(input.freshContext.playPreset.files),
             modelBinding: structuredClone(input.freshContext.modelBinding),
@@ -1141,10 +1153,7 @@ export class PlayCallChain {
             throw new PlayCallChainError("The call chain is waiting for the model to return.");
         session.narrativeOrigin = await this.#captureOrigin(session);
         const exchange = session.exchange + 1;
-        const nextRequest = createRequest(session, modelHost, exchange, [
-            ...session.transcript,
-            ...playerInputAppend(playerText),
-        ]);
+        const nextRequest = createRequest(session, modelHost, exchange, this.#compiler.locale, [...session.transcript, ...playerInputAppend(playerText)]);
         const operationKey = `player:${exchangeId}`;
         const playerOperationId = operationId(session.chainId, operationKey);
         const advance = {
@@ -1276,7 +1285,11 @@ export class PlayCallChain {
         let nextEventId = advance.eventId + 1;
         // Fresh in-memory seed per settlement. It is never persisted: a crashed
         // exchange is retried by the player and re-rolls (ADR-0044).
-        const resolutionSeed = calls.some(({ name }) => isResolutionTool(name))
+        const providedToolNames = currentPlayPrompt(session).tools.map(({ name }) => name);
+        const resolutionSeed = calls.some(({ name }) => {
+            const resolved = resolveToolName(name, providedToolNames);
+            return resolved.kind !== "rejected" && isResolutionTool(resolved.name);
+        })
             ? randomBytes(32).toString("hex")
             : undefined;
         for (const call of calls) {
@@ -1287,6 +1300,9 @@ export class PlayCallChain {
                 kind: "tool_call",
                 callId: call.id,
                 name: call.name,
+                ...(item.event.executedName === undefined
+                    ? {}
+                    : { executedName: item.event.executedName }),
                 arguments: structuredClone(call.arguments),
                 replayed: item.replayed,
             });
@@ -1348,7 +1364,7 @@ export class PlayCallChain {
             session.events.some((event) => event.id >
                 Math.max(previousNarrative?.id ?? 0, previousPlayer?.id ?? 0) &&
                 event.kind === "tool_result" &&
-                event.name === "world_checkpoint" &&
+                (event.executedName ?? event.name) === "world_checkpoint" &&
                 event.ok);
         const narrativeCheckpoint = checkpointRequested
             ? {
@@ -1475,7 +1491,7 @@ export class PlayCallChain {
         }
         if (hasToolCalls) {
             session.exchange += 1;
-            const nextRequest = createRequestWithMaxOutputTokens(session, session.lastRequest?.maxOutputTokens ?? 1, session.exchange);
+            const nextRequest = createRequestWithMaxOutputTokens(session, session.lastRequest?.maxOutputTokens ?? 1, session.exchange, this.#compiler.locale);
             if (session.lastRequest?.modelConfig !== undefined)
                 nextRequest.modelConfig = structuredClone(session.lastRequest.modelConfig);
             await this.#advances.end(session, {
@@ -1942,14 +1958,16 @@ export class PlayCallChain {
 function followupOperationId(session) {
     return `${session.chainId}:followup:${session.parentHead}`;
 }
-function createRequest(session, modelHost, exchange, appended = session.transcript) {
-    const request = createRequestWithMaxOutputTokens(session, modelHost.binding().maxOutputTokens, exchange, appended);
+function createRequest(session, modelHost, exchange, locale, appended = session.transcript) {
+    const request = createRequestWithMaxOutputTokens(session, modelHost.binding().maxOutputTokens, exchange, locale, appended);
     return modelHost.freezeRequest?.(request) ?? request;
 }
-function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, appended = session.transcript) {
+function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, locale, appended = session.transcript) {
     // The turn guide is a request-level suffix: it follows whatever this
-    // dispatch appends and is never part of the transcript it is built on.
-    const turnGuide = currentPlayPrompt(session).bootstrap.turnGuide;
+    // dispatch appends and is never part of the transcript it is built on. The
+    // player's one-turn request joins the suffix here, not in the bootstrap, so
+    // the bootstrap snapshot stays shared by every dispatch of the turn.
+    const turnGuide = turnGuideWithTurnNote(locale, currentPlayPrompt(session).bootstrap.turnGuide, session.turnNote);
     return {
         bootstrap: structuredClone(currentPlayPrompt(session).bootstrap),
         tools: structuredClone(currentPlayPrompt(session).tools),
@@ -2043,13 +2061,17 @@ function appendCommittedHistory(session, head, messages) {
 function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
     const key = `${exchange}:${call.id}`;
     const signature = JSON.stringify(call.arguments);
+    const provided = currentPlayPrompt(session).tools.map(({ name }) => name);
+    const resolved = resolveToolName(call.name, provided);
+    // The executed name, not the model's spelling, decides replay identity.
+    const executedName = resolved.kind === "rejected" ? call.name : resolved.name;
     const completed = working.get(key);
     let result;
     let replayed = false;
     if (completed !== undefined) {
         replayed = true;
         result =
-            completed.name === call.name && completed.signature === signature
+            completed.name === executedName && completed.signature === signature
                 ? structuredClone(completed.result)
                 : {
                     ok: false,
@@ -2057,19 +2079,19 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
                     markdown: "# Runtime tool rejected\n\nThe same tool-call ID is already bound to another tool name or argument set.",
                 };
     }
-    else if (!callChainToolNames.has(call.name) ||
-        !currentPlayPrompt(session).tools.some(({ name }) => name === call.name)) {
+    else if (resolved.kind === "rejected" ||
+        !callChainToolNames.has(executedName)) {
         result = {
             ok: false,
             failureKind: "protocol",
-            markdown: `# Runtime tool rejected\n\nThe current call chain does not provide ${call.name}.`,
+            markdown: `# Runtime tool rejected\n\nThe current call chain does not provide ${call.name}. Available tools: ${provided.join(", ")}.`,
         };
     }
     else {
         try {
-            result = isResolutionTool(call.name)
-                ? resolutionToolResult(call.name, call.arguments, resolutionSeed, key, locale)
-                : call.name === "world_checkpoint"
+            result = isResolutionTool(executedName)
+                ? resolutionToolResult(executedName, call.arguments, resolutionSeed, key, locale)
+                : executedName === "world_checkpoint"
                     ? typeof call.arguments === "object" &&
                         call.arguments !== null &&
                         !Array.isArray(call.arguments) &&
@@ -2085,7 +2107,7 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
                             failureKind: "protocol",
                             markdown: "world_checkpoint requires an empty argument object.",
                         }
-                    : session.documents.execute(call, session.history, {
+                    : session.documents.execute({ ...call, name: executedName }, session.history, {
                         historyScope: session.worldId,
                         locale,
                         legacyHistoryTools: hasLegacyHistoryTools(currentPlayPrompt(session).tools),
@@ -2098,9 +2120,14 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
                 markdown: `# Runtime tool failed\n\n${error instanceof Error ? error.message : "Tool execution failed."}`,
             };
         }
+        if (resolved.kind === "alias")
+            result = {
+                ...result,
+                markdown: `${result.markdown}\n\n${renderToolAliasNote(call.name, executedName, locale)}`,
+            };
         working.set(key, {
             key,
-            name: call.name,
+            name: executedName,
             signature,
             result: structuredClone(result),
         });
@@ -2110,6 +2137,7 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
         kind: "tool_result",
         callId: call.id,
         name: call.name,
+        ...(executedName === call.name ? {} : { executedName }),
         ok: result.ok,
         markdown: result.markdown,
         ...(result.resolution === undefined
@@ -2240,7 +2268,8 @@ function projectContextReads(session) {
             exchange = event.exchange;
             continue;
         }
-        if (event.kind === "tool_call" && event.name === "context_read") {
+        if (event.kind === "tool_call" &&
+            (event.executedName ?? event.name) === "context_read") {
             const ref = isRecord(event.arguments) && typeof event.arguments.ref === "string"
                 ? event.arguments.ref
                 : "(invalid ref)";
@@ -2250,7 +2279,8 @@ function projectContextReads(session) {
             });
             continue;
         }
-        if (event.kind !== "tool_result" || event.name !== "context_read")
+        if (event.kind !== "tool_result" ||
+            (event.executedName ?? event.name) !== "context_read")
             continue;
         const call = calls.get(event.callId);
         if (call === undefined)
@@ -2354,6 +2384,28 @@ function validatePlayerText(value) {
     if (value.trim().length === 0)
         throw new PlayCallChainError("Player text must not be empty.");
 }
+/**
+ * The player's one-turn request: one line, bounded like a turn-guide line.
+ * Blank input means no request. Length beyond the soft limit is only warned
+ * about by the client and Prompt Preview, never rejected here.
+ */
+function validTurnNote(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isTurnGuideLine(value))
+        throw new PlayCallChainError("The turn request must be a single line of at most 1000 characters.");
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function setTurnNote(session, turnNote) {
+    if (turnNote === undefined)
+        delete session.turnNote;
+    else
+        session.turnNote = turnNote;
+}
+function turnNoteField(turnNote) {
+    return turnNote === undefined ? {} : { turnNote };
+}
 function touch(session) {
     session.updatedAt = Date.now();
 }

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

@@ -5,6 +5,8 @@ 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 { acceptWorldStateRevision, beginWorldStateRevision, fileNativeStateChanges, worldDocumentRevisionFailureMessage, } from "../world/WorldStateRevision.js";
@@ -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) ||
@@ -419,6 +436,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";
@@ -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.
  *

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.`;
+}