narraeon 0.4.0 → 0.5.1

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

@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import { aggregateModelUsage, } from "../../protocol/modelUsage.js";
+import { ModelHostCancelledError } from "../model/ModelHost.js";
+const maximumExchangesPerMessage = 64;
+const maximumStreamTailCharacters = 240;
+/**
+ * Deep Module for the shared authoring-conversation loop. Its Interface leaves
+ * content-package and world-revision publication behind the settlement seam.
+ */
+export class ModelToolConversation {
+    #runs = new Map();
+    isRunning(sessionId) {
+        return this.#runs.has(sessionId);
+    }
+    runningRequestId(sessionId) {
+        return this.#runs.get(sessionId)?.requestId ?? null;
+    }
+    running(sessionId) {
+        const run = this.#runs.get(sessionId);
+        return run === undefined
+            ? null
+            : { requestId: run.requestId, promise: run.promise };
+    }
+    streaming(sessionId) {
+        const streaming = this.#runs.get(sessionId)?.streaming;
+        return streaming === undefined ? null : structuredClone(streaming);
+    }
+    run(input) {
+        const existing = this.#runs.get(input.session.sessionId);
+        if (existing !== undefined) {
+            if (existing.requestId !== input.requestId)
+                throw new Error("Another message in this authoring conversation is still running");
+            return existing.promise;
+        }
+        const live = {
+            requestId: input.requestId,
+            controller: new AbortController(),
+            promise: Promise.resolve(undefined),
+            streaming: emptyStreaming(),
+        };
+        live.promise = this.#execute(input, live).finally(() => {
+            if (this.#runs.get(input.session.sessionId) === live)
+                this.#runs.delete(input.session.sessionId);
+            input.changed?.(true);
+        });
+        this.#runs.set(input.session.sessionId, live);
+        input.changed?.(true);
+        return live.promise;
+    }
+    cancel(sessionId) {
+        const running = this.#runs.get(sessionId);
+        if (running === undefined)
+            return null;
+        running.controller.abort();
+        return running.promise;
+    }
+    async #execute(input, live) {
+        const { session } = input;
+        const bootstrap = session.requests?.at(-1)?.bootstrap ?? session.bootstrap;
+        try {
+            for (let round = 0; round < maximumExchangesPerMessage; round += 1) {
+                session.exchange += 1;
+                live.streaming = emptyStreaming();
+                session.updatedAt = Date.now();
+                await input.save(session);
+                input.changed?.(true);
+                const response = await input.host.exchange({
+                    bootstrap,
+                    toolUniverse: bootstrap.toolUniverse,
+                    allowedTools: bootstrap.toolUniverse.map(({ name }) => name),
+                    toolStrategy: bootstrap.toolStrategy,
+                    tools: bootstrap.tools,
+                    appended: session.modelItems,
+                    requestId: live.requestId,
+                    operationId: session.sessionId,
+                    requestAttempt: 1,
+                    exchange: session.exchange,
+                    maxOutputTokens: session.modelBinding.maxOutputTokens,
+                }, {
+                    signal: live.controller.signal,
+                    onDelta: (delta) => {
+                        recordDelta(live, delta);
+                        input.changed?.(false);
+                    },
+                });
+                assertCompleteResponse(response);
+                const toolCalls = response.toolCalls ?? [];
+                assertUniqueToolCallIds(toolCalls);
+                const visibleText = response.text ?? "";
+                if (toolCalls.length === 0 && visibleText.trim().length === 0)
+                    throw new Error(input.failure?.emptyResponse ??
+                        "The model returned an empty tool-free authoring response");
+                session.usage = aggregateModelUsage(session.usage, response.usage);
+                session.modelItems.push({
+                    kind: "assistant",
+                    text: visibleText,
+                    ...(response.reasoningContent === undefined
+                        ? {}
+                        : { reasoningContent: response.reasoningContent }),
+                    providerState: response.providerState,
+                    toolCalls: structuredClone(toolCalls),
+                });
+                session.updatedAt = Date.now();
+                if (toolCalls.length === 0) {
+                    session.messages.push({
+                        id: `message-${randomUUID()}`,
+                        role: "assistant",
+                        text: visibleText,
+                        createdAt: session.updatedAt,
+                    });
+                    session.runStatus = "ready";
+                    session.activeRequestId = null;
+                    session.completedRequestIds = rememberRequest(session.completedRequestIds, live.requestId);
+                    session.lastFailure = null;
+                    await input.save(session);
+                    input.changed?.(true);
+                    return input.view(session);
+                }
+                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`);
+        }
+        catch (error) {
+            session.runStatus = "interrupted";
+            session.activeRequestId = null;
+            session.completedRequestIds = rememberRequest(session.completedRequestIds, live.requestId);
+            session.lastFailure =
+                error instanceof ModelHostCancelledError
+                    ? (input.failure?.cancelled ??
+                        "The authoring response was cancelled. Complete tool responses already settled were retained.")
+                    : error instanceof Error
+                        ? error.message
+                        : (input.failure?.interrupted ??
+                            "The authoring response was interrupted");
+            session.updatedAt = Date.now();
+            await input.save(session);
+            return input.view(session);
+        }
+    }
+}
+export function appendAuthoringUserMessage(session, message, requestId) {
+    const now = Date.now();
+    session.messages.push({
+        id: `message-${randomUUID()}`,
+        role: "user",
+        text: requiredAuthoringMessage(message),
+        createdAt: now,
+    });
+    session.modelItems.push({ kind: "user", text: message });
+    session.runStatus = "running";
+    session.activeRequestId = requiredAuthoringRequestId(requestId);
+    session.lastFailure = null;
+    session.updatedAt = now;
+}
+export function requiredAuthoringMessage(message) {
+    if (message.trim().length === 0)
+        throw new Error("An authoring message cannot be empty");
+    if (message.length > 64 * 1024)
+        throw new Error("The authoring message is too large");
+    return message;
+}
+export function requiredAuthoringRequestId(requestId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/u.test(requestId))
+        throw new Error("Invalid authoring request ID");
+    return requestId;
+}
+export function rememberAuthoringRequest(existing, requestId) {
+    return rememberRequest(existing, requestId);
+}
+function assertCompleteResponse(response) {
+    if (response.providerState === undefined)
+        throw new Error("The complete authoring response is missing provider continuation state");
+}
+function assertUniqueToolCallIds(calls) {
+    const ids = new Set();
+    for (const call of calls) {
+        if (call.id.length === 0 || call.name.length === 0 || ids.has(call.id))
+            throw new Error("The model returned invalid or duplicate tool-call IDs");
+        ids.add(call.id);
+    }
+}
+function rememberRequest(existing, requestId) {
+    return [
+        ...existing.filter((candidate) => candidate !== requestId),
+        requestId,
+    ];
+}
+function emptyStreaming() {
+    return {
+        reasoningChars: 0,
+        textChars: 0,
+        toolChars: 0,
+        tail: "",
+        reasoningText: "",
+        visibleText: "",
+        toolFragment: "",
+        receivedAt: Date.now(),
+    };
+}
+function recordDelta(live, delta) {
+    if (delta.kind === "reasoning") {
+        live.streaming.reasoningChars += delta.text.length;
+        live.streaming.reasoningText = `${live.streaming.reasoningText ?? ""}${delta.text}`;
+    }
+    else if (delta.kind === "text") {
+        live.streaming.textChars += delta.text.length;
+        live.streaming.visibleText = `${live.streaming.visibleText ?? ""}${delta.text}`;
+    }
+    else {
+        live.streaming.toolChars += delta.text.length;
+        live.streaming.toolFragment = `${live.streaming.toolFragment ?? ""}${delta.text}`;
+    }
+    if (delta.kind === "text")
+        live.streaming.tail = `${live.streaming.tail}${delta.text}`.slice(-maximumStreamTailCharacters);
+    live.streaming.receivedAt = Date.now();
+}

package/dist/node/runtime/config/AppPreferencesStore.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { chmod, mkdir, open, readFile, rename, stat, unlink, } from "node:fs/promises";
 import { join } from "node:path";
-import { defaultAppLocale, isAppLocale, } from "../../protocol/appPreferences.js";
+import { defaultAppLocale, defaultAppReadingPreferences, isAppLocale, isAppReadingPreferences, } from "../../protocol/appPreferences.js";
 const preferencesFileName = "preferences-v1.json";
 export class AppPreferencesStore {
     #configRoot;
@@ -15,11 +15,20 @@ export class AppPreferencesStore {
         await this.#mutationTail;
         return toView(await this.#readDocument());
     }
-    save(locale) {
+    save(update) {
         return this.#mutate(async () => {
-            if (!isAppLocale(locale))
-                throw new Error("Unsupported app locale");
-            const document = { schemaVersion: 1, locale };
+            if (Object.keys(update).length === 0 ||
+                Object.keys(update).some((key) => key !== "locale" && key !== "reading") ||
+                (update.locale !== undefined && !isAppLocale(update.locale)) ||
+                (update.reading !== undefined &&
+                    !isAppReadingPreferences(update.reading)))
+                throw new Error("Unsupported app preferences update");
+            const current = toView(await this.#readDocument());
+            const document = {
+                schemaVersion: 2,
+                locale: update.locale ?? current.locale,
+                reading: structuredClone(update.reading ?? current.reading),
+            };
             await this.#writeDocument(document);
             return toView(document);
         });
@@ -49,7 +58,11 @@ export class AppPreferencesStore {
             if (!isMissingFile(error))
                 throw error;
         }
-        return { schemaVersion: 1, locale: defaultAppLocale };
+        return {
+            schemaVersion: 2,
+            locale: defaultAppLocale,
+            reading: structuredClone(defaultAppReadingPreferences),
+        };
     }
     async #writeDocument(document) {
         await mkdir(this.#configRoot, { recursive: true, mode: 0o700 });
@@ -73,19 +86,35 @@ export class AppPreferencesStore {
     }
 }
 function validateDocument(value) {
-    if (typeof value !== "object" ||
-        value === null ||
-        Array.isArray(value) ||
-        !("schemaVersion" in value) ||
-        value.schemaVersion !== 1 ||
-        !("locale" in value) ||
-        !isAppLocale(value.locale) ||
-        Object.keys(value).some((key) => key !== "schemaVersion" && key !== "locale"))
-        throw new Error("App preferences file does not match the v1 schema");
-    return { schemaVersion: 1, locale: value.locale };
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("App preferences file does not match a supported schema");
+    if ("schemaVersion" in value &&
+        value.schemaVersion === 1 &&
+        "locale" in value &&
+        isAppLocale(value.locale) &&
+        Object.keys(value).every((key) => key === "schemaVersion" || key === "locale"))
+        return { schemaVersion: 1, locale: value.locale };
+    if ("schemaVersion" in value &&
+        value.schemaVersion === 2 &&
+        "locale" in value &&
+        isAppLocale(value.locale) &&
+        "reading" in value &&
+        isAppReadingPreferences(value.reading) &&
+        Object.keys(value).every((key) => key === "schemaVersion" || key === "locale" || key === "reading"))
+        return {
+            schemaVersion: 2,
+            locale: value.locale,
+            reading: structuredClone(value.reading),
+        };
+    throw new Error("App preferences file does not match a supported schema");
 }
 function toView(document) {
-    return { locale: document.locale };
+    return {
+        locale: document.locale,
+        reading: document.schemaVersion === 1
+            ? structuredClone(defaultAppReadingPreferences)
+            : structuredClone(document.reading),
+    };
 }
 function isMissingFile(error) {
     return error.code === "ENOENT";

package/dist/node/runtime/content/ContentTreeFingerprint.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+/** Stable identity for one complete portable content tree revision. */
+export function contentTreeFingerprint(files) {
+    return createHash("sha256")
+        .update(JSON.stringify([...files]
+        .map(({ path, contents, encoding }) => ({
+        path,
+        contents,
+        ...(encoding === undefined ? {} : { encoding }),
+    }))
+        .sort((left, right) => left.path === right.path ? 0 : left.path < right.path ? -1 : 1)))
+        .digest("hex");
+}

package/dist/node/runtime/content/ContentWorkspace.js

@@ -3,7 +3,7 @@ import { inflateRawSync } from "node:zlib";
 import { portableContentTreePathKey } from "../../protocol/contentTree.js";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 import { defaultContentWorkspaceLimits, maximumPortableContentArchiveBytes, } from "./ContentLimits.js";
-import { CurrentTreeContentLibrary, InvalidContentTreeError, } from "./CurrentTreeContentLibrary.js";
+import { CurrentTreeContentLibrary, InvalidContentTreeError, normalizeCurrentContentTreeFiles, } from "./CurrentTreeContentLibrary.js";
 import { inspectContentPackageCurrentTree, isContentPackageWorldDocumentPath, worldDocumentTextRequirement, } from "./FileNativeContentTree.js";
 export { CurrentTreeContentPackageBusyError, CurrentTreeContentLibraryError, CurrentTreeContentPackageNotFoundError, InvalidContentTreeError, } from "./CurrentTreeContentLibrary.js";
 const portableTreeUtf8Decoder = new TextDecoder("utf-8", {
@@ -36,11 +36,21 @@ export class ContentWorkspace {
         });
     }
     createCurrentTreeContentPackage() {
-        return this.#currentTreeLibrary.createPackage(minimalFileNativeContentScaffold(this.#locale()));
+        const locale = this.#locale();
+        return this.#currentTreeLibrary.createPackage({
+            title: defaultContentPackageTitle(locale, "new"),
+            files: minimalFileNativeContentScaffold(locale),
+        });
     }
     listCurrentTreeContentPackages() {
         return this.#currentTreeLibrary.listPackages();
     }
+    readPackageScriptGrants(localId) {
+        return this.#currentTreeLibrary.readScriptGrants(localId);
+    }
+    packageScriptPermissions(localId, enabled) {
+        return this.#currentTreeLibrary.scriptPermissions(localId, enabled);
+    }
     readCurrentTreeContentPackage(localId) {
         return this.#currentTreeLibrary.readPackage(localId);
     }
@@ -50,6 +60,14 @@ export class ContentWorkspace {
     inspectCurrentTreeContentPackage(files) {
         return inspectContentPackageCurrentTree(files);
     }
+    /**
+     * Apply the exact storage boundary used by current-tree publication without
+     * mutating Authority. Model-directed transactions use this after every write
+     * so one over-limit call cannot invalidate accepted sibling calls.
+     */
+    validateCurrentTreeContentPackage(files) {
+        normalizeCurrentContentTreeFiles(files, this.#limits);
+    }
     replaceCurrentTreeContentPackage(localId, files, options = {}) {
         return this.#currentTreeLibrary.replaceCurrentTree(localId, files, options);
     }
@@ -58,7 +76,11 @@ export class ContentWorkspace {
             const files = readPortableContentArchive(archive, this.#limits, options.signal);
             options.signal?.throwIfAborted();
             const currentTree = files.map(toCurrentTreeFile);
-            return this.#currentTreeLibrary.importPackage(currentTree, options.signal === undefined ? {} : { signal: options.signal });
+            return this.#currentTreeLibrary.importPackage({
+                title: options.title ??
+                    defaultContentPackageTitle(this.#locale(), "imported"),
+                files: currentTree,
+            }, options.signal === undefined ? {} : { signal: options.signal });
         });
     }
     copyCurrentTreeContentPackage(localId, options = {}) {
@@ -67,8 +89,8 @@ export class ContentWorkspace {
     deleteCurrentTreeContentPackage(localId, options = {}) {
         return this.#mutate(() => this.#currentTreeLibrary.deletePackage(localId, options));
     }
-    renameCurrentTreeContentPackage(localId, name, options = {}) {
-        return this.#mutate(() => this.#currentTreeLibrary.renamePackage(localId, name, options));
+    renameCurrentTreeContentPackage(localId, title, options = {}) {
+        return this.#mutate(() => this.#currentTreeLibrary.renamePackage(localId, title, options));
     }
     exportCurrentTreeContentPackage(localId, options = {}) {
         return this.#mutate(async () => {
@@ -83,7 +105,7 @@ export class ContentWorkspace {
             await crashProcessAtPortableContentExportEdge("after_archive_created");
             options.signal?.throwIfAborted();
             return {
-                fileName: `${portableArchiveBaseName(package_.displayName)}.zip`,
+                fileName: `${portableArchiveBaseName(package_.title)}.zip`,
                 archive,
             };
         });
@@ -103,6 +125,13 @@ export class ContentWorkspace {
         }
     }
 }
+function defaultContentPackageTitle(locale, source) {
+    if (locale === "zh-CN")
+        return source === "new" ? "待创作内容包" : "导入的内容包";
+    return source === "new"
+        ? "Untitled content package"
+        : "Imported content package";
+}
 /**
  * A new package is immediately valid and editable. These files are a protocol
  * scaffold, not a sample story: an authoring model replaces the placeholders
@@ -122,7 +151,7 @@ export function minimalFileNativeContentScaffold(locale = defaultAppLocale) {
                 contents: `$document:
   id: situation.current
   ref: current-situation
-  title: 待创作世界
+  title: 当前情境
   summary: 当前正在发生且接下来不能忘记的短期局面。
   aliases: []
 地点: 未设定
@@ -137,7 +166,7 @@ export function minimalFileNativeContentScaffold(locale = defaultAppLocale) {
             },
             {
                 path: "control/blocks/world.md",
-                contents: `<!-- 本文件只写这个世界特有的规则。通用裁决与状态维护判据由主持预设提供，每条游玩调用链都会加载，不要在这里重复。 -->
+                contents: `<!-- 本文件只写这个世界特有的规则。按当前预设实际启用的作者块核对通用裁决与状态维护判据，不要在这里重复。 -->
 
 # 本世界的题材与专属规则
 
@@ -171,7 +200,7 @@ export function minimalFileNativeContentScaffold(locale = defaultAppLocale) {
             contents: `$document:
   id: situation.current
   ref: current-situation
-  title: Unwritten world
+  title: Current situation
   summary: The short-term situation happening now that must not be forgotten next.
   aliases: []
 location: Not set
@@ -186,7 +215,7 @@ short_term_continuity: []
         },
         {
             path: "control/blocks/world.md",
-            contents: `<!-- Keep only rules unique to this world in this file. The host preset supplies general adjudication and state-maintenance criteria to every play call chain; do not repeat them here. -->
+            contents: `<!-- Keep only rules unique to this world in this file. Check the current preset’s actually enabled author blocks for general adjudication and state-maintenance criteria; do not repeat them here. -->
 
 # This world's genre and special rules
 
@@ -211,7 +240,7 @@ short_term_continuity: []
 }
 const defaultWorldFrame = `format: narraeon.world-frame/v1
 bindings:
-  currentSituation: situation.current
+  currentSituation: "@current-situation"
 instructions:
   - markdown: blocks/world.md
 context:
@@ -219,6 +248,7 @@ context:
   - slot: { kind: catalog, directory: locations, maxEntries: 24, required: false }
   - slot: { kind: catalog, directory: items, maxEntries: 24, required: false }
   - slot: { kind: catalog, directory: rules, maxEntries: 24, required: false }
+  - slot: { kind: catalog, directory: events, maxEntries: 24, required: false }
   - slot: { kind: current_situation }
   - slot: { kind: history, recent: 2 }
   - slot: { kind: additional_materials }
@@ -295,8 +325,8 @@ function createPortableContentArchive(files) {
     end.writeUInt32LE(localOffset, 16);
     return Buffer.concat([...localRecords, centralDirectory, end]);
 }
-function portableArchiveBaseName(displayName) {
-    const normalized = displayName
+function portableArchiveBaseName(title) {
+    const normalized = title
         .normalize("NFKC")
         .replaceAll(/[^\p{L}\p{N}._-]+/gu, "-")
         .replaceAll(/^[.-]+|[.-]+$/gu, "")