narraeon 0.5.1 → 0.5.3

package/dist/node/runtime/play/PlayDocumentTools.js

@@ -1,3 +1,6 @@
+import { HistoryQuery, historyInputs } from "../history/HistoryQuery.js";
+import { renderHistoryResult } from "../history/HistoryRendering.js";
+import { stateDirectoryHandle, parseStateDirectoryHandle, } from "../world/StateDirectoryHandles.js";
 import { renderDocumentWritePosition } from "../prompt/WorldMaintenanceReport.js";
 import { createHash } from "node:crypto";
 import { stringify } from "yaml";
@@ -113,19 +116,61 @@ export class FileNativePlayDocuments {
             documents,
         };
     }
-    execute(call, history) {
+    execute(call, history, options = {}) {
+        let historyQuery;
+        const query = () => (historyQuery ??= new HistoryQuery(options.historyScope ?? "local-document-context", historyInputs(history)));
+        const render = (result) => renderHistoryResult(result, options.locale ?? "en");
+        const legacy = options.legacyHistoryTools !== false;
+        const args = call.arguments;
+        if (call.name === "history_search")
+            return render(query().search(args));
+        if (call.name === "history_read")
+            return render(query().read(args));
+        if (call.name === "history_list") {
+            return render(legacy && record(args) && args.order !== undefined
+                ? query().legacyList(args, "history_list")
+                : query().list(args));
+        }
+        if (call.name === "context_list" &&
+            record(args) &&
+            args.source === "history") {
+            const { source: _source, ...parameters } = args;
+            void _source;
+            return legacy
+                ? render(query().legacyList(parameters, "context_list"))
+                : toolFailure("Use history_list for committed history.");
+        }
+        if (call.name === "context_search" &&
+            record(args) &&
+            args.source === "history") {
+            const { source: _source, ...parameters } = args;
+            void _source;
+            return legacy
+                ? render(query().legacySearch(parameters))
+                : toolFailure("Use history_search for committed history.");
+        }
+        if (call.name === "context_read" &&
+            record(args) &&
+            typeof args.ref === "string" &&
+            /^@?history-message-/u.test(args.ref)) {
+            if (!legacy)
+                return toolFailure("Use history_read with refs supplied in injections or tool results.");
+            if (!hasOnlyToolKeys(args, ["ref", "cursor", "maxBytes"]))
+                return toolFailure("Legacy context_read requires ref and accepts only obsolete cursor/maxBytes in addition.");
+            return renderHistoryResult(query().read({
+                ref: args.ref.startsWith("@") ? args.ref : `@${args.ref}`,
+            }), options.locale ?? "en", true);
+        }
         if (call.name === "context_search")
-            return executeContextSearch(this.#candidate.snapshot, history, call.arguments);
+            return executeContextSearch(this.#candidate.snapshot, call.arguments);
         if (call.name === "state_list")
-            return executeStateList(this.#candidate.snapshot, history, call.arguments, this.#declaredDirectories);
-        if (call.name === "history_list")
-            return executeHistoryList(this.#candidate.snapshot, history, call.arguments);
+            return executeStateList(this.#candidate.snapshot, call.arguments, this.#declaredDirectories);
         // Frozen contexts created before runtime-tools-v5 retain this exact name
         // and argument shape. New contexts never advertise it.
         if (call.name === "context_list")
-            return executeContextList(this.#candidate.snapshot, history, call.arguments, this.#declaredDirectories);
+            return executeContextList(this.#candidate.snapshot, call.arguments, this.#declaredDirectories);
         if (call.name === "context_read") {
-            const result = executeContextRead(this.#candidate.snapshot, history, call.arguments);
+            const result = executeContextRead(this.#candidate.snapshot, call.arguments);
             authorizeToolRead(this.#reads, this.#candidate.snapshot, result);
             const ref = result.readAuthorization?.shortRef;
             if (ref !== undefined && result.markdown !== undefined)
@@ -518,7 +563,7 @@ function toolFailure(message, failureKind = "protocol") {
         failureKind,
     };
 }
-function executeContextSearch(snapshot, history, args) {
+function executeContextSearch(snapshot, args) {
     if (!record(args) ||
         !hasOnlyToolKeys(args, [
             "source",
@@ -559,38 +604,7 @@ function executeContextSearch(snapshot, history, args) {
                 ? { cursor: args.cursor }
                 : {}),
         });
-    const source = history.map(({ path, contents }) => [
-        historyRef(path),
-        contents,
-        [`history-commit-${path.split("-")[0] ?? ""}`],
-    ]);
-    const normalizedQuery = normalizeSearch(query, caseSensitive);
-    const within = typeof args.within === "string" ? args.within.replace(/^@/u, "") : null;
-    const allHits = source.filter(([ref, text, parentScopes]) => (within === null || ref === within || parentScopes.includes(within)) &&
-        normalizeSearch(text, caseSensitive).includes(normalizedQuery));
-    const scope = JSON.stringify({
-        kind: "search",
-        source: "history",
-        query,
-        caseSensitive,
-        within: args.within ?? null,
-        limit,
-    });
-    const offset = parseCursor(args.cursor, scope);
-    if (offset === null)
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nThe cursor does not match the search criteria or endpoint.",
-        };
-    const hits = allHits.slice(offset, offset + limit);
-    const complete = offset + hits.length >= allHits.length;
-    const renderedHits = hits
-        .map(([ref, text]) => `- @${ref}\n  Exact-match excerpt:\n${quoteMarkdown(snippet(text, query), "  ")}`)
-        .join("\n");
-    return {
-        ok: true,
-        markdown: `# Literal search\n\nScope: history${args.within === undefined ? "" : ` · ${args.within}`}\nNormalization: ${caseSensitive ? "original text" : "NFKC + case folding"}\nTotal matches: ${allHits.length}\n${renderedHits || "Zero literal matches do not prove that the fact is absent from the world."}\n\n---\nThis page: ${offset}..${offset + hits.length} / ${allHits.length} matches\nComplete: ${complete ? "yes" : "no"}${complete ? "" : `\nNext-page cursor: ${cursorFor(scope, offset + hits.length)}`}`,
-    };
+    return toolFailure("Use history_search for committed history.");
 }
 function searchState(snapshot, input) {
     const within = parseStateSearchScope(input.within);
@@ -632,37 +646,6 @@ function parseStateSearchScope(handle) {
         ? invalidStateHandle
         : { document: { shortRef: document[1] } };
 }
-function stateDirectoryHandle(directory) {
-    if (directory === "")
-        return "@dir-/";
-    const encoded = directory.split("/").map(encodeURIComponent).join("/");
-    return `@dir-/${encoded}`;
-}
-function parseStateDirectoryHandle(handle) {
-    if (handle === "@dir-/")
-        return "";
-    if (!handle.startsWith("@dir-/") || handle.length === "@dir-/".length)
-        return null;
-    try {
-        const directory = handle
-            .slice("@dir-/".length)
-            .split("/")
-            .map(decodeURIComponent)
-            .join("/");
-        if (directory
-            .split("/")
-            .some((segment) => segment === "" ||
-            segment === "." ||
-            segment === ".." ||
-            segment.includes("\\")) ||
-            stateDirectoryHandle(directory) !== handle)
-            return null;
-        return directory;
-    }
-    catch {
-        return null;
-    }
-}
 function validStateDirectory(directory) {
     if (directory.length === 0)
         return false;
@@ -682,7 +665,7 @@ function knownStateDirectory(snapshot, directory, declaredDirectories) {
     const logicalPrefix = `${snapshot.logicalRoot}/${relativePrefix}`;
     return snapshot.files.some(({ path }) => path.startsWith(logicalPrefix));
 }
-function executeStateList(snapshot, history, args, declaredDirectories) {
+function executeStateList(snapshot, args, declaredDirectories) {
     if (!record(args) ||
         !hasOnlyToolKeys(args, ["parent", "cursor", "limit"]) ||
         typeof args.parent !== "string" ||
@@ -693,21 +676,9 @@ function executeStateList(snapshot, history, args, declaredDirectories) {
             ok: false,
             markdown: "# Runtime argument error\n\nstate_list requires an @dir-* parent returned by Runtime and accepts only cursor and limit in addition; use history_list for committed history.",
         };
-    return executeContextList(snapshot, history, { ...args, source: "state" }, declaredDirectories);
+    return executeContextList(snapshot, { ...args, source: "state" }, declaredDirectories);
 }
-function executeHistoryList(snapshot, history, args) {
-    if (!record(args) ||
-        !hasOnlyToolKeys(args, ["order", "cursor", "limit"]) ||
-        (args.order !== "newest_first" && args.order !== "oldest_first") ||
-        (args.limit !== undefined && typeof args.limit !== "number") ||
-        !validOptionalCursor(args.cursor))
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nhistory_list requires newest_first or oldest_first order and accepts only cursor and limit in addition; use state_list for state directories.",
-        };
-    return executeContextList(snapshot, history, { ...args, source: "history" });
-}
-function executeContextList(snapshot, history, args, declaredDirectories = []) {
+function executeContextList(snapshot, args, declaredDirectories = []) {
     if (!record(args) || (args.source !== "state" && args.source !== "history"))
         return {
             ok: false,
@@ -774,31 +745,9 @@ function executeContextList(snapshot, history, args, declaredDirectories = []) {
             markdown: `# Directory listing\n\nScope: state · ${parent}\nCoverage: ${result.coverage.status === "complete" ? "complete" : "partial"}\n${entries.join("\n") || "(empty)"}\n\n---\nThis page: ${result.page.start}..${result.page.end} / ${result.page.total} items\nComplete: ${result.page.complete ? "yes" : "no"}${result.page.nextCursor === null ? "" : `\nNext-page cursor: ${result.page.nextCursor}`}`,
         };
     }
-    const entries = [...history]
-        .sort((a, b) => (args.order ?? "newest_first") === "oldest_first"
-        ? a.path.localeCompare(b.path)
-        : b.path.localeCompare(a.path))
-        .map(({ path, contents }) => `- @${historyRef(path)}, ${Buffer.byteLength(contents, "utf8")} bytes`);
-    const scope = JSON.stringify({
-        kind: "list",
-        source: "history",
-        order: args.order,
-        limit,
-    });
-    const offset = parseCursor(args.cursor, scope);
-    if (offset === null)
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nThe cursor does not match the listing criteria or endpoint.",
-        };
-    const page = entries.slice(offset, offset + limit);
-    const complete = offset + page.length >= entries.length;
-    return {
-        ok: true,
-        markdown: `# Directory listing\n\nScope: history · ${String(args.order)}\n${page.join("\n") || "(empty)"}\n\n---\nThis page: ${offset}..${offset + page.length} / ${entries.length} items\nComplete: ${complete ? "yes" : "no"}${complete ? "" : `\nNext-page cursor: ${cursorFor(scope, offset + page.length)}`}`,
-    };
+    return toolFailure("Use history_list for committed history.");
 }
-function executeContextRead(snapshot, history, args) {
+function executeContextRead(snapshot, args) {
     if (!record(args) ||
         // Frozen contexts created before complete exact reads still advertise
         // cursor/maxBytes. Accept and ignore those obsolete arguments so an
@@ -809,13 +758,6 @@ function executeContextRead(snapshot, history, args) {
             ok: false,
             markdown: "# Runtime argument error\n\nA stable ref returned by list or search is required.",
         };
-    const historyRefValue = args.ref.replace(/^@/u, "");
-    const historyEntry = history.find(({ path }) => historyRef(path) === historyRefValue);
-    if (historyEntry !== undefined)
-        return {
-            ok: true,
-            markdown: `# Exact read @${historyRefValue}\n\n${historyEntry.contents}\n\n---\nSource: @${historyRefValue}\nComplete: yes`,
-        };
     const handle = parseStateReadHandle(args.ref);
     if (handle === null)
         return {
@@ -956,45 +898,6 @@ function hasOnlyToolKeys(value, allowed) {
 function validOptionalCursor(value) {
     return value === undefined || value === null || typeof value === "string";
 }
-function normalizeSearch(value, caseSensitive) {
-    const normalized = value.normalize("NFKC");
-    return caseSensitive ? normalized : normalized.toLocaleLowerCase("und");
-}
-function snippet(text, query) {
-    const position = text
-        .normalize("NFKC")
-        .toLocaleLowerCase("und")
-        .indexOf(query.normalize("NFKC").toLocaleLowerCase("und"));
-    const start = Math.max(0, position - 120);
-    return text.slice(start, start + 240).replace(/\s+/gu, " ");
-}
-function historyRef(path) {
-    return `history-message-${path.replace(/\.md$/u, "")}`;
-}
-function cursorFor(scope, offset) {
-    return Buffer.from(JSON.stringify({
-        scope: createHash("sha256").update(scope).digest("hex"),
-        offset,
-    }), "utf8").toString("base64url");
-}
-function parseCursor(cursor, scope) {
-    if (cursor === undefined || cursor === null)
-        return 0;
-    if (typeof cursor !== "string")
-        return null;
-    try {
-        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
-        if (!record(value) ||
-            value.scope !== createHash("sha256").update(scope).digest("hex") ||
-            !Number.isSafeInteger(value.offset) ||
-            Number(value.offset) < 0)
-            return null;
-        return Number(value.offset);
-    }
-    catch {
-        return null;
-    }
-}
 export function parseNarrative(args) {
     if (!record(args) ||
         typeof args.text !== "string" ||

package/dist/node/runtime/play/PlayTraceRetention.js

@@ -0,0 +1,264 @@
+import { FileNativePlayDocuments, } from "./PlayDocumentTools.js";
+import { currentPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
+import { isPlayerRoundMarker, playerInputAppend } from "./PlayContinuity.js";
+import { PlayCallChainError } from "./PlayCallChainError.js";
+/**
+ * Prepare the selected player's prefix at the existing pre-commit seam.
+ * Endpoint reads, revision submission and publication belong to the operation.
+ */
+export function preparePlayerRevisionTrace(source, eventIndex) {
+    const prefix = structuredClone(source.events.slice(0, eventIndex));
+    const transcript = transcriptThroughEvents(source.transcript, prefix);
+    const player = source.events[eventIndex];
+    return {
+        // This append precedes the operation's materialization check, as before.
+        withReplacement(selected, replacement) {
+            const events = [
+                ...prefix,
+                {
+                    id: player.id,
+                    kind: "player",
+                    exchangeId: replacement.exchangeId,
+                    text: replacement.text,
+                    context: player.context,
+                    committedHead: replacement.head,
+                },
+            ];
+            const continuedTranscript = [
+                ...transcript,
+                ...playerInputAppend({
+                    history: Object.fromEntries(selected.history.map(({ messageId, exactText }) => [
+                        messageId,
+                        exactText,
+                    ])),
+                    checkpoint: selected.narrativeCheckpoint,
+                    text: replacement.text,
+                    locale: replacement.locale,
+                    checkpointAvailable: source.tools.some(({ name }) => name === "world_checkpoint"),
+                }),
+            ];
+            return {
+                atEndpoint(endpoint) {
+                    return assembleRetainedTrace(source, endpoint, {
+                        events,
+                        transcript: continuedTranscript,
+                        toolEvents: prefix,
+                        authorizationEvents: prefix,
+                        exchangeEvents: prefix,
+                        complete: false,
+                        materials: endpoint.binding.additionalMaterials,
+                    });
+                },
+            };
+        },
+        pagePrefixAtEndpoint(endpoint) {
+            if (prefix.length === 0)
+                return null;
+            // Preserve the fresh path's post-commit prefix reconstruction seam.
+            const prefixTranscript = transcriptThroughEvents(source.transcript, prefix);
+            return assembleRetainedTrace(source, endpoint, {
+                events: prefix,
+                transcript: prefixTranscript,
+                toolEvents: prefix,
+                authorizationEvents: prefix,
+                exchangeEvents: prefix,
+                complete: false,
+                materials: endpoint.selected.additionalMaterials,
+            });
+        },
+    };
+}
+/** A complete context defines its own closure; partial contexts use page events. */
+export function prepareForkTrace(source, events) {
+    const complete = events.length === source.events.length;
+    const transcript = complete
+        ? structuredClone(source.transcript)
+        : transcriptThroughEvents(source.transcript, events);
+    return {
+        atEndpoint(endpoint) {
+            return assembleRetainedTrace(source, endpoint, {
+                events,
+                transcript,
+                toolEvents: events,
+                authorizationEvents: events,
+                exchangeEvents: events,
+                complete,
+                materials: endpoint.binding.additionalMaterials,
+            });
+        },
+    };
+}
+function assembleRetainedTrace(source, endpoint, selection) {
+    const completedKeys = selection.complete
+        ? null
+        : completedToolKeys(selection.toolEvents);
+    const documents = restorePlayDocuments(endpoint.binding.files, source, selection.authorizationEvents);
+    return {
+        continuityContextId: source.continuityContextId ?? source.chainId,
+        baselineHead: source.baselineHead,
+        baselineHistoryLength: source.baselineHistoryLength ?? endpoint.baseline.history.length,
+        promptRuns: playPromptRunsThroughEvents(source, selection.events),
+        ...(source.presetFiles === undefined
+            ? {}
+            : { presetFiles: structuredClone(source.presetFiles) }),
+        playPreset: structuredClone(source.playPreset),
+        ...(source.followups === undefined
+            ? {}
+            : { followups: structuredClone(source.followups) }),
+        ...(source.playPresetScriptsEnabled === undefined
+            ? {}
+            : { playPresetScriptsEnabled: source.playPresetScriptsEnabled }),
+        ...(source.modelBinding === undefined
+            ? {}
+            : { modelBinding: structuredClone(source.modelBinding) }),
+        status: "ready",
+        canRetry: false,
+        bootstrap: structuredClone(source.bootstrap),
+        tools: structuredClone(source.tools),
+        transcript: structuredClone(selection.transcript),
+        events: structuredClone([...selection.events]),
+        completedTools: source.completedTools
+            .filter(({ key }) => completedKeys === null || completedKeys.has(key))
+            .map((item) => structuredClone(item)),
+        documentAuthorizationCheckpoints: authorizationCheckpointsThroughEvents(source, selection.events, documents.authorizationCheckpoint()),
+        changedDocuments: changedDocumentsAtHead(source.changedDocuments, endpoint.baseline.state, endpoint.selected.state),
+        nextMaterials: structuredClone(selection.materials),
+        nextEventId: Math.max(0, ...selection.events.map(({ id }) => id)) + 1,
+        exchange: completedAssistantExchange(selection.exchangeEvents),
+        lastRequest: null,
+        lastRequestAttempt: 0,
+        lastFailure: null,
+    };
+}
+export function restorePlayDocuments(files, context, events) {
+    const documents = new FileNativePlayDocuments(files);
+    try {
+        const checkpoint = documentAuthorizationThroughEvents(context, events);
+        const runs = playPromptRunsThroughEvents(context, events);
+        if (checkpoint === undefined || runs.length > 0)
+            documents.bindBootstrap(currentPlayPrompt({ ...context, promptRuns: runs }).bootstrap);
+        if (checkpoint !== undefined)
+            documents.restoreAuthorizationCheckpoint(checkpoint.authorization);
+    }
+    catch (error) {
+        throw new PlayCallChainError(`Call-chain document authorization could not be restored: ${error instanceof Error ? error.message : "invalid checkpoint"}。`);
+    }
+    return documents;
+}
+function documentAuthorizationThroughEvents(context, events) {
+    const checkpoints = context.documentAuthorizationCheckpoints;
+    if (checkpoints === undefined || checkpoints.length === 0)
+        return undefined;
+    const selectedEventIds = new Set(events.map(({ id }) => id));
+    const selected = checkpoints.findLast(({ afterEventId }) => afterEventId === 0 || selectedEventIds.has(afterEventId));
+    // Legacy V1 records had no durable dynamic authorization. If the selected
+    // prefix predates their first lazily-written checkpoint, retain the exact
+    // old recovery behavior and rebuild only bootstrap authorization.
+    return selected === undefined ? undefined : structuredClone(selected);
+}
+export function independentContextCopy(source) {
+    const context = structuredClone(source);
+    context.continuityContextId ??= source.chainId;
+    delete context.derivedFrom;
+    delete context.branchedBeforePlayer;
+    return context;
+}
+function authorizationCheckpointsThroughEvents(context, events, fallback) {
+    const eventIds = new Set(events.map(({ id }) => id));
+    const selected = (context.documentAuthorizationCheckpoints ?? [])
+        .filter(({ afterEventId }) => afterEventId === 0 || eventIds.has(afterEventId))
+        .map((checkpoint) => structuredClone(checkpoint));
+    if (selected.length > 0)
+        return selected;
+    return [
+        {
+            afterEventId: Math.max(0, ...events.map(({ id }) => id)),
+            authorization: structuredClone(fallback),
+        },
+    ];
+}
+function transcriptThroughEvents(transcript, events) {
+    const result = [];
+    let cursor = 0;
+    for (const [index, event] of events.entries()) {
+        if (event.kind === "player") {
+            const marker = transcript[cursor];
+            if (isPlayerRoundMarker(marker)) {
+                result.push(structuredClone(marker));
+                cursor += 1;
+            }
+            const item = transcript[cursor];
+            if (item?.kind !== "player" || item.text !== event.text)
+                throw new PlayCallChainError("Source call-chain events do not match the model transcript, so a fork cannot be created safely.");
+            result.push(structuredClone(item));
+            cursor += 1;
+            continue;
+        }
+        if (event.kind === "assistant" && event.status === "completed") {
+            const notice = transcript[cursor];
+            const hasContinuationNotice = notice?.kind === "runtime_notice" && notice.notice === "continuation";
+            const item = transcript[cursor + (hasContinuationNotice ? 1 : 0)];
+            const hasToolCall = events
+                .slice(index + 1)
+                .find((candidate) => candidate.kind === "player" ||
+                candidate.kind === "assistant" ||
+                candidate.kind === "tool_call");
+            const recorded = event.text.trim().length > 0 ||
+                hasToolCall?.kind === "tool_call" ||
+                item?.kind === "assistant";
+            if (!recorded)
+                continue;
+            if (item?.kind !== "assistant" || item.text !== event.text)
+                throw new PlayCallChainError("Source call-chain responses do not match the model transcript, so a fork cannot be created safely.");
+            // A continuation notice belongs to the generation it precedes, never
+            // to a fork ending at the previously completed narrative.
+            if (hasContinuationNotice) {
+                result.push(structuredClone(notice));
+                cursor += 1;
+            }
+            result.push(structuredClone(item));
+            cursor += 1;
+            continue;
+        }
+        if (event.kind === "tool_result") {
+            const item = transcript[cursor];
+            if (item?.kind !== "tool" || item.toolCallId !== event.callId)
+                throw new PlayCallChainError("Source call-chain tool results do not match the model transcript, so a fork cannot be created safely.");
+            result.push(structuredClone(item));
+            cursor += 1;
+            // A tool-step notice follows the entire settled batch and remains part
+            // of its closure even when the selected endpoint stops at that batch.
+            const notice = transcript[cursor];
+            if (notice?.kind === "runtime_notice" && notice.notice === "tool_step") {
+                result.push(structuredClone(notice));
+                cursor += 1;
+            }
+        }
+    }
+    return result;
+}
+function completedToolKeys(events) {
+    const keys = new Set();
+    let exchange = null;
+    for (const event of events) {
+        if (event.kind === "player")
+            exchange = null;
+        else if (event.kind === "assistant")
+            exchange = event.exchange;
+        else if (event.kind === "tool_call" && exchange !== null)
+            keys.add(`${exchange}:${event.callId}`);
+    }
+    return keys;
+}
+function changedDocumentsAtHead(changes, baseline, selected) {
+    const before = new Map(baseline.map((file) => [file.path, file.contents]));
+    const after = new Map(selected.map((file) => [file.path, file.contents]));
+    return changes
+        .filter(({ path }) => after.has(path) && before.get(path) !== after.get(path))
+        .map((change) => structuredClone(change));
+}
+function completedAssistantExchange(events) {
+    return Math.max(0, ...events
+        .filter((event) => event.kind === "assistant" && event.status === "completed")
+        .map(({ exchange }) => exchange));
+}