narraeon 0.7.1 → 0.7.4

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

@@ -8,6 +8,8 @@ import { renderPromptDeltaMessage, } from "../prompt/FileNativePromptCompiler.js
 import { aggregateAnthropicModelStream, aggregateChatModelStream, aggregateResponsesModelStream, } from "./ModelHostStream.js";
 import { defaultRuntimeToolDefinitionStrategy, portableRuntimeToolInputSchema, } from "../prompt/FileNativeToolRegistry.js";
 import { AiExchangeCapture, errorDescription, } from "./AiFailureLog.js";
+/** Anthropic allows four cache_control breakpoints per request. */
+const explicitCacheBreakpointLimit = 4;
 const providerContinuationCodecVersion = 1;
 function resolveConnection(connection) {
     const resolved = structuredClone({
@@ -17,6 +19,7 @@ function resolveConnection(connection) {
         reasoningSummary: connection.reasoningSummary ?? "provider_default",
         thinkingMode: connection.thinkingMode ?? "provider_default",
         thinkingBudgetTokens: connection.thinkingBudgetTokens ?? null,
+        cacheSuffixBreakpoint: connection.cacheSuffixBreakpoint ?? true,
     });
     const issue = modelReasoningPolicyIssue({
         provider: resolved.provider,
@@ -95,6 +98,8 @@ export class FileNativeModelHost {
             throw new ModelHostBindingMismatchError("The request protocol does not match the selected model host");
         return new _a({
             ...request.modelConfig,
+            // A frozen request without this choice predates the transcript breakpoint.
+            cacheSuffixBreakpoint: request.modelConfig.cacheSuffixBreakpoint === true,
             baseUrl: this.#connection.baseUrl,
             apiKey: this.#connection.apiKey,
         }, this.#fetch, this.#failureLog);
@@ -458,19 +463,16 @@ async function trace(kind, value) {
         // Explicit acceptance diagnostics must never change provider semantics.
     }
 }
-function items(request) {
-    return request.appended;
-}
 function chatRequestBody(connection, request) {
     const tools = providerToolDefinitions(request);
     const allowedTools = providerAllowedTools(request);
     const hasPolicy = hasFrozenToolPolicy(request);
-    return {
+    return checkedCacheBreakpoints({
         model: connection.modelId,
         ...chatReasoningRequest(connection),
         messages: [
             ...chatBootstrapMessages(connection, request),
-            ...chatAppend(request),
+            ...chatAppend(connection, request),
         ],
         ...(connection.dialect === "cliproxyapi"
             ? { prompt_cache_key: promptCacheKey(connection, request) }
@@ -495,17 +497,17 @@ function chatRequestBody(connection, request) {
         max_tokens: request.maxOutputTokens,
         stream: true,
         stream_options: { include_usage: true },
-    };
+    });
 }
 function anthropicRequestBody(connection, request) {
     const tools = providerToolDefinitions(request);
-    return {
+    return checkedCacheBreakpoints({
         model: connection.modelId,
         ...anthropicReasoningRequest(connection),
         system: request.bootstrap.provider.system,
         messages: [
             ...anthropicBootstrapMessages(request),
-            ...anthropicAppend(request),
+            ...anthropicAppend(connection, request),
         ],
         ...(tools.length === 0
             ? {}
@@ -522,14 +524,14 @@ function anthropicRequestBody(connection, request) {
             : {}),
         max_tokens: request.maxOutputTokens,
         stream: true,
-    };
+    });
 }
 function responsesRequestInput(connection, request) {
     return {
         connection,
         input: [
             ...responsesBootstrapMessages(connection, request),
-            ...responsesAppend(request),
+            ...responsesAppend(connection, request),
         ],
         tools: providerToolDefinitions(request).map((tool) => ({
             name: tool.name,
@@ -555,7 +557,7 @@ function responsesRequestBody(input) {
                 tools: allowedTools.map((name) => ({ type: "function", name })),
             }
             : "auto";
-    return {
+    return checkedCacheBreakpoints({
         model: input.connection.modelId,
         ...responsesReasoningRequest(resolveConnection(input.connection)),
         input: input.input,
@@ -582,7 +584,7 @@ function responsesRequestBody(input) {
         store: false,
         include: ["reasoning.encrypted_content"],
         stream: true,
-    };
+    });
 }
 /**
  * A frozen policy is present when the caller supplies the logical operation's
@@ -758,8 +760,88 @@ function promptCacheKey(connection, request) {
         .update(`${connection.provider}\0${connection.dialect}\0${connection.modelId}\0${scope}`)
         .digest("hex");
 }
-function chatAppend(request) {
-    return items(request).flatMap((item) => {
+/**
+ * Explicit-breakpoint encodings mark the last transcript item before the
+ * request-level suffix, so the next dispatch reads back the transcript it sent.
+ * A request without a suffix keeps its request end as the transcript's entry,
+ * so it is encoded exactly as before.
+ */
+function appendWithSuffixBreakpoint(connection, request, encode, markLast) {
+    const { transcript, suffix } = splitRequestSuffix(request.appended);
+    const encoded = encode(transcript);
+    const breakpoint = suffix.length > 0 &&
+        encoded.length > 0 &&
+        connection.cacheSuffixBreakpoint &&
+        modelCacheStrategy(connection) !== "provider_managed";
+    return [...(breakpoint ? markLast(encoded) : encoded), ...encode(suffix)];
+}
+/** Request-level suffix items are recompiled for every dispatch and never stored. */
+function splitRequestSuffix(appended) {
+    let end = appended.length;
+    while (end > 0 && isRequestSuffix(appended[end - 1]))
+        end -= 1;
+    return { transcript: appended.slice(0, end), suffix: appended.slice(end) };
+}
+function isRequestSuffix(item) {
+    return item.kind === "runtime_notice" && item.notice === "turn_guide";
+}
+/** Message-level cache_control, the form the CLIProxyAPI prefix breakpoints use. */
+function markLastMessage(messages) {
+    const last = messages.at(-1);
+    if (!isRecord(last))
+        throw new Error("The transcript tail cannot carry a cache breakpoint.");
+    return [
+        ...messages.slice(0, -1),
+        { ...last, cache_control: { type: "ephemeral" } },
+    ];
+}
+/** Thinking blocks reject cache_control, so the breakpoint lands on the last block that accepts it. */
+function markLastAnthropicBlock(messages) {
+    const last = messages.at(-1);
+    if (!isRecord(last))
+        throw new Error("The transcript tail cannot carry a cache breakpoint.");
+    const content = typeof last.content === "string"
+        ? [{ type: "text", text: last.content }]
+        : Array.isArray(last.content)
+            ? last.content
+            : [];
+    const index = content.findLastIndex((block) => isRecord(block) &&
+        block.type !== "thinking" &&
+        block.type !== "redacted_thinking");
+    if (index < 0)
+        throw new Error("The Anthropic transcript tail has no block that can carry a cache breakpoint.");
+    return [
+        ...messages.slice(0, -1),
+        {
+            ...last,
+            content: content.map((block, position) => position === index
+                ? {
+                    ...block,
+                    cache_control: { type: "ephemeral" },
+                }
+                : block),
+        },
+    ];
+}
+/** Refuses a request over the breakpoint limit instead of silently dropping one. */
+function checkedCacheBreakpoints(body) {
+    const count = countCacheBreakpoints(body);
+    if (count > explicitCacheBreakpointLimit)
+        throw new Error(`The request has ${count} cache breakpoints; the Anthropic limit is ${explicitCacheBreakpointLimit}.`);
+    return body;
+}
+function countCacheBreakpoints(value) {
+    if (Array.isArray(value))
+        return value.reduce((total, item) => total + countCacheBreakpoints(item), 0);
+    if (!isRecord(value))
+        return 0;
+    return Object.entries(value).reduce((total, [key, item]) => total + (key === "cache_control" ? 1 : 0) + countCacheBreakpoints(item), 0);
+}
+function chatAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, chatItems, markLastMessage);
+}
+function chatItems(items) {
+    return items.flatMap((item) => {
         if (item.kind === "player" ||
             item.kind === "user" ||
             item.kind === "runtime_notice")
@@ -782,7 +864,10 @@ function chatAppend(request) {
         throw continuationError("Chat Completions");
     });
 }
-function anthropicAppend(request) {
+function anthropicAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, anthropicItems, markLastAnthropicBlock);
+}
+function anthropicItems(items) {
     const messages = [];
     let toolResults = [];
     const flushToolResults = () => {
@@ -791,7 +876,7 @@ function anthropicAppend(request) {
         messages.push({ role: "user", content: toolResults });
         toolResults = [];
     };
-    for (const item of items(request)) {
+    for (const item of items) {
         if (item.kind === "tool") {
             toolResults.push({
                 type: "tool_result",
@@ -825,8 +910,11 @@ function anthropicAppend(request) {
     flushToolResults();
     return messages;
 }
-function responsesAppend(request) {
-    return items(request).flatMap((item) => {
+function responsesAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, responsesItems, markLastMessage);
+}
+function responsesItems(items) {
+    return items.flatMap((item) => {
         if (item.kind === "player" ||
             item.kind === "user" ||
             item.kind === "runtime_notice")

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

@@ -1,15 +1,18 @@
 import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+/** Written last by the released-record cleanup (ADR-0034); its absence means "not yet run". */
+const LAYOUT_MARKER = "play-advance-layout.json";
 /**
  * The single in-progress play advance of a call chain, if any.
  *
  * It exists only between `begin` and `markSettled`. A marker that survives a
  * restart means the advance was interrupted; the runtime marks the chain
- * interrupted and the player retries. Legacy records from earlier layouts are
- * ignored, so they never block a world from opening.
+ * interrupted and the player retries. Released records from earlier layouts
+ * never block a world from opening, and the storage upgrade removes them
+ * (see `migrateLayout`).
  */
 export class FileNativePlayAdvanceStore {
     #worldsRoot;
@@ -52,6 +55,50 @@ export class FileNativePlayAdvanceStore {
             force: true,
         });
     }
+    /**
+     * Whether the world's advance records are free of the pre-ADR-0044 layout
+     * (ADR-0034). Reads never write: a world with no released records is current
+     * without a marker.
+     */
+    async layoutCurrent(worldId) {
+        assertIdentity(worldId, "World ID");
+        if ((await readOptionalJson(this.#layoutMarkerPath(worldId))) !==
+            null)
+            return true;
+        return (await this.#releasedChainRoots(worldId)).length === 0;
+    }
+    /**
+     * Remove the released `records/` and `current.json` of every chain. Each
+     * chain's `in-progress.json` stays as it is, and a chain left empty is removed.
+     * The marker is written last, so an interrupted run simply runs again.
+     */
+    async migrateLayout(worldId) {
+        assertIdentity(worldId, "World ID");
+        if (await this.layoutCurrent(worldId))
+            return;
+        for (const chainRoot of await this.#releasedChainRoots(worldId)) {
+            await rm(join(chainRoot, "records"), { recursive: true, force: true });
+            await rm(join(chainRoot, "current.json"), { force: true });
+            if ((await readdir(chainRoot)).length === 0)
+                await rm(chainRoot, { recursive: true, force: true });
+        }
+        await publishJson(this.#layoutMarkerPath(worldId), layoutMarker());
+    }
+    /** Chain directories that still hold a released record or pointer. */
+    async #releasedChainRoots(worldId) {
+        const advancesRoot = join(this.#worldsRoot, worldId, "runtime", "play-advances");
+        const roots = [];
+        for (const name of await readDirectoryNames(advancesRoot)) {
+            const chainRoot = join(advancesRoot, name);
+            if ((await pathExists(join(chainRoot, "records"))) ||
+                (await pathExists(join(chainRoot, "current.json"))))
+                roots.push(chainRoot);
+        }
+        return roots;
+    }
+    #layoutMarkerPath(worldId) {
+        return join(this.#worldsRoot, worldId, "runtime", LAYOUT_MARKER);
+    }
     #markerPath(worldId, chainId) {
         return join(this.#worldsRoot, worldId, "runtime", "play-advances", digest(chainId), "in-progress.json");
     }
@@ -120,6 +167,26 @@ async function readOptionalJson(path) {
         throw error;
     }
 }
+async function readDirectoryNames(directory) {
+    try {
+        return await readdir(directory);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function pathExists(path) {
+    return stat(path).then(() => true, (error) => {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    });
+}
+function layoutMarker() {
+    return { schemaVersion: 1, kind: "play_advance_layout" };
+}
 /** Atomic publish: write a temporary file, then rename over the target. */
 async function publishJson(path, value) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });