narraeon 0.1.1 → 0.3.0

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

@@ -114,6 +114,12 @@ export class FileNativePlayDocuments {
     execute(call, history) {
         if (call.name === "context_search")
             return executeContextSearch(this.#candidate.snapshot, history, call.arguments);
+        if (call.name === "state_list")
+            return executeStateList(this.#candidate.snapshot, history, call.arguments);
+        if (call.name === "history_list")
+            return executeHistoryList(this.#candidate.snapshot, history, call.arguments);
+        // Frozen contexts created before runtime-tools-v5 retain this exact name
+        // and argument shape. New contexts never advertise it.
         if (call.name === "context_list")
             return executeContextList(this.#candidate.snapshot, history, call.arguments);
         if (call.name === "context_read") {
@@ -470,6 +476,10 @@ function toolFailure(message, failureKind = "protocol") {
     };
 }
 function previewContextToolResult(snapshot, history, call) {
+    if (call.name === "state_list")
+        return executeStateList(snapshot, history, call.arguments);
+    if (call.name === "history_list")
+        return executeHistoryList(snapshot, history, call.arguments);
     if (call.name === "context_list")
         return executeContextList(snapshot, history, call.arguments);
     if (call.name === "context_search")
@@ -640,6 +650,31 @@ function parseStateDirectoryHandle(handle) {
         return null;
     }
 }
+function executeStateList(snapshot, history, args) {
+    if (!record(args) ||
+        !hasOnlyToolKeys(args, ["parent", "cursor", "limit"]) ||
+        typeof args.parent !== "string" ||
+        parseStateDirectoryHandle(args.parent) === null ||
+        (args.limit !== undefined && typeof args.limit !== "number") ||
+        !validOptionalCursor(args.cursor))
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nstate_list requires an @dir-* parent returned by Runtime and accepts only cursor and limit in addition; use history_list for committed history.",
+        };
+    return executeContextList(snapshot, history, { ...args, source: "state" });
+}
+function executeHistoryList(snapshot, history, args) {
+    if (!record(args) ||
+        !hasOnlyToolKeys(args, ["order", "cursor", "limit"]) ||
+        (args.order !== "newest_first" && args.order !== "oldest_first") ||
+        (args.limit !== undefined && typeof args.limit !== "number") ||
+        !validOptionalCursor(args.cursor))
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nhistory_list requires newest_first or oldest_first order and accepts only cursor and limit in addition; use state_list for state directories.",
+        };
+    return executeContextList(snapshot, history, { ...args, source: "history" });
+}
 function executeContextList(snapshot, history, args) {
     if (!record(args) || (args.source !== "state" && args.source !== "history"))
         return {

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

@@ -1,3 +1,4 @@
+import { ModelHostCancelledError } from "../model/ModelHost.js";
 import { errorDescription, } from "../model/AiFailureLog.js";
 /**
  * Run every follow-up declared by the frozen play preset exactly once after the
@@ -24,11 +25,15 @@ export async function runPlayFollowupRequests(input) {
     const completed = [];
     let failure;
     for (const followup of input.followups) {
-        if (input.signal?.aborted === true) {
+        if (signalWasAborted(input.signal)) {
             failure ??= "The follow-up request was cancelled.";
             break;
         }
         const outcome = await runOne(input, followup, prefix);
+        if (signalWasAborted(input.signal)) {
+            failure ??= "The follow-up request was cancelled.";
+            break;
+        }
         outcomes.push(outcome);
         input.observer?.onOutcome?.(outcome);
         if (outcome.failure === undefined)
@@ -58,27 +63,39 @@ async function runOne(input, followup, prefix) {
     let responseDiagnostics;
     try {
         await input.artifacts.beginRequestAttempt(requestContext);
-        const response = await input.modelHost.exchange({
-            bootstrap: structuredClone(input.bootstrap),
-            tools: structuredClone(followup.tools),
-            toolUniverse: structuredClone(followup.tools),
-            allowedTools: [...followup.allowedTools],
-            toolStrategy: input.toolStrategy,
-            // The prompt replaces the previous followup's prompt instead of being
-            // appended after it: every request sees exactly the main-chain prefix.
-            appended: [
-                ...structuredClone(prefix),
-                {
-                    kind: "prompt_delta",
-                    logicalMessages: structuredClone(followup.logicalMessages),
-                },
-            ],
-            requestId: followup.id,
-            operationId: input.context.operationId,
-            requestAttempt: 1,
-            exchange: 1,
-            maxOutputTokens: input.maxOutputTokens,
-        });
+        input.observer?.onProviderDispatch?.();
+        let response;
+        try {
+            response = await input.modelHost.exchange({
+                bootstrap: structuredClone(input.bootstrap),
+                tools: structuredClone(followup.tools),
+                toolUniverse: structuredClone(followup.tools),
+                allowedTools: [...followup.allowedTools],
+                toolStrategy: input.toolStrategy,
+                // The prompt replaces the previous followup's prompt instead of being
+                // appended after it: every request sees exactly the main-chain prefix.
+                appended: [
+                    ...structuredClone(prefix),
+                    {
+                        kind: "prompt_delta",
+                        logicalMessages: structuredClone(followup.logicalMessages),
+                    },
+                ],
+                requestId: followup.id,
+                operationId: input.context.operationId,
+                requestAttempt: 1,
+                exchange: 1,
+                maxOutputTokens: input.maxOutputTokens,
+            }, {
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                onDelta: (delta) => input.observer?.onProviderDelta?.(delta),
+            });
+            if (input.signal?.aborted === true)
+                throw new ModelHostCancelledError("The player cancelled the follow-up model request; its response was not committed.");
+        }
+        finally {
+            input.observer?.onProviderSettled?.();
+        }
         responseDiagnostics = response.diagnostics;
         if (response.diagnostics !== undefined)
             await input.failureLog?.recordExchangeIfActive(response.diagnostics);
@@ -86,10 +103,7 @@ async function runOne(input, followup, prefix) {
         if (response.reasoningContent !== undefined)
             outcome.reasoning = response.reasoningContent;
         if (response.usage !== undefined)
-            outcome.usage = {
-                inputTokens: response.usage.inputTokens,
-                outputTokens: response.usage.outputTokens,
-            };
+            outcome.usage = structuredClone(response.usage);
         // One request, one pass: tool results are recorded for the trace but never
         // fed back for another exchange.
         for (const call of response.toolCalls ?? []) {
@@ -156,6 +170,9 @@ async function runOne(input, followup, prefix) {
     }
     return outcome;
 }
+function signalWasAborted(signal) {
+    return signal?.aborted === true;
+}
 async function executeArtifactCall(input, context, call) {
     if (call.name !== "artifact_emit" && call.name !== "artifact_clear")
         return {

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

@@ -27,12 +27,13 @@ const runtimeContracts = {
 - World-write tools change only an uncommitted working copy. Their changes are not official world facts until Runtime accepts and completes the commit.`,
         operation: `# Runtime call-chain rules
 
-- The model may output player-visible text directly, call attached read or world-write tools, and then continue from tool results.
+- A response with no tool calls may contain player-visible story text and finish the current call-chain step.
+- A response that calls any tool is an intermediate tool step. Do not include player-visible story text in that response. After receiving all tool results, return the story in a later response with no tool calls.
 - Obey only the real tool definitions attached to this request. A tool that is not defined cannot be called.
 - Runtime performs state commits and saves follow-up artifacts. Tool exchanges and internal processing must never appear in player-visible content.`,
         shell: `# Runtime play boundary
 
-The model may output player-visible text directly, call attached read or world-write tools as needed, or continue after receiving tool results. Runtime executes only real tool definitions, file validation, and authority commits. This block does not define story content, point of view, style, player agency, or state semantics.`,
+A tool-free response may contain player-visible story text. A response that calls any tool is an intermediate step and must not contain player-visible story text; continue from the tool results, then narrate in a later tool-free response. Runtime executes only real tool definitions, file validation, and authority commits. This block does not define story content, point of view, style, player agency, or state semantics.`,
     },
     "zh-CN": {
         play: `# Runtime 权限边界
@@ -48,16 +49,18 @@ The model may output player-visible text directly, call attached read or world-w
 - 世界写入工具只修改尚未提交的工作副本；Runtime 接受并完成提交前，这些修改都不是正式世界事实。`,
         operation: `# Runtime 调用链规则
 
-- 模型可以直接输出玩家可见文本，或调用本次请求随附的读取和世界写入工具，再根据工具结果继续。
+- 不调用工具的响应可以输出玩家可见故事正文，并结束当前调用链步骤。
+- 只要响应调用了任何工具，它就是工具中间步；该响应不要输出玩家可见故事正文。收到全部工具结果后，再用一个不调用工具的后续响应完成叙事。
 - 只服从当前请求的真实工具定义；没有定义的工具不可调用。
 - 状态提交与后置产物保存由 Runtime 执行。工具交换与内部处理过程不得混入玩家可见内容。`,
         shell: `# Runtime 游玩边界
 
-模型可以根据当前需要直接输出玩家可见文本、调用请求随附的读取或世界写入工具，或在取得工具结果后继续。Runtime 只执行真实工具定义、文件校验和权威提交；本段不规定故事、人称、文风、玩家代理权或状态语义。`,
+不调用工具的响应可以输出玩家可见故事正文。只要响应调用了任何工具，它就是工具中间步，不得同时输出玩家可见故事正文；先根据工具结果继续，再用一个不调用工具的后续响应完成叙事。Runtime 只执行真实工具定义、文件校验和权威提交；本段不规定故事、人称、文风、玩家代理权或状态语义。`,
     },
 };
 const playCallChainToolNames = new Set([
-    "context_list",
+    "state_list",
+    "history_list",
     "context_search",
     "context_read",
     "world_patch",
@@ -123,12 +126,13 @@ export class FileNativePromptCompiler {
         const tools = runtimeToolsForNames(registeredRuntimeToolNames, this.#locale);
         const toolStrategy = this.#toolStrategyOverride ??
             defaultRuntimeToolDefinitionStrategy(effectiveInput.modelBinding.provider);
-        const provider = mapProvider(effectiveInput.modelBinding.provider, logicalMessages);
+        const cacheStrategy = effectiveInput.modelBinding.cacheStrategy ??
+            (effectiveInput.modelBinding.provider === "anthropic_messages"
+                ? "explicit_anthropic_blocks"
+                : "provider_managed");
+        const provider = mapProvider(effectiveInput.modelBinding.provider, logicalMessages, cacheStrategy);
         const budget = disabledPromptBudget(effectiveInput);
-        const stableMessages = logicalMessages.filter(({ role }) => role !== "player_input");
-        const stableText = stableMessages
-            .map(({ role, markdown }) => `${role}\n${markdown}`)
-            .join("\n");
+        const stableText = cacheStableText(logicalMessages);
         const cache = stableCacheBoundary(stableText, tools, toolStrategy);
         return {
             logicalMessages,
@@ -140,7 +144,12 @@ export class FileNativePromptCompiler {
             budget,
             cache: {
                 ...cache,
-                breakpoints: ["runtime_system", "author_instruction", "world_context"],
+                strategy: cacheStrategy,
+                breakpoints: cacheStrategy === "explicit_anthropic_blocks"
+                    ? ["runtime_system", "author_instruction", "world_context"]
+                    : cacheStrategy === "explicit_cliproxyapi_message"
+                        ? ["author_instruction", "world_context"]
+                        : [],
             },
         };
     }
@@ -164,11 +173,8 @@ export class FileNativePromptCompiler {
         const presetCompilation = this.compilePlayPreset(input, binding);
         const toolUniverse = presetCompilation.toolUniverse.filter(({ name }) => playCallChainToolNames.has(name));
         const logicalMessages = playCallChainNarrativeGuidance(presetCompilation.bootstrap.logicalMessages, binding);
-        const provider = mapProvider(input.modelBinding.provider, logicalMessages);
-        const stableText = logicalMessages
-            .filter(({ role }) => role !== "player_input")
-            .map(({ role, markdown }) => `${role}\n${markdown}`)
-            .join("\n");
+        const provider = mapProvider(input.modelBinding.provider, logicalMessages, presetCompilation.bootstrap.cache.strategy);
+        const stableText = cacheStableText(logicalMessages);
         const bootstrap = {
             ...structuredClone(presetCompilation.bootstrap),
             logicalMessages,
@@ -212,12 +218,9 @@ export class FileNativePromptCompiler {
             });
             return { role: message.role, blocks, markdown: joinBlocks(blocks) };
         });
-        const provider = mapProvider(input.modelBinding.provider, logicalMessages);
+        const provider = mapProvider(input.modelBinding.provider, logicalMessages, base.cache.strategy);
         const budget = disabledPromptBudget(input);
-        const stableMessages = logicalMessages.filter(({ role }) => role !== "player_input");
-        const stableText = stableMessages
-            .map(({ role, markdown }) => `${role}\n${markdown}`)
-            .join("\n");
+        const stableText = cacheStableText(logicalMessages);
         const cache = stableCacheBoundary(stableText, base.tools, base.toolStrategy);
         return {
             ...base,
@@ -330,7 +333,7 @@ function withoutAppendedContextGenesis(input) {
     if (input.playerInputPlacement !== "append")
         return input;
     const additionalMaterials = input.world.additionalMaterials.filter((material) => material.kind !== "history_message" ||
-        !material.message.endsWith(".message.genesis.narrator"));
+        !material.message.endsWith("message.genesis.narrator"));
     if (additionalMaterials.length === input.world.additionalMaterials.length)
         return input;
     return {
@@ -729,7 +732,7 @@ function addDocumentSelection(target, slot, required, snapshot, selected, covera
             source: modelVisibleDocumentSource(target, document, locale),
             status: "optional_missing",
             complete: false,
-            continuation: "context_list",
+            continuation: "state_list",
         });
         return;
     }
@@ -860,7 +863,7 @@ function resolveCatalog(slot, snapshot, selected, coverage, locale) {
                 ? "paged_catalog"
                 : "resolved",
         complete: matches.length > 0 && matches.length <= max && damaged.length === 0,
-        continuation: "context_list",
+        continuation: "state_list",
     });
 }
 function validCatalogDirectory(directory) {
@@ -883,7 +886,7 @@ function resolveRecentHistory(slot, history, selected, coverage, locale) {
     // in commit order. Its keys are semantic message IDs, not sortable file
     // names: lexical sorting would put `message.genesis` after every numbered
     // message and `message.9` after `message.15`.
-    const ordered = Object.entries(history).filter(([ref]) => !ref.endsWith(".message.genesis.narrator"));
+    const ordered = Object.entries(history).filter(([ref]) => !ref.endsWith("message.genesis.narrator"));
     const chosen = ordered.slice(-recent);
     if (chosen.length === 0) {
         selected.push({
@@ -918,7 +921,7 @@ function resolveRecentHistory(slot, history, selected, coverage, locale) {
                 : `${historyMessageLabel(ref, locale)} (recent ${index + 1}/${chosen.length})`,
             status: "resolved",
             complete: true,
-            continuation: "context_list",
+            continuation: "history_list",
         });
     }
 }
@@ -963,7 +966,7 @@ function resolveAdditionalMaterials(materials, snapshot, history, selected, cove
                         : `selected history commit (${matches.length} messages)`,
                 status: "resolved",
                 complete: true,
-                continuation: "context_list",
+                continuation: "history_list",
             });
         }
     }
@@ -972,11 +975,11 @@ function renderHistoryMessage(ref, text, locale) {
     return `## ${historyMessageLabel(ref, locale)}\n\n${text.trim()}`;
 }
 function historyMessageLabel(ref, locale) {
-    if (ref.endsWith(".message.genesis.narrator"))
+    if (ref.endsWith("message.genesis.narrator"))
         return locale === "zh-CN" ? "开场白" : "Opening";
-    if (/(?:\.message\.[^.]+(?:\.[0-9]+)?\.|-)(player)(?:-|$)/u.test(ref))
+    if (/(?:^|\.)message\.[^.]+(?:\.[0-9]+)?\.player$|(?:^|-)player(?:-|$)/u.test(ref))
         return locale === "zh-CN" ? "玩家原文" : "Player input";
-    if (/(?:\.message\.[^.]+(?:\.[0-9]+)?\.|-)(narrator)(?:-|$)/u.test(ref))
+    if (/(?:^|\.)message\.[^.]+(?:\.[0-9]+)?\.narrator$|(?:^|-)narrator(?:-|$)/u.test(ref))
         return locale === "zh-CN" ? "主持叙事" : "Host narrative";
     return locale === "zh-CN" ? "已提交消息" : "Committed message";
 }
@@ -1223,10 +1226,16 @@ function coverageWriteHint(entry, locale) {
             ? ` · 可继续 ${entry.continuation}`
             : ` · continue with ${entry.continuation}`;
 }
-function mapProvider(provider, messages) {
+function mapProvider(provider, messages, cacheStrategy) {
     const byRole = Object.fromEntries(messages.map((message) => [message.role, message.markdown]));
     const userBlocks = [
-        { type: "text", text: byRole.world_context },
+        {
+            type: "text",
+            text: byRole.world_context,
+            ...(cacheStrategy === "provider_managed"
+                ? {}
+                : { cache_control: { type: "ephemeral" } }),
+        },
         ...(typeof byRole.player_input === "string" &&
             byRole.player_input.length > 0
             ? [{ type: "text", text: byRole.player_input }]
@@ -1328,9 +1337,15 @@ function readMarkdown(files, path, label) {
 function joinBlocks(blocks) {
     return blocks.map(({ markdown }) => markdown.trim()).join("\n\n");
 }
-function utf8Tokens(value) {
+function utf8Bytes(value) {
     return new TextEncoder().encode(value).byteLength;
 }
+function cacheStableText(messages) {
+    return messages
+        .filter(({ role }) => role !== "player_input")
+        .map(({ role, markdown }) => `${role}\n${markdown}`)
+        .join("\n");
+}
 function stableCacheBoundary(stableText, toolUniverse, toolStrategy) {
     const stableTools = JSON.stringify({ toolUniverse, toolStrategy });
     const stablePrefix = JSON.stringify({
@@ -1338,10 +1353,10 @@ function stableCacheBoundary(stableText, toolUniverse, toolStrategy) {
         toolUniverse,
         toolStrategy,
     });
-    const stableBytes = utf8Tokens(stableText) + utf8Tokens(stableTools);
+    const stableBytes = utf8Bytes(stableText) + utf8Bytes(stableTools);
     return {
         stablePrefixFingerprint: `sha256:${sha256(stablePrefix)}`,
-        estimatedCacheableTokens: stableBytes,
+        estimatedCacheableBytes: stableBytes,
         firstDynamicByte: stableBytes,
     };
 }

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

@@ -7,7 +7,8 @@ import { defaultAppLocale, } from "../../protocol/appPreferences.js";
  * tool contract.
  */
 export const registeredRuntimeToolNames = [
-    "context_list",
+    "state_list",
+    "history_list",
     "context_search",
     "context_read",
     "world_patch",
@@ -16,7 +17,7 @@ export const registeredRuntimeToolNames = [
     "artifact_clear",
 ];
 /** Changes only when the executable Runtime tool universe or schemas change. */
-export const runtimeToolRegistryRevision = "runtime-tools-v3";
+export const runtimeToolRegistryRevision = "runtime-tools-v5";
 export function defaultRuntimeToolDefinitionStrategy(provider) {
     return provider === "openai_responses"
         ? "native_allowed_subset"
@@ -39,14 +40,41 @@ export function runtimeToolsForNames(names, locale = defaultAppLocale) {
         inputSchema: toolDefinitions[name].inputSchema,
     }));
 }
-function createToolDefinitions(locale) {
-    const descriptions = toolDescriptions[locale];
-    const object = (properties, required) => ({
+/**
+ * Return a Provider-portable root-object schema for a Runtime-owned tool.
+ *
+ * Released call-chain contexts keep their exact logical tool definitions. The
+ * legacy context_list branch therefore lives here as a wire-only compatibility
+ * projection: adapters may repair its old root union without adding it back to
+ * the tool universe exposed to new sessions.
+ */
+export function portableRuntimeToolInputSchema(name) {
+    if (name === "context_list")
+        return legacyContextListInputSchema();
+    if (!isRegisteredRuntimeToolName(name))
+        return null;
+    return structuredClone(createToolDefinitions(defaultAppLocale)[name].inputSchema);
+}
+function objectSchema(properties, required) {
+    return {
         type: "object",
         additionalProperties: false,
         required,
         properties,
-    });
+    };
+}
+function legacyContextListInputSchema() {
+    return objectSchema({
+        source: { enum: ["state", "history"] },
+        parent: { type: "string", minLength: 1 },
+        order: { enum: ["newest_first", "oldest_first"] },
+        cursor: { type: ["string", "null"] },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+    }, ["source"]);
+}
+function createToolDefinitions(locale) {
+    const descriptions = toolDescriptions[locale];
+    const object = objectSchema;
     const string = { type: "string", minLength: 1 };
     const yamlLocator = object({
         yaml: {
@@ -56,25 +84,21 @@ function createToolDefinitions(locale) {
     }, ["yaml"]);
     const markdownLocator = object({ markdown: { type: "array", items: { type: "string" }, minItems: 1 } }, ["markdown"]);
     const definitions = {
-        context_list: {
-            description: descriptions.context_list,
-            inputSchema: {
-                type: "object",
-                oneOf: [
-                    object({
-                        source: { const: "state" },
-                        parent: string,
-                        cursor: { type: ["string", "null"] },
-                        limit: { type: "integer", minimum: 1, maximum: 100 },
-                    }, ["source", "parent"]),
-                    object({
-                        source: { const: "history" },
-                        order: { enum: ["newest_first", "oldest_first"] },
-                        cursor: { type: ["string", "null"] },
-                        limit: { type: "integer", minimum: 1, maximum: 100 },
-                    }, ["source", "order"]),
-                ],
-            },
+        state_list: {
+            description: descriptions.state_list,
+            inputSchema: object({
+                parent: string,
+                cursor: { type: ["string", "null"] },
+                limit: { type: "integer", minimum: 1, maximum: 100 },
+            }, ["parent"]),
+        },
+        history_list: {
+            description: descriptions.history_list,
+            inputSchema: object({
+                order: { enum: ["newest_first", "oldest_first"] },
+                cursor: { type: ["string", "null"] },
+                limit: { type: "integer", minimum: 1, maximum: 100 },
+            }, ["order"]),
         },
         context_search: {
             description: descriptions.context_search,
@@ -172,20 +196,22 @@ function createToolDefinitions(locale) {
 }
 const toolDescriptions = {
     en: {
-        context_list: 'List handles known to Runtime. State-directory requests have the fixed shape {source:"state", parent:"@dir-/"}; when descending, parent must be an @dir-* handle returned by a prior result. History requests have the fixed shape {source:"history", order:"newest_first"}. The two shapes are mutually exclusive: never send parent and order together.',
+        state_list: "List document and state directory handles known to Runtime. parent must be @dir-/ for the state root or an @dir-* handle returned by an earlier state_list result; descend only through returned directory handles. A cursor is valid only for the same state snapshot, parent, and limit. Pass returned document handles to context_read. This tool never lists committed history.",
+        history_list: "List handles for committed history messages known to Runtime. order must be newest_first or oldest_first. A cursor is valid only for the same committed-history snapshot, order, and limit. Pass returned @history-message-* handles to context_read. This tool never lists the mutable state directory.",
         context_search: "Search literal source text in state or history. Zero matches means only that the supplied text had no literal match; it does not prove that a world fact does not exist. Player-visible narrative must not recount the search process. within accepts only an @document or @dir-* handle returned by Runtime.",
         context_read: "Precisely read an @document, @node, or @history-message-* handle previously returned by Runtime. Read headings, page markers, metadata boundaries, and body boundaries in a whole-document result are not source text. Update metadata only as one set_metadata operation and 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. Never pass file paths, natural-language names, or an invented world/... value.",
         world_patch: 'Update a document that has been read precisely. target must be an @short-ref. When title, summary, or aliases are stale, update all three with {op:"set_metadata",title,summary,aliases}, copying unchanged values from the read result. A YAML edit uses locator:{yaml:["field","child"]}, for example {op:"replace",locator:{yaml:["status"]},value:"new value"}. 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. Do not use path, JSON Pointer, set, or a file name.',
-        world_create: 'Create a document inside a state directory returned by Runtime. parent must be an @dir-* handle returned by context_list, such as @dir-/characters; use @dir-/ for the root. 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_create: 'Create a document inside a state directory returned by Runtime. parent must be an @dir-* handle returned by state_list, such as @dir-/characters; use @dir-/ for the root. 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.',
         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.",
         artifact_clear: "Clear the projection of an artifact that this follow-up declared in advance and explicitly allows to be cleared. The call cannot choose a channel, key, or any other output contract.",
     },
     "zh-CN": {
-        context_list: '列出 Runtime 已知句柄。状态目录形状固定为 {source:"state", parent:"@dir-/"}，继续下级时 parent 只能使用结果返回的 @dir-*；历史形状固定为 {source:"history", order:"newest_first"}。两种形状互斥，不要同时传 parent 和 order。',
+        state_list: "列出 Runtime 已知的文档与状态目录句柄。状态根目录的 parent 使用 @dir-/；继续下级时只能使用先前 state_list 结果返回的 @dir-*。cursor 只对同一状态快照、parent 和 limit 有效。返回的文档句柄交给 context_read；本工具不列出已提交历史。",
+        history_list: "列出 Runtime 已知的已提交历史消息句柄。order 必须是 newest_first 或 oldest_first；cursor 只对同一历史快照、order 和 limit 有效。返回的 @history-message-* 交给 context_read；本工具不列出可变状态目录。",
         context_search: "在 state 或 history 的原文字面中搜索。0 命中只表示给定文本没有字面命中，不证明世界事实不存在；玩家可见叙事不得复述搜索过程。within 只能使用 Runtime 已返回的 @文档或 @dir-* 句柄。",
         context_read: "精确读取 Runtime 先前返回的 @文档、@节点或 @history-message-* 句柄。整文档结果中的读取标题、分页线、元信息边界和正文边界不属于源文；元信息只能用 set_metadata 整组更新，中间的可写正文用 locator 更新。YAML 正文不含 $document 技术头，Markdown 正文从文档 # 一级标题开始。不要传文件路径、自然语言名称或自行拼造的 world/...。",
         world_patch: '更新已精确读取的文档。target 必须使用 @短引用；文档 title、summary 或 aliases 过时时用 {op:"set_metadata",title,summary,aliases} 整组更新，未改项照抄读取结果。YAML edit 使用 locator:{yaml:["字段","子字段"]}，例如 {op:"replace",locator:{yaml:["情况"]},value:"新值"}。YAML value 需要引用整份文档时只能写 {$ref:"@短引用"}，短引用必须来自 Runtime 的 list、read 或 create 结果；不得自行编造文档 id。没有可用句柄时，根据语义使用普通文本，或先 world_create 后使用其返回的 @短引用。向已存在的 sequence 末尾加一项必须使用 append 并把 locator 指向该 sequence；add 只创建尚不存在的 map key 或 list index。Markdown locator 不包含文档 # 一级标题：{markdown:["职责"]} 精确指向 ## 职责，replace_section.markdown 必须从同级同名标题开始。修改 # 标题下、第一个 ## 前的文字用 replace_preamble（只传该段文字）；替换整个 Markdown 正文用 replace_body，且 markdown 必须保留原 # 一级标题。成功结果只报告文档是否发生变化，不回显正文；只有后续决策依赖 Runtime 序列化后的精确正文时才重新 context_read。不要使用 path、JSON Pointer、set 或文件名。',
-        world_create: '在 Runtime 返回的状态目录中创建文档。parent 必须是 context_list 返回的 @dir-*，例如 @dir-/characters；根目录使用 @dir-/。refHint 是小写 ASCII 短引用，不要传 world/ 路径。YAML body 需要引用整份文档时只能写 {$ref:"@短引用"}，且短引用必须来自 Runtime 的 list、read 或 create 结果；不得自行编造文档 id。',
+        world_create: '在 Runtime 返回的状态目录中创建文档。parent 必须是 state_list 返回的 @dir-*，例如 @dir-/characters；根目录使用 @dir-/。refHint 是小写 ASCII 短引用，不要传 world/ 路径。YAML body 需要引用整份文档时只能写 {$ref:"@短引用"}，且短引用必须来自 Runtime 的 list、read 或 create 结果；不得自行编造文档 id。',
         artifact_emit: "提交本次后置请求预先声明的产物。只能传 output name 与 payload；频道、key、内容类型、renderer、保存策略和权威含义由 Runtime contract 固定。",
         artifact_clear: "清除本次后置请求预先声明且允许 clear 的产物投影；不能选择频道、key 或其他输出契约。",
     },

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

@@ -1,4 +1,5 @@
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
+import { aggregateModelUsage, emptyAggregatedModelUsage, } from "../../protocol/modelUsage.js";
 import { defaultSettingImprovementPromptForLocale } from "../../shared/default-setting-improvement-prompt.js";
 import { inspectContentPackageCurrentTree, } from "../content/FileNativeContentTree.js";
 import { WorldDocumentStore, } from "../world/WorldDocumentStore.js";
@@ -408,8 +409,7 @@ export class DocumentCandidateSettingImprovement {
     }
     #recordExchange(usage) {
         this.#progress.round += 1;
-        this.#progress.usage.inputTokens += usage?.inputTokens ?? 0;
-        this.#progress.usage.outputTokens += usage?.outputTokens ?? 0;
+        this.#progress.usage = aggregateModelUsage(this.#progress.usage, usage);
         this.#progress.streaming = null;
         this.#progress.updatedAt = Date.now();
     }
@@ -577,6 +577,7 @@ export class DocumentCandidateSettingImprovement {
                     role: "tool",
                     toolCallId: call.id,
                     content: result.markdown,
+                    ...(result.ok ? {} : { isError: true }),
                 });
                 this.#recordAction(call, result.ok);
                 if (!result.ok) {
@@ -786,6 +787,7 @@ export class DocumentCandidateSettingImprovement {
                                 content: failureIndex === null || failureIndex === index
                                     ? failed.markdown
                                     : renderSettingBatchRejected(revisionCalls, failureIndex, this.#locale),
+                                isError: true,
                             });
                         await this.#recordResponseFailure(response, {
                             kind: "tool_execution",
@@ -817,6 +819,7 @@ export class DocumentCandidateSettingImprovement {
                         content: rejection === null
                             ? localized(this.#locale, "# Candidate final state accepted\n\nRuntime accepted the current isolated candidate for user review. The content package is unchanged and will be replaced only if the user applies the entire candidate.", "# 候选终态已接受\n\nRuntime 已接受当前隔离候选供用户审阅；内容包尚未改变，只有用户整批应用后才会替换当前树。")
                             : localized(this.#locale, `# Runtime tool rejected\n\n${rejection}`, `# Runtime 工具拒绝\n\n${rejection}`),
+                        ...(rejection === null ? {} : { isError: true }),
                     });
                     if (rejection === null)
                         finished = true;
@@ -839,6 +842,7 @@ export class DocumentCandidateSettingImprovement {
                         role: "tool",
                         toolCallId: call.id,
                         content: check.markdown,
+                        ...(check.passed ? {} : { isError: true }),
                     });
                     lastFailedCheck = check.passed ? null : check.markdown;
                     previewedSnapshotId = check.passed ? candidate.id : null;
@@ -881,6 +885,7 @@ export class DocumentCandidateSettingImprovement {
                     role: "tool",
                     toolCallId: call.id,
                     content: result.markdown,
+                    ...(result.ok ? {} : { isError: true }),
                 });
                 this.#recordAction(call, result.ok);
                 if (!result.ok) {
@@ -1023,7 +1028,7 @@ function assistantMessage(response) {
             : { reasoningContent: response.reasoningContent }),
         ...(response.providerState === undefined
             ? {}
-            : { providerState: response.providerState }),
+            : { providerState: structuredClone(response.providerState) }),
         toolCalls: structuredClone(response.toolCalls),
     };
 }
@@ -1613,7 +1618,7 @@ function idleSettingProgress() {
         toolCalls: 0,
         repairs: 0,
         failedChecks: 0,
-        usage: { inputTokens: 0, outputTokens: 0 },
+        usage: emptyAggregatedModelUsage(),
         writing: null,
         recentActions: [],
         lastCheck: null,