Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.2 KB
Raw Blame
/**
 * Preview-bound approval (fix wave 5, ENG-O1), shared by every command whose
 * apply must touch exactly the set its preview showed: `gbrain jobs
 * authorize-legacy --select`, `gbrain jobs cancel --select`, `gbrain repair
 * stale-atoms` and `gbrain repair extractor-facts`.
 *
 * The flow is the same for all four:
 *
 *   1. The preview computes `previewHash(parts)` over everything the operator
 *      reviewed (brain and source identity, the listed items with their
 *      revisions or evidence, the selection options) and saves the items with
 *      `saveApprovedSet`. It prints the hash and the filled apply command.
 *   2. The apply passes the hash back (`--expect <hash>`). `loadApprovedSet`
 *      returns the saved items, or refuses with `preview_changed` when no set
 *      was saved under that hash or the set is older than the checkpoint purge
 *      window. A refused load never returns a partial set, so an apply either
 *      starts from the whole approved set or not at all.
 *   3. The apply replays the approved items (each with its own request id, so
 *      a resumed apply after a crash replays the same requests and reconciles
 *      their receipts before advancing), rechecking each item against the
 *      live state, and calls `clearApprovedSet` when it finishes.
 *
 * Sets live in `op_checkpoints` (`op='repair-approval'`, keyed by command and
 * hash), so no migration is needed. `purgeStaleCheckpoints` deletes rows older
 * than its TTL (7 days by default); `APPROVAL_MAX_AGE_DAYS` matches it, so a
 * set the purge may already have taken is never trusted.
 *
 * `previewHash` is SHA-256 over the same key-sorted JSON as
 * `authorityDigest` (`minions/submission-authority.ts`), so the existing
 * `authorizeLegacyJobs --ids` snapshot digest is byte-identical when computed
 * through this helper.
 */
import type { BrainEngine } from '../engine.ts';
import type { OperationError } from '../ops/contract.ts';
import { catalogueError } from '../error-catalogue.ts';
import { digest } from './digest.ts';

export const PREVIEW_APPROVAL_OP = 'repair-approval';

/** The default `purgeStaleCheckpoints` TTL; an older approved set may already be gone. */
export const APPROVAL_MAX_AGE_DAYS = 7;

export type PreviewApprovalCommand = 'authorize-legacy' | 'jobs-cancel' | 'stale-atoms' | 'atoms-restore' | 'atom-fence-rows' | 'extractor-facts' | 'unwithdrawn-facts' | 'purged-page-facts' | 'purged-change-reasons' | 'conversation-labels' | 'captured-facts' | 'agent-session-facts' | 'redacted-facts' | 'loop-facts' | 'ontology-facts' | 'facts-rehome' | 'consolidate-ties' | 'duplicate-facts' | 'failed-writes' | 'split-facts' | 'frontmatter' | 'fences' | 'slug-conflicts' | 'managed-sync-orphans' | 'frontmatter-keys' | 'file-drift' | 'stuck-recovery' | 'ghost-pages' | 'origin-twins' | 'moved-pages' | 'receipt-compaction' | 'accepted-takes' | 'rename-identity' | 'overwritten-edits' | 'legacy-twins' | 'missing-tables' | 'segmented-mirror' | 'segmented-tiling' | 'uncommitted-deletions' | 'visibility' | 'generations' | 'fact-claim-dates' | 'timeline-order' | 'contact-rows' | 'provenance' | 'secret-spans' | 'rows-behind' | 'facts-home' | 'private-labels' | 'lost-fence-rows' | 'open-facts';

export interface ApprovedSetKey {
  command: PreviewApprovalCommand;
  /** The preview hash the operator passed with `--expect`. */
  hash: string;
  /** The read-only command that prints a fresh preview, filled with the caller's real flags. */
  previewCommand: string;
  /**
   * #6351: the hash a preview of the same selection prints when it finds
   * nothing, computed from current state (source incarnations included). A
   * preview that found nothing saves no set; its hash still approves applying
   * nothing while that state holds.
   */
  emptyHash?: () => Promise<string>;
}

export interface ApprovedSet<T> {
  command: PreviewApprovalCommand;
  hash: string;
  items: T[];
  /** When the preview last saved this set (database clock, ISO 8601). */
  approved_at: string;
}

/** SHA-256 hex over key-sorted JSON of everything the preview showed. */
export function previewHash(parts: unknown): string {
  return digest(parts);
}

/** `preview_changed`: the hash no longer names a saved, fresh approved set. */
export function previewChangedError(hash: string, previewCommand: string): OperationError {
  return catalogueError('preview_changed', `The preview changed since ${hash}; re-run ${previewCommand} and use the new hash.`,
    `Re-run the preview: ${previewCommand}`);
}

function fingerprint(command: PreviewApprovalCommand, hash: string): string {
  return `${command}:${hash}`;
}

/** Saves (or re-confirms, restarting its age) the approved set a preview printed. */
export async function saveApprovedSet<T>(engine: BrainEngine, key: Omit<ApprovedSetKey, 'previewCommand'>, items: readonly T[]): Promise<void> {
  await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES($1,$2,$3::text::jsonb)
    ON CONFLICT(op,fingerprint) DO UPDATE SET completed_keys=EXCLUDED.completed_keys,updated_at=now()`,
  [PREVIEW_APPROVAL_OP, fingerprint(key.command, key.hash), JSON.stringify([{ command: key.command, hash: key.hash, items }])]);
}

/**
 * The whole approved set saved under `hash`, or `preview_changed` when it is
 * missing, malformed or older than `APPROVAL_MAX_AGE_DAYS`. Age is measured on
 * the database clock, the same clock the purge uses.
 */
export async function loadApprovedSet<T>(engine: BrainEngine, key: ApprovedSetKey): Promise<ApprovedSet<T>> {
  const [row] = await engine.executeRaw<{ completed_keys: Array<{ command?: string; hash?: string; items?: T[] }>; fresh: boolean; approved_at: string }>(
    `SELECT completed_keys, updated_at >= now() - ($3 || ' days')::interval AS fresh,
            to_char(updated_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS approved_at
       FROM op_checkpoints WHERE op=$1 AND fingerprint=$2`,
    [PREVIEW_APPROVAL_OP, fingerprint(key.command, key.hash), String(APPROVAL_MAX_AGE_DAYS)]);
  const saved = row?.completed_keys?.[0];
  if (!row && key.emptyHash && await key.emptyHash() === key.hash) {
    return { command: key.command, hash: key.hash, items: [], approved_at: new Date().toISOString() };
  }
  if (!row || row.fresh !== true || saved?.command !== key.command || saved.hash !== key.hash || !Array.isArray(saved.items)) {
    throw previewChangedError(key.hash, key.previewCommand);
  }
  return { command: key.command, hash: key.hash, items: saved.items, approved_at: row.approved_at };
}

/** Drops an approved set once its apply finished. */
export async function clearApprovedSet(engine: BrainEngine, key: Omit<ApprovedSetKey, 'previewCommand'>): Promise<void> {
  await engine.executeRaw('DELETE FROM op_checkpoints WHERE op=$1 AND fingerprint=$2', [PREVIEW_APPROVAL_OP, fingerprint(key.command, key.hash)]);
}

/** Applies one approved item and drops the set once the last item returns; an item that throws keeps the set, so the printed apply resumes with the same hash. */
export async function retireAfterLastItem<T>(engine: BrainEngine, command: PreviewApprovalCommand, hash: string | null | undefined, last: boolean, apply: () => Promise<T>): Promise<T> {
  const outcome = await apply();
  if (last && hash) await clearApprovedSet(engine, { command, hash });
  return outcome;
}