@openviking/dsh-memory-plugin 0.3.0 → 0.4.3

package/shared/plugin-config.mjs

@@ -19,43 +19,52 @@
  * Resolution stays env → ovcli.conf plugin.<harness> → ovcli.conf plugin →
  * ov.conf harness section (legacy) → defaults.
  *
- * Consumers: Claude Code and Codex only. The other harnesses ship this module
- * through `sync.mjs` but still read their knobs from the environment, so a
- * `plugin` entry named after them is inert. `HARNESS_KEYS` lists what a harness
- * loader actually consumes today — add a key here as its loader starts calling
- * `loadPluginSettings`, not before, so the section never promises a knob that
- * silently does nothing.
+ * Every harness resolves through `resolveSettings()` below, and assembles its
+ * whole configuration through `buildPluginConfig()`, so one `plugin` section
+ * configures all of them and `ov config switch` moves behaviour along with
+ * credentials. The knobs themselves are declared once in `config-schema.mjs`;
+ * this module decides which files supply them and what is derived from them.
  */
 
-import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve as resolvePath } from "node:path";
+import { join } from "node:path";
 
-const DEFAULT_OVCLI_CONF_PATH = join(homedir(), ".openviking", "ovcli.conf");
+import { HARNESS_KEYS, KNOBS, harnessKey, resolveKnobs } from "./config-schema.mjs";
+import {
+  buildUserAgent,
+  loadCredentialFiles,
+  readManifestVersion,
+  resolveConnection,
+} from "./credentials.mjs";
+import {
+  announcedOverrides,
+  loadWorkspaceLayers,
+  mergeConfigLayers,
+  normalizeWorkspaceConfig,
+  projectWorkspaceSettings,
+} from "./workspace-config.mjs";
+import { findWorkspaceRoot, resolveWorkspaceIdentity } from "./workspace-identity.mjs";
+import { resolveEffectivePeerId, resolvePluginPeerId } from "./workspace-peer.mjs";
+import { readEntry } from "./workspace-registry.mjs";
 
-export const HARNESS_KEYS = {
-  claudeCode: "claude_code",
-  codex: "codex",
-};
+const OVCLI_LAYER = "ovcli.conf";
+const OV_CONF_LAYER = "ov.conf";
 
-function tryLoadJson(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
+export { HARNESS_KEYS, harnessKey };
 
 /**
  * Merge the shared plugin section with the harness-specific override.
  * Returns a flat settings object; unknown keys pass through untouched so a
  * harness can add its own knobs without touching this module.
+ *
+ * `cliFile` is ovcli.conf already parsed. Callers that have it hand it over so
+ * the file is read once per build and, more importantly, so the `plugin`
+ * section comes out of the same file the credential chain read — an
+ * `OPENVIKING_CONFIG_FILE` that is ovcli-shaped is ovcli.conf, and only
+ * `loadCredentialFiles` knows that.
  */
-export function loadPluginSettings(harness, env = process.env) {
-  const path = resolvePath(
-    (env.OPENVIKING_CLI_CONFIG_FILE || DEFAULT_OVCLI_CONF_PATH).replace(/^~/, homedir()),
-  );
-  const file = tryLoadJson(path);
+export function loadPluginSettings(harness, env = process.env, options = {}) {
+  const file = options.cliFile || loadCredentialFiles(env).cliFile;
   const plugin = file && typeof file.plugin === "object" && file.plugin ? file.plugin : {};
 
   const shared = {};
@@ -63,11 +72,212 @@ export function loadPluginSettings(harness, env = process.env) {
     if (value && typeof value === "object" && !Array.isArray(value)) continue;
     shared[key] = value;
   }
-  const scoped = harness && plugin[harness] && typeof plugin[harness] === "object"
-    ? plugin[harness]
-    : {};
+  // Both spellings of the harness name find the same override, so copying
+  // `claude-code` out of the installer is not a silent no-op.
+  const key = harnessKey(harness);
+  const scoped = {};
+  for (const candidate of [key, key.replace(/_/g, "-")]) {
+    const value = candidate && plugin[candidate];
+    if (value && typeof value === "object" && !Array.isArray(value)) Object.assign(scoped, value);
+  }
+
+  const settings = { ...shared, ...scoped };
+  const cwd = String(options.cwd || "").trim();
+  if (!cwd) return settings;
+  return { ...settings, ...resolveWorkspaceSettings(cwd, env, options).settings };
+}
+
+/**
+ * Every knob for one harness, resolved through the whole layer stack.
+ *
+ * `legacy` is that harness's section in ov.conf, which is where tuning used to
+ * live: it stays the lowest configured layer so an existing deployment keeps
+ * working, and everything above it comes from files a client may edit.
+ *
+ * Returns the settings, the names some layer actually supplied (what the
+ * `*Configured` flags report), and the raw ovcli.conf merge — a couple of
+ * callers still need to know a value came from ovcli.conf rather than ov.conf.
+ */
+export function resolveSettings(harness, options = {}) {
+  const { env = process.env, cwd = "", legacy = {}, clientVersion = "", cliFile = null } = options;
+  const key = harnessKey(harness);
+  const plugin = loadPluginSettings(key, env, { cwd, clientVersion, cliFile });
+  const { settings, configured, sources } = resolveKnobs({
+    harness: key,
+    layers: [
+      { name: OV_CONF_LAYER, data: legacy },
+      { name: OVCLI_LAYER, data: plugin },
+    ],
+    env,
+  });
+  return { settings, configured, sources, plugin };
+}
 
-  return { ...shared, ...scoped };
+/**
+ * The workspace layers for one cwd, flattened into harness knobs.
+ *
+ * Takes the cwd explicitly because a hook's `loadConfig()` runs at module top
+ * level, before the payload on stdin has said which directory the session is
+ * actually in — the caller resolves this again once it knows.
+ */
+export function resolveWorkspaceSettings(cwd, env = process.env, { clientVersion = "" } = {}) {
+  const empty = { settings: {}, root: "", provenance: {}, warnings: [], announced: [] };
+  try {
+    const { root } = findWorkspaceRoot(cwd, env);
+    if (!root) return empty;
+
+    const { layers, warnings } = loadWorkspaceLayers(root, { clientVersion });
+    // The identity is what makes the registry's negative evidence work: without
+    // it a directory reused by a different repository inherits the old peer.
+    const identity = resolveWorkspaceIdentity({ cwd, env });
+    const registry = readEntry(root, { identity, env });
+    warnings.push(...registry.warnings);
+    if (registry.entry?.settings) layers.push({ layer: "registry", data: registry.entry.settings });
+    if (registry.entry?.peer) layers.push({ layer: "registry", data: { peer: registry.entry.peer } });
+    if (!layers.length) return { ...empty, root, warnings };
+
+    const { value, provenance } = mergeConfigLayers(layers, warnings);
+    normalizeWorkspaceConfig(value, warnings);
+    return {
+      settings: projectWorkspaceSettings(value),
+      root,
+      provenance,
+      warnings,
+      announced: announcedOverrides(provenance),
+      value,
+    };
+  } catch {
+    // A hook must never die over a config file. An unreadable layer is no layer.
+    return empty;
+  }
+}
+
+const SEND_ONLY_WHEN_CONFIGURED = KNOBS.filter((knob) => knob.sendOnlyWhenConfigured);
+
+function str(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+/** The ov.conf block named after this harness, the lowest layer of every chain. */
+function ovConfSection(ovFile, key) {
+  const section = key ? ovFile?.[key] : null;
+  return section && typeof section === "object" && !Array.isArray(section) ? section : {};
+}
+
+/**
+ * One harness's whole configuration: the files, the knobs, the peer, and the
+ * handful of fields derived from them.
+ *
+ * Every loader used to write this sequence out by hand and each wrote a
+ * slightly different subset, which is how ov.conf's `<harness>.authMode` came
+ * to apply on three harnesses only, and why two of the four knobs the server
+ * defaults for itself were reported as configured on two harnesses and nowhere
+ * else. What is left in a loader after this call is what only that harness
+ * knows.
+ *
+ * The connection — server, key, identity, auth mode — is not a knob: it comes
+ * from `resolveConnection`, the same call an MCP proxy's connection comes
+ * from, and the `plugin` keys and ov.conf block that name it are read there.
+ *
+ * `legacy` replaces the ov.conf block this harness would otherwise get for its
+ * knobs (dsh's host hands it one of its own); `hostInput` is what an embedding
+ * host named for this process, which is the more specific answer and outranks
+ * every file; `logFile` is the log basename this harness has always used, and
+ * a harness that never had a default log path does not get one invented for
+ * it; `rootKeyFallback` is for the harnesses whose chain predates the ovcli.conf
+ * pinning and has always ended at `server.root_api_key`.
+ */
+export function buildPluginConfig(harness, {
+  cwd = "",
+  env = process.env,
+  legacy = null,
+  manifestUrl = "",
+  version = "",
+  hostInput = {},
+  logFile = "",
+  rootKeyFallback = false,
+  deriveEffectivePeer = false,
+} = {}) {
+  const name = String(harness || "");
+  const key = harnessKey(name);
+  const workspaceCwd = str(cwd) || process.cwd();
+  const files = loadCredentialFiles(env);
+  // The version answers two questions: what the User-Agent reports, and whether
+  // a workspace file asking for a newer client gets to say so.
+  const clientVersion = str(version) || (manifestUrl ? readManifestVersion(manifestUrl) : "");
+  const { settings, configured, sources } = resolveSettings(key, {
+    env,
+    cwd: workspaceCwd,
+    legacy: legacy || ovConfSection(files.ovFile, key),
+    cliFile: files.cliFile,
+    clientVersion,
+  });
+  const connection = resolveConnection(key, { env, files, hostInput, rootKeyFallback });
+  const { baseUrl, account, user } = connection;
+  const timeoutMs = settings.timeoutMs;
+  const peerId = resolvePluginPeerId({
+    settings,
+    configured,
+    sources,
+    credentials: connection,
+    hostInput: hostInput?.peerId,
+    env,
+  });
+
+  const config = {
+    ...settings,
+    harness: name,
+    clientVersion,
+    userAgent: buildUserAgent(name, clientVersion),
+
+    baseUrl,
+    mcpUrl: connection.mcpUrl,
+    apiKey: connection.apiKey,
+    account,
+    user,
+    authMode: connection.authMode,
+    sendIdentityHeaders: connection.sendIdentityHeaders,
+
+    credentialSource: connection.credentialSource,
+    apiKeySource: connection.apiKeySource,
+    credentialPath: connection.credentialPath,
+    hasApiKey: connection.hasApiKey,
+    configPath: connection.cliPath || connection.ovPath || null,
+    cliConfigPath: connection.cliPath,
+    ovConfigPath: connection.ovPath,
+    cliPath: connection.cliPath,
+    ovPath: connection.ovPath,
+
+    peerId,
+    explicitPeerId: peerId,
+
+    // A write gets a longer budget than a read, and a digest has to finish
+    // inside the recall request it belongs to, so both fall back to a knob.
+    captureTimeoutMs: settings.captureTimeoutMs || Math.max(timeoutMs * 2, 30000),
+    recallCompressTimeoutMs: settings.recallCompressTimeoutMs
+      || Math.max(1000, settings.recallTimeoutMs - 10000),
+    debugLogPath: settings.debugLogPath
+      || (logFile ? join(homedir(), ".openviking", "logs", logFile) : ""),
+
+    // The spellings these fields carried before every harness shared a loader.
+    endpoint: baseUrl,
+    accountId: account,
+    userId: user,
+    requestTimeoutMs: timeoutMs,
+  };
+  for (const knob of SEND_ONLY_WHEN_CONFIGURED) {
+    config[`${knob.name}Configured`] = configured.has(knob.name);
+  }
+
+  // Only for the harnesses that resolve the peer once at load. The rest derive
+  // it per session, against the directory the payload names, and an MCP proxy
+  // must not derive one from wherever it happened to be launched.
+  if (deriveEffectivePeer) {
+    const effectivePeer = resolveEffectivePeerId({ cfg: config, cwd: workspaceCwd, env });
+    config.effectivePeer = effectivePeer;
+    config.legacyPeerId = effectivePeer.legacyPeerId;
+  }
+  return config;
 }
 
 const REWRITE_MODES = new Set(["off", "client", "server", "auto"]);

package/shared/recall-compress-core.mjs

@@ -86,10 +86,16 @@ export function repairDigestUris(digest, validUris = []) {
       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 = line.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
-      if (validSet.has(uri)) return uri;
-      const nearest = nearestUri(uri, valid);
+    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;
@@ -149,6 +155,7 @@ async function writeCache(path, value) {
 export async function compressRecallContext({
   query,
   rendered,
+  shortContext = rendered,
   entries = [],
   cfg = {},
   runCompressor,
@@ -158,7 +165,9 @@ export async function compressRecallContext({
   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: input };
+  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));
@@ -171,7 +180,8 @@ export async function compressRecallContext({
   });
   const cached = await readCache(cachePath);
   if (cached?.key === key && typeof cached.digest === "string") {
-    return { status: COMPRESS_OK, context: cached.digest };
+    const digest = normalizeCompressedContext(cached.digest, 4000, maxBullets);
+    if (digest) return { status: COMPRESS_OK, context: digest };
   }
 
   const prompt = buildRecallCompressionPrompt({
@@ -185,9 +195,10 @@ export async function compressRecallContext({
   if (!normalized) return { status: COMPRESS_EMPTY, context: "" };
 
   const validUris = entries.map((entry) => entry?.uri).filter(Boolean);
-  const digest = repairDigestUris(normalized, validUris.length
+  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 });

package/shared/recall-core.mjs

@@ -31,6 +31,28 @@ const CODING_QUOTA_WEIGHTS = {
 
 let userSpaceCache = "";
 
+/**
+ * Is recall on for this config?
+ *
+ * The switch has four spellings in the wild: a boolean `autoRecall`, opencode's
+ * `{ enabled }` object, dsh and pi's `syncTurns`, and the global `enabled`
+ * that turns the whole plugin off. Reading it here rather than in each loader
+ * is what keeps it from drifting a fifth time — and any spelling that says off
+ * wins, so a config that disables recall under an older name still disables it.
+ */
+export function isRecallEnabled(cfg = {}) {
+  return isSwitchOn([cfg.enabled, cfg.autoRecall, cfg.recall, cfg.syncRecall]);
+}
+
+/** Any recognised spelling that says off wins; everything else means on. */
+function isSwitchOn(values) {
+  for (const value of values) {
+    if (value === false) return false;
+    if (value && typeof value === "object" && !Array.isArray(value) && value.enabled === false) return false;
+  }
+  return true;
+}
+
 export function estimateTokens(text) {
   return text ? Math.ceil(String(text).length / 4) : 0;
 }
@@ -338,9 +360,8 @@ async function resolveItemContent(fetchJSON, item, cfg, actorPeerId = "") {
 }
 
 async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId = "", log = () => {}) {
-  if (items.length === 0) return null;
-
-  let budgetRemaining = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+  const budgetTotal = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+  let budgetRemaining = budgetTotal;
   const lines = [
     "<openviking-context>",
     "Relevant context from OpenViking. Use the read MCP tool to expand URIs.",
@@ -373,15 +394,15 @@ async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId =
 
   lines.push("</openviking-context>");
 
-  const budgetUsed = Math.max(200, Number(cfg.recallTokenBudget || 2000)) - budgetRemaining;
+  const budgetUsed = budgetTotal - budgetRemaining;
   log("recall_injection_built", {
     contentItems: contentCount,
     hintItems: hintCount,
     budgetUsed,
-    budgetTotal: Math.max(200, Number(cfg.recallTokenBudget || 2000)),
+    budgetTotal,
   });
 
-  return lines.join("\n");
+  return { block: lines.join("\n"), contentCount, hintCount, budgetUsed, stage: "ranked" };
 }
 
 const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
@@ -417,6 +438,31 @@ export async function markContextFaceLegacy(path = stateFile("context-face.json"
   await writeJsonFile(path, { legacyUntil: now + LEGACY_CACHE_TTL_MS });
 }
 
+/**
+ * A `peer_scope` the server rejects is remembered the same way, but unlike the
+ * context face this one is not a silent capability probe: dropping the field
+ * widens recall from the caller's own peer to the whole user root, so doctor
+ * reads this file back and warns.
+ */
+export function peerScopeMemoPath() {
+  return stateFile("peer-scope.json");
+}
+
+export async function readPeerScopeDowngrade(path = peerScopeMemoPath(), now = Date.now()) {
+  const cached = await readJsonFile(path);
+  if (!cached?.legacyUntil || Number(cached.legacyUntil) <= now) return null;
+  return cached;
+}
+
+export async function markPeerScopeDowngrade(scope, status, path = peerScopeMemoPath(), now = Date.now()) {
+  await writeJsonFile(path, {
+    legacyUntil: now + LEGACY_CACHE_TTL_MS,
+    scope: String(scope || ""),
+    status: Number(status) || 0,
+    at: now,
+  });
+}
+
 function looksLikeUnknownField(res) {
   const text = JSON.stringify(res?.error ?? res?.result ?? res?.detail ?? "").toLowerCase();
   return text.includes("extra") || text.includes("mode") || text.includes("unexpected");
@@ -558,7 +604,15 @@ async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log =
 export async function postRecall(fetchJSON, body, opts = {}) {
   const actorPeerId = opts.actorPeerId || "";
   const log = opts.log || (() => {});
+  const memoPath = opts.peerScopeMemoPath;
   const request = { ...body };
+
+  // A remembered downgrade is still a downgrade: recall runs wider than the
+  // caller asked for, so the memo doubles as the doctor's evidence.
+  if (request.peer_scope && await readPeerScopeDowngrade(memoPath)) {
+    delete request.peer_scope;
+  }
+
   const res = await fetchJSON("/api/v1/search/recall", {
     method: "POST",
     body: JSON.stringify(request),
@@ -566,9 +620,17 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   if (!request.peer_scope || (res.status !== 400 && res.status !== 422)) {
     return res;
   }
+  // Only an unknown-field rejection means "this server predates peer_scope".
+  // Retrying every other 400/422 without it silently widens the search from
+  // the caller's own peer to the whole user root.
+  if (!looksLikeUnknownField(res)) {
+    log("recall_peer_scope_error", { status: res.status || 0 });
+    return res;
+  }
 
   const downgraded = { ...request };
   delete downgraded.peer_scope;
+  await markPeerScopeDowngrade(String(request.peer_scope), res.status || 0, memoPath);
   log("recall_peer_scope_downgrade", { status: res.status || 0 });
   return fetchJSON("/api/v1/search/recall", {
     method: "POST",
@@ -576,11 +638,56 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   }, { actorPeerId });
 }
 
+/**
+ * Recall, plus whatever is still filed under the peer this workspace used
+ * before the identity rule changed.
+ *
+ * Under the default `peer_scope: "all"` this costs nothing: the server's own
+ * sweep of `{user_root}/peers` already reaches the old peer's memories. Under
+ * `"actor"` that sweep is off by definition, so the old peer is asked for
+ * separately — as itself, which is both cheaper and wider than a bare
+ * cross-peer read (that would need the user id, and reaches memories only).
+ *
+ * `stage` names the path the block came from, which is what a host needs to
+ * tell "the server had nothing" (`no_results`) from "the score threshold
+ * dropped everything" (`filtered_out`) when the block is empty, and a
+ * `server_assembled` block from a `ranked` one when it is not.
+ */
+export async function buildRecallBlockDetailed(fetchJSON, cfg, query, options = {}) {
+  const primary = await recallForPeer(fetchJSON, cfg, query, options);
+
+  const legacyPeerId = String(options.legacyPeerId || "").trim();
+  const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
+  if (cfg.recallPeerScope !== "actor" || !legacyPeerId || legacyPeerId === actorPeerId) return primary;
+
+  const log = options.log || (() => {});
+  const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
+  if (!legacy.block) return primary;
+  log("recall_legacy_peer_hit", { legacyPeerId });
+  return {
+    block: primary.block ? `${primary.block}\n${legacy.block}` : legacy.block,
+    contentCount: primary.contentCount + legacy.contentCount,
+    hintCount: primary.hintCount + legacy.hintCount,
+    budgetUsed: primary.budgetUsed + legacy.budgetUsed,
+    stage: primary.block ? primary.stage : legacy.stage,
+  };
+}
+
+/** The block alone, or null when nothing was injectable. */
 export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+  const { block } = await buildRecallBlockDetailed(fetchJSON, cfg, query, options);
+  return block || null;
+}
+
+function emptyRecall(stage) {
+  return { block: "", contentCount: 0, hintCount: 0, budgetUsed: 0, stage };
+}
+
+async function recallForPeer(fetchJSON, cfg, query, options = {}) {
   const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
   const log = options.log || (() => {});
   const trimmed = String(query || "").trim();
-  if (!trimmed) return null;
+  if (!trimmed) return emptyRecall("no_results");
 
   // Assembly happens server-side when the deployment offers the context face;
   // older servers fall through to /recall, then to raw find.
@@ -589,12 +696,23 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
     actorPeerId,
     log,
   });
-  if (serverBlock !== null) return serverBlock || null;
+  if (serverBlock !== null) {
+    if (!serverBlock) return emptyRecall("no_results");
+    // The server rendered one budgeted unit, so nothing here degraded to a
+    // URI-only hint and the block's own estimate is what it cost.
+    return {
+      block: serverBlock,
+      contentCount: 1,
+      hintCount: 0,
+      budgetUsed: estimateTokens(serverBlock),
+      stage: "server_assembled",
+    };
+  }
 
   const recallLimit = Math.max(1, Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT));
   const perSourceLimit = Math.max(recallLimit * 2, 8);
   const raw = await searchAllSources(fetchJSON, trimmed, perSourceLimit, actorPeerId, log);
-  if (raw.length === 0) return null;
+  if (raw.length === 0) return emptyRecall("no_results");
 
   const profile = buildQueryProfile(trimmed);
   const scoreThreshold = Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35;
@@ -608,6 +726,6 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
     items: picked.map((it) => ({ type: it._sourceType, uri: it.uri, score: clampScore(it.score) })),
   });
 
-  if (picked.length === 0) return null;
+  if (picked.length === 0) return emptyRecall("filtered_out");
   return buildFallbackInjectionBlock(fetchJSON, picked, cfg, actorPeerId, log);
 }