Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
2.8 KB
Raw Blame
/**
 * 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 [];
  }
}