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
5.5 KB
Raw Blame
/**
 * Canonical MCP server payload builder.
 *
 * Pure function: given the plugin config (vault + identity), return the
 * two `McpServerEntry` objects that every adapter writes verbatim.
 * Same input → byte-identical output; this is what lets `--apply`
 * be idempotent and `verify` detect drift via re-construction rather
 * than a stored hash.
 */

import type { McpPayload, McpServerEntry } from "./types.ts";

export class PayloadError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "PayloadError";
  }
}

export interface PayloadConfig {
  readonly vault: string;
  readonly agent_name: string | null;
  readonly timezone: string | null;
}

const COMMAND = "o2b";

/**
 * `command` + leading args that start the `o2b` launcher on `platform`.
 *
 * POSIX: `o2b` straight off PATH (the `install-cli` symlink). Native
 * Windows: `cmd /d /c o2b` - the launcher there is `o2b.cmd`, and a batch
 * file is not something every host can spawn directly (Node refuses `.cmd`
 * without a shell since the 2024 BatBadBut fix; Rust and Bun resolve only
 * `.exe` from a bare name). `cmd /c <name>` is the form several MCP hosts'
 * Windows docs give for `npx`, and it resolves `o2b.cmd` through PATH and
 * PATHEXT. `/d` skips cmd's AutoRun, whose output would corrupt the
 * JSON-RPC stream on stdout.
 *
 * cmd.exe looks for a bare name in the current directory BEFORE PATH, and
 * an MCP host starts its servers in the project it opened - so a repository
 * that ships an `o2b.cmd` would run it. The Windows payload therefore
 * carries {@link WINDOWS_LAUNCHER_ENV}, which turns that lookup off for
 * this cmd.exe and everything it starts (the launcher's own `bun` lookup
 * included). An absolute launcher path was the alternative, but cmd's
 * quote stripping (`cmd /c "<path with a space>" ... "<vault>"`) breaks it
 * for any profile or vault path with a space in it.
 */
export function launcherCommand(platform: string = process.platform): {
  readonly command: string;
  readonly prefix: ReadonlyArray<string>;
} {
  if (platform === "win32") return { command: "cmd", prefix: ["/d", "/c", COMMAND] };
  return { command: COMMAND, prefix: [] };
}

/**
 * Characters `cmd.exe` interprets even inside an argument a host did not
 * quote (hosts quote only arguments with whitespace). A vault path holding
 * one would be split or executed by the `cmd /c` launcher, so the Windows
 * payload refuses it by name instead of writing a config that breaks - or
 * runs something - at spawn time.
 */
const CMD_METACHARACTERS = /[&|<>^%"!]/;

/**
 * Environment every Windows payload entry carries: cmd.exe and the Win32
 * search it drives stop looking in the current directory for a bare
 * command name (see {@link launcherCommand}).
 */
export const WINDOWS_LAUNCHER_ENV: Readonly<Record<string, string>> = Object.freeze({
  NoDefaultCurrentDirectoryInExePath: "1",
});

/**
 * The two registrations every adapter writes, verbatim.
 *
 * The entries register a STDIO server - `o2b mcp --vault <vault>` - and
 * carry no credential: the env block names identity and timezone only.
 * That is why a minted MCP token changes nothing for a harness
 * bootstrapped with this payload: stdio identity is config-derived (one
 * caller per process that already owns the process tree), and the token
 * authenticates the HTTP transport's hand-configured clients instead.
 */
export function buildPayload(cfg: PayloadConfig, platform: string = process.platform): McpPayload {
  if (!cfg.vault || typeof cfg.vault !== "string") {
    throw new PayloadError("buildPayload: vault is required");
  }
  if (platform === "win32" && CMD_METACHARACTERS.test(cfg.vault)) {
    throw new PayloadError(
      `buildPayload: the vault path ${cfg.vault} contains a character cmd.exe interprets ` +
        '(& | < > ^ % " !); MCP hosts on Windows start o2b through `cmd /c`, which would split ' +
        "or execute it. Move or rename the vault so its path has none of them.",
    );
  }
  const env = buildEnv(cfg, platform);
  const { command, prefix } = launcherCommand(platform);
  const full: McpServerEntry = {
    command,
    args: [...prefix, "mcp", "--vault", cfg.vault],
    ...(env ? { env } : {}),
  };
  const writer: McpServerEntry = {
    command,
    args: [...prefix, "mcp", "--writer-only", "--vault", cfg.vault],
    ...(env ? { env } : {}),
  };
  return { full, writer };
}

/**
 * The arguments `o2b` itself receives from a payload entry, with the
 * Windows launcher words (`cmd /d /c o2b`) taken off the front.
 *
 * A host that does not start the launcher - grok runs
 * `bun run <repo>/src/cli/main.ts` directly - appends the entry's args to
 * its own command. Handing it the Windows args unchanged would make the
 * CLI see `/d /c o2b mcp …` and refuse an unknown verb. The check looks at
 * the entry's own shape rather than the current platform, so a payload
 * built for either platform strips correctly on any host.
 */
export function cliArgs(entry: McpServerEntry): ReadonlyArray<string> {
  const win = launcherCommand("win32");
  const hasPrefix =
    entry.command === win.command && win.prefix.every((word, i) => entry.args[i] === word);
  return hasPrefix ? entry.args.slice(win.prefix.length) : entry.args;
}

function buildEnv(cfg: PayloadConfig, platform: string): Record<string, string> | undefined {
  const env: Record<string, string> = platform === "win32" ? { ...WINDOWS_LAUNCHER_ENV } : {};
  if (cfg.agent_name) env["VAULT_AGENT_NAME"] = cfg.agent_name;
  if (cfg.timezone) env["VAULT_TIMEZONE"] = cfg.timezone;
  return Object.keys(env).length > 0 ? env : undefined;
}