Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
21.4 KB
Raw Blame
/**
 * Shared adapter body for runtimes that consume MCP servers via a JSON
 * config file with a top-level object (default `mcpServers`). Cursor,
 * kiro, Gemini CLI follow the default shape; opencode reuses the same
 * body with a custom top-level key and entry shape.
 *
 * Per-target specifics (config path, top-level key, post-install notes)
 * are injected via `JsonMcpAdapterSpec`. The body itself owns
 * idempotency, drift detection, manifest I/O, and the
 * user-modified-block safety net.
 *
 * What `verify` here can and cannot prove: it compares the on-disk config
 * against the canonical payload. It does not, and cannot from this side,
 * establish that the runtime loaded the entry - see the comment on the
 * `ok` return, where a declared-but-never-implemented MCP probe seam used
 * to make that ambiguity invisible.
 */

import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
import { dirname } from "node:path";

import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { renderUnifiedDiff } from "../../diff.ts";
import { redactStructured } from "../../redactor.ts";
import type { InstallTargetId } from "../../runtime/host-facts.ts";
import { handshakeNote, probeHost, probeRefutedVerdict, probeRefutes } from "../host-probe.ts";
import { payloadWithRuntimeIdentity } from "../identity.ts";
import {
  mergeMcpServers,
  removeMcpServers,
  JsonMergeError,
  OSB_KEY_FULL,
  OSB_KEY_WRITER,
} from "../json-merge.ts";
import { payloadForHost } from "../payload-host.ts";
import { recordEntry, readManifest, removeEntry } from "../manifest.ts";
import { deepJsonEquals, expectedPayloadFromEnv, payloadKeyEquals } from "../payload-equals.ts";
import {
  InstallError,
  type ApplyOpts,
  type ApplyResult,
  type DetectResult,
  type InstallAdapter,
  type InstallEnv,
  type InstallPlan,
  type ManifestEntry,
  type McpPayload,
  type McpServerEntry,
  type SessionPathsResult,
  type UninstallResult,
  type VerifyResult,
} from "../types.ts";
import { sessionPathsFor } from "../session-paths.ts";

export interface JsonMcpAdapterSpec {
  /** The runtime this spec installs into; becomes `InstallAdapter.target`. */
  readonly target: InstallTargetId;
  readonly label: string;
  /** Top-level key under which MCP servers live. Default `mcpServers`. */
  readonly topLevelKey?: string;
  /**
   * Maps the canonical `McpServerEntry` to the runtime's on-disk entry
   * shape. Default emits `{command, args, env?}`. Adapters whose runtime
   * uses a different schema (opencode: `{type, command: [bin, ...args],
   * environment?, enabled}`) inject the mapping here.
   */
  readonly serializeEntry?: (entry: McpServerEntry) => Record<string, unknown>;
  /**
   * Compares an on-disk entry against the canonical payload for
   * idempotency and drift detection. Defaults to `payloadKeyEquals`
   * when `serializeEntry` is absent, and to strict structural equality
   * against `serializeEntry(expected)` when it is present.
   */
  readonly entryEquals?: (
    current: Record<string, unknown> | undefined,
    expected: McpServerEntry,
  ) => boolean;
  /** Resolves the absolute path to the runtime's config file. */
  resolveConfigPath(env: InstallEnv): string;
  /** Extra notes attached to `detect.notes` / plan output. */
  readonly notes?: ReadonlyArray<string>;
  /** Plan-level post-install reminders (e.g. "restart Cursor app"). */
  readonly postNotes?: ReadonlyArray<string>;
  /** Fix-hint text for `verify` when drift detected. */
  readonly fixHintForDrift?: string;
  /**
   * When set, stamp this runtime's own id (`target`) as `VAULT_AGENT_NAME` so
   * its Brain writes attribute to itself rather than inheriting the shared
   * operator name. Opt-in: only real runtime integrations set it; the generic
   * "other MCP host" adapters leave the operator name untouched.
   */
  readonly runtimeIdentity?: boolean;
}

/** Apply the runtime-identity rule to the payload when the spec opted in. */
function identifyPayload(spec: JsonMcpAdapterSpec, payload: McpPayload): McpPayload {
  return spec.runtimeIdentity ? payloadWithRuntimeIdentity(payload, spec.target) : payload;
}

/**
 * The payload as this target's config file must hold it: the host's own
 * dimensions (tool profile, host id) then the runtime-identity rule.
 *
 * Both transforms are pure functions of the spec and the `InstallEnv`,
 * and every path that touches the file - plan, apply, verify - goes
 * through this one function. That is what keeps re-construction honest:
 * a transform applied on apply but not on verify would report drift
 * against bytes this adapter had just written itself.
 */
function payloadForSpec(
  spec: JsonMcpAdapterSpec,
  payload: McpPayload,
  env: InstallEnv,
): McpPayload {
  return identifyPayload(spec, payloadForHost(spec.target, payload, env));
}

/**
 * The same composition as {@link payloadForSpec}, rebuilt from the
 * `InstallEnv` alone - the verify side of re-construction. It exists so
 * the two sides cannot be assembled in different orders by accident:
 * `verify` once applied the identity rule and not the host rule, which
 * made every runtime-identity adapter report drift against the file it
 * had just written.
 */
function expectedPayloadForSpec(spec: JsonMcpAdapterSpec, env: InstallEnv): McpPayload {
  return identifyPayload(spec, expectedPayloadFromEnv(env, spec.target));
}

function readFileOrEmpty(path: string): string {
  try {
    return readFileSync(path, "utf8");
  } catch {
    return "";
  }
}

function parseJsonObject(raw: string): Record<string, unknown> | null {
  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
  if (text.trim().length === 0) return {};
  try {
    const parsed = JSON.parse(text);
    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
    return parsed as Record<string, unknown>;
  } catch {
    return null;
  }
}

function readMcpBlock(
  root: Record<string, unknown>,
  topKey: string,
): Record<string, unknown> | null {
  const block = root[topKey] ?? {};
  if (block === null || typeof block !== "object" || Array.isArray(block)) return null;
  return block as Record<string, unknown>;
}

function fileMtimeMs(path: string): number | null {
  try {
    return statSync(path).mtimeMs;
  } catch {
    return null;
  }
}

interface OnDiskState {
  readonly exists: boolean;
  readonly canonical: boolean;
  readonly full: Record<string, unknown> | undefined;
  readonly writer: Record<string, unknown> | undefined;
  readonly raw: string;
  readonly mtimeMs: number | null;
}

function readOnDisk(spec: JsonMcpAdapterSpec, env: InstallEnv, payload: McpPayload): OnDiskState {
  const path = spec.resolveConfigPath(env);
  if (!existsSync(path)) {
    return {
      exists: false,
      canonical: false,
      full: undefined,
      writer: undefined,
      raw: "",
      mtimeMs: null,
    };
  }
  const raw = readFileOrEmpty(path);
  const topKey = spec.topLevelKey ?? "mcpServers";
  const parsed = parseJsonObject(raw);
  if (parsed === null) {
    return {
      exists: true,
      canonical: false,
      full: undefined,
      writer: undefined,
      raw,
      mtimeMs: fileMtimeMs(path),
    };
  }
  const block = readMcpBlock(parsed, topKey);
  if (block === null) {
    return {
      exists: true,
      canonical: false,
      full: undefined,
      writer: undefined,
      raw,
      mtimeMs: fileMtimeMs(path),
    };
  }
  const full = block[OSB_KEY_FULL] as Record<string, unknown> | undefined;
  const writer = block[OSB_KEY_WRITER] as Record<string, unknown> | undefined;
  const equals = resolveEntryEquals(spec);
  const canonical = equals(full, payload.full) && equals(writer, payload.writer);
  return { exists: true, canonical, full, writer, raw, mtimeMs: fileMtimeMs(path) };
}

/**
 * Resolution order for the entry comparator: explicit `entryEquals`
 * wins; a spec with only `serializeEntry` gets strict structural
 * equality against the re-serialized canonical entry; the default
 * shape keeps the historical `payloadKeyEquals` semantics (extra
 * top-level entry keys tolerated).
 */
function resolveEntryEquals(
  spec: JsonMcpAdapterSpec,
): (current: Record<string, unknown> | undefined, expected: McpServerEntry) => boolean {
  if (spec.entryEquals) return spec.entryEquals;
  const serialize = spec.serializeEntry;
  if (serialize) {
    return (current, expected) =>
      current !== undefined && deepJsonEquals(current, serialize(expected));
  }
  return payloadKeyEquals;
}

/**
 * Redact one side of the plan diff before it renders. The consent
 * preview must never carry a secret VALUE from the surrounding config:
 * a minified settings file puts every other server's `env` block on the
 * changed lines, and the plan (plain and `--json`) goes to the invoking
 * agent's transcript. Both sides go through `redactStructured` -
 * credential-named keys lose their values, and both sides re-serialize
 * through the same canonical form so the diff still shows exactly the
 * shape change the merge makes. Redaction here is a preview concern
 * only: `apply` keeps writing the untouched bytes.
 */
function redactDiffSide(text: string): string {
  const parsed = parseJsonObject(text);
  if (parsed === null) return text;
  return JSON.stringify(redactStructured(parsed).value, null, 2);
}

/**
 * The file-level half of the plan preview (t_b6bcd984): read the
 * on-disk config, run the exact merge `apply` will run - pure, no
 * write - and render the unified diff the consent flow shows the
 * operator. `null` when nothing would change, or when the on-disk
 * content is not the valid JSON object the merge parses: that case is
 * the drift guard's refusal in `apply`, not a diff this preview can
 * honestly draw. Compute-before-write: `apply` re-reads and re-merges
 * on its own path and stays unchanged here.
 */
function planDiff(
  spec: JsonMcpAdapterSpec,
  payload: McpPayload,
  path: string,
): { diff: string } | null {
  const raw = readFileOrEmpty(path);
  let merged: string;
  try {
    merged = mergeMcpServers(raw, payload, {
      topLevelKey: spec.topLevelKey ?? "mcpServers",
      ...(spec.serializeEntry ? { serializeEntry: spec.serializeEntry } : {}),
    });
  } catch (e) {
    if (e instanceof JsonMergeError) return null;
    throw e;
  }
  if (merged === raw) return null;
  return { diff: renderUnifiedDiff(redactDiffSide(raw), redactDiffSide(merged), path) };
}

export function createJsonMcpAdapter(spec: JsonMcpAdapterSpec): InstallAdapter {
  const topKey = spec.topLevelKey ?? "mcpServers";

  return {
    target: spec.target,
    label: spec.label,

    detect(env: InstallEnv): DetectResult {
      const path = spec.resolveConfigPath(env);
      const baseNotes = [...(spec.notes ?? [])];
      if (!existsSync(path)) {
        return {
          target: spec.target,
          status: "not-installed",
          configPath: path,
          notes: [...baseNotes, "config file missing"],
        };
      }
      const raw = readFileOrEmpty(path);
      const parsed = parseJsonObject(raw);
      if (parsed === null) {
        return {
          target: spec.target,
          status: "drift",
          configPath: path,
          notes: [...baseNotes, "config file is not valid JSON"],
        };
      }
      const block = readMcpBlock(parsed, topKey);
      if (block === null) {
        return {
          target: spec.target,
          status: "drift",
          configPath: path,
          notes: [...baseNotes, `${topKey} is not a JSON object`],
        };
      }
      const hasFull = OSB_KEY_FULL in block;
      const hasWriter = OSB_KEY_WRITER in block;
      if (!hasFull && !hasWriter) {
        return {
          target: spec.target,
          status: "not-installed",
          configPath: path,
          notes: baseNotes,
        };
      }
      if (hasFull && hasWriter) {
        return {
          target: spec.target,
          status: "installed",
          configPath: path,
          notes: [...baseNotes, `both OSB keys present under ${topKey}`],
        };
      }
      return {
        target: spec.target,
        status: "drift",
        configPath: path,
        notes: [
          ...baseNotes,
          `partial OSB install: ${hasFull ? "writer key missing" : "full-server key missing"}`,
        ],
      };
    },

    plan(rawPayload: McpPayload, env: InstallEnv): InstallPlan {
      const path = spec.resolveConfigPath(env);
      // The PREVIEW prints the args that will actually be written, not
      // the un-transformed canonical ones: a plan whose command line
      // differs from the applied one is a plan the operator cannot use
      // to review the change.
      const payload = payloadForSpec(spec, rawPayload, env);
      const preview =
        `json-merge two keys into ${topKey} at ${path}: ` +
        `${OSB_KEY_FULL} → ${payload.full.command} ${payload.full.args.join(" ")}; ` +
        `${OSB_KEY_WRITER} → ${payload.writer.command} ${payload.writer.args.join(" ")}`;
      const diff = planDiff(spec, payload, path);
      return {
        target: spec.target,
        steps: [{ kind: "json-merge", path, preview, ...(diff && { diff: diff.diff }) }],
        postNotes: [...(spec.postNotes ?? [])],
      };
    },

    apply(
      _plan: InstallPlan,
      rawPayload: McpPayload,
      env: InstallEnv,
      opts: ApplyOpts,
    ): ApplyResult {
      const path = spec.resolveConfigPath(env);
      const payload = payloadForSpec(spec, rawPayload, env);
      const onDisk = readOnDisk(spec, env, payload);
      const manifestEntry = readManifest(env.vault).installs[spec.target];

      // Safety net: if the on-disk content differs from canonical AND
      // mtime is newer than manifest.applied_at AND user didn't pass
      // --force, refuse. This catches hand-edits.
      if (
        manifestEntry &&
        onDisk.exists &&
        !onDisk.canonical &&
        // Mixed: file exists but OSB keys are not exactly canonical.
        // If at least one OSB key is present, treat as potentially
        // hand-edited.
        (onDisk.full !== undefined || onDisk.writer !== undefined) &&
        !opts.force
      ) {
        const appliedAt = Date.parse(manifestEntry.applied_at);
        const mtime = onDisk.mtimeMs ?? 0;
        if (Number.isFinite(appliedAt) && mtime > appliedAt + 1000) {
          throw new InstallError(
            `${spec.target}: ${path} appears hand-edited after the last install ` +
              `(mtime newer than manifest applied_at). Refusing to overwrite.`,
            spec.target,
            "user-modified-block",
            "re-run with --force to overwrite, or run `o2b uninstall --target " +
              spec.target +
              " --apply` first",
          );
        }
      }

      const merged = mergeMcpServers(onDisk.raw, payload, {
        topLevelKey: topKey,
        ...(spec.serializeEntry ? { serializeEntry: spec.serializeEntry } : {}),
      });
      const contentChanged = merged !== onDisk.raw;
      if (!opts.dryRun && contentChanged) {
        ensureParent(path);
        atomicWriteFileSync(path, merged);
      }

      // Re-apply with byte-identical content: keep the previous
      // `applied_at` so the user-modified-block detector continues to
      // compare disk mtime against the actual install moment, not the
      // current wall clock.
      const existing = readManifest(env.vault).installs[spec.target];
      const appliedAt = !contentChanged && existing ? existing.applied_at : env.now.toISOString();
      const manifest: ManifestEntry = {
        target: spec.target,
        applied_at: appliedAt,
        operation: "json-merge",
        config_path: path,
        owned_keys: [`${topKey}.${OSB_KEY_FULL}`, `${topKey}.${OSB_KEY_WRITER}`],
      };
      if (!opts.dryRun && (contentChanged || !existing)) {
        recordEntry(env.vault, manifest);
      }

      return {
        target: spec.target,
        manifest,
        steps_executed: opts.dryRun || !contentChanged ? 0 : 1,
      };
    },

    uninstall(env: InstallEnv, opts: ApplyOpts & { fromSnippet?: boolean }): UninstallResult {
      const path = spec.resolveConfigPath(env);
      const stored = readManifest(env.vault).installs[spec.target];
      const skipped: Array<readonly [string, string]> = [];
      const removed_keys: string[] = [];
      const removed_paths: string[] = [];

      if (!stored && !opts.fromSnippet) {
        throw new InstallError(
          `${spec.target}: no install manifest entry found. ` +
            `Pass --force-from-snippet to remove based on the canonical payload.`,
          spec.target,
          "manifest-missing",
          "o2b uninstall --target " + spec.target + " --apply --force-from-snippet",
        );
      }

      if (!existsSync(path)) {
        skipped.push([path, "config file no longer present"]);
        if (!opts.dryRun) removeEntry(env.vault, spec.target);
        return { target: spec.target, removed_keys, removed_paths, skipped };
      }

      const raw = readFileOrEmpty(path);
      const next = removeMcpServers(raw, { topLevelKey: topKey });
      if (!opts.dryRun && next !== raw) {
        atomicWriteFileSync(path, next);
      }
      removed_keys.push(`${topKey}.${OSB_KEY_FULL}`, `${topKey}.${OSB_KEY_WRITER}`);
      if (!opts.dryRun) removeEntry(env.vault, spec.target);
      return { target: spec.target, removed_keys, removed_paths, skipped };
    },

    /**
     * Read off `RUNTIME_FACTS`, not off the spec. Every JSON-MCP host's
     * session store is already declared there, and a `sessionRoots` field
     * on {@link JsonMcpAdapterSpec} would be a second place to spell it.
     */
    sessionPaths(env: InstallEnv): SessionPathsResult | null {
      return sessionPathsFor(spec.target, env);
    },

    verify(env: InstallEnv): VerifyResult {
      const path = spec.resolveConfigPath(env);
      const stored = readManifest(env.vault).installs[spec.target];
      if (!stored) {
        return {
          target: spec.target,
          status: "not-installed",
          details: ["no install manifest entry"],
          fix_hint: null,
        };
      }
      if (!existsSync(path)) {
        return {
          target: spec.target,
          status: "drift",
          details: [`config file missing: ${path}`],
          fix_hint: spec.fixHintForDrift ?? `o2b install --target ${spec.target} --apply`,
        };
      }
      const raw = readFileOrEmpty(path);
      const parsed = parseJsonObject(raw);
      if (parsed === null) {
        return {
          target: spec.target,
          status: "drift",
          details: [`config file is not valid JSON: ${path}`],
          fix_hint: spec.fixHintForDrift ?? `o2b install --target ${spec.target} --apply`,
        };
      }
      const block = readMcpBlock(parsed, topKey);
      if (block === null) {
        return {
          target: spec.target,
          status: "drift",
          details: [`${topKey} is not a JSON object: ${path}`],
          fix_hint: spec.fixHintForDrift ?? `o2b install --target ${spec.target} --apply`,
        };
      }
      const hasFull = OSB_KEY_FULL in block;
      const hasWriter = OSB_KEY_WRITER in block;
      if (!hasFull || !hasWriter) {
        return {
          target: spec.target,
          status: "drift",
          details: [
            `${hasFull ? "" : OSB_KEY_FULL + " key missing; "}${hasWriter ? "" : OSB_KEY_WRITER + " key missing"}`.trim(),
          ],
          fix_hint: spec.fixHintForDrift ?? `o2b install --target ${spec.target} --apply`,
        };
      }
      const expected = expectedPayloadForSpec(spec, env);
      const equals = resolveEntryEquals(spec);
      if (
        !equals(block[OSB_KEY_FULL] as Record<string, unknown> | undefined, expected.full) ||
        !equals(block[OSB_KEY_WRITER] as Record<string, unknown> | undefined, expected.writer)
      ) {
        return {
          target: spec.target,
          status: "drift",
          details: [`${path}: OSB keys differ from canonical payload`],
          fix_hint: spec.fixHintForDrift ?? `o2b install --target ${spec.target} --apply`,
        };
      }
      // The config matches. What that is EVIDENCE of depends on the host,
      // and the fact table is what decides: a target whose `RUNTIME_FACTS`
      // row declares a `hostProbe` gets asked, and the answer - or the
      // named reason there is none - replaces the blanket note. Nothing in
      // this body spawns a runtime's own MCP server to speak a handshake
      // to itself: that would prove WE can run `o2b`, not that Cursor
      // loaded the entry. It asks the host's own CLI what it has
      // registered, which is the only question a host can answer about
      // itself, and no row in this body's population declares one today -
      // so they keep the blanket note, and keep it honestly.
      const probe = probeHost(spec.target, env);
      if (probeRefutes(probe)) {
        // The file was just compared and matches, so the shared rule reads
        // this as a host that has not reloaded it - never as a lost
        // registration.
        const verdict = probeRefutedVerdict({
          target: spec.target,
          label: spec.label,
          artifactMatches: true,
        });
        return {
          target: spec.target,
          status: verdict.status,
          details: [`${path}: matches the canonical payload, but ${handshakeNote(probe)}`],
          fix_hint: verdict.fixHint,
        };
      }
      return {
        target: spec.target,
        status: "ok",
        details: [`${path}: both OSB keys match the canonical payload (${handshakeNote(probe)})`],
        fix_hint: null,
      };
    },
  };
}

function ensureParent(path: string): void {
  const dir = dirname(path);
  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
}