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.2 KB
Raw Blame
/**
 * The fault guard in a real process.
 *
 * The in-process suite (`mcp-fault-guard.test.ts`) dispatches faults with
 * `process.emit`, because the test runner fails a test on any genuine
 * unhandled rejection. Only a spawned process proves the two claims the
 * guard makes about the runtime: a detached rejection does NOT end the
 * server, and an uncaught exception ends it with 70 THROUGH the exit
 * hooks (the lock file the hook unlinks is gone afterwards).
 *
 * Children get a throwaway HOME and TMPDIR under this run's own temp
 * directory, so no product code they run reaches the operator's config.
 */

import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { EXIT_INTERNAL_FAULT, FAULT_KIND } from "../../src/cli/mcp-fault-guard.ts";
import { IS_WINDOWS, homeEnv } from "../helpers/platform.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

const REPO_ROOT = join(import.meta.dir, "../..");
const FIXTURES = join(import.meta.dir, "../fixtures/mcp-fault-guard");
const CLI = join(REPO_ROOT, "src/cli/main.ts");
/** The runtime running this suite, so children never pick another Bun from PATH. */
const BUN = process.execPath;
/** A generous ceiling: each child starts and finishes in well under a second. */
const SPAWN_TIMEOUT_MS = 30_000;

const temps: string[] = [];

afterEach(() => {
  while (temps.length > 0) rmSync(temps.pop()!, { recursive: true, force: true });
});

function sandbox(): { vault: string; env: Record<string, string> } {
  const root = mkdtempSync(join(tmpdir(), "osb-mcp-fault-guard-"));
  temps.push(root);
  const vault = join(root, "vault");
  const home = join(root, "home");
  const tmp = join(root, "tmp");
  for (const dir of [vault, home, tmp]) mkdirSync(dir, { recursive: true });
  return {
    vault,
    env: {
      PATH: process.env["PATH"] ?? "",
      // Without it a Windows child cannot initialise Winsock.
      ...(process.env["SYSTEMROOT"] ? { SYSTEMROOT: process.env["SYSTEMROOT"] } : {}),
      ...homeEnv(home),
      TMPDIR: tmp,
      TMP: tmp,
      TEMP: tmp,
    },
  };
}

function frame(id: number, method: string, params: Record<string, unknown> = {}): string {
  return `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
}

/**
 * Collect stdout lines as they arrive, so a test can wait for one by id.
 * A wait still pending when stdout ends is rejected by name: a child that
 * died fails the test at once instead of at the timeout.
 */
function lineReader(stream: ReadableStream<Uint8Array>): {
  waitFor: (pred: (line: string) => boolean) => Promise<string>;
} {
  interface Waiter {
    readonly pred: (line: string) => boolean;
    readonly done: (line: string) => void;
    readonly fail: (error: Error) => void;
  }
  const lines: string[] = [];
  let waiters: Waiter[] = [];
  let ended = false;
  const settle = (line: string): void => {
    lines.push(line);
    waiters = waiters.filter((w) => {
      if (!w.pred(line)) return true;
      w.done(line);
      return false;
    });
  };
  void (async () => {
    const decoder = new TextDecoder();
    let buffer = "";
    for await (const chunk of stream) {
      buffer += decoder.decode(chunk, { stream: true });
      const parts = buffer.split("\n");
      buffer = parts.pop() ?? "";
      for (const line of parts) settle(line);
    }
    ended = true;
    for (const w of waiters) w.fail(new Error("child stdout ended before the awaited response"));
    waiters = [];
  })();
  return {
    waitFor: (pred) =>
      new Promise((done, fail) => {
        const hit = lines.find(pred);
        if (hit !== undefined) done(hit);
        else if (ended) fail(new Error("child stdout ended before the awaited response"));
        else waiters.push({ pred, done, fail });
      }),
  };
}

const responseTo =
  (id: number) =>
  (line: string): boolean => {
    try {
      return (JSON.parse(line) as { id?: unknown }).id === id;
    } catch {
      return false;
    }
  };

describe("mcp fault guard in a spawned process", () => {
  test(
    "a detached rejection is named and the server keeps answering",
    async () => {
      const { vault, env } = sandbox();
      const proc = Bun.spawn([BUN, join(FIXTURES, "serve-with-rejection.ts"), vault], {
        cwd: REPO_ROOT,
        env,
        stdin: "pipe",
        stdout: "pipe",
        stderr: "pipe",
      });
      const stderrText = new Response(proc.stderr).text();
      const out = lineReader(proc.stdout);

      proc.stdin.write(
        frame(1, "initialize", {
          protocolVersion: "2025-06-18",
          capabilities: {},
          clientInfo: { name: "fault-guard-spawn", version: "0" },
        }),
      );
      await out.waitFor(responseTo(1));
      proc.stdin.write(frame(2, "tools/call", { name: "brain_context", arguments: {} }));
      proc.stdin.write(frame(3, "tools/list"));
      const [called, listed] = await Promise.all([
        out.waitFor(responseTo(2)),
        out.waitFor(responseTo(3)),
      ]);
      expect(JSON.parse(called)).toHaveProperty("result");
      expect(JSON.parse(listed).result.tools.length).toBeGreaterThan(0);
      expect(proc.exitCode).toBeNull();

      proc.stdin.end();
      const code = await proc.exited;
      const stderr = await stderrText;
      expect(stderr).toContain(
        `[mcp] ${FAULT_KIND.unhandledRejection} #1: Error: fixture rejection nobody awaits (server keeps serving)`,
      );
      expect(code).toBe(0);
    },
    SPAWN_TIMEOUT_MS,
  );

  test(
    "an uncaught exception exits 70 through the exit hooks",
    async () => {
      const { vault, env } = sandbox();
      const proc = Bun.spawn([BUN, join(FIXTURES, "serve-with-throw.ts"), vault], {
        cwd: REPO_ROOT,
        env,
        stdin: "ignore",
        stdout: "pipe",
        stderr: "pipe",
      });
      const [stdout, stderr, code] = await Promise.all([
        new Response(proc.stdout).text(),
        new Response(proc.stderr).text(),
        proc.exited,
      ]);
      const lockPath = stdout.trim();
      expect(lockPath).toEndWith(".lock");
      expect(stderr).toContain(
        `[mcp] ${FAULT_KIND.uncaughtException}: Error: fixture exception from a timer`,
      );
      expect(code).toBe(EXIT_INTERNAL_FAULT);
      // The sync lockfile module's `exit` hook ran: the lock is gone.
      expect(existsSync(lockPath)).toBe(false);
    },
    SPAWN_TIMEOUT_MS,
  );

  test(
    "a rejection inside o2b mcp over HTTP raises the /health count, and the guard is released",
    async () => {
      const { vault, env } = sandbox();
      const proc = Bun.spawn(
        [
          BUN,
          "--preload",
          join(FIXTURES, "reject-once-guarded.ts"),
          CLI,
          "mcp",
          "--transport",
          "http",
          "--port",
          "0",
          "--vault",
          vault,
        ],
        { cwd: REPO_ROOT, env, stdin: "ignore", stdout: "ignore", stderr: "pipe" },
      );
      const err = lineReader(proc.stderr);
      try {
        const named = err.waitFor((line) =>
          line.includes(`[mcp] ${FAULT_KIND.unhandledRejection} #1: Error: fixture rejection`),
        );
        const listening = await err.waitFor((line) => line.includes(" listening on http://"));
        const url = /listening on (http:\/\/\S+)/.exec(listening)?.[1];
        expect(url).toBeDefined();
        await named;
        const body = (await (await fetch(`${url}/health`)).json()) as {
          faults?: { unhandled_rejection: number; last_fault_at: string | null };
        };
        expect(body.faults?.unhandled_rejection).toBe(1);
        expect(Number.isNaN(Date.parse(body.faults?.last_fault_at ?? ""))).toBe(false);
        expect(proc.exitCode).toBeNull();
      } finally {
        proc.kill("SIGTERM");
      }
      await proc.exited;
      // A Windows kill ends the child without running its exit hooks, so
      // only POSIX can watch the verb release the guard on the way out.
      if (!IS_WINDOWS) {
        const exitLine = await err.waitFor((line) => line.includes("listeners at exit: "));
        expect(exitLine).toEndWith("listeners at exit: 0");
      }
    },
    SPAWN_TIMEOUT_MS,
  );
});