narraeon 0.1.0 → 0.1.1-oidc.1

package/README.md

@@ -17,7 +17,7 @@ The model handles the meaning of the story: it portrays characters, responds to
 
 ## Requirements
 
-- Node.js **24.12.0 or newer**
+- Either Docker Engine / Docker Desktop, or Node.js **24.12.0 or newer**
 - A modern browser
 - For AI play or setting improvement, a model endpoint and API credential compatible with one of the supported adapters:
   - OpenAI Responses API
@@ -46,6 +46,22 @@ npx narraeon --help
 
 The server listens only on `127.0.0.1`. If the chosen port already hosts a compatible Narraeon instance, the CLI reuses it. If another program owns the port, startup fails instead of attaching to an unknown service.
 
+Alternatively, run the release image from GitHub Container Registry:
+
+```bash
+docker run --detach --name narraeon \
+  --publish 127.0.0.1:4317:4317 \
+  --volume narraeon-data:/var/lib/narraeon \
+  ghcr.io/narraeon/narraeon:latest
+```
+
+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.
+Stable releases move `latest`, prereleases move `next`, and every release also
+has an exact version tag.
+
 ## Run from source
 
 ```bash
@@ -136,6 +152,10 @@ Narraeon uses the operating system's standard per-user application directories.
 | `NARRAEON_LOG_ROOT`    | Runtime logs and AI failure diagnostics                    |
 | `NARRAEON_PORT`        | Local web port, default `4317`                             |
 
+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.
 
 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

@@ -17,7 +17,7 @@ Narraeon 是一个用于开放式 AI 角色扮演的本地优先工作区。你
 
 ## 运行要求
 
-- Node.js **24.12.0 或更高版本**
+- Docker Engine／Docker Desktop，或 Node.js **24.12.0 或更高版本**，二选一
 - 现代浏览器
 - 如果要进行 AI 游玩或设定完善，还需要与以下任一适配器兼容的模型端点和 API 凭据：
   - OpenAI Responses API
@@ -46,6 +46,17 @@ npx narraeon --help
 
 服务只监听 `127.0.0.1`。如果选定端口已经运行兼容的 Narraeon，CLI 会直接复用；如果端口被其他程序占用，启动会明确失败，不会连接未知服务。
 
+也可以直接运行 GitHub Container Registry 上的发布镜像：
+
+```bash
+docker run --detach --name narraeon \
+  --publish 127.0.0.1:4317:4317 \
+  --volume narraeon-data:/var/lib/narraeon \
+  ghcr.io/narraeon/narraeon:latest
+```
+
+然后打开 <http://127.0.0.1:4317>。命名卷会在重建容器后继续保留世界、配置、凭据、日志和恢复数据。宿主机一侧应继续绑定 `127.0.0.1`；绑定所有网卡会把本地单用户 Runtime 不必要地暴露出去。稳定版会移动 `latest`，预发布版会移动 `next`，每次发布还会保留精确版本标签。
+
 ## 从源码运行
 
 ```bash
@@ -136,6 +147,8 @@ Narraeon 默认使用当前操作系统的标准用户应用目录。如果要
 | `NARRAEON_LOG_ROOT`    | Runtime 日志和 AI 失败诊断         |
 | `NARRAEON_PORT`        | 本地 Web 端口，默认为 `4317`       |
 
+容器镜像把前三类存储目录统一放在 `/var/lib/narraeon` 下，因此 Docker 示例只需要持久化这一个目录。
+
 浏览器只与同机 Runtime 通信。“本地优先”不等于远程模型推理也离线：提示词、选中的世界材料、工具交换和生成文本会发送到你配置的 Provider。API Key 保存在本地配置中，保存后不会再返回给浏览器。
 
 发生 Provider、响应格式、Runtime 工具或候选检查错误时，Narraeon 会在 `NARRAEON_LOG_ROOT/ai-failures` 下创建 JSONL 事故记录。它会保存原始 Provider 交换和后续恢复尝试，包括 Provider 真实返回的 reasoning／thinking。它不会伪造隐藏思考，也不会记录 API Key 和请求 header。不过日志仍可能包含私密提示词、世界内容、工具参数和 Provider 返回的思考，因此应当把该目录视为敏感数据。

package/dist/node/cli/NarraeonCli.js

@@ -2,7 +2,7 @@ import { createConnection } from "node:net";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { resolveAppPaths } from "../runtime/config/appPaths.js";
-import { parseWebPort, startWebServer, } from "../server/startWebServer.js";
+import { parseWebHost, parseWebPort, startWebServer, } from "../server/startWebServer.js";
 export class NarraeonCliUsageError extends Error {
 }
 export async function runNarraeonCli(input) {
@@ -29,6 +29,7 @@ export async function runNarraeonCli(input) {
         server = await start({
             paths: resolveAppPaths(input.environment),
             staticRoot: input.staticRoot,
+            host: command.host,
             port: command.port,
         });
     }
@@ -93,7 +94,9 @@ function parseCliCommand(args, environment) {
     if (parsed.positionals.length !== 1 || parsed.positionals[0] !== "web")
         throw new NarraeonCliUsageError(`Unknown command: ${parsed.positionals.join(" ") || "(empty)"}`);
     let port;
+    let host;
     try {
+        host = parseWebHost(environment.NARRAEON_HOST);
         port = parseWebPort(parsed.values.port ?? environment.NARRAEON_PORT, parsed.values.port === undefined ? "NARRAEON_PORT" : "--port");
     }
     catch (error) {
@@ -101,6 +104,7 @@ function parseCliCommand(args, environment) {
     }
     return {
         kind: "web",
+        host,
         port,
         openBrowser: parsed.values.open !== false,
     };

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

@@ -51,7 +51,10 @@ export async function aggregateChatModelStream(body, onDelta) {
                 reasoningContent += delta.reasoning_content;
                 onDelta?.({ kind: "reasoning", text: delta.reasoning_content });
             }
-            if (delta.tool_calls === undefined)
+            // Gateways in front of a Chat Completions Model often write `null` where
+            // the protocol omits a field, both for the whole tool-call list and for
+            // individual fragment fields. A null carries no continuation content.
+            if (delta.tool_calls === undefined || delta.tool_calls === null)
                 continue;
             if (!Array.isArray(delta.tool_calls))
                 throw new Error("Chat SSE tool_calls delta is invalid");
@@ -69,26 +72,26 @@ export async function aggregateChatModelStream(body, onDelta) {
                     type: "function",
                     arguments: "",
                 };
-                if (fragmentValue.id !== undefined) {
+                if (isPresent(fragmentValue.id)) {
                     if (typeof fragmentValue.id !== "string")
                         throw new Error("Chat SSE tool-call id is invalid");
                     current.id += fragmentValue.id;
                 }
-                if (fragmentValue.type !== undefined) {
+                if (isPresent(fragmentValue.type)) {
                     if (fragmentValue.type !== "function")
                         throw new Error("Chat SSE tool-call type is invalid");
                     current.type = fragmentValue.type;
                 }
-                if (fragmentValue.function !== undefined) {
+                if (isPresent(fragmentValue.function)) {
                     if (!isRecord(fragmentValue.function))
                         throw new Error("Chat SSE tool-call function is invalid");
                     const function_ = fragmentValue.function;
-                    if (function_.name !== undefined) {
+                    if (isPresent(function_.name)) {
                         if (typeof function_.name !== "string")
                             throw new Error("Chat SSE tool-call name is invalid");
                         current.name += function_.name;
                     }
-                    if (function_.arguments !== undefined) {
+                    if (isPresent(function_.arguments)) {
                         if (typeof function_.arguments !== "string")
                             throw new Error("Chat SSE tool-call arguments are invalid");
                         current.arguments += function_.arguments;
@@ -362,6 +365,9 @@ function mergeUsage(target, value) {
 function stringOrUndefined(value) {
     return typeof value === "string" ? value : undefined;
 }
+function isPresent(value) {
+    return value !== undefined && value !== null;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/node/server/main.js

@@ -1,11 +1,13 @@
 import { resolve } from "node:path";
 import { resolveAppPaths } from "../runtime/config/appPaths.js";
-import { parseWebPort, startWebServer } from "./startWebServer.js";
+import { parseWebHost, parseWebPort, startWebServer, } from "./startWebServer.js";
+const host = parseWebHost(process.env.NARRAEON_HOST);
 const port = parseWebPort(process.env.NARRAEON_PORT);
 const paths = resolveAppPaths(process.env);
 const server = await startWebServer({
     paths,
     staticRoot: resolve("dist/web"),
+    host,
     port,
 });
 installGracefulShutdown(server);

package/dist/node/server/startWebServer.js

@@ -1,6 +1,8 @@
 import { createRuntime } from "./createRuntime.js";
 import { createServer } from "./createServer.js";
 export const defaultWebPort = 4317;
+export const defaultWebHost = "127.0.0.1";
+export const containerWebHost = "0.0.0.0";
 export async function startWebServer(input) {
     const runtime = await createRuntime(input.paths);
     const server = await createServer({
@@ -10,7 +12,7 @@ export async function startWebServer(input) {
         ...(input.logger === undefined ? {} : { logger: input.logger }),
     });
     try {
-        await server.listen({ host: "127.0.0.1", port: input.port });
+        await server.listen({ host: input.host, port: input.port });
         return server;
     }
     catch (error) {
@@ -18,6 +20,13 @@ export async function startWebServer(input) {
         throw error;
     }
 }
+export function parseWebHost(value, source = "NARRAEON_HOST") {
+    if (value === undefined)
+        return defaultWebHost;
+    if (value === defaultWebHost || value === containerWebHost)
+        return value;
+    throw new Error(`${source} must be ${defaultWebHost} or ${containerWebHost}: ${value}`);
+}
 export function parseWebPort(value, source = "NARRAEON_PORT") {
     if (value === undefined)
         return defaultWebPort;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narraeon",
-  "version": "0.1.0",
+  "version": "0.1.1-oidc.1",
   "description": "A local-first workspace for living worlds.",
   "license": "Apache-2.0",
   "type": "module",
@@ -44,6 +44,7 @@
     "prepack": "npm run build",
     "start": "node src/server/main.ts",
     "test": "npm run test:unit && npm run test:release && npm run test:e2e",
+    "test:container": "docker build --tag narraeon:release-smoke . && node scripts/smoke-container.mjs --image narraeon:release-smoke",
     "test:e2e": "npm run build && playwright test",
     "test:package": "node scripts/smoke-package.mjs",
     "test:release": "node --test scripts/check-release.test.mjs",