@openviking/dsh-memory-plugin 0.3.2 → 0.4.3

package/runtime.mjs

@@ -1,6 +1,6 @@
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { isCaptureEnabled } from "./shared/capture-utils.mjs";
 import { buildProfileBlock } from "./shared/profile-inject.mjs";
-import { buildRecallBlock } from "./shared/recall-core.mjs";
+import { buildRecallBlock, isRecallEnabled } from "./shared/recall-core.mjs";
 import { deriveHarnessSessionId } from "./shared/session-model.mjs";
 import {
   dequeue,
@@ -13,6 +13,7 @@ import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs";
 import {
   captureEvent,
   OPENVIKING_PLUGIN_SOURCE,
+  pluginMessage,
   promptText,
 } from "./capture.mjs";
 
@@ -93,7 +94,7 @@ export class OpenVikingRuntime {
     }
     // Replay is a write, so it stays behind the same toggle: a backlog queued
     // while capture was on waits for a session that still writes.
-    if (state.config.syncTurns) {
+    if (isCaptureEnabled(state.config)) {
       await this.replayPendingQueue();
     }
     await this.refreshPendingState(state);
@@ -121,12 +122,12 @@ export class OpenVikingRuntime {
       return null;
     }
     state.profileDelivered = true;
-    return pluginMessage(state.profileBlock, "instructions");
+    return pluginMessage(state.profileBlock, { form: "instructions" });
   }
 
   async recallMessage(agent, messages) {
     const state = await this.initialize(agent);
-    if (!state.ready) return null;
+    if (!state.ready || !isRecallEnabled(state.config)) return null;
     const query = promptText(messages);
     if (query.length < state.config.minQueryLength) return null;
     const block = await buildRecallBlock(
@@ -140,12 +141,12 @@ export class OpenVikingRuntime {
         log: (stage, data) => this.log(stage, data),
       },
     );
-    return block ? pluginMessage(block, "recall") : null;
+    return block ? pluginMessage(block, { form: "recall" }) : null;
   }
 
   capture(session, event) {
     const state = this.stateFor(session);
-    if (!state.config.syncTurns) return;
+    if (!isCaptureEnabled(state.config)) return;
     const payload = captureEvent(event, state.config, state.toolNames);
     if (!payload) return;
     this.enqueueWrite(state, async () => {
@@ -177,7 +178,7 @@ export class OpenVikingRuntime {
   maybeCommit(session, event) {
     if (event.type !== "turn/end") return;
     const state = this.stateFor(session);
-    if (!state.config.syncTurns) return;
+    if (!isCaptureEnabled(state.config)) return;
     this.enqueueWrite(state, async () => {
       if (state.hasPendingWrites) return;
       if (!state.ready && !(await this.ensureState(state)).ready) return;
@@ -210,7 +211,7 @@ export class OpenVikingRuntime {
     if (state.disposing) return state.disposing;
     state.disposing = (async () => {
       this.enqueueWrite(state, async () => {
-        if (!state.config.syncTurns) return;
+        if (!isCaptureEnabled(state.config)) return;
         const commitPayload = {
           keep_recent_count: state.config.commitKeepRecentCount,
         };
@@ -403,19 +404,6 @@ export class OpenVikingRuntime {
   }
 }
 
-function pluginMessage(content, form) {
-  // dsh's own constructor: identity, normalization, and any future Message
-  // invariants come from the pinned peer instead of a hand-built object.
-  return createUserMessage({
-    content: [{ type: "text", text: content }],
-    source: {
-      kind: "plugin",
-      plugin: OPENVIKING_PLUGIN_SOURCE,
-      form,
-    },
-  });
-}
-
 function hasStartupProfile(agent) {
   const session = agent.session;
   const ownEvents = typeof session?.ownEvents === "function"

package/servers/mcp-proxy.mjs

@@ -4,40 +4,30 @@
  * stdio -> streamable-HTTP MCP proxy for the OpenViking DSH bundle.
  *
  * DSH's MCP bridge starts this process as a local stdio MCP server. The proxy
- * reads the same OpenViking credential sources as the in-process runtime; the
- * bundle also forwards its resolved config through the child environment, so
- * values that came from the Cordis patch survive the process boundary.
+ * resolves its connection through the same `resolveConfig()` as the in-process
+ * runtime, from the child environment the bundle builds in `mcp.mjs`: DSH
+ * scrubs credential-shaped names out of what it inherits, and values that came
+ * from the Cordis patch are invisible to a subprocess otherwise.
  */
 
 import { resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveConfig } from "../config.mjs";
-import { resolveOpenVikingCredentials } from "../shared/credentials.mjs";
 import { createLogger } from "../shared/debug-log.mjs";
-import { buildMcpProxyConfig } from "../shared/mcp-proxy-config.mjs";
+import { toMcpProxyConfig } from "../shared/mcp-proxy-config.mjs";
 import { createOpenVikingMcpProxy } from "../shared/mcp-proxy-core.mjs";
 
 export function readProxyConfig(env = process.env, cwd = process.cwd()) {
   const cfg = resolveConfig({}, env, cwd);
-  const creds = resolveOpenVikingCredentials(env);
-  return buildMcpProxyConfig({
-    baseUrl: cfg.endpoint,
-    apiKey: cfg.apiKey,
-    account: cfg.account,
-    user: cfg.user,
+  return toMcpProxyConfig(cfg, {
+    env,
     // Not gated through `resolveMcpActorPeerId` like the other proxies: DSH's
     // parent process resolves the peer per session and hands it over in the
-    // child env (`mcp.mjs` `buildMcpConfig`), so this one is not a guess at the
-    // launch directory.
-    peerId: cfg.peerId,
-    userAgent: cfg.userAgent,
-    timeoutMs: cfg.requestTimeoutMs,
+    // child env. Empty means it has none, and deriving one from wherever DSH
+    // launched this process would send a peer the runtime does not.
+    peerId: String(env.OPENVIKING_PEER_ID || "").trim(),
     debug: Boolean(env.OV_DEBUG_LOG),
-    debugLogPath: env.OV_DEBUG_LOG,
-    credentialSource: creds.credentialSource,
-    credentialPath: creds.cliPath || creds.ovPath,
-    watchedPaths: [creds.cliPath, creds.ovPath, creds.cliPathCandidate],
-    env,
+    debugLogPath: env.OV_DEBUG_LOG || "",
   });
 }
 

package/shared/capture-utils.mjs

@@ -266,7 +266,13 @@ export function extractTextFromPayload(payload, options = {}) {
   return chunks.join("\n\n");
 }
 
-function collectToolNamesByIdFromEntries(entries) {
+/**
+ * Map every tool call id in a transcript to the name of the tool it invoked.
+ *
+ * A result block names the call by id only, so the name has to come from the
+ * call that preceded it. Pass the map as `toolNameById` to the extractors.
+ */
+export function collectToolNamesByIdFromEntries(entries) {
   const map = {};
   for (const entry of entries || []) {
     const payload = entry?.payload && typeof entry.payload === "object" ? entry.payload : entry;
@@ -433,6 +439,24 @@ export function extractCaptureTurns(rolloutEntries, cfg = {}) {
   return turns;
 }
 
+/**
+ * Index of the last turn that came from a human prompt, or -1.
+ *
+ * `role === "user"` alone is not enough: normalizeCaptureRole() maps tool
+ * results onto the user role too, and those carry `tool` parts rather than
+ * `text` parts. Used by the post-compact shrink path to find where the current
+ * interaction starts.
+ */
+export function findLastHumanTurnIndex(turns) {
+  const list = Array.isArray(turns) ? turns : [];
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const turn = list[i];
+    if (turn?.role !== "user") continue;
+    if (turn.parts?.some((part) => part?.type === "text")) return i;
+  }
+  return -1;
+}
+
 export function normalizeCaptureRole(role) {
   const value = normalizeType(role);
   if (value === "user") return "user";
@@ -511,12 +535,24 @@ function stripInjectedDigestBlocks(text) {
   return out.join("\n");
 }
 
+/**
+ * Drop everything in a turn that the conversation did not put there.
+ *
+ * Recall injects a context block into the prompt, and the host adds notes of
+ * its own; captured back unchanged, this turn's injection becomes next turn's
+ * memory and the loop feeds on itself. Formatting the conversation did author
+ * — newlines, code fences — survives.
+ */
 export function sanitizeCapturedText(text) {
   let value = String(text || "");
   value = value
     .replace(/\u0000/g, "")
     .replace(/<openviking-context\b[^>]*>[\s\S]*?<\/openviking-context>/gi, " ")
     .replace(/<relevant-memor(?:y|ies)\b[^>]*>[\s\S]*?<\/relevant-memor(?:y|ies)>/gi, " ")
+    // Claude Code wraps its own out-of-band notes to the model in these two
+    // shapes. They are the host talking to itself, not the conversation.
+    .replace(/<system-reminder\b[^>]*>[\s\S]*?<\/system-reminder>/gi, " ")
+    .replace(/^[ \t]*\[Subagent Context\][^\n]*$/gim, " ")
     .replace(/^\s*Sender\s*\([^)]+\)\s*```[\s\S]*?```\s*/gim, " ")
     .replace(/^\s*Conversation (?:metadata|info):\s*```[\s\S]*?```\s*/gim, " ")
     .replace(/^\s*\[?\d{4}-\d{2}-\d{2}[T ][^\]\n]{3,80}\]?\s*/gm, "")
@@ -540,6 +576,23 @@ function isPunctuationOnly(text) {
   return !/[a-z0-9\u3400-\u9fff]/i.test(text);
 }
 
+/**
+ * Is capture on for this config?
+ *
+ * The switch has four spellings in the wild: a boolean `autoCapture`, 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 capture under an older name still disables it.
+ */
+export function isCaptureEnabled(cfg = {}) {
+  for (const value of [cfg.enabled, cfg.autoCapture, cfg.capture, cfg.syncTurns]) {
+    if (value === false) return false;
+    if (value && typeof value === "object" && !Array.isArray(value) && value.enabled === false) return false;
+  }
+  return true;
+}
+
 export function shouldCaptureText(text, role, cfg = {}, { filters = true } = {}) {
   const maxLength = cfg.captureMaxLength || 24000;
   const sanitized = sanitizeCapturedText(text);
@@ -576,3 +629,26 @@ export function shouldCaptureText(text, role, cfg = {}, { filters = true } = {})
 
   return { shouldCapture: true, reason: "ok", text: capped };
 }
+
+/**
+ * Apply the capture filter to a list of `{ role, content }` turns.
+ *
+ * The harnesses that compose `agent-hook-runtime` used to send whatever their
+ * transcript parser produced: an acknowledgement, a slash command, a stray
+ * `ok`, or a turn far past `captureMaxLength` all reached the extractor
+ * verbatim. This is the same decision every other harness makes, in one place,
+ * so a thin harness gets it by calling rather than by reimplementing it.
+ *
+ * Returns the surviving turns with `content` replaced by the sanitized and
+ * capped text, and the dropped ones with the reason, for the debug log.
+ */
+export function filterCaptureTurns(turns, cfg = {}) {
+  const kept = [];
+  const dropped = [];
+  for (const turn of Array.isArray(turns) ? turns : []) {
+    const decision = shouldCaptureText(turn?.content, turn?.role, cfg);
+    if (decision.shouldCapture) kept.push({ ...turn, content: decision.text });
+    else dropped.push({ role: turn?.role, reason: decision.reason });
+  }
+  return { kept, dropped };
+}

package/shared/config-schema.mjs

@@ -0,0 +1,359 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Every knob a memory plugin reads, declared once.
+ *
+ * A setting stayed uniform across harnesses only when a shared module read it
+ * on the hot path: `recallLimit`, `scoreThreshold` and `captureMaxLength` agree
+ * everywhere because `recall-core` and `capture-utils` read them. Everything
+ * else drifted — the same switch is `autoRecall` in three loaders, an
+ * `autoRecall` *object* in opencode, `syncTurns` in dsh and pi, and absent from
+ * the thin hook runtime — because each loader hand-wrote its own list and the
+ * author picked a name. Three more lists then had to be kept in step by hand:
+ * the doctor's known-knob set, the workspace file's dotted-key map, and the
+ * implicit inventory inside `loadAgentHookConfig`.
+ *
+ * This module is the one list. The others are projections of it:
+ * `pluginConfigKeys()` for the doctor, `WORKSPACE_KNOB_MAP` for the workspace
+ * file, and `resolveKnobs()` for every loader. A knob added here reaches all of
+ * them; a knob spelled wrong reaches none.
+ *
+ * Declaration fields:
+ *   name        canonical key, and the property the loaders read
+ *   type        bool | int | number | enum | string | list
+ *   default     value when no layer supplies one
+ *   harness     per-harness default, where one genuinely differs
+ *   min/max     clamped, not rejected: a config file must not kill a hook
+ *   values      the enum's members; anything else falls back to the default
+ *   env         OPENVIKING_* variable, the highest-priority layer
+ *   aliases     older spellings, honoured forever; the doctor names them
+ *   workspace   dotted key in `.openviking/config.json`
+ *   capability  which capability owns it, for the switches in recall/capture
+ *   sendOnlyWhenConfigured
+ *               the request omits this field unless a layer actually set it,
+ *               so the server's own default stands. Loaders project the flag
+ *               as `<name>Configured` and `recall-core` reads it from there.
+ */
+
+export const CAPABILITIES = ["connection", "peer", "recall", "capture", "session", "debug"];
+
+/** @type {ReadonlyArray<object>} */
+export const KNOBS = [
+  // ── connection and identity ────────────────────────────────────────────
+  // Credentials resolve through `credentials.mjs`; these entries exist so the
+  // doctor recognises them inside `plugin` and so ov.conf's harness section
+  // keeps working.
+  { name: "enabled", type: "bool", default: true, env: "OPENVIKING_MEMORY_ENABLED", capability: "connection" },
+  { name: "apiKey", type: "string", default: "", capability: "connection" },
+  { name: "accountId", type: "string", default: "", capability: "connection" },
+  { name: "userId", type: "string", default: "", capability: "connection" },
+  { name: "authMode", type: "enum", values: ["trusted", "api_key"], default: "", env: "OPENVIKING_AUTH_MODE", aliases: ["auth_mode"], capability: "connection" },
+  {
+    name: "timeoutMs",
+    type: "int",
+    default: 15000,
+    // opencode drives an editor session that tolerates a slower call; dsh runs
+    // inside a chat host that does not.
+    harness: { opencode: 30000, dsh: 10000 },
+    min: 1000,
+    max: 300000,
+    env: "OPENVIKING_TIMEOUT_MS",
+    aliases: ["requestTimeoutMs"],
+    capability: "connection",
+  },
+  { name: "mcpEnabled", type: "bool", default: true, capability: "connection" },
+  { name: "mcpToolCallTimeoutMs", type: "int", default: 60000, min: 1000, max: 600000, capability: "connection" },
+  { name: "dataDir", type: "string", default: "", capability: "connection" },
+
+  { name: "peerId", type: "string", default: "", env: "OPENVIKING_PEER_ID", aliases: ["peer_id"], workspace: "peer.id", capability: "peer" },
+  { name: "peerSource", type: "template", default: "", env: "OPENVIKING_PEER_SOURCE", workspace: "peer.source", capability: "peer" },
+  { name: "workspacePeer", type: "bool", default: true, env: "OPENVIKING_WORKSPACE_PEER", capability: "peer" },
+
+  // ── recall ────────────────────────────────────────────────────────────
+  {
+    name: "autoRecall",
+    type: "bool",
+    default: true,
+    env: "OPENVIKING_AUTO_RECALL",
+    workspace: "recall.enabled",
+    capability: "recall",
+  },
+  { name: "recallLimit", type: "int", default: 10, min: 1, max: 50, env: "OPENVIKING_RECALL_LIMIT", workspace: "recall.max_items", sendOnlyWhenConfigured: true, capability: "recall" },
+  { name: "scoreThreshold", type: "number", default: 0.35, min: 0, max: 1, env: "OPENVIKING_SCORE_THRESHOLD", aliases: ["recallScoreThreshold"], workspace: "recall.score_threshold", capability: "recall" },
+  { name: "minQueryLength", type: "int", default: 3, min: 1, max: 64, env: "OPENVIKING_MIN_QUERY_LENGTH", aliases: ["recallMinQueryLength"], capability: "recall" },
+  { name: "recallTokenBudget", type: "int", default: 2000, min: 200, max: 50000, env: "OPENVIKING_RECALL_TOKEN_BUDGET", aliases: ["recallBudget"], capability: "recall" },
+  { name: "recallMaxContentChars", type: "int", default: 500, min: 100, max: 5000, env: "OPENVIKING_RECALL_MAX_CONTENT_CHARS", capability: "recall" },
+  { name: "recallPreferAbstract", type: "bool", default: true, env: "OPENVIKING_RECALL_PREFER_ABSTRACT", capability: "recall" },
+  { name: "recallPeerScope", type: "enum", values: ["all", "actor"], default: "all", env: "OPENVIKING_RECALL_PEER_SCOPE", workspace: "recall.peer_scope", capability: "recall" },
+  { name: "recallDedupTurns", type: "int", default: 5, min: 0, max: 20, env: "OPENVIKING_RECALL_DEDUP_TURNS", workspace: "recall.dedup_turns", capability: "recall" },
+  { name: "recallMaxTokens", type: "int", default: 1600, min: 64, max: 200000, env: "OPENVIKING_RECALL_MAX_TOKENS", sendOnlyWhenConfigured: true, capability: "recall" },
+  { name: "recallQueryExpansion", type: "enum", values: ["auto", "off"], default: "auto", env: "OPENVIKING_RECALL_QUERY_EXPANSION", sendOnlyWhenConfigured: true, capability: "recall" },
+  { name: "recallTimeoutMs", type: "int", default: 120000, min: 1000, max: 600000, env: "OPENVIKING_RECALL_TIMEOUT_MS", capability: "recall" },
+  // 0 keeps the built-in default, which outlasts the server's rewrite fuse.
+  { name: "recallContextTimeoutMs", type: "int", default: 0, min: 0, max: 600000, env: "OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS", capability: "recall" },
+  { name: "logRankingDetails", type: "bool", default: false, env: "OPENVIKING_LOG_RANKING_DETAILS", capability: "recall" },
+  { name: "recallLedger", type: "bool", default: true, env: "OPENVIKING_RECALL_LEDGER", capability: "recall" },
+  { name: "recallQueryFilters", type: "list", default: [], env: "OPENVIKING_RECALL_QUERY_FILTERS", capability: "recall" },
+
+  // Digest compression. Claude Code reads this as the tri-state
+  // off/client/server/auto through `normalizeRewriteMode`; Codex reads the same
+  // key as on/off. Both spellings stay declared so neither harness's users are
+  // told their config is a typo.
+  { name: "recallCompress", type: "string", default: "auto", env: "OPENVIKING_RECALL_COMPRESS", aliases: ["recallRewrite"], capability: "recall" },
+  { name: "recallCompressModel", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_MODEL", capability: "recall" },
+  { name: "recallCompressBaseUrl", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_BASE_URL", capability: "recall" },
+  { name: "recallCompressThinking", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_THINKING", aliases: ["recallCompressReasoningEffort"], capability: "recall" },
+  // 0 means "derive from recallTimeoutMs" — the loader that owns the fallback
+  // is the one that knows the request budget it has to fit inside.
+  { name: "recallCompressTimeoutMs", type: "int", default: 0, min: 0, max: 600000, env: "OPENVIKING_RECALL_COMPRESS_TIMEOUT_MS", capability: "recall" },
+  { name: "recallCompressDetectOnStartup", type: "bool", default: true, env: "OPENVIKING_RECALL_COMPRESS_DETECT_ON_STARTUP", capability: "recall" },
+  { name: "recallCompressDetectTimeoutMs", type: "int", default: 15000, min: 1000, max: 600000, env: "OPENVIKING_RECALL_COMPRESS_DETECT_TIMEOUT_MS", capability: "recall" },
+  { name: "recallCompressDetectTtlMs", type: "int", default: 604800000, min: 0, capability: "recall", env: "OPENVIKING_RECALL_COMPRESS_DETECT_TTL_MS" },
+  { name: "recallCompressMinInputChars", type: "int", default: 1500, min: 0, max: 100000, env: "OPENVIKING_RECALL_COMPRESS_MIN_INPUT_CHARS", capability: "recall" },
+  { name: "recallCompressMaxInputChars", type: "int", default: 18000, min: 1000, max: 200000, env: "OPENVIKING_RECALL_COMPRESS_MAX_INPUT_CHARS", capability: "recall" },
+  { name: "recallCompressMaxBullets", type: "int", default: 6, min: 1, max: 50, env: "OPENVIKING_RECALL_COMPRESS_MAX_BULLETS", sendOnlyWhenConfigured: true, capability: "recall" },
+
+  // ── capture ───────────────────────────────────────────────────────────
+  // `syncTurns` is dsh and pi's spelling of the same switch. It stays an alias
+  // rather than a second knob so `ov config switch` moves both.
+  {
+    name: "autoCapture",
+    type: "bool",
+    default: true,
+    env: "OPENVIKING_AUTO_CAPTURE",
+    aliases: ["syncTurns"],
+    workspace: "capture.enabled",
+    capability: "capture",
+  },
+  { name: "captureMode", type: "enum", values: ["semantic", "keyword"], default: "semantic", env: "OPENVIKING_CAPTURE_MODE", capability: "capture" },
+  { name: "captureMaxLength", type: "int", default: 24000, min: 200, max: 100000, env: "OPENVIKING_CAPTURE_MAX_LENGTH", capability: "capture" },
+  // Tool output is reported verbatim; the server owns truncation via
+  // tool_output_externalization. This cap only guards pathological payloads.
+  { name: "captureToolMaxChars", type: "int", default: 1000000, min: 200, max: 1000000, env: "OPENVIKING_CAPTURE_TOOL_MAX_CHARS", capability: "capture" },
+  // Default true: a memory plugin that only sees the user's half of the
+  // conversation extracts noticeably worse.
+  { name: "captureAssistantTurns", type: "bool", default: true, env: "OPENVIKING_CAPTURE_ASSISTANT_TURNS", capability: "capture" },
+  { name: "captureLastAssistantOnStop", type: "bool", default: true, env: "OPENVIKING_CAPTURE_LAST_ASSISTANT_ON_STOP", capability: "capture" },
+  { name: "captureToolResults", type: "bool", default: false, env: "OPENVIKING_CAPTURE_TOOL_RESULTS", capability: "capture" },
+  { name: "captureFilters", type: "list", default: [], env: "OPENVIKING_CAPTURE_FILTERS", capability: "capture" },
+  // 0 means "derive from timeoutMs": a write gets a longer budget than a read.
+  { name: "captureTimeoutMs", type: "int", default: 0, min: 0, max: 600000, env: "OPENVIKING_CAPTURE_TIMEOUT_MS", capability: "capture" },
+  { name: "commitTokenThreshold", type: "int", default: 20000, min: 1000, max: 1000000, env: "OPENVIKING_COMMIT_TOKEN_THRESHOLD", workspace: "capture.commit_token_threshold", capability: "capture" },
+  { name: "commitKeepRecentCount", type: "int", default: 10, min: 0, max: 1000, env: "OPENVIKING_COMMIT_KEEP_RECENT_COUNT", capability: "capture" },
+  { name: "commitTurnThreshold", type: "int", default: 8, min: 1, max: 1000, env: "OPENVIKING_COMMIT_TURN_THRESHOLD", capability: "capture" },
+  { name: "autoCommitOnCompact", type: "bool", default: true, env: "OPENVIKING_AUTO_COMMIT_ON_COMPACT", capability: "capture" },
+  { name: "writePathAsync", type: "bool", default: true, env: "OPENVIKING_WRITE_PATH_ASYNC", capability: "capture" },
+
+  // ── session lifecycle ─────────────────────────────────────────────────
+  { name: "noAutoInject", type: "bool", default: false, env: "OPENVIKING_NO_AUTO_INJECT", capability: "session" },
+  { name: "profileTokenBudget", type: "int", default: 10000, min: 500, max: 50000, env: "OPENVIKING_PROFILE_TOKEN_BUDGET", aliases: ["profileBudget"], capability: "session" },
+  { name: "resumeContextBudget", type: "int", default: 32000, min: 1024, max: 128000, env: "OPENVIKING_RESUME_CONTEXT_BUDGET", capability: "session" },
+  { name: "resumeArchiveInject", type: "bool", default: true, env: "OPENVIKING_RESUME_ARCHIVE_INJECT", capability: "session" },
+  { name: "resumeArchiveTokenBudget", type: "int", default: 32000, min: 0, max: 128000, env: "OPENVIKING_RESUME_ARCHIVE_TOKEN_BUDGET", capability: "session" },
+  { name: "resumeArchiveMaxChars", type: "int", default: 6000, min: 1000, max: 200000, env: "OPENVIKING_RESUME_ARCHIVE_MAX_CHARS", capability: "session" },
+  { name: "skillExperience", type: "bool", default: false, env: "OPENVIKING_SKILL_EXPERIENCE", capability: "session" },
+  { name: "skillExperienceLimit", type: "int", default: 3, min: 1, max: 50, env: "OPENVIKING_SKILL_EXPERIENCE_LIMIT", capability: "session" },
+  { name: "skipSubagentSessions", type: "bool", default: false, env: "OPENVIKING_SKIP_SUBAGENT_SESSIONS", capability: "session" },
+  { name: "repoContext", type: "bool", default: true, capability: "session" },
+  { name: "repoContextCacheTtlMs", type: "int", default: 60000, min: 1000, max: 3600000, capability: "session" },
+
+  { name: "takeoverEnabled", type: "bool", default: true, env: "OPENVIKING_TAKEOVER", capability: "session" },
+  { name: "takeoverTokenThreshold", type: "int", default: 30000, min: 1, max: 1000000, capability: "session" },
+  { name: "takeoverKeepRecentTurns", type: "int", default: 3, min: 0, max: 100, capability: "session" },
+  { name: "takeoverOverviewBudget", type: "int", default: 3000, min: 100, max: 50000, capability: "session" },
+  { name: "takeoverOverviewPollMs", type: "int", default: 2000, min: 0, max: 60000, capability: "session" },
+  { name: "takeoverOverviewPollMax", type: "int", default: 15, min: 1, max: 120, capability: "session" },
+
+  { name: "bypassSession", type: "bool", default: false, env: "OPENVIKING_BYPASS_SESSION", capability: "session" },
+  {
+    name: "bypassSessionPatterns",
+    type: "list",
+    default: [],
+    env: "OPENVIKING_BYPASS_SESSION_PATTERNS",
+    // pi shipped this under its own name before the shared matcher existed.
+    aliases: ["bypassPatterns"],
+    workspace: "bypass.session_patterns",
+    capability: "session",
+  },
+
+  // ── debug ─────────────────────────────────────────────────────────────
+  { name: "debug", type: "bool", default: false, env: "OPENVIKING_DEBUG", capability: "debug" },
+  // The default path is per-harness and built from a log directory the loader
+  // owns, so the schema only carries what a user set.
+  { name: "debugLogPath", type: "string", default: "", env: "OPENVIKING_DEBUG_LOG", capability: "debug" },
+  { name: "logLevel", type: "enum", values: ["silent", "error", "info"], default: "error", env: "OPENVIKING_LOG_LEVEL", capability: "debug" },
+];
+
+export const KNOB_BY_NAME = new Map(KNOBS.map((knob) => [knob.name, knob]));
+
+/** Every accepted spelling → the canonical knob it means. */
+export const KNOB_BY_KEY = new Map();
+for (const knob of KNOBS) {
+  KNOB_BY_KEY.set(knob.name, knob);
+  for (const alias of knob.aliases || []) KNOB_BY_KEY.set(alias, knob);
+}
+
+/** Every key a user may legitimately write in `ovcli.conf`'s plugin section. */
+export function pluginConfigKeys() {
+  return new Set(KNOB_BY_KEY.keys());
+}
+
+/** The workspace file's dotted keys → the knob each one sets. */
+export const WORKSPACE_KNOB_MAP = Object.fromEntries(
+  KNOBS.filter((knob) => knob.workspace).map((knob) => [knob.workspace, knob.name]),
+);
+
+/** The enum members and clamps the workspace validator reports on. */
+export const WORKSPACE_ENUMS = Object.fromEntries(
+  KNOBS.filter((knob) => knob.workspace).map((knob) => [knob.workspace, knob.values || null]),
+);
+
+export const WORKSPACE_RANGES = Object.fromEntries(
+  KNOBS.filter((knob) => knob.workspace && knob.min !== undefined && knob.max !== undefined)
+    .map((knob) => [knob.workspace, {
+      min: knob.min,
+      max: knob.max,
+      integer: knob.type === "int",
+    }]),
+);
+
+/**
+ * The harnesses that may appear as a per-harness object inside `plugin`.
+ *
+ * The key is snake_case because that is what ov.conf's own sections use; the
+ * hyphenated spelling a host calls itself (`claude-code`, `trae-cn`) is
+ * accepted too, so a user who copies the harness name out of the installer
+ * lands on the right override instead of on a silent no-op.
+ */
+export const HARNESS_KEYS = {
+  claudeCode: "claude_code",
+  codex: "codex",
+  cursor: "cursor",
+  trae: "trae",
+  traeCn: "trae_cn",
+  zcode: "zcode",
+  opencode: "opencode",
+  dsh: "dsh",
+  pi: "pi",
+  openclaw: "openclaw",
+};
+
+export function harnessKey(harness) {
+  return String(harness || "").trim().toLowerCase().replace(/-/g, "_");
+}
+
+/** Both accepted spellings of every harness, for the `plugin` section. */
+export const HARNESS_CONFIG_KEYS = new Set(
+  Object.values(HARNESS_KEYS).flatMap((key) => [key, key.replace(/_/g, "-")]),
+);
+
+export function knobDefault(knob, harness = "") {
+  if (harness && knob.harness && knob.harness[harness] !== undefined) return knob.harness[harness];
+  return Array.isArray(knob.default) ? [...knob.default] : knob.default;
+}
+
+const TRUE_WORDS = ["1", "true", "yes", "on"];
+const FALSE_WORDS = ["0", "false", "no", "off"];
+
+/**
+ * Coerce one raw value to the knob's type.
+ *
+ * A value out of range is clamped and a value of the wrong shape falls back to
+ * the default: a hook that dies because someone typed a letter into a number
+ * would take the host's session down with it.
+ */
+export function coerceKnobValue(knob, raw, fallback) {
+  if (raw === undefined || raw === null) return fallback;
+  switch (knob.type) {
+    case "bool": {
+      if (typeof raw === "boolean") return raw;
+      const word = String(raw).trim().toLowerCase();
+      if (TRUE_WORDS.includes(word)) return true;
+      if (FALSE_WORDS.includes(word)) return false;
+      return fallback;
+    }
+    case "int":
+    case "number": {
+      if (typeof raw === "string" && !raw.trim()) return fallback;
+      const value = knob.type === "int" ? Math.round(Number(raw)) : Number(raw);
+      if (!Number.isFinite(value)) return fallback;
+      const floored = knob.min === undefined ? value : Math.max(knob.min, value);
+      return knob.max === undefined ? floored : Math.min(knob.max, floored);
+    }
+    case "enum": {
+      const word = String(raw ?? "").trim();
+      return (knob.values || []).includes(word) ? word : fallback;
+    }
+    // A peer template may be one string or an ordered list of fallbacks, and
+    // `String([a, b])` would quietly turn the list into one bogus template.
+    case "template": {
+      if (Array.isArray(raw)) {
+        const items = raw.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+        return items.length ? items : fallback;
+      }
+      const text = String(raw ?? "").trim();
+      return text ? text : fallback;
+    }
+    case "list": {
+      const items = Array.isArray(raw)
+        ? raw
+        : typeof raw === "string" ? raw.split(",") : null;
+      if (!items) return fallback;
+      return items.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+    }
+    default: {
+      const text = String(raw ?? "").trim();
+      return text ? text : fallback;
+    }
+  }
+}
+
+/**
+ * Resolve every knob through the layers, lowest priority first.
+ *
+ * `layers` is `[{ name, data }]`; `env` is the top layer and needs no entry.
+ * Returns the settings plus the names a layer actually supplied, which is what
+ * the `*Configured` flags report — several call sites send a field to the
+ * server only when the user asked for it, and a default must not look asked-for.
+ */
+export function resolveKnobs({ harness = "", layers = [], env = {} } = {}) {
+  const settings = {};
+  const configured = new Set();
+  const sources = {};
+  // A value that would not parse is not a configuration: without this sentinel
+  // `recallLimit: "abc"` would report as configured and send a default to the
+  // server dressed up as the user's choice.
+  const UNPARSEABLE = Symbol("unparseable");
+
+  const take = (knob, raw, source, current) => {
+    const value = coerceKnobValue(knob, raw, UNPARSEABLE);
+    if (value === UNPARSEABLE) return current;
+    configured.add(knob.name);
+    sources[knob.name] = source;
+    return value;
+  };
+
+  for (const knob of KNOBS) {
+    let value = knobDefault(knob, harness);
+    for (const layer of layers) {
+      const data = layer?.data;
+      if (!data || typeof data !== "object") continue;
+      // Aliases first so the canonical name wins when one layer carries both:
+      // a file with `recallCompressThinking` beside its older
+      // `recallCompressReasoningEffort` means the newer one.
+      for (const key of [...(knob.aliases || []), knob.name]) {
+        if (!Object.prototype.hasOwnProperty.call(data, key)) continue;
+        if (data[key] === undefined) continue;
+        value = take(knob, data[key], layer.name || "file", value);
+      }
+    }
+    if (knob.env) {
+      const raw = env[knob.env];
+      if (raw !== undefined && raw !== null && String(raw) !== "") {
+        value = take(knob, raw, "env", value);
+      }
+    }
+    settings[knob.name] = value;
+  }
+
+  return { settings, configured, sources };
+}