Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { expect } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../../src/core/engine.ts';
import { __setChatTransportForTests, type ChatResult } from '../../src/core/ai/gateway.ts';
import { runPhaseExtractAtoms } from '../../src/core/cycle/extract-atoms.ts';
import { OperationError } from '../../src/core/ops/contract.ts';
import { managedAtomSession, readAtomOrigin, resumeManagedAtoms } from '../../src/core/persistence/atom-maintenance.ts';
import { retryManagedAtomBatch } from '../../src/core/persistence/atom-retry.ts';
import { withCoordinatedWrite } from '../../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './write-attribution.ts';
import { compactWriteReceipts, receiptFor } from '../../src/core/persistence/journal.ts';
import type { WriteRequest } from '../../src/core/persistence/model.ts';
import { disposePersistenceConsumer, waitForWrite } from '../../src/core/persistence/service.ts';
import { sha256 } from '../../src/core/persistence/digest.ts';
import { withEnv } from './with-env.ts';
import { waitFor } from './wait-for.ts';
const requestsSql = "SELECT * FROM persistence_requests WHERE source_id=$1 AND intent->>'kind' IS DISTINCT FROM 'managed_generation_activate' ORDER BY sequence";
export const atomCompactionCases = ['all_failed', 'mixed_all', 'completion_only', 'failed_child_only', 'committed_child_only', 'changed_target', 'success', 'malformed'] as const;
export const atomCompactionActions = ['resume', 'retry'] as const;
export async function exerciseAtomCompaction(engine: BrainEngine, scenario: typeof atomCompactionCases[number], action: typeof atomCompactionActions[number]): Promise<void> {
const home = mkdtempSync(join(tmpdir(), 'gbrain-atom-compaction-'));
const sourceId = `compact-${sha256(`${scenario}-${action}`).slice(0, 12)}`;
let observedEngine = engine;
try {
await withEnv({ GBRAIN_HOME: home }, async () => {
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [sourceId]);
await engine.putPage('notes/2026-01-01-example', { type: 'source', title: 'Example', compiled_truth: 'A private project record. '.repeat(40), frontmatter: { visibility: 'private' } }, { sourceId });
const page = (await engine.getPage('notes/2026-01-01-example', { sourceId }))!;
const titles = ['Measured progress', 'Explicit ownership'];
const slugs = titles.map(title => `atoms/2026-01-01/${title.toLowerCase().replaceAll(' ', '-')}-${sha256(`${page.slug}\0${title}`).slice(0, 8)}`);
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
const observe = (target: BrainEngine): BrainEngine => new Proxy(target, {
get(current, key) {
if (key === 'addLinksBatch') return async (...args: Parameters<BrainEngine['addLinksBatch']>) => {
if (scenario !== 'success' && (scenario === 'all_failed' || args[0].some(link => link.to_slug === slugs[1]))) {
throw new OperationError('revision_conflict', 'Fixture atom publication conflict');
}
return current.addLinksBatch(...args);
};
if (key === 'transaction') return <T>(fn: (tx: BrainEngine) => Promise<T>): Promise<T> => current.transaction(tx => fn(observe(tx)));
const value = Reflect.get(current, key);
return typeof value === 'function' ? value.bind(current) : value;
},
});
observedEngine = observe(engine);
let calls = 0;
const chat = async (): Promise<ChatResult> => {
calls++;
return { text: scenario === 'malformed' ? 'Invalid model output' : JSON.stringify(titles.map(title => ({ title, atom_type: 'insight', body: `Use ${title.toLowerCase()} to guide the project.` }))),
blocks: [], stopReason: 'end', usage: { input_tokens: 10, output_tokens: 10, cache_read_tokens: 0, cache_creation_tokens: 0 }, model: 'anthropic:claude-haiku-4-5', providerId: 'anthropic' };
};
const opts = { sourceId, _chat: chat, _transcripts: [], _pages: [{ slug: page.slug, content: page.compiled_truth, contentHash: page.content_hash! }] };
const first = await runPhaseExtractAtoms(observedEngine, opts);
expect(first.status).toBe(scenario === 'success' ? 'ok' : 'warn');
expect(calls).toBe(1);
const accepted = await engine.executeRaw<WriteRequest>(requestsSql, [sourceId]);
expect(accepted).toHaveLength(scenario === 'malformed' ? 1 : 3);
const completion = await waitForWrite(observedEngine, accepted.at(-1)!, { engine: engine.kind });
expect(completion.state).toBe(['success', 'malformed'].includes(scenario) ? 'committed' : 'conflict');
// A committed atom still has its embedding effect running. Stopping the
// consumer requeues it, and compaction retains a receipt whose effect is
// unfinished, so settle the source's effects before stopping.
await waitFor(async () => (await engine.executeRaw(
"SELECT 1 FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id WHERE r.source_id=$1 AND e.state IN ('queued','running')", [sourceId])).length === 0,
{ label: `${engine.kind}: ${scenario} ${action} atom effects settled` });
await disposePersistenceConsumer(observedEngine);
const originals = await engine.executeRaw<WriteRequest>(requestsSql, [sourceId]);
expect(await engine.executeRaw("SELECT state FROM persistence_requests WHERE source_id=$1 AND intent->>'kind'='managed_generation_activate'", [sourceId]))
.toEqual(scenario === 'malformed' ? [] : [{ state: scenario === 'success' ? 'committed' : 'failed' }]);
if (scenario !== 'malformed') expect(originals.map(row => row.state)).toEqual(scenario === 'success' ? ['committed', 'committed', 'committed'] :
scenario === 'all_failed' ? ['conflict', 'conflict', 'conflict'] : ['committed', 'conflict', 'conflict']);
if (scenario === 'changed_target') {
await engine.transaction(tx => withCoordinatedWrite(tx, [sourceId], async () => {
await tx.lockPageKeys([{ sourceId, slug: slugs[0] }]);
const atom = (await tx.getPage(slugs[0], { sourceId }))!;
await tx.putPage(slugs[0], { ...atom, compiled_truth: 'Independent correction after the original atom committed.' }, { sourceId });
}, TEST_WRITE_ATTRIBUTION));
}
const pagesBefore = await engine.executeRaw('SELECT * FROM pages WHERE source_id=$1 ORDER BY id', [sourceId]);
const checkpointsBefore = await engine.executeRaw("SELECT * FROM op_checkpoints WHERE op='managed-atoms' AND completed_keys->0->>'sourceId'=$1 ORDER BY fingerprint", [sourceId]);
expect(checkpointsBefore).toHaveLength(['success', 'malformed'].includes(scenario) ? 1 : 0);
const compactIds = scenario === 'completion_only' ? [completion.id] : scenario === 'failed_child_only' ? [originals[1].id] :
scenario === 'committed_child_only' ? [originals[0].id] : originals.map(row => row.id);
const [counterBefore] = await engine.executeRaw<{ terminal_bytes: string }>("SELECT terminal_bytes::text FROM persistence_counters WHERE key='brain'");
await engine.executeRaw("UPDATE persistence_requests SET completed_at=now()-interval '31 days' WHERE id=ANY($1::uuid[])", [compactIds]);
expect(await compactWriteReceipts(engine)).toBe(compactIds.length);
const retained = await engine.executeRaw<WriteRequest>(requestsSql, [sourceId]);
for (let i = 0; i < retained.length; i++) {
expect(retained[i].compacted).toBe(compactIds.includes(retained[i].id));
expect(retained[i].intent).toEqual(compactIds.includes(retained[i].id) ? null : originals[i].intent);
expect(retained[i].outcome).toEqual(originals[i].outcome);
expect(retained[i].state).toBe(originals[i].state);
}
const releasedBytes = originals.reduce((sum, row, i) => sum + Number(row.terminal_reservation) - Number(retained[i].terminal_reservation), 0);
expect(releasedBytes).toBeGreaterThan(0);
const [counterAfter] = await engine.executeRaw<{ terminal_bytes: string }>("SELECT terminal_bytes::text FROM persistence_counters WHERE key='brain'");
expect(Number(counterAfter.terminal_bytes)).toBe(Number(counterBefore.terminal_bytes) - releasedBytes);
const providerFree = async (): Promise<ChatResult> => { calls++; throw new Error('Compacted atom receipts must prevent another model call'); };
__setChatTransportForTests(providerFree);
if (action === 'resume') {
const replay = await runPhaseExtractAtoms(engine, { ...opts, _chat: providerFree });
// #6325: a failed batch is retried automatically whether or not its receipt was compacted.
expect(calls).toBe(scenario === 'malformed' ? 2 : 1);
expect(replay.status).toBe(scenario === 'success' ? 'ok' : 'warn');
if (scenario === 'success') expect(replay.details?.duplicates_skipped).toBe(1);
const session = (await managedAtomSession(engine, sourceId))!;
const origin = await readAtomOrigin(engine, session, { kind: 'page', slug: page.slug, content: page.compiled_truth, contentHash: page.content_hash! });
if (scenario === 'success') expect(await resumeManagedAtoms(engine, session, origin)).toBe('done');
else if (scenario === 'malformed') expect(await resumeManagedAtoms(engine, session, origin)).toBe('run');
else {
let error: unknown;
try { await resumeManagedAtoms(engine, session, origin); } catch (caught) { error = caught; }
expect(error).toBeInstanceOf(OperationError);
expect(retained.map(row => row.request_id)).toContain((error as OperationError).writeRequest?.request_id!);
}
} else {
for (const row of retained) {
let error: unknown;
try { await retryManagedAtomBatch(engine, sourceId, row.request_id, 'reviewed-expired-retry'); } catch (caught) { error = caught; }
expect(calls).toBe(1);
expect(error).toBeInstanceOf(OperationError);
expect(error).toMatchObject({ code: 'recovery_required' });
const refusal = error as OperationError;
expect(refusal.message).toContain('expired');
expect(refusal.suggestion ?? '').not.toContain('gbrain jobs submit');
const expired = retained.find(item => item.request_id === refusal.writeRequest?.request_id)!;
expect(expired.compacted).toBe(true);
expect(refusal.writeRequest).toEqual(receiptFor(expired));
}
}
await disposePersistenceConsumer(engine);
expect(calls).toBe(action === 'resume' && scenario === 'malformed' ? 2 : 1);
expect(await engine.executeRaw<WriteRequest>(requestsSql, [sourceId])).toEqual(retained);
expect(await engine.executeRaw('SELECT * FROM pages WHERE source_id=$1 ORDER BY id', [sourceId])).toEqual(pagesBefore);
expect(await engine.executeRaw("SELECT * FROM op_checkpoints WHERE op='managed-atoms' AND completed_keys->0->>'sourceId'=$1 ORDER BY fingerprint", [sourceId])).toEqual(checkpointsBefore);
expect(await engine.executeRaw<{ terminal_bytes: string }>("SELECT terminal_bytes::text FROM persistence_counters WHERE key='brain'")).toEqual([counterAfter]);
});
} finally {
await disposePersistenceConsumer(observedEngine);
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
__setChatTransportForTests(null);
rmSync(home, { recursive: true, force: true });
}
}