Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.8 KB
Raw Blame
/**
 * GBRAIN_SERVE_SYNC_IPC='0' kill switch — both halves of the contract.
 *
 * Lane 1 — the ENV GATE itself (src/mcp/server.ts). The env is read at serve
 * boot (call-time, inside startMcpServer's resolve-IPC block), and
 * startMcpServer cannot run in-process (its StdioServerTransport attaches to
 * the REAL process.stdin and its shutdown chain ends in process.exit — a
 * stdin EOF would silently kill the test runner). So a child process boots
 * the REAL startMcpServer (bun -e driver: real in-memory PGLite engine + a
 * tmp GBRAIN_HOME config whose database_path anchors the socket/secret).
 * With the switch set, the listener that WOULD have registered the sync
 * kinds answers sync_start/sync_status/sync_abort with unsupported_kind
 * while resolve + turn_context still work. A CONTROL child without the
 * switch answers sync_status with unknown_job — this kills the vacuity
 * class where a broken serve-sync-runner import (whose catch ALSO yields
 * handler-absent → unsupported_kind) would masquerade as the kill switch.
 * The stub-composition analog (handler map without sync kinds →
 * unsupported_kind) is pinned in test/context/resolve-ipc-sync-kinds.test.ts
 * and deliberately NOT duplicated here.
 *
 * Lane 2 — the CLIENT ladder mapping (src/commands/sync-delegate.ts). On
 * unsupported_kind the delegate client prints the documented remediation
 * ("sync delegation disabled (GBRAIN_SERVE_SYNC_IPC=0 or a startup
 * failure)"), sets exit verdict 1, and returns true (HANDLED). true is the
 * no-fall-through contract: cli.ts `return`s on it (src/cli.ts sync
 * pre-connect hook), so the client can never proceed to a direct in-process
 * sync against a brain a live serve still holds.
 *
 * Serial: spawns bun subprocesses that boot PGLite WASM, and the ladder lane
 * mutates env (withEnv) + the CLI exit verdict / process.exitCode.
 */

import { describe, test, expect, afterEach } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import {
  IPC_UNAVAILABLE,
  ensureIpcSecret,
  ipcSecretPath,
  readIpcSecret,
  requestSyncAbort,
  requestSyncStart,
  requestSyncStatus,
  requestTurnContext,
  resolveSocketPath,
  resolveViaIpc,
  startResolveIpcServer,
  type TurnContextResponse,
} from '../src/core/context/resolve-ipc.ts';
import type { SyncStartResponse, SyncStatusResponse } from '../src/core/context/sync-ipc.ts';
import { maybeDelegateSyncToServe } from '../src/commands/sync-delegate.ts';
import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';
import { withEnv } from './helpers/with-env.ts';

const REPO_ROOT = resolve(import.meta.dir, '..');

const cleanupDirs: string[] = [];
const killers: Array<() => Promise<void>> = [];
afterEach(async () => {
  for (const kill of killers.splice(0)) { try { await kill(); } catch { /* dead */ } }
  for (const d of cleanupDirs.splice(0)) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } }
});

/** Env the child must NOT inherit (a dev/CI DATABASE_URL would flip engines;
 * ambient brain/source/opt-out vars would perturb the serve's resolution). */
const CHILD_STRIP = [
  'GBRAIN_DATABASE_URL', 'DATABASE_URL', 'GBRAIN_BRAIN_ID', 'GBRAIN_SOURCE',
  'GBRAIN_SYNC_NO_DELEGATE', 'GBRAIN_HOOKS', 'GBRAIN_SERVE_SYNC_IPC',
];

interface DriverServe {
  sock: string;
  secret: string;
  stderrText: () => string;
}

/**
 * Boot the REAL startMcpServer in a child process. In-memory PGLite engine
 * (snapshot-eligible, fast) + a tmp config whose database_path exists only to
 * anchor the IPC socket + secret — the resolve-IPC block reads
 * loadConfig().database_path for those paths and uses the passed engine for
 * every handler. stdin is a held-open silent pipe (the MCP stdio transport
 * reads it; EOF would trigger the shutdown chain).
 */
async function bootDriverServe(extraEnv: Record<string, string>): Promise<DriverServe> {
  const tmpParent = mkdtempSync(join(tmpdir(), 'gb-ssk-'));
  cleanupDirs.push(tmpParent);
  const home = join(tmpParent, '.gbrain');
  mkdirSync(home, { recursive: true });
  const dbDir = join(tmpParent, 'db');
  writeFileSync(
    join(home, 'config.json'),
    JSON.stringify({ engine: 'pglite', database_path: dbDir, embedding_dimensions: 1536 }),
  );

  const env = { ...process.env } as Record<string, string>;
  for (const k of CHILD_STRIP) delete env[k];
  Object.assign(env, {
    GBRAIN_HOME: tmpParent,
    HOME: tmpParent,
    GBRAIN_SWEEP: '0',
    GBRAIN_SKIP_STARTUP_HOOKS: '1',
  }, extraEnv);

  const driver = [
    '(async () => {',
    `  const { PGLiteEngine } = await import(${JSON.stringify(join(REPO_ROOT, 'src', 'core', 'pglite-engine.ts'))});`,
    `  const { startMcpServer } = await import(${JSON.stringify(join(REPO_ROOT, 'src', 'mcp', 'server.ts'))});`,
    '  const engine = new PGLiteEngine();',
    '  await engine.connect({});',
    '  await engine.initSchema();',
    '  await startMcpServer(engine);',
    "  console.error('[driver] serve ready');",
    "})().catch((e) => { console.error('[driver] boot failed: ' + (e && e.stack ? e.stack : String(e))); process.exit(1); });",
  ].join('\n');

  const proc = Bun.spawn([process.execPath, '-e', driver], {
    cwd: tmpParent,
    env,
    stdin: 'pipe',
    stdout: 'pipe',
    stderr: 'pipe',
  });
  killers.push(async () => {
    if (proc.exitCode === null) { proc.kill('SIGKILL'); await proc.exited; }
  });
  const stderrChunks: string[] = [];
  const decoder = new TextDecoder();
  for (const [stream, sink] of [[proc.stdout, null], [proc.stderr, stderrChunks]] as const) {
    void (async () => {
      const reader = (stream as ReadableStream<Uint8Array>).getReader();
      try {
        for (;;) {
          const { value, done } = await reader.read();
          if (done) break;
          if (sink) sink.push(decoder.decode(value, { stream: true }));
        }
      } catch { /* child gone */ }
    })();
  }

  const sock = resolveSocketPath(dbDir);
  const deadline = Date.now() + 90_000;
  while (!(existsSync(sock) && existsSync(ipcSecretPath(dbDir)))) {
    if (proc.exitCode !== null) {
      throw new Error(`driver serve exited early (code ${proc.exitCode})\nstderr:\n${stderrChunks.join('')}`);
    }
    if (Date.now() > deadline) {
      throw new Error(`timed out waiting for the IPC socket + secret\nstderr:\n${stderrChunks.join('')}`);
    }
    await new Promise((r) => setTimeout(r, 100));
  }
  return { sock, secret: readIpcSecret(dbDir)!, stderrText: () => stderrChunks.join('') };
}

/** Retry an IPC round trip past transient IPC_UNAVAILABLE (child still settling). */
async function withIpcRetry<T>(fn: () => Promise<T | typeof IPC_UNAVAILABLE>): Promise<T | typeof IPC_UNAVAILABLE> {
  let last: T | typeof IPC_UNAVAILABLE = IPC_UNAVAILABLE;
  for (let i = 0; i < 5; i++) {
    last = await fn();
    if (last !== IPC_UNAVAILABLE) return last;
    await new Promise((r) => setTimeout(r, 200));
  }
  return last;
}

describe('GBRAIN_SERVE_SYNC_IPC=0 — the serve-boot env gate (real startMcpServer)', () => {
  test('switch set: sync kinds answer unsupported_kind while resolve + turn_context still work', async () => {
    const serve = await bootDriverServe({ GBRAIN_SERVE_SYNC_IPC: '0' });

    const start = await withIpcRetry(() =>
      requestSyncStart(serve.sock, { secret: serve.secret, clientToken: 'ks-1', options: { timeoutSeconds: 60 } }),
    );
    expect(start).not.toBe(IPC_UNAVAILABLE);
    const startResp = start as SyncStartResponse;
    expect(startResp.ok).toBe(false);
    expect(startResp.error).toBe('unsupported_kind');
    expect(startResp.protocol).toBe(2);

    const status = await requestSyncStatus(serve.sock, { secret: serve.secret, jobId: 'any' });
    expect((status as SyncStatusResponse).error).toBe('unsupported_kind');
    const abort = await requestSyncAbort(serve.sock, { secret: serve.secret, jobId: 'any' });
    expect((abort as SyncStatusResponse).error).toBe('unsupported_kind');

    // The switch narrows the surface, it never blinds it: the same listener
    // still answers the resolve kind ok (resolveViaIpc collapses ok:false
    // into IPC_UNAVAILABLE, so not-UNAVAILABLE === the handler answered ok)…
    const resolved = await withIpcRetry(() => resolveViaIpc(serve.sock, { candidates: [] }));
    expect(resolved).not.toBe(IPC_UNAVAILABLE);

    // …and turn_context (secret-gated, so this also proves the secret file
    // the client reads is the one the serve provisioned).
    const tc = await withIpcRetry(() =>
      requestTurnContext(serve.sock, { secret: serve.secret, window: [] }, { timeoutMs: 5_000 }),
    );
    expect(tc).not.toBe(IPC_UNAVAILABLE);
    const tcResp = tc as TurnContextResponse;
    expect(tcResp.protocol).toBe(2);
    expect(tcResp.ok).toBe(true);

    // The gate-off path is a SILENT skip; the runner-import-failure path (the
    // other route to handler-absent) logs loudly. Distinguish them.
    expect(serve.stderrText()).not.toContain('[serve-sync] handlers unavailable');
  }, 120_000);

  test('control (switch unset): the same driver registers the kinds — sync_status answers unknown_job', async () => {
    // Sensitivity pin: without this control, a broken serve-sync-runner
    // import would ALSO produce unsupported_kind (its catch skips
    // registration) and the killswitch test above would pass vacuously.
    // sync_status on an unknown jobId is the side-effect-free discriminator:
    // registered handlers answer unknown_job, an absent map answers
    // unsupported_kind.
    const serve = await bootDriverServe({});
    const status = await withIpcRetry(() =>
      requestSyncStatus(serve.sock, { secret: serve.secret, jobId: 'missing' }),
    );
    expect(status).not.toBe(IPC_UNAVAILABLE);
    const resp = status as SyncStatusResponse;
    expect(resp.ok).toBe(false);
    expect(resp.error).toBe('unknown_job');
    expect(resp.protocol).toBe(2);
    expect(serve.stderrText()).not.toContain('[serve-sync] handlers unavailable');
  }, 120_000);
});

describe('client ladder — the unsupported_kind arm (sync-delegate.ts)', () => {
  test('live serve answering unsupported_kind → documented remediation, verdict 1, HANDLED (no direct-sync fall-through)', async () => {
    const dataDir = mkdtempSync(join(tmpdir(), 'gb-ssk-ladder-'));
    cleanupDirs.push(dataDir);
    // A provably-alive serve holder (the PID is us) — same fixture shape as
    // test/sync-delegate-ladder.test.ts.
    mkdirSync(join(dataDir, '.gbrain-lock'), { recursive: true });
    writeFileSync(
      join(dataDir, '.gbrain-lock', 'lock'),
      JSON.stringify({
        pid: process.pid,
        acquired_at: new Date().toISOString(),
        refreshed_at: new Date().toISOString(),
        command: '/x/gbrain/src/cli.ts serve',
        subcommand: 'serve',
      }),
    );
    const secret = ensureIpcSecret(dataDir);
    // The exact handler map a killswitched serve registers: resolve present,
    // sync kinds ABSENT — the real IPC server then answers unsupported_kind.
    const server = await startResolveIpcServer(
      resolveSocketPath(dataDir),
      { resolve: async () => null },
      { secret },
    );
    expect(server).not.toBeNull();

    const savedExitCode = process.exitCode;
    _resetCliExitVerdictForTests();
    /* eslint-disable no-console */
    const origError = console.error;
    const lines: string[] = [];
    console.error = (...a: unknown[]) => { lines.push(a.map(String).join(' ')); };
    try {
      const handled = await withEnv(
        // Hermetic ladder walk: host brain, no ambient source, opt-out unset.
        { GBRAIN_BRAIN_ID: undefined, GBRAIN_SOURCE: undefined, GBRAIN_SYNC_NO_DELEGATE: undefined, GBRAIN_HOME: dataDir },
        () => maybeDelegateSyncToServe(dataDir, []),
      );
      // true = HANDLED: cli.ts's pre-connect hook `return`s on it, so the
      // direct connect-engine + in-process sync path NEVER runs. false would
      // be the fall-through — the exact bug this arm exists to prevent.
      expect(handled).toBe(true);
      const text = lines.join('\n');
      expect(text).toContain('the serve has sync delegation disabled (GBRAIN_SERVE_SYNC_IPC=0 or a startup failure).');
      // remediation(): the flag-independent ways out are always named.
      expect(text).toContain('stop the serve (PID');
      expect(text).toContain('--no-delegate');
      // The refusal happened up-front: no delegation banner, no poll loop.
      expect(text).not.toContain('delegating the sync through it');
      expect(currentExitCode()).toBe(1);
    } finally {
      console.error = origError;
      /* eslint-enable no-console */
      try { server!.close(); } catch { /* noop */ }
      _resetCliExitVerdictForTests();
      // setCliExitVerdict mirrors into process.exitCode — undo, or this FILE
      // exits 1 with 0 fails. `?? 0`: Bun ignores an undefined assignment.
      process.exitCode = savedExitCode ?? 0;
    }
  });
});