Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { once } from 'node:events';
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { OperationError } from '../src/core/ops/contract.ts';
import { runPersistenceAdministration } from '../src/core/persistence/administration.ts';
import { createPersistenceIpcProvider } from '../src/core/persistence/provider.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { readLocalWriter, registerLocalWriter, revokeLocalWriter, verifyLocalWriter, persistenceHome } from '../src/core/persistence/identity.ts';
import { startPersistenceIpcServer, requestPersistenceAdministration, requestPersistenceCapabilities, persistenceSocketPathForConfig } from '../src/core/persistence/ipc.ts';
import { acquireLock, releaseLock } from '../src/core/pglite-lock.ts';
import { parsePersistenceAdminArgs } from '../src/commands/persistence-admin.ts';
import { withEnv } from './helpers/with-env.ts';
import { reviewedWriterIntent } from './helpers/writer-admin-intent.ts';
import { caught, envelopeFor, expectFunnelSuggestions } from './helpers/agent-envelope.ts';
let engine: PGLiteEngine;
let brainId: string;
beforeAll(async () => {
engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema();
[ { brain_id: brainId } ] = await engine.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1');
}, 60_000);
afterAll(async () => { await disposePersistenceConsumer(engine); await engine.disconnect(); });
/**
* #5332: a spawned CLI that never exits (or whose pipes a grandchild holds
* open) must FAIL this file with its teardown run, never park it. The whole
* drain races one timer; on expiry the child is SIGKILLed and the await
* rejects with the argv, so the caller's finally still closes the IPC server
* and releases the lock.
*/
async function spawnCliBounded(args: string[], cwd: string, wallMs: number) {
const child = Bun.spawn([process.execPath, join(import.meta.dir, '../src/cli.ts'), ...args], {
cwd, env: { ...process.env, GBRAIN_NO_BANNER: '1', GBRAIN_BACKUP_CHECK: '0' }, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe',
});
let timer: ReturnType<typeof setTimeout> | undefined;
const expiry = new Promise<never>((_, reject) => {
timer = setTimeout(() => {
try { child.kill(9); } catch { /* already exited */ }
reject(new Error(`gbrain ${args.join(' ')} did not exit within ${wallMs}ms (#5332)`));
}, wallMs);
});
try {
const [stdout, stderr, code] = await Promise.race([
Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]),
expiry,
]);
return { stdout, stderr, code };
} finally { clearTimeout(timer); }
}
async function isolated<T>(run: (dir: string) => Promise<T>): Promise<T> {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-admin-test-'));
try {
return await withEnv({ GBRAIN_HOME: dir, GBRAIN_BRAIN_ID: 'host', GBRAIN_SOURCE: undefined, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, () => run(dir));
} finally { await disposePersistenceConsumer(engine); rmSync(dir, { force: true, recursive: true }); }
}
describe('local writer administration', () => {
test('registration grants validate and replacement revokes the old credential without returning secrets', () => isolated(async () => {
const first = await runPersistenceAdministration(engine, 'local_writer_register', { lane: 'cli' });
const old = await readLocalWriter(engine, 'cli');
await expect(runPersistenceAdministration(engine, 'local_writer_register', { lane: 'cli', allowed_operations: ['get_page'] })).rejects.toMatchObject({ code: 'writer_regrant_required' });
const second = await runPersistenceAdministration(engine, 'local_writer_register', { lane: 'cli', replace: true, allowed_operations: ['get_page'] });
expect(second.id).not.toBe(first.id);
await expect(verifyLocalWriter(engine, old)).rejects.toMatchObject({ code: 'permission_denied' });
expect((await readLocalWriter(engine, 'cli')).id).toBe(second.id as string);
const listed = await runPersistenceAdministration(engine, 'local_writer_list', { limit: 1000 });
expect(JSON.stringify([first, second, listed])).not.toContain(old.credential);
expect(JSON.stringify(listed)).not.toContain('credential_hash');
const backup = readdirSync(persistenceHome()).find(name => name.includes('.cli.json.revoked.'))!;
expect(JSON.parse(readFileSync(join(persistenceHome(), backup), 'utf8')).id).toBe(old.id);
await expect(runPersistenceAdministration(engine, 'local_writer_register', { lane: 'stdio', scopes: ['admin'] })).rejects.toMatchObject({ code: 'invalid_params' });
await expect(runPersistenceAdministration(engine, 'local_writer_register', { lane: 'stdio', source_ids: ['missing-source'] })).rejects.toMatchObject({ code: 'invalid_params' });
await expect(runPersistenceAdministration(engine, 'local_writer_register', { lane: 'stdio', allowed_operations: ['writer_status'] })).rejects.toMatchObject({ code: 'invalid_params' });
}));
test('a failed replacement transaction preserves the original active credential file and removes its pending file', () => isolated(async () => {
const old = await registerLocalWriter(engine, 'cli');
const proxy = new Proxy(engine, { get(target, property) {
if (property === 'transaction') return (fn: (tx: BrainEngine) => Promise<unknown>) => target.transaction(tx => fn(new Proxy(tx, {
get(target, key) {
if (key === 'executeRaw') return (sql: string, params: unknown[]) => {
if (sql.includes('INSERT INTO persistence_local_writers')) throw new OperationError('storage_error', 'Simulated registration failure.');
return target.executeRaw(sql, params);
};
const value = Reflect.get(target, key); return typeof value === 'function' ? value.bind(target) : value;
},
})));
const value = Reflect.get(target, property); return typeof value === 'function' ? value.bind(target) : value;
} }) as BrainEngine;
await expect(registerLocalWriter(proxy, 'cli', undefined, true)).rejects.toMatchObject({ code: 'storage_error' });
expect(await readLocalWriter(engine, 'cli')).toEqual(old);
expect((await verifyLocalWriter(engine, old)).principal.id).toBe(old.id);
expect(readdirSync(persistenceHome()).filter(name => name.includes('.pending.'))).toEqual([]);
}));
test('concurrent explicit replacements serialize and the published credential is the only live successor', () => isolated(async () => {
const old = await registerLocalWriter(engine, 'cli');
const successors = await Promise.all([registerLocalWriter(engine, 'cli', undefined, true), registerLocalWriter(engine, 'cli', undefined, true)]);
const active = await readLocalWriter(engine, 'cli');
expect(successors.map(value => value.id)).toContain(active.id);
const rows = await engine.executeRaw('SELECT id FROM persistence_local_writers WHERE id=ANY($1::uuid[]) AND revoked_at IS NULL', [[old.id, ...successors.map(value => value.id)]]);
expect(rows).toEqual([{ id: active.id }]);
}));
test('claim and transfer require matching bytes and epoch; a real native probe acquires and releases', () => isolated(async dir => {
const sourceId = `admin-${randomUUID().slice(0, 8)}`;
const initial = join(dir, 'initial'), successor = join(dir, 'successor');
mkdirSync(initial); mkdirSync(successor);
writeFileSync(join(initial, 'page.md'), 'canonical bytes');
writeFileSync(join(successor, 'page.md'), 'different bytes');
await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, initial]);
const claim = await runPersistenceAdministration(engine, 'writer_claim', { source_id: sourceId, path: initial, ...await reviewedWriterIntent(engine, 'writer_claim') });
expect(claim.claimed).toBe(true);
const prepared = await runPersistenceAdministration(engine, 'writer_transfer_prepare', { source_id: sourceId, ...await reviewedWriterIntent(engine, 'writer_transfer_prepare') }) as any;
await expect(runPersistenceAdministration(engine, 'writer_transfer_accept', {
source_id: sourceId, path: successor, expected_epoch: prepared.owner_epoch, manifest: prepared.manifest.digest,
...await reviewedWriterIntent(engine, 'writer_transfer_accept'),
})).rejects.toMatchObject({ code: 'writer_manifest_mismatch' });
writeFileSync(join(successor, 'page.md'), 'canonical bytes');
await expect(runPersistenceAdministration(engine, 'writer_transfer_accept', {
source_id: sourceId, path: successor, expected_epoch: '99', manifest: prepared.manifest.digest,
...await reviewedWriterIntent(engine, 'writer_transfer_accept'),
})).rejects.toMatchObject({ code: 'writer_transfer_conflict' });
const accepted = await runPersistenceAdministration(engine, 'writer_transfer_accept', {
source_id: sourceId, path: successor, expected_epoch: prepared.owner_epoch, manifest: prepared.manifest.digest,
...await reviewedWriterIntent(engine, 'writer_transfer_accept'),
}) as any;
expect(accepted.binding.local_path).toBe(successor);
expect(String(accepted.binding.owner_epoch)).toBe('2');
const status = await runPersistenceAdministration(engine, 'writer_status', { probe: true });
expect(status.native_lock).toMatchObject({ napi: 3, acquired: true, released: true });
}));
test('private IPC rejects stdio, lane forgery, revoked credentials, and wire trust assertions', () => isolated(async dir => {
const config = { engine: 'pglite' as const, database_path: join(dir, 'db') };
const provider = await createPersistenceIpcProvider(engine, config);
const cli = await readLocalWriter(engine, 'cli'), stdio = await readLocalWriter(engine, 'stdio');
const binding = (await startPersistenceIpcServer(join(dir, 'administration.sock'), provider))!;
const request = { version: 1 as const, kind: 'administration' as const, brain_id: brainId,
operation: 'local_writer_list' as const, params: {}, registration: cli };
try {
expect((await requestPersistenceCapabilities(binding.socketPath)).administration).toContain('writer_status');
expect(await requestPersistenceAdministration(binding.socketPath, request)).toHaveProperty('writers');
await expect(requestPersistenceAdministration(binding.socketPath, { ...request, registration: stdio })).rejects.toMatchObject({ code: 'invalid_params' });
await expect(requestPersistenceAdministration(binding.socketPath, { ...request, registration: { ...stdio, lane: 'cli' } })).rejects.toMatchObject({ code: 'permission_denied' });
await expect(requestPersistenceAdministration(binding.socketPath, { ...request, remote: false } as any)).rejects.toMatchObject({ code: 'invalid_params' });
await expect(requestPersistenceAdministration(binding.socketPath, { ...request, params: { remote: false } })).rejects.toMatchObject({ code: 'invalid_params' });
await revokeLocalWriter(engine, cli.id);
await expect(requestPersistenceAdministration(binding.socketPath, request)).rejects.toMatchObject({ code: 'permission_denied' });
await expect(provider.administer!({ ...request, operation: 'local_writer_register', params: { lane: 'cli', replace: true } })).rejects.toMatchObject({ code: 'permission_denied' });
} finally { const closed = once(binding.server, 'close'); binding.close(); await closed; }
}));
test('actual CLI status/probe, registrations and dry-run claim delegate while PGLite ownership is held', () => isolated(async dir => {
const config = { engine: 'pglite' as const, database_path: join(dir, 'db') };
mkdirSync(config.database_path);
const lock = await acquireLock(config.database_path);
const metadata = lock.lockPath ?? join(config.database_path, '.gbrain-lock', 'lock');
writeFileSync(metadata, JSON.stringify({ ...JSON.parse(readFileSync(metadata, 'utf8')), subcommand: 'serve' }));
mkdirSync(join(dir, '.gbrain'), { recursive: true });
writeFileSync(join(dir, '.gbrain', 'config.json'), JSON.stringify(config));
const provider = await createPersistenceIpcProvider(engine, config);
const binding = (await startPersistenceIpcServer(persistenceSocketPathForConfig(config)!, provider))!;
try {
for (const args of [
['sources', 'writer', 'status', '--probe', '--json'],
['auth', 'local-writer', 'list', '--json'],
['sources', 'writer', 'claim', 'default', '--path', dir, '--dry-run', '--json'],
]) {
const { stdout, stderr, code } = await spawnCliBounded(args, dir, 60_000);
expect({ code, stderr }).toMatchObject({ code: 0 });
const result = JSON.parse(stdout);
if (args.includes('--probe')) expect(result.native_lock).toMatchObject({ acquired: true, released: true });
else if (args.includes('--dry-run')) expect(result.dry_run).toBe(true);
else expect(result).toHaveProperty('writers');
}
} finally { const closed = once(binding.server, 'close'); binding.close(); await closed; await releaseLock(lock); }
}));
test('the spawned-CLI bound fails with teardown instead of parking (forced 1 ms probe, #5332)', () => isolated(async dir => {
const config = { engine: 'pglite' as const, database_path: join(dir, 'db') };
mkdirSync(config.database_path);
const lock = await acquireLock(config.database_path);
try {
await expect(spawnCliBounded(['sources', 'writer', 'status', '--json'], dir, 1)).rejects.toThrow(/did not exit within 1ms \(#5332\)/);
} finally { await releaseLock(lock); }
}));
test('CLI parser preserves exact grant/epoch intent and rejects malformed flag combinations', () => {
expect(parsePersistenceAdminArgs('local-writer', ['register', 'stdio', '--allowed-operations=', '--source-ids', 'default', '--replace'])).toMatchObject({
operation: 'local_writer_register', params: { lane: 'stdio', allowed_operations: [], source_ids: ['default'], replace: true },
});
expect(parsePersistenceAdminArgs('writer', ['transfer', 'accept', 'default', '--expected-epoch', '42', '--manifest', 'a'.repeat(64)])).toMatchObject({
operation: 'writer_transfer_accept', params: { source_id: 'default', expected_epoch: '42' },
});
expect(() => parsePersistenceAdminArgs('writer', ['claim', 'default', '--source', 'other'])).toThrow('Specify the source once');
expect(() => parsePersistenceAdminArgs('writer', ['status', '--probe=false'])).toThrow('does not accept a value');
expect(() => parsePersistenceAdminArgs('writer', ['transfer', 'steal', 'default'])).toThrow('prepare or accept');
});
});
describe('administration refusals name their own next step', () => {
test('every invalid() and uuid() call site carries a site-specific suggestion', () => {
expectFunnelSuggestions('src/core/persistence/administration.ts', 'invalid', 15);
expectFunnelSuggestions('src/core/persistence/administration.ts', 'uuid', 4);
expectFunnelSuggestions('src/commands/persistence-admin.ts', 'invalid', 8);
});
test('a grant naming an inactive source names it and reads the source list', () => isolated(async () => {
const env = envelopeFor(await caught(() => runPersistenceAdministration(engine, 'local_writer_register', { lane: 'stdio', source_ids: ['missing-source'] })));
expect(env).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'sources', 'list', '--json'], next: 'run' } });
expect(env.suggestion).toContain('missing-source');
}));
test('a grant outside its scope names the operations to remove', () => isolated(async () => {
const env = envelopeFor(await caught(() => runPersistenceAdministration(engine, 'local_writer_register', { lane: 'stdio', allowed_operations: ['writer_status'] })));
expect(env.code).toBe('invalid_params');
expect(env.suggestion).toContain('Remove writer_status from --allowed-operations');
}));
test('activation without --confirm-quiesced points at the reviewed status', () => isolated(async () => {
const env = envelopeFor(await caught(() => runPersistenceAdministration(engine, 'writer_activate', {})));
expect(env).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'sources', 'writer', 'status', '--json'], next: 'run' } });
expect(env.suggestion).toContain('--admin-intent writer_activate');
}));
test('deactivate with a source previews the brain-wide change instead', () => isolated(async () => {
const env = envelopeFor(await caught(() => runPersistenceAdministration(engine, 'writer_deactivate', { source_id: 'default' })));
expect(env).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'sources', 'writer', 'deactivate', '--dry-run', '--json'], next: 'run' } });
}));
test('revoke with a malformed id reads the writer list; a non-boolean flag names its CLI form', () => isolated(async () => {
const revoke = envelopeFor(await caught(() => runPersistenceAdministration(engine, 'local_writer_revoke', { id: 'nope' })));
expect(revoke).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'auth', 'local-writer', 'list', '--json'], next: 'run' } });
const dryRun = envelopeFor(await caught(() => runPersistenceAdministration(engine, 'local_writer_revoke', { id: 'nope', dry_run: 'yes' })));
expect(dryRun.suggestion).toContain('--dry-run');
}));
test('CLI usage refusals name the exact usage and offer the group help', async () => {
const duplicate = envelopeFor(await caught(() => parsePersistenceAdminArgs('writer', ['claim', 'default', '--source', 'other'])));
expect(duplicate).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'sources', 'writer', '--help'], next: 'run' } });
expect(duplicate.suggestion).toContain('default and other');
const unknown = envelopeFor(await caught(() => parsePersistenceAdminArgs('local-writer', ['list', '--force'])));
expect(unknown).toMatchObject({ fix: { argv: ['gbrain', 'auth', 'local-writer', '--help'] } });
expect(unknown.suggestion).toContain('Remove --force');
});
});