Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Agent-first operator wave Lane E (E1/E2/E11): doctor checks speak contract v1.
*
* - status stays ok | warn | fail (schema_version 2); capabilities off by
* choice are `ok` + severity:'info' + readiness_state and do not cost score;
* - every non-ok check carries a rendered `fix` or a `fix_unavailable_reason`;
* - top_issues[] gain the structured `action` next to the legacy `fix` string;
* - checkError() is the one "could not run" shape;
* - `--only` parsing / engine need; the backup coaching gate; the non-TTY
* heartbeat budget; the agent_contract check.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { buildChecks, computeDoctorReport, type Check } from '../src/commands/doctor.ts';
import { checkError, finalizeCheckFixes, infoCheck } from '../src/commands/doctor/check-fix.ts';
import { doctorCheckNames, onlyNeedsEngine, parseOnlyChecks } from '../src/commands/doctor/registry.ts';
import { throttleDoctorHeartbeat } from '../src/commands/doctor/heartbeat.ts';
import { agentContractCheck, agentContractEntry } from '../src/commands/doctor/checks/agent-contract.ts';
import { readAgentContractEvents, recordAgentContractEvent } from '../src/core/agent-contract-log.ts';
import { VERSION } from '../src/version.ts';
import { backupCoachingDue } from '../src/core/backup/status-file.ts';
import type { ProgressReporter } from '../src/core/progress.ts';
import { withEnv } from './helpers/with-env.ts';
const fix = { argv: ['gbrain', 'doctor', '--json'], consent: [], actor: 'agent' as const, why: 'diagnose', requires_exclusive: false, docs: 'docs/guides/troubleshooting.md' };
describe('doctor report status set (E2)', () => {
test('info checks are ok, keep the health score, and keyless brains report capped_by', () => {
const checks: Check[] = [
infoCheck('embeddings', 'off by choice', 'disabled_by_choice', fix),
{ name: 'connection', status: 'ok', message: 'Connected' },
];
const report = computeDoctorReport(checks);
expect(report.schema_version).toBe(2);
expect(report.status).toBe('healthy');
expect(report.health_score).toBe(100);
expect(report.capped_by).toEqual(['embeddings_disabled']);
for (const c of report.checks) expect(['ok', 'warn', 'fail']).toContain(c.status);
const emb = report.checks.find(c => c.name === 'embeddings')!;
expect(emb).toMatchObject({ status: 'ok', severity: 'info', readiness_state: 'disabled_by_choice' });
expect(report.top_issues).toEqual([]);
});
test('a brain without disabled embeddings carries no capped_by', () => {
expect(computeDoctorReport([{ name: 'embeddings', status: 'ok', message: 'ok' }]).capped_by).toBeUndefined();
});
test('fixes render for the transport: next, shell-quoted command, absolute docs; top_issues gain action', () => {
const report = computeDoctorReport([{ name: 'sync_failures', status: 'warn', message: 'x', fix }]);
const rendered = report.checks[0].fix as unknown as Record<string, unknown>;
expect(rendered).toMatchObject({ next: 'run', command: 'gbrain doctor --json', actor: 'agent' });
expect(String(rendered.docs)).toMatch(/^https:\/\//);
expect(report.top_issues?.[0]).toMatchObject({ name: 'sync_failures', fix: 'x', action: { next: 'run', command: 'gbrain doctor --json' } });
});
test('an MCP render context rewrites a CLI-only agent fix to tell_user_to_run', () => {
const report = computeDoctorReport([{ name: 'sync_failures', status: 'warn', message: 'x', fix }], {
render: { transport: 'http', isCallable: () => false, preapproved: () => false },
});
expect(report.checks[0].fix).toMatchObject({ actor: 'host_admin', next: 'tell_user_to_run' });
});
test('every non-ok check ends with a fix or a fix_unavailable_reason', () => {
const out = finalizeCheckFixes<Check>([
{ name: 'a', status: 'warn', message: 'legacy prose' },
{ name: 'b', status: 'fail', message: 'x', fix_unavailable_reason: 'operator_judgement' },
{ name: 'c', status: 'ok', message: 'fine' },
]);
expect(out[0].fix_unavailable_reason).toBe('unstructured');
expect(out[1].fix_unavailable_reason).toBe('operator_judgement');
expect(out[2].fix_unavailable_reason).toBeUndefined();
});
});
describe('checkError (E1)', () => {
test('keeps the Could-not message and says the check itself failed', () => {
expect(checkError('rls', 'check RLS status', new Error('boom'))).toEqual({
name: 'rls', status: 'warn', message: 'Could not check RLS status: boom', fix_unavailable_reason: 'check_errored',
});
expect(checkError('rls', 'check RLS status')).toMatchObject({ message: 'Could not check RLS status' });
});
test('a database access error gets the read-only db-repair diagnosis as fix', () => {
const err = Object.assign(new Error('password authentication failed for user "x"'), { code: '28P01' });
const c = checkError('rls', 'check RLS status', err);
expect(c.fix).toMatchObject({ argv: ['gbrain', 'db-repair'], consent: [], verify: { argv: ['gbrain', 'doctor', '--only', 'rls', '--json'] } });
});
});
describe('doctor --only (E1)', () => {
test('parses comma lists, repeats and = form', () => {
expect(parseOnlyChecks(['--json'])).toBeNull();
expect([...parseOnlyChecks(['--only', 'a,b', '--only=c'])!]).toEqual(['a', 'b', 'c']);
});
test('knows its vocabulary and which checks need the engine', () => {
const names = doctorCheckNames();
expect(names.has('harness_wiring')).toBe(true);
expect(names.has('agent_contract')).toBe(true);
expect(onlyNeedsEngine(new Set(['harness_wiring', 'agent_contract']))).toBe(false);
expect(onlyNeedsEngine(new Set(['embeddings']))).toBe(true);
});
test('engine-free run returns exactly the requested checks', async () => {
const home = mkdtempSync(join(tmpdir(), 'gbrain-only-'));
try {
await withEnv({ GBRAIN_HOME: home, HOME: home, CLAUDECODE: undefined, CLAUDE_CODE_ENTRYPOINT: undefined, CODEX_SANDBOX: undefined, CODEX_CI: undefined, CODEX_HOME: undefined, OPENCODE: undefined, OPENCODE_PID: undefined }, async () => {
const checks = await buildChecks(null, ['--only', 'agent_contract,harness_wiring', '--json']);
expect(checks.map(c => c.name).sort()).toEqual(['agent_contract', 'harness_wiring']);
});
} finally {
rmSync(home, { recursive: true, force: true });
}
});
});
describe('backup coaching gate (E7)', () => {
const now = Date.parse('2026-10-03T00:00:00Z');
const day = 86_400_000;
test('young and small brains are not coached; 25 items or 7 days are; old caches keep warning', () => {
expect(backupCoachingDue({ maturity: { items: 3, since: new Date(now - day).toISOString() } }, now)).toBe(false);
expect(backupCoachingDue({ maturity: { items: 25, since: new Date(now - day).toISOString() } }, now)).toBe(true);
expect(backupCoachingDue({ maturity: { items: 0, since: new Date(now - 7 * day).toISOString() } }, now)).toBe(true);
expect(backupCoachingDue({ maturity: { items: 0, since: null } }, now)).toBe(false);
expect(backupCoachingDue({}, now)).toBe(true);
});
});
describe('non-TTY heartbeat budget (E11)', () => {
test('at most one heartbeat per gap; a slow check still gets its line', () => {
const lines: string[] = [];
const inner = { start: () => {}, tick: () => {}, heartbeat: (n: string) => { lines.push(n); }, finish: () => {}, child: () => inner } as unknown as ProgressReporter;
let t = 0;
const p = throttleDoctorHeartbeat(inner, { tty: false, now: () => t, gapMs: 5_000 });
p.start('doctor.db_checks');
for (let i = 0; i < 40; i++) { t += 100; p.heartbeat(`check_${i}`); }
expect(lines).toEqual([]);
t += 6_000;
p.heartbeat('slow_check');
expect(lines).toEqual(['slow_check']);
expect(throttleDoctorHeartbeat(inner, { tty: true })).toBe(inner);
});
});
describe('agent_contract check (E11)', () => {
const now = Date.parse('2026-10-03T00:00:00Z');
const ts = new Date(now - 3_600_000).toISOString();
test('clean log is ok', () => {
expect(agentContractCheck([], now)).toMatchObject({ status: 'ok' });
});
test('refused paid runs and derived-cap stops warn with the user-only preapproval command', () => {
const c = agentContractCheck([
{ ts, command: 'dream', transport: 'cli', code: 'confirmation_required', effects: ['paid'], outcome: 'refused' },
{ ts, command: 'embed', transport: 'cli', code: 'derived_cap_exhausted', effects: ['paid'], outcome: 'stopped' },
{ ts, command: 'dream', transport: 'cli', code: 'confirmation_required', effects: ['paid'], outcome: 'preapproved' },
], now);
expect(c.status).toBe('warn');
expect(c.details).toMatchObject({ consent_refused: 1, derived_cap_exhausted: 1 });
expect(c.fix).toMatchObject({ argv: ['gbrain', 'config', 'set', 'consent.preapprove.paid.max_usd_per_run', '<usd>'], actor: 'user', consent: ['paid'] });
});
test('internal errors warn without a fabricated fix; old events age out', () => {
const c = agentContractCheck([
{ ts, op: 'find_orphans', transport: 'stdio', code: 'internal_error', has_suggestion: true },
{ ts: new Date(now - 30 * 86_400_000).toISOString(), op: 'x', transport: 'stdio', code: 'internal_error' },
], now);
expect(c).toMatchObject({ status: 'warn', fix_unavailable_reason: 'operator_judgement', details: { internal_errors: 1 } });
expect(c.message).toContain('find_orphans');
});
});
describe('keyless brain: capability checks are information, not warnings (E2)', () => {
let home: string;
let engine: PGLiteEngine;
beforeAll(async () => {
home = mkdtempSync(join(tmpdir(), 'gbrain-keyless-info-'));
mkdirSync(join(home, '.gbrain'));
writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', embedding_disabled: true }));
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => {
await engine.disconnect();
rmSync(home, { recursive: true, force: true });
});
test('embeddings / embedding_provider / embed_staleness / takes_count / fact_take_vectors / cycle_freshness are ok + info', async () => {
await withEnv({ GBRAIN_HOME: home, OPENAI_API_KEY: undefined, VOYAGE_API_KEY: undefined, ANTHROPIC_API_KEY: undefined }, async () => {
const checks = await buildChecks(engine, ['--only', 'embeddings,embedding_provider,embed_staleness,takes_count,fact_take_vectors,cycle_freshness']);
const byName = new Map(checks.map(c => [c.name, c]));
for (const name of ['embeddings', 'embedding_provider', 'embed_staleness', 'fact_take_vectors']) {
expect(byName.get(name), name).toMatchObject({ status: 'ok', severity: 'info', readiness_state: 'disabled_by_choice' });
}
expect(byName.get('embeddings')!.fix).toMatchObject({ argv: expect.arrayContaining(['gbrain', 'init', '--force', '--embedding-model']) });
expect(byName.get('embedding_provider')!.message).not.toMatch(/migrate embeddings/);
expect(byName.get('takes_count')).toMatchObject({ status: 'ok', severity: 'info', fix: { consent: ['paid'] } });
expect(byName.get('cycle_freshness')!.status).toBe('ok');
});
});
});
describe('connection errors name their source; brain score unknown when DB checks did not run (E10)', () => {
test('describeUrlSource names the env var or the config file under GBRAIN_HOME', async () => {
const { describeUrlSource } = await import('../src/commands/doctor/checks/db-connection.ts');
const home = mkdtempSync(join(tmpdir(), 'gbrain-url-source-'));
try {
await withEnv({ GBRAIN_HOME: home }, async () => {
expect(describeUrlSource('env:GBRAIN_DATABASE_URL')).toBe('the GBRAIN_DATABASE_URL environment variable');
expect(describeUrlSource('config-file')).toBe(`database_url in ${join(home, '.gbrain', 'config.json')}`);
expect(describeUrlSource(null)).toBeNull();
});
} finally {
rmSync(home, { recursive: true, force: true });
}
});
test('a non-ok connection marks the brain score unknown; a live one does not', () => {
expect(computeDoctorReport([{ name: 'connection', status: 'fail', message: 'refused' }]).unknown_scores).toEqual(['brain']);
expect(computeDoctorReport([{ name: 'connection', status: 'ok', message: 'Connected, 0 pages' }]).unknown_scores).toBeUndefined();
});
test('non-Supabase URLs get no Supabase advice', async () => {
const { classifyPgAccessError } = await import('../src/core/pg-access-classify.ts');
const err = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:5432'), { code: 'ECONNREFUSED' });
expect(classifyPgAccessError(err, { url: 'postgresql://[email protected]:5432/brain' }).remediation).not.toMatch(/Supabase/);
expect(classifyPgAccessError(err, { url: 'postgresql://[email protected]:5432/postgres' }).remediation).toMatch(/Supabase/);
});
});
describe('#6758 agent_contract: events from other builds are history, counted apart', () => {
const now = Date.parse('2026-10-03T00:00:00Z');
const ts = new Date(now - 3_600_000).toISOString();
const older = new Date(now - 2 * 86_400_000).toISOString();
test('faults split by the build that recorded them; all from other builds reads as historical', () => {
const c = agentContractCheck([
{ ts: older, op: 'find_orphans', transport: 'stdio', code: 'internal_error', version: '0.60.100.0' },
{ ts, op: 'find_orphans', transport: 'stdio', code: 'internal_error', version: '0.60.200.0' },
{ ts, op: 'search', transport: 'stdio', code: 'internal_error' },
], now);
expect(c.status).toBe('warn');
expect(c.details).toMatchObject({ internal_errors: 3, builds: { this_build: 0, other_builds: 2, unknown_build: 1, versions: ['0.60.100.0', '0.60.200.0'] },
incident: { scope: 'historical', since: older } });
expect(c.message).toContain('2 of 3 were recorded by another gbrain build (0.60.100.0 to 0.60.200.0)');
expect(c.message).toContain('1 by a build that did not record its version');
});
test('a fault from this build is current', () => {
const c = agentContractCheck([
{ ts: older, op: 'x', transport: 'stdio', code: 'internal_error', version: '0.60.100.0' },
{ ts, op: 'y', transport: 'stdio', code: 'internal_error', version: VERSION },
], now);
expect(c.details).toMatchObject({ builds: { this_build: 1, other_builds: 1, unknown_build: 0 }, incident: { scope: 'current', since: older } });
});
test('recordAgentContractEvent stamps the build that wrote the event', async () => {
const home = mkdtempSync(join(tmpdir(), 'gbrain-agent-contract-version-'));
try {
await withEnv({ GBRAIN_HOME: home }, async () => {
recordAgentContractEvent({ transport: 'cli', command: 'embed', code: 'internal_error', outcome: 'failed' });
recordAgentContractEvent({ transport: 'cli', command: 'embed', code: 'internal_error', version: '0.1.0.0' });
expect(readAgentContractEvents().map(e => e.version)).toEqual([VERSION, '0.1.0.0']);
});
} finally { rmSync(home, { recursive: true, force: true }); }
});
});
test('#7145: agent_contract judges the whole 7-day window, not only the newest 500 events', async () => {
const home = mkdtempSync(join(tmpdir(), 'gbrain-agent-contract-window-'));
try {
await withEnv({ GBRAIN_HOME: home }, async () => {
recordAgentContractEvent({ transport: 'cli', command: 'example-op', code: 'internal_error' });
for (let i = 0; i < 600; i++) recordAgentContractEvent({ transport: 'cli', command: 'example-op', code: 'not_found', has_suggestion: true });
const [check] = await agentContractEntry.run({} as never) as Check[];
expect(check).toMatchObject({ name: 'agent_contract', status: 'warn', details: { internal_errors: 1, events: 601 } });
});
} finally { rmSync(home, { recursive: true, force: true }); }
});