Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Slow whole-brain reads (sync status, sources status, doctor, orphans, anomalies, status, diag) tell their caller
* what is happening while they run, so an agent whose harness cuts the command off cannot mistake silence for an
* empty result:
*
* - one stderr line when the read starts, then one every 10 s while it runs (stdout stays the one result);
* - the `--json` document carries `elapsed_ms` and `complete`, and `incomplete` lists each field a budget or
* bound left out (the existing markers: a `*_read` field with `status: 'not_read'`, `complete: false`,
* `items_complete: false`, `budget_hit: true`, a doctor check unknown for its budget);
* - SIGTERM, SIGHUP or SIGINT before the result prints one stderr line and, under `--json`, one `interrupted`
* document saying how long it ran and that no result was read.
*
* One read per CLI process, so module state is safe.
*/
export const READ_HEARTBEAT_EVERY_MS = 10_000;
export interface IncompleteField { field: string; reason: 'not_read' | 'bounded' | 'budget' | 'error' }
interface ActiveRead {
label: string;
startedAt: number;
json: boolean;
timer: ReturnType<typeof setInterval> | null;
sigint: (() => void) | null;
writeErr: (line: string) => void;
}
let active: ActiveRead | null = null;
let interruptWriter: ((doc: Record<string, unknown>) => void) | null = null;
/** The CLI's stdout writer for the `interrupted` document (cli-force-exit.ts registers it, so this module imports nothing). */
export function setInterruptedDocumentWriter(write: ((doc: Record<string, unknown>) => void) | null): void { interruptWriter = write; }
const seconds = (ms: number) => Math.round(ms / 1000);
/**
* Starts the heartbeat for one read. `json`: the caller asked for `--json` (an interrupt then writes the
* `interrupted` document). Returns the function that ends the read.
*/
export function beginSlowRead(label: string, opts: { json: boolean; everyMs?: number; writeErr?: (line: string) => void; now?: () => number }): () => void {
endSlowRead();
const now = opts.now ?? Date.now;
const writeErr = opts.writeErr ?? (line => { try { process.stderr.write(line + '\n'); } catch { /* stderr gone */ } });
const read: ActiveRead = { label, startedAt: now(), json: opts.json, timer: null, sigint: null, writeErr };
active = read;
writeErr(`[gbrain] reading ${label}; large brains can take minutes. Progress prints here every ${seconds(opts.everyMs ?? READ_HEARTBEAT_EVERY_MS)} s; the result prints on stdout when it is ready.`);
read.timer = setInterval(() => writeErr(`[gbrain] still reading ${label} (${seconds(now() - read.startedAt)} s so far); no result yet.`), opts.everyMs ?? READ_HEARTBEAT_EVERY_MS);
read.timer.unref?.();
if (process.listenerCount('SIGINT') === 0) {
read.sigint = () => { noteInterrupted('SIGINT', now()); process.exit(130); };
process.on('SIGINT', read.sigint);
}
return endSlowRead;
}
/** Ends the active read: the heartbeat stops and an interrupt no longer prints a note. Idempotent. */
export function endSlowRead(): void {
if (!active) return;
if (active.timer) clearInterval(active.timer);
if (active.sigint) process.off('SIGINT', active.sigint);
active = null;
}
/** Milliseconds since the active read started; null when none is active. */
export function slowReadElapsedMs(now = Date.now()): number | null {
return active ? now - active.startedAt : null;
}
const MAX_NODES = 50_000;
/** Every field a budget or bound left out of `doc`, by path (`sources[0].holds_read`), from the existing markers. */
export function incompleteFields(doc: unknown): IncompleteField[] {
const out: IncompleteField[] = [];
let nodes = 0;
const walk = (value: unknown, path: string, depth: number) => {
if (value === null || typeof value !== 'object' || depth > 8 || ++nodes > MAX_NODES) return;
if (Array.isArray(value)) { value.forEach((item, i) => walk(item, `${path}[${i}]`, depth + 1)); return; }
const record = value as Record<string, unknown>;
if (path && record.status === 'not_read') out.push({ field: path, reason: 'not_read' });
if (path && record.health === 'unknown' && record.reason === 'budget') out.push({ field: path, reason: 'budget' });
for (const [key, child] of Object.entries(record)) {
const at = path ? `${path}.${key}` : key;
if (child === false && (key === 'complete' || key.endsWith('_complete')) && at !== 'complete') out.push({ field: at, reason: 'bounded' });
else if (child === true && key === 'budget_hit') out.push({ field: at, reason: 'budget' });
else walk(child, at, depth + 1);
}
};
walk(doc, '', 0);
return out;
}
/**
* The read's `--json` document with `elapsed_ms` (since the read started) and `complete` (false when the document
* says it is paged or a field was not read; `incomplete` names each). A field the document already sets wins; an
* error envelope gets `elapsed_ms` only; a non-object document (a bare array) is returned as is. Ends the read.
*/
export function withReadMeta<T>(doc: T, now = Date.now()): T {
const elapsed = slowReadElapsedMs(now);
endSlowRead();
if (elapsed === null || doc === null || typeof doc !== 'object' || Array.isArray(doc)) return doc;
const record = doc as Record<string, unknown>;
// An error envelope read nothing: it gains the elapsed time, never a completeness claim.
if (record.error !== undefined && record.error !== null) return (record.elapsed_ms === undefined ? { ...record, elapsed_ms: elapsed } : record) as T;
const incomplete = incompleteFields(record);
const complete = record.complete !== false && incomplete.length === 0;
return { ...record, ...(record.elapsed_ms === undefined ? { elapsed_ms: elapsed } : {}), ...(record.complete === undefined ? { complete } : {}),
...(incomplete.length && record.incomplete === undefined ? { incomplete } : {}) } as T;
}
/**
* A signal arrived while a read was active: one stderr line and, under `--json`, the `interrupted` document.
* Returns false (and writes nothing) when no read is active.
*/
export function noteInterrupted(signal: string, now = Date.now()): boolean {
const read = active;
if (!read) return false;
endSlowRead();
const elapsedMs = now - read.startedAt;
const message = `Interrupted by ${signal} after ${seconds(elapsedMs)} s while reading ${read.label}, before the result was ready. Nothing was read, so this is not an empty result.`;
read.writeErr(`[gbrain] ${message} Re-run with a longer timeout; large brains can take minutes.`);
if (read.json) {
interruptWriter?.({ error: 'interrupted', code: 'interrupted', message,
suggestion: 'Re-run the same command with a longer timeout (large brains can take minutes), or run `gbrain diag --json` for a bounded summary.',
signal, read: read.label, elapsed_ms: elapsedMs, complete: false, contract_version: 1 });
}
return true;
}