Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Agent-contract health log (agent operator wave E11 seam, landed with A1).
*
* Dispatch, renderCliError and requireConsent append one line per
* NON-SUCCESS outcome: `{ts, op|command, transport, code, has_suggestion |
* effects, outcome}`. Never params, never messages: only codes and shapes.
* Fail-open and synchronous (one small O_APPEND write per event, safe on the
* exit path). Bounded: the file is truncated to its newest half once it
* passes MAX_BYTES. Doctor's `agent_contract` check (Lane E) reads it.
*
* Path: `<GBRAIN_HOME>/agent-contract/events.jsonl` via gbrainPath.
*/
import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { dirname } from 'node:path';
import { gbrainPath } from './config.ts';
import type { Effect, Transport } from './agent-output.ts';
import { VERSION } from '../version.ts';
const MAX_BYTES = 1024 * 1024;
export interface AgentContractEvent {
op?: string;
command?: string;
transport: Transport;
code: string;
has_suggestion?: boolean;
effects?: Effect[];
outcome?: string;
/** Internal normaliser fault class (never a message). */
fault?: string;
/** #6629, #6758: the gbrain release that wrote the event (stamped on every event; absent on lines older builds wrote). */
version?: string;
/** #6629: the `--json` guard mode the event concerns. */
guard?: 'document' | 'ndjson';
/** #6629: the process exit code the event was recorded at. */
exit_code?: number;
}
export function agentContractLogPath(): string {
return gbrainPath('agent-contract', 'events.jsonl');
}
/** Append one bounded JSONL line. Fail-open: logging can never change an outcome. */
export function appendBoundedJsonl(path: string, record: Record<string, unknown>, maxBytes: number = MAX_BYTES): void {
try {
mkdirSync(dirname(path), { recursive: true });
appendFileSync(path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
if (statSync(path).size <= maxBytes) return;
const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
writeFileSync(path, `${lines.slice(Math.floor(lines.length / 2)).join('\n')}\n`, { mode: 0o600 });
} catch { /* fail-open */ }
}
/** #6758: every event names the build that wrote it, so doctor can tell history from a current fault. */
export function recordAgentContractEvent(event: AgentContractEvent): void {
appendBoundedJsonl(agentContractLogPath(), { ts: new Date().toISOString(), ...event, version: event.version ?? VERSION });
}
/** Read back recent events (newest last). Never throws. */
export function readAgentContractEvents(limit = 500): Array<AgentContractEvent & { ts: string }> {
try {
const lines = readFileSync(agentContractLogPath(), 'utf8').split('\n').filter(Boolean);
return lines.slice(-limit).map(l => JSON.parse(l));
} catch {
return [];
}
}