Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { expect } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../../src/core/engine.ts';
import type { GBrainConfig } from '../../src/core/config.ts';
import { claimWorktree } from '../../src/core/persistence/ownership.ts';
import { disposePersistenceConsumer, waitForWrites } from '../../src/core/persistence/service.ts';
import { TERMINAL_STATES, type WriteRequest } from '../../src/core/persistence/model.ts';
import { isolatedPersistencePostgres } from './persistence-postgres.ts';
import { syncLockId } from '../../src/core/db-lock.ts';
import { testBackends } from './test-backends.ts';
import { CONNECTOR_WAIT_BUDGET_MS, connectorWaitBudget } from '../../src/core/persistence/connector-sync.ts';
import { testWaitMs } from './wait-for.ts';
import { connectTemplateBrain } from './brain-template.ts';
import { readManagedConnectorState } from '../../src/core/persistence/connector-state.ts';
export const options = { noEmbed: true, noExtract: true, noSchemaPack: true };
export const json = (body: unknown, status = 200, headers = {}) => new Response(JSON.stringify(body), {
status, headers: { 'content-type': 'application/json', ...headers },
});
export const googleConfig = { kind: 'google', g_account: '[email protected]', g_services: 'contacts', g_access: 'env', g_token_env: 'CONNECTOR_TEST_TOKEN' };
export const githubConfig = { kind: 'github', gh_scope: 'repos', gh_repos: 'acme-example/app', gh_token_env: 'CONNECTOR_TEST_TOKEN' };
export const contact = (id: string, name: string) => ({ resourceName: `people/${id}`, names: [{ displayName: name }], emailAddresses: [{ value: `${id}@example.invalid` }] });
export const issueFixture = { number: 1, title: 'Example issue', state: 'open', body: 'A useful synthetic issue body.', created_at: '2026-01-01T00:00:00Z', updated_at: '2026-01-02T00:00:00Z', labels: [], assignees: [], user: { login: 'example-user' }, html_url: 'https://github.com/acme-example/app/issues/1' };
export function githubFetch(opts: { failDetail?: boolean; failSecondPage?: boolean; deleted?: boolean; calls?: string[] } = {}) {
return async (url: string) => {
opts.calls?.push(url);
const u = new URL(url);
const path = u.pathname;
if (path.endsWith('/issues')) {
if (opts.failSecondPage && u.searchParams.has('page')) return json({ message: 'fixture listing failure' }, 400);
return json(opts.deleted ? [] : [issueFixture], 200, opts.failSecondPage ? { link: '<https://api.github.com/repos/acme-example/app/issues?page=2>; rel="next"' } : {});
}
if (path.endsWith('/pulls') || path.endsWith('/comments')) return json([]);
if (path.endsWith('/issues/1')) return opts.failDetail ? json({ message: 'fixture detail failure' }, 400) : json(issueFixture);
if (path === '/repos/acme-example/app') return json({ full_name: 'acme-example/app', private: true, default_branch: 'main' });
throw new Error('Unexpected external fixture route');
};
}
/**
* A baseline sweep that finished: re-run `run` until the source has no
* accepted-pending connector writes and no unfinished write request. A sweep
* whose writes outlast its wait budget ends partial (its cursor is saved by the
* next run), so a test that snapshots the cursor right after one `run()` could
* read the state before the cursor moved and then see the next run move it.
*/
export async function completeBaselineSweep(engine: BrainEngine, sourceId: string, run: () => Promise<unknown>, attempts = 5): Promise<void> {
for (let i = 0; i < attempts; i++) {
await run();
const unfinished = await engine.executeRaw<{ n: number }>(
'SELECT count(*)::int AS n FROM persistence_requests WHERE source_id=$1 AND NOT (state = ANY($2::text[]))', [sourceId, [...TERMINAL_STATES]]);
if ((await connectorPendingSet(engine, sourceId)).length === 0 && unfinished[0]!.n === 0) return;
}
throw new Error(`baseline sweep of ${sourceId} still had pending connector writes after ${attempts} runs`);
}
export async function sourceCheckpoint(engine: BrainEngine, id: string) {
return engine.executeRaw("SELECT completed_keys FROM op_checkpoints WHERE op='managed-connector' AND fingerprint IN (SELECT intent->>'checkpointKey' FROM persistence_requests WHERE source_id=$1)", [id]);
}
export function createConnectorFixture() {
const backends = testBackends();
const home = mkdtempSync(join(tmpdir(), 'gbrain-connector-parity-'));
const engines: BrainEngine[] = [];
let closePostgres: (() => Promise<void>) | undefined;
const env = { GBRAIN_HOME: home, CONNECTOR_TEST_TOKEN: 'synthetic-local-fixture' };
const setup = async () => {
connectorWaitBudget.ms = CONNECTOR_WAIT_BUDGET_MS;
if (backends.includes('pglite')) {
engines.push(await connectTemplateBrain(join(home, 'database')));
}
if (backends.includes('postgres')) {
const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
engines.push(pg.engine);
closePostgres = pg.close;
}
};
const teardown = async () => {
connectorWaitBudget.ms = CONNECTOR_WAIT_BUDGET_MS;
for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
await closePostgres?.();
rmSync(home, { recursive: true, force: true });
};
async function source(engine: BrainEngine, config: Record<string, unknown>) {
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
const id = `connector-${randomUUID().slice(0, 8)}`;
const dir = join(home, id);
mkdirSync(dir);
await engine.executeRaw('INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,$3::text::jsonb)', [id, dir, JSON.stringify(config)]);
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
return { id, dir };
}
async function boundSource(engine: BrainEngine, config: Record<string, unknown>) {
const f = await source(engine, config);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
const binding = await claimWorktree(engine, f.id, f.dir);
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
return { ...f, binding };
}
async function standaloneConnector(engine: BrainEngine, f: { id: string; dir: string }, sourceConfig: Record<string, unknown>, crash = false, retryFailed = false) {
let database: GBrainConfig & { poolSize?: number } = { engine: 'pglite', database_path: join(home, 'database') };
if (engine.kind === 'postgres') {
const [row] = await engine.executeRaw<{ name: string }>('SELECT current_database() AS name');
const url = new URL(process.env.DATABASE_URL!);
url.pathname = `/${row.name}`;
database = { engine: 'postgres', database_url: url.toString(), poolSize: 4 };
}
await disposePersistenceConsumer(engine);
await engine.disconnect();
let childPid: number | undefined;
try {
const child = Bun.spawn([process.execPath, 'run', join(import.meta.dir, 'connector-restart.ts')], {
env: { ...process.env, ...env, GBRAIN_TEST_CONNECTOR_RESTART: JSON.stringify({ database, sourceId: f.id,
root: f.dir, sourceConfig, body: 'Updated organization after interruption', crash, retryFailed }) }, stdout: 'pipe', stderr: 'pipe',
});
childPid = child.pid;
const timer = setTimeout(() => child.kill('SIGKILL'), 30_000);
try {
const [stdout, stderr, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
return { stdout, stderr, exitCode };
} finally { clearTimeout(timer); if (child.exitCode === null) child.kill('SIGKILL'); await child.exited; }
} finally {
await engine.connect(database);
if (crash && childPid !== undefined) await engine.executeRaw(`UPDATE gbrain_cycle_locks
SET acquired_at=now()-interval '2 minutes',last_refreshed_at=now()-interval '1 hour',ttl_expires_at=now()-interval '1 hour'
WHERE id=$1 AND holder_pid=$2`, [syncLockId(f.id), childPid]);
}
}
return { home, engines, env, backends, setup, teardown, source, boundSource, standaloneConnector };
}
/** #7490: the People reachability probe (one connection, email addresses only), told apart from a contacts sweep page. */
export function isPeopleAccessProbe(url: string): boolean {
const u = new URL(url);
return u.pathname.endsWith('/people/me/connections') && u.searchParams.get('pageSize') === '1' && u.searchParams.get('personFields') === 'emailAddresses';
}
/**
* #5686: a managed Google run resolves the credential's account (People
* reachability, Calendar primary, Gmail profile, then OAuth userinfo) before
* any service runs. Fixture fetchers that only model sweep routes get those
* identity routes answered here.
*/
export function withGoogleAccount(fetcher: ((url: string, init?: RequestInit) => Promise<Response>) | undefined, account = googleConfig.g_account) {
return async (url: string, init?: RequestInit) => {
const path = new URL(url).pathname;
if (path.endsWith('/people/me')) return json({ resourceName: 'people/me', emailAddresses: [{ value: account, metadata: { primary: true } }] });
if (isPeopleAccessProbe(url)) return json({ connections: [] });
if (path.endsWith('/v1/userinfo')) return json({ email: account });
if (path.endsWith('/calendars/primary')) return json({ id: account });
if (!fetcher) throw new Error('Unexpected external fixture route');
return fetcher(url, init);
};
}
/**
* A managed sweep returns with an accepted write still pending once its wait
* budget runs out; the cursor stays put and the write publishes later. A seed
* that reads its imported pages, or stops the consumer and hands the database
* to a child, first waits for every write the source admitted to commit.
*/
export async function settleConnectorWrites(engine: BrainEngine, sourceId: string) {
const rows = await engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE source_id=$1 ORDER BY created_at', [sourceId]);
const settled = await waitForWrites(engine, rows, { engine: engine.kind }, testWaitMs(30_000));
expect(settled.map(row => [row.slug, row.state])).toEqual(rows.map(row => [row.slug, 'committed']));
}
/**
* The fixture's 1.5 s wait budget is for runs against a paused owner. A run whose assertions need every write
* published (a healthy owner) runs on the production budget, so a slow host waits for the owner instead of
* stopping the sweep `writer_pending`. A committed write returns at once, so this costs nothing on a fast host.
*/
/** A run that expects `writer_pending` against a paused owner stops on a 1.5 s budget instead of the production 30 s. */
export async function withPausedOwnerBudget<T>(run: () => Promise<T>): Promise<T> {
const budget = connectorWaitBudget.ms;
connectorWaitBudget.ms = testWaitMs(1_500);
try { return await run(); } finally { connectorWaitBudget.ms = budget; }
}
/** #5600: the pending set a managed connector run ended with (connector state row). */
export async function connectorPendingSet(engine: BrainEngine, sourceId: string) {
const [source] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text FROM sources WHERE id=$1', [sourceId]);
return (await readManagedConnectorState(engine, sourceId, source.incarnation)).pending;
}
/**
* Fix wave 4: the connector cursor a checkpoint row carries, without its item
* holds or generation. A failed or partial run may publish updated holds, but
* never moves this cursor.
*/
export async function sourceCursor(engine: BrainEngine, id: string) {
return cursorOf(await sourceCheckpoint(engine, id));
}
export function cursorOf(rows: Array<{ completed_keys?: unknown }> | Record<string, unknown>[]) {
return (rows as Array<{ completed_keys?: Array<{ state?: Record<string, unknown> | null }> }>).map(row => (row.completed_keys ?? []).map(entry => {
if (!entry?.state) return { state: entry?.state ?? null };
const { item_holds: _holds, ...cursor } = entry.state;
return { state: cursor };
}));
}