@visual-z/xeno 0.1.0

package/src/runtime/history-tools.ts

@@ -0,0 +1,108 @@
+/** N.2: one ancestry-scoped reader for query, exact event, and structured pages. */
+import { join } from "node:path";
+import { deriveHandoff } from "../core/derive.ts";
+import type { Handoff } from "../core/handoff.ts";
+import { HISTORY_SECTIONS, historyPage, type HistorySection } from "../core/history.ts";
+import { historyEntries, historyHits, historyIndex, queryHistory, type HistoryEntry } from "../core/history-query.ts";
+import { resourceKey } from "../core/evidence-links.ts";
+import { canonicalValue } from "../core/continuation.ts";
+import { digestNode, nodePath, readManifest } from "../store/log.ts";
+import { readNodeHistory } from "../store/restore.ts";
+import { archiveObservation, readObservation } from "../store/observations.ts";
+import { observationContains } from "../store/history-search.ts";
+import { presentObservation, type ToolContext, type ToolResult } from "./tools.ts";
+
+export async function runHistoryTool(logDir: string, currentNode: number, ctx: ToolContext, input: unknown): Promise<ToolResult> {
+  try {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("history expects an object");
+    const args = input as Record<string, unknown>;
+    const archive = ctx.outputStore ?? join(logDir, "artifacts");
+    if (typeof args["artifact"] === "string") return { ok: true, content: JSON.stringify(await readObservation(archive,
+      args["artifact"], typeof args["offset"] === "number" ? args["offset"] : 0,
+      Math.max(1, Math.floor(ctx.maxOutputBytes / 3)))) };
+    const index = await readManifest(logDir);
+    const history = await readNodeHistory(logDir, currentNode, index);
+    if (!history.ok) throw new Error(history.error);
+    const entries = historyEntries(history.nodes);
+    const indexed = historyIndex(entries);
+    if (args["events"] !== undefined) {
+      const requested = args["events"];
+      if (!Array.isArray(requested) || requested.length < 1 || requested.length > 100 || requested.some(event => typeof event !== "string" || !event)) {
+        throw new Error("history events must contain 1..100 event ids");
+      }
+      const items = requested.map(event => indexed.byEvent.get(event) ?? { event, missing: true });
+      const missing = requested.filter(event => !indexed.byEvent.has(event));
+      return { ...await historyValue(ctx, { items, missing }), ok: missing.length === 0 };
+    }
+    if (typeof args["event"] === "string") {
+      const found = indexed.byEvent.get(args["event"]);
+      if (!found) throw new Error("event is not readable in the active ancestry");
+      return historyValue(ctx, found);
+    }
+    if (typeof args["query"] === "string" || args["recent"] === true || typeof args["resource"] === "string" || typeof args["work_id"] === "string") {
+      const query = typeof args["query"] === "string" ? args["query"] : "";
+      if (query.length > 2000) throw new Error("history query is limited to 2000 characters; use a more specific query");
+      const tool = typeof args["tool"] === "string" ? args["tool"] : undefined;
+      const limit = args["limit"] === undefined ? 10 : args["limit"];
+      if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error("history limit must be 1..100");
+      const terms = query.toLowerCase().trim().split(/\s+/).filter(Boolean);
+      const matches: (HistoryEntry & { hits: { line: number; text: string }[] })[] = [];
+      let selected: readonly HistoryEntry[] = entries;
+      if (typeof args["work_id"] === "string") selected = indexed.byWork.get(args["work_id"]) ?? [];
+      if (typeof args["resource"] === "string") {
+        const resources = new Set(indexed.byResource.get(resourceKey(args["resource"])) ?? []);
+        selected = selected.filter(entry => resources.has(entry));
+      }
+      for (const entry of selected.toReversed()) {
+        if (tool !== undefined && entry.tool !== tool) continue;
+        const inline = `${entry.text}\n${canonicalValue(entry.input)}`.toLowerCase();
+        const missing = terms.filter((term) => !inline.includes(term));
+        if (missing.length > 0 && !(entry.artifact && await observationContains(archive, entry.artifact, missing))) continue;
+        // This is an index excerpt, not replacement evidence. Exact event/artifact
+        // readers retain every omitted byte, with a stable snapshot for pagination.
+        // Hits show where the terms are, so a match deep in a long observation
+        // does not force reading the whole original back (N.2).
+        matches.push({ ...entry, text: entry.text.slice(0, 200), hits: historyHits(entry.text, terms) });
+      }
+      // Keep empty-query ordering identical to the pure reference search.
+      if (terms.length === 0 && matches.length !== queryHistory(selected, "", tool).length) throw new Error("history index mismatch");
+      async function* serialized(): AsyncGenerator<Uint8Array> {
+        for (const match of matches) yield new TextEncoder().encode(JSON.stringify(match) + "\n");
+      }
+      const saved = await archiveObservation(archive, serialized(), ctx.maxOutputBytes);
+      const page = matches.slice(0, limit);
+      const render = () => JSON.stringify({ matches: matches.length, items: page,
+        full_results: { artifact: saved.ref.sha256, format: "jsonl", offset: 0 },
+        instruction: "Use event for original evidence; artifact and offset page this immutable search result." });
+      let response = render();
+      while (page.length > 0 && new TextEncoder().encode(response).length > ctx.maxOutputBytes) { page.pop(); response = render(); }
+      if (new TextEncoder().encode(response).length > ctx.maxOutputBytes) response = `history artifact: ${saved.ref.sha256}; ${matches.length} matches; offset 0`;
+      // The snapshot itself is a first-class observation so copy/fork preserves it.
+      return { ok: true, content: response, content_ref: saved.ref, content_sha256: saved.ref.sha256 };
+    }
+    if (!Number.isSafeInteger(args["node"]) || typeof args["section"] !== "string" ||
+        !(HISTORY_SECTIONS as readonly string[]).includes(args["section"])) throw new Error("history requires query, recent, event, artifact, or node and section");
+    const node = args["node"] as number;
+    if (!index.nodes.some((entry) => entry.node === node) || !history.nodes.some((entry) => entry.node === node)) throw new Error("history source must be a sealed node in the active ancestry");
+    // Fold only the events contributed to this ancestry, respecting rewind points.
+    let full: Handoff | null = null;
+    let depth = 0;
+    for (const part of history.nodes) {
+      full = deriveHandoff({ prev: full, depth: ++depth, events: part.events,
+        self: { node: part.node, log_ref: nodePath(logDir, part.node), sha256: await digestNode(logDir, part.node) },
+        config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity } });
+      if (part.node === node) break;
+    }
+    if (full === null) throw new Error("empty history");
+    const page = historyPage(full, args["section"] as HistorySection,
+      typeof args["offset"] === "number" ? args["offset"] : 0,
+      typeof args["limit"] === "number" ? Math.min(args["limit"], 100) : 20);
+    return { ok: true, ...await presentObservation(ctx, JSON.stringify({ source: full.predecessor, section: args["section"], ...page })) };
+  } catch (error) { return { ok: false, content: `history: ${String(error)}` }; }
+}
+
+async function historyValue(ctx: ToolContext, value: unknown): Promise<ToolResult> {
+  const content = JSON.stringify(value);
+  const observation = await presentObservation(ctx, content);
+  return { ok: true, ...observation, data: observation.content_ref ? { artifact: observation.content_ref, format: "json" } : JSON.parse(content) };
+}