Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.5 KB
Raw Blame
/**
 * W4: the doctor's alert verdict (`DoctorReport.alert`), what an agent cron
 * pages on instead of `health_score`.
 *
 * Only the page class pages (PAGE_CHECK_LEVELS in src/core/doctor-categories.ts):
 *   - act: a page-class check reported its paging status; each item keeps the
 *     check's own rendered fix (argv or MCP call, consent, actor, verify).
 *   - unknown: a page-class check did not run fresh in this run (over its
 *     budget, stopped at a bound, errored, served from its last known result,
 *     skipped by the tier, or the database checks did not run). Each item names
 *     the check, the budget it ran under and the command that measures it.
 *   - none: every page-class check ran fresh and none pages.
 * act dominates unknown, which dominates none; both item lists are kept.
 *
 * gbrain doctor --alert runs the page class alone (the alert tier: every
 * page-class entry, fresh, under ALERT_BUDGET_MS_DEFAULT), so a healthy brain
 * reaches none on every run. It keeps a consecutive-unknown counter per brain
 * on the file plane (doctor-alert-state.json under GBRAIN_HOME) so a cron can
 * page on the second unknown in a row. A remote report omits check messages
 * (they can carry local paths) and gives a host-admin step where no MCP fix exists.
 */
import { createHash } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { atomicWriteFileSync } from '../../core/atomic-write.ts';
import { cliRenderContext, redactForTransport, renderAction, type RenderContext, type RenderedAction } from '../../core/agent-output.ts';
import { gbrainPath, loadConfig } from '../../core/config.ts';
import { PAGE_CHECK_LEVELS, PAGE_CHECK_NAMES } from '../../core/doctor-categories.ts';
import { DOCTOR_ALERT_ACT_EXIT_CODE, DOCTOR_ALERT_UNKNOWN_EXIT_CODE } from '../../core/exit-codes.ts';
import type { Check, DoctorReport } from '../doctor.ts';
import { fixLine } from './check-fix.ts';
import { writeJsonDocument } from '../../core/cli-force-exit.ts';
import { entryRunsAt } from './budget.ts';
import { agentFix, type FixUnavailableReason } from './check-fix.ts';
import type { DoctorTier } from './context.ts';
import { DOCTOR_CHECK_REGISTRY } from './registry.ts';

export type AlertLevel = 'none' | 'act' | 'unknown';
export type AlertUnknownReason = 'budget' | 'bound' | 'errored' | 'last_known' | 'not_run';

export interface AlertActItem {
  /** Stable: the check's own details.code when it has one, else the check name. */
  code: string;
  check: string;
  status: 'warn' | 'fail';
  /** The check's message; omitted on a remote report (it can name local paths). */
  message?: string;
  docs: string;
  fix?: RenderedAction;
  fix_unavailable_reason?: FixUnavailableReason;
}

export interface AlertUnknownItem {
  code: 'doctor_alert_unknown';
  check: string;
  reason: AlertUnknownReason;
  /** The budget the check ran under, when a budget stopped it. */
  budget_ms: number | null;
  message: string;
  /** Measures this check fresh (with a larger budget when a budget stopped it). */
  fix: RenderedAction;
  /** Set by doctor --alert: how many alert runs in a row (this one included) ended unknown. */
  consecutive_unknown_runs?: number;
}

export interface DoctorAlert {
  level: AlertLevel;
  items: AlertActItem[];
  unknown: AlertUnknownItem[];
  /** Set by doctor --alert: alert runs in a row ending unknown (0 after a none or act run); null when the state file can be neither read nor written. */
  consecutive_unknown?: number | null;
  docs: string;
}

/** The alert tier's default end-to-end budget (connect included); --budget-ms overrides it. */
export const ALERT_BUDGET_MS_DEFAULT = 30_000;
export const ALERT_DOCS = 'docs/guides/troubleshooting.md#doctor-alert';
const STATE_FILE = 'doctor-alert-state.json';

/** The arguments --alert runs with: the page class alone (unless --tier / --only is given) under the alert budget, skill checks skipped. */
export function alertRunArgs(args: readonly string[]): string[] {
  const has = (flag: string) => args.some((a) => a === flag || a.startsWith(`${flag}=`));
  const out = [...args];
  if (!has('--tier') && !has('--only')) out.push('--only', [...PAGE_CHECK_NAMES].join(','));
  if (!has('--budget-ms')) out.push('--budget-ms', String(ALERT_BUDGET_MS_DEFAULT));
  if (!args.includes('--scope=brain')) out.push('--scope=brain');
  return out;
}

/**
 * The page-class checks this run executed: none when the database checks did not run (no connection check that is
 * ok), else every page-class check whose entry runs at tier and that `only` (--only) names, when given. A page-class
 * check missing from such a run did not apply.
 */
export function alertRanChecks(checks: readonly Pick<Check, 'name' | 'status'>[], tier: DoctorTier, only?: ReadonlySet<string> | null): Set<string> {
  if (!checks.some((c) => c.name === 'connection' && c.status === 'ok')) return new Set();
  return new Set([...PAGE_CHECK_NAMES].filter((name) => (!only || only.has(name)) && DOCTOR_CHECK_REGISTRY.some((e) => e.emits.includes(name) && entryRunsAt(e.tier, tier))));
}

function unknownReason(c: Check): AlertUnknownReason | null {
  if (c.details?.last_known !== undefined) return 'last_known';
  if (c.details?.health === 'unknown') return c.details.reason === 'budget' ? 'budget' : c.details.reason === 'bound' ? 'bound' : 'errored';
  if (c.fix_unavailable_reason === 'check_errored') return 'errored';
  if (c.readiness_state === 'unknown' && c.status !== 'fail') return 'not_run';
  return null;
}

/** An advisory warning (details.advisory, e.g. the opt-in autopilot install suggestion) never pages; a failure always does. */
function pages(c: Check): boolean {
  return c.status === 'fail' || (c.status === 'warn' && PAGE_CHECK_LEVELS.get(c.name) === 'warn' && c.details?.advisory !== true);
}

function isRendered(fix: Check['fix']): fix is RenderedAction {
  return !!fix && typeof (fix as RenderedAction).next === 'string';
}

const UNKNOWN_WHY: Record<AlertUnknownReason, string> = {
  budget: 'did not finish within its budget',
  bound: 'stopped at one of its own bounds before reading everything',
  errored: 'could not be checked',
  last_known: 'was reported from its last known result, not measured in this run',
  not_run: 'did not run (the database checks did not run, or this tier or report skips it)',
};

/**
 * The alert verdict of a finalized check list (computeDoctorReport calls it after rendering fixes). ran: the
 * page-class checks this run executed, so one it did not emit did not apply; without it a missing page-class check
 * is unknown (a focused or remote report that never runs it).
 */
export function computeAlert(checks: readonly Check[], opts: { ran?: ReadonlySet<string>; render?: RenderContext } = {}): DoctorAlert {
  const render = opts.render ?? cliRenderContext();
  const remote = render.transport !== 'cli';
  const items: AlertActItem[] = [];
  const unknown: AlertUnknownItem[] = [];
  for (const name of PAGE_CHECK_NAMES) {
    const found = checks.filter((c) => c.name === name);
    if (found.length === 0) {
      if (!opts.ran?.has(name)) unknown.push(unknownItem(name, 'not_run', null, render));
      continue;
    }
    const paging = found.find((c) => unknownReason(c) === null && pages(c));
    const stale = found.find((c) => unknownReason(c) !== null);
    if (paging) items.push(actItem(paging, remote, render));
    else if (stale) unknown.push(unknownItem(name, unknownReason(stale)!, stale, render));
  }
  const level: AlertLevel = items.length ? 'act' : unknown.length ? 'unknown' : 'none';
  const alert: DoctorAlert = { level, items, unknown, docs: ALERT_DOCS };
  return remote ? redactForTransport(alert, 'http') : alert;
}

function actItem(c: Check, remote: boolean, render: RenderContext): AlertActItem {
  const code = typeof c.details?.code === 'string' ? c.details.code : c.name;
  const docs = typeof c.details?.docs === 'string' ? c.details.docs : `${ALERT_DOCS}-act`;
  const fix = isRendered(c.fix) ? c.fix : remote
    ? renderAction({ argv: ['gbrain', 'doctor', '--only', c.name, '--json'], consent: [], actor: 'host_admin', requires_exclusive: false, docs,
      why: `Run on the brain host: the local report says what ${c.name} found and how to fix it.` }, render)
    : undefined;
  return {
    code, check: c.name, status: c.status as 'warn' | 'fail',
    ...(remote ? {} : { message: c.message }),
    docs,
    ...(fix ? { fix } : { fix_unavailable_reason: c.fix_unavailable_reason ?? 'unstructured' }),
  };
}

function unknownItem(name: string, reason: AlertUnknownReason, c: Check | null, render: RenderContext): AlertUnknownItem {
  const budgetMs = typeof c?.details?.budget_ms === 'number' ? c.details.budget_ms : null;
  const fix = reason === 'budget' && isRendered(c?.fix) ? c!.fix as RenderedAction
    : renderAction(agentFix(['gbrain', 'doctor', '--only', name, '--budget-ms', '0', '--json'],
      'Measures only this check now, with no overall budget; read-only.', name, { docs: ALERT_DOCS }), render);
  const budget = budgetMs !== null ? ` (budget ${budgetMs} ms)` : '';
  const step = fix.command ?? (fix.mcp ? `the ${fix.mcp.tool} tool` : 'the fix');
  return {
    code: 'doctor_alert_unknown', check: name, reason, budget_ms: budgetMs,
    message: `${name} ${UNKNOWN_WHY[reason]}${budget}, so its health is unknown, not clear. Measure it with ${step}, `
      + 'run the full tier (gbrain doctor --alert --tier standard --json) or raise the alert budget (--budget-ms).',
    fix,
  };
}

/** The brain this home's alert state is kept for: a hash of its database URL or path, never the value itself. */
function brainKey(): string {
  let id = 'default';
  try {
    const cfg = loadConfig();
    id = cfg?.database_url ?? cfg?.database_path ?? 'default';
  } catch { /* unreadable config: one shared key */ }
  return createHash('sha256').update(id).digest('hex').slice(0, 16);
}

/**
 * doctor --alert: count this run into the brain's consecutive-unknown streak (reset by a none or act run), stamp the
 * count on the alert and its unknown items, and persist it atomically. A home that cannot be written (read-only)
 * still gets this run's count from what it read; null only when it could neither read nor write the state.
 */
export function recordAlertStreak(alert: DoctorAlert, now = new Date()): DoctorAlert {
  const path = gbrainPath(STATE_FILE);
  type BrainState = { consecutive_unknown: number; last_level: AlertLevel; updated_at: string };
  let brains: Record<string, BrainState> = {};
  let readable = true;
  try {
    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
    if (parsed && typeof parsed.brains === 'object' && parsed.brains) brains = parsed.brains;
  } catch (err) {
    readable = (err as NodeJS.ErrnoException)?.code === 'ENOENT';
  }
  const key = brainKey();
  const prev = Number(brains[key]?.consecutive_unknown ?? 0);
  const count = alert.level === 'unknown' ? (Number.isSafeInteger(prev) && prev > 0 ? prev : 0) + 1 : 0;
  brains[key] = { consecutive_unknown: count, last_level: alert.level, updated_at: now.toISOString() };
  let written = true;
  try {
    atomicWriteFileSync(path, JSON.stringify({ schema_version: 1, brains }, null, 2) + '\n', { mode: 0o600 });
  } catch {
    written = false;
  }
  if (!readable && !written) return { ...alert, consecutive_unknown: null };
  return {
    ...alert,
    consecutive_unknown: count,
    unknown: alert.unknown.map((u) => ({ ...u, consecutive_unknown_runs: count, message: `${u.message} Unknown for ${count} consecutive alert run(s).` })),
  };
}

/** The exit status of a doctor --alert run: 0 none, 17 act, 18 unknown. */
export function alertExitCode(level: AlertLevel): number {
  return level === 'act' ? DOCTOR_ALERT_ACT_EXIT_CODE : level === 'unknown' ? DOCTOR_ALERT_UNKNOWN_EXIT_CODE : 0;
}

/** `gbrain doctor --alert`: print the verdict (with this brain's consecutive-unknown count) and return the exit code. */
export function printAlertReport(report: DoctorReport, json: boolean): number {
  const alert = recordAlertStreak(report.alert!);
  if (json) {
    void writeJsonDocument(JSON.stringify({ ...report, alert }));
    return alertExitCode(alert.level);
  }
  const streak = alert.level === 'unknown' && alert.consecutive_unknown ? ` (${alert.consecutive_unknown} consecutive unknown run(s))` : '';
  console.log(`Alert: ${alert.level}${streak}`);
  for (const item of alert.items) {
    console.log(`  [ACT] ${item.check}: ${item.message ?? item.code}`);
    const fix = fixLine(item.fix);
    if (fix) console.log(`    Fix: ${fix}`);
  }
  for (const item of alert.unknown) console.log(`  [UNKNOWN] ${item.check}: ${item.message}`);
  console.log(`Health score: ${report.health_score}/100 (context only; page on the alert level).`);
  return alertExitCode(alert.level);
}