Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { afterEach, describe, expect, test } from 'bun:test';
import net, { type Server } from 'node:net';
import { once } from 'node:events';
import { mkdtempSync, rmSync, statSync, writeFileSync, readFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { OperationError } from '../src/core/ops/contract.ts';
import { printRefreshOutcome } from '../src/commands/sources-refresh.ts';
import { _resetCliExitVerdictForTests } from '../src/core/cli-force-exit.ts';
import {
PERSISTENCE_IPC_MAX_BYTES, PersistenceIpcTransportError,
persistenceSocketPathForConfig, requestPersistenceAdministration, requestPersistenceCapabilities, requestPersistenceOperation,
startPersistenceIpcServer, type PersistenceIpcBinding, type PersistenceIpcRequest,
} from '../src/core/persistence/ipc.ts';
const BRAIN = '10000000-0000-4000-8000-000000000001';
const ID = '20000000-0000-4000-8000-000000000001';
const REGISTRATION = { id: '30000000-0000-4000-8000-000000000001', credential: 'a'.repeat(64), lane: 'cli' as const };
const dirs: string[] = [];
const bindings: PersistenceIpcBinding[] = [];
const rawServers: Server[] = [];
function socketPath() {
const dir = mkdtempSync(join(tmpdir(), 'gb-write-ipc-'));
dirs.push(dir);
return join(dir, 'write.sock');
}
function request(params: Record<string, unknown> = {}): PersistenceIpcRequest {
return { version: 1, kind: 'operation', brain_id: BRAIN, operation: 'put_page',
params: { request_id: ID, slug: 'test/page', content: 'hello', ...params },
registration: REGISTRATION, routing: { source: null, cwd: tmpdir() } };
}
async function bind(path: string, dispatch: (request: PersistenceIpcRequest) => Promise<unknown>) {
const result = await startPersistenceIpcServer(path, { brainId: BRAIN, dispatch });
expect(result).not.toBeNull();
bindings.push(result!);
return result!;
}
async function rawExchange(path: string, payload: string): Promise<Record<string, any>> {
return new Promise((resolve, reject) => {
const socket = net.createConnection(path);
let result = '';
socket.once('error', reject);
socket.once('connect', () => socket.write(payload));
socket.on('data', chunk => { result += chunk.toString(); });
socket.once('end', () => { socket.destroy(); resolve(JSON.parse(result)); });
});
}
afterEach(async () => {
for (const binding of bindings.splice(0)) {
const closed = binding.server.listening ? once(binding.server, 'close') : Promise.resolve();
binding.close();
await closed;
}
for (const server of rawServers.splice(0)) {
if (server.listening) { const closed = once(server, 'close'); server.close(); await closed; }
}
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
describe('dedicated persistence IPC', () => {
test('capabilities identify the durable brain and operations; socket is private', async () => {
const path = socketPath();
await bind(path, async () => { throw new Error('Capabilities must not dispatch.'); });
const capabilities = await requestPersistenceCapabilities(path);
expect(capabilities.brain_id).toBe(BRAIN);
expect(capabilities.operations).toContain('get_write_request');
expect(capabilities.operations).toContain('fetch');
expect(capabilities.max_frame_bytes).toBe(PERSISTENCE_IPC_MAX_BYTES);
if (process.platform !== 'win32') expect(statSync(path).mode & 0o777).toBe(0o600);
expect(persistenceSocketPathForConfig({ engine: 'pglite', database_path: tmpdir() })).toBe(join(tmpdir(), '.gbrain-persistence.sock'));
});
test('preserves explicit source, client cwd, principal credential, and request ID', async () => {
const path = socketPath();
let received: PersistenceIpcRequest | undefined;
await bind(path, async value => { received = value; return { status: 'created', revision: ID }; });
const sent = request();
sent.routing.source = 'client-source';
const result = await requestPersistenceOperation(path, sent);
expect(received).toEqual(sent);
expect(result).toEqual({ status: 'created', revision: ID });
});
test('five million maximally escaped content bytes fit without truncation', async () => {
const path = socketPath();
await bind(path, async value => ({ bytes: Buffer.byteLength(value.params.content as string), tail: (value.params.content as string).slice(-1) }));
const content = '\0'.repeat(4_999_999) + 'z';
const result = await requestPersistenceOperation(path, request({ content }));
expect(result).toEqual({ bytes: 5_000_000, tail: 'z' });
});
test('oversized request refuses before delivery', async () => {
const path = socketPath();
let calls = 0;
await bind(path, async () => { calls++; return {}; });
await expect(requestPersistenceOperation(path, request({ content: 'x'.repeat(PERSISTENCE_IPC_MAX_BYTES) }))).rejects.toThrow('transport limit');
expect(calls).toBe(0);
});
test('unknown operations, forged context, wrong brain and missing IDs cannot dispatch', async () => {
const path = socketPath();
let calls = 0;
await bind(path, async () => { calls++; return {}; });
for (const malformed of [
{ ...request(), operation: 'execute_sql' },
{ ...request(), remote: false },
{ ...request(), auth: { scopes: ['admin'] } },
{ ...request(), registration: { ...REGISTRATION, principal: 'admin' } },
{ ...request(), params: { slug: 'test/page', content: 'hello' } },
{ ...request(), brain_id: '10000000-0000-4000-8000-000000000002' },
]) {
const response = await rawExchange(path, JSON.stringify(malformed) + '\n');
expect(response.ok).toBe(false);
}
expect(calls).toBe(0);
});
test('multiple frames on one connection dispatch at most once', async () => {
const path = socketPath();
let calls = 0;
await bind(path, async () => { calls++; await Bun.sleep(5); return { ok: true }; });
await rawExchange(path, (JSON.stringify(request()) + '\n').repeat(2));
expect(calls).toBe(1);
});
test('frozen pending envelopes and revision errors survive transport', async () => {
const path = socketPath();
await bind(path, async () => {
const error = new OperationError('unavailable', 'Write queued.', 'Retry the same request ID.');
error.protocolVersion = 1;
error.writeError = 'write_pending';
error.writeRequest = { request_id: ID, state: 'queued', retry_after_ms: 100 };
throw error;
});
try { await requestPersistenceOperation(path, request()); throw new Error('Expected pending error.'); }
catch (error) {
expect(error).toBeInstanceOf(OperationError);
expect((error as OperationError).toJSON()).toMatchObject({ error: 'unavailable', protocol_version: 1,
write_error: 'write_pending', write_request: { request_id: ID, state: 'queued' } });
}
});
test('private driver failures are not reflected', async () => {
const path = socketPath();
await bind(path, async () => { throw new Error(`secret=${REGISTRATION.credential}`); });
try { await requestPersistenceOperation(path, request()); throw new Error('Expected error.'); }
catch (error) {
expect(error).toBeInstanceOf(OperationError);
expect((error as Error).message).not.toContain(REGISTRATION.credential);
}
});
test('optional safe health survives IPC without private nested fields', async () => {
const path = socketPath();
const diagnostic = { age_ms: 120000, assessment: 'stalled' as const,
reason: 'cause_unknown' as const, next_action: 'inspect_owner' as const };
await bind(path, async () => {
const error = new OperationError('write_pending', 'Still pending.');
error.writeRequest = { request_id: ID, state: 'queued', retry_after_ms: 30000,
diagnostic: { ...diagnostic, ...{ predecessor_id: 'PRIVATE_PREDECESSOR' } } };
throw error;
});
try { await requestPersistenceOperation(path, request()); throw new Error('Expected pending error.'); }
catch (error) {
const body = (error as OperationError).toJSON();
expect(body).toMatchObject({ write_request: { request_id: ID, diagnostic } });
expect(JSON.stringify(body)).not.toContain('PRIVATE_PREDECESSOR');
}
});
test('lost acknowledgement is unknown, keeps original ID, and never auto-retries', async () => {
const path = socketPath();
let calls = 0;
const server = net.createServer(socket => {
socket.once('data', () => { calls++; socket.destroy(); });
});
rawServers.push(server);
server.listen(path);
await once(server, 'listening');
try { await requestPersistenceOperation(path, request()); throw new Error('Expected lost response.'); }
catch (error) {
expect(error).toBeInstanceOf(PersistenceIpcTransportError);
expect((error as PersistenceIpcTransportError).toJSON()).toMatchObject({ request_id: ID, submission_status: 'unknown' });
expect((error as PersistenceIpcTransportError).toJSON()).not.toHaveProperty('write_request');
}
expect(calls).toBe(1);
});
test('timeout does not abort work already dispatched', async () => {
const path = socketPath();
let finish!: () => void;
const gate = new Promise<void>(resolve => { finish = resolve; });
let completed = false;
await bind(path, async () => { await gate; completed = true; return {}; });
await expect(requestPersistenceOperation(path, request(), 30)).rejects.toMatchObject({ sent: true, requestId: ID });
finish();
await Bun.sleep(5);
expect(completed).toBe(true);
});
test('live owners are preserved and close is idempotent', async () => {
const path = socketPath();
const first = await bind(path, async () => ({ owner: 'first' }));
const second = await startPersistenceIpcServer(path, { brainId: BRAIN, dispatch: async () => ({ owner: 'second' }) });
expect(second).toBeNull();
expect(await requestPersistenceOperation(path, request())).toEqual({ owner: 'first' });
const closed = once(first.server, 'close');
first.close(); first.close();
await closed;
await bind(path, async () => ({ owner: 'next' }));
expect(await requestPersistenceOperation(path, request())).toEqual({ owner: 'next' });
});
test('ordinary files at the discovery path are never removed', async () => {
const path = socketPath();
writeFileSync(path, 'keep');
await expect(startPersistenceIpcServer(path, { brainId: BRAIN, dispatch: async () => ({}) })).rejects.toThrow('not a socket');
expect(readFileSync(path, 'utf8')).toBe('keep');
});
test('#7707, #8130: a refusal\'s structured fix, why and reason survive the owner socket, so a delegated sources refresh prints the direct path\'s v1 fix', async () => {
// Value: protects=a refusal delegated to a resident owner keeps its structured fix (argv, actor, ask_user) instead of falling back to the
// prose suggestion; fails_when=remoteOperationError drops `fix`; why_new=test 4e reads the direct path only; seam=an owner whose
// administration throws the refusal; no_claim=a real resident refresh.
const path = socketPath();
const refusal = () => {
const error = new OperationError('refresh_diverged', 'The checkout HEAD is not an ancestor of origin/main.', 'Publish the local commits first.');
error.fix = { argv: ['gbrain', 'git', 'commit-push', '--push-only', '--keep-checkout', '--path', '/tmp/brain-example', '--json'], consent: [], actor: 'user',
ask_user: true, requires_exclusive: false, why: 'HEAD has a local commit the upstream lacks.', user_message: 'Push the local commit of source-a?',
docs: 'docs/guides/write-refusals.md#refresh_diverged' };
error.why = 'The checkout holds a commit the upstream lacks.';
error.reason = 'local_commits';
error.contractVersion = 1;
return error;
};
const result = await startPersistenceIpcServer(path, { brainId: BRAIN, dispatch: async () => ({}), administer: async () => { throw refusal(); } });
bindings.push(result!);
const delegated = await requestPersistenceAdministration(path, { version: 1, kind: 'administration', brain_id: BRAIN, operation: 'writer_refresh',
params: { source_id: 'source-a' }, registration: REGISTRATION }).then(() => null, error => error);
expect(delegated).toBeInstanceOf(OperationError);
const printed = (error: OperationError) => {
const out: string[] = [];
const log = console.log;
console.log = (line: string) => { out.push(line); };
try { printRefreshOutcome({ error }, true); } finally { console.log = log; _resetCliExitVerdictForTests(); process.exitCode = 0; }
return JSON.parse(out.join('\n'));
};
const direct = printed(refusal()).fix;
expect(direct).toMatchObject({ argv: refusal().fix!.argv, next: 'ask_user', actor: 'user' });
expect(printed(delegated as OperationError).fix).toEqual(direct);
expect((delegated as OperationError).toJSON()).toMatchObject({ why: 'The checkout holds a commit the upstream lacks.', reason: 'local_commits', contract_version: 1 });
});
});