dsh-engram 0.3.7 → 0.5.0

package/lib/preference.js

@@ -0,0 +1,276 @@
+/**
+ * dsh-engram: user-correction / preference learning — zero-LLM.
+ *
+ * Trend-driven (correx / PAHF(Meta, arXiv 2602.16173) / Mem0 preference
+ * extraction): when the user corrects or states a preference to the agent,
+ * that lesson should persist — "the AI makes a mistake and gets corrected,
+ * the lesson survives". The pull-only model left this entirely to manual
+ * engram_store calls; this module closes the gap by watching `user/message`
+ * session events and turning deterministic correction/preference cues into
+ * `preference` memories — no model call, no embeddings, pure pattern rules.
+ *
+ * Signal design (avoid false positives):
+ *   - Only strong, explicit cues are treated as preference statements
+ *     (negation "不要用X/别再用X/avoid/never use", substitution "改用X/换成X/
+ *     instead of", affirmation "prefer/please use/always use/应该用/统一用").
+ *   - A one-shot operation instruction ("运行 npm test") carries no
+ *     preference cue and is never captured.
+ *   - Interrogatives are skipped — asking "是不是用X?" is not a statement.
+ *   - The extracted clause is bounded (4..120 chars); empty/pointless clauses
+ *     fall back to no capture.
+ *   - A per-session cap and a recent-window dedup mirror the auto-capture
+ *     discipline of lib/capture.js (the store layer re-dedups by hash too).
+ *   - Captured text is <direction marker> + the extracted clause, so recall
+ *     lines read as standing rules ("prefer", "avoid", "switch-to").
+ *
+ * All functions are pure and deterministic; `now`/weights are injectable for
+ * node:test (matching lib/capture.js and lib/rerank.js).
+ */
+
+import { workspaceKey as wk } from "./util.js";
+
+/** Direction of the preference statement, used in the captured text. */
+export const PREFERENCE_DIRECTION = {
+  prefer: "prefer", // affirmative: use / prefer / always use
+  avoid: "avoid", // negative: don't use / never / stop
+  switch: "switch-to", // substitution: use X instead of Y / 改用 X
+};
+
+const PREFERENCE_SIGNAL = 0.55;
+/** Cap the per-session count of auto-captured preference memories. */
+export const DEFAULT_PREFERENCE_PER_SESSION = 8;
+
+/** Strip leading punctuation/whitespace before a clause. */
+function trimLead(s) {
+  return s.replace(/^[\s,，。;；:：、!！?？'"“”‘’()（）]+/, "").trim();
+}
+
+/** Trim a captured clause to a bounded, single-line window. */
+function boundClause(s) {
+  let t = String(s ?? "").replace(/\s*\n+\s*/g, " ").replace(/[。；;！!？?]+$/, "").trim();
+  t = trimLead(t);
+  // trailing sentence particles / connective fillers that are noise in a rule clause
+  t = t.replace(/(?:的|了|吧|啊|呢|呀|哦)$/, "").trim();
+  if (t.length > 120) t = `${t.slice(0, 120)}…`;
+  return t;
+}
+
+/** Is this user message an interrogative (asking, not stating)? */
+function isInterrogative(text) {
+  if (/[?？]\s*$/.test(text)) return true;
+  return /(是不是|可不可以|能不能|是否|有没有|好不好|行不行|该不该|要不要)/.test(text);
+}
+
+/** Skip meta-talk about our own memory tools (not a real preference). */
+function isToolMeta(text) {
+  return /(engram_|esr_|\[ENGRAM\]|\[ESR\]|\[RECALL\])/.test(text) && /(记|存|调|删|用|store|recall|remember|delete|remove)/.test(text);
+}
+
+/** A single extractor: cue regex + how to derive the clause + direction. */
+const EXTRACTORS = [
+  // ── Chinese: negation (avoidance) ────────────────────────────────────────
+  // 不要用X / 别用X / 别再用X / 不要再X / 请勿使用X / 避免用X / 不要选X…
+  {
+    re: /(?:不要|别再?|请勿|切勿|避免|禁止|严禁|尽量别)(?:再|去|要)?\s*(?:用|使用|采用|选|选择|用?到){0,2}\s*([^，。;；!！?？\n]{2,80})/,
+    kind: PREFERENCE_DIRECTION.avoid,
+  },
+  // 不要再这样 / 别这么干 (clause after a bare negation)
+  {
+    re: /(?:不要再|别这样|别这么|不要这样|不要这么)([^，。;；!！?？\n]{0,60})/,
+    kind: PREFERENCE_DIRECTION.avoid,
+  },
+  // 别/不要 bare + trailing object ("别 X" where X is a 2+ char target)
+  {
+    re: /(?:^|[\s，,;；])(?:别|不要)\s+([^，。;；!！?？\n]{2,80})/,
+    kind: PREFERENCE_DIRECTION.avoid,
+  },
+  // ── Chinese: substitution (switch-to) ─────────────────────────────────────
+  // 改用X / 换成X / 用X而不是Y / 应该用X / 统一用X / 优先用X / 尽量用X
+  {
+    re: /(?:改用|换成|换用|切到|迁移到|改用为|建议用|优先用|统一用|尽量用|应该用|应当用|就得用|最好用|记得用|请用|就用|用用看)\s*([^，。;；!！?？\n]{2,80})/,
+    kind: PREFERENCE_DIRECTION.switch,
+  },
+  {
+    re: /(?:应该|建议|可以|记得|统一|优先|最好|尽量)\s*都?\s*(?:用|选|采用?|使?用?到)\s*([^，。;；!！?？\n]{2,80})/,
+    kind: PREFERENCE_DIRECTION.switch,
+  },
+  {
+    re: /(?:用|选|采用?)\s*([^，。;；!！?？\n]{2,80})\s*(?:而|而不是|而非|别|不要)\s*(?:用|选|采用?)?\s*([^，。;；!！?？\n]{1,40})/,
+    kind: PREFERENCE_DIRECTION.switch,
+  },
+  // ── Chinese: affirmation (prefer) ────────────────────────────────────────
+  // 喜欢用X / 习惯用X / 更倾向X / 偏好X
+  {
+    re: /(?:偏好|更倾向(?:于)?|喜欢用|习惯用|爱用|常用)\s*([^，。;；!！?？\n]{2,80})/,
+    kind: PREFERENCE_DIRECTION.prefer,
+  },
+  {
+    re: /(?:以后|从现在起|之后|接下来|后面|下次)\s*(?:都|一律|统一)?\s*(?:用|选|采用?)\s*([^，。;；!！?？\n]{2,80})/,
+    kind: PREFERENCE_DIRECTION.switch,
+  },
+
+  // ── English: negation (avoidance) ─────────────────────────────────────────
+  // don't use X / do not use X / never use X / avoid X / stop using X.
+  // The clause runs to the next sentence/beginning-of-comma boundary so a
+  // short target like "var" in "never use var, always use let" survives.
+  {
+    re: /\b(?:don'?t|do not|never|stop|avoid|please don'?t|do not ever)\s+(?:use|using|pick|choose|select|go with|use?ing)?\s*([A-Za-z0-9_./@-]+(?:\s+[A-Za-z0-9_./'()@-]{1,60}){0,5})/i,
+    kind: PREFERENCE_DIRECTION.avoid,
+  },
+  // X is not allowed / no more X
+  {
+    re: /\b(?:no more|not allowed|clear|drop)\s+([A-Za-z0-9_./@-]+(?:\s+[A-Za-z0-9_./'()@-]{1,60}){0,5})/i,
+    kind: PREFERENCE_DIRECTION.avoid,
+  },
+  // ── English: substitution (switch-to) ─────────────────────────────────────
+  // use X instead (of Y) / switch to X / go with X / move to X
+  {
+    re: /\b(?:use|using|switch to|switch over to|go with|move to|migrate to|default to|prefer to use)\s+([A-Za-z0-9_./@-]+(?:\s+[A-Za-z0-9_./'()@-]{1,60}){0,5})\s*(?:instead|rather|over|from now on)?/i,
+    kind: PREFERENCE_DIRECTION.switch,
+  },
+  // instead of / rather than (primary target elsewhere)
+  {
+    re: /\b(?:instead of|rather than|as opposed to)\s+([A-Za-z0-9_./@-]+(?:\s+[A-Za-z0-9_./'()@-]{1,60}){0,5})/i,
+    kind: PREFERENCE_DIRECTION.avoid,
+  },
+  // ── English: affirmation (prefer) ─────────────────────────────────────────
+  {
+    re: /\b(?:i prefer|prefer|i like|like using|usually use|always use|we use|please use)\s+([A-Za-z0-9_./@-]+(?:\s+[A-Za-z0-9_./'()@-]{1,60}){0,5})/i,
+    kind: PREFERENCE_DIRECTION.prefer,
+  },
+];
+
+/**
+ * Extract a preference statement from user message text, or null when the
+ * message carries no explicit correction/preference cue. Pure + deterministic.
+ *
+ * @param {string} text user message text
+ * @returns {{ clause: string, direction: string, text: string, tags: string[] } | null}
+ */
+export function extractPreference(text) {
+  if (typeof text !== "string" || text.trim().length === 0) return null;
+  const src = text.trim();
+  if (src.length < 6 || src.length > 2000) return null;
+  if (isInterrogative(src)) return null;
+  if (isToolMeta(src)) return null;
+
+  for (const ex of EXTRACTORS) {
+    const m = src.match(ex.re);
+    if (!m) continue;
+    // A clause may be a short but meaningful target ("var"); 2 chars minimum.
+    let clause = boundClause(m[1] ?? "");
+    if (clause.length < 2 || clause.length > 120) continue;
+    const direction = ex.kind;
+    const marker = direction === PREFERENCE_DIRECTION.avoid ? "avoid" : direction === PREFERENCE_DIRECTION.switch ? "switch-to" : "prefer";
+    const lang = /[\u4e00-\u9fff]/.test(clause) ? "zh" : "en";
+    return {
+      clause,
+      direction,
+      text: `user ${marker}: ${clause}`,
+      tags: ["preference", "user", marker, lang, "auto-captured"],
+    };
+  }
+  return null;
+}
+
+/**
+ * Install the `session/event` listener that captures user corrections and
+ * preferences as `preference` memories. Mirrors installGoalCapture's
+ * containment + lazy adapter pattern: `storeAdapter` is any
+ * { storeMemory(entry) -> Promise } face, resolved per event, with a
+ * per-session capture cap and a recent-window dedup. Returns the disposer.
+ *
+ * @param {object} ctx cordis scoped context (ctx.on available)
+ * @param {object} storeAdapter { storeMemory({workspace,kind,text,tags,signal,filePath,sessionId,seq}) -> Promise }
+ * @param {object} config { autoCapturePreferences, preferenceCapturePerSession }
+ * @param {object} [log]
+ * @param {object} [stats] optional mutable {total, preference} counters
+ */
+export function installPreferenceCapture(ctx, storeAdapter, config, log, stats) {
+  if (config?.autoCapturePreferences === false) {
+    // still install a no-op listener? No — return a no-op disposer so callers
+    // can always dispose without branching on config.
+    return () => {};
+  }
+  const cap = Number.isInteger(config?.preferenceCapturePerSession)
+    ? config.preferenceCapturePerSession
+    : DEFAULT_PREFERENCE_PER_SESSION;
+  const perSession = new Map(); // sessionId -> count
+  const recent = new Set(); // `${workspace}|${text}` recent-window dedup
+
+  const onEvent = (session, event) => {
+    try {
+      if (event?.type !== "user/message") return;
+      // Only learn from the human user's own messages. The harness also emits
+      // user/message events for injected context (runtime-context, skill-catalog
+      // snapshots, etc.) — those are instructions to the model, not corrections
+      // the user is teaching us, and must never become preference memories.
+      if (event.data?.source?.kind !== "user") return;
+      const cwd = session?.header?.cwd;
+      const sessionId = session?.id;
+      if (typeof cwd !== "string" || cwd.length === 0) return;
+      if (typeof sessionId !== "string" || sessionId.length === 0) return;
+
+      const text = messageText(event.data);
+      if (text.length === 0) return;
+
+      const extracted = extractPreference(text);
+      if (extracted === null) return;
+
+      const used = perSession.get(sessionId) ?? 0;
+      if (used >= cap) return;
+      perSession.set(sessionId, used + 1);
+
+      const key = `${wk(cwd)}|${extracted.text}`;
+      if (recent.has(key)) return;
+      recent.add(key);
+      if (recent.size > 500) {
+        const first = recent.values().next().value;
+        recent.delete(first);
+      }
+
+      if (stats) {
+        stats.total = (stats.total ?? 0) + 1;
+        stats.preference = (stats.preference ?? 0) + 1;
+      }
+
+      storeAdapter
+        .storeMemory(
+          {
+            workspace: wk(cwd),
+            kind: "preference",
+            text: extracted.text,
+            tags: extracted.tags,
+            signal: PREFERENCE_SIGNAL,
+            filePath: null,
+            sessionId,
+            seq: Array.isArray(session.events) ? session.events.length : 0,
+          },
+          config,
+        )
+        .then(() => {})
+        .catch((error) => log?.warn?.(`engram preference capture failed: ${String(error)}`));
+    } catch (error) {
+      // fully contained — a capture bug must never disturb the session pipeline
+      log?.warn?.(`engram preference capture threw: ${String(error)}`);
+    }
+  };
+  return ctx.on("session/event", onEvent);
+}
+
+/**
+ * Extract plain text from a `user/message` event data payload. Mirrors the
+ * shape understood by index-block.firstUserMessageText: `content` is an
+ * array of blocks each with `.text`, or a single `.text` field. Pure.
+ */
+export function messageText(data) {
+  if (data === null || typeof data !== "object") return "";
+  const blocks = Array.isArray(data.content) ? data.content : [];
+  if (blocks.length > 0) {
+    return blocks
+      .map((b) => (b !== null && typeof b === "object" && typeof b.text === "string" ? b.text : ""))
+      .join(" ")
+      .trim();
+  }
+  return typeof data.text === "string" ? data.text.trim() : "";
+}

package/lib/result-pack.js

@@ -0,0 +1,276 @@
+/**
+ * dsh-engram ResultPack L2 (PROPOSAL-resultpack §L2): archive pruned tool-result
+ * middles + `result_recall` paged recall — the ObservationPack pattern SoL-Pi
+ * mechanism ③ (load archived, keep a handle + digest on the surface, page back
+ * on demand; its paired EdgeBench: bill −23.58%).
+ *
+ * L1 (lib/boundary-prune.js) prunes over-threshold tool results at todo/goal
+ * boundaries through DSH's own deterministic `toolResultPruner`. The L1 pruned
+ * middle was simply gone — the model could not reach it again. L2 makes the
+ * prune lossless:
+ *
+ *   1. When L1 fires, we read the ORIGINAL result from the session log
+ *      (`session.eventAt(originalSeq)` + `deriveEventMessage`), extract the
+ *      removed middle span, redact secrets (same rules as the memory write
+ *      path), and archive it to a per-callId JSON file under
+ *      `~/.dsh/engram/resultpack/`.
+ *   2. We append a tail handle to the pruned surface node via the host's own
+ *      surface-replace protocol (append tool/result + surfaceOp replace,
+ *      replay-safe): `[middle archived: result_recall(<callId>) 可取]`.
+ *      The model decides whether to drill down — the same progressive
+ *      disclosure philosophy as [ENGRAM] → engram_detail.
+ *   3. `result_recall(callId, offset?)` returns the archived middle in paged
+ *      text blocks, so a very large result is never re-materialized whole.
+ *
+ * Zero-LLM, deterministic, fail-contained (never throws into the session
+ * pipeline); every write is atomic temp-file + rename. Retention is a simple
+ * mtime sweep (`sweepExpired`), wired to the same GC cadence as memory GC.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { redactText } from "./redact.js";
+import { hashText, workspaceKey as wk, truncate } from "./util.js";
+
+/** Default page budget for result_recall (chars per page). */
+export const DEFAULT_PAGE_CHARS = 4000;
+/** Default retention for archived results (mtime-based sweep). */
+export const DEFAULT_RETENTION_DAYS = 7;
+/** Handle line appended to the pruned surface node. */
+const HANDLE_PREFIX = "[middle archived: result_recall(";
+
+/** Archived-result directory under the engram home (~/.dsh/engram/resultpack). */
+export function resultPackDir(home = path.join(os.homedir(), ".dsh", "engram")) {
+  return path.join(home, "resultpack");
+}
+
+/** Stable, path-safe archive id derived from the tool callId. */
+export function archiveId(callId) {
+  return `${hashText(String(callId))}`;
+}
+
+/** Read one archived result back (parsed), or undefined when absent/broken. */
+export function readArchived(dir, callId) {
+  try {
+    const file = path.join(dir, `${archiveId(callId)}.json`);
+    if (!fs.existsSync(file)) return void 0;
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+
+/**
+ * Extract the removed middle text from an original tool-result content and the
+ * host pruner budgets. Mirrors host arithmetic (code-point slicing across text
+ * blocks: everything between headChars and total-tailChars is the middle).
+ * @param blocks - original message content (blocks with `.type`/`.text`).
+ * @param headChars - pruner head budget.
+ * @param tailChars - pruner tail budget.
+ * @returns { removed: string, head: string, tail: string } or null when nothing removed.
+ */
+export function extractMiddle(blocks, headChars, tailChars) {
+  if (!Array.isArray(blocks)) return null;
+  const total = blocks.reduce((n, b) => (b && b.type === "text" ? n + Array.from(String(b.text)).length : n), 0);
+  const removedStart = headChars;
+  const removedEnd = total - tailChars;
+  if (total <= removedStart + tailChars || removedEnd <= removedStart) return null;
+  const removed = [];
+  const head = [];
+  const tail = [];
+  let consumed = 0;
+  for (const block of blocks) {
+    if (!block || block.type !== "text") continue;
+    const points = Array.from(String(block.text));
+    const blockStart = consumed;
+    const blockEnd = blockStart + points.length;
+    const headEnd = Math.min(points.length, Math.max(0, removedStart - blockStart));
+    const tailStart = Math.min(points.length, Math.max(0, removedEnd - blockStart));
+    head.push(points.slice(0, headEnd).join(""));
+    if (tailStart > headEnd) removed.push(points.slice(headEnd, tailStart).join(""));
+    tail.push(points.slice(tailStart).join(""));
+    consumed = blockEnd;
+  }
+  return {
+    removed: removed.join(""),
+    head: head.join(""),
+    tail: tail.join(""),
+  };
+}
+
+/**
+ * Archive the pruned middles from one L1 prune report, appending a tail handle
+ * on each pruned surface node. Returns the count archived. Never throws.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir archive directory
+ * @param {object} opts.session the session being pruned (eventAt + deriveEventMessage)
+ * @param {object} opts.report the host pruner's return `{ pruned, charsRemoved }`
+ * @param {string} [opts.workspace] workspace key used on the archive metadata
+ * @param {object} [opts.log]
+ * @returns {number} archives written
+ */
+export function archivePrunedResults({ dir, session, report, workspace, log }) {
+  const pruned = report?.pruned;
+  if (!Array.isArray(pruned) || pruned.length === 0) return 0;
+  let archived = 0;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (error) {
+    log?.warn?.(`engram result-pack: archive dir unavailable: ${String(error)}`);
+    return 0;
+  }
+  for (const item of pruned) {
+    try {
+      const callId = item?.callId;
+      if (typeof callId !== "string" || callId.length === 0) continue;
+      const original = item.originalSeq !== void 0 ? session?.eventAt?.(item.originalSeq) : void 0;
+      const message = original ? session?.deriveEventMessage?.(original) : void 0;
+      const blocks = message?.content;
+      // Fall back to a default budget when the report lacks head/tail (the host
+      // report carries charsBefore/After only; budgets default to host DEFAULTS).
+      const mine = extractMiddle(blocks, item.headChars ?? 4096, item.tailChars ?? 1024);
+      const removed = mine?.removed ?? "";
+      if (removed.length === 0) continue;
+      const record = {
+        v: 1,
+        callId,
+        workspace: workspace ?? wk(message?.source?.workspace ?? ""),
+        sessionId: item.sessionId ?? session?.id ?? null,
+        originalSeq: item.originalSeq ?? null,
+        createdAt: Date.now(),
+        headChars: item.headChars ?? 4096,
+        tailChars: item.tailChars ?? 1024,
+        charsBefore: item.charsBefore ?? removed.length,
+        charsAfter: item.charsAfter ?? (item.headChars ?? 4096) + (item.tailChars ?? 1024),
+        head: truncate(mine?.head ?? "", 2000),
+        tail: truncate(mine?.tail ?? "", 2000),
+        // Redacted before persistence — the memory path's guarantee holds here.
+        removed: redactText(removed),
+      };
+      const file = path.join(dir, `${archiveId(callId)}.json`);
+      const tmp = `${file}.${hashText(String(Date.now() + Math.random()))}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(record), "utf8");
+      fs.renameSync(tmp, file);
+      archived += 1;
+      appendHandle({ session, callId, replacementSeq: item.replacementSeq, log });
+    } catch (error) {
+      log?.warn?.(`engram result-pack: archive failed: ${String(error)}`);
+    }
+  }
+  return archived;
+}
+
+/**
+ * Append a `[middle archived: result_recall(callId) 可取]` tail to one pruned
+ * surface node using the host's own surface-replace protocol (append a
+ * tool/result +++ surfaceOp replace; replay-safe, zero-LLM). Never throws.
+ */
+export function appendHandle({ session, callId, replacementSeq, log }) {
+  try {
+    if (!session || typeof session.append !== "function") return;
+    const seq = replacementSeq;
+    if (seq === void 0) return;
+    const node = session.eventAt?.(seq);
+    if (!node || node.type !== "tool/result") return;
+    const current = session.deriveEventMessage?.(node);
+    if (!current) return;
+    const handleText = `${HANDLE_PREFIX}${callId}) 可取]`;
+    const content = Array.isArray(current.content) ? [...current.content] : [];
+    // Avoid stacking duplicate handles on repeated prunes of the same node.
+    if (content.some((b) => b && typeof b.text === "string" && b.text.includes(HANDLE_PREFIX))) return;
+    content.push({ type: "text", text: handleText });
+    const message = { ...current, content };
+    session.append("tool/result", { ...node.data, message }, {
+      surfaceOp: { op: "replace", startSeq: seq, endSeq: seq },
+      sourceEventSeqs: [seq],
+    });
+  } catch (error) {
+    log?.warn?.(`engram result-pack: handle append failed: ${String(error)}`);
+  }
+}
+
+/**
+ * Page out one archived middle. Pure + deterministic.
+ * @param {object} archived parsed archive record
+ * @param {number} [offset] zero-based page index
+ * @param {number} [pageChars] chars per page
+ * @returns {{ total, totalChars, offset, page, hasMore, text, callId }}
+ */
+export function pageArchived(archived, offset = 0, pageChars = DEFAULT_PAGE_CHARS) {
+  const totalChars = Array.from(String(archived?.removed ?? "")).length;
+  const total = Math.max(1, Math.ceil(totalChars / pageChars));
+  const idx = Number.isFinite(offset) && offset >= 0 ? Math.floor(offset) : 0;
+  const p = Math.min(idx, total - 1);
+  const chars = Array.from(String(archived?.removed ?? ""));
+  const text = chars.slice(p * pageChars, (p + 1) * pageChars).join("");
+  return {
+    callId: archived?.callId ?? null,
+    total,
+    totalChars,
+    offset: p,
+    page: p + 1,
+    hasMore: p + 1 < total,
+    text,
+  };
+}
+
+/**
+ * Sweep archives whose mtime is older than `retentionDays`. Returns deleted
+ * count. Never throws.
+ */
+export function sweepExpired(dir, retentionDays = DEFAULT_RETENTION_DAYS) {
+  let deleted = 0;
+  try {
+    if (!fs.existsSync(dir)) return 0;
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith(".json")) continue;
+      const file = path.join(dir, name);
+      try {
+        if (fs.statSync(file).mtimeMs < cutoff) {
+          fs.unlinkSync(file);
+          deleted += 1;
+        }
+      } catch { /* racing removal — ignore */ }
+    }
+  } catch { /* unreadable dir — ignore */ }
+  return deleted;
+}
+
+/**
+ * The model-facing tool definition: `result_recall(callId, offset?)`.
+ * Independent of the memory domain (archives live on the filesystem). Reads
+ * are workspace-sandboxed by callerOf-style cwd resolution, but the archive is
+ * keyed by globally-unique callId, so we just return the archive when found.
+ */
+export function resultRecallTool(dir, pageChars = DEFAULT_PAGE_CHARS) {
+  return {
+    name: "result_recall",
+    description: "Retrieve an archived pruned tool-result middle by its callId (page 1 by default). The handle line inside a pruned result names the callId. Returns one page of the original middle text; paging is 0-based via offset.",
+    parameters: {
+      type: "object",
+      properties: {
+        callId: { type: "string", description: "callId from a `[middle archived: result_recall(<callId>) 可取]` handle (required)" },
+        offset: { type: "number", description: "Zero-based page index to return (default 0)", minimum: 0 },
+      },
+      required: ["callId"],
+    },
+    output: {
+      schema: { type: "string" },
+      render: (_args, value) => [{ type: "text", text: String(value) }],
+    },
+    execute: async (raw) => {
+      const callId = typeof raw?.callId === "string" ? raw.callId.trim() : "";
+      if (callId.length === 0) return "result_recall: callId is required";
+      const offset = Number.isFinite(raw?.offset) ? Math.floor(raw.offset) : 0;
+      const archived = readArchived(dir, callId);
+      if (archived === void 0) return `result_recall: no archived middle for callId ${callId} (expired or never archived)`;
+      const page = pageArchived(archived, offset, pageChars);
+      const header = `result_recall ${callId} · page ${page.page}/${page.total} · ${page.totalChars} chars archived${page.hasMore ? ` · offset=${page.offset + 1} 取下一页` : ""}\n\n`;
+      return header + page.text;
+    },
+  };
+}