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.1 KB
Raw Blame
/**
 * The per-host friction matrix, and the end of the blanket no-handshake
 * claim.
 *
 * Two properties this file exists to hold:
 *
 *   1. The matrix is DERIVED. Its rows come from the live adapter
 *      registry and its cells from `RUNTIME_FACTS`, so a runtime added to
 *      the fact table and the registry appears here without a line of
 *      this file changing. Every cell assertion below reads its expected
 *      value out of the same fact row the implementation reads, never out
 *      of a literal copied from it - a test that pins "cursor: 40" passes
 *      for a matrix that ignores the table entirely.
 *   2. A target whose fact row declares a host probe no longer prints the
 *      blanket "no MCP handshake attempted" note. Both probe branches -
 *      the binary answering and the binary being absent - are driven
 *      through a real plan+apply into a temp home, because a probe that
 *      reports `ok` when it could not run is the misleading default this
 *      whole release removes.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Writable } from "node:stream";

import { registerAllAdapters } from "../../../src/core/install/adapters/all.ts";
import {
  resetCodexRunner,
  setCodexRunner,
  type CodexRunner,
} from "../../../src/core/install/adapters/codex.ts";
import {
  resetCopilotRunner,
  setCopilotRunner,
  type CopilotRunner,
} from "../../../src/core/install/adapters/copilot-cli.ts";
import {
  buildFrictionMatrix,
  diffFrictionRows,
  FRICTION_DIMENSION,
  FRICTION_DIMENSIONS,
  frictionRowFor,
  type FrictionInput,
  type FrictionRow,
} from "../../../src/core/install/friction.ts";
import {
  hostProbeCommand,
  NO_HANDSHAKE_NOTE,
  resetHostProbeRunner,
  setHostProbeRunner,
  type HostProbeRunner,
} from "../../../src/core/install/host-probe.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../../../src/core/install/json-merge.ts";
import {
  carriesHostDimensions,
  payloadForHost,
  TOOL_PROFILE_FLAG,
} from "../../../src/core/install/payload-host.ts";
import { buildPayload } from "../../../src/core/install/payload.ts";
import {
  INSTALL_TARGET_IDS,
  RUNTIME_FACTS,
  TOOL_CEILING_KIND,
  type InstallTargetId,
} from "../../../src/core/runtime/host-facts.ts";
import type {
  ApplyOpts,
  InstallAdapter,
  InstallEnv,
  SessionPathsResult,
} from "../../../src/core/install/types.ts";

let vault: string;
let home: string;

/**
 * The apply below is REAL, and every mutation seam an adapter owns must be
 * injected before it runs. The rule, not the instance: the host probe is a
 * read-only seam this suite stages per case, but each subprocess-driven
 * adapter carries a SEPARATE seam for the commands that CHANGE the
 * machine, and any of those left on its default runner will spawn the
 * operator's real host binary against the operator's real registration.
 *
 * That is not hypothetical. `codex` was pinned here and `copilot` was not,
 * so on a machine with the Copilot CLI installed this file ran four rounds
 * of `copilot mcp remove` + `copilot mcp add` against the developer's own
 * registration, pointing it at a `/tmp/osb-friction-v-*` vault that
 * `afterEach` then deleted - and CI, where no `copilot` exists, reported
 * a clean pass.
 *
 * Pinning them absent also makes the suite deterministic: a runner that
 * exists on some developer machines and on no CI runner would exercise the
 * subprocess branch here and the file-fallback branch there and report
 * both as the same pass. Both branches have their own coverage in the
 * adapters' own suites; this one pins the fallback so the friction matrix
 * is the only variable.
 */
const ABSENT_CODEX: CodexRunner = {
  available: () => false,
  run: () => ({ exitCode: 1, stdout: "", stderr: "codex is not on PATH" }),
};

const ABSENT_COPILOT: CopilotRunner = {
  available: () => false,
  run: () => ({ exitCode: 1, stdout: "", stderr: "copilot is not on PATH" }),
  list: () => ({ ok: false, names: [] }),
};

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-friction-v-"));
  home = mkdtempSync(join(tmpdir(), "osb-friction-h-"));
  setCodexRunner(ABSENT_CODEX);
  setCopilotRunner(ABSENT_COPILOT);
});

afterEach(() => {
  resetHostProbeRunner();
  resetCodexRunner();
  resetCopilotRunner();
  for (const dir of [vault, home]) {
    try {
      rmSync(dir, { recursive: true, force: true });
    } catch {
      // temp cleanup is best-effort
    }
  }
});

function sink(): NodeJS.WriteStream {
  return new Writable({
    write(_chunk, _enc, cb) {
      cb();
    },
  }) as unknown as NodeJS.WriteStream;
}

function installEnv(): InstallEnv {
  return {
    vault,
    home,
    cwd: home,
    env: { VAULT_AGENT_NAME: "claude-vps", VAULT_TIMEZONE: "UTC" },
    now: new Date("2026-05-20T12:00:00.000Z"),
  };
}

function applyOpts(): ApplyOpts {
  return { dryRun: false, force: false, stdout: sink(), stderr: sink() };
}

function input(): FrictionInput {
  const env = installEnv();
  return {
    env,
    payload: buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" }),
    adapters: registerAllAdapters().list(),
  };
}

/** The one cell of `row` for `dimension`; the row is total over the set. */
function cell(row: FrictionRow, dimension: string) {
  const found = row.cells.find((c) => c.dimension === dimension);
  expect(`${row.target} answers ${dimension}: ${found !== undefined}`).toBe(
    `${row.target} answers ${dimension}: true`,
  );
  return found!;
}

describe("the friction matrix is derived, not written", () => {
  test("the row population is the fact table's, in both directions", () => {
    const rows = buildFrictionMatrix(input()).rows;
    expect(rows.map((r) => r.target).toSorted()).toEqual(
      Object.keys(RUNTIME_FACTS).toSorted() as InstallTargetId[],
    );
    // A matrix over an empty registry would satisfy the equality above if
    // the fact table were ever emptied too.
    expect(rows.length).toBeGreaterThan(5);
  });

  test("every row answers every dimension exactly once, in the declared order", () => {
    for (const row of buildFrictionMatrix(input()).rows) {
      expect(`${row.target}: ${row.cells.map((c) => c.dimension).join(",")}`).toBe(
        `${row.target}: ${FRICTION_DIMENSIONS.join(",")}`,
      );
      const empty = row.cells.filter((c) => c.value.trim().length === 0);
      expect(`${row.target} cells with no answer: ${empty.length}`).toBe(
        `${row.target} cells with no answer: 0`,
      );
    }
  });

  test("the ceiling cell carries the fact row's own number and its citation", () => {
    for (const row of buildFrictionMatrix(input()).rows) {
      const ceiling = RUNTIME_FACTS[row.target].toolCeiling;
      const answer = cell(row, FRICTION_DIMENSION.toolCeiling);
      expect(answer.value).toContain(ceiling.kind);
      if (ceiling.kind === TOOL_CEILING_KIND.declared) {
        expect(answer.value).toContain(String(ceiling.maxTools));
        expect(answer.detail).toBe(ceiling.source);
      } else if (ceiling.kind === TOOL_CEILING_KIND.unknown) {
        expect(answer.detail).toBe(ceiling.reason);
      }
    }
  });

  test("the verify-evidence cell names the declared probe, and the blanket note survives only without one", () => {
    for (const row of buildFrictionMatrix(input()).rows) {
      const probe = RUNTIME_FACTS[row.target].hostProbe;
      const answer = cell(row, FRICTION_DIMENSION.verifyEvidence);
      if (probe === null) {
        expect(`${row.target}: ${answer.detail}`).toBe(`${row.target}: ${NO_HANDSHAKE_NOTE}`);
      } else {
        expect(answer.value).toContain(hostProbeCommand(probe));
        expect(answer.detail).toBe(probe.answers);
      }
    }
  });

  test("the session cells report what the fact row declares, not what is on this machine", () => {
    for (const row of buildFrictionMatrix(input()).rows) {
      const facts = RUNTIME_FACTS[row.target];
      const roots = cell(row, FRICTION_DIMENSION.sessionTranscripts);
      // Declared for THIS platform: a root scoped to another platform (the
      // %APPDATA% Cursor layout) is not a declaration a POSIX host answers.
      const declared = facts.sessionRoots.filter(
        (root) => root.platforms === undefined || root.platforms.includes(process.platform),
      );
      if (declared.length === 0) {
        expect(roots.detail).toBeNull();
      } else {
        expect(roots.value).toContain(String(declared.length));
        for (const root of declared) {
          expect(roots.detail ?? "").toContain(root.resolve({ home, env: {} }));
        }
      }
      // The parser cell, on EVERY row. Guarding it behind
      // `sessionAdapter !== null` ran it for three of the ten and left
      // nothing pinning what the other seven say - the rows where the
      // answer is "none ships", which is the answer an operator reads to
      // decide whether importing this host's transcripts is possible at
      // all. The expected value is derived from the row's own roots, the
      // same input the cell is built from.
      const parser = cell(row, FRICTION_DIMENSION.sessionParser);
      const parsers = [
        ...new Set(facts.sessionRoots.map((root) => root.adapter).filter((a) => a !== null)),
      ].toSorted();
      expect(`${row.target}: ${parser.value}`).toBe(
        `${row.target}: ${parsers.length > 0 ? parsers.join(", ") : "none ships"}`,
      );
      if (parsers.length === 0) {
        // Roots in a format nothing reads are named, so "none ships" is a
        // measured answer rather than a shrug; no roots at all is silence.
        for (const format of new Set(facts.sessionRoots.map((root) => root.format))) {
          expect(`${row.target}: ${parser.detail ?? ""}`).toContain(format);
        }
        if (facts.sessionRoots.length === 0) expect(parser.detail).toBeNull();
      }
    }
  });

  test("the mechanism cell is the live adapter's own plan", () => {
    const shared = input();
    for (const adapter of shared.adapters) {
      const kinds = new Set(adapter.plan(shared.payload, shared.env).steps.map((s) => s.kind));
      const answer = cell(frictionRowFor(adapter.target, shared), FRICTION_DIMENSION.mechanism);
      expect(`${adapter.target}: ${answer.value}`).toBe(
        `${adapter.target}: ${[...kinds].toSorted().join(", ")}`,
      );
    }
  });

  test("an unknown target is refused by name, with the known list", () => {
    let message = "";
    try {
      frictionRowFor("claude-code" as InstallTargetId, input());
    } catch (e) {
      message = (e as Error).message;
    }
    expect(message).toContain("claude-code");
    for (const known of INSTALL_TARGET_IDS) expect(message).toContain(known);
  });
});

describe("a diff names the dimensions that differ and stays silent about the rest", () => {
  test("the differing set is exactly the set of unequal cells, over every pair", () => {
    const rows = buildFrictionMatrix(input()).rows;
    const wrong: string[] = [];
    for (const base of rows) {
      for (const compare of rows) {
        const named = new Set(diffFrictionRows(base, compare).differing.map((d) => d.dimension));
        for (const dimension of FRICTION_DIMENSIONS) {
          const differs = cell(base, dimension).value !== cell(compare, dimension).value;
          if (differs !== named.has(dimension)) {
            wrong.push(`${base.target} vs ${compare.target}: ${dimension}`);
          }
        }
      }
    }
    expect(wrong.join("\n")).toBe("");
  });

  test("a row against itself names nothing, and two unlike hosts name something", () => {
    const rows = buildFrictionMatrix(input()).rows;
    const cursor = rows.find((r) => r.target === "cursor")!;
    const pi = rows.find((r) => r.target === "pi")!;
    expect(diffFrictionRows(cursor, cursor).differing).toEqual([]);
    expect(diffFrictionRows(cursor, cursor).shared).toBe(FRICTION_DIMENSIONS.length);
    expect(diffFrictionRows(cursor, pi).differing.length).toBeGreaterThan(0);
    expect(
      diffFrictionRows(cursor, pi).differing.length + diffFrictionRows(cursor, pi).shared,
    ).toBe(FRICTION_DIMENSIONS.length);
  });
});

// ---------- The probe, on both branches ----------

/** Every target whose fact row declares a host probe. Derived. */
const PROBE_BEARING: ReadonlyArray<InstallTargetId> = INSTALL_TARGET_IDS.filter(
  (target) => RUNTIME_FACTS[target].hostProbe !== null,
);

/** A runner whose binary is present and prints `registered`, one per line. */
function answeringRunner(registered: ReadonlyArray<string>): HostProbeRunner {
  return {
    available: () => true,
    run: () => ({ exitCode: 0, stdout: registered.join("\n") + "\n", stderr: "" }),
  };
}

/** Install `target` for real, then verify it, and return the printed details. */
function detailsAfterInstall(target: InstallTargetId): {
  readonly status: string;
  readonly details: string;
} {
  const adapter = registerAllAdapters().get(target)!;
  const env = installEnv();
  const payload = buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" });
  adapter.apply(adapter.plan(payload, env), payload, env, applyOpts());
  const result = adapter.verify(env);
  return { status: result.status, details: result.details.join("; ") };
}

describe("a target that declares a host probe stops claiming a handshake it never attempts", () => {
  test("the probe-bearing population is not empty", () => {
    // Every case below iterates it; an empty list would pass them all.
    expect(PROBE_BEARING.length).toBeGreaterThan(0);
  });

  test("the binary answers: verify names the probe and never the blanket note", () => {
    for (const target of PROBE_BEARING) {
      setHostProbeRunner(answeringRunner([OSB_KEY_FULL, OSB_KEY_WRITER]));
      const { status, details } = detailsAfterInstall(target);
      expect(`${target}: ${status}`).toBe(`${target}: ok`);
      expect(details).toContain(hostProbeCommand(RUNTIME_FACTS[target].hostProbe!));
      expect(details).not.toContain(NO_HANDSHAKE_NOTE);
    }
  });

  test("the binary is absent: verify names the skip reason and never the blanket note", () => {
    for (const target of PROBE_BEARING) {
      const bin = RUNTIME_FACTS[target].hostProbe!.bin;
      setHostProbeRunner({
        available: () => false,
        run: () => {
          throw new Error(`the runner must not spawn ${bin} when it is not on PATH`);
        },
      });
      const { details } = detailsAfterInstall(target);
      expect(details).toContain(bin);
      expect(details).toContain("not on PATH");
      expect(details).not.toContain(NO_HANDSHAKE_NOTE);
    }
  });

  test("the binary refuses: the non-zero exit is named, not swallowed", () => {
    for (const target of PROBE_BEARING) {
      setHostProbeRunner({
        available: () => true,
        run: () => ({ exitCode: 3, stdout: "", stderr: "not authenticated\n" }),
      });
      const { details } = detailsAfterInstall(target);
      expect(details).toContain("3");
      expect(details).toContain("not authenticated");
      expect(details).not.toContain(NO_HANDSHAKE_NOTE);
    }
  });

  test("the binary answers but the host has nothing registered: that is not ok", () => {
    // Every mutation runner is pinned absent above, so each of these
    // installs landed in its adapter's FILE fallback and that file was
    // just compared and found correct. The shared rule
    // (`probeRefutedVerdict`) reads a refuting probe over a matching
    // artifact as a host that has not reloaded it, so the verdict is
    // `mcp-unreachable` and the repair is a restart - never `drift`,
    // which would tell the operator to rewrite bytes that are already
    // right. The host-is-the-only-record half of that rule is driven in
    // `tests/core/install/adapters/copilot-cli.test.ts`, where the
    // subprocess branch has an artifact-free registration to refute.
    for (const target of PROBE_BEARING) {
      setHostProbeRunner(answeringRunner([]));
      const { status, details } = detailsAfterInstall(target);
      expect(`${target}: ${status}`).toBe(`${target}: mcp-unreachable`);
      expect(details).toContain(OSB_KEY_FULL);
    }
  });

  test("a target with no probe keeps the blanket note, because it is the true answer", () => {
    setHostProbeRunner(answeringRunner([OSB_KEY_FULL, OSB_KEY_WRITER]));
    const { details } = detailsAfterInstall("cursor");
    expect(details).toContain(NO_HANDSHAKE_NOTE);
  });
});

// ---------- The cells that must describe the real artifact ----------

describe("the tool-profile cell describes the registration this target writes", () => {
  /** Targets whose generated registration carries no MCP command line. */
  const NOT_CARRIED: ReadonlyArray<InstallTargetId> = INSTALL_TARGET_IDS.filter(
    (target) => !carriesHostDimensions(target),
  );

  test("the population is not empty, and it is the declared one", () => {
    // Derived from the declaration the write path uses, so a target that
    // starts routing through `payloadForHost` moves between the two cases
    // below rather than escaping both.
    expect(NOT_CARRIED.toSorted()).toEqual(["aider", "generic", "pi"]);
  });

  test("a target that writes no command line says so instead of naming a profile", () => {
    // It used to resolve the ladder anyway and print, for example,
    // `generic tool-profile minimal / resolved from user-config` beside a
    // `--target generic --apply` whose args carry no `--tool-profile` at
    // all - a cell contradicting the artifact it claims to describe.
    for (const target of NOT_CARRIED) {
      const answer = cell(frictionRowFor(target, input()), FRICTION_DIMENSION.toolProfile);
      expect(`${target}: ${answer.value}`).toBe(`${target}: not carried`);
      expect(answer.detail ?? "").toContain("no MCP command line");
    }
  });

  test("a target that does write one names the profile its payload carries", () => {
    const shared = input();
    for (const target of INSTALL_TARGET_IDS.filter(carriesHostDimensions)) {
      const answer = cell(frictionRowFor(target, shared), FRICTION_DIMENSION.toolProfile);
      const written = payloadForHost(target, shared.payload, shared.env);
      const index = written.full.args.indexOf(TOOL_PROFILE_FLAG);
      const carried = index === -1 ? "none" : written.full.args[index + 1];
      expect(`${target}: ${answer.value}`).toBe(`${target}: ${carried}`);
    }
  });
});

describe("the session cells ask the adapter, not the fact table", () => {
  /** An adapter that answers a DIFFERENT session store than its row. */
  function withSessionPaths(
    adapter: InstallAdapter,
    answer: SessionPathsResult | null,
  ): InstallAdapter {
    return { ...adapter, sessionPaths: () => answer };
  }

  test("an adapter that answers null is reported as declaring nothing", () => {
    // `codex` declares four roots in `RUNTIME_FACTS`. A matrix reading the
    // table directly would print them however the adapter answered, which
    // is what made `InstallAdapter.sessionPaths` a required member with
    // ten implementations and no caller anywhere in `src/`.
    const shared = input();
    const codex = shared.adapters.find((a) => a.target === "codex")!;
    const silent = withSessionPaths(codex, null);
    const row = frictionRowFor("codex", { ...shared, adapters: [silent] });
    expect(cell(row, FRICTION_DIMENSION.sessionTranscripts).value).toBe("none declared");
    expect(cell(row, FRICTION_DIMENSION.sessionParser).value).toBe("none ships");
  });

  test("the roots printed are the ones the adapter resolved", () => {
    const shared = input();
    for (const adapter of shared.adapters) {
      const answered = adapter.sessionPaths(shared.env);
      const roots = cell(
        frictionRowFor(adapter.target, shared),
        FRICTION_DIMENSION.sessionTranscripts,
      );
      if (answered === null) {
        expect(`${adapter.target}: ${roots.value}`).toBe(`${adapter.target}: none declared`);
        continue;
      }
      for (const root of answered.roots) expect(roots.detail ?? "").toContain(root.path);
    }
  });
});

describe("an unreadable _brain.yaml is reported, not thrown", () => {
  beforeEach(() => {
    mkdirSync(join(vault, "Brain"), { recursive: true });
    writeFileSync(
      join(vault, "Brain", "_brain.yaml"),
      "schema_version: 1\ninstall:\n  tool_profile: [broken\n",
    );
  });

  test("the matrix still answers every row, and names the refusal in the cells", () => {
    // `--friction` is documented as a report that never exits non-zero.
    // Once `plan()` began resolving the tool profile, a vault whose config
    // will not parse turned it into an uncaught `BrainConfigError` stack
    // trace - `runFriction` catches only usage and payload errors.
    const rows = buildFrictionMatrix(input()).rows;
    expect(rows.length).toBe(INSTALL_TARGET_IDS.length);
    const unresolved = rows.filter((row) => row.cells.some((c) => c.value === "unresolved"));
    expect(unresolved.length).toBeGreaterThan(0);
    for (const row of unresolved) {
      const named = row.cells.filter((c) => c.value === "unresolved");
      for (const c of named) expect(c.detail ?? "").toContain("_brain.yaml");
    }
  });

  test("the refusal is stated, never replaced by a default profile", () => {
    const row = frictionRowFor("cursor", input());
    const profile = cell(row, FRICTION_DIMENSION.toolProfile);
    expect(profile.value).toBe("unresolved");
    expect(profile.value).not.toBe("catalog");
  });
});