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
15.5 KB
Raw Blame
/**
 * Asking a host what it has actually registered.
 *
 * Every JSON-config adapter's `verify()` ended on one sentence -
 * {@link NO_HANDSHAKE_NOTE} - because a config comparison is all it did.
 * That sentence is honest where nothing better is available and a lie of
 * omission where something is: {@link RUNTIME_FACTS} declares a
 * `hostProbe` for the runtimes that can be ASKED, and a target that
 * carries one has no business printing "no handshake attempted" when the
 * handshake is one keyless subprocess away.
 *
 * Three rules this module is written under:
 *
 *   - **Keyless and free.** The probe asks the host which servers it has
 *     registered. It starts no model turn, needs no API key, and writes
 *     nothing. `RUNTIME_FACTS[t].hostProbe.answers` states, per row, what
 *     a successful run establishes.
 *   - **A skip is named.** The absence of an answer is a member of
 *     {@link HOST_PROBE_RESULT} carrying the reason - the binary is not on
 *     PATH, or it exited non-zero with this stderr - never an assumed
 *     `ok`. A probe that reports success when it could not run is the
 *     misleading default this module exists to remove.
 *   - **The subprocess is injectable.** {@link setHostProbeRunner} is the
 *     seam, exactly as `CopilotRunner` already is for that adapter's
 *     mutation commands, so both branches are drivable in a test on a
 *     machine where the host binary does not exist.
 *   - **The host asked is the host being verified.** The probe takes the
 *     adapter's own {@link InstallEnv} and spawns under
 *     {@link hostProbeEnvironment}, never under the ambient process
 *     environment. `codex.ts` declares "the Codex home is injected, never
 *     ambient" for its mutation runner; a probe that ignored the same
 *     injection would let a relocated `CODEX_HOME` verify `ok` against the
 *     operator's real `~/.codex`, which is a wrong answer wearing a live
 *     host's authority.
 *
 * ## Two verdicts for one probe answer
 *
 * "The host answered and does not list our servers" is not one condition,
 * and {@link probeRefutedVerdict} is the one place that splits it:
 *
 *   - the registration is backed by an ARTIFACT this build wrote and that
 *     artifact still matches the canonical payload. The configuration is
 *     right and the host has not loaded it, so the verdict is
 *     `mcp-unreachable` and the repair is a restart. Re-applying would
 *     rewrite bytes that are already correct and change nothing.
 *   - the host's own registry IS the record - `copilot mcp add` leaves no
 *     file, and a Codex config that does not declare the tables has no
 *     artifact to be right - so the host saying "no" means the
 *     registration is gone. The verdict is `drift` and the repair is
 *     `--apply`.
 *
 * Stated here rather than in each adapter because the three probe-bearing
 * bodies reached the same two verdicts by three separate arguments, and a
 * rule argued three times is a rule that will be argued differently once.
 *
 * LEAF module: `RUNTIME_FACTS`, the install types and the two server-key
 * constants, and nothing from `./adapters/`.
 * `src/core/install/adapters/_json-mcp.ts` and `copilot-cli.ts` read it;
 * importing either back into here would close a cycle
 * `tests/core/architecture/import-cycles.test.ts` gates.
 */

import { RUNTIME_FACTS, type HostProbeSpec, type InstallTargetId } from "../runtime/host-facts.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "./json-merge.ts";
import type { InstallEnv, VerifyStatus } from "./types.ts";

/**
 * Stated on every clean `verify` of a target that declares no probe, so
 * an `ok` cannot be read as "the runtime answered". One constant, because
 * the sentence is a property of the whole install surface and every
 * target that cannot be asked must say it the same way.
 */
export const NO_HANDSHAKE_NOTE = "configuration comparison; no MCP handshake attempted";

/** The two server names an Open Second Brain install registers. */
const OSB_SERVER_KEYS: ReadonlyArray<string> = Object.freeze([OSB_KEY_FULL, OSB_KEY_WRITER]);

/**
 * What came back when this build asked a host about its registrations.
 *
 * `not-declared` is a member rather than an absent value: "this runtime
 * publishes no way to ask it" is an answer, and it is the one that earns
 * {@link NO_HANDSHAKE_NOTE}. No guard ships with it - unlike the target
 * ids, these values never arrive from argv or a config file, so there is
 * no raw boundary for a guard to stand on.
 */
export const HOST_PROBE_RESULT = Object.freeze({
  answered: "answered",
  binaryMissing: "binary-missing",
  probeFailed: "probe-failed",
  notDeclared: "not-declared",
} as const);

export type HostProbeResult = (typeof HOST_PROBE_RESULT)[keyof typeof HOST_PROBE_RESULT];

/** The host ran the probe and named its registrations. */
export interface AnsweredProbe {
  readonly kind: typeof HOST_PROBE_RESULT.answered;
  /** `bin` plus `argv`, the way a reader would re-run it. */
  readonly command: string;
  /** OSB server names the host reported. */
  readonly registered: ReadonlyArray<string>;
  /** OSB server names it did not report. Empty is the clean answer. */
  readonly missing: ReadonlyArray<string>;
}

/** The probe could not run, and this is why. */
export interface SkippedProbe {
  readonly kind: typeof HOST_PROBE_RESULT.binaryMissing | typeof HOST_PROBE_RESULT.probeFailed;
  readonly command: string;
  /** A sentence naming the obstacle; never empty. */
  readonly reason: string;
}

/** The runtime publishes nothing to ask. */
export interface UndeclaredProbe {
  readonly kind: typeof HOST_PROBE_RESULT.notDeclared;
}

export type HostProbeOutcome = AnsweredProbe | SkippedProbe | UndeclaredProbe;

/** One probe run, as the seam reports it. */
export interface HostProbeRunResult {
  readonly exitCode: number;
  readonly stdout: string;
  readonly stderr: string;
}

/**
 * The machine the probe is asked ABOUT, as a child process environment.
 *
 * `InstallEnv.env` is the environment the adapter writes its artifacts
 * against, and `InstallEnv.home` is the home those artifacts are resolved
 * under - which is not necessarily the ambient `HOME`, because every
 * install surface accepts an injected one. `HOME` is set from it so a host
 * that derives its own configuration directory (`~/.codex`,
 * `~/.config/github-copilot`) derives the SAME one the adapter just wrote,
 * and an explicit `CODEX_HOME` / `XDG_CONFIG_HOME` already in `env.env`
 * rides through untouched.
 */
export type HostProbeEnvironment = Readonly<Record<string, string>>;

export function hostProbeEnvironment(env: InstallEnv): HostProbeEnvironment {
  return { ...env.env, HOME: env.home };
}

/**
 * How long a probe may take before it is a failed probe.
 *
 * `o2b install --check` is a synchronous command an operator runs to find
 * out whether their machine is wired up. A host CLI that blocks on a
 * network call or an interactive authentication prompt would hang it with
 * no way out and no message, which is worse than the named skip a refusal
 * produces - so the wait is bounded and the timeout becomes one more named
 * reason. Generous enough that a cold process start on a loaded machine
 * is not reported as a broken host.
 */
export const HOST_PROBE_TIMEOUT_MS = 10_000;

/**
 * The subprocess seam. `available` answers whether the binary resolves on
 * PATH at all, which is a different failure from a binary that ran and
 * refused - the two produce different named skips, so they cannot share a
 * branch. Both take the {@link HostProbeEnvironment} because both questions
 * are about the injected machine: the PATH that resolves the binary is the
 * one that machine has.
 */
export interface HostProbeRunner {
  available(bin: string, env: HostProbeEnvironment): boolean;
  run(bin: string, argv: ReadonlyArray<string>, env: HostProbeEnvironment): HostProbeRunResult;
}

/**
 * The real subprocess runner, with its wait bounded by `timeoutMs`.
 *
 * A factory rather than a constant so the timeout branch is drivable
 * against a harmless slow binary in a fraction of a second, instead of
 * being the one path in this module that ships untested because exercising
 * it would mean waiting {@link HOST_PROBE_TIMEOUT_MS} for it.
 */
export function createHostProbeRunner(timeoutMs: number): HostProbeRunner {
  return {
    available(bin: string, env: HostProbeEnvironment): boolean {
      try {
        const path = env["PATH"];
        return (path === undefined ? Bun.which(bin) : Bun.which(bin, { PATH: path })) !== null;
      } catch {
        return false;
      }
    },
    run(bin: string, argv: ReadonlyArray<string>, env: HostProbeEnvironment): HostProbeRunResult {
      try {
        const r = Bun.spawnSync({
          cmd: [bin, ...argv],
          env: { ...env },
          stdout: "pipe",
          stderr: "pipe",
          timeout: timeoutMs,
        });
        // `!= null`, not `!== null`: Bun leaves `signalCode` UNDEFINED on a
        // normal exit, so the strict form read every successful probe as a
        // kill and threw its stdout away - `o2b install --check` then called
        // a correctly registered Codex `mcp-unreachable`.
        if (r.signalCode != null) {
          // A killed child has no answer to report, and its partial stdout
          // must not be parsed as one. The signal is named because the
          // timeout kill and a host that crashed arrive the same way, and
          // guessing between them would be inventing the reason.
          return {
            exitCode: r.exitCode ?? 1,
            stdout: "",
            stderr: `killed by ${r.signalCode}; the probe is capped at ${timeoutMs} ms`,
          };
        }
        return {
          exitCode: r.exitCode ?? 1,
          stdout: r.stdout?.toString() ?? "",
          stderr: r.stderr?.toString() ?? "",
        };
      } catch (e) {
        // The shell's own "command not found" code, so the reason a reader
        // sees is the reason the shell would have printed.
        return { exitCode: 127, stdout: "", stderr: (e as Error).message };
      }
    },
  };
}

const defaultRunner: HostProbeRunner = createHostProbeRunner(HOST_PROBE_TIMEOUT_MS);

let activeRunner: HostProbeRunner = defaultRunner;

export function setHostProbeRunner(runner: HostProbeRunner): void {
  activeRunner = runner;
}

export function resetHostProbeRunner(): void {
  activeRunner = defaultRunner;
}

/** The probe as a reader would re-run it. */
export function hostProbeCommand(spec: HostProbeSpec): string {
  return [spec.bin, ...spec.argv].join(" ");
}

/**
 * The OSB server names `stdout` reports.
 *
 * The first whitespace-delimited token of each line is the name column of
 * every `mcp list` output this build has seen; anything else on the line
 * (a state, a transport, a command) is not compared. Only the two names
 * this tool registers are returned, so a host with fifty other servers
 * answers the same question as a host with none.
 *
 * The HEADER row of a padded table (`Name  Command  Args …`, which is what
 * real `codex mcp list` prints - see
 * `tests/fixtures/install/codex-mcp-list.txt`) therefore contributes the
 * token `Name`, and that is left in rather than stripped. Stripping it
 * would mean recognising each host's header, which is a per-host grammar
 * this build would then have to keep up with; leaving it in is safe by
 * CONSTRUCTION rather than by luck, because the return value is an
 * intersection with two fixed names and no host can print a column header
 * called `open-second-brain`. `tests/core/install/host-probe.test.ts`
 * drives the real capture and holds that property.
 */
function registeredNames(stdout: string): ReadonlyArray<string> {
  const tokens = new Set(
    stdout
      .split("\n")
      .map((line) => line.trim().split(/\s+/)[0] ?? "")
      .filter((token) => token.length > 0),
  );
  return OSB_SERVER_KEYS.filter((key) => tokens.has(key));
}

/** The first non-empty line of `text`, trimmed; `""` when there is none. */
function firstLine(text: string): string {
  return (
    text
      .split("\n")
      .find((line) => line.trim().length > 0)
      ?.trim() ?? ""
  );
}

/**
 * Ask `target`'s host what it has registered.
 *
 * Total: a target with no declared probe gets {@link UndeclaredProbe}
 * rather than a thrown error, because "nothing to ask" is the answer the
 * majority of rows legitimately have.
 */
export function probeHost(target: InstallTargetId, env: InstallEnv): HostProbeOutcome {
  const spec = RUNTIME_FACTS[target].hostProbe;
  if (spec === null) return { kind: HOST_PROBE_RESULT.notDeclared };
  const command = hostProbeCommand(spec);
  const probeEnv = hostProbeEnvironment(env);
  if (!activeRunner.available(spec.bin, probeEnv)) {
    return {
      kind: HOST_PROBE_RESULT.binaryMissing,
      command,
      reason: `\`${spec.bin}\` is not on PATH`,
    };
  }
  const run = activeRunner.run(spec.bin, spec.argv, probeEnv);
  if (run.exitCode !== 0) {
    const stderr = firstLine(run.stderr);
    return {
      kind: HOST_PROBE_RESULT.probeFailed,
      command,
      reason:
        `\`${command}\` exited ${run.exitCode}` +
        (stderr.length > 0 ? `: ${stderr}` : " with no output"),
    };
  }
  const registered = registeredNames(run.stdout);
  return {
    kind: HOST_PROBE_RESULT.answered,
    command,
    registered,
    missing: OSB_SERVER_KEYS.filter((key) => !registered.includes(key)),
  };
}

/**
 * The clause a `verify` detail carries about host confirmation.
 *
 * One function so the JSON-config adapter body and the Copilot adapter
 * cannot word the same four outcomes differently - the drift that let one
 * of them print a blanket claim while the other asked a real question.
 */
export function handshakeNote(outcome: HostProbeOutcome): string {
  switch (outcome.kind) {
    case HOST_PROBE_RESULT.answered:
      return outcome.missing.length === 0
        ? `\`${outcome.command}\` reports both OSB servers registered`
        : `\`${outcome.command}\` does not report: ${outcome.missing.join(", ")}`;
    case HOST_PROBE_RESULT.binaryMissing:
    case HOST_PROBE_RESULT.probeFailed:
      return `host probe skipped: ${outcome.reason}`;
    case HOST_PROBE_RESULT.notDeclared:
      return NO_HANDSHAKE_NOTE;
  }
}

/**
 * Whether the host CONTRADICTED a configuration that otherwise verified.
 *
 * True only for an answer: a probe that could not run refutes nothing,
 * and demoting a correct install because a binary was absent would be the
 * same over-claim as the blanket `ok`, pointed the other way.
 */
export function probeRefutes(outcome: HostProbeOutcome): boolean {
  return outcome.kind === HOST_PROBE_RESULT.answered && outcome.missing.length > 0;
}

/** The verdict a refuting probe earns, and the repair that matches it. */
export interface ProbeRefutedVerdict {
  readonly status: VerifyStatus;
  readonly fixHint: string;
}

/**
 * What a refuting probe MEANS, decided once for every probe-bearing
 * adapter. See "Two verdicts for one probe answer" at the top of this
 * module for why the same answer earns two different verdicts.
 *
 * `artifactMatches` is the caller's own comparison: true when this build
 * wrote a registration artifact and that artifact still equals the
 * canonical payload, false when the host's registry is the only record or
 * when the artifact does not carry the registration at all.
 */
export function probeRefutedVerdict(args: {
  readonly target: InstallTargetId;
  readonly label: string;
  readonly artifactMatches: boolean;
}): ProbeRefutedVerdict {
  if (args.artifactMatches) {
    return {
      status: "mcp-unreachable",
      fixHint: `restart ${args.label} so it reloads its MCP configuration`,
    };
  }
  return { status: "drift", fixHint: `o2b install --target ${args.target} --apply` };
}