narraeon 0.7.5 → 0.7.7

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/FileNativeContinuityCorrection.js

@@ -4,7 +4,7 @@ import { FileNativePromptCompiler, } from "../prompt/FileNativePromptCompiler.js
 import { validateMaterialList } from "../prompt/MaterialSelection.js";
 import { FileNativeWorldCreationError, } from "../world/FileNativeWorldStore.js";
 import { WorldOperationBusyError, } from "../world/WorldOperationCoordinator.js";
-import { beginWorldStateRevision, fileNativeStateChanges, reviseWorldState, worldDocumentRevisionFailureMessage, worldStateRevisionChanges, } from "../world/WorldStateRevision.js";
+import { beginWorldStateRevision, fileNativeStateChanges, acceptWorldStateRevision, worldDocumentRevisionFailureMessage, worldStateRevisionChanges, } from "../world/WorldStateRevision.js";
 export class FileNativeContinuityCorrection {
     #worlds;
     #compiler;
@@ -260,9 +260,17 @@ export class FileNativeContinuityCorrection {
         return document;
     }
     #reviseDocument(candidate, command) {
-        const revised = reviseWorldState(candidate, { commands: [command] });
-        if (!revised.ok || revised.snapshotStatus !== "usable")
-            throw new Error(worldDocumentRevisionFailureMessage(revised.diagnostics));
+        // A correction applies all of its edits or none of them, so a skipped edit
+        // is a failure here even though the revision itself settled.
+        const revised = candidate.snapshot.revise({ commands: [command] });
+        const failures = revised.ok
+            ? revised.editOutcomes.flatMap(({ status, diagnostic }) => status === "failed" && diagnostic !== undefined ? [diagnostic] : [])
+            : revised.diagnostics;
+        if (!revised.ok ||
+            revised.snapshotStatus !== "usable" ||
+            failures.length > 0)
+            throw new Error(worldDocumentRevisionFailureMessage(failures));
+        acceptWorldStateRevision(candidate, revised);
         candidate.reads.clear();
     }
     #advance(candidate) {

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,13 +4,15 @@ 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";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
 import { equalModelHostBinding, ModelHostCancelledError, } from "../model/ModelHost.js";
@@ -103,6 +105,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 +155,7 @@ export class PlayCallChain {
             canRetry: false,
             bootstrap: fresh.bootstrap,
             tools: fresh.tools,
+            ...turnNoteField(validTurnNote(input.turnNote)),
             transcript: [],
             events: [],
             completedTools: [],
@@ -243,6 +247,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 +258,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 +267,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 +754,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 +863,7 @@ export class PlayCallChain {
                 previousContexts: [],
                 previousChainId,
                 timelineGeneration,
+                ...turnNoteField(intent.turnNote),
                 parentHead: head,
                 updatedAt: Date.now(),
             };
@@ -974,6 +984,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 +1152,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 +1284,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 +1299,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,
             });
@@ -1313,7 +1328,7 @@ export class PlayCallChain {
                     ],
                 });
                 worldClock = readDeclaredWorldClock(snapshot);
-                const { coverage, maintenance } = this.#compiler.inspectWorldMaterials({
+                const { maintenance } = this.#compiler.inspectWorldMaterials({
                     controlFingerprint: "receipt",
                     documentSnapshot: snapshot,
                     history: Object.fromEntries(session.history.map(({ path, contents }) => [path, contents])),
@@ -1321,23 +1336,18 @@ export class PlayCallChain {
                 });
                 for (const { result } of writes) {
                     const write = result.candidateWrite;
-                    write.freshContextCoverage = renderFreshContextCoverage(snapshot, coverage, write.shortRef, this.#compiler.locale);
                     const previous = session.documents.committedSnapshot.query({
                         kind: "read_document",
                         document: { shortRef: write.shortRef },
                     });
-                    const advice = renderWriteSizeAdvice(maintenance, write.shortRef, previous.kind === "read_document"
+                    write.sizeAdvice = renderWriteSizeAdvice(maintenance, write.shortRef, previous.kind === "read_document"
                         ? Buffer.byteLength(previous.body, "utf8")
                         : null, this.#compiler.locale);
-                    if (advice.length > 0)
-                        write.freshContextCoverage += `\n${advice}`;
                 }
             }
-            catch (error) {
-                // A coverage prediction must never reject an otherwise valid write.
-                const reason = error instanceof Error ? error.message : "Material selection failed";
-                for (const { result } of writes)
-                    result.candidateWrite.freshContextCoverage = `${this.#compiler.locale === "zh-CN" ? "暂时无法判定下次注入；写入结果不受影响。原因" : "Fresh-context coverage unavailable; the write result is unaffected. Reason"}: ${reason}`;
+            catch {
+                // Maintenance advice is diagnostic: a failure omits it and never
+                // rejects or undoes an accepted write.
             }
         }
         const previousNarrative = session.events.findLast((event) => event.kind === "assistant" &&
@@ -1348,7 +1358,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 +1485,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 +1952,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),
@@ -1997,7 +2009,7 @@ function finalizeWriteReceipts(settlement) {
         const status = candidateWrite.changed && committedWriteRefs.has(candidateWrite.shortRef)
             ? `@${candidateWrite.shortRef} write succeeded`
             : `@${candidateWrite.shortRef} unchanged`;
-        const markdown = [status, candidateWrite.freshContextCoverage]
+        const markdown = [status, candidateWrite.sizeAdvice]
             .filter(Boolean)
             .join("\n");
         completed.result.markdown = markdown;
@@ -2043,13 +2055,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 +2073,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 +2101,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 +2114,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 +2131,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 +2262,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 +2273,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 +2378,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();
 }