Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #9279: captured session windows whose facts land on an entity page stored in segments.
*
* 1. Protects: a corpus window whose extracted facts resolve to a segmented entity page (named by the extractor, or
* inferred from a mention, which is how most conversation facts arrive) commits them onto the page's ## Facts
* table and the session file counts as extracted, on a managed Git source and on a repo-less brain; a refusal that
* retrying cannot change (page_body_segmented) stops its window after the one paid attempt instead of five, retention
* keeps the file it holds and doctor counts it; a window an older build stopped on that refusal is extracted by the
* first sweep on a new build, with no command.
* 2. Fails when: subject inference reads the whole body of a segmented page to check its fence (the getters throw
* page_body_segmented after the model call), a deterministic refusal is paid for again on the same build, retention
* deletes a held file at the un-ingested ceiling, or a stopped window waits for a hand-run retry after the upgrade.
* 3. Real seams: the maintenance sweep and its corpus window runner, the managed persistence consumer, a page imported
* large enough to be stored in segments, gateway test transports, PGLite and Postgres (testBackends).
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { opError } from '../src/core/ops/contract.ts';
import { configureGateway, resetGateway, __setChatTransportForTests, __setEmbedTransportForTests, type ChatResult } from '../src/core/ai/gateway.ts';
import { invokeAI } from '../src/core/ai/invocation-guard.ts';
import { CORPUS_INGESTED_SUFFIX, runMaintenanceSweep } from '../src/core/sweep.ts';
import { toCorpusText } from '../src/core/transcripts/claude-code-jsonl.ts';
import { CORPUS_FAILURE_SUFFIX, CORPUS_UNINGESTED_RETENTION_FACTOR, CORPUS_WINDOW_FAILURE_CAP, corpusBacklog, gcCorpusTurnFiles, readCorpusFailure } from '../src/core/context/corpus-segments.ts';
import { corpusFailureGate, corpusFileStat, corpusFrontierKey, runCorpusWindows } from '../src/core/context/corpus-windows.ts';
import { buildMemoryWritebackCheck } from '../src/commands/doctor/checks/memory-writeback.ts';
import { VERSION } from '../src/version.ts';
import type { CapabilityReport } from '../src/core/capability.ts';
import { spoolPath } from './helpers/corpus-spool.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { waitFor } from './helpers/wait-for.ts';
import { withEnv } from './helpers/with-env.ts';
const KEYED: CapabilityReport = { embeddings: { available: false }, extraction: { available: true, provider: 'anthropic' }, search: 'keyword-only', mode: 'keyed' };
const PERSON = { slug: 'people/alice-example', title: 'Alice Example' };
const NAMED = 'Alice Example ships the example roadmap';
const INFERRED = 'Alice Example will send the deck by Friday';
const DIMS = 1536;
/** Fence rows on the entity page: about 1.5 MB, over the 1 MiB inline bound, so it is stored in segments. */
const FENCE_ROWS = 4000;
const TEST_MS = 240_000;
const SETTLE_MS = 30_000;
const SWEEP_BUDGET_MS = 120_000;
const DAY_MS = 24 * 60 * 60 * 1000;
const RETENTION_DAYS = 30;
let extractions = 0;
const usage = { input_tokens: 5, output_tokens: 5, cache_read_tokens: 0, cache_creation_tokens: 0 };
function entityPage(): string {
const rows = Array.from({ length: FENCE_ROWS }, (_, i) => '| ' + (i + 1) + ' | Alice Example noted item ' + i + ' of the example roadmap, one of a long run of notes kept on this page over the years, with a longer tail of words that makes each row of the table wider so the page grows past the inline bound | fact | 0.9 | world | medium | 2026-01-01 | | meetings/2026-01-0' + (i % 9 + 1) + ' | a context note that adds some more length to this row ' + i + ' |');
return '---\ntitle: ' + PERSON.title + '\ntype: person\n---\n# ' + PERSON.title + '\n\n## Facts\n\n<!--- gbrain:facts:begin -->\n'
+ '| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |\n'
+ '|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|\n'
+ rows.join('\n') + '\n<!--- gbrain:facts:end -->\n';
}
const transcript = () => toCorpusText([
{ role: 'user', text: 'Planning notes with Alice Example about the example roadmap. '.repeat(40) },
{ role: 'assistant', text: 'Summary of the example roadmap discussion. '.repeat(40) },
]);
beforeAll(() => {
configureGateway({ chat_model: 'anthropic:claude-sonnet-4-6', embedding_model: 'openai:text-embedding-3-large', embedding_dimensions: DIMS,
env: { ANTHROPIC_API_KEY: 'sk-ant-test', OPENAI_API_KEY: 'sk-test' } });
__setChatTransportForTests(async (): Promise<ChatResult> => {
extractions++;
const facts = [
{ fact: NAMED, kind: 'fact', entity: PERSON.slug, confidence: 0.9, notability: 'high' },
{ fact: INFERRED, kind: 'commitment', entity: null, confidence: 0.9, notability: 'high' },
];
return { text: JSON.stringify({ facts }), blocks: [], stopReason: 'end', model: 'anthropic:claude-sonnet-4-6', providerId: 'anthropic', usage };
});
__setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({ embeddings: values.map(() => Array.from({ length: DIMS }, (_, i) => (i === 0 ? 1 : 0))) })) as never);
});
afterAll(() => {
__setChatTransportForTests(null);
__setEmbedTransportForTests(null);
resetGateway();
});
for (const kind of testBackends()) {
describe('corpus sweep onto a segmented entity page (' + kind + ', #9279)', () => {
let engine: BrainEngine;
let close: () => Promise<void>;
const dirs: string[] = [];
beforeAll(async () => {
if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
}, TEST_MS);
afterAll(async () => {
await disposePersistenceConsumer(engine).catch(() => undefined);
await close?.();
for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
}, TEST_MS);
/** A source (managed Git checkout, or none) holding the segmented entity page, with one captured session file. */
async function brain(dir: string, mode: 'git' | 'repoless') {
const root = join(dir, 'checkout'); mkdirSync(root);
const corpusDir = join(dir, 'sessions'); mkdirSync(corpusDir);
const sourceId = 'source-' + randomUUID().slice(0, 8);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, mode === 'git' ? root : null]);
for (const [key, value] of [['sync.write_through', 'true'], ['facts.extraction_enabled', 'true'], ['dream.synthesize.session_corpus_dir', corpusDir],
['facts.default_visibility', 'world']]) await engine.setConfig(key, value);
if (mode === 'git') await claimWorktree(engine, sourceId, root);
const ctx = { engine, sourceId, remote: false as const, config: { engine: engine.kind, embedding_disabled: true },
dryRun: false, logger: { info() {}, warn() {}, error() {} } } as unknown as OperationContext;
await submitPageMutation(ctx, { operation: 'put_page', params: { slug: PERSON.slug, request_id: randomUUID(), content: entityPage() } });
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
const sessionFile = spoolPath(corpusDir, 'example-session.txt', sourceId);
writeFileSync(sessionFile, transcript());
const logs: string[] = [];
const sweep = async () => {
const report = await runMaintenanceSweep(engine, { sourceId, capabilities: KEYED, budgetMs: SWEEP_BUDGET_MS, log: line => logs.push(line) });
await waitFor(async () => (await engine.executeRaw<{ n: number }>(
`SELECT COUNT(*)::int AS n FROM persistence_requests WHERE source_id=$1 AND state IN ('queued','running','recovering')`, [sourceId]))[0].n === 0,
{ timeoutMs: SETTLE_MS, label: 'fact requests settled' });
return report.corpusIngested;
};
const facts = () => engine.executeRaw<{ fact: string; slug: string; fenced: boolean }>(
`SELECT fact, source_markdown_slug AS slug, row_num IS NOT NULL AS fenced FROM facts WHERE source_id=$1 AND source='sweep:corpus' ORDER BY fact`, [sourceId]);
const storage = async () => (await engine.executeRaw<{ s: string }>('SELECT body_storage AS s FROM pages WHERE source_id=$1 AND slug=$2', [sourceId, PERSON.slug]))[0]?.s;
const [{ incarnation }] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]);
return { dir, corpusDir, sourceId, incarnation, sessionFile, logs, sweep, facts, storage };
}
/** One test's brain under its own GBRAIN_HOME (the worktree owner's host identity lives there). */
async function withBrain(mode: 'git' | 'repoless', body: (b: Awaited<ReturnType<typeof brain>>) => Promise<void>) {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-9279-'));
dirs.push(dir);
await withEnv({ GBRAIN_HOME: join(dir, 'home'), GBRAIN_AUDIT_DIR: join(dir, 'audit') }, async () => {
try { await body(await brain(dir, mode)); } finally {
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
}
});
}
for (const mode of ['git', 'repoless'] as const) {
test('a window whose named and inferred facts land on the segmented page commits them, fenced, in one paid call (' + mode + ')', async () => {
extractions = 0;
await withBrain(mode, async b => {
expect(await b.storage()).toBe('segmented');
expect(await b.sweep()).toBe(1);
expect(b.logs.join('\n')).not.toContain('page_body_segmented');
expect(extractions).toBe(1);
expect(existsSync(b.sessionFile + CORPUS_INGESTED_SUFFIX)).toBe(true);
expect(existsSync(b.sessionFile + CORPUS_FAILURE_SUFFIX)).toBe(false);
expect(await b.facts()).toEqual([
{ fact: NAMED, slug: PERSON.slug, fenced: true },
{ fact: INFERRED, slug: PERSON.slug, fenced: true },
]);
expect(await b.storage()).toBe('segmented');
expect(await b.sweep()).toBe(0);
expect(extractions).toBe(1);
});
}, TEST_MS);
}
test('a window an older build stopped on page_body_segmented is extracted by the first sweep after the upgrade, with no command', async () => {
extractions = 0;
await withBrain('repoless', async b => {
const key = await corpusFrontierKey(b.sessionFile, 'example-session.txt');
writeFileSync(b.sessionFile + CORPUS_FAILURE_SUFFIX, JSON.stringify({ version: 1, key, source_incarnation: b.incarnation, count: CORPUS_WINDOW_FAILURE_CAP,
first_at: Date.now() - DAY_MS, last_at: Date.now() - DAY_MS, last_code: 'page_body_segmented', fingerprint: null, rearmed: false }) + '\n');
expect(await b.sweep()).toBe(1);
expect(extractions).toBe(1);
expect(existsSync(b.sessionFile + CORPUS_FAILURE_SUFFIX)).toBe(false);
expect((await b.facts()).map(f => f.fact)).toEqual([NAMED, INFERRED]);
});
}, TEST_MS);
test('retention keeps a file held by a deterministic refusal and doctor counts it; an ordinary stopped file still goes', async () => {
await withBrain('repoless', async b => {
const old = (Date.now() - (RETENTION_DAYS * CORPUS_UNINGESTED_RETENTION_FACTOR + 1) * DAY_MS) / 1000;
const record = (code: string) => JSON.stringify({ version: 1, key: 'k@0', source_incarnation: b.incarnation, count: CORPUS_WINDOW_FAILURE_CAP,
first_at: 1, last_at: 1, last_code: code, fingerprint: null, rearmed: false, build: VERSION }) + '\n';
const held = spoolPath(b.corpusDir, 'held-session.txt', b.sourceId);
const ordinary = spoolPath(b.corpusDir, 'ordinary-session.txt', b.sourceId);
for (const [file, code] of [[held, 'page_body_segmented'], [ordinary, 'provider_error']] as const) {
writeFileSync(file, transcript());
writeFileSync(file + CORPUS_FAILURE_SUFFIX, record(code));
utimesSync(file, old, old);
}
const check = await buildMemoryWritebackCheck(engine);
expect(check.details).toMatchObject({ corpus_failed_windows: { stopped: 2, held: 1 } });
expect(corpusBacklog(join(b.corpusDir, 'sourced'), RETENTION_DAYS * DAY_MS)).toMatchObject({ pastRetention: 2, held: 1 });
expect(check.message).toContain('1 of them stopped at once on a refusal that retrying cannot change');
gcCorpusTurnFiles(join(b.corpusDir, 'sourced'), RETENTION_DAYS * DAY_MS);
expect(existsSync(held)).toBe(true);
expect(existsSync(ordinary)).toBe(false);
});
}, TEST_MS);
});
}
describe('a deterministic refusal after the model call (#9279)', () => {
test('stops its window after the one paid attempt on this build, and runs once on another build', async () => {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-9279-windows-'));
try {
const full = join(dir, 'refused-session.txt');
writeFileSync(full, transcript());
let paid = 0;
const run = async () => runCorpusWindows({
full, raw: readFileSync(full, 'utf8'), fileStat: corpusFileStat((await import('node:fs')).statSync(full)), maxWindows: 1,
overBudget: () => false, signal: new AbortController().signal, failures: { fingerprint: null },
extract: async () => {
await invokeAI({ operation: 'extract', model: 'anthropic:test', kind: 'chat' }, async () => { paid++; return 'facts'; }, () => null);
throw opError('page_body_segmented', 'The entity page is stored in segments.', 'Retrying refuses the same way.');
},
}).catch((e: unknown) => e);
await run();
expect(paid).toBe(1);
const record = readCorpusFailure(full)!;
expect(record).toMatchObject({ count: CORPUS_WINDOW_FAILURE_CAP, last_code: 'page_body_segmented', build: VERSION });
expect(await run()).toMatchObject({ status: 'dead_lettered' });
expect(paid).toBe(1);
expect(corpusFailureGate({ ...record, build: '0.0.0.1' }, record.key, null, null, Date.now())).toBe('run');
expect(corpusFailureGate({ ...record, last_code: 'provider_error' }, record.key, null, null, Date.now())).toBe('dead_lettered');
} finally { rmSync(dir, { recursive: true, force: true }); }
}, TEST_MS);
async function retryHeld(error: () => Error) {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-9279-retry-'));
const full = join(dir, 'held-session.txt');
writeFileSync(full, transcript());
const key = await corpusFrontierKey(full, 'held-session.txt');
writeFileSync(full + CORPUS_FAILURE_SUFFIX, JSON.stringify({ version: 1, key, source_incarnation: null, count: CORPUS_WINDOW_FAILURE_CAP,
first_at: 1, last_at: 1, last_code: 'page_body_segmented', fingerprint: null, rearmed: false, build: '0.0.0.1' }) + '\n');
let paid = 0;
await runCorpusWindows({
full, raw: readFileSync(full, 'utf8'), fileStat: corpusFileStat((await import('node:fs')).statSync(full)), maxWindows: 1,
overBudget: () => false, signal: new AbortController().signal, failures: { fingerprint: null },
extract: async () => {
await invokeAI({ operation: 'extract', model: 'anthropic:test', kind: 'chat' }, async () => { paid++; return 'facts'; }, () => null);
throw error();
},
}).catch((e: unknown) => e);
return { dir, paid, record: readCorpusFailure(full)! };
}
test('retries a held window automatically once, not on every later build', async () => {
const { dir, paid, record } = await retryHeld(() => opError('page_body_segmented', 'The entity page is stored in segments.', 'Retrying refuses the same way.'));
try {
expect(paid).toBe(1);
expect(record).toMatchObject({ count: CORPUS_WINDOW_FAILURE_CAP + 1, last_code: 'page_body_segmented', build: VERSION, upgrade_retried: true });
expect(corpusFailureGate({ ...record, build: '0.0.0.2' }, record.key, null, null, Date.now())).toBe('dead_lettered');
} finally { rmSync(dir, { recursive: true, force: true }); }
}, TEST_MS);
test('a transient failure on that retry starts a fresh count instead of stopping the window for good', async () => {
const { dir, paid, record } = await retryHeld(() => opError('unavailable', 'The provider timed out.', 'Retry later.'));
try {
expect(paid).toBe(1);
expect(record).toMatchObject({ count: 1, last_code: 'unavailable', upgrade_retried: true, held: true });
expect(corpusFailureGate(record, record.key, null, null, Date.now())).toBe('run');
const full = join(dir, 'held-session.txt');
const old = (Date.now() - (RETENTION_DAYS * CORPUS_UNINGESTED_RETENTION_FACTOR + 1) * DAY_MS) / 1000;
utimesSync(full, old, old);
gcCorpusTurnFiles(dir, RETENTION_DAYS * DAY_MS);
expect(existsSync(full)).toBe(true);
} finally { rmSync(dir, { recursive: true, force: true }); }
}, TEST_MS);
});