narraeon 0.1.1 → 0.3.0

package/dist/node/protocol/modelConnections.js

@@ -1,3 +1,52 @@
+/** CLIProxyAPI gives these model-name suffixes priority over body effort. */
+export function hasCLIProxyThinkingSuffix(modelId) {
+    return /\((?:-1|none|auto|minimal|low|medium|high|xhigh|max|\d+)\)$/iu.test(modelId);
+}
+/** One validation authority shared by storage and the wire adapter boundary. */
+export function modelReasoningPolicyIssue(input) {
+    const thinking = input.thinking ?? "provider_default";
+    const thinkingBudgetTokens = input.thinkingBudgetTokens ?? null;
+    const thinkingControlledByCLIProxySuffix = input.provider === "anthropic_messages" &&
+        input.dialect === "cliproxyapi" &&
+        hasCLIProxyThinkingSuffix(input.modelId);
+    if (input.provider === "anthropic_messages" &&
+        (input.effort === "none" || input.effort === "minimal"))
+        return "Anthropic Messages effort supports low, medium, high, xhigh, and max; use Thinking disabled instead of effort none";
+    if (input.provider !== "anthropic_messages" &&
+        thinking !== "provider_default")
+        return "Only Anthropic Messages defines a separate thinking mode; OpenAI-shaped protocols control reasoning through effort";
+    if (input.provider !== "anthropic_messages" && thinkingBudgetTokens !== null)
+        return "Only Anthropic Messages manual thinking accepts a thinking token budget";
+    if (thinking === "enabled") {
+        if (thinkingBudgetTokens === null ||
+            !Number.isSafeInteger(thinkingBudgetTokens) ||
+            thinkingBudgetTokens < 1_024)
+            return "Anthropic manual thinking requires an integer budget of at least 1024 tokens";
+        if (input.maxOutputTokens !== undefined &&
+            thinkingBudgetTokens >= input.maxOutputTokens)
+            return "Anthropic thinking budget must be lower than maximum output tokens";
+    }
+    else if (thinkingBudgetTokens !== null) {
+        return "A thinking token budget is valid only when Anthropic Thinking is set to manual enabled";
+    }
+    if (input.provider === "anthropic_messages" &&
+        (thinking === "provider_default" || thinking === "disabled") &&
+        input.summary !== "provider_default" &&
+        !(thinking === "provider_default" && thinkingControlledByCLIProxySuffix))
+        return "Anthropic returned thinking can be configured only when Thinking is adaptive or manual enabled, or when a CLIProxyAPI model suffix controls Thinking";
+    if (input.provider !== "openai_responses" &&
+        (input.summary === "concise" || input.summary === "detailed"))
+        return "Concise and detailed reasoning summaries are defined only by OpenAI Responses";
+    if (input.provider === "chat_completions" &&
+        input.dialect === "standard" &&
+        input.summary !== "provider_default")
+        return "Standard Chat Completions has no reasoning-summary parameter; use provider default or select the CLIProxyAPI dialect";
+    if (input.dialect === "cliproxyapi" &&
+        (input.effort !== "provider_default" || thinking !== "provider_default") &&
+        hasCLIProxyThinkingSuffix(input.modelId))
+        return "CLIProxyAPI model thinking suffixes override request effort and thinking; use either the model suffix with provider defaults or explicit request fields, not both";
+    return null;
+}
 export const modelProviderPresets = [
     {
         id: "custom",

package/dist/node/protocol/modelUsage.js

@@ -0,0 +1,39 @@
+const modelUsageKeys = [
+    "inputTokens",
+    "uncachedInputTokens",
+    "cacheReadTokens",
+    "cacheWriteTokens",
+    "reasoningTokens",
+    "outputTokens",
+    "totalTokens",
+];
+/** A zero baseline used only before any Provider exchange has completed. */
+export function emptyAggregatedModelUsage() {
+    return usageWithValue(0, "derived_provider_fields");
+}
+/**
+ * Sum complete Provider usage records without treating an unreported field as
+ * zero. Once any exchange lacks a field, that aggregate remains unavailable.
+ */
+export function aggregateModelUsage(current, next) {
+    const result = {};
+    for (const key of modelUsageKeys) {
+        const right = next?.[key] ?? null;
+        result[key] =
+            current[key] === null || right === null ? null : current[key] + right;
+    }
+    return {
+        ...result,
+        provenance: Object.fromEntries(modelUsageKeys.map((key) => [
+            key,
+            result[key] === null ? "unavailable" : "derived_provider_fields",
+        ])),
+    };
+}
+function usageWithValue(value, source) {
+    const values = Object.fromEntries(modelUsageKeys.map((key) => [key, value]));
+    return {
+        ...values,
+        provenance: Object.fromEntries(modelUsageKeys.map((key) => [key, source])),
+    };
+}

package/dist/node/protocol/v1.js

@@ -106,7 +106,20 @@ const requiredFields = {
         exchangeId: "string",
         playerText: "string",
     },
+    "play.chain.cancel": {
+        worldId: "string",
+        chainId: "string",
+        exchangeId: "string",
+    },
     "play.chain.inspect": { worldId: "string" },
+    "play.timeline.page": { worldId: "string", limit: "number" },
+    "play.timeline.detail": {
+        worldId: "string",
+        chainId: "string",
+        eventId: "number",
+    },
+    "world.surface.read": { worldId: "string", surface: "string" },
+    "world.play-decorations.read": { worldId: "string" },
     "correction.begin": { worldId: "string", operationId: "string" },
     "correction.read": { candidateId: "string", document: "string" },
     "correction.patch": {
@@ -205,6 +218,23 @@ function validateRequestFields(request) {
         request.operationId !== undefined &&
         (typeof request.operationId !== "string" || request.operationId === ""))
         throw new V1ProtocolError("invalid_request", "artifacts.debug.operationId is invalid");
+    if (request.type === "play.timeline.page") {
+        if (!Number.isSafeInteger(request.limit) ||
+            Number(request.limit) < 1 ||
+            Number(request.limit) > 100 ||
+            (request.cursor !== undefined &&
+                (typeof request.cursor !== "string" || request.cursor === "")))
+            throw new V1ProtocolError("invalid_request", "play.timeline.page pagination is invalid");
+    }
+    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 (request.type === "world.surface.read" &&
+        request.surface !== "state" &&
+        request.surface !== "control" &&
+        request.surface !== "history" &&
+        request.surface !== "runtime")
+        throw new V1ProtocolError("invalid_request", "world.surface.read.surface is invalid");
     if (request.type !== "setting-improvement.start")
         return;
     if (request.mode !== "plan_first" && request.mode !== "direct_candidate")
@@ -264,7 +294,12 @@ const requestTypes = new Set([
     "play.chain.revise-player",
     "play.chain.start",
     "play.chain.append",
+    "play.chain.cancel",
     "play.chain.inspect",
+    "play.timeline.page",
+    "play.timeline.detail",
+    "world.surface.read",
+    "world.play-decorations.read",
     "correction.begin",
     "correction.read",
     "correction.patch",

package/dist/node/runtime/FileNativePhysicalClone.js

@@ -0,0 +1,86 @@
+import { constants } from "node:fs";
+import { copyFile, link, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+const hardlinkFallbackCodes = new Set([
+    "EXDEV",
+    "EPERM",
+    "EACCES",
+    "EMLINK",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+    "ENOSYS",
+]);
+const reflinkFallbackCodes = new Set([
+    "EXDEV",
+    "EPERM",
+    "EACCES",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+    "EINVAL",
+    "ENOSYS",
+]);
+/**
+ * Retains one file without aliasing mutable bytes. Immutable files prefer a
+ * hard link; every other case walks reflink -> exclusive byte copy.
+ */
+export async function cloneFilePhysically(input) {
+    await mkdir(dirname(input.target), { recursive: true, mode: 0o700 });
+    const strategy = process.env.NARRAEON_INTERNAL_TEST_CLONE_STRATEGY;
+    if (input.immutable && strategy !== "reflink" && strategy !== "copy") {
+        try {
+            await link(input.source, input.target);
+            return;
+        }
+        catch (error) {
+            if (await acceptExistingTarget(error, input))
+                return;
+            if (!isFallbackError(error, hardlinkFallbackCodes))
+                throw error;
+        }
+    }
+    if (strategy !== "copy") {
+        try {
+            await copyFileAsReflink(input.source, input.target);
+            return;
+        }
+        catch (error) {
+            if (await acceptExistingTarget(error, input))
+                return;
+            if (!isFallbackError(error, reflinkFallbackCodes))
+                throw error;
+        }
+    }
+    try {
+        await copyFile(input.source, input.target, constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (await acceptExistingTarget(error, input))
+            return;
+        throw error;
+    }
+}
+async function copyFileAsReflink(source, target) {
+    const injectedErrorCode = process.env.NARRAEON_INTERNAL_TEST_REFLINK_ERROR_CODE;
+    if (injectedErrorCode !== undefined) {
+        const error = new Error(`${injectedErrorCode}: injected copy-on-write clone failure`);
+        error.code = injectedErrorCode;
+        error.path = source;
+        error.syscall = "copyfile";
+        throw error;
+    }
+    await copyFile(source, target, constants.COPYFILE_FICLONE_FORCE);
+}
+async function acceptExistingTarget(error, input) {
+    if (!isNodeError(error) ||
+        error.code !== "EEXIST" ||
+        input.onTargetExists === undefined)
+        return false;
+    await input.onTargetExists(input.source, input.target);
+    return true;
+}
+function isFallbackError(error, acceptedCodes) {
+    return isNodeError(error) && acceptedCodes.has(error.code ?? "");
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/node/runtime/V1Runtime.js

@@ -239,7 +239,8 @@ export class V1Runtime {
                         : this.#playPresets.bindRevision(request.playPresetId, request.playPresetRevision),
                 ]);
                 const hostBinding = presetHostBinding(playPreset);
-                return this.#compiler.preview({
+                const modelHost = new FileNativeModelHost(connection);
+                const preview = this.#compiler.preview({
                     endpoint: {
                         id: `content:${request.packageId}`,
                         commit: "current",
@@ -251,8 +252,32 @@ export class V1Runtime {
                     }), `content:${request.packageId}.message.genesis.narrator`, "content-preview"),
                     playerInputPlacement: "append",
                     playerInput: request.playerInput,
-                    modelBinding: new FileNativeModelHost(connection).binding(),
+                    modelBinding: modelHost.binding(),
                 }, playPreset);
+                const tools = structuredClone(preview.compilation.toolUniverse ?? preview.compilation.tools);
+                return {
+                    ...preview,
+                    wireRequest: modelHost.previewRequest({
+                        bootstrap: structuredClone(preview.compilation),
+                        tools: structuredClone(tools),
+                        toolUniverse: structuredClone(tools),
+                        allowedTools: tools.map(({ name }) => name),
+                        toolStrategy: preview.compilation.toolStrategy,
+                        appended: preview.initialAppend === undefined
+                            ? []
+                            : [
+                                {
+                                    kind: "player",
+                                    text: preview.initialAppend.logical.text,
+                                },
+                            ],
+                        requestId: "play_call_chain",
+                        operationId: "prompt-preview",
+                        requestAttempt: 1,
+                        exchange: 1,
+                        maxOutputTokens: modelHost.binding().maxOutputTokens,
+                    }),
+                };
             }
             case "world.create": {
                 const [package_, connection, preset] = await Promise.all([
@@ -280,38 +305,42 @@ export class V1Runtime {
                     return this.#worlds.deleteWorld(request.worldId);
                 });
             case "world.read": {
-                await this.#reconcileArtifacts(request.worldId);
                 const head = await this.#worlds.currentHead(request.worldId);
                 const playerViews = await this.#worlds.renderPlayerViewsAtHead(request.worldId, head);
-                const [state, control, history, runtime, endpoint, authority, artifacts, extensions, playerViewPanels,] = await Promise.all([
-                    this.#worlds.readSurface(request.worldId, "state"),
-                    this.#worlds.readSurface(request.worldId, "control"),
-                    this.#worlds.readSurface(request.worldId, "history"),
-                    this.#worlds.readSurface(request.worldId, "runtime"),
-                    this.#worlds.recoverEndpoint(request.worldId, head),
-                    this.#worlds.readAuthorityHistory(request.worldId),
-                    this.#frontendProjection(request.worldId),
-                    this.#artifacts.readExtensionSummaries(request.worldId),
+                const [playerViewPanels, playTimeline] = await Promise.all([
                     this.#frontendPlayerViewPanels(request.worldId, head, playerViews),
+                    this.#worlds.playTimeline.readPage(request.worldId, 40),
                 ]);
                 return {
                     worldId: request.worldId,
                     head,
-                    state,
-                    control,
-                    history,
-                    runtime,
+                    state: [],
+                    control: [],
+                    history: [],
+                    runtime: { head, surfaces: "lazy" },
                     playerViews,
-                    committedMessages: endpoint.history.map((message) => ({
-                        ...message,
-                        head: authority.commits.find((commit) => commit.historyAppend.some(({ messageId }) => messageId === message.messageId))?.head ?? "genesis",
-                    })),
-                    artifacts,
-                    extensions,
+                    committedMessages: [],
+                    artifacts: [],
+                    extensions: [],
                     playerViewPanels,
-                    playCallChain: await this.#playCallChains.inspectWorld(request.worldId),
+                    artifactDebug: [],
+                    playCallChain: null,
+                    playTimeline,
                 };
             }
+            case "world.surface.read":
+                return request.surface === "runtime"
+                    ? this.#worlds.readSurface(request.worldId, "runtime")
+                    : this.#worlds.readSurface(request.worldId, request.surface);
+            case "world.play-decorations.read": {
+                const head = await this.#reconcileArtifacts(request.worldId);
+                const [artifacts, extensions, artifactDebug] = await Promise.all([
+                    this.#frontendProjection(request.worldId),
+                    this.#artifacts.readExtensionSummaries(request.worldId),
+                    this.#frontendDebug(request.worldId),
+                ]);
+                return { head, artifacts, extensions, artifactDebug };
+            }
             case "artifacts.read":
                 await this.#reconcileArtifacts(request.worldId);
                 return this.#frontendProjection(request.worldId, request.channel);
@@ -345,17 +374,12 @@ export class V1Runtime {
             }
             case "world.derive": {
                 const preset = await this.#playPresets.bindCurrent();
-                const result = await this.#worlds.deriveWorld({
+                const result = await this.#playCallChains.deriveWorld({
                     operationId: request.operationId,
                     sourceWorldId: request.sourceWorldId,
                     sourceHead: request.sourceHead,
                     hostPresetId: preset.id,
                 });
-                await this.#playCallChains.forkToDerivedWorld({
-                    sourceWorldId: request.sourceWorldId,
-                    sourceHead: request.sourceHead,
-                    targetWorldId: result.world.worldId,
-                });
                 await this.#reconcileResultArtifacts(result);
                 return result;
             }
@@ -398,8 +422,20 @@ export class V1Runtime {
                         ? {}
                         : { observer: playCallChainObserver }),
                 }));
+            case "play.chain.cancel":
+                return playCall(() => this.#playCallChains.cancel({
+                    worldId: request.worldId,
+                    chainId: request.chainId,
+                    exchangeId: request.exchangeId,
+                }));
             case "play.chain.inspect":
                 return this.#playCallChains.inspectWorld(request.worldId);
+            case "play.timeline.page":
+                await this.#worlds.ensureCurrentStorage(request.worldId);
+                return this.#worlds.playTimeline.readPage(request.worldId, request.limit, request.cursor);
+            case "play.timeline.detail":
+                await this.#worlds.ensureCurrentStorage(request.worldId);
+                return this.#worlds.playTimeline.readDetail(request.worldId, request.chainId, request.eventId);
             case "correction.begin":
                 return this.#corrections.begin({
                     worldId: request.worldId,
@@ -437,6 +473,7 @@ export class V1Runtime {
             this.#worlds.currentHeadOperationId(worldId),
         ]);
         await this.#artifacts.reconcileHead(worldId, head, currentOperationId ?? undefined);
+        return head;
     }
     async #frontendProjection(worldId, channel) {
         const artifacts = await this.#artifacts.readActiveProjection(worldId, channel);