Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.7 KB
Raw Blame
/**
 * #6696 B2: thin-client `gbrain doctor --tier ops` and `--only <check>`.
 *
 * The thin client asks the serve what it lists for this token (tools/list,
 * already filtered by scope) and sends a parameter only where it is
 * advertised:
 *
 *   1. `run_doctor` lists `tier` / `only` -> the serve runs the ops sections
 *      (admin scope) and the client prints that report;
 *   2. otherwise, when every requested check is one the bands cover (or the
 *      tier is ops) and `get_brain_health` is listed -> the read-scope bands,
 *      shown as checks (a token without admin lands here);
 *   3. otherwise (an older serve) -> the structured handoff
 *      `doctor_tier_unavailable`: run doctor on the brain host. The full
 *      thin-client report is never run in place of the request.
 */
import type { GBrainConfig } from './config.ts';
import { callRemoteTool, listRemoteTools, RemoteMcpError, unpackToolResult } from './mcp-client.ts';
import { isScopeErrorCode } from './error-catalogue.ts';
import { opError } from './ops/contract.ts';
import { renderCliError } from './agent-output.ts';
import { setCliExitVerdict, writeJsonDocument } from './cli-force-exit.ts';

/** The checks `get_brain_health` answers, and the band each is read from. */
export const BAND_CHECKS: ReadonlySet<string> = new Set(['persistence_capacity', 'persistence_terminal_failures']);

interface BandsResult {
  status: string;
  capacity: { band: string; days: string; max_pct_band: string; forecast: string };
  write_failures: { band: string; active_blockers: string; window_days: number | null };
  [section: string]: unknown;
}
interface ScopedCheck { name: string; status: 'ok' | 'warn' | 'fail'; message: string; details?: Record<string, unknown> }

/** Bands as doctor checks: `low` warns, `critical` fails, `unknown` warns with health unknown (never a clear band). */
export function bandChecks(bands: BandsResult, only: ReadonlySet<string> | null): ScopedCheck[] {
  const checks: ScopedCheck[] = [];
  const c = bands.capacity;
  if (!only || only.has('persistence_capacity')) {
    const status = c.band === 'critical' ? 'fail' : c.band === 'ok' ? 'ok' : 'warn';
    checks.push({ name: 'persistence_capacity', status, details: { band: c.band, days: c.days, max_pct_band: c.max_pct_band, forecast: c.forecast, ...(c.band === 'unknown' ? { health: 'unknown' } : {}) },
      message: c.band === 'unknown' ? 'Write capacity could not be read on the serve. Health is unknown.'
        : `Write capacity band ${c.band} (highest use ${c.max_pct_band}%, days to exhaustion ${c.days.replaceAll('_', ' ')}).${c.band === 'ok' ? '' : ' Run on the brain host: gbrain doctor --only persistence_capacity --json'}` });
  }
  const f = bands.write_failures;
  if (!only || only.has('persistence_terminal_failures')) {
    const blocked = f.active_blockers !== 'none' && f.active_blockers !== 'unknown';
    checks.push({ name: 'persistence_terminal_failures', status: f.band === 'unknown' || blocked ? 'warn' : 'ok',
      details: { band: f.band, active_blockers: f.active_blockers, window_days: f.window_days, ...(f.band === 'unknown' ? { health: 'unknown' } : {}) },
      message: f.band === 'unknown' ? 'Write failures could not be read on the serve. Health is unknown.'
        : `Unresolved write failures in your sources: ${f.band}; active blockers: ${f.active_blockers}.${blocked ? ' Run on the brain host: gbrain doctor --only persistence_terminal_failures --json' : ''}` });
  }
  return checks;
}

/** `tier` / `only` as parsed by the doctor dispatch (src/cli/commands/doctor.ts); `label` names the request in the handoff. */
export async function runScopedRemoteDoctor(config: GBrainConfig, req: { tier?: string; only: ReadonlySet<string> | null; json: boolean; label: string; alert?: boolean }): Promise<void> {
  const { tier, only, json } = req;
  const handoff = (why: string) => {
    const out = renderCliError(opError('doctor_tier_unavailable', `The remote brain cannot answer gbrain doctor ${req.label} for this client: ${why}`,
      'Run gbrain doctor --tier ops --json on the brain host, or upgrade and restart its serve.'), { json, command: 'doctor', tty: !!process.stderr.isTTY });
    if (out.stdout) process.stdout.write(out.stdout);
    if (out.stderr) process.stderr.write(out.stderr);
    setCliExitVerdict(out.exitCode);
  };
  if (tier !== undefined && tier !== 'ops') return handoff(`only the ops tier is served remotely (the ${tier} tier runs on the brain host).`);

  const tools = await listRemoteTools(config);
  const runDoctor = tools.find((t) => t.name === 'run_doctor');
  const needs = [...(tier ? ['tier'] : []), ...(only ? ['only'] : [])];
  if (runDoctor && needs.every((p) => runDoctor.params.includes(p))) {
    try {
      const report = unpackToolResult<{ status: string; checks: unknown[] }>(await callRemoteTool(config, 'run_doctor', { ...(tier ? { tier } : {}), ...(only ? { only: [...only] } : {}) }));
      if (req.alert) return printAlert(report, json);
      return print(report, json);
    } catch (e) {
      if (!(e instanceof RemoteMcpError && isScopeErrorCode(e.detail?.code, e.detail?.canonical_code, e.detail?.reason))) throw e;
    }
  }
  const bandsCover = !only || [...only].every((n) => BAND_CHECKS.has(n));
  if (bandsCover && tools.some((t) => t.name === 'get_brain_health')) {
    const bands = unpackToolResult<BandsResult>(await callRemoteTool(config, 'get_brain_health', {}));
    const checks = bandChecks(bands, only);
    const status = checks.some((c) => c.status === 'fail') ? 'unhealthy' : checks.some((c) => c.status === 'warn') ? 'warnings' : 'healthy';
    return print({ schema_version: 2, mode: 'bands', status, source: 'get_brain_health', ...(tier ? { tier } : {}), checks, bands }, json);
  }
  return handoff(runDoctor || tools.some((t) => t.name === 'get_brain_health')
    ? `this token cannot run ${only ? `the ${[...only].join(', ')} check(s)` : 'the ops tier'} remotely and the read-scope bands do not cover ${only ? 'them' : 'every ops section'}.`
    : 'the serve predates the doctor ops tier (run_doctor lists no tier or only parameter and get_brain_health is not served).');
}

/**
 * W4 `gbrain doctor --alert` on a thin client: the serve ran the page-class checks (run_doctor `only`); exit by its
 * alert verdict with this client's consecutive-unknown count. A serve older than the alert reports none: unknown.
 */
async function printAlert(report: Record<string, unknown>, json: boolean): Promise<void> {
  const { recordAlertStreak, alertExitCode, ALERT_DOCS } = await import('../commands/doctor/alert.ts');
  const served = report.alert as import('../commands/doctor/alert.ts').DoctorAlert | undefined;
  const alert = recordAlertStreak(served ?? { level: 'unknown', items: [], unknown: [], docs: ALERT_DOCS });
  if (!served) process.stderr.write('[gbrain doctor] the remote serve predates doctor --alert, so the verdict is unknown; upgrade and restart it.\n');
  if (json) void writeJsonDocument(JSON.stringify({ ...report, alert }));
  else {
    console.log(`Alert (remote): ${alert.level}`);
    for (const item of alert.items) console.log(`  [ACT] ${item.check}: ${item.fix?.command ?? item.fix?.user_message ?? item.code}`);
    for (const item of alert.unknown) console.log(`  [UNKNOWN] ${item.check}: ${item.message}`);
  }
  setCliExitVerdict(alertExitCode(alert.level));
}

function print(report: { status: string; checks: unknown[] } & Record<string, unknown>, json: boolean): void {
  if (json) void writeJsonDocument(JSON.stringify(report));
  else {
    console.log(`\nGBrain Health Check (remote${report.mode === 'bands' ? ', bands' : report.tier ? `, ${report.tier} tier` : ''})`);
    for (const c of report.checks as ScopedCheck[]) console.log(`  [${c.status === 'ok' ? 'OK' : c.status === 'warn' ? 'WARN' : 'FAIL'}] ${c.name}: ${c.message}`);
  }
  setCliExitVerdict(report.status === 'unhealthy' ? 1 : 0);
}