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
8.8 KB
Raw Blame
/**
 * The host probe: what it parses, which machine it asks, and what it does
 * when the host does not answer.
 *
 * Three properties, each of which was previously either untested or tested
 * only against strings the tests themselves authored:
 *
 *   1. The parser is driven by a REAL capture. Every case for
 *      `registeredNames` used to invent its own `mcp list` output, so the
 *      parser was only ever held against the format the test author
 *      believed in. Real `codex mcp list` prints a padded table WITH a
 *      header row, which no authored fixture had.
 *   2. The probe asks the host named by the `InstallEnv`, not the ambient
 *      one. `codex.ts` declares "the Codex home is injected, never
 *      ambient" for its mutation runner; the probe seam took no
 *      environment at all, so `verify` on a relocated `CODEX_HOME`
 *      described one machine in its file half and another in its
 *      handshake half.
 *   3. The wait is bounded. An unauthenticated host that blocks on a
 *      network call or a prompt used to hang `o2b install --check` with no
 *      message and no way out.
 */

import { describe, expect, test, afterEach } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";

import {
  createHostProbeRunner,
  hostProbeEnvironment,
  HOST_PROBE_RESULT,
  HOST_PROBE_TIMEOUT_MS,
  probeHost,
  resetHostProbeRunner,
  setHostProbeRunner,
  type HostProbeEnvironment,
  type HostProbeRunResult,
} from "../../../src/core/install/host-probe.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../../../src/core/install/json-merge.ts";
import type { InstallEnv } from "../../../src/core/install/types.ts";

const REPO_ROOT = join(import.meta.dir, "..", "..", "..");

/** The capture committed at `tests/fixtures/install/codex-mcp-list.txt`. */
function realCodexListing(): string {
  return readFileSync(
    join(REPO_ROOT, "tests", "fixtures", "install", "codex-mcp-list.txt"),
    "utf8",
  );
}

function envFor(extra: Readonly<Record<string, string>> = {}): InstallEnv {
  return {
    vault: "/srv/vaults/example",
    home: "/home/operator",
    cwd: "/srv/projects/example",
    env: { PATH: "/usr/bin", ...extra },
    now: new Date("2026-08-16T09:00:00.000Z"),
  };
}

afterEach(() => {
  resetHostProbeRunner();
});

describe("the parser is held against real host output", () => {
  test("the committed capture is the real shape: a padded table with a header", () => {
    // A fixture that had been reduced to one bare name would make every
    // assertion below pass for a parser that cannot read a table at all.
    const lines = realCodexListing().trimEnd().split("\n");
    expect(lines.length).toBe(2);
    expect(lines[0]!.split(/\s+/)[0]).toBe("Name");
    expect(lines[0]).toContain("Status");
    expect(lines[1]).toContain("enabled");
  });

  test("it reports the one OSB server this machine had registered", () => {
    setHostProbeRunner({
      available: () => true,
      run: () => ({ exitCode: 0, stdout: realCodexListing(), stderr: "" }),
    });
    const outcome = probeHost("codex", envFor());
    expect(outcome.kind).toBe(HOST_PROBE_RESULT.answered);
    if (outcome.kind !== HOST_PROBE_RESULT.answered) throw new Error("unreachable");
    expect(outcome.registered).toEqual([OSB_KEY_FULL]);
    expect(outcome.missing).toEqual([OSB_KEY_WRITER]);
  });

  test("the header row cannot become a registered server", () => {
    // `registeredNames` deliberately does NOT skip the header: recognising
    // each host's header would be a per-host grammar to keep up with. It
    // is safe by construction instead - the answer is an intersection with
    // two fixed names, and no host prints a column called
    // `open-second-brain`. This is the assertion that says so out loud.
    setHostProbeRunner({
      available: () => true,
      run: () => ({ exitCode: 0, stdout: realCodexListing(), stderr: "" }),
    });
    const outcome = probeHost("codex", envFor());
    if (outcome.kind !== HOST_PROBE_RESULT.answered) throw new Error("unreachable");
    for (const name of [...outcome.registered, ...outcome.missing]) {
      expect([OSB_KEY_FULL, OSB_KEY_WRITER]).toContain(name);
    }
  });

  test("a host with both registered under the same table shape answers clean", () => {
    const both =
      realCodexListing().trimEnd() +
      "\nopen-second-brain-writer  o2b  mcp  -  -  enabled  Unsupported\n";
    setHostProbeRunner({
      available: () => true,
      run: () => ({ exitCode: 0, stdout: both, stderr: "" }),
    });
    const outcome = probeHost("codex", envFor());
    if (outcome.kind !== HOST_PROBE_RESULT.answered) throw new Error("unreachable");
    expect(outcome.missing).toEqual([]);
  });
});

describe("the probe asks the host being verified", () => {
  /** A runner that records the environment it was handed. */
  function recordingRunner(seen: { env: HostProbeEnvironment | null; bin: string | null }) {
    return {
      available(bin: string, env: HostProbeEnvironment): boolean {
        seen.bin = bin;
        seen.env = env;
        return true;
      },
      run(
        _bin: string,
        _argv: ReadonlyArray<string>,
        env: HostProbeEnvironment,
      ): HostProbeRunResult {
        seen.env = env;
        return { exitCode: 0, stdout: "", stderr: "" };
      },
    };
  }

  test("HOME is the injected home, not the ambient one", () => {
    const seen: { env: HostProbeEnvironment | null; bin: string | null } = { env: null, bin: null };
    setHostProbeRunner(recordingRunner(seen));
    probeHost("codex", envFor());
    expect(seen.bin).toBe("codex");
    expect(seen.env?.["HOME"]).toBe("/home/operator");
  });

  test("a relocated CODEX_HOME reaches the subprocess", () => {
    // The measured defect: applying codex into an isolated `CODEX_HOME`
    // and calling `verify` ran `codex mcp list` with `CODEX_HOME` unset,
    // so the handshake described the operator's real `~/.codex` while the
    // file comparison described the temporary one.
    const seen: { env: HostProbeEnvironment | null; bin: string | null } = { env: null, bin: null };
    setHostProbeRunner(recordingRunner(seen));
    probeHost("codex", envFor({ CODEX_HOME: "/mnt/elsewhere/codex" }));
    expect(seen.env?.["CODEX_HOME"]).toBe("/mnt/elsewhere/codex");
  });

  test("the environment is derived from the InstallEnv alone", () => {
    const env = envFor({ XDG_CONFIG_HOME: "/mnt/cfg" });
    expect(hostProbeEnvironment(env)).toEqual({
      PATH: "/usr/bin",
      XDG_CONFIG_HOME: "/mnt/cfg",
      HOME: "/home/operator",
    });
  });
});

describe("the wait is bounded", () => {
  test("the shipped cap is a positive number of milliseconds", () => {
    expect(Number.isSafeInteger(HOST_PROBE_TIMEOUT_MS)).toBe(true);
    expect(HOST_PROBE_TIMEOUT_MS).toBeGreaterThan(0);
  });

  test("a host that never answers is killed and reported, not waited on", () => {
    // Driven against a process that just waits, which stands in for the
    // real obstacle: a host CLI blocking on a network call or an
    // interactive authentication prompt. Without the cap this call never
    // returns. The running Bun is the stand-in rather than `sleep`, which
    // native Windows does not ship.
    const runner = createHostProbeRunner(200);
    const started = Date.now();
    const result = runner.run(process.execPath, ["-e", "setTimeout(() => {}, 30000)"], {
      PATH: process.env["PATH"] ?? "/usr/bin",
    });
    const elapsed = Date.now() - started;
    expect(elapsed).toBeLessThan(10_000);
    expect(result.exitCode).not.toBe(0);
    expect(result.stdout).toBe("");
    expect(result.stderr).toContain("200 ms");
  });

  test("a host that answers in time keeps its answer", () => {
    // The regression this pins: Bun leaves `signalCode` undefined, not
    // null, on a normal exit, and a strict `!== null` check read every
    // successful probe as killed and discarded its stdout. Driven against a
    // real child because a stubbed runner cannot reproduce a runtime quirk.
    const runner = createHostProbeRunner(HOST_PROBE_TIMEOUT_MS);
    const result = runner.run(
      process.execPath,
      ["-e", `process.stdout.write(${JSON.stringify(realCodexListing())})`],
      { PATH: process.env["PATH"] ?? "/usr/bin" },
    );
    expect(result.stderr).toBe("");
    expect(result.exitCode).toBe(0);
    expect(result.stdout).toBe(realCodexListing());
  });

  test("a killed probe becomes a named skip, never an assumed answer", () => {
    setHostProbeRunner({
      available: () => true,
      run: () => ({
        exitCode: 1,
        stdout: "",
        stderr: `killed by SIGTERM; the probe is capped at ${HOST_PROBE_TIMEOUT_MS} ms`,
      }),
    });
    const outcome = probeHost("codex", envFor());
    expect(outcome.kind).toBe(HOST_PROBE_RESULT.probeFailed);
    if (outcome.kind !== HOST_PROBE_RESULT.probeFailed) throw new Error("unreachable");
    expect(outcome.reason).toContain("SIGTERM");
  });
});