Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.5 KB
Raw Blame
/**
 * `content_repair` cycle phase (#6377): one bounded pass of the content-repair
 * lane (src/core/repair/content-lane.ts) in the global maintenance lane,
 * right after `fence_repair`, so the content holds managed sync records
 * (`frontmatter_slug_conflict` today's candidate; `invalid_fence` is
 * `fence_repair`'s) clear within one maintenance cycle with no operator. The
 * phase runs every kind in `CONTENT_REPAIR_KINDS` except `fences`, which
 * `fence_repair` just ran, through the same shared trusted repair runner, so
 * each kind keeps its own census, owner checks, caps, ledger and gates, and a
 * new lane kind is picked up here with no change. With `CONTENT_REPAIR_KINDS`
 * holding only `fences` the phase runs nothing and says so (`no_kinds`).
 *
 * Gated on `fences.repair.enabled` (one switch for the whole lane, D3), with a
 * deadline of min(120 s, a third of the maintenance job's remaining time); an
 * apply on a real run, a preview on a dry run. The report is counts by kind,
 * outcome and reason, the lane's model spend and the oldest unresolved hold's
 * age. 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
 * 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 RepairKind, type RepairResult } from '../repair/core.ts';
import type { RepairKindSpec } from '../repair/registry.ts';
import { CONTENT_REPAIR_KINDS, contentLaneArgv, runContentLane, type ContentLaneResult } from '../repair/content-lane.ts';
import { FENCE_REPAIR_ENABLED_KEY, fenceRepairEnabled } from '../fence-repair/config.ts';
import { isUncontainedPhaseError } from './phase-containment.ts';

/** The longest one phase run spends on the lane; inside a maintenance job it is also at most a third of the job's remaining time. */
export const CONTENT_REPAIR_PHASE_BUDGET_MS = 120_000;

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

/** The kinds the phase runs by default: the lane minus the kind `fence_repair` already ran. */
export function contentRepairPhaseKinds(): RepairKind[] {
  return CONTENT_REPAIR_KINDS.filter(kind => kind !== 'fences');
}

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

/** Counts by reason over a kind's per-item outcomes (its `remaining` when the kind reports one). */
function heldByReason(result: RepairResult): Record<string, number> {
  if (result.remaining) return result.remaining;
  const counts: Record<string, number> = {};
  for (const item of result.outcome_items ?? []) if (item.outcome !== 'repaired' && item.reason) counts[item.reason] = (counts[item.reason] ?? 0) + 1;
  return counts;
}

export async function runContentRepairPhase(engine: BrainEngine | null, opts: ContentRepairPhaseOpts): Promise<PhaseResult> {
  const base = { phase: 'content_repair' as const, duration_ms: 0 };
  if (!engine) return { ...base, status: 'skipped', summary: 'no database connected', details: { reason: 'no_database' } };
  const kinds = [...(opts.kinds ?? contentRepairPhaseKinds())];
  const preview = contentLaneArgv({}).join(' ');
  if (!kinds.length) {
    return { ...base, status: 'skipped', details: { reason: 'no_kinds', kinds },
      summary: 'no content-repair kind beyond fence_repair is registered in this release, so the phase ran nothing; fence holds were handled by fence_repair.' };
  }
  if (!(await fenceRepairEnabled(engine))) {
    return { ...base, status: 'skipped', details: { reason: 'disabled', kinds },
      summary: `content 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 ? CONTENT_REPAIR_PHASE_BUDGET_MS
    : Math.min(CONTENT_REPAIR_PHASE_BUDGET_MS, Math.floor((opts.deadlineAtMs - start) / 3));
  if (timeBudgetMs <= 0) {
    return { ...base, status: 'skipped', summary: 'no maintenance-job time left for content repair; the next run continues', details: { reason: 'deadline', kinds } };
  }
  let lane: ContentLaneResult;
  try {
    lane = await runContentLane(engine, await resolveRepairScope(engine), { apply: !opts.dryRun, kinds, deadline: start + timeBudgetMs,
      logger: { info() {}, warn: console.warn, error: console.error }, ...(opts.registry ? { registry: opts.registry } : {}), ...(opts.signal ? { signal: opts.signal } : {}) });
  } 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, kinds, time_budget_ms: timeBudgetMs,
      fix: previewFix('The content repair stopped on an error; the preview shows each kind\'s plan and the error on the brain host.') },
      summary: `content 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 byKind = Object.fromEntries(lane.results.map(result => {
    const held = heldByReason(result);
    const v = result.verification as { oldest_hold_at?: string | null } | undefined;
    return [result.kind, { mode: result.mode, candidates: result.affected, repaired: result.repaired ?? result.applied, failed: result.failed.length, outcomes: result.outcomes ?? {}, held_by_reason: held,
      llm_usd: result.cost.llm_usd ?? null, complete: result.complete, stopped_reason: result.stopped?.reason ?? null, oldest_hold_at: v?.oldest_hold_at ?? null }];
  })) as Record<string, { mode: string; candidates: number; repaired: number; failed: number; outcomes: Record<string, number>; held_by_reason: Record<string, number>; llm_usd: number | null; complete: boolean;
    stopped_reason: string | null; oldest_hold_at: string | null }>;
  const kindsRun = Object.values(byKind);
  const candidates = kindsRun.reduce((sum, k) => sum + k.candidates, 0);
  const repaired = kindsRun.reduce((sum, k) => sum + k.repaired, 0);
  const heldTotals: Record<string, number> = {};
  for (const k of kindsRun) for (const [reason, n] of Object.entries(k.held_by_reason)) heldTotals[reason] = (heldTotals[reason] ?? 0) + n;
  const held = Object.values(heldTotals).reduce((sum, n) => sum + n, 0);
  const needsHuman = (heldTotals.needs_human ?? 0) + (heldTotals.merge_recommended ?? 0) + (heldTotals.content_repair_needs_human ?? 0);
  const oldest = kindsRun.map(k => k.oldest_hold_at).filter((at): at is string => !!at).sort()[0] ?? null;
  const oldestHoldAgeHours = oldest ? Math.max(0, Math.round((now() - Date.parse(oldest)) / 3_600_000)) : null;
  const hardStop = lane.stopped.find(stop => stop.reason !== 'time_budget');
  // A kind that threw (reason `error`, GBRA-130 A-46) is reported by its code: the phase report never carries an error's message.
  const kindError = hardStop?.reason === 'error' ? hardStop : undefined;
  const stopped = lane.stopped.map(stop => stop.reason === 'error' ? { kind: stop.kind, reason: stop.reason, code: stop.code ?? 'internal', message: `${stop.kind} raised ${stop.code ?? 'an error'}`, ...(stop.fix ? { fix: stop.fix } : {}) } : stop);
  const timeStop = lane.stopped.find(stop => stop.reason === 'time_budget');
  const failed = lane.failed.length;
  const usd = `$${lane.cost.llm_usd.toFixed(4)}`;
  const parts = [
    lane.mode === 'dry_run' ? `dry run: ${candidates} content candidate(s) planned across ${lane.kinds.join(', ')}, nothing written`
      : candidates === 0 && held === 0 ? `no content holds to repair (${lane.kinds.join(', ')})`
        : `repaired ${repaired} of ${candidates} content candidate(s) across ${lane.kinds.join(', ')} (${usd} on the model)`,
    held ? `${held} still held (${Object.entries(heldTotals).filter(([, n]) => n).map(([reason, n]) => `${reason} ${n}`).join(', ')})` : '',
    oldestHoldAgeHours !== null ? `the oldest unresolved hold is ${oldestHoldAgeHours} h old` : '',
  ].filter(Boolean).join('; ');
  const notes = [
    timeStop ? `Stopped at the phase time budget (${Math.round(timeBudgetMs / 1000)} s) in ${timeStop.kind}; the next maintenance run resumes.` : '',
    kindError ? `${kindError.kind} stopped on an error (${kindError.code ?? 'internal'}) and the next maintenance run retries; the other kinds ran. Run \`${preview}\` on the brain host to see the plan and the error; ask the user if it keeps failing.`
      : hardStop ? `Stopped (${hardStop.kind}: ${hardStop.reason}): ${hardStop.message}` : '',
    failed ? `${failed} item(s) refused and left unchanged (first: ${lane.failed[0]!.kind} ${lane.failed[0]!.item}, ${lane.failed[0]!.reason}); the next full scan retries them.` : '',
    needsHuman ? `${needsHuman} wait for a person: gbrain sync status --source <id> --json names each with its paragraph.` : '',
  ].filter(Boolean);
  const fix = hardStop ? hardStop.fix ?? previewFix('A lane kind stopped; the preview shows each kind\'s plan on the brain host.')
    : needsHuman ? previewFix('Some holds wait for a person; the preview names each with its exact next step.') : undefined;
  return {
    ...base,
    status: hardStop || failed ? 'warn' : 'ok',
    summary: [`${parts}.`, ...notes].join(' '),
    details: {
      mode: lane.mode, kinds: lane.kinds, candidates, repaired, failed, held_by_reason: heldTotals, by_kind: byKind,
      llm_usd: lane.cost.llm_usd, oldest_hold_at: oldest, oldest_hold_age_hours: oldestHoldAgeHours,
      complete: lane.results.every(result => result.complete), time_budget_ms: timeBudgetMs, stopped_reason: hardStop?.reason ?? timeStop?.reason ?? null,
      ...(kindError ? { reason: 'error', code: kindError.code ?? 'internal' } : {}), ...(lane.stopped.length ? { stopped } : {}), ...(fix ? { fix } : {}),
    },
  };
}