Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Tests for the top-level CLI dispatch guard introduced in multi-topology v1.
*
* When `~/.gbrain/config.json` has `remote_mcp` set, 9 commands are refused
* with a canonical error pointing at the remote host:
* sync, embed, extract, migrate, apply-migrations, repair-jsonb, orphans,
* integrity, serve.
*
* Doctor is NOT in the refused set — it routes to runRemoteDoctor instead.
*
* Strategy: seed `~/.gbrain/config.json` with remote_mcp set in a tempdir
* home, then spawn `gbrain <cmd>` via test/helpers/cli-spawn.ts (async
* Bun.spawn — NOT execFileSync — so the test event loop stays responsive;
* DATABASE_URL / GBRAIN_DATABASE_URL always stripped, HOME + GBRAIN_HOME
* pinned to the temp home) and assert (a) exit code 1, (b) stderr contains
* the canonical error message, (c) the local engine was never reached.
* GBRAIN_REMOTE_CLIENT_SECRET is stripped per-call — the helper doesn't do
* it and an ambient secret would alter thin-client auth routing.
*
* The refusedCommands spawns run ONCE through runCliBatch (width 2 — the
* machine-wide cap, see cli-spawn.ts) in the describe's beforeAll against a
* single seeded thin-client home; the loop's tests assert on the cached
* results. Sharing the home is safe because refusal happens at the dispatch
* guard before any engine/filesystem work (that IS the invariant under
* test), the seeded engine is `postgres` with no database_url (no scratch
* store possible even under regression), and the loop asserts only on exit
* code + stderr. Everything else still spawns its own child against a fresh
* per-test home (dispatch wiring coverage).
*
* Includes a regression test that local-config installs still pass through
* to connectEngine normally.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach, afterEach } from 'bun:test';
import { mkdtempSync, rmSync, writeFileSync, mkdirSync, existsSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
import { runCli, runCliBatch, type CliResult } from './helpers/cli-spawn.ts';
// The original hand-rolled spawner stripped this alongside the database
// URLs; cli-spawn.ts strips only the URLs, so keep stripping it here.
const HERMETIC_ENV = { GBRAIN_REMOTE_CLIENT_SECRET: undefined } as const;
let tmp: string;
function configPath(home: string): string { return join(home, '.gbrain', 'config.json'); }
function seedThinClientConfig(home: string, extra: Record<string, unknown> = {}) {
mkdirSync(join(home, '.gbrain'), { recursive: true });
writeFileSync(configPath(home), JSON.stringify({
engine: 'postgres',
remote_mcp: {
issuer_url: 'https://brain-host.example',
mcp_url: 'https://brain-host.example/mcp',
oauth_client_id: 'cid',
oauth_client_secret: 'csecret',
},
...extra,
}, null, 2));
}
function seedLocalPGLiteConfig(home: string) {
mkdirSync(join(home, '.gbrain'), { recursive: true });
writeFileSync(configPath(home), JSON.stringify({
engine: 'pglite',
database_path: join(home, 'brain.pglite'),
}, null, 2));
}
async function run(args: string[]): Promise<CliResult> {
return runCli(args, { home: tmp, env: HERMETIC_ENV });
}
// Fresh-home hooks for describes whose tests still spawn their own child.
// Registered per-describe (not module-level) so the batched refusal tests
// don't mint homes they never use.
function useFreshHome(): void {
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), 'gbrain-cli-dispatch-'));
});
afterEach(() => {
try { rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ }
});
}
describe('thin-client dispatch guard refuses DB-bound commands', () => {
// Each command in the refused set MUST exit 1 with a canonical error and
// MUST NOT attempt to connect to a local engine.
const refusedCommands = [
['sync'],
['embed', '--stale'],
['extract', 'links'],
// 'migrate' the engine-migration command (different from the migrations
// orchestrator). Both are in CLI_ONLY but only `migrate-engine` here.
['migrate', '--to', 'pglite'],
['apply-migrations', '--yes'],
['repair-jsonb', '--dry-run'],
['orphans'],
['integrity', 'check'],
['serve', '--http'],
// v0.32 audit REFUSE additions (no MCP route, or localOnly ops) and the
// v0.31.1-era refusals not covered above.
['pages', 'purge-deleted'],
['files', 'list'],
['eval', 'export'],
['code-def', 'fixture'],
['code-refs', 'fixture'],
['code-callers', 'fixture'],
['code-callees', 'fixture'],
['dream'],
['transcripts', 'ingest'],
['storage', 'status'],
['takes', 'extract'],
['sources', 'list'],
];
// One shared seeded home for the batch (see file header for why sharing
// is safe). Do NOT add anything here that writes to the home or depends
// on another row's side effects — batch order is not execution order.
let batchHome: string;
const refused = new Map<string, CliResult>();
beforeAll(async () => {
batchHome = mkdtempSync(join(tmpdir(), 'gbrain-cli-dispatch-refuse-'));
seedThinClientConfig(batchHome);
const results = await runCliBatch(refusedCommands, { home: batchHome, env: HERMETIC_ENV });
refusedCommands.forEach((argv, i) => refused.set(argv.join(' '), results[i]));
}, 120_000);
afterAll(() => {
try { rmSync(batchHome, { recursive: true, force: true }); } catch { /* best-effort */ }
});
function cached(argv: string[]): CliResult {
const r = refused.get(argv.join(' '));
if (!r) throw new Error(`not in refusedCommands batch: gbrain ${argv.join(' ')}`);
return r;
}
for (const args of refusedCommands) {
test(`refuses \`gbrain ${args.join(' ')}\` with pinpoint hint`, () => {
const r = cached(args);
expect(r.exitCode).toBe(1);
// v0.31.1 (Issue #734): refusal carries an actionable hint via
// THIN_CLIENT_REFUSE_HINTS instead of a generic "run on the remote
// host" message. Hint format: "`gbrain <cmd>` is not routable. <hint>"
expect(r.stderr).toContain(`gbrain ${args[0]}`);
expect(r.stderr).toContain('thin-client of https://brain-host.example/mcp');
expect(r.stderr).toContain('not routable');
});
}
});
describe('thin-client dispatch guard does NOT refuse safe commands', () => {
useFreshHome();
// Commands that are still useful in thin-client mode (init, auth, version,
// help) MUST NOT be refused. We assert the canonical thin-client error
// does NOT appear.
test('`gbrain --brain <id> serve` refuses instead of bridging to the configured remote', async () => {
seedThinClientConfig(tmp);
const r = await run(['--brain', 'other-brain', 'serve']);
expect(r.exitCode).toBe(2);
expect(r.stderr).toContain('--brain is not supported on a thin-client install');
expect(r.stderr).not.toContain('[gbrain-bridge] relaying');
});
test('`gbrain --version` works on thin-client install', async () => {
seedThinClientConfig(tmp);
const r = await run(['--version']);
expect(r.exitCode).toBe(0);
expect(r.stdout).toContain('gbrain');
expect(r.stderr).not.toContain('thin client');
});
test('`gbrain --help` works on thin-client install', async () => {
seedThinClientConfig(tmp);
const r = await run(['--help']);
expect(r.exitCode).toBe(0);
expect(r.stderr).not.toContain('requires a local engine');
});
});
describe('thin-client doctor routes to runRemoteDoctor', () => {
useFreshHome();
test('`gbrain doctor` runs remote checks (not DB-bound checks) when remote_mcp is set', async () => {
seedThinClientConfig(tmp);
const r = await run(['doctor', '--json']);
// Doctor will likely fail because brain-host.example isn't reachable —
// but that's irrelevant. What matters is it ran the THIN-CLIENT doctor,
// not the local-DB doctor. Fingerprint: the remote doctor's JSON output
// has `mode: "thin-client"`. The local doctor doesn't.
expect(r.stdout).toContain('"mode":"thin-client"');
// Output must include the remote_mcp fields, NOT a schema_version check.
expect(r.stdout).toContain('"mcp_url":"https://brain-host.example/mcp"');
});
});
describe('regression — local config still passes through normally', () => {
useFreshHome();
test('local PGLite config does NOT trigger thin-client guard for `sync`', async () => {
// Seed a local PGLite config (no remote_mcp). `gbrain sync` shouldn't
// refuse with the thin-client error. It may error for other reasons
// (no brain repo configured, etc.) — what matters is the canonical
// thin-client message MUST NOT appear.
seedLocalPGLiteConfig(tmp);
const r = await run(['sync', '--dry-run']);
expect(r.stderr).not.toContain('thin client');
expect(r.stderr).not.toContain('requires a local engine');
});
test('local PGLite config does NOT trigger guard for `doctor`', async () => {
seedLocalPGLiteConfig(tmp);
const r = await run(['doctor', '--fast', '--json']);
// Local doctor's output has different fingerprint — no `mode: thin-client`.
expect(r.stdout).not.toContain('"mode":"thin-client"');
});
});
describe('thin-client scratch-DB guard — jobs partial dispatch + config refusal', () => {
useFreshHome();
test('`gbrain config set x y` is refused with pinpoint hint', async () => {
seedThinClientConfig(tmp);
const r = await run(['config', 'set', 'search.reranker.enabled', 'false']);
expect(r.exitCode).toBe(1);
expect(r.stderr).toContain('gbrain config');
expect(r.stderr).toContain('not routable');
expect(r.stderr).toContain('thin-client of https://brain-host.example/mcp');
});
// #5254: the unbound-write policy decides whether Postgres pages may skip
// their canonical files; only the brain host may change it (no MCP op writes config).
test('`gbrain config set persistence.unbound_write` is refused on a thin client', async () => {
seedThinClientConfig(tmp);
const r = await run(['config', 'set', 'persistence.unbound_write', 'database_only']);
expect(r.exitCode).toBe(1);
expect(r.stderr).toContain('not routable');
});
test('`gbrain jobs work` is refused with pinpoint hint (host-queue-bound)', async () => {
seedThinClientConfig(tmp);
const r = await run(['jobs', 'work']);
expect(r.exitCode).toBe(1);
expect(r.stderr).toContain('gbrain jobs');
expect(r.stderr).toContain('not routable');
expect(r.stderr).toContain('thin-client of https://brain-host.example/mcp');
});
test('`gbrain jobs get` never fabricates a scratch local engine', async () => {
// The regression this pins: on a thin-client install with a PGLite
// engine key, `jobs get` connected a LOCAL engine before its remote
// routing branch ran — creating an empty scratch PGLite store in the
// thin-client GBRAIN_HOME and replaying the entire migration chain
// ("Schema version 1 → N") on every invocation. The remote call to
// brain-host.example will fail (unreachable) — irrelevant here. What
// matters: no local store is created and no migration replay runs.
seedThinClientConfig(tmp, { engine: 'pglite' });
const r = await run(['jobs', 'get', '999']);
expect(existsSync(join(tmp, '.gbrain', 'brain.pglite'))).toBe(false);
expect(r.stdout + r.stderr).not.toContain('Schema version');
expect(r.stdout + r.stderr).not.toContain('migration(s) pending');
// A scratch store is a FRESH install, so a re-regression would print the
// quiet-replay summary line, not the verbose header — pin both shapes.
expect(r.stdout + r.stderr).not.toContain('Setting up brain schema');
});
test('`gbrain jobs list` never fabricates a scratch local engine', async () => {
seedThinClientConfig(tmp, { engine: 'pglite' });
const r = await run(['jobs', 'list']);
// Partial dispatch owns `jobs`: list/get route over MCP, never refused.
expect(r.stderr).not.toContain('not routable');
expect(existsSync(join(tmp, '.gbrain', 'brain.pglite'))).toBe(false);
expect(r.stdout + r.stderr).not.toContain('Schema version');
expect(r.stdout + r.stderr).not.toContain('Setting up brain schema');
});
test('`gbrain think` never fabricates a scratch local engine', async () => {
// Same class as jobs get: pglite-keyed thin client must not open a
// scratch store / replay migrations before the remote think call.
seedThinClientConfig(tmp, { engine: 'pglite' });
const r = await run(['think', 'What do we know?']);
expect(existsSync(join(tmp, '.gbrain', 'brain.pglite'))).toBe(false);
expect(r.stdout + r.stderr).not.toContain('Schema version');
expect(r.stdout + r.stderr).not.toContain('Setting up brain schema');
expect(r.stdout + r.stderr).not.toContain('database_url is missing');
});
test('`gbrain think` on postgres-keyed thin client never demands database_url', async () => {
// Topology 2 as shipped: engine postgres, remote_mcp set, no database_url.
// Today's connectEngine() throws `database_url is missing` before
// runThinkCli's isThinClient branch. Remote call to brain-host.example
// will fail (unreachable) — irrelevant. Pin that connectEngine did not run.
seedThinClientConfig(tmp, { engine: 'postgres' });
const r = await run(['think', 'What do we know?']);
expect(r.stdout + r.stderr).not.toContain('database_url is missing');
expect(r.stdout + r.stderr).not.toContain('No brain configured');
});
});