narraeon 0.1.1-oidc.1 → 0.2.0

package/README.md

@@ -59,6 +59,9 @@ Then open <http://127.0.0.1:4317>. The named volume preserves worlds,
 configuration, credentials, logs, and recovery state across container
 recreation. Keep the host-side address as `127.0.0.1`; publishing the port on
 all interfaces would unnecessarily expose a local, single-user Runtime.
+Narraeon does not currently provide built-in web authentication or access
+control. Run it only on loopback or a trusted private network; public exposure
+is unsupported until a unified security model is designed.
 Stable releases move `latest`, prereleases move `next`, and every release also
 has an exact version tag.
 
@@ -156,7 +159,7 @@ The container image maps all three storage roots under
 `/var/lib/narraeon`, which is why the Docker example persists that single
 directory as a volume.
 
-The browser talks only to the same-machine Runtime. Local-first does not mean that remote model inference is offline: prompts, selected world material, tool exchanges, and generated text are sent to the provider you configure. API keys are stored in the local configuration and are not returned to the browser after saving.
+By default, the browser talks only to the same-machine Runtime. Local-first does not mean that remote model inference is offline: prompts, selected world material, tool exchanges, and generated text are sent to the provider you configure. API keys are stored in the local configuration and are not returned to the browser after saving.
 
 When a provider, response-format, Runtime-tool, or candidate-check error occurs, Narraeon creates a JSONL incident under `NARRAEON_LOG_ROOT/ai-failures`. It preserves the raw provider exchange and later recovery attempts, including reasoning or thinking actually returned by the provider. It does not invent hidden reasoning or record API keys and request headers. The files can still contain private prompts, world content, tool arguments, and provider-returned reasoning, so treat the log directory as sensitive.
 

package/README.zh-CN.md

@@ -55,7 +55,7 @@ docker run --detach --name narraeon \
   ghcr.io/narraeon/narraeon:latest
 ```
 
-然后打开 <http://127.0.0.1:4317>。命名卷会在重建容器后继续保留世界、配置、凭据、日志和恢复数据。宿主机一侧应继续绑定 `127.0.0.1`；绑定所有网卡会把本地单用户 Runtime 不必要地暴露出去。稳定版会移动 `latest`，预发布版会移动 `next`，每次发布还会保留精确版本标签。
+然后打开 <http://127.0.0.1:4317>。命名卷会在重建容器后继续保留世界、配置、凭据、日志和恢复数据。宿主机一侧应继续绑定 `127.0.0.1`；绑定所有网卡会把本地单用户 Runtime 不必要地暴露出去。Narraeon 当前不内置 Web 认证或访问控制，只应运行在回环地址或受信任私网中；在统一安全模型设计完成前，不支持暴露到公网。稳定版会移动 `latest`，预发布版会移动 `next`，每次发布还会保留精确版本标签。
 
 ## 从源码运行
 
@@ -149,7 +149,7 @@ Narraeon 默认使用当前操作系统的标准用户应用目录。如果要
 
 容器镜像把前三类存储目录统一放在 `/var/lib/narraeon` 下，因此 Docker 示例只需要持久化这一个目录。
 
-浏览器只与同机 Runtime 通信。“本地优先”不等于远程模型推理也离线：提示词、选中的世界材料、工具交换和生成文本会发送到你配置的 Provider。API Key 保存在本地配置中，保存后不会再返回给浏览器。
+默认情况下，浏览器只与同机 Runtime 通信。“本地优先”不等于远程模型推理也离线：提示词、选中的世界材料、工具交换和生成文本会发送到你配置的 Provider。API Key 保存在本地配置中，保存后不会再返回给浏览器。
 
 发生 Provider、响应格式、Runtime 工具或候选检查错误时，Narraeon 会在 `NARRAEON_LOG_ROOT/ai-failures` 下创建 JSONL 事故记录。它会保存原始 Provider 交换和后续恢复尝试，包括 Provider 真实返回的 reasoning／thinking。它不会伪造隐藏思考，也不会记录 API Key 和请求 header。不过日志仍可能包含私密提示词、世界内容、工具参数和 Provider 返回的思考，因此应当把该目录视为敏感数据。
 

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

@@ -107,6 +107,14 @@ const requiredFields = {
         playerText: "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 +213,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")
@@ -265,6 +290,10 @@ const requestTypes = new Set([
     "play.chain.start",
     "play.chain.append",
     "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/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);
@@ -400,6 +429,12 @@ export class V1Runtime {
                 }));
             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 +472,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);