Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.9 KB
Raw Blame
/**
 * `--help` must be answerable with no brain configured.
 *
 * A reader runs `--help` most often right after install, before `gbrain init`.
 * CLI_ONLY_SELF_HELP members skip the dispatcher's generic usage stub (that is
 * the point — they print their own), but they were then reached through the
 * normal dispatch, which connects the engine first. So on a machine with no
 * brain they exited 1 with "No brain configured" and their own help block was
 * unreachable code.
 *
 * The oracle here is behaviour, not a declaration: each command is actually
 * run with an empty GBRAIN_HOME.
 */
import { describe, test, expect } from 'bun:test';
import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

const REPO = fileURLToPath(new URL('..', import.meta.url));

/** Answer `--help` before touching the engine. */
const HELP_WITHOUT_BRAIN = [
  'models',
  'watch',
  'skillopt',
  'maintain',
  'extract-conversation-facts',
  'transcripts',
  'jobs',
  // #4152: dream answers --help (and the retriage subverb help) engine-free.
  'dream',
  // cathedral-5: runCompileContext honours help before reading the engine
  // (SELF_HELP_WITHOUT_ENGINE loader, same shape as dream/jobs).
  'compile-context',
  'sources',
  // cathedral-6: agent answers --help (incl. `register --help`) engine-free.
  'agent',
  // wave-2 repair core: runRepairCommand prints REPAIR_HELP before the engine.
  'repair',
  // System One: the decide dispatch module prints its help before connecting.
  'decide',
  // D3: handlers that print their own help, once shadowed by the generic stub
  // (selfHelp flipped). Pre-connect records answer before any engine...
  'remote', 'providers', 'resolvers', 'integrity', 'mounts', 'routing-eval', 'skillify', 'claw-test',
  // ...conversation-parser through its engine-free subcommand route, the rest
  // through SELF_HELP_WITHOUT_ENGINE's table entries.
  'conversation-parser', 'advisor', 'anomalies', 'backfill', 'book-mirror', 'edges-backfill', 'features',
  'founder', 'graph-query', 'orphans', 'salience', 'think',
  // D5: selfHelp handlers that already answered --help before the engine but
  // were reached only after connect; now SELF_HELP_WITHOUT_ENGINE table entries.
  'brainstorm', 'lsd', 'migrate', 'pages', 'pricing', 'whoknows',
  // Agent operator gate fixes: embed's usage (incl. its consent flags) prints before the engine.
  'embed',
  // Core memory: runCore prints its usage for --help before reading the engine.
  'core',
  // #6114: router commands print their usage from cli.ts before dispatch (src/cli/router-help.ts).
  'config',
  // Cat 41 run 4: recall's usage (incl. --question) prints before the engine.
  'recall',
];

/**
 * Self-help members that still need a brain for `--help`, because their handler
 * has no `--help` branch to reach. Pinned rather than omitted so the list can
 * only shrink deliberately: writing help for one of these, or dropping it from
 * CLI_ONLY_SELF_HELP so the generic stub answers, fails this test until the
 * entry moves.
 */
const STILL_NEEDS_A_BRAIN: string[] = [];

async function runHelp(command: string): Promise<{ code: number; out: string }> {
  return runCli([command, '--help']);
}

async function runCli(argv: string[]): Promise<{ code: number; out: string }> {
  const home = mkdtempSync(join(tmpdir(), 'gbrain-nobrain-'));
  // An empty GBRAIN_HOME is not enough: loadConfig also honours
  // GBRAIN_DATABASE_URL and DATABASE_URL (config.ts:550-551), so a developer
  // or CI runner that exports either would let the CLI connect anyway — the
  // positive assertions would pass on master and this guard would be inert.
  const env: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: home };
  delete env.GBRAIN_DATABASE_URL;
  delete env.DATABASE_URL;
  // --no-env-file: bun auto-loads .env from cwd, and GBRAIN_DATABASE_URL is
  // honored unconditionally, so a developer's local .env would put back
  // exactly what the deletes above removed.
  const proc = Bun.spawn(['bun', '--no-env-file', 'run', 'src/cli.ts', ...argv], {
    cwd: REPO,
    env,
    stdout: 'pipe',
    stderr: 'pipe',
  });
  const [stdout, stderr] = await Promise.all([
    new Response(proc.stdout).text(),
    new Response(proc.stderr).text(),
  ]);
  const code = await proc.exited;
  return { code, out: stdout + stderr };
}

describe('--help without a configured brain', () => {
  // cathedral-6: the register SUBCOMMAND help must also answer brainless —
  // the whole point of the SELF_HELP_WITHOUT_ENGINE entry is that a reader on
  // a fresh machine can discover the mint flow before they have a brain.
  test('agent register --help answers with real help', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-nobrain-'));
    const env: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: home };
    delete env.GBRAIN_DATABASE_URL;
    delete env.DATABASE_URL;
    const proc = Bun.spawn(['bun', '--no-env-file', 'run', 'src/cli.ts', 'agent', 'register', '--help'], {
      cwd: REPO, env, stdout: 'pipe', stderr: 'pipe',
    });
    const [stdout, stderr] = await Promise.all([
      new Response(proc.stdout).text(),
      new Response(proc.stderr).text(),
    ]);
    const code = await proc.exited;
    expect(code).toBe(0);
    expect(stdout + stderr).toContain('--preset daily-driver|coding-agent');
  }, 30_000);

  // System One: the eval-only judge harness is discoverable (and runnable) brainless.
  test('decide judge-agreement --help answers with its usage', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-nobrain-'));
    const env: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: home };
    delete env.GBRAIN_DATABASE_URL;
    delete env.DATABASE_URL;
    for (const args of [['decide', 'judge-agreement', '--help'], ['decide', 'judge-agreement']]) {
      const proc = Bun.spawn(['bun', '--no-env-file', 'run', 'src/cli.ts', ...args], { cwd: REPO, env, stdout: 'pipe', stderr: 'pipe' });
      const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
      await proc.exited;
      expect(stdout + stderr).not.toContain('No brain configured');
      expect(stdout + stderr).toContain('judge-agreement --suite <longmemeval|grounding> --input <file>');
    }
  }, 30_000);

  // D5: retrieval-upgrade is an alias whose help is the `migrate embeddings` usage.
  test('retrieval-upgrade --help answers with the migrate embeddings usage', async () => {
    const { code, out } = await runHelp('retrieval-upgrade');
    expect(code).toBe(0);
    expect(out).not.toContain('No brain configured');
    expect(out).toContain('Usage: gbrain migrate embeddings --to <provider:model>');
  }, 30_000);

  for (const command of HELP_WITHOUT_BRAIN) {
    test(`${command} --help answers`, async () => {
      const { code, out } = await runHelp(command);
      expect(code).toBe(0);
      expect(out).not.toContain('No brain configured');
      // Real help, not a one-line stub or an empty exit.
      expect(out.split('\n').filter(l => l.trim()).length).toBeGreaterThan(3);
      expect(out.toLowerCase()).toContain(command.split('-')[0]);
    }, 30_000);
  }

  // #6521: a subcommand's help must answer brainless too. SELF_HELP_WITHOUT_ENGINE dispatches the handler with a
  // null engine and trusts it to answer help first; `core list --help` ran `list` against null ("null is not an
  // object (evaluating 'exec.executeRaw')", exit 1) and `loops show --help` exited 2 ("needs a loop id"). `core`
  // and `loops` are routers now (cli.ts prints their usage before dispatch, src/cli/router-help.ts); `transcripts`
  // keeps per-subcommand help, so its handler answers the flag for `status`/`audit-secrets`. The explicit table
  // is the fail-first; the ROUTERS walk in test/helpers/cli-help-gate.ts is the ratchet afterwards.
  const SUBCOMMAND_HELP_WITHOUT_BRAIN: Array<{ argv: string[]; usage: string }> = [
    { argv: ['core', 'list', '--help'], usage: 'Usage: gbrain core' },
    { argv: ['core', 'status', '--help'], usage: 'Usage: gbrain core' },
    { argv: ['core', 'init', '--help'], usage: 'Usage: gbrain core' },
    { argv: ['core', 'suggest', '-h'], usage: 'Usage: gbrain core' },
    { argv: ['core', 'add', 'x', '--help'], usage: 'Usage: gbrain core' },
    { argv: ['core', 'add', 'help'], usage: 'Usage: gbrain core' },
    { argv: ['loops', 'list', '--help'], usage: 'gbrain loops —' },
    { argv: ['loops', 'show', '--help'], usage: 'gbrain loops —' },
    { argv: ['loops', 'done', '--help'], usage: 'gbrain loops —' },
    { argv: ['loops', 'drop', '-h'], usage: 'gbrain loops —' },
    { argv: ['loops', 'mute', '--help'], usage: 'gbrain loops —' },
    { argv: ['loops', 'unmute', 'help'], usage: 'gbrain loops —' },
    { argv: ['transcripts', 'status', '--help'], usage: 'gbrain transcripts' },
    { argv: ['transcripts', 'audit-secrets', '--help'], usage: 'gbrain transcripts' },
  ];
  test('subcommand help answers brainless (#6521: core, loops, transcripts status)', async () => {
    const results = await Promise.all(SUBCOMMAND_HELP_WITHOUT_BRAIN.map(async c => ({ ...c, ...(await runCli(c.argv)) })));
    for (const r of results) {
      const label = r.argv.join(' ');
      expect(r.out, label).not.toContain('No brain configured');
      expect(r.out, label).not.toContain('internal_error');
      expect(r.out, label).not.toContain('null is not an object');
      expect(r.out, label).not.toContain('needs a loop id');
      expect(r.out, label).toContain(r.usage);
      expect(r.code, label).toBe(0);
    }
  }, 120_000);

  // Value: protects=init --help names the surface the printed registration really pins; fails_when=the help says default full while readiness pins REGISTRATION_SURFACE (starter); why_new=the help line was written before the starter default (#7983 item 5); seam=none; no_claim=the registration argv itself (readiness tests)
  test('init --help names the registration surface default', async () => {
    const { REGISTRATION_SURFACE } = await import('../src/core/mcp-registration.ts');
    const r = await runCli(['init', '--help']);
    expect(r.code).toBe(0);
    expect(r.out).toContain(`(default: ${REGISTRATION_SURFACE}, listing the memory verbs and request_tools)`);
  }, 60_000);

  test('the known-unfixed set is exactly what it claims', async () => {
    // Concurrently: seven sequential CLI spawns is most of this file's wall
    // clock, and each one is independent (its own temp GBRAIN_HOME).
    const results = await Promise.all(
      STILL_NEEDS_A_BRAIN.map(async command => ({ command, ...(await runHelp(command)) })),
    );
    const unexpectedlyWorking = results
      .filter(r => !r.out.includes('No brain configured'))
      .map(r => r.command);
    // Not a wish that they stay broken — a tripwire. Fixing one is good and
    // should move it to HELP_WITHOUT_BRAIN in the same change, so the coverage
    // list never drifts away from reality in either direction.
    expect(unexpectedlyWorking).toEqual([]);
  }, 90_000);
});