@openviking/opencode-plugin 2026.9.9 → 2026.9.21-1

package/lib/shared/credentials.mjs

@@ -2,11 +2,11 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve as resolvePath } from "node:path";
-import { fileURLToPath } from "node:url";
 
 const DEFAULT_OVCLI_CONF_PATH = join(homedir(), ".openviking", "ovcli.conf");
 const DEFAULT_OV_CONF_PATH = join(homedir(), ".openviking", "ov.conf");
-const DEFAULT_BASE_URL = "http://127.0.0.1:1933";
+const DEFAULT_TIMEOUT_MS = 15000;
+const MIN_TIMEOUT_MS = 1000;
 
 function str(val, fallback = "") {
   if (typeof val === "string" && val.trim()) return val.trim();
@@ -108,6 +108,88 @@ export function loadCredentialFiles(env = process.env) {
   };
 }
 
+/**
+ * The environment variables that name part of the connection. Any one of them
+ * set is what takes the chain off ovcli.conf in `auto` mode, so a variable
+ * that only tunes how the chain runs must not be on this list: an
+ * `OPENVIKING_AUTH_MODE` exported on its own would otherwise unpin the file.
+ */
+export const CREDENTIAL_ENV_VARS = [
+  "OPENVIKING_URL",
+  "OPENVIKING_BASE_URL",
+  "OPENVIKING_MCP_URL",
+  "OPENVIKING_BEARER_TOKEN",
+  "OPENVIKING_API_KEY",
+  "OPENVIKING_ACCOUNT",
+  "OPENVIKING_USER",
+  "OPENVIKING_PEER_ID",
+];
+
+/** Every environment variable `resolveConnection` reads. */
+export const CONNECTION_ENV_VARS = [
+  ...CREDENTIAL_ENV_VARS,
+  "OPENVIKING_AUTH_MODE",
+  "OPENVIKING_CREDENTIAL_SOURCE",
+  "OPENVIKING_CREDENTIALS_SOURCE",
+  "OPENVIKING_CLI_CONFIG_FILE",
+  "OPENVIKING_CONFIG_FILE",
+];
+
+function isSection(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * ov.conf spells its sections snake_case while a host may call itself
+ * `claude-code` or `trae-cn`, so both spellings land on the same block. The
+ * normalization stays inline rather than importing `config-schema.mjs`, which
+ * the portable agent-plugins bundle would then have to ship as well.
+ */
+function sectionKey(harness) {
+  return String(harness || "").trim().toLowerCase().replace(/-/g, "_");
+}
+
+/** The calling harness's own section of ov.conf. */
+function harnessSection(ovFile, harness) {
+  const section = ovFile[sectionKey(harness)];
+  return isSection(section) ? section : {};
+}
+
+/**
+ * ovcli.conf's `plugin` section as this harness sees it: the shared scalars,
+ * then `plugin.<harness>` over them in both spellings, the hyphenated one last.
+ * `loadPluginSettings` merges the same way for every other knob, and the two
+ * must agree or a key would win in the hooks and lose here.
+ */
+function pluginSection(cliFile, harness) {
+  const plugin = isSection(cliFile.plugin) ? cliFile.plugin : {};
+  const merged = {};
+  for (const [key, value] of Object.entries(plugin)) {
+    if (!isSection(value)) merged[key] = value;
+  }
+  const key = sectionKey(harness);
+  for (const candidate of [key, key.replace(/_/g, "-")]) {
+    if (candidate && isSection(plugin[candidate])) Object.assign(merged, plugin[candidate]);
+  }
+  return merged;
+}
+
+/** A knob-file scalar as the schema coerces a string knob: `12345` is "12345". */
+function scalar(value) {
+  return value === undefined || value === null ? "" : String(value).trim();
+}
+
+const AUTH_MODES = ["trusted", "api_key"];
+
+function normalizeAuthMode(value) {
+  const mode = str(value, "").toLowerCase();
+  return AUTH_MODES.includes(mode) ? mode : "";
+}
+
+function authModeIn(section) {
+  return normalizeAuthMode(section.authMode) || normalizeAuthMode(section.auth_mode);
+}
+
 function sourceMode(env) {
   const raw = str(env.OPENVIKING_CREDENTIAL_SOURCE, str(env.OPENVIKING_CREDENTIALS_SOURCE, "auto"))
     .toLowerCase();
@@ -117,123 +199,177 @@ function sourceMode(env) {
 }
 
 function hasEnvCredentialFields(env) {
-  return Boolean(
-    str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, "")) ||
-    str(env.OPENVIKING_MCP_URL, "") ||
-    str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, "")) ||
-    str(env.OPENVIKING_ACCOUNT, "") ||
-    str(env.OPENVIKING_USER, "") ||
-    str(env.OPENVIKING_PEER_ID, ""),
-  );
+  return CREDENTIAL_ENV_VARS.some((name) => str(env[name], ""));
 }
 
-function deriveBaseUrl({ env, cliFile, ovFile, mode, useCli }) {
-  const envUrl = str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, ""));
-  const cliUrl = str(cliFile.url, "");
-
-  if (mode !== "cli" && envUrl) return envUrl.replace(/\/+$/, "");
-  if (useCli && cliUrl) return cliUrl.replace(/\/+$/, "");
-  if (mode !== "env" && cliUrl) return cliUrl.replace(/\/+$/, "");
-
-  const server = ovFile.server || {};
-  const ovUrl = str(server.url, "");
-  if (ovUrl) return ovUrl.replace(/\/+$/, "");
+function trimSlash(value) {
+  return value.replace(/\/+$/, "");
+}
 
-  const host = str(server.host, "127.0.0.1").replace("0.0.0.0", "127.0.0.1");
-  const port = Number.isFinite(Number(server.port)) ? Math.floor(Number(server.port)) : 1933;
-  return `http://${host}:${port}`;
+/** The first layer that holds a value, with the source label and file it names. */
+function firstLayer(layers) {
+  for (const [value, source, path = ""] of layers) {
+    if (value) return { value, source, path };
+  }
+  return { value: "", source: "none", path: "" };
 }
 
-export function resolveOpenVikingCredentials(env = process.env) {
-  const files = loadCredentialFiles(env);
+/**
+ * The one connection a harness has: which server, which key, whose identity,
+ * and whether that identity goes on the wire. Hooks reach it through
+ * `buildPluginConfig`, every MCP proxy through the same loader or through
+ * `buildProxyConnection`, so the two sides of one harness cannot disagree.
+ *
+ * Only three kinds of input count: what an embedding host named (`hostInput`),
+ * the environment, and the two files under `~/.openviking`. The working
+ * directory never does — an MCP proxy starts wherever its host launches it.
+ *
+ * ovcli.conf pins the chain when it names a url, key, identity or peer and the
+ * environment names none of those; pinned, the environment's credentials no
+ * longer apply. `OPENVIKING_CREDENTIAL_SOURCE` forces either side, and forced
+ * to `env` no file is read at all — which is what lets a parent process hand a
+ * resolved connection, including an empty key, to a child verbatim. Every chain
+ * runs host → env (unpinned) → ovcli.conf → its `plugin.<harness>` and
+ * `plugin` keys → ov.conf's harness section; the key then ends at
+ * `server.root_api_key`, which a pinned chain reaches only with
+ * `rootKeyFallback`, and the identity skips ov.conf's harness section when
+ * pinned. The auth mode reads the environment in either mode, then the
+ * `plugin` keys, the harness section and `server.auth_mode`; failing all of
+ * them, an identity from any layer means the deployment expects one.
+ */
+export function resolveConnection(harness, {
+  env = process.env,
+  files = null,
+  hostInput = {},
+  rootKeyFallback = false,
+} = {}) {
+  const name = str(harness, "");
+  const loaded = files || loadCredentialFiles(env);
+  const { cliFile, ovFile, cliPath, ovPath } = loaded;
+  const host = hostInput || {};
   const mode = sourceMode(env);
   const envHasCredentials = hasEnvCredentialFields(env);
-  const useCli = mode === "cli" ||
-    (mode === "auto" && !envHasCredentials && files.cliPath && hasCredentialFields(files.cliFile));
-  const cx = files.ovFile.codex || {};
-  const server = files.ovFile.server || {};
-
-  const baseUrl = deriveBaseUrl({ env, ...files, mode, useCli });
-
-  const apiKey = useCli
-    ? str(files.cliFile.api_key, "")
-    : (
-        str(env.OPENVIKING_BEARER_TOKEN, "") ||
-        str(env.OPENVIKING_API_KEY, "") ||
-        str(files.cliFile.api_key, "") ||
-        str(cx.apiKey, "") ||
-        str(server.root_api_key, "")
-      );
-
-  const account = useCli
-    ? str(files.cliFile.account, str(files.cliFile.account_id, ""))
-    : (
-        str(env.OPENVIKING_ACCOUNT, "") ||
-        str(files.cliFile.account, str(files.cliFile.account_id, "")) ||
-        str(cx.accountId, "")
-      );
-
-  const user = useCli
-    ? str(files.cliFile.user, str(files.cliFile.user_id, ""))
-    : (
-        str(env.OPENVIKING_USER, "") ||
-        str(files.cliFile.user, str(files.cliFile.user_id, "")) ||
-        str(cx.userId, "")
-      );
-
-  const peerId = useCli
-    ? str(files.cliFile.actor_peer_id, str(files.cliFile.peer_id, ""))
-    : (
-        str(env.OPENVIKING_PEER_ID, "") ||
-        str(files.cliFile.actor_peer_id, str(files.cliFile.peer_id, "")) ||
-        str(cx.peerId, str(cx.peer_id, ""))
-      );
-
-  const explicitMcpUrl = str(env.OPENVIKING_MCP_URL, "");
-  const mcpUrl = (mode !== "cli" && explicitMcpUrl) ? explicitMcpUrl : `${baseUrl.replace(/\/+$/, "")}/mcp`;
-
-  // The file that actually supplied the api_key, following the same chain —
-  // empty when the key came from the environment or was never found.
-  let credentialPath = "";
-  if (apiKey) {
-    if (useCli) credentialPath = files.cliPath;
-    else if (str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, ""))) credentialPath = "";
-    else if (str(files.cliFile.api_key, "")) credentialPath = files.cliPath;
-    else credentialPath = files.ovPath;
-  }
+  const pinned = mode === "cli" ||
+    (mode === "auto" && !envHasCredentials && Boolean(cliPath) && hasCredentialFields(cliFile));
+  const unpinned = (layer) => (pinned ? [] : [layer]);
+  const fromFiles = mode !== "env";
+  const filed = (...layers) => (fromFiles ? layers : []);
+  const plugin = pluginSection(cliFile, name);
+  const section = harnessSection(ovFile, name);
+  const server = isSection(ovFile.server) ? ovFile.server : {};
+
+  const key = firstLayer([
+    [str(host.apiKey, ""), "host"],
+    ...unpinned([str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, "")), "env"]),
+    ...filed(
+      [str(cliFile.api_key, ""), "ovcli", cliPath],
+      [scalar(plugin.apiKey), "ovcli", cliPath],
+      [scalar(section.apiKey), "ov", ovPath],
+    ),
+    ...((pinned && !rootKeyFallback) ? [] : filed([str(server.root_api_key, ""), "ov", ovPath])),
+  ]);
+
+  const identity = (hostValue, envName, cliValue, knob) => firstLayer([
+    [str(hostValue, ""), "host"],
+    ...unpinned([str(env[envName], ""), "env"]),
+    ...filed([cliValue, "ovcli", cliPath], [scalar(plugin[knob]), "ovcli", cliPath]),
+    ...(pinned ? [] : filed([str(section[knob], ""), "ov", ovPath])),
+  ]).value;
+  const account = identity(host.account, "OPENVIKING_ACCOUNT", str(cliFile.account, str(cliFile.account_id, "")), "accountId");
+  const user = identity(host.user, "OPENVIKING_USER", str(cliFile.user, str(cliFile.user_id, "")), "userId");
+
+  const peerId = firstLayer([
+    ...unpinned([str(env.OPENVIKING_PEER_ID, ""), "env"]),
+    ...filed([str(cliFile.actor_peer_id, str(cliFile.peer_id, "")), "ovcli"]),
+    ...(pinned ? [] : filed([str(section.peerId, str(section.peer_id, "")), "ov"])),
+  ]).value;
+
+  const authMode = normalizeAuthMode(host.authMode)
+    || normalizeAuthMode(env.OPENVIKING_AUTH_MODE)
+    || (fromFiles && (authModeIn(plugin) || authModeIn(section) || normalizeAuthMode(server.auth_mode)))
+    || ((account || user) ? "trusted" : "api_key");
+
+  const hostBaseUrl = trimSlash(str(host.baseUrl, ""));
+  const envUrl = pinned ? "" : str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, ""));
+  const fileUrl = fromFiles ? (str(cliFile.url, "") || str(server.url, "")) : "";
+  const baseUrl = hostBaseUrl || trimSlash(envUrl || fileUrl) || serverAddress(fromFiles ? server : {});
+  const envMcpUrl = pinned ? "" : str(env.OPENVIKING_MCP_URL, "");
+  const mcpUrl = (!hostBaseUrl && envMcpUrl) ? envMcpUrl : `${baseUrl}/mcp`;
 
   return {
-    ...files,
-    credentialSource: useCli ? "ovcli" : ((mode === "env" || envHasCredentials) ? "env" : "auto"),
-    credentialPath,
+    ...loaded,
+    harness: name,
+    credentialSource: pinned ? "ovcli" : ((mode === "env" || envHasCredentials) ? "env" : "auto"),
     baseUrl,
     mcpUrl,
-    apiKey,
+    apiKey: key.value,
     account,
     user,
     peerId,
-    hasApiKey: Boolean(apiKey),
+    authMode,
+    sendIdentityHeaders: authMode === "trusted",
+    hasApiKey: Boolean(key.value),
+    // Which layer supplied the key and the file behind it, empty when the key
+    // came from the host or the environment. A doctor and a 401 hint report it;
+    // `credentialSource` is the mode the chain ran in, not a file.
+    apiKeySource: key.source,
+    credentialPath: key.path,
   };
 }
 
-function main() {
-  const cmd = process.argv[2] || "";
-  if (cmd === "mcp-url") {
-    process.stdout.write(resolveOpenVikingCredentials().mcpUrl);
-    return;
-  }
-  if (cmd === "has-api-key") {
-    process.stdout.write(resolveOpenVikingCredentials().hasApiKey ? "1" : "0");
-    return;
-  }
-  if (cmd === "has-peer-id") {
-    process.stdout.write(resolveOpenVikingCredentials().peerId ? "1" : "0");
-    return;
-  }
-  process.stderr.write("usage: ov-credentials.mjs <mcp-url|has-api-key|has-peer-id>\n");
-  process.exitCode = 2;
+function serverAddress(server) {
+  const host = str(server.host, "127.0.0.1").replace("0.0.0.0", "127.0.0.1");
+  const port = Number.isFinite(Number(server.port)) ? Math.floor(Number(server.port)) : 1933;
+  return `http://${host}:${port}`;
+}
+
+function envFlag(env, name) {
+  const raw = str(env[name], "").toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes";
 }
 
-if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
-  main();
+function clampTimeout(value) {
+  const raw = str(value, "");
+  const parsed = raw ? Number(raw) : NaN;
+  return Math.max(MIN_TIMEOUT_MS, Math.floor(Number.isFinite(parsed) ? parsed : DEFAULT_TIMEOUT_MS));
+}
+
+/**
+ * Everything a stdio MCP proxy needs, for a package that ships no hooks.
+ *
+ * `buildPluginConfig` answers the same question one layer up, but reaching it
+ * means vendoring the knob schema and the workspace layers — a closure the
+ * portable agent-plugins bundle would carry in git to send one HTTP header.
+ * This is the same connection plus what a proxy adds to it: the User-Agent,
+ * the request timeout, and the debug log.
+ *
+ * The api_key ends at `server.root_api_key` even when ovcli.conf pinned the
+ * chain to itself. A portable package has no installer to migrate anyone, so
+ * an install that names only a `url` there keeps the key it has always used.
+ */
+export function buildProxyConnection(harness, { env = process.env, manifestUrl = "", version = "" } = {}) {
+  const name = str(harness);
+  const connection = resolveConnection(name, { env, rootKeyFallback: true });
+  return {
+    harness: name,
+    userAgent: buildUserAgent(name, str(version) || (manifestUrl ? readManifestVersion(manifestUrl) : "")),
+    baseUrl: connection.baseUrl,
+    mcpUrl: connection.mcpUrl,
+    apiKey: connection.apiKey,
+    account: connection.account,
+    user: connection.user,
+    peerId: connection.peerId,
+    authMode: connection.authMode,
+    sendIdentityHeaders: connection.sendIdentityHeaders,
+    credentialSource: connection.credentialSource,
+    apiKeySource: connection.apiKeySource,
+    credentialPath: connection.credentialPath,
+    hasApiKey: connection.hasApiKey,
+    cliPath: connection.cliPath,
+    ovPath: connection.ovPath,
+    timeoutMs: clampTimeout(env.OPENVIKING_TIMEOUT_MS),
+    debug: envFlag(env, "OPENVIKING_DEBUG"),
+    debugLogPath: str(env.OPENVIKING_DEBUG_LOG)
+      || join(homedir(), ".openviking", "logs", `${name}.log`),
+  };
 }

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,
+    };
+  });
+}