Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.6 KB
Raw Blame
/**
 * One surface for every stdio registration gbrain writes
 * (src/core/mcp-registration.ts): readiness (Claude Code, Codex, opencode),
 * init's quickstart line, `registerClaudeMcp` / `registerCodexMcp`, and the
 * plugin generator all build from REGISTRATION_SURFACE through
 * `stdioServeArgv`; `registeredSurface` reads an existing entry's form for
 * never-narrow. The opencode user/project writer and the exec-lane
 * replacement are driven end to end in bootstrap-opencode-door.serial and
 * bootstrap-dispatcher.serial.
 */
import { describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { PLUGIN_SURFACE, REGISTRATION_ADVERTISE, REGISTRATION_SURFACE, registeredAdvertise, registeredSurface, registrationAdvertise, stdioServeArgv } from '../src/core/mcp-registration.ts';
import { harnessWiringEntry } from '../src/core/readiness.ts';
import { hookLauncherPath } from '../src/core/setup/hook-launcher.ts';
import { registerClaudeMcp, registerCodexMcp } from '../src/core/bootstrap/hooks.ts';
import { resolveSurfaceWithSource } from '../src/mcp/surface.ts';

const BIN = '/opt/example/bin/gbrain';
const ROOT = resolve(import.meta.dir, '..');
const wiring = (h: 'claude-code' | 'codex' | 'opencode', surface?: 'verbs' | 'starter' | 'full') =>
  harnessWiringEntry({ transport: 'cli', harnesses: [h], lockOwner: null, gbrainBin: BIN, ...(surface ? { surface } : {}) }).fix;

describe('REGISTRATION_SURFACE and stdioServeArgv', () => {
  test('new registrations pin starter (Garry, 2026-10-24); plugins stay full; null renders a bare serve', () => {
    expect(REGISTRATION_SURFACE).toBe('starter');
    expect(PLUGIN_SURFACE).toBe('full');
    expect(stdioServeArgv(BIN)).toEqual([BIN, 'serve', '--surface', 'starter']);
    expect(stdioServeArgv(BIN, 'starter')).toEqual([BIN, 'serve', '--surface', 'starter']);
    expect(stdioServeArgv(BIN, 'full')).toEqual([BIN, 'serve', '--surface', 'full']);
    expect(stdioServeArgv(BIN, null)).toEqual([BIN, 'serve']);
  });

  test('new registrations list the memory verbs; --advertise is written only when narrower than the surface', () => {
    expect(REGISTRATION_ADVERTISE).toBe('verbs');
    expect(stdioServeArgv(BIN, REGISTRATION_SURFACE, REGISTRATION_ADVERTISE)).toEqual([BIN, 'serve', '--surface', 'starter', '--advertise', 'verbs']);
    expect(stdioServeArgv(BIN, 'starter', 'verbs')).toEqual([BIN, 'serve', '--surface', 'starter', '--advertise', 'verbs']);
    expect(stdioServeArgv(BIN, 'verbs', 'verbs')).toEqual([BIN, 'serve', '--surface', 'verbs']);
    expect(stdioServeArgv(BIN, null, 'verbs')).toEqual([BIN, 'serve']);
  });

  test('registrationAdvertise: a chosen surface lists in full, an existing registration keeps its listing, a new one lists the verbs', () => {
    expect(registrationAdvertise({ userChoseSurface: false })).toBe('verbs');
    expect(registrationAdvertise({ userChoseSurface: true })).toBeNull();
    expect(registrationAdvertise({ userChoseSurface: false, prior: {} })).toBeNull();
    expect(registrationAdvertise({ userChoseSurface: false, prior: { advertise: 'starter' } })).toBe('starter');
    expect(registrationAdvertise({ userChoseSurface: true, prior: { advertise: 'verbs' } })).toBeNull();
  });

  test('registeredAdvertise reads an existing registration\'s listing', () => {
    expect(registeredAdvertise(`${BIN} serve --surface full --advertise verbs`)).toBe('verbs');
    expect(registeredAdvertise('Args: serve --surface full --advertise=starter')).toBe('starter');
    expect(registeredAdvertise(`${BIN} serve --surface full`)).toBeNull();
  });

  test('registeredSurface reads a pinned value, a bare serve, or nothing', () => {
    expect(registeredSurface(`gbrain:\n  Command: ${BIN}\n  Args: serve --surface full\n`)).toBe('full');
    expect(registeredSurface(`${BIN} serve --surface=verbs --source-guard`)).toBe('verbs');
    expect(registeredSurface(`gbrain:\n  Command: ${BIN}\n  Args: serve\n`)).toBeNull();
    expect(registeredSurface('gbrain: http https://brain.example/mcp')).toBeUndefined();
  });
});

describe('every stdio registration path builds from REGISTRATION_SURFACE', () => {
  test('readiness harness_wiring: Claude Code and Codex pin the surface; opencode runs bootstrap hooks', () => {
    // #8426: Claude Code and Codex register through gbrain setup, which puts serve behind the hook launcher.
    expect(wiring('claude-code')?.argv).toEqual(['gbrain', 'setup', 'claude-code', '--no-hooks', '--gbrain-bin', BIN]);
    expect(wiring('codex')?.argv).toEqual(['gbrain', 'setup', 'codex', '--no-hooks', '--gbrain-bin', BIN]);
    expect(wiring('opencode')?.argv).toEqual(['gbrain', 'bootstrap', 'hooks', '--harness', 'opencode', '--no-hooks']);
    expect(wiring('claude-code')?.why).toContain(`${hookLauncherPath()} ${stdioServeArgv(BIN, REGISTRATION_SURFACE, REGISTRATION_ADVERTISE).join(' ')}`);
  });

  test('init --surface reaches the readiness fix (the quickstart line and the first-run harness decision read it)', () => {
    expect(wiring('claude-code', 'starter')?.argv).toEqual(['gbrain', 'setup', 'claude-code', '--no-hooks', '--gbrain-bin', BIN, '--surface', 'starter']);
    expect(wiring('claude-code', 'starter')?.why).toContain(`${BIN} serve --surface starter`);
    expect(wiring('opencode', 'verbs')?.argv).toEqual(['gbrain', 'bootstrap', 'hooks', '--harness', 'opencode', '--no-hooks', '--surface', 'verbs']);
    const missing = harnessWiringEntry({ transport: 'cli', harnesses: [], lockOwner: null, gbrainBin: BIN }).fix;
    expect(missing?.why).toContain('serve --surface starter --advertise verbs');
  });

  test('bootstrap hooks: registerClaudeMcp and registerCodexMcp write --advertise when given', () => {
    const claude = registerClaudeMcp({ gbrainBin: BIN, scope: 'user', sourceId: 'workspace', advertise: 'verbs' })[0];
    const codex = registerCodexMcp({ gbrainBin: BIN, sourceId: 'workspace', advertise: 'verbs' })[0];
    expect(claude.slice(claude.indexOf('--') + 1)).toEqual([BIN, 'serve', '--surface', 'starter', '--advertise', 'verbs']);
    expect(codex.slice(codex.indexOf('--') + 1)).toEqual([BIN, 'serve', '--surface', 'starter', '--advertise', 'verbs']);
  });

  test('bootstrap hooks: registerClaudeMcp and registerCodexMcp default to the surface and carry an existing form', () => {
    const claude = registerClaudeMcp({ gbrainBin: BIN, scope: 'user', sourceId: 'workspace' })[0];
    const codex = registerCodexMcp({ gbrainBin: BIN, sourceId: 'workspace' })[0];
    expect(claude.slice(claude.indexOf('--') + 1)).toEqual(stdioServeArgv(BIN));
    expect(codex.slice(codex.indexOf('--') + 1)).toEqual(stdioServeArgv(BIN));
    expect(registerClaudeMcp({ gbrainBin: BIN, scope: 'user', sourceId: 'w', surface: 'starter' })[0].slice(-3)).toEqual(['serve', '--surface', 'starter']);
    expect(registerCodexMcp({ gbrainBin: BIN, sourceId: 'w', surface: null })[0].slice(-2)).toEqual([BIN, 'serve']);
  });

  test('the plugin generator states the plugin surface and refuses a manifest pinned elsewhere', () => {
    const out = mkdtempSync(join(tmpdir(), 'gb-reg-plugin-'));
    try {
      const ok = spawnSync('bun', ['run', join(ROOT, 'scripts/generate-plugin-tree.ts'), '--out', join(out, 'plugin')], { encoding: 'utf8', timeout: 60_000 });
      expect(ok.status, ok.stderr).toBe(0);
      expect(readFileSync(join(out, 'plugin', 'README.md'), 'utf8')).toContain(`gbrain serve --surface ${PLUGIN_SURFACE}`);
      for (const file of ['.codex-plugin/mcp.json', '.claude-plugin/plugin.json']) {
        const args = (JSON.parse(readFileSync(join(ROOT, file), 'utf8')) as { mcpServers: { gbrain: { args: string[] } } }).mcpServers.gbrain.args;
        expect(args[args.indexOf('--surface') + 1]).toBe(PLUGIN_SURFACE);
      }

      const root = join(out, 'fixture');
      mkdirSync(join(root, 'skills', 'alpha'), { recursive: true });
      mkdirSync(join(root, 'skills', 'conventions'), { recursive: true });
      mkdirSync(join(root, '.codex-plugin'), { recursive: true });
      writeFileSync(join(root, 'VERSION'), '0.0.0.0\n');
      writeFileSync(join(root, 'openclaw.plugin.json'), JSON.stringify({ name: 'fixture', version: '0.0.0.0', skills: ['skills/alpha'], shared_deps: [] }));
      writeFileSync(join(root, 'skills', 'alpha', 'SKILL.md'), '---\nname: alpha\ndescription: fixture skill\n---\n# alpha\n');
      writeFileSync(join(root, 'skills', 'manifest.json'), JSON.stringify({ skills: [{ name: 'alpha' }] }));
      writeFileSync(join(root, 'skills', 'plugin-lanes.json'), JSON.stringify({ starter_policy: 'x', additions: {}, base_exclusions: {}, not_added: {}, starter_gaps: {} }));
      writeFileSync(join(root, '.codex-plugin', 'mcp.json'), JSON.stringify({ mcpServers: { gbrain: { command: 'x', args: ['serve', '--surface', 'starter'] } } }));
      const bad = spawnSync('bun', ['run', join(ROOT, 'scripts/generate-plugin-tree.ts'), '--out', join(root, 'out')], {
        encoding: 'utf8', timeout: 60_000, env: { ...process.env, GBRAIN_PLUGIN_TREE_ROOT: root },
      });
      expect(bad.status).toBe(1);
      expect(bad.stderr).toContain(`.codex-plugin/mcp.json pins --surface starter; plugin lanes serve the plugin surface '${PLUGIN_SURFACE}'`);
    } finally {
      rmSync(out, { recursive: true, force: true });
    }
  }, 120_000);
});

// S0 (wave 0): one surface constant across every install path. Every
// registration command these files show pins REGISTRATION_SURFACE; a bare
// `serve` resolves to the same value. Narrower surfaces stay documented as
// opt-ins in prose, never as a registration command. The dated *-CLI-PIN.md
// files are verification records of what was observed, not install paths.
describe('S0: README, docs/mcp, INSTALL, BOOTSTRAP, push-context and the manifests name one surface', () => {
  const DOCS = [
    'README.md', 'INSTALL_FOR_AGENTS.md', 'BOOTSTRAP_FOR_AGENTS.md', 'docs/guides/push-context.md',
    'docs/INSTALL.md', 'docs/protocol/MEMORY_VERBS_v1.md', 'docs/tutorials/connect-coding-agent.md',
    ...readdirSync(join(ROOT, 'docs/mcp')).filter(f => f.endsWith('.md') && !f.endsWith('-CLI-PIN.md')).map(f => `docs/mcp/${f}`),
  ];

  test('every `serve --surface <x>` in the install docs is the registration surface', () => {
    const offenders: string[] = [];
    for (const file of DOCS) {
      readFileSync(join(ROOT, file), 'utf8').split('\n').forEach((line, i) => {
        for (const m of line.matchAll(/\bserve\b[^`\n|]*?--surface[\s=]+["']?(verbs|starter|full)\b/g)) {
          if (m[1] !== REGISTRATION_SURFACE) offenders.push(`${file}:${i + 1}: ${line.trim()}`);
        }
      });
    }
    expect(offenders).toEqual([]);
  });

  test('every harness registration command in the install docs lists the memory verbs (--advertise verbs)', () => {
    const offenders: string[] = [];
    let commands = 0;
    for (const file of DOCS) {
      readFileSync(join(ROOT, file), 'utf8').split('\n').forEach((line, i) => {
        for (const m of line.matchAll(/\bmcp add\b[^`\n|]*?\bserve\b([^`\n|]*)/g)) {
          commands++;
          if (/--access[\s=]+read-only/.test(m[1])) continue;
          if (!new RegExp(`--advertise(?:[\\s=]+|\\s+--arg\\s+)${REGISTRATION_ADVERTISE}\\b`).test(m[1])) offenders.push(`${file}:${i + 1}: ${line.trim()}`);
        }
      });
    }
    expect(commands).toBeGreaterThanOrEqual(10);
    expect(offenders).toEqual([]);
  });

  test('#8436: no install doc teaches a Claude Code or Codex stdio mcp add of serve that skips gbrain\'s launcher', () => {
    const offenders: string[] = [];
    for (const file of [...DOCS, 'docs/protocol/AGENT_OPERATOR_v1.md']) {
      readFileSync(join(ROOT, file), 'utf8').split('\n').forEach((line, i) => {
        for (const m of line.matchAll(/\b(?:claude|codex)\s+mcp add\b[^`\n|]*?\bserve\b/g)) {
          if (!m[0].includes('hook-launcher/gbrain-hook')) offenders.push(`${file}:${i + 1}: ${line.trim()}`);
        }
      });
    }
    expect(offenders).toEqual([]);
  });

  test('the plugin manifests pin the plugin surface (full); the OpenClaw bundle runs a bare serve, whose default is full too', () => {
    for (const file of ['.codex-plugin/mcp.json', '.claude-plugin/plugin.json']) {
      const args = (JSON.parse(readFileSync(join(ROOT, file), 'utf8')) as { mcpServers: { gbrain: { args: string[] } } }).mcpServers.gbrain.args;
      expect({ file, surface: args[args.indexOf('--surface') + 1] }).toEqual({ file, surface: PLUGIN_SURFACE });
    }
    const openclaw = JSON.parse(readFileSync(join(ROOT, 'openclaw.plugin.json'), 'utf8')) as { mcpServers: { gbrain: { args: string[] } } };
    expect(openclaw.mcpServers.gbrain.args).toEqual(['serve']);
    expect(resolveSurfaceWithSource(null, {})).toEqual({ surface: PLUGIN_SURFACE, source: 'default' });
  });
});