Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.0 KB
Raw Blame
/**
 * Doctor checks speak the agent operator contract (agent-first operator wave,
 * Lane E1/E2): every non-ok check carries a `fix` (Action) or a
 * `fix_unavailable_reason`, the generic "Could not check X" sites go through
 * `checkError()`, and a capability that is off by choice or not applicable is
 * reported `ok` + `severity: 'info'` + `readiness_state` with the enable
 * command as `fix` (information, never coaching).
 *
 * Stored checks carry `Action`; `finalizeCheckFixes` renders them for the
 * report's transport (CLI `gbrain doctor --json`, MCP `run_doctor`).
 */
import { cliRenderContext, redactForTransport, renderAction, type Action, type RenderContext, type RenderedAction } from '../../core/agent-output.ts';
import { embeddingEnablement, type ReadinessEntry, type ReadinessState } from '../../core/readiness.ts';
import { loadConfig } from '../../core/config.ts';
import { classifyPgAccessError } from '../../core/pg-access-classify.ts';
import { brainRoutingArgs } from '../../core/brain-resolver.ts';
import { repairForCheck } from '../../core/repair/registry.ts';
import type { Check } from '../doctor.ts';

/**
 * Why a non-ok check has no runnable `fix`:
 * - `check_errored`: the probe itself failed, so there is nothing to repair yet (message carries the error).
 * - `operator_judgement`: the finding needs a human decision about the data; the message explains it.
 * - `no_safe_automatic_fix`: a fix exists only as a manual, case-by-case repair.
 * - `unstructured`: legacy check whose guidance is still prose in `message` (shrinking; see check-fix tests).
 */
export type FixUnavailableReason = 'check_errored' | 'operator_judgement' | 'no_safe_automatic_fix' | 'unstructured';

/** Agent-contract fields every doctor Check may carry (additive; schema_version stays 2). */
export interface CheckAgentFields {
  /** Stored as an Action; rendered (RenderedAction: `next`, `command`, absolute `docs`) in reports. */
  fix?: Action | RenderedAction;
  fix_unavailable_reason?: FixUnavailableReason;
  /** `info`: status stays `ok`; the capability is off by choice or not applicable (readiness_state says which). */
  severity?: 'info';
  readiness_state?: ReadinessState;
}

interface CheckLike extends CheckAgentFields {
  name: string;
  status: 'ok' | 'warn' | 'fail';
  message: string;
  details?: Record<string, unknown>;
}

/** The read-only verification every doctor fix points at. */
export function doctorVerify(check: string): { argv: string[] } {
  return { argv: ['gbrain', 'doctor', '--only', check, '--json'] };
}

/** A gbrain command the agent may run with no consent (read-only or a reversible local repair). */
export function agentFix(argv: string[], why: string, verifyCheck: string, extra: Partial<Action> = {}): Action {
  return { argv, consent: [], actor: 'agent', why, verify: doctorVerify(verifyCheck), requires_exclusive: false, ...extra };
}

/**
 * A low brain score's next step: the read-only remediation plan, which names
 * the job and repair steps that raise each score component, their cost, and
 * the highest score this brain can reach (a keyless brain's embed share stays 0).
 */
export function brainScorePlanFix(): Action {
  return agentFix(['gbrain', 'doctor', '--remediation-plan', '--json', ...brainRoutingArgs()],
    'The plan lists which steps raise each score component, what they cost and the reachable maximum; it changes nothing.', 'brain_score');
}

/**
 * Information, not a problem: status `ok`, `severity: 'info'`. Use for a
 * capability that is `disabled_by_choice` or `not_applicable` (keyless brain,
 * empty brain, no serve running). `fix` is the enable command, if any.
 */
export function infoCheck(name: string, message: string, state: ReadinessState, fix?: Action, details?: Record<string, unknown>): Check {
  return {
    name, status: 'ok' as const, message, severity: 'info' as const, readiness_state: state,
    ...(fix ? { fix } : {}), ...(details ? { details } : {}),
  };
}

/**
 * The one embedding-enable command (A7 `embeddingEnablement`: resolved
 * datastore, a keyed provider, pages and facts kept) for doctor checks on a
 * keyless brain. Undefined when there is no readable config.
 */
export function keylessEnablementFix(): Action | undefined {
  try {
    const cfg = loadConfig();
    return cfg ? embeddingEnablement(cfg) : undefined;
  } catch {
    return undefined;
  }
}

/** A readiness entry rendered as a doctor info check (keeps its why and enable fix). */
export function readinessInfoCheck(name: string, entry: ReadinessEntry, message?: string): Check {
  return infoCheck(name, message ?? entry.why, entry.state, entry.fix);
}

/**
 * The one shape for "this check could not run": `warn`, the original
 * `Could not <what>: <error>` message, and either a DB-access fix (when the
 * error classifies as a database access problem) or
 * `fix_unavailable_reason: 'check_errored'`.
 */
export function checkError(name: string, what: string, err?: unknown, opts: { status?: 'warn' | 'fail'; details?: Record<string, unknown> } = {}): Check {
  const msg = err === undefined ? '' : err instanceof Error ? err.message : String(err);
  const message = msg ? `Could not ${what}: ${msg}` : `Could not ${what}`;
  let fix: Action | undefined;
  if (err !== undefined) {
    try {
      const d = classifyPgAccessError(err);
      if (d.reason !== 'unknown') {
        fix = agentFix(['gbrain', 'db-repair'], `The database refused the check (${d.reason}). \`gbrain db-repair\` diagnoses it without changing anything.`, name,
          { docs: 'docs/ENGINES.md#engine-detection-and-access-repair' });
      }
    } catch { /* classification is best-effort */ }
  }
  return {
    name, status: opts.status ?? 'warn', message,
    ...(fix ? { fix } : { fix_unavailable_reason: 'check_errored' as const }),
    ...(opts.details ? { details: opts.details } : {}),
  };
}

/**
 * Wave B decision #10: a check whose scan reads whole page bodies skips pages
 * stored in segments (their body columns are NULL). It reports how many with
 * `skipped_segmented: n` and a message ending in `skipped (segmented): n`,
 * so a segmented brain never looks healthier than it was checked to be.
 * n = 0 returns the check unchanged.
 */
export function withSkippedSegmented<T extends { status: Check['status']; message: string; skipped_segmented?: number }>(check: T, n: number): T {
  if (!n) return check;
  return { ...check, skipped_segmented: n,
    message: `${check.message} skipped (segmented): ${n} page(s) store their body in segments, and this check reads whole bodies, so it did not check them.` };
}

function isRendered(fix: Action | RenderedAction): fix is RenderedAction {
  return typeof (fix as RenderedAction).next === 'string';
}

/**
 * Report-time pass: render every stored `fix` for the caller's transport
 * (redacted on http: no local paths, PIDs or key names) and
 * mark any non-ok check that still has neither a fix nor a reason as
 * `unstructured` (its message is the guidance).
 */
export function finalizeCheckFixes<T extends CheckLike>(checks: readonly T[], render: RenderContext = cliRenderContext()): T[] {
  return checks.map((check) => {
    const c = render.transport === 'cli' ? withRepairPreviewFix(check) : check;
    if (c.fix) return isRendered(c.fix) ? c : { ...c, fix: redactForTransport(renderAction(c.fix, render), render.transport) };
    if (c.status === 'ok' || c.fix_unavailable_reason) return c;
    return { ...c, fix_unavailable_reason: 'unstructured' as const };
  });
}

/**
 * E1: a repairable finding on the local doctor carries its next step: the
 * read-only `gbrain repair <kind>` preview, which lists what the repair would
 * change and prints the exact apply command for the user to approve.
 */
function withRepairPreviewFix<T extends CheckLike>(check: T): T {
  if (check.status === 'ok' || check.fix || check.details?.health === 'unknown') return check;
  const kind = repairForCheck(check.name)?.kind;
  if (!kind) return check;
  return { ...check, fix: agentFix(['gbrain', 'repair', kind], 'Previews the repair without changing anything and prints the exact apply command; applying rewrites stored records, so ask the user first.', check.name) };
}

/** One-line human rendering of a check's fix (`Fix: <command>` / tool call), or null. */
export function fixLine(fix: CheckAgentFields['fix']): string | null {
  if (!fix) return null;
  const r = isRendered(fix) ? fix : renderAction(fix, cliRenderContext());
  const step = r.command ?? (r.mcp ? `${r.mcp.tool} ${JSON.stringify(r.mcp.arguments)}` : null);
  if (!step) return r.user_message ? `Ask the user: ${r.user_message}` : null;
  return r.next === 'run' ? step : `${step}  (${r.next.replace(/_/g, ' ')})`;
}

/**
 * E10: categories whose score is not evidence because their checks never ran.
 * When the `connection` check is present and not ok, no database check ran, so
 * a `brain` score of 100 would read as "healthy" — it is unknown.
 */
export function unknownScoreCategories(checks: readonly CheckLike[]): Array<'brain'> {
  const conn = checks.find((c) => c.name === 'connection');
  return conn && conn.status !== 'ok' ? ['brain'] : [];
}