narraeon 0.1.0

package/dist/node/server/createServer.js

@@ -0,0 +1,218 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { PassThrough } from "node:stream";
+import fastifyStatic from "@fastify/static";
+import Fastify, { LogController, } from "fastify";
+import { maxPortableContentArchiveBase64Characters } from "../protocol/contentTree.js";
+import { parseV1Envelope, V1ProtocolError, v1Protocol, } from "../protocol/v1.js";
+const runtimeRequestBodyLimit = maxPortableContentArchiveBase64Characters + 64 * 1024;
+const playCallChainStreamContentType = "application/x-ndjson";
+class RuntimeLogController extends LogController {
+    incomingRequest(request, reply, metadata) {
+        // The request body is not parsed yet. Runtime API requests are logged by
+        // the route pre-handler once their request type is known.
+        if (isRuntimeApiRequest(request))
+            return;
+        super.incomingRequest(request, reply, metadata);
+    }
+    requestCompleted(error, request, reply, metadata) {
+        if (isPollingRequest(request) && error == null && reply.statusCode < 400)
+            return;
+        super.requestCompleted(error, request, reply, metadata);
+    }
+}
+function isPollingRequest(request) {
+    const body = request.body;
+    if (!isRuntimeApiRequest(request) || !isRecord(body))
+        return false;
+    const runtimeRequest = body.request;
+    return (isRecord(runtimeRequest) &&
+        (runtimeRequest.type === "setting-improvement.progress" ||
+            runtimeRequest.type === "play.chain.inspect"));
+}
+function isRuntimeApiRequest(request) {
+    return request.url === "/api/runtime/v1";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export async function createServer(input) {
+    if (!Number.isInteger(input.port) || input.port < 1 || input.port > 65_535)
+        throw new Error(`Invalid local web port: ${input.port}`);
+    const server = Fastify({
+        logController: new RuntimeLogController(),
+        logger: input.logger === false
+            ? false
+            : {
+                level: "info",
+                redact: {
+                    paths: [
+                        "req.headers.authorization",
+                        "req.headers.x-api-key",
+                        "req.body",
+                    ],
+                    censor: "[REDACTED]",
+                },
+                ...(input.logStream === undefined
+                    ? {}
+                    : { stream: input.logStream }),
+            },
+    });
+    const suffix = input.port === 80 ? "" : `:${input.port}`;
+    const origins = new Set([
+        `http://127.0.0.1${suffix}`,
+        `http://localhost${suffix}`,
+    ]);
+    const html = await readFile(join(input.staticRoot, "index.html"), "utf8");
+    // Origin is what actually stops a hostile page from driving this server: a
+    // cross-site request carries its own origin, and a JSON POST always triggers
+    // a preflight, so the header is always there to check. A per-boot token on
+    // top bought nothing against that threat and made every restart invalidate
+    // the tab the user already had open.
+    const sameOrigin = (request, reply, done) => {
+        if (request.headers.origin === undefined ||
+            !origins.has(request.headers.origin))
+            void forbidden(reply);
+        else
+            done();
+    };
+    const logRuntimeRequest = (request, _reply, done) => {
+        if (!isPollingRequest(request))
+            request.log.info({ req: request }, "incoming request");
+        done();
+    };
+    server.addHook("onSend", (request, reply, payload, done) => {
+        void reply
+            .header("Cache-Control", request.url.startsWith("/api/") ? "no-store" : "no-cache")
+            .header("Content-Security-Policy", 
+        // App renderer code is explicitly frozen local trusted code and runs
+        // inside its own sandboxed iframe. The inline allowance is required
+        // for srcDoc templates; the host still exposes no Runtime capability
+        // to that code and the product does not treat it as a hostile sandbox.
+        "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; base-uri 'none'; frame-ancestors 'none'; object-src 'none'")
+            .header("X-Content-Type-Options", "nosniff")
+            .header("X-Frame-Options", "DENY");
+        done(null, payload);
+    });
+    server.get("/health", () => ({
+        status: "ok",
+        protocol: "narraeon.runtime/v1",
+    }));
+    server.post("/api/runtime/v1", {
+        bodyLimit: runtimeRequestBodyLimit,
+        onRequest: [sameOrigin],
+        preHandler: [logRuntimeRequest],
+    }, async (request, reply) => {
+        let runtimeRequestType;
+        try {
+            const envelope = parseV1Envelope(request.body);
+            runtimeRequestType = envelope.request.type;
+            if (acceptsPlayCallChainStream(request) &&
+                (envelope.request.type === "play.chain.start" ||
+                    envelope.request.type === "play.chain.append"))
+                return sendPlayCallChainStream(input.runtime, envelope.request, request, reply);
+            const response = await input.runtime.handle(envelope.request);
+            if ((runtimeRequestType === "play.chain.start" ||
+                runtimeRequestType === "play.chain.append") &&
+                isRecord(response.result) &&
+                response.result.status === "interrupted" &&
+                typeof response.result.lastFailure === "string")
+                request.log.error({
+                    runtimeRequestType,
+                    playCallFailure: response.result.lastFailure,
+                }, "play call interrupted");
+            return reply.send(response);
+        }
+        catch (error) {
+            if (error instanceof V1ProtocolError) {
+                return reply.status(400).send({
+                    protocol: "narraeon.runtime/v1",
+                    error: {
+                        code: error.code,
+                        message: error.message,
+                    },
+                });
+            }
+            throw error;
+        }
+    });
+    await server.register(fastifyStatic, {
+        root: input.staticRoot,
+        index: false,
+    });
+    const index = (_request, reply) => reply.type("text/html; charset=utf-8").send(html);
+    server.get("/", index);
+    server.get("/index.html", index);
+    return server;
+}
+function acceptsPlayCallChainStream(request) {
+    const accept = request.headers.accept;
+    return (typeof accept === "string" &&
+        accept
+            .split(",")
+            .some((value) => value.trim().startsWith(playCallChainStreamContentType)));
+}
+function sendPlayCallChainStream(runtime, runtimeRequest, request, reply) {
+    const stream = new PassThrough();
+    const send = (frame) => {
+        if (stream.destroyed || stream.writableEnded)
+            return;
+        stream.write(`${JSON.stringify({ protocol: v1Protocol, frame })}\n`);
+    };
+    const observer = {
+        onSnapshot(value) {
+            send({ kind: "snapshot", value, final: false });
+        },
+        onAssistantDelta(delta) {
+            send({
+                kind: "assistant_delta",
+                eventId: delta.eventId,
+                deltaKind: delta.kind,
+                text: delta.text,
+                updatedAt: delta.updatedAt,
+            });
+        },
+    };
+    void runtime
+        .handle(runtimeRequest, observer)
+        .then((response) => {
+        if (!isPlayCallChainView(response.result))
+            throw new Error("The Runtime stream did not return a call-chain snapshot");
+        send({ kind: "snapshot", value: response.result, final: true });
+        if (response.result.status === "interrupted" &&
+            response.result.lastFailure !== null)
+            request.log.error({
+                runtimeRequestType: runtimeRequest.type,
+                playCallFailure: response.result.lastFailure,
+            }, "play call interrupted");
+    })
+        .catch((error) => {
+        const message = error instanceof Error ? error.message : "Runtime streaming failed";
+        request.log.error({ err: error, runtimeRequestType: runtimeRequest.type }, "play call stream failed");
+        send({ kind: "error", message });
+    })
+        .finally(() => {
+        if (!stream.destroyed && !stream.writableEnded)
+            stream.end();
+    });
+    return reply.type(playCallChainStreamContentType).send(stream);
+}
+function isPlayCallChainView(value) {
+    return (isRecord(value) &&
+        typeof value.chainId === "string" &&
+        typeof value.worldId === "string" &&
+        Array.isArray(value.previousContexts) &&
+        Array.isArray(value.events) &&
+        (value.status === "ready" ||
+            value.status === "running" ||
+            value.status === "interrupted"));
+}
+function forbidden(reply) {
+    return reply.status(403).send({
+        protocol: "narraeon.runtime/v1",
+        error: {
+            code: "forbidden_request",
+            message: "Local web request is not authorized",
+        },
+    });
+}

package/dist/node/server/main.js

@@ -0,0 +1,25 @@
+import { resolve } from "node:path";
+import { resolveAppPaths } from "../runtime/config/appPaths.js";
+import { parseWebPort, startWebServer } from "./startWebServer.js";
+const port = parseWebPort(process.env.NARRAEON_PORT);
+const paths = resolveAppPaths(process.env);
+const server = await startWebServer({
+    paths,
+    staticRoot: resolve("dist/web"),
+    port,
+});
+installGracefulShutdown(server);
+function installGracefulShutdown(server) {
+    let closing = false;
+    const close = () => {
+        if (closing)
+            return;
+        closing = true;
+        void server.close().catch((error) => {
+            console.error(error);
+            process.exitCode = 1;
+        });
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}

package/dist/node/server/startWebServer.js

@@ -0,0 +1,28 @@
+import { createRuntime } from "./createRuntime.js";
+import { createServer } from "./createServer.js";
+export const defaultWebPort = 4317;
+export async function startWebServer(input) {
+    const runtime = await createRuntime(input.paths);
+    const server = await createServer({
+        runtime,
+        staticRoot: input.staticRoot,
+        port: input.port,
+        ...(input.logger === undefined ? {} : { logger: input.logger }),
+    });
+    try {
+        await server.listen({ host: "127.0.0.1", port: input.port });
+        return server;
+    }
+    catch (error) {
+        await server.close().catch(() => undefined);
+        throw error;
+    }
+}
+export function parseWebPort(value, source = "NARRAEON_PORT") {
+    if (value === undefined)
+        return defaultWebPort;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535)
+        throw new Error(`${source} is not a valid port: ${value}`);
+    return parsed;
+}

package/dist/node/shared/default-play-prompts.js

@@ -0,0 +1,85 @@
+/**
+ * Canonical author-owned narrative prompt shared by the default and
+ * first-party presets. Portable presets still receive ordinary editable file
+ * contents; this module only prevents the shipped starting points from
+ * drifting apart. The general adjudication and state-maintenance criteria live
+ * in the host preset, which every mode loads.
+ */
+export const defaultNarrationPromptZhCN = `# 玩家可见叙事规则
+
+当你决定输出玩家可见故事正文时，写成互动式小说，不写成裁决报告、工具日志或主持流程说明。哪些事已经发生，以当前调用链里已经作出的判断、已经写入的世界变化和玩家明确实施的行动为准；补充不改变结果的表演细节是允许的。
+
+这一段是互动式小说的正文，不是过程报告。读者是玩家本人，他要的是读下去的体验，不是一份“这次交互发生了什么”的交代。
+
+## 怎么写
+
+从玩家这次输入写起，把它扩写成完整的场景——他具体怎么做的、什么语气神态、当时的姿态和距离——再接着写它引出的后续。不要用“你说要去找他”这类回指句开头，直接把那个动作演出来。
+
+让环境、光线、声音、他人的小动作和身体反应参与进来。情绪和关系尽量侧写，通过动作走形、话说到一半停住、视线躲闪来呈现，而不是直接判定“他很紧张”。玩家没有互动的 NPC 也在做自己的事，让场面里同时发生的事不必都与玩家有关。
+
+当前调用链写进世界文档、而玩家角色感知得到的变化，这一段必须演出来：不是复述“他的态度变好了”，是让他做出或说出能看出这一点的那句话、那个动作。写进了文档却没进叙事，玩家就读不到它，对他等于没有发生。已经确定的结果同样不能改：谁在哪、拿着什么、答应了什么，都要保持一致。在这个骨架上尽管写具体——他拿起什么、说了哪句话、手上停在哪个动作——这些细节会随本段叙事一起提交，后续模型请求读得到它们。
+
+以玩家原文、已加载的世界材料和当前调用链已经确定的结果为准。结果既包括写进文档的持续变化，也包括只在当前场面成立的直接后果；两者都不得被叙事掩盖或改写。玩家只表达愿望、意图或尝试时，不要擅自把愿望写成已经达成。
+
+## 怎么收尾
+
+**最后一句写某个人做的一件具体的事，或说的一句具体的话。** 他问了什么，原话写出来；他把东西递过来，写他怎么递的；他站起身往门口走，写他走了。这句话本身要有内容，读者读的是这件事，不是读“该我了”。
+
+轮到玩家，是他从这件事里自己得出的结论，不需要你告诉他。所以结尾不写场面的状态，只写事件：
+
+- 不写“没人接话”“屋里安静下来”“空气凝住了”——沉默不是事件，用它收尾等于什么都没发生。
+- 不写“两道视线落回你身上”“他等着你的下文”“所有人都在等你开口”——这是把“轮到你了”翻译成了场面语言，和直接问“你打算怎么做”是同一件事，只是穿了小说的皮。
+- 不写“你打算怎么做”“接下来你会怎么办”“你可以选择……”，也不要在结尾把局势总结一遍或列出他有哪些选项。
+
+如果写到最后发现场上确实没人有动作可做，那说明这一段收早了：让某个人先做点什么——开口、起身、动手、走近——再停。
+
+## 边界
+
+玩家可见文本只写小说正文，可以分多个自然段；不要标题、清单、解释、工具过程或幕后说明。停笔位置约束的是故事推进到哪里，不是可以写多厚——在这个范围内把场面、反应和氛围写足。
+
+篇幅由这一刻的分量决定，不是每段都写成同一个长度。过场收快；玩家真正在意的那一刻停下来，把那几秒拆开写。
+
+不要替玩家作出**本该由他决定**的事——改变目标立场、答应或拒绝、交出或收下、动手或收手。为执行他已表达的意图而演出的连带动作、应答和具体措辞不算替玩家决定；玩家的尝试失败、NPC 作出自主反应、当前没有任何文档变化，也都不妨碍正常叙事。
+`;
+export const defaultNarrationPromptEn = `# Player-visible narrative rules
+
+Whenever you produce player-visible story text, write it as an interactive novel, not as an adjudication report, tool log, or explanation of the hosting process. What has happened is determined by decisions already made in the current call chain, world changes already written, and actions the player explicitly carried out. You may add performance details that do not alter those outcomes.
+
+This is the body of an interactive novel, not a process report. The reader is the player, who wants an experience worth continuing, not a recap of “what happened in this interaction.”
+
+## How to write
+
+Begin with the player's current input. Expand it into a complete scene—how the action is performed, the player's tone and expression, posture, and distance—then continue into the consequences it produces. Do not open with a backward reference such as “You said you would go find them.” Put the action directly on the page.
+
+Bring in the environment, light, sound, other characters' small movements, and physical reactions. Imply emotion and relationships through a movement going wrong, a sentence breaking off, or a gaze turning away instead of declaring “they are nervous.” NPCs the player is not engaging with still have their own business; simultaneous events do not all need to revolve around the player.
+
+Any change written to a world document in the current call chain that the player character can perceive must be dramatized here. Do not say “their attitude improved”; show the line or gesture that makes the change visible. If a change exists in a document but not in the narrative, the player cannot read it and it effectively did not happen for them. Do not alter settled results either: keep consistent who is where, what they hold, and what they promised. Within that structure, be specific—what someone picks up, the exact words they say, where a hand pauses. These details are committed with the narrative and remain available to later model requests.
+
+Follow the player's original text, the loaded world material, and outcomes already settled in the current call chain. Outcomes include durable changes written to documents and direct consequences that hold only in the current scene. The narrative may neither hide nor rewrite either kind. When the player expresses only a wish, intention, or attempt, do not silently turn it into an accomplished result.
+
+## How to end
+
+**Make the final sentence a specific action someone takes or a specific line they say.** If someone asks a question, write the actual question. If they hand something over, show how. If they stand and walk toward the door, write that movement. The sentence must have content; the reader should be reading the event, not a disguised message that “it is your turn.”
+
+The player can infer that it is their turn. Do not state the condition of the scene at the end; end on an event:
+
+- Do not end with “no one answers,” “the room falls quiet,” or “the air freezes.” Silence is not an event, and ending on it means nothing happened.
+- Do not end with “two pairs of eyes return to you,” “they wait for you to continue,” or “everyone waits for you to speak.” Those phrases merely translate “your turn” into scenic language and are equivalent to asking “What do you do?”, dressed in prose.
+- Do not write “What do you do?”, “What happens next?”, or “You could choose…”. Do not summarize the situation or list the player's options at the end.
+
+If you reach the end and nobody in the scene has an action to take, the passage stopped too early. Let someone do something—speak, stand, act, or approach—then stop.
+
+## Boundaries
+
+Player-visible text contains only the novel's prose and may use several natural paragraphs. Do not include headings, lists, explanations, tool activity, or backstage notes. The stopping point limits how far the story advances, not how fully the moment can be rendered; within that boundary, give the scene, reactions, and atmosphere enough space.
+
+Let the weight of the moment determine length instead of forcing every passage into the same size. Move quickly through transitions; when the player truly cares about a moment, slow down and separate those few seconds.
+
+Do not make a decision that **belongs to the player**—changing goals or allegiance, accepting or refusing, giving or taking something, striking or holding back. Supporting movements, replies, and exact wording that carry out an intention the player already expressed do not take agency away. A failed attempt, an NPC's autonomous reaction, or a response with no document changes can all still produce normal narrative.
+`;
+export const defaultNarrationPrompt = defaultNarrationPromptEn;
+export function defaultNarrationPromptForLocale(locale) {
+    return locale === "zh-CN"
+        ? defaultNarrationPromptZhCN
+        : defaultNarrationPromptEn;
+}