Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.9 KB
Raw Blame
/**
 * gbrain pages — page-level operator commands. v0.26.5+.
 *
 * The first subcommand: `pages purge-deleted [--older-than HOURS|Nh|Nd] [--retry-parked] [--dry-run] [--json] [--yes]`.
 * `pages unsearchable` (#6696 B3) lists embedding-state rows; its body is pages-unsearchable.ts.
 * `pages ghosts [--source <id>] [--json]` (#6696 B5, pages-ghosts.ts) lists ghost pages, read-only.
 * `pages status <slug...> [--source <id>] [--json]` (#7179, pages-status.ts) says whether each page is searchable and why, read-only.
 * Manual escape hatch alongside the autopilot purge phase. Hard-deletes pages
 * whose `deleted_at` is older than the cutoff; cascades to content_chunks,
 * page_links, chunk_relations via existing FKs.
 */
import type { BrainEngine } from '../core/engine.ts';
import { notHeld, purgeConsentRequest, purgeDeletedPagesCoordinated, selectPurgeCandidates } from '../core/persistence/purge-deleted.ts';
import { PURGE_PARK_LIMIT } from '../core/persistence/purge-parks.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { consentGate } from '../core/consent-cli.ts';
import { strictArgsRefusal } from '../cli/strict-args.ts';
import { PAGES_SUBCOMMANDS, ROUTERS, subcommandHelpRequested } from '../cli/subcommands.ts';

const SOFT_DELETE_TTL_HOURS_DEFAULT = 72;

export { PAGES_SUBCOMMANDS as SUBCOMMANDS } from '../cli/subcommands.ts';

export interface PurgeArgs { olderThanHours: number; dryRun: boolean; json: boolean; retryParked: boolean }

/**
 * Strict `purge-deleted` arguments (#6114): exactly `--dry-run`, `--json`,
 * `--retry-parked` (#6741), `--yes` (read by the consent gate) and one `--older-than <HOURS|Nh|Nd>` (also `--older-than=N`).
 * Anything else throws `invalid_params` before the engine is touched; cli.ts
 * refuses the same tokens earlier through the same table.
 */
export function parsePurgeArgs(args: readonly string[]): PurgeArgs {
  const refusal = strictArgsRefusal('pages', ['purge-deleted', ...args]);
  if (refusal) throw refusal;
  let olderThanHours = SOFT_DELETE_TTL_HOURS_DEFAULT;
  for (let i = 0; i < args.length; i++) {
    const a = args[i]!;
    const raw = a === '--older-than' ? args[++i]! : a.startsWith('--older-than=') ? a.slice('--older-than='.length) : null;
    if (raw === null) continue;
    const n = parseInt(raw, 10);
    olderThanHours = raw.endsWith('d') ? n * 24 : n;
  }
  return { olderThanHours, dryRun: args.includes('--dry-run'), json: args.includes('--json'), retryParked: args.includes('--retry-parked') };
}

async function runPurgeDeleted(engine: BrainEngine, args: string[]): Promise<void> {
  const { olderThanHours, dryRun, json, retryParked } = parsePurgeArgs(args);
  // #6741: one selector for the preview, the consent and the run (selectPurgeCandidates): the same cutoff, rename
  // holds, writer state and parks; --retry-parked puts the parked pages the cutoff selects back among the candidates.
  // GST-2689: the preview reads ahead what the run's carry does (forecastCarry, read-only), so it lists the parked origins
  // the run releases and leaves out the ones it parks; nothing is labelled before the consent.
  const forecast = await (await import('../core/repair/origin-carry.ts')).forecastCarry(engine, olderThanHours);
  const selection = await selectPurgeCandidates(engine, olderThanHours, { retryParked, forecast });
  const retried = selection.parked.filter(park => park.retried).length;
  const notes = { ...(selection.parked.length ? { parked: selection.parked, retry_parked: retryParked } : {}), ...(selection.blocked.length ? { blocked: selection.blocked } : {}),
    ...(selection.released_origins.length ? { released_origins: selection.released_origins } : {}) };

  if (dryRun) {
    // Read-only: the same predicate and DB now() clock as the real purge; only the verb differs.
    if (json) {
      console.log(JSON.stringify({ dry_run: true, older_than_hours: olderThanHours, count: selection.count, slugs: selection.slugs, sync_unreviewed: selection.sync_unreviewed, ...notes }, null, 2));
      return;
    }
    console.log(`(dry-run) Would purge ${selection.count} page(s) soft-deleted more than ${olderThanHours}h ago.`);
    // #7130: the automatic purge keeps these; a purged page can only come back from a backup.
    if (selection.sync_unreviewed) console.log(`  ${selection.sync_unreviewed} of them were deleted by a managed sync, not a person, and no live page has their content; restore any you need first (gbrain restore <slug> --source-id <id> --force). A purged page can only come back from a backup.`);
    for (const p of selection.pages ?? []) console.log(`  ${p.slug}  deleted_at=${p.deleted_at.toISOString()}`);
    for (const c of selection.candidates) console.log(`  ${c.source_id}/${c.slug}${c.park ? ' (parked; retried once more)' : ''}${c.sync_unreviewed ? ' (deleted by a managed sync; no live twin)' : ''}`);
    for (const p of selection.parked.filter(park => !park.retried)) console.log(`  parked: ${p.source_id}/${p.slug} after ${p.failures} failures (${p.code ?? 'error'}); skipped unless --retry-parked`);
    for (const b of selection.blocked.filter(entry => entry.code === 'writer_not_active')) console.log(`  waiting: ${b.source_id}/${b.slug}: ${b.reason}`);
    for (const o of selection.released_origins) console.log(`  released: ${o.source_id}/${o.slug} is parked (gbrain doctor: derived_origin_parked); the run labels the pages derived from it private first and keeps it parked if that fails`);
    return;
  }

  // D6: a hard purge is irreversible and brain-wide, so the CLI asks first
  // (a TTY prompt, `--yes`, or exit 3 with the consent payload). The
  // autopilot purge phase calls the library directly and is unaffected.
  if (selection.count === 0) {
    if (json) console.log(JSON.stringify({ older_than_hours: olderThanHours, count: 0, slugs: [], ...notes }, null, 2));
    else {
      console.log(`No pages to purge (older than ${olderThanHours}h).`);
      for (const b of selection.blocked) console.error(`Not purged: ${b.source_id}/${b.slug}: ${b.reason}`);
    }
    return;
  }
  const authorized = await consentGate(purgeConsentRequest(selection.count, olderThanHours, json, args, retryParked, retried, selection.sync_unreviewed), { json });
  if (!authorized) return;

  const result = await purgeDeletedPagesCoordinated(engine, olderThanHours, { retryParked, release: forecast.release.map(origin => origin.id), only: notHeld(forecast) });
  if (json) {
    console.log(JSON.stringify({ older_than_hours: olderThanHours, count: result.count, slugs: result.slugs,
      ...(result.capacity_deferred ? { capacity_deferred: result.capacity_deferred } : {}), ...(result.blocked.length ? { blocked: result.blocked } : {}) }, null, 2));
    if (result.error) setCliExitVerdict(1);
    return;
  }
  for (const b of result.blocked) console.error(`Not purged: ${b.source_id}/${b.slug}: ${b.reason}`);
  if (result.error) setCliExitVerdict(1);
  if (result.count === 0) {
    console.log(`No pages to purge (older than ${olderThanHours}h).`);
  } else {
    console.log(`Purged ${result.count} page(s) (older than ${olderThanHours}h):`);
    for (const slug of result.slugs) console.log(`  ${slug}`);
  }
}

export function printUsage(): void {
  console.log(`gbrain pages — page-level operator commands

Subcommands:
  ghosts [--source <id>] [--json]   List live pages whose canonical file is missing on the
                                    owner host (ghost pages). Read-only; remove them with
                                    gbrain repair ghost-pages --source <id> (preview first).
  purges list [--source <id>] [--json]
                                    List page purge tombstones (slug, hash, request, time).
  unpurge <slug> [--source <id>] [--json]
                                    Clear a page's purge tombstones so its old content can be
                                    imported again. Restores nothing.
  purge-deleted [--older-than HOURS|Nh|Nd] [--retry-parked] [--dry-run] [--json] [--yes]
                                    Hard-delete soft-deleted pages older than the cutoff
                                    (default 72h) in every source of the brain (per-source
                                    purge is not supported). Cascades to chunks/links/edges.
                                    Asks first: a TTY prompt, --yes, or exit 3 with the
                                    consent payload. Preview with --dry-run --json.
                                    Mirror of the autopilot purge phase. On a managed brain a
                                    page whose purge failed ${PURGE_PARK_LIMIT} times is parked;
                                    --retry-parked tries each parked page once more.
  unsearchable --source <id> [--state <state>] [--limit N] [--json]
                                    Read-only: pages search cannot fully see, one row per
                                    page and embedding state (pending, keyword_only,
                                    quarantined, empty, deleted_page_chunks,
                                    chunkless_healable; embedded only via --state) with
                                    reason, chunks, bytes and each state's fix. --limit
                                    defaults to 50; complete:false means more rows exist.
  status <slug...> [--source <id>] [--json]
                                    Read-only: per page, whether search can find it (state,
                                    searchable true|keyword|false), its chunks and vector-less
                                    chunks, any large-page embedding hold or sync hold on its
                                    file, whether the file is in the synced commit, why, and
                                    the fix. A page that is not searchable still exits 0.

Notes:
  Soft-delete a page via \`gbrain delete <slug> --force\`; restore via \`gbrain restore <slug> --force\`
  (the delete_page / restore_page ops, equally reachable over MCP). Deleting also removes
  the page's markdown file from the source working tree; restoring re-creates it.
  This command is the manual operator escape hatch — the autopilot cycle's
  purge phase already calls the same library function on every run.
`);
}

export async function runPages(engine: BrainEngine, args: string[]): Promise<void> {
  if (subcommandHelpRequested(args, ROUTERS.pages)) { printUsage(); return; }
  const sub = args[0] as (typeof PAGES_SUBCOMMANDS)[number] | undefined;
  switch (sub) {
    case 'purge-deleted': return runPurgeDeleted(engine, args.slice(1));
    case 'purges': case 'unpurge': return (await import('./pages-purges.ts')).runPagePurges(engine, sub, args.slice(1));
    case 'unsearchable': return (await import('./pages-unsearchable.ts')).runPagesUnsearchable(engine, args.slice(1));
    case 'ghosts': return (await import('./pages-ghosts.ts')).runPagesGhosts(engine, args.slice(1));
    case 'status': return (await import('./pages-status.ts')).runPagesStatus(engine, args.slice(1));
    case undefined:
      printUsage();
      return;
    default:
      console.error(`Unknown subcommand: ${sub}`);
      printUsage();
      process.exit(2);
  }
}