Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.6 KB
Raw Blame
/**
 * Doctor check registry contract (refactor wave 1, W4 doctor).
 *
 * `buildChecks` parses the argument vector once and resolves the skills dir
 * once into a DoctorContext; the runner in ./registry.ts calls every entry in
 * order with it. An entry returns the checks it produced, or STOP_DOCTOR to
 * end the run there (the two places master's buildChecks returned early).
 * Fields an entry writes for later entries are named explicitly below.
 */

import type { BrainEngine } from '../../core/engine.ts';
import type { DbUrlSource } from '../../core/config.ts';
import type { AutoFixReport } from '../../core/dry-fix.ts';
import type { createProgress } from '../../core/progress.ts';
import type { resolveSkillsDir } from '../check-resolvable.ts';
import type { Check } from '../doctor.ts';
import type { DoctorDeadline } from './budget.ts';
import type { BrainHealth } from '../../core/types.ts';

/** Returned by an entry to end the run; the checks gathered so far are the result. */
export const STOP_DOCTOR: unique symbol = Symbol('STOP_DOCTOR');

/**
 * #6696 B1: `--tier ops|quick|standard|deep`. `ops` runs only the entries tagged
 * `ops` (observational, under one absolute deadline); `quick` (#7142) adds the
 * entries tagged `quick` under its own deadline and reports every other check
 * from its last known result; `standard` (default) runs ops entries first, then
 * the rest; `deep` adds the entries tagged `deep`.
 */
export type DoctorTier = 'ops' | 'quick' | 'standard' | 'deep';

/** #7142: the tiers that answer from cheap reads only (a round-trip connection check, counter-mode sections). */
export function cheapTier(tier: DoctorTier | undefined): boolean {
  return tier === 'ops' || tier === 'quick';
}

export interface DoctorEntry {
  /** The entry's primary check name (an entry that only stops names the check it gates on). */
  name: string;
  /** Every check name `run` can push, categorized in src/core/doctor-categories.ts. */
  emits: readonly string[];
  /**
   * Names a pre-gate entry only emits with a connected engine (#6303). `--only`
   * of one of them connects the engine; test/doctor-only-engine-checks.test.ts
   * fails when an engine-only name is not declared.
   */
  engineChecks?: readonly string[];
  /** The lowest tier that runs this entry (default `standard`). */
  tier?: DoctorTier;
  /**
   * #6696 B1: an `ops` entry whose reads go past counters, config and catalog on
   * PGLite. Under `--tier ops` on PGLite it reports `not_applicable` instead of
   * running, and the ops report stays complete.
   */
  opsPglite?: 'not_applicable';
  run(ctx: DoctorContext): Promise<Check[] | typeof STOP_DOCTOR>;
}

export interface DoctorContext {
  engine: BrainEngine | null;
  args: string[];
  dbSource?: DbUrlSource;
  connectError?: unknown;
  jsonOutput: boolean;
  fastMode: boolean;
  doFix: boolean;
  dryRun: boolean;
  scope: 'all' | 'brain';
  orphanRatioSourceId: string | undefined;
  progress: ReturnType<typeof createProgress>;
  /** `--skills-dir` / env / walk-up resolution; `source: 'none'` under `--scope=brain`. */
  skillsDirResolution: ReturnType<typeof resolveSkillsDir> | { dir: null; source: 'none' };
  skillsDir: string | null;
  /** Written by the resolver-health entry when `--fix` runs the DRY auto-repair. */
  autoFixReport: AutoFixReport | null;
  /** Written by the schema-version entry: the brain's `config.version` (0 until read). */
  schemaVersion: number;
  /** Written by the connection entry when `getStats` fails; the next entry stops the run. */
  connectionFailed: boolean;
  /** `--only <check>[,…]`: run only the entries that emit these checks (plus the connection lane). */
  only?: ReadonlySet<string> | null;
  /** #6696 B1: the tier this run selected (default `standard`). */
  tier: DoctorTier;
  /** #6696 B1: the run's absolute deadline (absent in tests that build a context by hand). */
  deadline?: DoctorDeadline;
  /** #6696 B2: the remote caller's readable sources (run_doctor tier/only); undefined: brain-wide or `--source`. */
  sourceIds?: string[];
  /** #7146: the run serves a remote caller (run_doctor tier/only): checks that name pages or paths confine them. */
  remote?: boolean;
  /** #6803 C3: the running entry's absolute deadline (scans stop at it and report what they read); undefined: unbounded. */
  entryDeadlineAt?: number;
  /** #7142: a brain-wide local CLI run (or the background refresh) that reads and records last known results (./last-known.ts). */
  lastKnown?: 'cli' | 'refresh';
  /** #7142: the per-entry budget of the background refresh, instead of `doctor.entry_budget_ms`. */
  entryBudgetOverrideMs?: number;
  /** #6696 B1: one `getHealth()` per run, shared by every entry that reads it (`doctorHealth`). */
  healthMemo?: Promise<BrainHealth>;
}

/** #6696 B2: the source scope of a source-aware section: the remote caller's sources, else `--source`, else brain-wide. */
export function doctorSourceIds(ctx: DoctorContext): string[] | undefined {
  return ctx.sourceIds ?? (ctx.orphanRatioSourceId ? [ctx.orphanRatioSourceId] : undefined);
}

/** #6696 B1: the brain health of this run, read once (graph coverage and the embeddings check both use it). */
export function doctorHealth(ctx: DoctorContext): Promise<BrainHealth> {
  ctx.healthMemo ??= connectedEngine(ctx).getHealth();
  return ctx.healthMemo;
}

/**
 * The engine for entries that run after the DB-checks early stop, which ends
 * the run when there is no engine or `--fast` is set.
 */
export function connectedEngine(ctx: DoctorContext): BrainEngine {
  if (!ctx.engine) throw new Error('doctor: a DB check ran without an engine; it must be ordered after the DB-checks early stop');
  return ctx.engine;
}