@openviking/opencode-plugin 0.2.3 → 2026.9.9-1

package/lib/shared/input-filters.mjs

@@ -0,0 +1,219 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Ordered, operator-configured regex filters for memory plugin input.
+ *
+ * Rules are sed-style strings, applied in order to a single piece of text:
+ *   s/^\s*ultrathink\s+//i   substitute (add `g` to replace every match)
+ *   d|^\s*[/!]|              drop the text when the pattern matches
+ *   k/^\?ov\b/               keep the text only when the pattern matches
+ *   user:d/^\s*\/clear\b/    apply to one role only
+ *
+ * A malformed rule becomes an entry in `errors` and is skipped rather than
+ * throwing, so a typo in a config file cannot take a hook down.
+ */
+
+const OPS = new Set(["s", "d", "k"]);
+const SCOPES = ["user", "assistant"];
+const ALLOWED_FLAGS = "imsug";
+
+export const INPUT_FILTER_KNOBS = [
+  {
+    key: "recallQueryFilters",
+    env: "OPENVIKING_RECALL_QUERY_FILTERS",
+    label: "recall query filters",
+  },
+  {
+    key: "captureFilters",
+    env: "OPENVIKING_CAPTURE_FILTERS",
+    label: "capture filters",
+  },
+];
+
+/**
+ * Read one delimited field. `\` always consumes the next character, and only
+ * `\<delim>` is un-escaped, so `\d` / `\b` / `\x2c` reach RegExp verbatim.
+ * Returns the index of the closing delimiter, or -1 when it is missing.
+ */
+function scanField(source, start, delim) {
+  let out = "";
+  let i = start;
+  while (i < source.length) {
+    const c = source[i];
+    if (c === "\\") {
+      const next = source[i + 1];
+      if (next === undefined) {
+        out += "\\";
+        i += 1;
+        continue;
+      }
+      out += next === delim ? next : "\\" + next;
+      i += 2;
+      continue;
+    }
+    if (c === delim) return { value: out, end: i };
+    out += c;
+    i += 1;
+  }
+  return { value: out, end: -1 };
+}
+
+export function parseInputFilterRule(source) {
+  if (typeof source !== "string") {
+    return { source: String(source ?? ""), error: "rule must be a string" };
+  }
+  const raw = source.trim();
+  if (!raw) return { source: raw, error: "rule is empty" };
+
+  let scope = "";
+  let rest = raw;
+  for (const candidate of SCOPES) {
+    if (rest.startsWith(`${candidate}:`)) {
+      scope = candidate;
+      rest = rest.slice(candidate.length + 1);
+      break;
+    }
+  }
+
+  const op = rest[0] || "";
+  if (!OPS.has(op)) {
+    return {
+      source: raw,
+      error: `unknown operation "${op}" — expected s (substitute), d (drop) or k (keep)`,
+    };
+  }
+  const delim = rest[1];
+  if (delim === undefined) {
+    return { source: raw, error: `missing delimiter after "${op}"` };
+  }
+  if (/[A-Za-z0-9\s\\]/.test(delim)) {
+    return {
+      source: raw,
+      error: `invalid delimiter ${JSON.stringify(delim)} — use punctuation such as / | # or :`,
+    };
+  }
+
+  const first = scanField(rest, 2, delim);
+  const pattern = first.value;
+  let replacement = null;
+  let flagsRaw = "";
+  if (op === "s") {
+    if (first.end < 0) {
+      return { source: raw, error: `missing ${JSON.stringify(delim)} after the pattern` };
+    }
+    const second = scanField(rest, first.end + 1, delim);
+    if (second.end < 0) {
+      return {
+        source: raw,
+        error: `missing ${JSON.stringify(delim)} after the replacement — write s${delim}pattern${delim}replacement${delim}`,
+      };
+    }
+    replacement = second.value;
+    flagsRaw = rest.slice(second.end + 1);
+  } else {
+    flagsRaw = first.end < 0 ? "" : rest.slice(first.end + 1);
+  }
+
+  if (!pattern) return { source: raw, error: "pattern is empty" };
+
+  const flags = new Set();
+  for (const flag of flagsRaw) {
+    if (!ALLOWED_FLAGS.includes(flag)) {
+      return { source: raw, error: `unknown flag "${flag}" — allowed flags are i, m, s, u, g` };
+    }
+    if (flags.has(flag)) return { source: raw, error: `duplicate flag "${flag}"` };
+    flags.add(flag);
+  }
+  // d/k decide with .test(), which advances lastIndex on a global regex and
+  // would then alternate between calls. `g` means nothing there, so drop it.
+  if (op !== "s") flags.delete("g");
+
+  let re;
+  try {
+    re = new RegExp(pattern, [...flags].join(""));
+  } catch (err) {
+    // V8 already says "Invalid regular expression: <pattern>: <why>"; keep that
+    // detail without stuttering the prefix the doctors key off.
+    const message = err?.message || String(err);
+    return {
+      source: raw,
+      error: /^invalid regular expression/i.test(message)
+        ? `invalid${message.slice("Invalid".length)}`
+        : `invalid regular expression: ${message}`,
+    };
+  }
+
+  return { op, scope, re, replacement, source: raw };
+}
+
+export function compileInputFilters(rules) {
+  const compiled = [];
+  const errors = [];
+  const list = Array.isArray(rules) ? rules : [];
+  list.forEach((entry, index) => {
+    if (typeof entry !== "string") {
+      errors.push({ index, source: String(entry ?? ""), message: "rule must be a string" });
+      return;
+    }
+    if (!entry.trim()) return;
+    const parsed = parseInputFilterRule(entry);
+    if (parsed.error) errors.push({ index, source: parsed.source, message: parsed.error });
+    else compiled.push({ ...parsed, index });
+  });
+  return { rules: compiled, errors };
+}
+
+/**
+ * Run compiled rules over `text`.
+ *
+ * `substituteOnly` skips the d/k operations, so a caller that already took one
+ * drop decision for a turn can rewrite its individual pieces without taking a
+ * second, possibly contradictory one.
+ */
+export function applyInputFilters(text, compiled, { role = "", substituteOnly = false } = {}) {
+  const original = typeof text === "string" ? text : String(text ?? "");
+  let current = original;
+  for (const rule of Array.isArray(compiled) ? compiled : []) {
+    if (rule.scope && rule.scope !== role) continue;
+    if (rule.op === "s") {
+      current = current.replace(rule.re, rule.replacement);
+      continue;
+    }
+    if (substituteOnly) continue;
+    const matched = rule.re.test(current);
+    if ((rule.op === "d" && matched) || (rule.op === "k" && !matched)) {
+      return { text: "", changed: false, dropped: true, ruleIndex: rule.index, op: rule.op };
+    }
+  }
+  const finalText = current.trim();
+  return {
+    text: finalText,
+    changed: finalText !== original,
+    dropped: false,
+    ruleIndex: -1,
+    op: "",
+  };
+}
+
+/** Doctor-facing summary of both filter knobs on a resolved plugin config. */
+export function describeInputFilters(cfg = {}) {
+  return INPUT_FILTER_KNOBS.map(({ key, env, label }) => {
+    const configured = Array.isArray(cfg?.[key]) ? cfg[key] : [];
+    const compiled = compileInputFilters(configured);
+    const ops = { s: 0, d: 0, k: 0 };
+    for (const rule of compiled.rules) ops[rule.op] += 1;
+    const bits = [];
+    if (ops.s) bits.push(`${ops.s} substitute`);
+    if (ops.d) bits.push(`${ops.d} drop`);
+    if (ops.k) bits.push(`${ops.k} keep-only`);
+    const active = compiled.rules.length;
+    return {
+      key,
+      env,
+      label,
+      total: configured.length,
+      active,
+      summary: `${active} rule${active === 1 ? "" : "s"}${bits.length ? ` (${bits.join(", ")})` : ""}`,
+      errors: compiled.errors,
+    };
+  });
+}

package/lib/shared/mcp-proxy-config.mjs

@@ -0,0 +1,124 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Shared config shaping for the stdio MCP proxy entrypoints.
+ *
+ * Every harness loads its credentials differently, but the shape
+ * `createOpenVikingMcpProxy` consumes is identical everywhere, and so is the
+ * set of files whose changes must trigger a credential reload. Keeping that
+ * here stops each entrypoint from re-deriving `~` expansion, URL trimming,
+ * timeout clamping, and the watch list.
+ */
+
+import { homedir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+
+export const DEFAULT_PROXY_TIMEOUT_MS = 15000;
+const MIN_PROXY_TIMEOUT_MS = 1000;
+
+export function trimSlash(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+/** Expand a leading `~` and resolve to an absolute path; "" stays "". */
+export function normalizeConfigPath(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  if (raw === "~") return homedir();
+  if (raw.startsWith("~/")) return resolvePath(join(homedir(), raw.slice(2)));
+  return resolvePath(raw);
+}
+
+/**
+ * The credential files every harness must watch: the two `OPENVIKING_*_FILE`
+ * overrides and the two default locations under `~/.openviking`.
+ */
+export function defaultCredentialPaths(env = process.env) {
+  return [
+    normalizeConfigPath(env.OPENVIKING_CLI_CONFIG_FILE),
+    normalizeConfigPath(env.OPENVIKING_CONFIG_FILE),
+    join(homedir(), ".openviking", "ovcli.conf"),
+    join(homedir(), ".openviking", "ov.conf"),
+  ].filter(Boolean);
+}
+
+/**
+ * Resolve the actor peer header for a long-lived MCP proxy process.
+ *
+ * MCP servers may start in the plugin directory rather than the active
+ * workspace, so their process cwd is not a reliable peer identity — and unlike
+ * a hook, a long-lived proxy cannot re-derive one per turn. Broad recall
+ * intentionally spans the authenticated user's peer workspaces and therefore
+ * leaves the actor header unset. Actor-scoped recall needs an explicit peer so
+ * isolation never depends on the proxy's launch directory.
+ *
+ * A missing one degrades to broad recall with a warning rather than refusing to
+ * start: the proxy is what carries every memory tool, and taking those away
+ * because a scope preference cannot be honoured costs the user far more than
+ * the wider search does. Only the harness whose parent process injects the peer
+ * (dsh, `mcp.mjs:27`) can satisfy this without the user setting it.
+ */
+export function resolveMcpActorPeerId({
+  peerId = "",
+  recallPeerScope = "all",
+  onWarn = null,
+} = {}) {
+  if (recallPeerScope !== "actor") return "";
+
+  const explicitPeerId = String(peerId || "").trim();
+  if (explicitPeerId) return explicitPeerId;
+
+  const message = "OpenViking MCP: actor-scoped recall needs an explicit peer id, which an MCP proxy cannot "
+    + "derive from its launch directory. Falling back to broad recall across every peer under this user. "
+    + "Set actor_peer_id in ovcli.conf, or OPENVIKING_PEER_ID in the MCP server environment, to scope it.";
+  if (typeof onWarn === "function") onWarn(message);
+  else process.stderr.write(`${message}\n`);
+  return "";
+}
+
+function uniq(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+/**
+ * Shape a harness's loaded config into the object `createOpenVikingMcpProxy`
+ * expects.
+ *
+ * `mcpUrl` wins over `baseUrl` when both are given, so a harness that lets the
+ * user pin an explicit MCP URL keeps that behavior. `watchedPaths` are the
+ * harness's own extra files; the shared defaults are appended and the result
+ * deduplicated.
+ */
+export function buildMcpProxyConfig({
+  baseUrl = "",
+  mcpUrl = "",
+  apiKey = "",
+  account = "",
+  user = "",
+  peerId = "",
+  userAgent = "",
+  timeoutMs,
+  debug = false,
+  debugLogPath = "",
+  credentialSource = "auto",
+  credentialPath = "",
+  watchedPaths = [],
+  env = process.env,
+} = {}) {
+  return {
+    mcpUrl: mcpUrl || `${trimSlash(baseUrl)}/mcp`,
+    apiKey: apiKey || "",
+    account: account || "",
+    user: user || "",
+    peerId: peerId || "",
+    userAgent: userAgent || "",
+    timeoutMs: Math.max(
+      MIN_PROXY_TIMEOUT_MS,
+      Number(timeoutMs) || DEFAULT_PROXY_TIMEOUT_MS,
+    ),
+    debug: debug === true,
+    debugLogPath,
+    credentialSource: credentialSource || "auto",
+    credentialPath: credentialPath || "",
+    watchedPaths: uniq([...watchedPaths, ...defaultCredentialPaths(env)]),
+  };
+}

package/lib/shared/mcp-proxy-core.mjs

@@ -142,6 +142,7 @@ export function createOpenVikingMcpProxy({
   readConfig,
   loggerFactory,
   fetchImpl = globalThis.fetch,
+  localToolProvider = null,
 } = {}) {
   if (typeof fetchImpl !== "function") {
     throw new Error("global fetch is required; use Node.js 18 or newer");
@@ -179,6 +180,43 @@ export function createOpenVikingMcpProxy({
     } catch { /* debug logging must never affect protocol IO */ }
   }
 
+  function localTools() {
+    if (!localToolProvider || typeof localToolProvider.listTools !== "function") return [];
+    const tools = localToolProvider.listTools();
+    return Array.isArray(tools) ? tools : [];
+  }
+
+  function appendLocalTools(message, outbound) {
+    if (message.method !== "tools/list" || !Array.isArray(outbound?.result?.tools)) {
+      return outbound;
+    }
+    const additions = localTools().filter((tool) => tool?.name);
+    if (additions.length === 0) return outbound;
+    const localNames = new Set(additions.map((tool) => tool.name));
+    const upstreamTools = outbound.result.tools.filter((tool) => !localNames.has(tool?.name));
+    return {
+      ...outbound,
+      result: {
+        ...outbound.result,
+        tools: [...upstreamTools, ...additions],
+      },
+    };
+  }
+
+  async function callLocalTool(message) {
+    if (
+      message.method !== "tools/call"
+      || !localToolProvider
+      || typeof localToolProvider.callTool !== "function"
+    ) {
+      return null;
+    }
+    const name = message.params?.name;
+    if (!localTools().some((tool) => tool?.name === name)) return null;
+    reloadIfCredentialFilesChanged("local_tool_call");
+    return localToolProvider.callTool(message.params, { config: proxyConfig });
+  }
+
   function reloadConfig(reason) {
     proxyConfig = readConfig();
     logger = loggerFactory("mcp-proxy", proxyConfig);
@@ -215,6 +253,7 @@ export function createOpenVikingMcpProxy({
     if (proxyConfig.account) headers["X-OpenViking-Account"] = proxyConfig.account;
     if (proxyConfig.user) headers["X-OpenViking-User"] = proxyConfig.user;
     if (proxyConfig.peerId) headers["X-OpenViking-Actor-Peer"] = proxyConfig.peerId;
+    if (proxyConfig.userAgent) headers["User-Agent"] = proxyConfig.userAgent;
     return headers;
   }
 
@@ -253,10 +292,22 @@ export function createOpenVikingMcpProxy({
       );
     }
     const msg = err instanceof Error ? err.message : String(err);
+    if (err && err.name === "AbortError") {
+      // Client-side timeout, not an outage: the server may be healthy and
+      // still computing (rerank-inclusive find/search can legitimately take
+      // longer than the default budget). Keep -32001 for genuine
+      // connection failures so the two are not misdiagnosed as each other.
+      return errorResponse(
+        id,
+        -32004,
+        `OpenViking MCP request timed out after ${proxyConfig.timeoutMs}ms (${proxyConfig.mcpUrl}). The server may still be processing (rerank can be slow) — check /health or raise OPENVIKING_TIMEOUT_MS.`,
+        { timeoutMs: proxyConfig.timeoutMs, mcpUrl: proxyConfig.mcpUrl, cause: msg },
+      );
+    }
     return errorResponse(
       id,
       -32001,
-      `OpenViking MCP request failed. Check the configured URL (${proxyConfig.mcpUrl}) and that 'ov serve' is running.`,
+      `OpenViking MCP request failed. Check the configured URL (${proxyConfig.mcpUrl}) and that the OpenViking server (\`openviking-server\`) is reachable.`,
       { cause: msg },
     );
   }
@@ -381,6 +432,13 @@ export function createOpenVikingMcpProxy({
     }
 
     try {
+      const localResult = await callLocalTool(message);
+      if (localResult !== null) {
+        if (expectsResponse) {
+          await writeMessage({ jsonrpc: "2.0", id: message.id, result: localResult });
+        }
+        return;
+      }
       const send = sendWithRetry(message, { expectsResponse });
       if (message.method === "initialize") {
         initializeInFlight = send
@@ -396,7 +454,7 @@ export function createOpenVikingMcpProxy({
         return;
       }
       for (const outbound of result.messages) {
-        await writeMessage(outbound);
+        await writeMessage(appendLocalTools(message, outbound));
       }
     } catch (err) {
       if (expectsResponse) {

package/lib/shared/pending-queue.mjs

@@ -24,6 +24,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
 
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_TTL_DAYS = 7;
@@ -109,9 +110,7 @@ function pendingFromProcessingFilename(filename) {
 }
 
 function isRetryableReplayFailure(res) {
-  if (!res || res.ok) return false;
-  const status = Number(res.status || 0);
-  return !status || status >= 500 || status === 408 || status === 429;
+  return isRetryableFailure(res);
 }
 
 async function readEntry(dir, filename) {
@@ -410,6 +409,17 @@ export async function replayPending(fetchJSON, log) {
       res = { ok: false };
     }
 
+    if (entry.type === "commitSession") {
+      log("pending-queue", {
+        action: "commit-replay",
+        sessionId: entry.sessionId,
+        ok: Boolean(res?.ok),
+        status: res?.result?.status || res?.status,
+        trace_id: res?.traceId || res?.result?.trace_id,
+        error: res?.ok ? undefined : res?.error?.message || res?.error?.code,
+      });
+    }
+
     if (res?.ok) {
       await dequeue(claimedFilename);
       replayed++;

package/lib/shared/recall-compress-core.mjs

@@ -0,0 +1,206 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export const NO_RELEVANT_MEMORY = "NO_RELEVANT_MEMORY";
+export const DIGEST_HEADER = "OpenViking memory digest:";
+const COMPRESS_OK = "ok";
+const COMPRESS_EMPTY = "empty";
+const COMPRESS_FAILED = "failed";
+
+// Medium-constraint prompt: state the goal and two structural floors, but no hard
+// bullet-length contract. Hard per-bullet limits pin the digest to headline
+// density; leaving it unconstrained lets small models rewrite long URIs into dead
+// links, which the URI repair below cleans up.
+export function buildRecallCompressionPrompt({ query, rendered, maxBullets = 6 }) {
+  return `You are a memory relevance compressor utility.
+Do not use any tools. Do not investigate. Only transform the given text.
+
+User query:
+${query}
+
+Retrieved OpenViking context fragments:
+${rendered}
+
+Write a memory digest for a coding agent about to answer that query. Keep the
+concrete facts (paths, identifiers, decisions, constraints); drop pleasantries
+and conversational filler.
+
+Format rules:
+- Group related facts by topic, one bullet per topic, at most ${maxBullets} bullets.
+- Start every bullet with "- ".
+- End every bullet with its source, copied verbatim from the fragments above:
+  "来源：viking://..." or "source: viking://...". Never edit, shorten, or invent a URI.
+- Output the digest body only. No preamble, no closing remark.
+
+If nothing above is relevant to the query, output exactly: ${NO_RELEVANT_MEMORY}`;
+}
+
+function editDistance(a, b) {
+  if (a === b) return 0;
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  let prev = Array.from({ length: cols }, (_, i) => i);
+  for (let i = 1; i < rows; i += 1) {
+    const cur = [i];
+    for (let j = 1; j < cols; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = cur;
+  }
+  return prev[cols - 1];
+}
+
+function nearestUri(candidate, validUris) {
+  let best = "";
+  let bestDistance = Infinity;
+  for (const uri of validUris) {
+    const distance = editDistance(candidate, uri);
+    if (distance < bestDistance) {
+      best = uri;
+      bestDistance = distance;
+    }
+  }
+  // Only repair near-misses; an unrelated hallucination is dropped instead.
+  const tolerance = Math.max(4, Math.floor(candidate.length * 0.25));
+  return bestDistance <= tolerance ? best : "";
+}
+
+/**
+ * Small models occasionally mangle long URIs. Snap every cited URI back onto the
+ * set the server actually returned, and drop bullets whose citation cannot be
+ * recovered so the digest never carries a dead link.
+ */
+export function repairDigestUris(digest, validUris = []) {
+  const text = String(digest || "");
+  if (!text) return "";
+  const valid = validUris.map((uri) => String(uri || "").trim()).filter(Boolean);
+  if (!valid.length) return text;
+  const validSet = new Set(valid);
+
+  const lines = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim().startsWith("- ")) {
+      lines.push(line);
+      continue;
+    }
+    let tokenized = line;
+    for (const uri of [...valid].sort((a, b) => b.length - a.length)) {
+      if (/\s/.test(uri)) tokenized = tokenized.split(uri).join(encodeURI(uri));
+    }
+    let dropped = false;
+    const repaired = tokenized.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
+      let decoded = uri;
+      try { decoded = decodeURI(uri); } catch { /* keep the original candidate */ }
+      if (validSet.has(decoded)) return decoded;
+      const nearest = nearestUri(decoded, valid);
+      if (nearest) return nearest;
+      dropped = true;
+      return uri;
+    });
+    if (!dropped) lines.push(repaired);
+  }
+  return lines.join("\n").trim();
+}
+
+export function normalizeCompressedContext(raw, maxChars = 4000, maxBullets = 6) {
+  const text = String(raw || "").trim();
+  if (!text) return null;
+  if (text.toUpperCase() === NO_RELEVANT_MEMORY) return "";
+  const bullets = text.split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^[-*]\s+/.test(line) && line.includes("viking://"))
+    .slice(0, Math.max(1, maxBullets))
+    .map((line) => `- ${line.replace(/^[-*]\s+/, "").slice(0, 500).trim()}`);
+  if (!bullets.length) return null;
+  return (`${DIGEST_HEADER}\n${bullets.join("\n")}`).slice(0, Math.max(100, maxChars));
+}
+
+export function recallDigestCacheKey({
+  query = "",
+  rendered = "",
+  entries = [],
+  maxInputChars = 18000,
+  maxBullets = 6,
+} = {}) {
+  const uris = entries.map((entry) => String(entry?.uri || "").trim()).filter(Boolean).sort();
+  const source = JSON.stringify({
+    version: 2,
+    query: String(query),
+    rendered: String(rendered).slice(0, maxInputChars),
+    uris,
+    maxInputChars,
+    maxBullets,
+  });
+  return createHash("sha256").update(source).digest("hex");
+}
+
+async function readCache(path) {
+  if (!path) return null;
+  try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }
+}
+
+async function writeCache(path, value) {
+  if (!path) return;
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(value));
+    await rename(tmp, path);
+  } catch { /* best effort */ }
+}
+
+export async function compressRecallContext({
+  query,
+  rendered,
+  shortContext = rendered,
+  entries = [],
+  cfg = {},
+  runCompressor,
+  cachePath = "",
+  now = 0,
+}) {
+  const input = String(rendered || "").trim();
+  if (!input) return { status: COMPRESS_EMPTY, context: "" };
+  const minChars = Math.max(0, Number(cfg.recallCompressMinInputChars ?? 1500));
+  if (input.length < minChars) {
+    return { status: COMPRESS_OK, context: String(shortContext ?? input).trim() };
+  }
+
+  const maxInputChars = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));
+  const maxBullets = Math.max(1, Number(cfg.recallCompressMaxBullets || 6));
+  const key = recallDigestCacheKey({
+    query,
+    rendered: input,
+    entries,
+    maxInputChars,
+    maxBullets,
+  });
+  const cached = await readCache(cachePath);
+  if (cached?.key === key && typeof cached.digest === "string") {
+    const digest = normalizeCompressedContext(cached.digest, 4000, maxBullets);
+    if (digest) return { status: COMPRESS_OK, context: digest };
+  }
+
+  const prompt = buildRecallCompressionPrompt({
+    query,
+    rendered: input.slice(0, maxInputChars),
+    maxBullets,
+  });
+  const raw = await runCompressor(prompt);
+  const normalized = normalizeCompressedContext(raw, 4000, maxBullets);
+  if (normalized === null) return { status: COMPRESS_FAILED, context: "" };
+  if (!normalized) return { status: COMPRESS_EMPTY, context: "" };
+
+  const validUris = entries.map((entry) => entry?.uri).filter(Boolean);
+  const repaired = repairDigestUris(normalized, validUris.length
+    ? validUris
+    : (input.match(/viking:\/\/[^\s<>"']+/g) || []));
+  const digest = normalizeCompressedContext(repaired, 4000, maxBullets);
+  if (!digest) return { status: COMPRESS_FAILED, context: "" };
+
+  await writeCache(cachePath, { key, digest, updatedAt: now || 0 });
+  return { status: COMPRESS_OK, context: digest };
+}