Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.6 KB
Raw Blame
/**
 * `fence_repair` cycle phase (#6188): one bounded run of the `fences` repair
 * kind (src/core/repair/fences.ts) in the global maintenance lane, so fences
 * that sync held and malformed fences that pages store are repaired with no
 * operator. The phase has no rule logic of its own: the kind plans from its
 * census, skips sources this host may not write (an owner reason such as
 * `host_mismatch`) and the candidates a running sync still names
 * (`sync_in_progress`; the rest of a syncing source is repaired, #6278),
 * reads `fences.repair.llm` and the daily USD ledger itself, and re-plans on
 * the next run, where items already repaired drop out.
 *
 * The phase gates on `fences.repair.enabled`, runs the kind through the
 * shared trusted repair runner (an apply, or a preview on a dry run) with a
 * deadline of min(300 s, a third of the maintenance job's remaining time),
 * and reports the kind's verification: candidates, repairs per tier, what is
 * still held by reason, model spend, the oldest unresolved hold's age and the
 * USD per model repair. It never fails the cycle: a stop other than the time
 * budget, or an internal error, reports `warn` with the next step. Output is
 * counts and reason codes only, never a path, claim or cell value.
 */
import type { BrainEngine } from '../engine.ts';
import type { PhaseResult } from '../cycle.ts';
import type { Action } from '../agent-output.ts';
import { resolveRepairScope, type RepairResult } from '../repair/core.ts';
import { repairRunner, type RepairKindSpec } from '../repair/registry.ts';
import type { FenceRepairVerification } from '../repair/fences.ts';
import { FENCE_REASONS } from '../fence-repair/reasons.ts';
import type { FenceReason } from '../fence-repair/types.ts';
import { FENCE_REPAIR_ENABLED_KEY, FENCE_REPAIR_LLM_KEY, fenceRepairEnabled, fenceRepairLlmEnabled } from '../fence-repair/config.ts';
import { isUncontainedPhaseError } from './phase-containment.ts';

/** The longest one phase run spends repairing fences; inside a maintenance job it is also at most a third of the job's remaining time. */
export const FENCE_REPAIR_PHASE_BUDGET_MS = 300_000;

export interface FenceRepairPhaseOpts {
  dryRun: boolean;
  signal?: AbortSignal;
  /** The enclosing maintenance job's absolute deadline (epoch ms); null or unset for a direct `gbrain dream`. */
  deadlineAtMs?: number | null;
  /** Replaces the registered repair kinds, as `repairRunner` takes it (tests pass stub specs). */
  registry?: readonly RepairKindSpec[];
  now?: () => number;
}

const PREVIEW = 'gbrain repair fences';
const previewFix = (why: string): Action => ({ argv: ['gbrain', 'repair', 'fences'], consent: [], actor: 'agent', why, requires_exclusive: false,
  docs: 'docs/guides/repair.md#fences' });

export async function runFenceRepairPhase(engine: BrainEngine | null, opts: FenceRepairPhaseOpts): Promise<PhaseResult> {
  const base = { phase: 'fence_repair' as const, duration_ms: 0 };
  if (!engine) return { ...base, status: 'skipped', summary: 'no database connected', details: { reason: 'no_database' } };
  if (!(await fenceRepairEnabled(engine))) {
    return { ...base, status: 'skipped', details: { reason: 'disabled' },
      summary: `fence repair is paused (${FENCE_REPAIR_ENABLED_KEY} false), so nothing was repaired. Turn it back on with `
        + `\`gbrain config set ${FENCE_REPAIR_ENABLED_KEY} true\`, or preview and apply by hand with \`${PREVIEW}\`.` };
  }
  const now = opts.now ?? Date.now;
  const start = now();
  const timeBudgetMs = opts.deadlineAtMs == null ? FENCE_REPAIR_PHASE_BUDGET_MS
    : Math.min(FENCE_REPAIR_PHASE_BUDGET_MS, Math.floor((opts.deadlineAtMs - start) / 3));
  if (timeBudgetMs <= 0) {
    return { ...base, status: 'skipped', summary: 'no maintenance-job time left for fence repair; the next run continues', details: { reason: 'deadline' } };
  }
  const llmEnabled = await fenceRepairLlmEnabled(engine);
  let result: RepairResult;
  try {
    const runner = await repairRunner(engine, { apply: !opts.dryRun, logger: { info() {}, warn: console.warn, error: console.error },
      ...(opts.registry ? { registry: opts.registry } : {}) });
    result = await runner.run('fences', await resolveRepairScope(engine), { deadline: start + timeBudgetMs });
  } catch (error) {
    if (isUncontainedPhaseError(error, opts.signal)) throw error;
    const rawCode = (error as { code?: unknown } | null)?.code;
    const code = typeof rawCode === 'string' ? rawCode : 'internal';
    return { ...base, status: 'warn', details: { reason: 'error', code, time_budget_ms: timeBudgetMs,
      fix: previewFix('The fence repair stopped on an error; the preview shows the plan and the error on the brain host.') },
      summary: `fence repair stopped on an error (${code}) and the next maintenance run retries. Run \`${PREVIEW}\` on the brain host `
        + 'to see the plan and the error; ask the user if it keeps failing.' };
  }

  const v = result.verification as Partial<FenceRepairVerification> | undefined;
  const repairedByTier = v?.repaired_by_tier ?? { deterministic: 0, resolver: 0, llm: 0 };
  const heldByReason: Record<string, number> = v?.held_by_reason ?? result.remaining ?? {};
  const candidates = v?.candidates ?? result.affected;
  const repaired = result.repaired ?? result.applied;
  const oldestHoldAt = v?.oldest_hold_at ?? null;
  const oldestHoldAgeHours = oldestHoldAt ? Math.max(0, Math.round((now() - Date.parse(oldestHoldAt)) / 3_600_000)) : null;
  const llmUsd = result.cost.llm_usd ?? null;
  const llmUsdPerRepair = v?.llm_usd_per_repair ?? null;
  const scanPartial = v?.partial ?? result.scan?.partial ?? false;
  const stopped = result.stopped;
  const failed = result.failed.length;
  const held = Object.values(heldByReason).reduce((sum, n) => sum + n, 0);
  const manual = Object.entries(heldByReason).filter(([reason]) => FENCE_REASONS[reason as FenceReason]?.manualOnly).reduce((sum, [, n]) => sum + n, 0);
  const llmDisabled = heldByReason.llm_disabled ?? 0;

  const usd = (n: number | null) => n === null ? 'unpriced' : `$${n.toFixed(4)}`;
  const parts = [
    result.mode === 'dry_run' ? `dry run: ${candidates} fence candidate(s) planned, nothing written`
      : candidates === 0 && held === 0 ? 'no malformed fences to repair'
        : `repaired ${repaired} of ${candidates} fence candidate(s) (deterministic ${repairedByTier.deterministic}, resolver ${repairedByTier.resolver}, `
          + `model ${repairedByTier.llm}; ${usd(llmUsd)} on the model${llmUsdPerRepair !== null ? `, ${usd(llmUsdPerRepair)} per model repair` : ''})`,
    held ? `${held} still held (${Object.entries(heldByReason).filter(([, n]) => n).map(([reason, n]) => `${reason} ${n}`).join(', ')})` : '',
    oldestHoldAgeHours !== null ? `the oldest unresolved hold is ${oldestHoldAgeHours} h old` : '',
  ].filter(Boolean).join('; ');
  const notes = [
    stopped?.reason === 'time_budget' ? `Stopped at the phase time budget (${Math.round(timeBudgetMs / 1000)} s); the next maintenance run resumes.` : '',
    stopped && stopped.reason !== 'time_budget' ? `Stopped (${stopped.reason}): ${stopped.message}` : '',
    failed ? `${failed} item(s) refused and left unchanged (first: ${result.failed[0]!.item}, ${result.failed[0]!.reason}); the next full scan retries them.` : '',
    scanPartial ? 'The fence census scan is still partial; the next run continues it.' : '',
    llmEnabled ? '' : `Model (Tier 3) repair is off (${FENCE_REPAIR_LLM_KEY} false)${llmDisabled ? `: ${llmDisabled} fence(s) wait for it; ask the user before `
      + `turning it on (\`gbrain config set ${FENCE_REPAIR_LLM_KEY} true\`, paid) or edit them by hand` : ''}.`,
    manual ? `${manual} need a manual edit: run \`${PREVIEW}\` on the brain host for each exact fix.` : '',
  ].filter(Boolean);
  const fix = stopped && stopped.reason !== 'time_budget' ? stopped.fix : manual ? previewFix('Some fences need a manual edit; the preview names each exact fix.') : undefined;
  return {
    ...base,
    status: (stopped && stopped.reason !== 'time_budget') || failed ? 'warn' : 'ok',
    summary: [`${parts}.`, ...notes].join(' '),
    details: {
      mode: result.mode, candidates, repaired, failed, repaired_by_tier: repairedByTier, held_by_reason: heldByReason,
      llm_enabled: llmEnabled, llm_usd: llmUsd, llm_cap_remaining_usd: result.cost.llm_cap_remaining_usd ?? null,
      llm_repairs: v?.llm_repairs ?? 0, llm_usd_per_repair: llmUsdPerRepair, oldest_hold_at: oldestHoldAt, oldest_hold_age_hours: oldestHoldAgeHours,
      scan_partial: scanPartial, complete: result.complete, time_budget_ms: timeBudgetMs, stopped_reason: stopped?.reason ?? null,
      ...(stopped ? { stopped } : {}), ...(fix ? { fix } : {}),
    },
  };
}