Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `--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);
});