Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { readFileSync } from 'node:fs';
import type { BrainEngine } from '../engine.ts';
import { opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import type { Action } from '../agent-output.ts';
import { atomRetryInputKey, managedAtomSession, publishManagedAtoms, readAtomOrigin, resumeManagedAtoms, type AtomIntent, type ManagedAtomRetirement } from './atom-maintenance.ts';
import { isWriteReceipt, type WriteReceipt } from './types.ts';
import { anyAbortSignal } from '../abort-signals.ts';
import { MaintenanceWriteWait } from './maintenance-wait.ts';
const receiptFix = (requestId: string): Action => readFix('Reads the atom request\'s durable receipt: its state, outcome and error, read-only.',
{ argv: ['gbrain', 'write-request', '--', requestId] });
const drainFix = (sourceId: string): Action => ({
argv: ['gbrain', 'dream', '--drain', '--source', sourceId, '--json'], consent: ['paid'], actor: 'agent', requires_exclusive: false,
why: `Re-reads source ${sourceId}'s current content and extracts its atom backlog under a new run; extraction calls the configured LLM.`,
});
const assignFix = (sourceId: string): Action => readFix(`Lists the captured sessions held without a source and previews mapping them to ${sourceId}; writes nothing.`,
{ argv: ['gbrain', 'sweep', '--assign-corpus', sourceId] });
const pageFix = (sourceId: string, slug: string): Action => readFix(`Shows which page holds ${slug} in source ${sourceId} now, with its revision, read-only.`,
{ argv: ['gbrain', 'get', '--source', sourceId, '--', slug] });
/** A stop after a write was admitted reports that write (pending or committed), never `cancelled`. */
function stoppedRetry(reason: unknown, receipts: WriteReceipt[]): Error {
const pending = receipts.find(receipt => ['queued', 'running', 'recovering'].includes(receipt.state));
if (pending) {
const error = opError('write_pending', 'The atom retry stopped with an admitted write still pending.',
`The retry stopped (${reason instanceof Error ? reason.message : String(reason)}) after atom write ${pending.request_id} was admitted; it may still commit. Inspect its receipt and wait for it to settle before approving another attempt.`,
{ fix: receiptFix(pending.request_id) });
error.writeRequest = pending;
return Object.assign(error, { write_requests: receipts });
}
if (!receipts.length && reason instanceof Error) return reason;
return Object.assign(new DOMException(reason instanceof Error ? reason.message : String(reason ?? 'Atom retry aborted'), 'AbortError'),
{ write_requests: receipts });
}
/**
* The minion worker aborts `signal` at the job deadline; `deadlineAtMs` also
* bounds the shared write wait and stops the retry at the next stage boundary.
*/
export async function retryManagedAtomBatch(engine: BrainEngine, sourceId: string, requestId: string, retryId: string,
opts: { signal?: AbortSignal; deadlineAtMs?: number | null } = {}): Promise<Record<string, unknown>> {
let receipts: WriteReceipt[] = [];
let stop: ReturnType<typeof anyAbortSignal> | undefined;
const check = () => {
if (opts.deadlineAtMs != null && Date.now() >= opts.deadlineAtMs) throw stoppedRetry(new Error('Atom retry stopped at the job deadline.'), receipts);
const signal = stop?.signal ?? opts.signal;
if (signal?.aborted) throw stoppedRetry(signal.reason, receipts);
};
check();
const { withRefreshingLock } = await import('../db-lock.ts');
const { cycleLockIdFor } = await import('../cycle.ts');
try {
return await withRefreshingLock(engine, cycleLockIdFor(sourceId), async lockSignal => {
stop = anyAbortSignal(opts.signal ? [opts.signal, lockSignal] : [lockSignal]);
check();
const wait = new MaintenanceWriteWait(opts.deadlineAtMs ?? null);
const session = await managedAtomSession(engine, sourceId, { requestId, retryId }, wait, stop.signal);
check();
if (!session?.retry) throw opError('invalid_params', 'Explicit atom retry requires a managed source.',
`Source ${sourceId} is not under managed persistence, so retained atom batch ${requestId} cannot be retried there; nothing was started. Run the ordinary atom drain for the source instead (it calls the configured LLM, so confirm the spend).`,
{ fix: drainFix(sourceId) });
const retry = session.retry;
const origin = retry.origin;
if (origin.kind === 'transcript') {
const cfg = await (await import('../config.ts')).loadConfigWithEngine(engine) as unknown as { dream?: { synthesize?: { session_corpus_dir?: string } } } | null;
const { transcriptSourceHold } = await import('../cycle/synthesize-source-routing.ts');
const hold = await transcriptSourceHold(engine, origin.locator, { corpusDir: cfg?.dream?.synthesize?.session_corpus_dir ?? null, sourceId });
check();
if (hold) throw opError('transcript_source_mismatch', `The transcript of atom batch ${requestId} does not belong to source ${sourceId}, so nothing was started.`,
hold.owner
? `Transcript ${origin.locator} is a captured session of source ${hold.owner}; its atoms are extracted only by a run for that source, never retried into ${sourceId}. Run the atom drain for ${hold.owner} instead (it calls the configured LLM, so confirm the spend).`
: hold.reason === 'transcript_outside_corpus'
? `Transcript ${origin.locator} is not in the session corpus, and only source default reads transcripts from outside it, so the batch is not retried into ${sourceId}. Read the batch's receipt and report it to the user.`
: `Transcript ${origin.locator} is a captured session with no known source (${hold.reason}), so its atoms are not retried into ${sourceId}. Ask the user which source the session belongs to; gbrain sweep --assign-corpus <source> maps it, then a run for that source extracts it.`,
{ reason: hold.reason, fix: hold.owner ? drainFix(hold.owner) : hold.reason === 'transcript_outside_corpus' ? receiptFix(requestId) : assignFix(sourceId) });
}
const item = origin.kind === 'page'
? { kind: 'page' as const, slug: origin.locator, content: (await engine.readPageSnapshot(origin.locator, { sourceId }))?.page.compiled_truth ?? '', contentHash: origin.contentHash }
: { kind: 'transcript' as const, filePath: origin.locator, content: readFileSync(origin.locator, 'utf8'), contentHash: origin.contentHash };
check();
const current = await readAtomOrigin(engine, session, item);
check();
// The retry runs against the current origin (its revision and visibility);
// only a change to the input the run key covers refuses it.
if (atomRetryInputKey(session, current) !== atomRetryInputKey(session, origin)) throw opError('source_changed', 'The original atom input changed; this retry cannot reuse it.',
`The ${origin.kind} that atom request ${requestId} extracted from in source ${sourceId} has changed since, so its retained batch no longer applies; nothing was started. Run a fresh atom drain, which extracts from the current content.`,
{ fix: drainFix(sourceId) });
const resumed = await resumeManagedAtoms(engine, session, current);
check();
if (resumed === 'done') return { status: 'completed', replayed: true, model_rerun: false };
const checkpoint = retry.expectedCheckpoint as Array<{ failure?: string }> | null;
if (checkpoint && !checkpoint[0]?.failure) return { status: 'completed', replayed: true, model_rerun: false };
const saved = retry.rows.filter(row => row.intent?.kind === 'managed_atom_page');
const deleted = retry.rows.filter(row => row.intent?.kind === 'managed_atom_delete');
if (saved.length || deleted.length) {
const atoms: Parameters<typeof publishManagedAtoms>[3] = [];
for (const row of saved) {
const p = row.intent as AtomIntent;
const target = await engine.readPageSnapshot(row.slug, { sourceId, includeDeleted: true });
check();
const revision = row.state === 'committed' ? row.outcome?.revision : p.expected_revision ?? null;
if (typeof revision !== 'string' && (row.state === 'committed' || revision !== null)) throw opError('storage_error', 'The retained atom publication revision is unavailable.',
`The receipt of atom page ${row.slug} (request ${row.request_id}) no longer records the revision it published against, so the retry cannot republish it; nothing was published. Read the batch's receipt, then run a fresh atom drain for source ${sourceId}.`,
{ fix: receiptFix(requestId) });
const pageId = row.state === 'committed' ? row.page_id ?? target?.page.id ?? null : row.page_id;
if ((target?.page.id ?? null) !== pageId || (target?.revision ?? null) !== revision) {
throw opError('page_identity_changed', 'An atom target changed independently of the failed publication.',
`Atom page ${row.slug} in source ${sourceId} was edited, created, deleted or replaced after request ${requestId} failed, so republishing would overwrite that change; nothing was published. Read the page, then run a fresh atom drain if its atoms still need extracting.`,
{ fix: pageFix(sourceId, row.slug) });
}
if (typeof p.content !== 'string') throw opError('storage_error', 'The retained atom publication content is unavailable.',
`The receipt of atom page ${row.slug} (request ${row.request_id}) no longer holds its content (the retained payload expired), so the retry cannot republish it; nothing was published. Read the batch's receipt, then run a fresh atom drain for source ${sourceId}.`,
{ fix: receiptFix(requestId) });
atoms.push({ slug: row.slug, content: p.content, links: p.links ?? [], expectedTarget: { pageId, revision } });
}
const retirements: ManagedAtomRetirement[] = [];
for (const row of deleted) {
const p = row.intent as AtomIntent;
const target = await engine.readPageSnapshot(row.slug, { sourceId, includeDeleted: true });
check();
const revision = row.state === 'committed' ? row.outcome?.revision : p.expected_revision;
if (typeof revision !== 'string' || row.page_id === null || !target ||
target.page.id !== row.page_id || target.revision !== revision || Boolean(target.page.deleted_at) !== (row.state === 'committed')) {
throw opError('page_identity_changed', 'An atom retirement target changed independently of the failed publication.',
`Atom page ${row.slug} in source ${sourceId}, which request ${requestId} was retiring, was edited, restored or replaced after the failure, so retiring it now would discard that change; nothing was published. Read the page and decide with the user whether it should still be retired.`,
{ fix: pageFix(sourceId, row.slug) });
}
retirements.push({ slug: row.slug, pageId: row.page_id, revision });
}
check();
receipts = await publishManagedAtoms(engine, session, current, atoms, undefined, retirements);
check();
return { status: 'completed', model_rerun: false, write_requests: receipts };
}
if (!retry.rows.some(row => row.outcome?.failure)) throw opError('invalid_params', 'This failed batch has no malformed extraction to retry.',
`Atom batch ${requestId} in source ${sourceId} did not fail on malformed model output, so a model rerun cannot fix it; nothing was started. Read its receipt for the recorded error and fix that cause instead.`,
{ fix: receiptFix(requestId) });
const { runPhaseExtractAtoms } = await import('../cycle/extract-atoms.ts');
check();
const result = await runPhaseExtractAtoms(engine, { sourceId, _managedRetry: { requestId, retryId },
signal: stop.signal, attempt: { writeWait: wait },
_pages: item.kind === 'page' ? [item] : [], _transcripts: item.kind === 'transcript' ? [item] : [] });
receipts = Array.isArray(result.details?.write_requests) ? result.details.write_requests.filter(isWriteReceipt) : [];
check();
if (result.status !== 'ok') {
const receipt = receipts.at(-1);
const pending = receipt && ['queued', 'running', 'recovering'].includes(receipt.state);
const inspected = receipt?.request_id ?? requestId;
const error = opError(pending ? 'write_pending' : 'extraction_failed', 'The explicit atom retry did not complete; inspect its retained receipt before approving another attempt.',
pending
? `The retry's atom write ${inspected} in source ${sourceId} is still queued or running and may still commit. Inspect its receipt and wait for it to settle; do not approve another attempt meanwhile.`
: `The retry of atom batch ${requestId} in source ${sourceId} ran the model again and failed. Read the receipt for the recorded error before asking the user to approve another paid attempt.`,
{ fix: receiptFix(inspected) });
if (receipt) error.writeRequest = receipt;
throw error;
}
return { ...result, model_rerun: true };
}, { ttlMinutes: 5 });
} catch (error) {
// Lease loss reported at teardown, after work returned durable receipts.
if (receipts.length && error instanceof Error && error.name === 'LockStolenError') throw stoppedRetry(error, receipts);
throw error;
} finally { stop?.dispose(); }
}