narraeon 0.5.2 → 0.5.4

package/dist/node/runtime/history/HistoryQuery.js

@@ -0,0 +1,550 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
+// A restart rejects old process-bound cursors explicitly, without guessing a
+// snapshot or trusting client-provided query declarations. Frozen requests and
+// their already completed tool receipts are restored independently.
+const cursorSecret = randomBytes(32);
+export class HistoryQuery {
+    messages;
+    snapshotId;
+    #world;
+    constructor(world, inputs) {
+        this.#world = world;
+        const refs = inputs.map(({ id }) => historyMessageRef(id));
+        this.messages = inputs.map((message, index) => Object.freeze({
+            ...message,
+            ref: refs[index],
+            position: index + 1,
+            isOpening: message.isOpening === true,
+            previous: refs[index - 1] ?? null,
+            next: refs[index + 1] ?? null,
+            length: Array.from(message.text).length,
+        }));
+        this.snapshotId = createHash("sha256")
+            .update(JSON.stringify(inputs.map(({ id, role, isOpening, text }) => [
+            id,
+            role,
+            isOpening === true,
+            text,
+        ])))
+            .digest("hex");
+    }
+    list(args) {
+        try {
+            const input = argumentsObject(args, [
+                "before",
+                "after",
+                "limit",
+                "cursor",
+            ]);
+            let start;
+            let end;
+            let limit;
+            let query;
+            let anchor;
+            if (input.cursor !== undefined) {
+                cursorOnly(input);
+                const cursor = this.#decodeCursor(input.cursor, "history_list");
+                query = cursor.query;
+                limit = Number(query.limit);
+                anchor = typeof query.anchor === "string" ? query.anchor : null;
+                if (cursor.direction === "earlier") {
+                    end = cursor.offset;
+                    start = Math.max(0, end - limit);
+                }
+                else {
+                    start = cursor.offset;
+                    end = Math.min(this.messages.length, start + limit);
+                }
+            }
+            else {
+                limit = integer(input.limit, 20, 1, 100, "limit");
+                if (input.before !== undefined && input.after !== undefined)
+                    invalid("Use only one of before or after, or omit both for the latest page.");
+                anchor =
+                    input.before === undefined && input.after === undefined
+                        ? null
+                        : this.#find(input.before ?? input.after).ref;
+                if (input.after !== undefined) {
+                    start = this.#find(input.after).position;
+                    end = Math.min(this.messages.length, start + limit);
+                }
+                else {
+                    end =
+                        input.before === undefined
+                            ? this.messages.length
+                            : this.#find(input.before).position - 1;
+                    start = Math.max(0, end - limit);
+                }
+                query = {
+                    limit,
+                    anchor,
+                    mode: input.before !== undefined
+                        ? "before"
+                        : input.after !== undefined
+                            ? "after"
+                            : "latest",
+                };
+            }
+            return {
+                ok: true,
+                kind: "list",
+                total: this.messages.length,
+                messages: this.messages.slice(start, end),
+                anchor,
+                earlierCursor: start === 0
+                    ? null
+                    : this.#cursor("history_list", query, start, "earlier"),
+                laterCursor: end === this.messages.length
+                    ? null
+                    : this.#cursor("history_list", query, end, "later"),
+            };
+        }
+        catch (error) {
+            return queryFailure(error);
+        }
+    }
+    search(args) {
+        return this.#search(args, "history_search");
+    }
+    legacyList(args, tool) {
+        try {
+            const input = argumentsObject(args, ["order", "limit", "cursor"]);
+            if (input.order !== "newest_first" && input.order !== "oldest_first")
+                invalid("Legacy history listing requires newest_first or oldest_first order.");
+            const limit = integer(input.limit, 20, 1, 100, "limit");
+            const query = { order: input.order, limit };
+            let offset = 0;
+            if (input.cursor !== undefined && input.cursor !== null) {
+                const cursor = this.#decodeCursor(input.cursor, `legacy_${tool}`);
+                if (JSON.stringify(cursor.query) !== JSON.stringify(query))
+                    invalid("Keep the original legacy order and limit, or run a new query.");
+                offset = cursor.offset;
+            }
+            const ordered = input.order === "newest_first"
+                ? [...this.messages].reverse()
+                : this.messages;
+            const page = ordered.slice(offset, offset + limit);
+            return {
+                ok: true,
+                kind: "legacy_list",
+                total: this.messages.length,
+                order: input.order,
+                offset,
+                messages: page,
+                nextCursor: offset + page.length >= ordered.length
+                    ? null
+                    : this.#cursor(`legacy_${tool}`, query, offset + page.length, "later"),
+            };
+        }
+        catch (error) {
+            return queryFailure(error);
+        }
+    }
+    legacySearch(args) {
+        try {
+            const input = argumentsObject(args, [
+                "query",
+                "caseSensitive",
+                "within",
+                "limit",
+                "cursor",
+            ]);
+            const { cursor, query, within, ...options } = input;
+            if (within !== undefined && typeof within !== "string")
+                invalid("Legacy within must be a Runtime history handle.");
+            const request = { queries: [query], ...options, order: "oldest_first" };
+            if (cursor !== undefined && cursor !== null) {
+                const saved = this.#decodeCursor(cursor, "legacy_context_search");
+                if (normalizeLiteral(String(query), options.caseSensitive === true) !==
+                    normalizeLiteral(String(saved.query.queries[0]), options.caseSensitive === true) ||
+                    (within ?? null) !== saved.query.within ||
+                    integer(options.limit, 10, 1, 50, "limit") !== saved.query.limit ||
+                    (options.caseSensitive === true) !== saved.query.caseSensitive)
+                    invalid("Keep the original legacy search parameters, or run a new query.");
+                return this.#search({ cursor }, "legacy_context_search");
+            }
+            return this.#search(request, "legacy_context_search", typeof within === "string" ? within : null);
+        }
+        catch (error) {
+            return queryFailure(error);
+        }
+    }
+    #search(args, tool, within = null) {
+        try {
+            const input = argumentsObject(args, [
+                "queries",
+                "match",
+                "order",
+                "caseSensitive",
+                "limit",
+                "after",
+                "before",
+                "cursor",
+            ]);
+            let query;
+            let offset = 0;
+            if (input.cursor !== undefined) {
+                cursorOnly(input);
+                const cursor = this.#decodeCursor(input.cursor, tool);
+                query = cursor.query;
+                offset = cursor.offset;
+            }
+            else {
+                if (!Array.isArray(input.queries) ||
+                    input.queries.length < 1 ||
+                    input.queries.length > 5 ||
+                    input.queries.some((word) => typeof word !== "string" ||
+                        word.trim().length === 0 ||
+                        Array.from(word).length > 256))
+                    invalid("queries must contain 1–5 nonempty literal strings, each at most 256 Unicode code points.");
+                if (input.caseSensitive !== undefined &&
+                    typeof input.caseSensitive !== "boolean")
+                    invalid("caseSensitive must be boolean.");
+                if (input.match !== undefined &&
+                    input.match !== "any" &&
+                    input.match !== "all")
+                    invalid("match must be any or all (within one message).");
+                if (input.order !== undefined &&
+                    input.order !== "newest_first" &&
+                    input.order !== "oldest_first")
+                    invalid("order must be newest_first or oldest_first.");
+                const caseSensitive = input.caseSensitive === true;
+                const seen = new Set();
+                const queries = input.queries.filter((word) => {
+                    const normalized = normalizeLiteral(word, caseSensitive);
+                    if (seen.has(normalized))
+                        return false;
+                    seen.add(normalized);
+                    return true;
+                });
+                const start = input.after === undefined ? 0 : this.#find(input.after).position;
+                const end = input.before === undefined
+                    ? this.messages.length
+                    : this.#find(input.before).position - 1;
+                if (input.after !== undefined &&
+                    input.before !== undefined &&
+                    start > end)
+                    invalid("after must precede before in timeline order, regardless of search order.");
+                query = {
+                    queries,
+                    caseSensitive,
+                    match: input.match ?? "any",
+                    order: input.order ?? "newest_first",
+                    limit: integer(input.limit, 10, 1, 50, "limit"),
+                    start,
+                    end,
+                    within,
+                };
+            }
+            const queries = query.queries;
+            const caseSensitive = query.caseSensitive === true;
+            const match = query.match;
+            const order = query.order;
+            const start = Number(query.start);
+            const end = Number(query.end);
+            const limit = Number(query.limit);
+            const found = this.messages.slice(start, end).flatMap((message) => {
+                if (typeof query.within === "string" &&
+                    !historyScopeMatches(message, query.within))
+                    return [];
+                const hit = searchMessage(message, queries, caseSensitive);
+                return hit.hits.length > 0 &&
+                    (match === "any" || hit.hits.length === queries.length)
+                    ? [hit]
+                    : [];
+            });
+            if (order === "newest_first")
+                found.reverse();
+            const page = found.slice(offset, offset + limit);
+            return {
+                ok: true,
+                kind: "search",
+                total: this.messages.length,
+                range: start === end
+                    ? { start: null, end: null }
+                    : { start: start + 1, end },
+                queries,
+                caseSensitive,
+                match,
+                order,
+                within: typeof query.within === "string" ? query.within : null,
+                legacy: tool === "legacy_context_search",
+                matches: found.length,
+                messages: page,
+                nextCursor: offset + page.length >= found.length
+                    ? null
+                    : this.#cursor(tool, query, offset + page.length, "later"),
+            };
+        }
+        catch (error) {
+            return queryFailure(error);
+        }
+    }
+    read(args) {
+        try {
+            const input = argumentsObject(args, ["latest", "ref", "before", "after"]);
+            let start;
+            let end;
+            let center = null;
+            if (input.latest !== undefined) {
+                if (Object.keys(input).some((key) => key !== "latest"))
+                    invalid("Use {latest} alone, or {ref,before,after} for an anchor window.");
+                const latest = integer(input.latest, 4, 1, 21, "latest");
+                end = this.messages.length;
+                start = Math.max(0, end - latest);
+            }
+            else {
+                const message = this.#find(input.ref);
+                const before = integer(input.before, 0, 0, 20, "before");
+                const after = integer(input.after, 0, 0, 20, "after");
+                if (before + after > 20)
+                    invalid("before + after must be at most 20 messages. Extend in small windows if needed.");
+                center = message.ref;
+                start = Math.max(0, message.position - 1 - before);
+                end = Math.min(this.messages.length, message.position + after);
+            }
+            return {
+                ok: true,
+                kind: "read",
+                total: this.messages.length,
+                mode: center === null ? "latest" : "anchor",
+                center,
+                messages: this.messages.slice(start, end),
+                earlier: this.messages[start - 1]?.ref ?? null,
+                later: this.messages[end]?.ref ?? null,
+            };
+        }
+        catch (error) {
+            return queryFailure(error);
+        }
+    }
+    #find(ref) {
+        if (typeof ref !== "string" || !ref.startsWith("@history-message-"))
+            invalid("Use a history ref supplied by Runtime in an injection or a tool result.");
+        const message = this.messages.find((message) => message.ref === ref);
+        if (message === undefined)
+            throw new HistoryQueryError("history_ref_not_in_current_timeline", "This ref is not on the current timeline; it may still exist at an old endpoint. Query the current history again.");
+        return message;
+    }
+    #cursor(tool, query, offset, direction) {
+        const payload = {
+            version: 1,
+            world: this.#world,
+            snapshot: this.snapshotId,
+            tool,
+            query,
+            offset,
+            direction,
+        };
+        const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+        const signature = createHmac("sha256", cursorSecret)
+            .update(encoded)
+            .digest("base64url");
+        return `${encoded}.${signature}`;
+    }
+    #decodeCursor(value, tool) {
+        const bad = () => new HistoryQueryError("history_invalid_cursor", "Invalid, obsolete, cross-world or cross-tool cursor. Run the original query again; continue using only the returned cursor.");
+        if (typeof value !== "string")
+            throw bad();
+        const parts = value.split(".");
+        if (parts.length !== 2)
+            throw bad();
+        const [encoded, signature] = parts;
+        const expected = createHmac("sha256", cursorSecret)
+            .update(encoded)
+            .digest();
+        const received = Buffer.from(signature, "base64url");
+        if (!/^[A-Za-z0-9_-]+$/u.test(encoded) ||
+            signature !== received.toString("base64url") ||
+            received.length !== expected.length ||
+            !timingSafeEqual(received, expected))
+            throw bad();
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        }
+        catch {
+            throw bad();
+        }
+        if (payload.version !== 1 ||
+            payload.world !== this.#world ||
+            payload.tool !== tool)
+            throw bad();
+        if (payload.snapshot !== this.snapshotId)
+            throw new HistoryQueryError("history_changed", "The current history changed. Run the original query again and use its new cursor; do not combine pages from different snapshots.");
+        return payload;
+    }
+}
+export function historyMessageRef(id) {
+    return `@history-message-${id.replace(/\.md$/u, "").replace(/^@?history-message-/u, "")}`;
+}
+/** Decode storage identity once at the boundary; never infer order from it. */
+export function historyInputs(entries) {
+    return entries.map(({ path, contents }) => {
+        const id = path.replace(/\.md$/u, "");
+        return {
+            id,
+            text: contents,
+            role: /(?:\.|-)player(?:-|$)/u.test(id) ? "player" : "narrator",
+            isOpening: id.endsWith("message.genesis.narrator"),
+        };
+    });
+}
+class HistoryQueryError extends Error {
+    code;
+    recovery;
+    constructor(code, recovery) {
+        super(recovery);
+        this.code = code;
+        this.recovery = recovery;
+    }
+}
+function queryFailure(error) {
+    if (error instanceof HistoryQueryError)
+        return { ok: false, code: error.code, recovery: error.recovery };
+    throw error;
+}
+function invalid(message) {
+    throw new HistoryQueryError("history_invalid_arguments", message);
+}
+function argumentsObject(args, allowed) {
+    if (args === null ||
+        typeof args !== "object" ||
+        Array.isArray(args) ||
+        Object.keys(args).some((key) => !allowed.includes(key)))
+        invalid(`Use only ${allowed.join(", ")}.`);
+    return args;
+}
+function cursorOnly(input) {
+    if (Object.keys(input).length !== 1)
+        invalid("Continuation needs only {cursor}; omit all first-query arguments.");
+}
+function integer(value, fallback, min, max, name) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < min ||
+        value > max)
+        invalid(`${name} must be an integer from ${min} to ${max}.`);
+    return value;
+}
+function normalizeLiteral(value, caseSensitive) {
+    const normalized = value.normalize("NFKC");
+    return caseSensitive ? normalized : normalized.toLocaleLowerCase("und");
+}
+function searchMessage(message, queries, caseSensitive) {
+    // Grapheme clusters keep combining sequences together during normalization.
+    // Each normalized UTF-16 unit maps to the original cluster's code-point
+    // interval; expansions (ligatures, full-width letters, dotted I) stay exact.
+    const source = Array.from(message.text);
+    const mapping = [];
+    let normalized = "";
+    let originalOffset = 0;
+    for (const { segment } of new Intl.Segmenter("und", {
+        granularity: "grapheme",
+    }).segment(message.text)) {
+        const end = originalOffset + Array.from(segment).length;
+        const transformed = normalizeLiteral(segment, caseSensitive);
+        normalized += segment.normalize("NFKC");
+        transformed
+            .split("")
+            .forEach(() => mapping.push({ start: originalOffset, end }));
+        originalOffset = end;
+    }
+    // Case conversion uses the entire normalized text so contextual lowercasing
+    // (such as final Greek sigma) matches the existing literal-search rules.
+    if (!caseSensitive)
+        normalized = normalized.toLocaleLowerCase("und");
+    const perQuery = queries.map((query) => {
+        const needle = normalizeLiteral(query, caseSensitive);
+        const ranges = [];
+        let offset = 0;
+        while (offset <= normalized.length - needle.length) {
+            const found = normalized.indexOf(needle, offset);
+            if (found < 0)
+                break;
+            ranges.push({
+                start: mapping[found].start,
+                end: mapping[found + needle.length - 1].end,
+            });
+            offset = found + needle.length;
+        }
+        return { query, ranges };
+    });
+    const allRanges = perQuery
+        .flatMap(({ ranges }) => ranges)
+        .sort((a, b) => a.start - b.start || a.end - b.end);
+    const windows = [];
+    const add = (range) => {
+        const window = {
+            start: Math.max(0, range.start - 80),
+            end: Math.min(source.length, range.end + 80),
+        };
+        const overlaps = windows.filter((existing) => existing.start <= window.end && window.start <= existing.end);
+        if (overlaps.length === 0 && windows.length === 3)
+            return false;
+        for (const existing of overlaps) {
+            window.start = Math.min(window.start, existing.start);
+            window.end = Math.max(window.end, existing.end);
+            windows.splice(windows.indexOf(existing), 1);
+        }
+        windows.push(window);
+        return true;
+    };
+    // Prioritize the first occurrence of each distinct query before filling any
+    // remaining fragment slots with other matches in source order.
+    for (const { ranges } of perQuery)
+        if (ranges[0] !== undefined)
+            add(ranges[0]);
+    for (const range of allRanges) {
+        if (windows.length >= 3)
+            break;
+        const candidate = {
+            start: Math.max(0, range.start - 80),
+            end: Math.min(source.length, range.end + 80),
+        };
+        // Supplemental hits fill separate fragment slots. Do not repeatedly grow
+        // one window through a chain of nearby hits into a complete long body.
+        if (windows.some((window) => window.start <= candidate.end && candidate.start <= window.end))
+            continue;
+        add(range);
+    }
+    windows.sort((a, b) => a.start - b.start);
+    return {
+        message,
+        hits: perQuery
+            .filter(({ ranges }) => ranges.length > 0)
+            .map(({ query, ranges }) => ({ query, count: ranges.length })),
+        fragments: windows.map(({ start, end }) => ({
+            text: source.slice(start, end).join(""),
+            start: start + 1,
+            end,
+            omittedBefore: start > 0,
+            omittedAfter: end < source.length,
+        })),
+        omittedMatches: allRanges.some((range) => !windows.some((window) => range.start >= window.start && range.end <= window.end)),
+    };
+}
+function historyScopeMatches(message, within) {
+    if (historyMessageRef(message.id) === historyMessageRef(within))
+        return true;
+    const commit = /(?:^|\.)message\.([^.]+)\./u.exec(message.id)?.[1] ??
+        message.id.split("-")[0];
+    return within.replace(/^@/u, "") === `history-commit-${commit}`;
+}
+/** Resolve exact author/legacy selections without changing Authority order. */
+export function historySelectionMatches(material, key) {
+    if (material.kind === "history_message")
+        return historyIdentity(key) === historyIdentity(material.message);
+    const ref = material.commit;
+    return ref.startsWith("commit:")
+        ? historyIdentity(key).startsWith(`message.${ref.slice(7)}.`)
+        : ref === "genesis"
+            ? historyIdentity(key).startsWith("message.genesis.")
+            : key.startsWith(ref.replace(/^@?history-commit-/u, "history-message-").concat("-"));
+}
+function historyIdentity(ref) {
+    const value = ref.replace(/^@?(?:history-message-)?/u, "");
+    return (/(?:^|\.)(message\.(?:genesis|[0-9]+)(?:\.[0-9]+)?\.(?:player|narrator))$/u.exec(value)?.[1] ?? value);
+}

package/dist/node/runtime/history/HistoryRendering.js

@@ -0,0 +1,86 @@
+/** Shared metadata keeps injected refs and tool results directly navigable. */
+export function historyMessageLabel(message, locale) {
+    const zh = locale === "zh-CN";
+    const role = historyRoleLabel(message, locale);
+    return `${zh ? "位置" : "position"} ${message.position} · role=${message.role} · ${role}${message.isOpening ? (zh ? " · 开场白 isOpening=true" : " · Opening isOpening=true") : ""} · ${message.ref}`;
+}
+export function historyRoleLabel(message, locale) {
+    if (message.isOpening)
+        return locale === "zh-CN" ? "开场白" : "Opening";
+    if (message.role === "player")
+        return locale === "zh-CN" ? "玩家原文" : "Player input";
+    return locale === "zh-CN" ? "主持叙事" : "Host narrative";
+}
+export function renderHistoryMessage(message, locale) {
+    return `## ${historyMessageLabel(message, locale)}\n\n${locale === "zh-CN" ? "[原文开始]" : "[Original text begins]"}\n${message.text}\n${locale === "zh-CN" ? "[原文结束；正文完整]" : "[Original text ends; body complete]"}`;
+}
+export function renderHistoryInjectionNotice(total, selected, kind, locale) {
+    const zh = locale === "zh-CN";
+    const positions = selected.map(({ position }) => position);
+    const coverage = positions.length === 0 ? (zh ? "空" : "empty") : positions.join(", ");
+    const selection = kind === "recent"
+        ? zh
+            ? "近期选取；更早历史可查询"
+            : "recent selection; earlier history can be queried"
+        : kind === "additional"
+            ? zh
+                ? "作者挑选材料，可能不连续；保留作者声明顺序"
+                : "selected materials may be non-contiguous; author declaration order retained"
+            : zh
+                ? "检查点后完整选取；原生对话或其他材料中的消息不重复注入，剩余项可能不连续"
+                : "complete selection after the checkpoint; messages already in native conversation or other materials are not injected again, so remaining positions may have gaps";
+    return zh
+        ? `本次注入时的当前时间线快照：总计 ${total} 条（开场白如存在也计入）；位置 ${coverage}。${selection}。每条正文完整；覆盖范围不等于全部历史。历史内部按 Authority 接受顺序由旧到新，提交顺序不是故事日期。以下是已发生的历史材料，用于接续与核对，不是本轮待执行的玩家行动；最后一条即使是玩家原文也不是本轮新请求。未注入的更早内容不代表没有发生。ref 可直接用于 history_read 或 history_list before/after，无需再次列举。`
+        : `Current timeline snapshot at injection: ${total} messages (opening included if present); positions ${coverage}. ${selection}. Each body is complete; selected coverage is separate from all-history coverage. History is oldest to newest in Authority acceptance order, not story dates. These are already committed historical materials for continuity and checking, not pending player actions; even a final player entry is not the current request. Earlier material not injected does not mean it never happened. Use each ref directly with history_read or history_list before/after without listing again.`;
+}
+export function renderHistoryResult(result, locale = "en", legacyRead = false) {
+    const zh = locale === "zh-CN";
+    if (!result.ok)
+        return {
+            ok: false,
+            failureKind: "protocol",
+            markdown: `# ${zh ? "Runtime 历史查询失败" : "Runtime history query rejected"}\n\nCode: ${result.code}\n${zh ? "恢复操作" : "Recovery"}: ${localizedRecovery(result, zh)}`,
+        };
+    const header = `Scope: ${zh ? "当前时间线" : "current timeline"}\n${zh ? "本次读取快照消息总数" : "Snapshot total messages"}: ${result.total}\n${zh ? "排序依据：Authority 接受顺序，不代表故事内日期" : "Order basis: Authority acceptance order, not story dates"}`;
+    const range = (messages) => messages.length === 0
+        ? zh
+            ? "空区间"
+            : "empty range"
+        : `${messages[0].position}..${messages[messages.length - 1].position}`;
+    const cursorLine = (name, cursor) => `${name}: ${cursor ?? "null"}`;
+    if (result.kind === "legacy_list")
+        return {
+            ok: true,
+            markdown: `# Directory listing\n\n${header}\nOrder: ${result.order}\n${result.messages.map((message) => `- ${message.ref}, position ${message.position}, role=${message.role}${message.isOpening ? ", isOpening=true" : ""}, ${message.length} Unicode code points`).join("\n") || "(empty)"}\n\n---\nThis page: ${result.offset}..${result.offset + result.messages.length} / ${result.total} items\nComplete: ${result.nextCursor === null ? "yes" : "no"}${result.nextCursor === null ? "" : `\nNext-page cursor: ${result.nextCursor}`}`,
+        };
+    if (result.kind === "list")
+        return {
+            ok: true,
+            markdown: `# ${zh ? "已提交历史列表" : "Committed history listing"}\n\n${header}\nOrder: oldest_first (${zh ? "页内始终由旧到新" : "every page oldest to newest"})\n${result.messages
+                .map((message) => {
+                const preview = Array.from(message.text).slice(0, 120).join("");
+                return `### ${historyMessageLabel(message, locale)}\n${message.length} Unicode code points\n[${zh ? "部分原文预览" : "Partial original preview"}]\n${preview}\n[${message.length > 120 ? (zh ? "预览有省略" : "preview omitted remaining text") : zh ? "预览结束" : "preview ends"}]`;
+            })
+                .join("\n\n") || (zh ? "（空页）" : "(empty page)")}\n\n---\n${zh ? "本页位置／条数" : "Page positions / count"}: ${range(result.messages)} / ${result.messages.length}\n${cursorLine("earlierCursor", result.earlierCursor)}\n${cursorLine("laterCursor", result.laterCursor)}\n${zh ? "续页只传 {cursor}。" : "Continue with only {cursor}."}${result.messages.length === 0 && result.anchor !== null ? `\n${zh ? "可从锚点转向浏览" : "Browse from the anchor in the other direction"}: {before:"${result.anchor}"} / {after:"${result.anchor}"}` : ""}`,
+        };
+    if (result.kind === "read")
+        return {
+            ok: true,
+            markdown: `# ${zh ? "完整历史原文" : "Complete history originals"}\n\n${header}\nMode: ${result.mode}${result.center === null ? "" : `\nCenter: ${result.center}`}\nOrder: oldest_first\n${zh ? "实际位置" : "Actual positions"}: ${range(result.messages)}\n${zh ? "每条正文完整，无摘要、无截断" : "Each body is complete, without summary or truncation"}\n\n${result.messages.map((message) => renderHistoryMessage(message, locale)).join("\n\n") || (zh ? "（历史为空）" : "(empty history)")}\n\n---\n${cursorLine("earlier", result.earlier)}\n${cursorLine("later", result.later)}\n${result.earlier === null ? (zh ? "已到历史开头。" : "At the history beginning.") : legacyRead ? `context_read {ref:"${result.earlier}"}` : zh ? "向前不重复读取：history_read {ref:earlier,before:N}。" : "Read earlier without repeating this window: history_read {ref:earlier,before:N}."}\n${result.later === null ? (zh ? "已到历史结尾。" : "At the history end.") : legacyRead ? `context_read {ref:"${result.later}"}` : zh ? "向后不重复读取：history_read {ref:later,after:N}。" : "Read later without repeating this window: history_read {ref:later,after:N}."}\n${legacyRead ? (zh ? "按需逐条读取相邻原文。" : "Read adjacent originals one at a time as needed.") : zh ? "按需小步扩展；21 条消息不代表固定输出体积。" : "Expand in small windows as needed; 21 messages do not imply a fixed output size."}`,
+        };
+    return {
+        ok: true,
+        markdown: `# ${zh ? "历史字面搜索" : "History literal search"}\n\n${header}${result.within === null ? "" : `\nLegacy selected scope: ${result.within}`}\n${zh ? "搜索位置范围（排除边界）" : "Search position range (boundaries excluded)"}: ${result.range.start === null ? "empty" : `${result.range.start}..${result.range.end}`}\nOrder: ${result.order}\nMatch: ${result.match} (${zh ? "同一消息内" : "within one message"})\nNormalization: NFKC${result.caseSensitive ? " (case sensitive)" : " + case folding (locale und)"}\n${zh ? "查询词" : "Queries"}: ${JSON.stringify(result.queries)}\n${zh ? "命中消息总数" : "Total matching messages"}: ${result.matches}\n\n${result.messages.map(({ message, hits, fragments, omittedMatches }) => `### ${historyMessageLabel(message, locale)}\n${message.length} Unicode code points\n${zh ? "逐词命中次数" : "Matches per query"}: ${hits.map(({ query, count }) => `${JSON.stringify(query)}: ${count}`).join("; ")}\n${fragments.map((fragment) => `[${zh ? "部分原文片段" : "Partial original fragment"}: ${fragment.start}..${fragment.end}${fragment.omittedBefore ? "; prefix omitted" : ""}${fragment.omittedAfter ? "; suffix omitted" : ""}]\n${fragment.text}\n[${zh ? "片段结束" : "fragment ends"}]`).join("\n")}\n${omittedMatches ? (zh ? "另有命中未展示；可完整读取核实。" : "Additional matches omitted; read the complete original to verify.") : zh ? "全部命中均在所示片段内。" : "All matches are covered by these fragments."}`).join("\n\n") || (result.legacy ? (zh ? "零字面命中不证明事件没有发生；可改用其他 query 或读取相邻原文。" : "Zero literal matches do not prove an event never happened. Try another query or read adjacent originals.") : zh ? "零字面命中不证明事件没有发生；可改词、从 all 放宽为 any 或读取相邻上下文。" : "Zero literal matches do not prove an event never happened. Try other words, relax all to any, or read nearby context.")}\n\n---\n${cursorLine(result.legacy ? "Next-page cursor" : "nextCursor", result.nextCursor)}\n${result.legacy ? (zh ? "续页保留原source=history、query、caseSensitive、within与limit并使用返回cursor。" : "Legacy continuation keeps the original source=history, query, caseSensitive, within and limit with the returned cursor.") : zh ? "续页只传 {cursor}；已有原文足以判断时停止检索。all 仅限同一消息；相邻消息可改用 any 后读前后文。" : "Continue with only {cursor}; stop when the originals suffice. all applies to one message; use any then read context for terms in adjacent messages."}`,
+    };
+}
+function localizedRecovery(result, zh) {
+    if (!zh)
+        return result.recovery;
+    if (result.code === "history_changed")
+        return "当前历史已变化，请重新执行原查询，使用新游标；不要拼接不同快照的页面。";
+    if (result.code === "history_invalid_cursor")
+        return "游标非法、过期、属于其他世界或工具，或来自不支持的旧版本。请重新执行原查询；续页只传 Runtime 返回的 cursor。";
+    if (result.code === "history_ref_not_in_current_timeline")
+        return "该 ref 不在当前时间线中，可能仍保存在旧端点；请重新查询当前历史。";
+    return `参数不符合要求，请按工具定义修正。${result.recovery}`;
+}