Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runCli } from './helpers/cli-spawn.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
import { LEGACY_EMBEDDING_CONFIG } from './helpers/legacy-embedding-config.ts';
import { installFixtureChunks } from './helpers/page-projection.ts';
import { asOwner } from './helpers/owner-tier.ts';
import { ERROR_SCHEMA } from '../src/core/verbs.ts';
import { validateAgainstSchema } from '../src/core/verbs/conformance.ts';
const response = { facts: [], results: [], total: 0, protocol_version: 1,
budget_tokens: 0, budget_used: 0, dropped_count: 0,
budget_packing: { policy: 'query_first', applied: true, reason: 'budget_below_one',
facts: { candidates: 0, kept: 0, dropped: 0, used: 0 },
results: { candidates: 0, kept: 0, dropped: 0, used: 0 } } };
async function thinCall(engine: 'postgres' | 'pglite', args: string[], options: {
source?: string; dispatch?: (args: Record<string, unknown>) => Promise<unknown>;
} = {}) {
const calls: Array<{ name?: string; arguments?: Record<string, unknown> }> = [];
const server = Bun.serve({ hostname: '127.0.0.1', port: 0, async fetch(request): Promise<Response> {
const path = new URL(request.url).pathname;
const base = `http://127.0.0.1:${server.port}`;
if (path === '/.well-known/oauth-authorization-server') return Response.json({ issuer: base, token_endpoint: `${base}/token` });
if (path === '/token') return Response.json({ access_token: 'fixture', token_type: 'bearer', expires_in: 3600, scope: 'read' });
if (path !== '/mcp' || request.method !== 'POST') return new Response(null, { status: 405 });
const body = await request.json() as { id?: number; method: string;
params?: { protocolVersion?: string; name?: string; arguments?: Record<string, unknown> } };
if (body.id === undefined) return new Response(null, { status: 202 });
if (body.method === 'initialize') return Response.json({ jsonrpc: '2.0', id: body.id, result: {
protocolVersion: body.params?.protocolVersion, capabilities: { tools: {} }, serverInfo: { name: 'fixture', version: '1' },
} });
if (body.method !== 'tools/call') return new Response(null, { status: 400 });
calls.push({ name: body.params?.name, arguments: body.params?.arguments });
return Response.json({ jsonrpc: '2.0', id: body.id,
result: options.dispatch ? await options.dispatch(body.params?.arguments ?? {})
: { content: [{ type: 'text', text: JSON.stringify(response) }] } });
} });
const home = mkdtempSync(join(tmpdir(), 'gbrain-recall-thin-cli-'));
const brain = join(home, '.gbrain');
const databasePath = join(brain, 'brain.pglite');
mkdirSync(brain);
writeFileSync(join(brain, 'config.json'), JSON.stringify({ engine, database_path: databasePath, remote_mcp: {
issuer_url: `http://127.0.0.1:${server.port}`, mcp_url: `http://127.0.0.1:${server.port}/mcp`,
oauth_client_id: 'fixture', oauth_client_secret: 'fixture',
} }));
try {
const result = await runCli(['recall', ...args], { home, cwd: home, timeoutMs: 20_000, env: {
GBRAIN_SOURCE: options.source, GBRAIN_BRAIN_ID: 'host', GBRAIN_NO_BANNER: '1', GBRAIN_MODEL_DISCOVERY: 'off',
ANTHROPIC_API_KEY: undefined, OPENAI_API_KEY: undefined, VOYAGE_API_KEY: undefined,
} });
return { ...result, calls, localStoreCreated: existsSync(databasePath) };
} finally {
await server.stop(true);
rmSync(home, { recursive: true, force: true });
}
}
for (const engine of ['postgres', 'pglite'] as const) {
test(`${engine}-shaped thin CLI forwards opted-in recall before opening a local database`, async () => {
const policy = engine === 'postgres' ? ['--budget-policy', 'query_first'] : ['--budget-policy=query_first'];
const result = await thinCall(engine, ['topics/example', '--query', 'zebra telescope', '--budget-tokens', '0.5',
...policy, '--session-id', 'session-example', '--since', '2026-09-01', '--grep', 'needle',
'--supersessions', '--include-expired', '--pending', '--source', 'example', '--json']);
expect({ code: result.exitCode, stderr: result.stderr }).toMatchObject({ code: 0 });
expect(JSON.parse(result.stdout)).toEqual(response);
expect(result.calls).toEqual([{ name: 'recall', arguments: {
entity: 'topics/example', query: 'zebra telescope', budget_tokens: 0.5, budget_policy: 'query_first',
session_id: 'session-example', since: '2026-09-01T00:00:00.000Z', grep: 'needle',
supersessions: true, include_expired: true, include_pending: true, source_id: 'example', limit: 50,
} }]);
expect(result.localStoreCreated).toBe(false);
expect(result.stdout + result.stderr).not.toContain('Setting up brain schema');
});
}
test.each([
['--budget-policy', '--json'],
['--budget-policy=unknown', '--json'],
['--budget-policy', 'query_first', '--watch', '10', '--json'],
].map(args => [args]))('thin CLI rejects invalid policy requests before local or remote work: %j', async args => {
const result = await thinCall('postgres', args);
expect(result.exitCode).toBe(1);
expect(JSON.parse(result.stdout)).toMatchObject({ error: 'invalid_params' });
expect(result.calls).toEqual([]);
expect(result.localStoreCreated).toBe(false);
});
test('a query value spelling the policy flag does not opt a legacy thin call into new routing', async () => {
const result = await thinCall('postgres', ['--query', '--budget-policy', '--json']);
expect(result.exitCode).toBe(1);
expect(result.stderr).toContain('`gbrain recall` is not routable');
expect(result.calls).toEqual([]);
expect(result.localStoreCreated).toBe(false);
});
test('explicit thin brain selection fails before remote or local work', async () => {
const result = await thinCall('postgres', ['--budget-policy', 'query_first', '--brain', 'unregistered-example', '--json']);
expect(result.exitCode).toBe(2);
expect(result.stderr).toContain('--brain is not supported on a thin-client install');
expect(result.calls).toEqual([]);
expect(result.localStoreCreated).toBe(false);
});
test.each(['query_first', 'facts_first'])('thin %s JSON preserves a remote read error envelope without a mutation receipt', async policy => {
const error = { error: 'unavailable', message: 'Synthetic service unavailable', suggestion: 'Retry this read later.',
detail: 'fixture_read_failure', docs: 'https://example.test/help', protocol_version: 1 };
const result = await thinCall('postgres', ['--budget-policy', policy, '--json'], {
dispatch: async () => ({ isError: true, content: [{ type: 'text', text: JSON.stringify(error) }] }),
});
expect(result.exitCode).toBe(1);
// Agent contract v1: legacy keys preserved verbatim; the client adds the canonical `code`.
expect(JSON.parse(result.stdout)).toEqual({ ...error, code: 'unavailable' });
expect(validateAgainstSchema(JSON.parse(result.stdout), ERROR_SCHEMA)).toEqual([]);
expect(result.stderr).toContain('Synthetic service unavailable');
expect(result.calls).toHaveLength(1);
expect(result.localStoreCreated).toBe(false);
});
test('thin policy renders an unstructured remote failure as a stamped unavailable error', async () => {
const result = await thinCall('postgres', ['--budget-policy', 'query_first', '--json'], {
dispatch: async () => ({ isError: true, content: [{ type: 'text', text: 'Synthetic unstructured failure' }] }),
});
expect(result.exitCode).toBe(1);
const error = JSON.parse(result.stdout);
expect(error).toMatchObject({ error: 'unavailable', protocol_version: 1 });
expect(error.message).toContain('Synthetic unstructured failure');
expect(error.suggestion).toBeTruthy();
expect(validateAgainstSchema(error, ERROR_SCHEMA)).toEqual([]);
expect(result.localStoreCreated).toBe(false);
});
describe('actual remote source selection', () => {
let remote: PGLiteEngine;
beforeAll(async () => {
configureGateway({ ...LEGACY_EMBEDDING_CONFIG, env: {} });
remote = new PGLiteEngine();
await remote.connect({});
await remote.initSchema();
});
afterAll(async () => {
await remote.disconnect();
resetGateway();
});
test('thin recall actually narrows both evidence arms on the remote dispatcher', async () => {
await remote.setConfig('search.track_retrieval', 'false');
await remote.setConfig('mcp.strict_params', 'reject');
for (const source of ['default', 'peer', 'denied']) {
if (source !== 'default') await remote.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [source]);
const text = `Telescope evidence from ${source}.`;
await asOwner(remote, async tx => {
await tx.putPage('notes/telescope', { type: 'note', title: 'Telescope', compiled_truth: text }, { sourceId: source });
await installFixtureChunks(tx, 'notes/telescope', [{ chunk_index: 0, chunk_source: 'compiled_truth', chunk_text: text }], { sourceId: source });
await tx.insertFact({ fact: text, source: 'synthetic', visibility: 'world' }, { source_id: source });
});
}
await remote.executeRaw("INSERT INTO sources(id,name,archived) VALUES('archived-example','archived-example',true)");
const dispatch = (args: Record<string, unknown>) => dispatchToolCall(remote, 'recall', args, {
remote: true, sourceId: 'default', auth: { allowedSources: ['default', 'peer', 'ghost-example', 'archived-example'] }, config: {},
} as never);
const cases = [
{ flags: [], ambient: undefined, expected: ['default', 'peer'], wire: undefined },
{ flags: ['--source', 'default'], ambient: 'peer', expected: ['default'], wire: 'default' },
{ flags: ['--source', 'peer'], ambient: undefined, expected: ['peer'], wire: 'peer' },
{ flags: ['--source-id=peer'], ambient: undefined, expected: ['peer'], wire: 'peer' },
{ flags: [], ambient: 'peer', expected: ['peer'], wire: 'peer' },
];
for (const entry of cases) {
const result = await thinCall('postgres', ['--query', 'telescope', '--budget-policy', 'query_first', '--budget-tokens', '1000', '--json', ...entry.flags], { dispatch, source: entry.ambient });
expect({ code: result.exitCode, stderr: result.stderr }).toMatchObject({ code: 0 });
const body = JSON.parse(result.stdout);
const expected = entry.expected.map(source => `Telescope evidence from ${source}.`).sort();
expect(body.facts.map((row: any) => row.fact).sort()).toEqual(expected);
expect(body.results.map((row: any) => row.chunk).sort()).toEqual(expected);
expect(result.calls[0].arguments?.source_id).toBe(entry.wire);
expect(result.localStoreCreated).toBe(false);
}
const denied = await thinCall('postgres', ['--budget-policy', 'query_first', '--source', 'denied', '--json'], { dispatch });
expect(denied.exitCode).not.toBe(0);
expect(JSON.parse(denied.stdout)).toMatchObject({ error: 'scope_denied', detail: 'permission_denied', protocol_version: 1 });
expect(validateAgainstSchema(JSON.parse(denied.stdout), ERROR_SCHEMA)).toEqual([]);
expect(denied.stdout + denied.stderr).not.toContain('Telescope evidence from denied.');
expect(denied.localStoreCreated).toBe(false);
const allAmbient = await thinCall('postgres', ['--budget-policy', 'query_first', '--json'], { dispatch, source: '__all__' });
expect(allAmbient.exitCode).not.toBe(0);
expect(JSON.parse(allAmbient.stdout)).toMatchObject({ error: 'invalid_params', protocol_version: 1 });
expect(validateAgainstSchema(JSON.parse(allAmbient.stdout), ERROR_SCHEMA)).toEqual([]);
expect(allAmbient.stdout + allAmbient.stderr).toContain('invalid_params');
expect(allAmbient.stdout + allAmbient.stderr).not.toContain('Telescope evidence');
expect(allAmbient.localStoreCreated).toBe(false);
const allExplicit = await thinCall('postgres', ['--budget-policy', 'query_first', '--source', '__all__', '--json'], { dispatch });
expect(allExplicit.exitCode).not.toBe(0);
expect(JSON.parse(allExplicit.stdout)).toMatchObject({ error: 'invalid_params', protocol_version: 1 });
expect(validateAgainstSchema(JSON.parse(allExplicit.stdout), ERROR_SCHEMA)).toEqual([]);
expect(allExplicit.calls).toEqual([]);
expect(allExplicit.localStoreCreated).toBe(false);
for (const source of ['ghost-example', 'archived-example']) {
const missing = await thinCall('postgres', ['--budget-policy', 'query_first', '--source', source, '--json'], { dispatch });
expect(missing.exitCode).not.toBe(0);
const error = JSON.parse(missing.stdout);
expect(error).toMatchObject({ error: 'not_found', detail: 'unknown_source', protocol_version: 1 });
expect(validateAgainstSchema(error, ERROR_SCHEMA)).toEqual([]);
expect(missing.stdout + missing.stderr).not.toContain('Telescope evidence');
expect(missing.localStoreCreated).toBe(false);
}
for (const source of ['Bad Source', '__all__']) {
const invalid = await thinCall('postgres', ['--budget-policy', 'query_first', '--json'], { dispatch, source });
expect(invalid.exitCode).not.toBe(0);
const error = JSON.parse(invalid.stdout);
expect(error).toMatchObject({ error: 'invalid_params', protocol_version: 1 });
expect(validateAgainstSchema(error, ERROR_SCHEMA)).toEqual([]);
expect(invalid.calls).toEqual([]);
expect(invalid.localStoreCreated).toBe(false);
}
}, 90_000);
test('#6938 thin entity + session recall keeps the intersection before the remote LIMIT', async () => {
const entity = 'people/thin-session-example';
for (const [fact, session, date] of [
['older thin session match', 'wanted-session', '2020-01-01'],
['newer thin unrelated fact', 'other-session', '2024-01-01'],
]) {
await asOwner(remote, tx => tx.insertFact({ fact, source: 'synthetic', entity_slug: entity,
source_session: session, valid_from: new Date(date), visibility: 'world' }, { source_id: 'default' }));
}
const dispatch = (args: Record<string, unknown>) => dispatchToolCall(remote, 'recall', args, {
remote: true, sourceId: 'default', config: { engine: 'pglite' },
});
for (const session of ['wanted-session', 'absent-session']) {
const result = await thinCall('postgres', [entity, '--session', session, '--limit', '1',
'--budget-policy', 'facts_first', '--source', 'default', '--json'], { dispatch });
expect({ code: result.exitCode, stderr: result.stderr }).toMatchObject({ code: 0 });
expect(JSON.parse(result.stdout).facts.map((f: { fact: string }) => f.fact))
.toEqual(session === 'wanted-session' ? ['older thin session match'] : []);
expect(result.calls).toHaveLength(1);
expect(result.calls[0].arguments).toMatchObject({ entity, session_id: session, limit: 1 });
expect(result.localStoreCreated).toBe(false);
}
}, 60_000);
test('#6945 thin --since-last-run warns to raise --limit when the window is full, and only then', async () => {
const entity = 'people/thin-window-example';
for (const fact of ['thin window fact one', 'thin window fact two', 'thin window fact three']) {
await remote.insertFact({ fact, source: 'synthetic', entity_slug: entity, visibility: 'world' }, { source_id: 'default' });
}
const dispatch = (args: Record<string, unknown>) => dispatchToolCall(remote, 'recall', args, {
remote: true, sourceId: 'default', config: { engine: 'pglite' },
});
const full = await thinCall('postgres', [entity, '--since-last-run', '--limit', '2', '--source', 'default', '--json'], { dispatch });
expect({ code: full.exitCode, stderr: full.stderr }).toMatchObject({ code: 0 });
expect(JSON.parse(full.stdout).facts).toHaveLength(2);
expect(full.stderr).toContain('2 facts filled the --limit window; older facts since the last run may not be shown');
expect(full.stderr).toContain('(thin-client recall cannot page the cursor). Re-run with a larger --limit.');
expect(full.localStoreCreated).toBe(false);
const roomy = await thinCall('postgres', [entity, '--since-last-run', '--limit', '5', '--source', 'default', '--json'], { dispatch });
expect({ code: roomy.exitCode, stderr: roomy.stderr }).toMatchObject({ code: 0 });
expect(JSON.parse(roomy.stdout).facts).toHaveLength(3);
expect(roomy.stderr).not.toContain('filled the --limit window');
}, 60_000);
});