@openviking/opencode-plugin 2026.9.10 → 2026.9.21

package/lib/shared/ov-http.mjs

@@ -0,0 +1,112 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * The one path from a hook to the OpenViking server.
+ *
+ * Every harness used to own its own AbortController, header block and envelope
+ * parser, and they drifted: one sent the api key twice, one named the operator
+ * to every proxy on the path whether or not the server was trusted with it, one
+ * read a different field for the same account. A server-side change now lands
+ * in one place instead of eight.
+ *
+ * `X-API-Key` is deliberately absent. The server takes `Authorization: Bearer`,
+ * and the identity headers go out only when the resolved config says this
+ * server is trusted with the operator's name.
+ */
+
+// A request that aborts the instant it starts reads as a dead server. A config
+// that asks for less than a second gets a second.
+const MIN_TIMEOUT_MS = 1000;
+
+/**
+ * The headers every harness puts on every OpenViking request.
+ *
+ * `identityHeaders` overrides `cfg.sendIdentityHeaders` for the callers that
+ * decide per request rather than per config — the doctor probes both ways.
+ */
+export function buildOvHeaders(cfg = {}, { actorPeerId = "", identityHeaders, extraHeaders } = {}) {
+  const identity = identityHeaders === undefined ? Boolean(cfg.sendIdentityHeaders) : Boolean(identityHeaders);
+  const headers = { "Content-Type": "application/json" };
+  if (cfg.apiKey) headers["Authorization"] = `Bearer ${cfg.apiKey}`;
+  if (identity && cfg.account) headers["X-OpenViking-Account"] = cfg.account;
+  if (identity && cfg.user) headers["X-OpenViking-User"] = cfg.user;
+  if (actorPeerId) headers["X-OpenViking-Actor-Peer"] = actorPeerId;
+  if (cfg.userAgent) headers["User-Agent"] = cfg.userAgent;
+  return { ...headers, ...extraHeaders };
+}
+
+function responseTraceId(body) {
+  return body?.result?.trace_id || body?.error?.trace_id || body?.trace_id || undefined;
+}
+
+/**
+ * Build the `fetchJSON(path, init, { timeoutMs, actorPeerId })` a harness talks
+ * through. It resolves to `{ ok, status, result, error, traceId }` and never
+ * throws: a hook that crashes on a closed port would take its host's turn with
+ * it, so a network error is `{ ok: false, status: 0 }` and the retry rules in
+ * `retryable.mjs` decide what happens next.
+ *
+ * `resolveActorPeerId` is a callback because Codex only knows its peer after
+ * loading session state under the lock, well after the client is built.
+ * `requireJsonBody` is for the capture hooks, which would rather retry a body
+ * they cannot parse than record the turn as sent.
+ */
+export function createOvHttp(cfg = {}, {
+  defaultTimeoutMs = 0,
+  resolveActorPeerId = () => "",
+  identityHeaders,
+  extraHeaders,
+  requireJsonBody = false,
+} = {}) {
+  // dsh and pi name this field `endpoint`; every other harness names it `baseUrl`.
+  const baseUrl = cfg.baseUrl || cfg.endpoint || "";
+  return async function fetchJSON(path, init = {}, options = {}) {
+    const timeoutMs = Math.max(MIN_TIMEOUT_MS, Number(options.timeoutMs) || Number(defaultTimeoutMs) || 0);
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    try {
+      const headers = {
+        ...buildOvHeaders(cfg, {
+          actorPeerId: options.actorPeerId ?? resolveActorPeerId(),
+          identityHeaders,
+          extraHeaders,
+        }),
+        ...(init.headers || {}),
+      };
+      const response = await fetch(`${baseUrl}${path}`, { ...init, headers, signal: controller.signal });
+      const body = await response.json().catch(() => null);
+      if (requireJsonBody && !body) {
+        return {
+          ok: false,
+          status: response.status,
+          result: null,
+          error: { message: "empty or invalid JSON response" },
+        };
+      }
+      const traceId = responseTraceId(body);
+      if (!response.ok || body?.status === "error") {
+        return {
+          ok: false,
+          status: response.status,
+          result: null,
+          error: body?.error || { message: `HTTP ${response.status}` },
+          traceId,
+        };
+      }
+      return { ok: true, status: response.status, result: body?.result ?? body ?? {}, traceId };
+    } catch (error) {
+      const message = error?.message || String(error);
+      // This module owns the controller, so it says a timeout was a timeout
+      // rather than leaving callers to guess it from whatever fetch threw.
+      const failure = timedOut
+        ? { name: "AbortError", aborted: true, message }
+        : { message };
+      return { ok: false, status: 0, result: null, error: failure };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}

package/lib/shared/plugin-config.mjs

@@ -0,0 +1,300 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Per-harness plugin settings from ovcli.conf.
+ *
+ * ovcli.conf carried connection fields only, so every harness had to keep its
+ * tuning knobs in ov.conf's harness section — a server-side file that a
+ * client-side plugin has no business editing. The `plugin` section fixes that:
+ * shared keys apply to every harness that reads them, and a per-harness object
+ * overrides them.
+ *
+ *   {
+ *     "url": "...", "api_key": "...",
+ *     "plugin": {
+ *       "recallQueryExpansion": "off",
+ *       "recallCompress": "auto"
+ *     }
+ *   }
+ *
+ * Resolution stays env → ovcli.conf plugin.<harness> → ovcli.conf plugin →
+ * ov.conf harness section (legacy) → defaults.
+ *
+ * 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 { homedir } from "node:os";
+import { join } from "node:path";
+
+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";
+
+const OVCLI_LAYER = "ovcli.conf";
+const OV_CONF_LAYER = "ov.conf";
+
+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, options = {}) {
+  const file = options.cliFile || loadCredentialFiles(env).cliFile;
+  const plugin = file && typeof file.plugin === "object" && file.plugin ? file.plugin : {};
+
+  const shared = {};
+  for (const [key, value] of Object.entries(plugin)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) continue;
+    shared[key] = value;
+  }
+  // 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 };
+}
+
+/**
+ * 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"]);
+
+/**
+ * Normalize the tri-state rewrite knob.
+ *
+ * off    — never compress
+ * client — always compress locally through the host CLI
+ * server — always ask the server for a digest
+ * auto   — prefer local (cost lands on the user's own subscription), fall back
+ *          to the server when no healthy host CLI is available
+ */
+export function normalizeRewriteMode(value, fallback = "off") {
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (REWRITE_MODES.has(raw)) return raw;
+  if (raw === "1" || raw === "true" || raw === "yes") return "auto";
+  if (raw === "0" || raw === "false" || raw === "no") return "off";
+  return fallback;
+}

package/lib/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;
@@ -626,8 +647,13 @@ export async function postRecall(fetchJSON, body, opts = {}) {
  * `"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 buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+export async function buildRecallBlockDetailed(fetchJSON, cfg, query, options = {}) {
   const primary = await recallForPeer(fetchJSON, cfg, query, options);
 
   const legacyPeerId = String(options.legacyPeerId || "").trim();
@@ -636,16 +662,32 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
 
   const log = options.log || (() => {});
   const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
-  if (!legacy) return primary;
+  if (!legacy.block) return primary;
   log("recall_legacy_peer_hit", { legacyPeerId });
-  return primary ? `${primary}\n${legacy}` : legacy;
+  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.
@@ -654,12 +696,23 @@ async function recallForPeer(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;
@@ -673,6 +726,6 @@ async function recallForPeer(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);
 }