Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
18.0 KB
Raw Blame
/**
 * gbrain maintain — conservative self-healing maintenance.
 *
 * This command automates the safe parts of the operator runbook:
 *   - stale link/timeline extraction
 *   - stale per-source dream cycles when doctor reports cycle_freshness,
 *     limited to the free phases that never hard-delete (MAINTAIN_SAFE_PHASES)
 *
 * It deliberately does NOT mutate source files, apply schema-pack upgrades, or
 * invent semantic hub links. Those need review or a separate command with an
 * auditable proposal surface.
 */

import { existsSync } from 'fs';
import { isAbsolute } from 'path';
import { createHash } from 'crypto';
import type { BrainEngine } from '../core/engine.ts';
import type { BrainHealth } from '../core/types.ts';
import { buildChecks, computeDoctorReport, type DoctorReport, type Check } from './doctor.ts';
import { extractStaleFromDB } from './extract.ts';
import { runCycle, type CycleReport } from '../core/cycle.ts';
import { maintainSafePhases, readSafePhaseProviders, isValidRunnerName, runUnattendedMaintenance, type UpkeepOutcome } from '../core/maintenance/run.ts';
import { readUpkeepStatus } from '../core/maintenance/status.ts';
import { cliRenderContext, noticeBlock, renderAction, renderNotice, type Action } from '../core/agent-output.ts';
import { ItemRun } from '../core/item-failure.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { writeCliError } from '../cli/cli-error.ts';
import { opError } from '../core/ops/contract.ts';
import { autoDetectSkillsDirReadOnly } from '../core/repo-root.ts';
import { skillHealthSummary } from '../core/skill-health.ts';

type ActionStatus = 'ok' | 'would_apply' | 'applied' | 'blocked' | 'skipped';

export interface MaintenanceAction {
  name: string;
  status: ActionStatus;
  message: string;
  details?: Record<string, unknown>;
}

export interface MaintainOptions {
  json: boolean;
  safe: boolean;
  dryRun: boolean;
  help: boolean;
  unattended: boolean;
  runner: string;
  status: boolean;
  purge: boolean;
  yes: boolean;
  expect: string | null;
}

function flagValue(args: string[], flag: string): string | null {
  const i = args.indexOf(flag);
  if (i >= 0) return args[i + 1] ?? '';
  const eq = args.find((a) => a.startsWith(flag + '='));
  return eq ? eq.slice(flag.length + 1) : null;
}

export interface MaintainReport {
  mode: 'dry-run' | 'safe';
  before: {
    health: BrainHealth;
    doctor: DoctorReport;
  };
  actions: MaintenanceAction[];
  after: {
    health: BrainHealth;
    doctor: DoctorReport;
  };
}

export function parseMaintainArgs(args: string[]): MaintainOptions {
  const safe = args.includes('--safe');
  return {
    json: args.includes('--json'),
    safe,
    dryRun: args.includes('--dry-run') || !safe,
    help: args.includes('--help') || args.includes('-h'),
    unattended: args.includes('--unattended'),
    runner: flagValue(args, '--runner') ?? 'cli',
    status: args.includes('--status'),
    purge: args.includes('--purge'),
    yes: args.includes('--yes'),
    expect: flagValue(args, '--expect'),
  };
}

export function extractCycleFreshnessSourceIds(checks: Check[]): string[] {
  const ids = new Set<string>();
  for (const check of checks) {
    if (check.name !== 'cycle_freshness' || check.status === 'ok') continue;
    const re = /Source '([^']+)' last cycled/g;
    for (const match of check.message.matchAll(re)) {
      const id = match[1]?.trim();
      if (id) ids.add(id);
    }
  }
  return [...ids].sort();
}

// The step list --safe shares with unattended upkeep lives in the runner core.
export { MAINTAIN_SAFE_PHASES, maintainSafePhases, type SafePhaseProviders } from '../core/maintenance/run.ts';

async function buildDoctorReport(engine: BrainEngine): Promise<DoctorReport> {
  const checks = await buildChecks(engine, ['--json', '--scope=brain']);
  return computeDoctorReport(checks);
}

/** Read-only: skill size, growth and drift for the active skills folder; never edits a skill. */
async function reportSkillHealth(): Promise<MaintenanceAction> {
  const dir = autoDetectSkillsDirReadOnly().dir;
  if (!dir) return { name: 'skill_health', status: 'skipped', message: 'no skills folder found' };
  const { skillHealthFor } = await import('./skillpack/health.ts');
  const report = skillHealthFor(dir);
  const message = skillHealthSummary(report) + (report.findings.length ? '; run `gbrain skillpack health` for the fixes' : '');
  return { name: 'skill_health', status: 'ok', message, details: { scope: report.scope, totals: report.totals } };
}

async function runStaleExtraction(
  engine: BrainEngine,
  beforeHealth: BrainHealth,
  dryRun: boolean,
  json: boolean,
): Promise<MaintenanceAction> {
  if (beforeHealth.stale_pages <= 0) {
    return { name: 'extract_stale', status: 'ok', message: 'No stale pages.' };
  }

  if (dryRun) {
    return {
      name: 'extract_stale',
      status: 'would_apply',
      message: `Would run DB-backed stale extraction for ${beforeHealth.stale_pages} page(s).`,
      details: { stale_pages: beforeHealth.stale_pages },
    };
  }

  // maintain owns the report: in --json mode the helper's human summary must
  // stay off stdout or the JSON document stops parsing.
  const result = await extractStaleFromDB(engine, {
    dryRun: false,
    jsonMode: false,
    quiet: json,
    catchUp: false,
  });

  return {
    name: 'extract_stale',
    status: 'applied',
    message: `Processed ${result.pagesProcessed} stale page(s); ${result.staleRemaining} remain.`,
    details: {
      links_created: result.linksCreated,
      timeline_created: result.timelineCreated,
      pages_processed: result.pagesProcessed,
      stale_remaining: result.staleRemaining,
    },
  };
}

async function runCycleFreshnessMaintenance(
  engine: BrainEngine,
  beforeDoctor: DoctorReport,
  dryRun: boolean,
): Promise<MaintenanceAction[]> {
  const sourceIds = extractCycleFreshnessSourceIds(beforeDoctor.checks);
  if (sourceIds.length === 0) {
    return [{ name: 'cycle_freshness', status: 'ok', message: 'All sources cycled recently.' }];
  }

  const providers = await readSafePhaseProviders(engine);
  if (dryRun) {
    return sourceIds.map((sourceId) => {
      const { phases, held } = maintainSafePhases(sourceId, providers);
      return {
        name: 'cycle_freshness',
        status: 'would_apply',
        message: `Would run the free source cycle for ${sourceId} (no page purge, no paid phases).`,
        details: { source_id: sourceId, phases, held_phases: held },
      };
    });
  }

  const sources = await engine.listAllSources();
  const actions: MaintenanceAction[] = [];
  // One source's cycle throwing blocks that source only; a run-scoped error (abort, lost lock or connection) still stops maintain.
  const run = new ItemRun('maintain.cycle_sources');

  for (const sourceId of sourceIds) {
    const source = sources.find((s) => s.id === sourceId);
    const localPath = source?.local_path ?? null;
    // #7630: a relative local_path names whatever directory maintain runs from, so it is no checkout.
    const brainDir = localPath && isAbsolute(localPath) && existsSync(localPath) ? localPath : null;
    const { phases, held } = maintainSafePhases(sourceId, providers);
    let report: CycleReport;
    try {
      report = await runCycle(engine, {
        brainDir,
        dryRun: false,
        pull: false,
        sourceId,
        phases,
      });
      run.succeed();
    } catch (error) {
      const failure = run.fail(sourceId, error);
      actions.push({
        name: 'cycle_freshness',
        status: 'blocked',
        message: `Source-scoped dream cycle for ${sourceId} stopped with ${failure.code}: ${failure.message}`,
        details: { source_id: sourceId, brain_dir: brainDir, code: failure.code, error: failure.message, fix: { argv: ['gbrain', 'dream', '--source', sourceId], consent: ['paid'], actor: 'agent', requires_exclusive: false,
          why: `Reruns the source-scoped dream cycle for ${sourceId} once the cause above is fixed; its paid phases spend only within their configured caps.` } },
      });
      continue;
    }
    actions.push({
      name: 'cycle_freshness',
      status: report.status === 'failed' ? 'blocked' : 'applied',
      message: `Ran the free source cycle for ${sourceId}: ${report.status}.`,
      details: {
        source_id: sourceId,
        brain_dir: brainDir,
        cycle_status: report.status,
        phases: report.phases.map((p) => ({ phase: p.phase, status: p.status })),
        held_phases: held,
      },
    });
  }

  return actions;
}

export async function runMaintain(engine: BrainEngine, args: string[]): Promise<MaintainReport | void> {
  const opts = parseMaintainArgs(args);
  if (opts.help) {
    console.log(`Usage: gbrain maintain [--safe] [--dry-run] [--json]
       gbrain maintain --unattended [--runner <name>] [--json]
       gbrain maintain --status [--json]
       gbrain maintain --purge [--yes --expect <hash>] [--json]
       gbrain maintain --schedule [--yes | --dry-run] [--json]
       gbrain maintain --unschedule [--json]

Conservative self-healing maintenance.

Modes:
  --dry-run     Preview safe actions without writes. Default when --safe is absent.
  --safe        Apply safe actions: stale extraction and source cycle freshness.
                Skill health (size, growth, drift) is reported, never applied.
  --unattended  Run free upkeep once when it is due: links, timeline, facts index,
                bookkeeping GC and, with an embedding key, the embedding backlog
                within maintenance.embed_daily_usd (default $1 a day; 0 = off).
                Never purges a page or calls a chat model. Records
                maintenance.last_run; --runner names the caller (default cli).
  --status      Show the last upkeep run, the next due time and what waits for you.
  --purge       Preview the page purge (soft-deleted pages past purge.retention_hours);
                apply it with --yes --expect <hash> from the preview.
  --schedule    Opt in to an operating-system schedule (launchd, systemd user timer or
                crontab) that runs --unattended every 6 hours; --yes approves the
                install, --dry-run shows what it writes. A running gbrain serve
                already runs free upkeep while idle, so most installs need none.
  --unschedule  Remove that schedule.
  --json        Emit a structured before/action/after report.

Not auto-applied:
  source-file frontmatter fixes, schema-pack upgrades, atom-pack changes,
  semantic hub-link guesses, and destructive cleanup.
  The source cycle skips the page purge (\`gbrain pages purge-deleted\`) and
  every phase that calls a model (\`gbrain dream\`).
`);
    return;
  }
  if (opts.unattended) return void await runUnattendedCli(engine, opts);
  if (opts.status) return void await runStatusCli(engine, opts);
  if (opts.purge) return void await runPurgeCli(engine, opts);

  const beforeHealth = await engine.getHealth();
  const beforeDoctor = await buildDoctorReport(engine);
  const actions: MaintenanceAction[] = [];

  actions.push(await runStaleExtraction(engine, beforeHealth, opts.dryRun, opts.json));
  actions.push(...await runCycleFreshnessMaintenance(engine, beforeDoctor, opts.dryRun));
  actions.push(await reportSkillHealth());

  const afterHealth = await engine.getHealth();
  const afterDoctor = await buildDoctorReport(engine);
  const report: MaintainReport = {
    mode: opts.dryRun ? 'dry-run' : 'safe',
    before: { health: beforeHealth, doctor: beforeDoctor },
    actions,
    after: { health: afterHealth, doctor: afterDoctor },
  };
  if (actions.some((action) => action.status === 'blocked')) setCliExitVerdict(1);

  if (opts.json) {
    console.log(JSON.stringify(report, null, 2));
  } else {
    printMaintainReport(report);
  }
  return report;
}

function printMaintainReport(report: MaintainReport): void {
  console.log(`GBrain maintain (${report.mode})`);
  console.log(
    `Before: brain_score=${Math.round(report.before.health.brain_score)}/100 ` +
    `stale=${report.before.health.stale_pages} islands=${report.before.health.orphan_pages} ` +
    `doctor=${report.before.doctor.status}`,
  );
  for (const action of report.actions) {
    console.log(`  ${action.status}: ${action.name} — ${action.message}`);
  }
  console.log(
    `After:  brain_score=${Math.round(report.after.health.brain_score)}/100 ` +
    `stale=${report.after.health.stale_pages} islands=${report.after.health.orphan_pages} ` +
    `doctor=${report.after.doctor.status}`,
  );
  if (report.mode === 'dry-run') {
    console.log('Run `gbrain maintain --safe` to apply safe actions.');
  }
}

function printNotice(code: string, why: string, fix: Action | undefined): void {
  process.stderr.write(noticeBlock(renderNotice({ code, kind: 'info', why, ...(fix ? { fix } : {}) }, cliRenderContext())) + '\n');
}

async function runUnattendedCli(engine: BrainEngine, opts: MaintainOptions): Promise<UpkeepOutcome | void> {
  if (!isValidRunnerName(opts.runner)) {
    console.error(`--runner must be a short lowercase name (letters, digits, - or _), got "${opts.runner}".`);
    setCliExitVerdict(2);
    return;
  }
  const outcome = await runUnattendedMaintenance(engine, { runner: opts.runner });
  if (outcome.exit) setCliExitVerdict(outcome.exit);
  if (opts.json) {
    console.log(JSON.stringify({ ...outcome, ...(outcome.fix ? { fix: renderAction(outcome.fix, cliRenderContext()) } : {}) }, null, 2));
    return outcome;
  }
  console.log(outcome.message);
  for (const step of outcome.record?.steps ?? []) {
    if (outcome.status !== 'ran') break;
    console.log(`  ${step.status}: ${step.name} (${step.scope})${step.code ? ` ${step.code}` : step.reason ? ` ${step.reason}` : ''}`);
  }
  if (outcome.status === 'skipped' && outcome.code) printNotice(outcome.code, outcome.message, outcome.fix);
  return outcome;
}

async function runStatusCli(engine: BrainEngine, opts: MaintainOptions): Promise<void> {
  const status = await readUpkeepStatus(engine);
  const { fix, alternative_fix: alternative, ...rest } = status;
  if (opts.json) {
    console.log(JSON.stringify({ ...rest, ...(fix ? { fix: renderAction(fix, cliRenderContext()) } : {}),
      ...(alternative ? { alternative_fix: renderAction(alternative, cliRenderContext()) } : {}) }, null, 2));
    return;
  }
  console.log(status.message);
  if (status.last_run) console.log(`Last run: ${status.last_run} (${status.runner}), next due: ${status.next_due_at}`);
  for (const p of status.parked) console.log(`Parked: ${p.key} since ${p.since} (${p.slices} slices)`);
  if (status.held.length) console.log(`Held back on this brain (they would call a provider): ${status.held.join(', ')}`);
  console.log(`Left for you (paid, opt-in; gbrain dream or an autopilot runs them): ${status.paid_phases_opt_in.join(', ')}`);
  if (fix) console.log(`Fix: ${fix.argv!.join(' ')}: ${fix.why}`);
  if (alternative) console.log(`Or: ${alternative.argv!.join(' ')}: ${alternative.why}`);
}

/** Hash of exactly what a purge would remove, so --expect binds the apply to the preview the person saw. */
export function purgePreviewHash(retentionHours: number, pages: ReadonlyArray<{ source_id?: string; slug: string }>): string {
  const keys = pages.map((p) => `${p.source_id ?? 'default'}/${p.slug}`).sort();
  return createHash('sha256').update(JSON.stringify({ retentionHours, keys })).digest('hex').slice(0, 12);
}

async function runPurgeCli(engine: BrainEngine, opts: MaintainOptions): Promise<void> {
  const [{ selectPurgeCandidates, purgeDeletedPagesCoordinated }, { readPurgeRetentionHours }] = await Promise.all([
    import('../core/persistence/purge-deleted.ts'), import('../core/sync-reconcile.ts')]);
  const retention = await readPurgeRetentionHours(engine);
  const selection = await selectPurgeCandidates(engine, retention, { automatic: true });
  const pages: Array<{ source_id: string; slug: string }> = (selection.managed ? selection.candidates : selection.pages ?? [])
    .map((p) => ({ source_id: p.source_id, slug: p.slug }));
  const hash = purgePreviewHash(retention, pages);
  const apply = ['gbrain', 'maintain', '--purge', '--yes', '--expect', hash];
  if (!opts.yes) {
    const preview = { mode: 'preview', retention_hours: retention, count: pages.length, pages: pages.slice(0, 50), blocked: selection.blocked.length, hash,
      ...(pages.length ? { apply: renderAction({ argv: apply, consent: ['destructive'], actor: 'agent', requires_exclusive: false,
        why: `Permanently deletes the ${pages.length} page(s) listed (soft-deleted more than ${retention}h ago); gbrain restore cannot bring them back.` }, cliRenderContext()) } : {}) };
    if (opts.json) { console.log(JSON.stringify(preview, null, 2)); return; }
    console.log(`${pages.length} soft-deleted page(s) are past the ${retention}h recovery window.`);
    for (const p of pages.slice(0, 50)) console.log(`  ${p.source_id}/${p.slug}`);
    if (pages.length > 50) console.log(`  ...and ${pages.length - 50} more`);
    if (pages.length) console.log(`Nothing was deleted. To purge exactly these, run: ${apply.join(' ')}`);
    return;
  }
  if (opts.expect !== hash) {
    const why = opts.expect ? `The purge set changed since the preview (expected ${opts.expect}, now ${hash}); nothing was deleted.` : 'A purge needs --expect <hash> from the preview; nothing was deleted.';
    const fix: Action = { argv: ['gbrain', 'maintain', '--purge'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Shows the current purge set and its hash; it deletes nothing.' };
    setCliExitVerdict(writeCliError(opError('preview_changed', why, 'Preview again: gbrain maintain --purge', { fix, detail: `current hash ${hash}` }), 'maintain', { json: !!opts.json }));
    return;
  }
  const previewed = new Set(pages.map((p) => `${p.source_id}/${p.slug}`));
  const result = await purgeDeletedPagesCoordinated(engine, retention, { automatic: true, only: (p) => previewed.has(`${p.source_id}/${p.slug}`) });
  if (result.error) setCliExitVerdict(1);
  if (opts.json) { console.log(JSON.stringify({ mode: 'applied', purged: result.count, slugs: result.slugs, blocked: result.blocked, deferred: result.deferred, ...(result.error ? { error: result.error } : {}) }, null, 2)); return; }
  console.log(`Purged ${result.count} page(s).${result.blocked.length ? ` ${result.blocked.length} blocked; see --json.` : ''}`);
}