narraeon 0.6.0 → 0.6.2

package/dist/node/runtime/world/WorldTurnLedger.js

@@ -0,0 +1,353 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
+export class WorldTurnLedgerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorldTurnLedgerError";
+        this.code = code;
+    }
+}
+const headFile = join("runtime", "head.json");
+const turnsDirectory = join("runtime", "turns");
+function turnFileName(sequence) {
+    return join(turnsDirectory, `${String(sequence).padStart(8, "0")}.json`);
+}
+function assertSafePath(relativePath) {
+    const normalized = normalize(relativePath);
+    if (isAbsolute(relativePath) ||
+        normalized.startsWith(`..${sep}`) ||
+        normalized === ".." ||
+        normalized.length === 0 ||
+        normalized === headFile ||
+        normalized === turnsDirectory ||
+        normalized.startsWith(turnsDirectory + sep)) {
+        throw new WorldTurnLedgerError("invalid_path", `世界文件路径不合法：${relativePath}`);
+    }
+}
+async function writeFileAtomic(absolute, content) {
+    await mkdir(dirname(absolute), { recursive: true });
+    const temporary = `${absolute}.${randomUUID()}.tmp`;
+    await writeFile(temporary, content, "utf8");
+    await rename(temporary, absolute);
+}
+async function readTextOrNull(absolute) {
+    try {
+        return await readFile(absolute, "utf8");
+    }
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        throw error;
+    }
+}
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export async function initializeLedger(root) {
+    forgetLedger(root);
+    await writeFileAtomic(join(root, headFile), `${JSON.stringify({ sequence: 0 }, null, 2)}\n`);
+}
+export async function readHead(root) {
+    const text = await readTextOrNull(join(root, headFile));
+    if (text === null) {
+        throw new WorldTurnLedgerError("no_head", "世界缺少轮账本端点");
+    }
+    const parsed = JSON.parse(text);
+    if (typeof parsed.sequence !== "number" ||
+        !Number.isInteger(parsed.sequence) ||
+        parsed.sequence < 0) {
+        throw new WorldTurnLedgerError("corrupt", "世界轮账本端点格式不正确");
+    }
+    return parsed.sequence;
+}
+async function publishHead(root, sequence) {
+    await writeFileAtomic(join(root, headFile), `${JSON.stringify({ sequence }, null, 2)}\n`);
+}
+async function readAllRecords(root) {
+    let names;
+    try {
+        names = await readdir(join(root, turnsDirectory));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const text = await readFile(join(root, turnsDirectory, name), "utf8");
+        records.push(JSON.parse(text));
+    }
+    return records.sort((left, right) => left.sequence - right.sequence);
+}
+// 被某个 rewind 丢弃的轮是 (restores, rewind) 之间的位置；它们可能仍在磁盘上，
+// 直到清理完成，但读取时一律忽略。
+function viewOf(head, records) {
+    const byPosition = new Map();
+    for (const record of records) {
+        if (record.sequence <= head)
+            byPosition.set(record.sequence, record);
+    }
+    const discarded = new Set();
+    for (const record of byPosition.values()) {
+        if (record.restoresSequence === undefined)
+            continue;
+        for (let position = record.restoresSequence + 1; position < record.sequence; position += 1) {
+            discarded.add(position);
+        }
+    }
+    return { head, byPosition, discarded };
+}
+// 进程内视图缓存，按端点失效。一个数据目录只被一个进程操作（ADR-0044），
+// 所以 head 相同即记录相同：任何改变可见记录的写入都会先推进 head。
+// 只有 beginTurn 与 recoverIncomplete 会在 head 之上写入或删除记录，它们不影响视图
+// （视图只包含序号不大于 head 的记录，且 recoverIncomplete 本身会在结束时失效缓存）。
+const viewCache = new Map();
+async function loadView(root) {
+    const head = await readHead(root);
+    const cached = viewCache.get(resolve(root));
+    if (cached?.head === head)
+        return cached;
+    const view = viewOf(head, await readAllRecords(root));
+    viewCache.set(resolve(root), view);
+    return view;
+}
+// 世界目录被删除、归档导入或分叉发布到已存在路径之前调用：下一次读取从磁盘重建视图。
+export function forgetLedger(root) {
+    viewCache.delete(resolve(root));
+}
+// 把一个端点解析到它的逻辑位置：rewind 位置等价于它所恢复的位置。
+function resolvePosition(view, sequence) {
+    if (!Number.isInteger(sequence) || sequence < 0 || sequence > view.head) {
+        throw new WorldTurnLedgerError("unreachable", `端点 ${sequence} 不在当前账本范围内`);
+    }
+    let position = sequence;
+    for (;;) {
+        if (position === 0)
+            return 0;
+        if (view.discarded.has(position)) {
+            throw new WorldTurnLedgerError("unreachable", `端点 ${sequence} 已被回退丢弃`);
+        }
+        const record = view.byPosition.get(position);
+        if (!record) {
+            throw new WorldTurnLedgerError("missing_record", `缺少第 ${position} 轮记录`);
+        }
+        if (record.mode !== "rewind")
+            return position;
+        if (record.restoresSequence === undefined) {
+            throw new WorldTurnLedgerError("corrupt", `第 ${position} 轮缺少回退目标`);
+        }
+        position = record.restoresSequence;
+    }
+}
+// 从 sequence 之后的全部可见改动倒推：每个路径取最早一次修改前像。
+function overlayAfter(view, sequence) {
+    const overlay = new Map();
+    for (let position = sequence + 1; position <= view.head; position += 1) {
+        if (view.discarded.has(position))
+            continue;
+        const record = view.byPosition.get(position);
+        if (!record) {
+            throw new WorldTurnLedgerError("missing_record", `缺少第 ${position} 轮记录`);
+        }
+        if (record.mode === "rewind")
+            continue;
+        for (const file of record.files) {
+            if (!overlay.has(file.path))
+                overlay.set(file.path, file.before);
+        }
+    }
+    return overlay;
+}
+async function captureBefore(root, paths) {
+    const files = [];
+    for (const path of paths) {
+        assertSafePath(path);
+        files.push({ path, before: await readTextOrNull(join(root, path)) });
+    }
+    return files;
+}
+// 第一步：写入本轮记录（序号为 head + 1）。记录原子落盘，之后任何一步崩溃都可由 recoverIncomplete 回滚。
+export async function beginTurn(root, input) {
+    const head = await readHead(root);
+    const record = {
+        sequence: head + 1,
+        mode: input.mode,
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        ...(input.restoresSequence === undefined
+            ? {}
+            : { restoresSequence: input.restoresSequence }),
+        ...(input.payload === undefined ? {} : { payload: input.payload }),
+        files: await captureBefore(root, input.changes.map((change) => change.path)),
+    };
+    await writeFileAtomic(join(root, turnFileName(record.sequence)), `${JSON.stringify(record, null, 2)}\n`);
+    return record;
+}
+// 第二步：逐文件原子替换（写临时文件后 rename；删除即 rm）。
+export async function applyChanges(root, changes) {
+    for (const change of changes) {
+        assertSafePath(change.path);
+        const absolute = join(root, change.path);
+        if (change.content === null) {
+            await rm(absolute, { force: true });
+        }
+        else {
+            await writeFileAtomic(absolute, change.content);
+        }
+    }
+}
+// 第三步：发布端点。只有这一步之后，本轮才算完成。
+export async function commitTurnHead(root, record) {
+    await publishHead(root, record.sequence);
+}
+export async function appendTurn(root, input) {
+    const record = await beginTurn(root, input);
+    await applyChanges(root, input.changes);
+    await commitTurnHead(root, record);
+    return record;
+}
+// 启动时调用：序号大于 head 的记录说明上一次推进未完成，逆序恢复其修改前像。
+// 被丢弃的轮记录（读取时已忽略）在这里清理。返回是否回滚了未完成的轮。
+export async function recoverIncomplete(root) {
+    const head = await readHead(root);
+    const records = await readAllRecords(root);
+    const incomplete = records
+        .filter((record) => record.sequence > head)
+        .sort((left, right) => right.sequence - left.sequence);
+    for (const record of incomplete) {
+        for (const file of [...record.files].reverse()) {
+            assertSafePath(file.path);
+            const absolute = join(root, file.path);
+            if (file.before === null) {
+                await rm(absolute, { force: true });
+            }
+            else {
+                await writeFileAtomic(absolute, file.before);
+            }
+        }
+        await rm(join(root, turnFileName(record.sequence)), { force: true });
+    }
+    const view = viewOf(head, records);
+    for (const position of view.discarded) {
+        await rm(join(root, turnFileName(position)), { force: true });
+    }
+    forgetLedger(root);
+    return incomplete.length > 0;
+}
+export async function listTurns(root) {
+    const view = await loadView(root);
+    const turns = [];
+    for (let position = 1; position <= view.head; position += 1) {
+        if (view.discarded.has(position))
+            continue;
+        const record = view.byPosition.get(position);
+        if (!record) {
+            throw new WorldTurnLedgerError("missing_record", `缺少第 ${position} 轮记录`);
+        }
+        turns.push(record);
+    }
+    return turns;
+}
+// 把端点解析为它所表示的逻辑位置（rewind 位置等价于它恢复的位置）。
+export async function resolveEndpoint(root, sequence) {
+    return resolvePosition(await loadView(root), sequence);
+}
+// 第 sequence 轮记录文件的 sha256；0 轮没有记录，返回 null。
+export async function readTurnDigest(root, sequence) {
+    if (sequence === 0)
+        return null;
+    const text = await readFile(join(root, turnFileName(sequence)), "utf8");
+    return createHash("sha256").update(text).digest("hex");
+}
+// 读取端点 sequence 处某个文件的内容；不存在返回 null。
+export async function readFileAt(root, sequence, relativePath) {
+    assertSafePath(relativePath);
+    const view = await loadView(root);
+    const position = resolvePosition(view, sequence);
+    const overlay = overlayAfter(view, position);
+    if (overlay.has(relativePath))
+        return overlay.get(relativePath) ?? null;
+    return readTextOrNull(join(root, relativePath));
+}
+// 读取端点 sequence 处 dirs 下的全部文件（相对路径 → 内容）。
+export async function readTreeAt(root, sequence, dirs) {
+    const view = await loadView(root);
+    const position = resolvePosition(view, sequence);
+    const overlay = overlayAfter(view, position);
+    const tree = new Map();
+    for (const dir of dirs) {
+        assertSafePath(dir);
+        for (const path of await listFiles(root, dir)) {
+            if (!overlay.has(path)) {
+                const text = await readTextOrNull(join(root, path));
+                if (text !== null)
+                    tree.set(path, text);
+            }
+        }
+    }
+    for (const [path, before] of overlay) {
+        const inDir = dirs.some((dir) => path === dir || path.startsWith(dir + "/"));
+        if (!inDir || before === null)
+            continue;
+        tree.set(path, before);
+    }
+    return tree;
+}
+async function listFiles(root, dir) {
+    const found = [];
+    const visit = async (relative) => {
+        let entries;
+        try {
+            entries = await readdir(join(root, relative), { withFileTypes: true });
+        }
+        catch (error) {
+            if (isMissing(error))
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const child = `${relative}/${entry.name}`;
+            if (entry.isDirectory()) {
+                await visit(child);
+            }
+            else if (entry.isFile() && !entry.name.endsWith(".tmp")) {
+                found.push(child);
+            }
+        }
+    };
+    await visit(dir);
+    return found;
+}
+// 回退到端点 sequence：追加一轮 rewind（前像为回退前的文件），之后丢弃 (sequence, head] 的记录。
+// 已经处于 sequence 的端点是空操作。返回新轮记录，或 null。
+export async function rewindTo(root, sequence) {
+    const view = await loadView(root);
+    const target = resolvePosition(view, sequence);
+    if (target === view.head)
+        return null;
+    const overlay = overlayAfter(view, target);
+    const changes = [];
+    for (const [path, before] of overlay) {
+        const current = await readTextOrNull(join(root, path));
+        if (current === before)
+            continue;
+        changes.push({ path, content: before });
+    }
+    const record = await appendTurn(root, {
+        mode: "rewind",
+        changes,
+        restoresSequence: sequence,
+    });
+    // 端点已发布，丢弃的记录即可删除；失败可忽略，读取已把它们当作不可达，下次回退或恢复会再清理。
+    for (let position = target + 1; position <= view.head; position += 1) {
+        await rm(join(root, turnFileName(position)), { force: true }).catch(() => undefined);
+    }
+    return record;
+}

package/dist/node/runtime/world-revision/FileNativeWorldRevisionStore.js

@@ -111,7 +111,6 @@ export class FileNativeWorldRevisionStore {
             if (session.worldId !== worldId)
                 throw new Error("World-revision conversation belongs to another world");
             await rm(this.#sessionPath(sessionId));
-            await syncDirectory(this.#sessionsRoot);
         });
     }
     async #readEpoch(epochId) {
@@ -247,7 +246,7 @@ function validateSession(value) {
         /[\r\n\0]/u.test(value.worldTitle) ||
         typeof value.epochId !== "string" ||
         (value.locale !== "en" && value.locale !== "zh-CN") ||
-        !["ready", "running", "interrupted"].includes(String(value.runStatus)) ||
+        !["ready", "running", "paused", "interrupted"].includes(String(value.runStatus)) ||
         !finite(value.createdAt) ||
         !finite(value.updatedAt) ||
         value.updatedAt < value.createdAt ||
@@ -637,27 +636,16 @@ async function publishJson(path, value) {
         const handle = await open(temporary, "wx", 0o600);
         try {
             await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
-            await handle.sync();
         }
         finally {
             await handle.close();
         }
         await rename(temporary, path);
-        await syncDirectory(dirname(path));
     }
     finally {
         await rm(temporary, { force: true });
     }
 }
-async function syncDirectory(path) {
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
 function count(value) {
     return Number.isSafeInteger(value) && Number(value) >= 0;
 }

package/dist/node/runtime/world-revision/WorldRevisionSession.js

@@ -1,7 +1,7 @@
 import { authoringRequestPreviews } from "../authoring/AuthoringRequestSnapshot.js";
 import { createHash } from "node:crypto";
 import { emptyAggregatedModelUsage } from "../../protocol/modelUsage.js";
-import { appendAuthoringUserMessage, ModelToolConversation, rememberAuthoringRequest, } from "../authoring/ModelToolConversation.js";
+import { appendAuthoringUserMessage, ModelToolConversation, rememberAuthoringRequest, resumePausedAuthoringConversation, } from "../authoring/ModelToolConversation.js";
 import { contentTreeFingerprint } from "../content/ContentTreeFingerprint.js";
 import { equalModelHostBinding } from "../model/ModelHost.js";
 import { settingImprovementPromptForBinding, } from "../play/FileNativePlayPresetStore.js";
@@ -215,6 +215,34 @@ export class WorldRevisionSession {
         });
         return prepared.run ?? this.#view(prepared.session);
     }
+    /** Continues a paused conversation within the revision it paused in. */
+    async resume(input) {
+        const requestId = requiredRequestId(input.requestId);
+        const prepared = await this.#mutate(async () => {
+            let session = await this.#store.readSession(input.sessionId);
+            assertWorld(session, input.worldId);
+            session = await this.#recoverIfNeeded(session);
+            if (session.completedRequestIds.includes(requestId))
+                return { session, run: null };
+            const running = this.#conversation.running(session.sessionId);
+            if (running !== null) {
+                if (running.requestId !== requestId)
+                    throw new Error("Another message in this world-revision conversation is still running");
+                return { session, run: running.promise };
+            }
+            await this.#assertNoRunningConversation(input.worldId, session.sessionId);
+            const epoch = await this.#workspace.active(input.worldId);
+            if (epoch?.epochId !== session.epochId)
+                throw new WorldRevisionWorkspaceError("The paused conversation belongs to a revision that is no longer active; send a new message instead");
+            const host = await this.#bindExistingModelHost(session.modelBinding);
+            if (!equalModelHostBinding(session.modelBinding, host.binding()))
+                throw new Error("No saved model connection matches this world-revision conversation");
+            resumePausedAuthoringConversation(session);
+            await this.#store.saveSession(session);
+            return { session, run: this.#startRun(session, host, requestId) };
+        });
+        return prepared.run ?? this.#view(prepared.session);
+    }
     async preview(worldId, sessionId) {
         const session = sessionId === undefined ? null : await this.#store.readSession(sessionId);
         if (session !== null)
@@ -317,7 +345,6 @@ export class WorldRevisionSession {
             },
             view: (next) => this.#view(next),
             failure: {
-                exchangeLimit: "World revision exceeded 64 model exchanges for one user message",
                 cancelled: "The world-revision response was cancelled. Settled worktree changes were retained.",
                 interrupted: "The world-revision response was interrupted",
             },

package/dist/node/server/mobile.js

@@ -0,0 +1,52 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { inspect } from "node:util";
+import { resolveAppPaths } from "../runtime/config/appPaths.js";
+import { parseWebPort, startWebServer } from "./startWebServer.js";
+// Mobile entry: started inside the Android app's Node runtime. The native shell
+// owns the process lifecycle, so this module never registers signal handlers and
+// never calls process.exit(); a startup failure is logged and the native side
+// reports it.
+const paths = resolveAppPaths(process.env);
+const crashLogPath = join(paths.logRoot, "crash", "node-errors.log");
+// Node shares the Android app process: an uncaught error would make Node call
+// exit() and close the whole app. Record the error and keep serving instead; each
+// Runtime write is atomic, so a failed request does not leave a half-written file.
+process.on("uncaughtException", (error, origin) => {
+    recordCrash(origin, error);
+});
+process.on("unhandledRejection", (reason) => {
+    recordCrash("unhandledRejection", reason);
+});
+process.on("exit", (code) => {
+    recordCrash("exit", `process exiting with code ${code}`);
+});
+try {
+    const staticRoot = process.env.NARRAEON_STATIC_ROOT?.trim();
+    if (!staticRoot)
+        throw new Error("NARRAEON_STATIC_ROOT is required for the mobile entry");
+    const port = parseWebPort(process.env.NARRAEON_PORT);
+    const server = await startWebServer({
+        paths,
+        staticRoot,
+        host: "127.0.0.1",
+        port,
+    });
+    const address = server.server.address();
+    const listeningPort = typeof address === "object" && address !== null ? address.port : port;
+    process.stdout.write(`NARRAEON_READY ${listeningPort}\n`);
+}
+catch (error) {
+    recordCrash("startup", error);
+}
+function recordCrash(kind, value) {
+    const text = `${new Date().toISOString()} [${kind}] ${typeof value === "string" ? value : inspect(value, { depth: 4 })}\n`;
+    process.stderr.write(text);
+    try {
+        mkdirSync(join(paths.logRoot, "crash"), { recursive: true, mode: 0o700 });
+        appendFileSync(crashLogPath, text, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // The stderr copy above still reaches logcat and the native stderr log.
+    }
+}

package/dist/node/server/startWebServer.js

@@ -1,22 +1,29 @@
+import { acquireDataRootLock } from "../runtime/config/dataRootLock.js";
 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({
-        runtime,
-        staticRoot: input.staticRoot,
-        port: input.port,
-        ...(input.logger === undefined ? {} : { logger: input.logger }),
-    });
+    const lock = await acquireDataRootLock(input.paths.dataRoot);
+    let server;
     try {
+        const runtime = await createRuntime(input.paths);
+        server = await createServer({
+            runtime,
+            staticRoot: input.staticRoot,
+            port: input.port,
+            ...(input.logger === undefined ? {} : { logger: input.logger }),
+        });
+        server.addHook("onClose", () => lock.release());
         await server.listen({ host: input.host, port: input.port });
         return server;
     }
     catch (error) {
-        await server.close().catch(() => undefined);
+        if (server !== undefined)
+            await server.close().catch(() => undefined);
+        else
+            await lock.release();
         throw error;
     }
 }