narraeon 0.6.1 → 0.6.2

package/dist/node/protocol/v1.js

@@ -68,6 +68,11 @@ const requiredFields = {
         continuation: "object",
     },
     "setting-improvement.cancel": { sessionId: "string" },
+    "setting-improvement.resume": {
+        packageId: "string",
+        sessionId: "string",
+        requestId: "string",
+    },
     "play.create": { name: "string" },
     "play.copy": { presetId: "string" },
     "play.save": { presetId: "string", name: "string", files: "object" },
@@ -120,6 +125,11 @@ const requiredFields = {
         continuation: "object",
     },
     "world.revision.cancel": { sessionId: "string" },
+    "world.revision.resume": {
+        worldId: "string",
+        sessionId: "string",
+        requestId: "string",
+    },
     "world.revision.files.replace": {
         worldId: "string",
         epochId: "string",
@@ -422,6 +432,7 @@ const requestTypes = new Set([
     "setting-improvement.rollback",
     "setting-improvement.message",
     "setting-improvement.cancel",
+    "setting-improvement.resume",
     "play.read",
     "play.create",
     "play.copy",
@@ -456,6 +467,7 @@ const requestTypes = new Set([
     "world.revision.session.delete",
     "world.revision.message",
     "world.revision.cancel",
+    "world.revision.resume",
     "world.revision.files.replace",
     "world.revision.rollback",
     "world.revision.apply",

package/dist/node/runtime/V1Runtime.js

@@ -383,6 +383,8 @@ export class V1Runtime {
                 return this.#settingImprovements.send(request);
             case "setting-improvement.cancel":
                 return this.#settingImprovements.cancel(request.sessionId);
+            case "setting-improvement.resume":
+                return this.#settingImprovements.resume(request);
             case "play.read":
                 return this.#playPresets.list();
             case "play.create":
@@ -614,6 +616,8 @@ export class V1Runtime {
                 return this.#worldRevisionCall(() => this.#worldRevisions.send(request));
             case "world.revision.cancel":
                 return this.#worldRevisionCall(() => this.#worldRevisions.cancel(request.sessionId));
+            case "world.revision.resume":
+                return this.#worldRevisionCall(() => this.#worldRevisions.resume(request));
             case "world.revision.files.replace":
                 return this.#worldRevisionCall(() => this.#worldRevisions.replaceFiles(request));
             case "world.revision.rollback":

package/dist/node/runtime/authoring/ModelToolConversation.js

@@ -119,8 +119,15 @@ export class ModelToolConversation {
                 await input.settleToolResponse(session, session.modelItems.length - 1, toolCalls);
                 input.changed?.(true);
             }
-            throw new Error(input.failure?.exchangeLimit ??
-                `Authoring exceeded ${maximumExchangesPerMessage} model exchanges for one user message`);
+            // The exchange budget only bounds a runaway loop. Every tool response is
+            // already settled, so the conversation pauses and can resume unchanged.
+            session.runStatus = "paused";
+            session.activeRequestId = null;
+            session.completedRequestIds = rememberRequest(session.completedRequestIds, live.requestId);
+            session.lastFailure = null;
+            session.updatedAt = Date.now();
+            await input.save(session);
+            return input.view(session);
         }
         catch (error) {
             session.runStatus = "interrupted";
@@ -154,6 +161,22 @@ export function appendAuthoringUserMessage(session, message, requestId) {
     session.lastFailure = null;
     session.updatedAt = now;
 }
+/**
+ * Starts another exchange budget for a paused conversation without appending a
+ * user message; the next request replays the settled transcript as-is. The run
+ * still belongs to the paused user request, so that request stays active; the
+ * caller's resume request ID only deduplicates the resume itself.
+ */
+export function resumePausedAuthoringConversation(session) {
+    if (session.runStatus !== "paused")
+        throw new Error("Only a paused authoring conversation can be continued");
+    if (session.modelItems.at(-1)?.kind !== "tool")
+        throw new Error("The paused authoring conversation does not end with settled tool results");
+    session.runStatus = "running";
+    session.activeRequestId = session.requests?.at(-1)?.requestId ?? null;
+    session.lastFailure = null;
+    session.updatedAt = Date.now();
+}
 export function requiredAuthoringMessage(message) {
     if (message.trim().length === 0)
         throw new Error("An authoring message cannot be empty");

package/dist/node/runtime/prompt/WorldMaintenanceReport.js

@@ -236,16 +236,48 @@ export function renderDocumentWritePosition(shortRef, fact, locale) {
         ? `最近写入位置 @${shortRef}：\n正文：${worldWritePositionText(fact.lastBodyWrite, locale)}\n元信息：${worldWritePositionText(fact.lastMetadataWrite, locale)}`
         : `Last committed write @${shortRef}:\nBody: ${worldWritePositionText(fact.lastBodyWrite, locale)}\nMetadata: ${worldWritePositionText(fact.lastMetadataWrite, locale)}`;
 }
-export function renderWorldMaintenanceReport(report, locale) {
+/**
+ * Lists only documents the current tool response changed or that exceed their
+ * advisory limit, so the report stays proportional to the edit rather than to
+ * the package size.
+ */
+export function renderWorldMaintenanceReport(report, changedShortRefs, locale) {
     if (report === undefined)
         return "";
     const zh = locale === "zh-CN";
+    const heading = zh
+        ? "# 文档整理报告（UTF-8 字节；超限仅提示）"
+        : "# Document maintenance (UTF-8 bytes; advisory only)";
+    const documents = report.documents.filter((document) => document.overAdvisory || changedShortRefs.has(document.shortRef));
+    const slots = report.slots.filter((slot) => slot.overAdvisory ||
+        slot.documents.some((shortRef) => changedShortRefs.has(shortRef)));
+    if (documents.length === 0 && slots.length === 0)
+        return `${heading}\n${zh ? "本次没有改动世界文档，也没有文档或材料槽超过建议上限。" : "No world document changed in this response, and no document or slot exceeds its advisory limit."}`;
+    const allColumns = [
+        { label: zh ? "正文" : "body", value: (d) => d.bodyBytes },
+        {
+            label: zh ? "注入贡献" : "injection contribution",
+            value: (d) => d.injectedBytes,
+        },
+        { label: zh ? "建议上限" : "advisory", value: (d) => d.advisoryBytes },
+        { label: zh ? "基准" : "baseline", value: (d) => d.baselineBytes },
+        { label: zh ? "增长" : "growth", value: (d) => d.growthBytes },
+    ];
+    // Columns that are unset for every listed document carry no information.
+    const columns = allColumns.filter(({ value }) => documents.some((document) => value(document) !== null));
+    const overAdvisory = report.documents.some(({ overAdvisory }) => overAdvisory) ||
+        report.slots.some(({ overAdvisory }) => overAdvisory);
     return [
-        zh
-            ? "# 文档整理报告（UTF-8 字节；超限仅提示）"
-            : "# Document maintenance (UTF-8 bytes; advisory only)",
-        `${zh ? "世界材料 / 其中检查点历史 / 作者提示 / Runtime 提示 / 工具定义" : "World materials / checkpoint history subset / author instructions / Runtime instructions / tool definitions"}: ${report.worldMaterialsBytes} / ${report.checkpointHistoryBytes} / ${report.authorInstructionBytes} / ${report.runtimeInstructionBytes} / ${report.toolDefinitionBytes}`,
-        ...report.documents.map((document) => `@${document.shortRef}: ${zh ? "正文 / 注入贡献 / 建议上限 / 基准 / 增长" : "body / injection contribution / advisory / baseline / growth"}: ${document.bodyBytes} / ${document.injectedBytes} / ${document.advisoryBytes ?? "—"} / ${document.baselineBytes ?? "—"} / ${document.growthBytes ?? "—"}${document.overAdvisory ? (zh ? "（超过建议）" : " (over advisory)") : ""}`),
-        ...report.slots.map((slot) => `${zh ? "材料槽" : "Slot"} ${slot.id}: ${slot.bytes} / ${slot.advisoryBytes ?? "—"}${slot.overAdvisory ? (zh ? "（超过建议）" : " (over advisory)") : ""}`),
+        heading,
+        ...(overAdvisory
+            ? [
+                `${zh ? "世界材料 / 其中检查点历史 / 作者提示 / Runtime 提示 / 工具定义" : "World materials / checkpoint history subset / author instructions / Runtime instructions / tool definitions"}: ${report.worldMaterialsBytes} / ${report.checkpointHistoryBytes} / ${report.authorInstructionBytes} / ${report.runtimeInstructionBytes} / ${report.toolDefinitionBytes}`,
+            ]
+            : []),
+        ...(documents.length > 0
+            ? [columns.map(({ label }) => label).join(" / ")]
+            : []),
+        ...documents.map((document) => `@${document.shortRef}: ${columns.map(({ value }) => value(document) ?? "—").join(" / ")}${document.overAdvisory ? (zh ? "（超过建议）" : " (over advisory)") : ""}`),
+        ...slots.map((slot) => `${zh ? "材料槽" : "Slot"} ${slot.id}: ${slot.bytes} / ${slot.advisoryBytes ?? "—"}${slot.overAdvisory ? (zh ? "（超过建议）" : " (over advisory)") : ""}`),
     ].join("\n");
 }

package/dist/node/runtime/setting/FileNativeSettingImprovementStore.js

@@ -487,7 +487,10 @@ function validOptionalTitle(value) {
             !/[\r\n]/u.test(value)));
 }
 function validRunStatus(value) {
-    return value === "ready" || value === "running" || value === "interrupted";
+    return (value === "ready" ||
+        value === "running" ||
+        value === "paused" ||
+        value === "interrupted");
 }
 function validCount(value) {
     return Number.isSafeInteger(value) && Number(value) >= 0;

package/dist/node/runtime/setting/SettingAuthoringTransaction.js

@@ -329,6 +329,7 @@ export class SettingAuthoringTransaction {
     execute(calls) {
         const normalized = calls.map(normalizeCall);
         const results = [];
+        const responseBase = this.files();
         let lastSuccessfulWrite = -1;
         for (const call of normalized) {
             const before = this.files();
@@ -344,7 +345,9 @@ export class SettingAuthoringTransaction {
         if (lastSuccessfulWrite >= 0) {
             this.#review = this.#inspect();
             const settled = results[lastSuccessfulWrite];
-            settled.markdown = `${settled.markdown}\n\n${renderAutomaticReview(this.#review, this.#locale)}`;
+            // The stored review stays cumulative for the whole user request; the
+            // model only needs what this tool response changed.
+            settled.markdown = `${settled.markdown}\n\n${renderAutomaticReview(this.#review, fileDiff(responseBase, this.#snapshot.files), this.#snapshot, this.#locale)}`;
         }
         return results;
     }
@@ -450,9 +453,16 @@ export class SettingAuthoringTransaction {
         }
     }
 }
-function renderAutomaticReview(review, locale) {
-    if (review.status === "usable")
-        return `${localized(locale, `# Current-tree review passed\n\nContent-tree validation and the real Prompt Preview both passed. This tool response changes ${review.diff.length} file(s) directly in the content package. Use this review and the coverage below to decide whether the current user request is satisfied or further edits are needed.`, `# 当前树自动检查通过\n\n内容树校验和真实 Prompt Preview 均已通过；本次工具响应直接修改内容包中的 ${review.diff.length} 个文件。请根据本次检查与下方覆盖报告判断当前用户要求是否已经满足，或是否还需修改。`)}\n\n${renderPlayCoverage(review.playCoverage, locale)}\n\n${renderWorldMaintenanceReport(review.preview?.compilation.maintenance, locale)}`;
+function renderAutomaticReview(review, responseDiff, snapshot, locale) {
+    if (review.status === "usable" && review.preview !== null) {
+        const changed = responseDiff.length;
+        const cumulative = review.diff.length;
+        const changedPaths = new Set(responseDiff.map(({ path }) => path));
+        const changedShortRefs = new Set(listQueryableWorldDocuments(snapshot)
+            .filter(({ logicalPath }) => changedPaths.has(logicalPath))
+            .map(({ shortRef }) => shortRef));
+        return `${localized(locale, `# Current-tree review passed\n\nContent-tree validation and the real Prompt Preview both passed. This tool response changed ${changed} file(s) in the content package${cumulative === changed ? "" : `; ${cumulative} file(s) changed so far in this user request`}. Use this review and the coverage below to decide whether the current user request is satisfied or further edits are needed.`, `# 当前树自动检查通过\n\n内容树校验和真实 Prompt Preview 均已通过；本次工具响应修改内容包中的 ${changed} 个文件${cumulative === changed ? "" : `，本次用户请求累计改动 ${cumulative} 个文件`}。请根据本次检查与下方覆盖报告判断当前用户要求是否已经满足，或是否还需修改。`)}\n\n${renderPlayCoverage(buildSettingAuthoringPlayCoverage(snapshot, review.preview, responseDiff), locale)}\n\n${renderWorldMaintenanceReport(review.preview.compilation.maintenance, changedShortRefs, locale)}`;
+    }
     return [
         localized(locale, "# Current-tree review needs repair", "# 当前树自动检查需要修复"),
         "",
@@ -561,8 +571,6 @@ function playAccessDetail(access) {
     return details[access];
 }
 function renderPlayCoverage(coverage, locale) {
-    if (coverage === null)
-        return localized(locale, "# Play-consumption coverage\n\nCoverage is unavailable until the real Prompt Preview succeeds.", "# 游玩读取覆盖\n\n真实 Prompt Preview 通过后才会提供覆盖报告。");
     const labels = locale === "zh-CN"
         ? {
             full_injected: "全文注入",

package/dist/node/runtime/setting/SettingImprovementSession.js

@@ -4,7 +4,7 @@ import { InvalidContentTreeError, } from "../content/ContentWorkspace.js";
 import { contentTreeFingerprint } from "../content/ContentTreeFingerprint.js";
 import { equalModelHostBinding } from "../model/ModelHost.js";
 import { settingImprovementPromptForBinding, } from "../play/FileNativePlayPresetStore.js";
-import { appendAuthoringUserMessage, ModelToolConversation, rememberAuthoringRequest, } from "../authoring/ModelToolConversation.js";
+import { appendAuthoringUserMessage, ModelToolConversation, rememberAuthoringRequest, resumePausedAuthoringConversation, } from "../authoring/ModelToolConversation.js";
 import { summarizeStoredSettingImprovementSession, } from "./FileNativeSettingImprovementStore.js";
 import { SettingAuthoringTransaction, settingImprovementRuntimeContract, settingImprovementToolDefinitions, } from "./SettingAuthoringTransaction.js";
 class RecoveryWriteConflictError extends Error {
@@ -185,33 +185,48 @@ export class SettingImprovementSession {
                 session = await this.#store.read(input.continuation.sessionId);
                 assertPackage(session, input.packageId);
             }
-            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 setting-improvement conversation is still running");
-                return { session, run: running.promise };
-            }
-            const host = await this.#bindExistingModelHost(session.modelBinding);
-            if (!equalModelHostBinding(session.modelBinding, host.binding()))
-                throw new Error("No saved model connection matches this setting-improvement conversation");
-            const { playPreset, bootstrap } = await this.#compileCurrent(input.packageId, session.modelBinding);
-            session.schemaVersion = 3;
-            session.requests ??= [];
-            session.requests.push({
-                requestId,
-                modelItemStart: session.modelItems.length,
-                bootstrap,
-                playPreset: structuredClone(playPreset),
+            return this.#startRequest(session, requestId, async (next) => {
+                const { playPreset, bootstrap } = await this.#compileCurrent(input.packageId, next.modelBinding);
+                next.schemaVersion = 3;
+                next.requests ??= [];
+                next.requests.push({
+                    requestId,
+                    modelItemStart: next.modelItems.length,
+                    bootstrap,
+                    playPreset: structuredClone(playPreset),
+                });
+                appendAuthoringUserMessage(next, message, requestId);
             });
-            appendAuthoringUserMessage(session, message, requestId);
-            await this.#store.save(session);
-            return { session, run: this.#startRun(session, host, requestId) };
         });
         return prepared.run ?? this.#view(prepared.session);
     }
+    /** Continues a paused conversation with the frozen request it paused in. */
+    async resume(input) {
+        const requestId = requiredRequestId(input.requestId);
+        const prepared = await this.#mutate(async () => {
+            const session = await this.#store.read(input.sessionId);
+            assertPackage(session, input.packageId);
+            return this.#startRequest(session, requestId, (next) => resumePausedAuthoringConversation(next));
+        });
+        return prepared.run ?? this.#view(prepared.session);
+    }
+    async #startRequest(stored, requestId, prepare) {
+        const session = await this.#recoverIfNeeded(stored);
+        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 setting-improvement conversation is still running");
+            return { session, run: running.promise };
+        }
+        const host = await this.#bindExistingModelHost(session.modelBinding);
+        if (!equalModelHostBinding(session.modelBinding, host.binding()))
+            throw new Error("No saved model connection matches this setting-improvement conversation");
+        await prepare(session);
+        await this.#store.save(session);
+        return { session, run: this.#startRun(session, host, requestId) };
+    }
     async preview(packageId, sessionId) {
         const session = sessionId === undefined ? null : await this.#store.read(sessionId);
         if (session !== null)
@@ -307,7 +322,6 @@ export class SettingImprovementSession {
             view: (next) => this.#view(next),
             failure: {
                 emptyResponse: "The model returned an empty tool-free authoring response",
-                exchangeLimit: "Setting improvement exceeded 64 model exchanges for one user message",
                 cancelled: "The setting-improvement response was cancelled. Complete tool responses already published to the current tree were retained.",
                 interrupted: "The setting-improvement response was interrupted",
             },

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

@@ -246,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 ||

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

@@ -1,20 +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 rejects and the native side reads
-// stderr.
-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);
+// never calls process.exit(); a startup failure is logged and the native side
+// reports it.
 const paths = resolveAppPaths(process.env);
-const server = await startWebServer({
-    paths,
-    staticRoot,
-    host: "127.0.0.1",
-    port,
+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);
 });
-const address = server.server.address();
-const listeningPort = typeof address === "object" && address !== null ? address.port : port;
-process.stdout.write(`NARRAEON_READY ${listeningPort}\n`);
+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.
+    }
+}