Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

13.7 KB
Raw Blame
import { readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join, resolve as resolvePath } from "node:path";

const DEFAULT_OVCLI_CONF_PATH = join(homedir(), ".openviking", "ovcli.conf");
const DEFAULT_OV_CONF_PATH = join(homedir(), ".openviking", "ov.conf");
const DEFAULT_TIMEOUT_MS = 15000;
const MIN_TIMEOUT_MS = 1000;

function str(val, fallback = "") {
  if (typeof val === "string" && val.trim()) return val.trim();
  return fallback;
}

function normalizePath(value) {
  const raw = str(value, "");
  if (!raw) return "";
  if (raw === "~") return homedir();
  if (raw.startsWith("~/")) return resolvePath(join(homedir(), raw.slice(2)));
  return resolvePath(raw);
}

function tryLoadJson(path) {
  if (!path) return null;
  try {
    return JSON.parse(readFileSync(path, "utf-8"));
  } catch {
    return null;
  }
}

/**
 * Build the User-Agent every harness plugin sends on OpenViking-bound requests.
 * Shape is `name/semver` so downstream stats layers can parse it as one token.
 */
export function buildUserAgent(harness, version) {
  return `openviking-memory-${harness}/${str(version, "") || "0.0.0"}`;
}

/**
 * Read a plugin manifest's `version` field. Accepts a path or a URL (so callers
 * can resolve relative to import.meta.url). Returns "" when unreadable so the
 * User-Agent falls back to 0.0.0 instead of throwing inside a short-lived hook.
 */
export function readManifestVersion(manifest) {
  try {
    return str(JSON.parse(readFileSync(manifest, "utf-8")).version, "");
  } catch {
    return "";
  }
}

function looksLikeOvcli(obj) {
  if (!obj || typeof obj !== "object") return false;
  if (obj.server && typeof obj.server === "object") return false;
  return Boolean(
    typeof obj.url === "string" ||
    typeof obj.api_key === "string" ||
    typeof obj.account === "string" ||
    typeof obj.account_id === "string" ||
    typeof obj.user === "string" ||
    typeof obj.user_id === "string" ||
    typeof obj.actor_peer_id === "string",
  );
}

function hasCredentialFields(obj) {
  if (!obj || typeof obj !== "object") return false;
  return [
    "url",
    "api_key",
    "account",
    "account_id",
    "user",
    "user_id",
    "actor_peer_id",
    "peer_id",
  ].some((key) => typeof obj[key] === "string");
}

export function loadCredentialFiles(env = process.env) {
  const cliPathCandidate = normalizePath(env.OPENVIKING_CLI_CONFIG_FILE) || DEFAULT_OVCLI_CONF_PATH;
  const ovPathCandidate = normalizePath(env.OPENVIKING_CONFIG_FILE) || DEFAULT_OV_CONF_PATH;
  const cliPathEnv = Boolean(str(env.OPENVIKING_CLI_CONFIG_FILE, ""));
  const ovPathEnv = Boolean(str(env.OPENVIKING_CONFIG_FILE, ""));

  let cliFile = tryLoadJson(cliPathCandidate);
  let cliPath = cliFile ? cliPathCandidate : "";
  let ovFile = tryLoadJson(ovPathCandidate);
  let ovPath = ovFile ? ovPathCandidate : "";

  // Backward compat: older plugin installs used OPENVIKING_CONFIG_FILE for
  // both ov.conf and ovcli.conf. Preserve that when the file is ovcli-shaped.
  if (ovPathEnv && !cliPathEnv && looksLikeOvcli(ovFile)) {
    cliFile = ovFile;
    cliPath = ovPath;
    ovFile = null;
    ovPath = "";
  }

  return {
    cliFile: cliFile || {},
    cliPath,
    cliPathCandidate,
    ovFile: ovFile || {},
    ovPath,
  };
}

/**
 * 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();
  if (raw === "env" || raw === "environment") return "env";
  if (raw === "cli" || raw === "ovcli" || raw === "file" || raw === "config") return "cli";
  return "auto";
}

function hasEnvCredentialFields(env) {
  return CREDENTIAL_ENV_VARS.some((name) => str(env[name], ""));
}

function trimSlash(value) {
  return value.replace(/\/+$/, "");
}

/** 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: "" };
}

/**
 * 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 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 {
    ...loaded,
    harness: name,
    credentialSource: pinned ? "ovcli" : ((mode === "env" || envHasCredentials) ? "env" : "auto"),
    baseUrl,
    mcpUrl,
    apiKey: key.value,
    account,
    user,
    peerId,
    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 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";
}

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