narraeon 0.4.0 → 0.5.0

package/dist/node/protocol/appPreferences.js

@@ -1,5 +1,30 @@
 export const appLocales = ["en", "zh-CN"];
+export const readingDensities = ["compact", "standard", "relaxed"];
 export const defaultAppLocale = "en";
+export const defaultAppReadingPreferences = {
+    density: "compact",
+    fontSize: 17,
+    lineHeight: 1.7,
+    letterSpacing: 0.01,
+    measure: 48,
+};
 export function isAppLocale(value) {
     return appLocales.includes(value);
 }
+export function isAppReadingPreferences(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (Object.keys(candidate).length === 5 &&
+        readingDensities.includes(candidate.density) &&
+        isNumberInRange(candidate.fontSize, 15, 24) &&
+        isNumberInRange(candidate.lineHeight, 1.4, 2.4) &&
+        isNumberInRange(candidate.letterSpacing, 0, 0.12) &&
+        isNumberInRange(candidate.measure, 32, 72));
+}
+function isNumberInRange(value, minimum, maximum) {
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        value >= minimum &&
+        value <= maximum);
+}

package/dist/node/protocol/conversationObservation.js

@@ -0,0 +1,67 @@
+/** Only append-only live text uses deltas. Every other transition resets from
+ * the Runtime projection, including settlement, context changes and recovery. */
+export function conversationUpdate(previous, next) {
+    if (previous?.kind === "play" &&
+        next.kind === "play" &&
+        previous.extensionsRevision === next.extensionsRevision &&
+        previous.value !== null &&
+        next.value !== null &&
+        previous.value.chainId === next.value.chainId) {
+        const candidate = structuredClone(previous.value);
+        const deltas = [];
+        for (const event of next.value.events) {
+            const old = candidate.events.find((item) => item.id === event.id);
+            if (event.kind !== "assistant" ||
+                event.status !== "streaming" ||
+                old?.kind !== "assistant")
+                continue;
+            for (const field of ["text", "reasoning", "toolFragment"]) {
+                const before = old[field] ?? "";
+                const after = event[field];
+                if (!after?.startsWith(before))
+                    continue;
+                if (after !== before)
+                    deltas.push({
+                        eventId: event.id,
+                        field,
+                        text: after.slice(before.length),
+                    });
+                old[field] = after;
+            }
+        }
+        candidate.updatedAt = next.value.updatedAt;
+        if (next.value.activeInvocation === undefined)
+            delete candidate.activeInvocation;
+        else
+            candidate.activeInvocation = next.value.activeInvocation;
+        if (JSON.stringify(candidate) === JSON.stringify(next.value)) {
+            return {
+                kind: "play_delta",
+                chainId: candidate.chainId,
+                updatedAt: candidate.updatedAt,
+                progress: candidate.activeInvocation ?? null,
+                deltas,
+            };
+        }
+    }
+    return { kind: "snapshot", value: next };
+}
+export function applyConversationUpdate(previous, update) {
+    if (update.kind === "snapshot")
+        return update.value;
+    if (previous?.kind !== "play" || previous.value?.chainId !== update.chainId)
+        throw new Error("Conversation observation needs a fresh snapshot");
+    const value = structuredClone(previous.value);
+    for (const delta of update.deltas) {
+        const event = value.events.find((item) => item.id === delta.eventId);
+        if (event?.kind !== "assistant" || event.status !== "streaming")
+            throw new Error("Conversation observation has an unknown live event");
+        event[delta.field] = `${event[delta.field] ?? ""}${delta.text}`;
+    }
+    value.updatedAt = update.updatedAt;
+    if (update.progress === null)
+        delete value.activeInvocation;
+    else
+        value.activeInvocation = update.progress;
+    return { ...previous, kind: "play", value };
+}

package/dist/node/protocol/v1.js

@@ -19,12 +19,16 @@ export function parseV1Envelope(value) {
     return value;
 }
 const requiredFields = {
-    "preferences.save": { locale: "string" },
+    "preferences.save": {},
     "model.save": { connection: "object" },
     "model.copy": { connectionId: "string", name: "string" },
     "model.select": { connectionId: "string" },
     "model.delete": { connectionId: "string" },
     "model.models": { provider: "string", baseUrl: "string" },
+    "content.scripts.read": { packageId: "string" },
+    "content.scripts.set": { packageId: "string", enabled: "boolean" },
+    "world.package-scripts.read": { worldId: "string" },
+    "world.package-scripts.set": { worldId: "string", enabled: "boolean" },
     "content.read": { packageId: "string" },
     "content.replace": { packageId: "string", files: "array" },
     "content.copy": { packageId: "string" },
@@ -32,25 +36,31 @@ const requiredFields = {
     "content.rename": { packageId: "string", name: "string" },
     "content.import": { archiveBase64: "string" },
     "content.export": { packageId: "string" },
-    "setting-improvement.start": {
-        improvementId: "string",
+    "setting-improvement.read": { packageId: "string" },
+    "setting-improvement.preview": { packageId: "string" },
+    "setting-improvement.status": { packageId: "string" },
+    "setting-improvement.overview": { packageId: "string" },
+    "setting-improvement.session.read": {
         packageId: "string",
-        goal: "string",
-        mode: "string",
-        contextPaths: "array",
+        sessionId: "string",
     },
-    "setting-improvement.confirm": { improvementId: "string" },
-    "setting-improvement.progress": { improvementId: "string" },
-    "setting-improvement.revise-plan": {
-        improvementId: "string",
-        feedback: "string",
+    "setting-improvement.session.delete": {
+        packageId: "string",
+        sessionId: "string",
+    },
+    "setting-improvement.rollback": {
+        packageId: "string",
+        sessionId: "string",
+        changeSetId: "string",
+        path: "string",
     },
-    "setting-improvement.revise-candidate": {
-        improvementId: "string",
-        feedback: "string",
+    "setting-improvement.message": {
+        packageId: "string",
+        requestId: "string",
+        message: "string",
+        continuation: "object",
     },
-    "setting-improvement.apply": { improvementId: "string" },
-    "setting-improvement.discard": { improvementId: "string" },
+    "setting-improvement.cancel": { sessionId: "string" },
     "play.create": { name: "string" },
     "play.copy": { presetId: "string" },
     "play.save": { presetId: "string", name: "string", files: "object" },
@@ -82,6 +92,43 @@ const requiredFields = {
     "world.control-draft.save": { worldId: "string", files: "array" },
     "world.control-draft.preview": { worldId: "string" },
     "world.control-draft.apply": { worldId: "string" },
+    "world.revision.open": { worldId: "string" },
+    "world.revision.overview": { worldId: "string" },
+    "world.revision.preview": { worldId: "string" },
+    "world.revision.status": { worldId: "string" },
+    "world.revision.session.read": {
+        worldId: "string",
+        sessionId: "string",
+    },
+    "world.revision.session.delete": {
+        worldId: "string",
+        sessionId: "string",
+    },
+    "world.revision.message": {
+        worldId: "string",
+        requestId: "string",
+        message: "string",
+        continuation: "object",
+    },
+    "world.revision.cancel": { sessionId: "string" },
+    "world.revision.files.replace": {
+        worldId: "string",
+        epochId: "string",
+        expectedRevision: "string",
+        files: "array",
+    },
+    "world.revision.rollback": {
+        worldId: "string",
+        epochId: "string",
+        changeSetId: "string",
+        path: "string",
+    },
+    "world.revision.apply": {
+        worldId: "string",
+        epochId: "string",
+        expectedRevision: "string",
+    },
+    "world.revision.discard": { worldId: "string", epochId: "string" },
     "world.derive": {
         operationId: "string",
         sourceWorldId: "string",
@@ -94,6 +141,7 @@ const requiredFields = {
         eventId: "number",
         replacementExchangeId: "string",
         replacementText: "string",
+        continuation: "string",
     },
     "play.chain.start": {
         worldId: "string",
@@ -119,7 +167,10 @@ const requiredFields = {
         chainId: "string",
         eventId: "number",
     },
+    "world.play-context.read": { worldId: "string" },
     "world.surface.read": { worldId: "string", surface: "string" },
+    "world.extensions.read": { worldId: "string" },
+    "world.extensions.set": { worldId: "string", key: "string", value: "string" },
     "world.play-decorations.read": { worldId: "string" },
     "correction.begin": { worldId: "string", operationId: "string" },
     "correction.read": { candidateId: "string", document: "string" },
@@ -153,17 +204,33 @@ function validateRequestFields(request) {
         if (!valid || (kind === "string" && value === "" && !allowsEmptyString))
             throw new V1ProtocolError("invalid_request", `${String(request.type)}.${field} is invalid`);
     }
-    if (request.type === "preferences.save" &&
-        request.locale !== "en" &&
-        request.locale !== "zh-CN")
-        throw new V1ProtocolError("invalid_request", "preferences.save.locale must be en or zh-CN");
+    if (request.type === "world.extensions.set" &&
+        !["on", "off", "default"].includes(String(request.value)))
+        throw new V1ProtocolError("invalid_request", "Invalid world extension choice");
+    if (request.type === "preferences.save") {
+        if ((request.locale === undefined && request.reading === undefined) ||
+            Object.keys(request).some((key) => key !== "type" && key !== "locale" && key !== "reading"))
+            throw new V1ProtocolError("invalid_request", "preferences.save must update locale or reading preferences");
+        if (request.locale !== undefined &&
+            request.locale !== "en" &&
+            request.locale !== "zh-CN")
+            throw new V1ProtocolError("invalid_request", "preferences.save.locale must be en or zh-CN");
+        if (request.reading !== undefined &&
+            !isValidReadingPreferences(request.reading))
+            throw new V1ProtocolError("invalid_request", "preferences.save.reading is invalid");
+    }
     if (request.type === "content.import") {
         const archiveBase64 = request.archiveBase64;
         if (archiveBase64.length > maxPortableContentArchiveBase64Characters ||
             archiveBase64.length % 4 !== 0 ||
             !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(archiveBase64))
             throw new V1ProtocolError("invalid_request", "content.import.archiveBase64 is not a supported content-package ZIP");
-        const unexpectedFields = Object.keys(request).filter((field) => field !== "type" && field !== "archiveBase64");
+        if (request.title !== undefined &&
+            (typeof request.title !== "string" ||
+                request.title.trim().length === 0 ||
+                !/^[^\r\n]{1,160}$/u.test(request.title.trim())))
+            throw new V1ProtocolError("invalid_request", "content.import.title is invalid");
+        const unexpectedFields = Object.keys(request).filter((field) => field !== "type" && field !== "archiveBase64" && field !== "title");
         if (unexpectedFields.length > 0)
             throw new V1ProtocolError("invalid_request", `content.import contains unsupported fields: ${unexpectedFields.join(", ")}`);
         return;
@@ -194,6 +261,17 @@ function validateRequestFields(request) {
         !isRecord(request.structure))
         throw new V1ProtocolError("invalid_request", "play.save.structure must be a structured map");
     if (request.type === "play.workbench.read") {
+        if (request.draft !== undefined &&
+            (!isRecord(request.draft) ||
+                !isRecord(request.draft.files) ||
+                !Object.values(request.draft.files).every((value) => typeof value === "string") ||
+                (request.draft.structure !== undefined &&
+                    !isRecord(request.draft.structure)) ||
+                request.presetId === undefined))
+            throw new V1ProtocolError("invalid_request", "play.workbench.read.draft requires presetId, text files and an optional structured map");
+        if (request.worldId !== undefined &&
+            (typeof request.worldId !== "string" || request.worldId === ""))
+            throw new V1ProtocolError("invalid_request", "play.workbench.read.worldId is invalid");
         if (request.presetId !== undefined &&
             (typeof request.presetId !== "string" || request.presetId === ""))
             throw new V1ProtocolError("invalid_request", "play.workbench.read.presetId is invalid");
@@ -230,18 +308,53 @@ function validateRequestFields(request) {
     if (request.type === "play.timeline.detail" &&
         (!Number.isSafeInteger(request.eventId) || Number(request.eventId) < 1))
         throw new V1ProtocolError("invalid_request", "play.timeline.detail.eventId is invalid");
+    if (request.type === "play.chain.revise-player" &&
+        request.continuation !== "continue_context" &&
+        request.continuation !== "fresh_context")
+        throw new V1ProtocolError("invalid_request", "play.chain.revise-player.continuation is invalid");
     if (request.type === "world.surface.read" &&
         request.surface !== "state" &&
         request.surface !== "control" &&
         request.surface !== "history" &&
         request.surface !== "runtime")
         throw new V1ProtocolError("invalid_request", "world.surface.read.surface is invalid");
-    if (request.type !== "setting-improvement.start")
-        return;
-    if (request.mode !== "plan_first" && request.mode !== "direct_candidate")
-        throw new V1ProtocolError("invalid_request", "setting-improvement.start.mode is invalid");
-    if (!request.contextPaths.every((path) => typeof path === "string" && path.length > 0))
-        throw new V1ProtocolError("invalid_request", "setting-improvement.start.contextPaths is invalid");
+    if ((request.type === "setting-improvement.preview" ||
+        request.type === "world.revision.preview") &&
+        request.sessionId !== undefined &&
+        (typeof request.sessionId !== "string" || request.sessionId.length === 0))
+        throw new V1ProtocolError("invalid_request", "Authoring preview sessionId is invalid");
+    if (request.type === "world.revision.status" &&
+        request.sessionId !== undefined &&
+        (typeof request.sessionId !== "string" || request.sessionId.length === 0))
+        throw new V1ProtocolError("invalid_request", "world.revision.status.sessionId is invalid");
+    if (request.type === "setting-improvement.message" ||
+        request.type === "world.revision.message") {
+        const continuation = request.continuation;
+        if (!isRecord(continuation) ||
+            (continuation.kind !== "fresh_context" &&
+                continuation.kind !== "continue_context") ||
+            (continuation.kind === "continue_context" &&
+                typeof continuation.sessionId !== "string") ||
+            (continuation.kind === "fresh_context" && "sessionId" in continuation))
+            throw new V1ProtocolError("invalid_request", `${request.type}.continuation is invalid`);
+    }
+    if (request.type === "setting-improvement.rollback" &&
+        (typeof request.changeSetId !== "string" ||
+            !/^change-set:(0|[1-9][0-9]*)$/u.test(request.changeSetId)))
+        throw new V1ProtocolError("invalid_request", "setting-improvement.rollback.changeSetId is invalid");
+    if ((request.type === "world.revision.files.replace" ||
+        request.type === "world.revision.rollback" ||
+        request.type === "world.revision.apply" ||
+        request.type === "world.revision.discard") &&
+        (typeof request.epochId !== "string" ||
+            !/^revision-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(request.epochId)))
+        throw new V1ProtocolError("invalid_request", `${request.type}.epochId is invalid`);
+    if (request.type === "world.revision.rollback" &&
+        (typeof request.changeSetId !== "string" ||
+            !/^change-set:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(request.changeSetId) ||
+            typeof request.path !== "string" ||
+            request.path.length === 0))
+        throw new V1ProtocolError("invalid_request", "world.revision.rollback target is invalid");
 }
 const requestTypes = new Set([
     "workspace.read",
@@ -254,6 +367,10 @@ const requestTypes = new Set([
     "model.delete",
     "model.models",
     "content.create",
+    "content.scripts.read",
+    "content.scripts.set",
+    "world.package-scripts.read",
+    "world.package-scripts.set",
     "content.read",
     "content.replace",
     "content.copy",
@@ -261,13 +378,15 @@ const requestTypes = new Set([
     "content.rename",
     "content.import",
     "content.export",
-    "setting-improvement.start",
-    "setting-improvement.confirm",
-    "setting-improvement.progress",
-    "setting-improvement.revise-plan",
-    "setting-improvement.revise-candidate",
-    "setting-improvement.apply",
-    "setting-improvement.discard",
+    "setting-improvement.read",
+    "setting-improvement.preview",
+    "setting-improvement.status",
+    "setting-improvement.overview",
+    "setting-improvement.session.read",
+    "setting-improvement.session.delete",
+    "setting-improvement.rollback",
+    "setting-improvement.message",
+    "setting-improvement.cancel",
     "play.read",
     "play.create",
     "play.copy",
@@ -292,6 +411,18 @@ const requestTypes = new Set([
     "world.control-draft.save",
     "world.control-draft.preview",
     "world.control-draft.apply",
+    "world.revision.open",
+    "world.revision.overview",
+    "world.revision.preview",
+    "world.revision.status",
+    "world.revision.session.read",
+    "world.revision.session.delete",
+    "world.revision.message",
+    "world.revision.cancel",
+    "world.revision.files.replace",
+    "world.revision.rollback",
+    "world.revision.apply",
+    "world.revision.discard",
     "world.derive",
     "play.chain.revise-player",
     "play.chain.start",
@@ -300,7 +431,10 @@ const requestTypes = new Set([
     "play.chain.inspect",
     "play.timeline.page",
     "play.timeline.detail",
+    "world.play-context.read",
     "world.surface.read",
+    "world.extensions.read",
+    "world.extensions.set",
     "world.play-decorations.read",
     "correction.begin",
     "correction.read",
@@ -313,3 +447,21 @@ const requestTypes = new Set([
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isValidReadingPreferences(value) {
+    if (!isRecord(value))
+        return false;
+    return (Object.keys(value).length === 5 &&
+        (value.density === "compact" ||
+            value.density === "standard" ||
+            value.density === "relaxed") &&
+        isFiniteRange(value.fontSize, 15, 24) &&
+        isFiniteRange(value.lineHeight, 1.4, 2.4) &&
+        isFiniteRange(value.letterSpacing, 0, 0.12) &&
+        isFiniteRange(value.measure, 32, 72));
+}
+function isFiniteRange(value, minimum, maximum) {
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        value >= minimum &&
+        value <= maximum);
+}

package/dist/node/protocol/worldExtensions.js

@@ -0,0 +1,16 @@
+export function isWorldExtensionControl(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "key" in value &&
+        typeof value.key === "string" &&
+        value.key.length > 0 &&
+        "generation" in value &&
+        Number.isSafeInteger(value.generation) &&
+        Number(value.generation) >= 0 &&
+        Object.keys(value).length === 2);
+}
+export function requestControlKey(presetId, requestId) {
+    return requestId.startsWith("package:")
+        ? requestId
+        : `preset:${presetId}:request:${requestId}`;
+}

package/dist/node/protocol/worldMaintenance.js

@@ -0,0 +1,77 @@
+export function isWorldPromptMaintenance(value) {
+    if (!record(value) ||
+        value.unit !== "utf8_bytes" ||
+        (value.unavailableReason !== undefined &&
+            typeof value.unavailableReason !== "string") ||
+        ![
+            "worldMaterialsBytes",
+            "checkpointHistoryBytes",
+            "authorInstructionBytes",
+            "runtimeInstructionBytes",
+            "toolDefinitionBytes",
+        ].every((key) => count(value[key])) ||
+        !Array.isArray(value.documents) ||
+        !Array.isArray(value.slots))
+        return false;
+    return (value.documents.every((item) => record(item) &&
+        typeof item.shortRef === "string" &&
+        typeof item.title === "string" &&
+        count(item.bodyBytes) &&
+        count(item.injectedBytes) &&
+        ["world_origin", "document_creation", "unavailable"].includes(String(item.baselineKind)) &&
+        nullableCount(item.baselineBytes) &&
+        nullableNumber(item.growthBytes) &&
+        nullableNumber(item.growthRatio) &&
+        nullableCount(item.advisoryBytes) &&
+        typeof item.overAdvisory === "boolean" &&
+        position(item.lastBodyWrite) &&
+        position(item.lastMetadataWrite) &&
+        (item.observedContexts === undefined || count(item.observedContexts)) &&
+        count(item.bodyChangedContexts) &&
+        count(item.metadataChangedContexts)) &&
+        value.slots.every((slot) => record(slot) &&
+            typeof slot.id === "string" &&
+            count(slot.bytes) &&
+            nullableCount(slot.advisoryBytes) &&
+            typeof slot.overAdvisory === "boolean" &&
+            Array.isArray(slot.documents) &&
+            slot.documents.every((ref) => typeof ref === "string")));
+}
+function position(value) {
+    return (value === null ||
+        (record(value) &&
+            ["world_origin", "play", "correction", "history"].includes(String(value.kind)) &&
+            nullableCount(value.context) &&
+            count(value.round) &&
+            (value.worldTime === null || typeof value.worldTime === "string")));
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function count(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function nullableCount(value) {
+    return value === null || count(value);
+}
+function nullableNumber(value) {
+    return (value === null || (typeof value === "number" && Number.isFinite(value)));
+}
+/** Display only recorded provenance; a write position is not character knowledge. */
+export function worldWritePositionText(position, locale) {
+    const zh = locale === "zh-CN";
+    if (position === null)
+        return zh ? "未记录" : "Not recorded";
+    const place = position.kind === "world_origin"
+        ? zh
+            ? "世界创建时"
+            : "World creation"
+        : position.kind === "play" && position.context !== null
+            ? zh
+                ? `上下文 ${position.context} · 第 ${position.round} 回合`
+                : `Context ${position.context} · round ${position.round}`
+            : zh
+                ? `${position.kind === "correction" ? "连续性修订" : "历史提交"} · 玩家输入位置 ${position.round}`
+                : `${position.kind === "correction" ? "Continuity correction" : "History commit"} · player input position ${position.round}`;
+    return `${place} · ${zh ? "写入时世界时间" : "World time at write"}: ${position.worldTime ?? (zh ? "未记录" : "not recorded")}`;
+}

package/dist/node/protocol/worldPromptDiagnostics.js

@@ -0,0 +1 @@
+export {};

package/dist/node/runtime/ConversationChanges.js

@@ -0,0 +1,24 @@
+/** Observation failure never participates in a Runtime mutation. */
+export class ConversationChanges {
+    #listeners = new Map();
+    subscribe(scope, listener) {
+        const listeners = this.#listeners.get(scope) ?? new Set();
+        listeners.add(listener);
+        this.#listeners.set(scope, listeners);
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0)
+                this.#listeners.delete(scope);
+        };
+    }
+    publish(scope, durable = true) {
+        for (const listener of this.#listeners.get(scope) ?? []) {
+            try {
+                listener(durable);
+            }
+            catch {
+                /* Observers cannot affect settlement. */
+            }
+        }
+    }
+}