Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.0 KB
Raw Blame
/**
 * Serve-delegated maintenance sweep — the CLI half (#677).
 *
 * On a PGLite brain a live `gbrain serve` holds the single-writer lock for
 * its lifetime, so `gbrain sweep --once` used to exit 1 with
 * LiveServeLockError. The pre-connect hook in cli.ts calls
 * maybeDelegateSweepToServe: when the holder is a live serve, the sweep runs
 * INSIDE the serve over the resolve-IPC socket (sweep_start / sweep_status;
 * wire shapes in core/context/sweep-ipc.ts, execution in
 * core/serve-sweep-runner.ts) and this module polls to completion and prints
 * the report — same decision ladder as commands/sync-delegate.ts.
 *
 * Returns false = fall through to the normal connect path (no live serve, or
 * an explicit opt-out); true = handled (delegated or politely refused with an
 * exit verdict).
 */

import { randomUUID } from 'node:crypto';
import { existsSync } from 'node:fs';
import { serr } from '../core/console-prefix.ts';
import { probeLivePgliteHolder } from '../core/bootstrap/uninstall.ts';
import {
  IPC_UNAVAILABLE,
  readIpcSecret,
  requestSweepStart,
  requestSweepStatus,
  resolveSocketPath,
  type SweepStartIpcResult,
} from '../core/context/resolve-ipc.ts';
import type { DelegatedSweepOptions, SweepStatusResponse } from '../core/context/sweep-ipc.ts';

const POLL_MS = 500;
const MAX_POLL_FAILURES = 60;
const PID_PROBE_EVERY = 5;

async function setVerdict(code: number): Promise<void> {
  const { setCliExitVerdict } = await import('../core/cli-force-exit.ts');
  setCliExitVerdict(code);
}

function remediation(pid: number, extra = ''): string {
  const tail = extra ? ` ${extra}` : '';
  return (
    `Alternatives: stop that serve (kill ${pid}) and re-run, or pass --no-delegate ` +
    `to skip delegation (the run will then fail while the serve holds the lock).${tail}`
  );
}

/** Flags this delegation understands (same default-deny posture as sync). */
const KNOWN_FLAGS = new Set(['--once', '--json', '--no-delegate', '--help', '-h']);
const VALUE_FLAGS = new Set(['--source', '--budget-ms', '--batch-limit']);

export type ParsedDelegatedSweepArgs =
  | { ok: true; options: DelegatedSweepOptions; jsonMode: boolean }
  | { ok: false; refused: string };

/** Pure argv classifier (exported for tests). Default-deny on unknown tokens. */
export function parseDelegatedSweepArgs(args: string[]): ParsedDelegatedSweepArgs {
  const options: DelegatedSweepOptions = {};
  let jsonMode = false;
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (VALUE_FLAGS.has(a)) {
      const v = args[i + 1];
      if (v === undefined) return { ok: false, refused: `${a} (missing value)` };
      if (a === '--source') options.sourceId = v;
      else {
        const n = Number(v);
        if (!Number.isInteger(n) || n < 0) return { ok: false, refused: `${a} ${v}` };
        if (a === '--budget-ms') options.budgetMs = n;
        else options.batchLimit = n;
      }
      i++;
      continue;
    }
    if (KNOWN_FLAGS.has(a)) {
      if (a === '--json') jsonMode = true;
      continue;
    }
    return { ok: false, refused: a };
  }
  return { ok: true, options, jsonMode };
}

/**
 * Delegate `gbrain sweep --once` to a live serve when one holds this PGLite
 * brain's lock. Mirrors maybeDelegateSyncToServe's ladder.
 */
export async function maybeDelegateSweepToServe(dataDir: string, args: string[]): Promise<boolean> {
  // 0. Explicit opt-outs + non-delegatable spellings (help prints locally;
  //    a missing --once is a local usage error).
  if (args.includes('--no-delegate') || process.env.GBRAIN_SWEEP_NO_DELEGATE === '1') return false;
  if (args.includes('--help') || args.includes('-h')) return false;
  if (!args.includes('--once')) return false;
  // 1. Mounts never delegate — the socket/secret/lock belong to the HOST brain.
  try {
    const { resolveBrainId } = await import('../core/brain-resolver.ts');
    const { getCliOptions } = await import('../core/cli-options.ts');
    if (resolveBrainId(getCliOptions().brain) !== 'host') return false;
  } catch { /* resolver trouble → normal path */ }
  // 2. Holder probe (read-only; never reaps).
  const holder = probeLivePgliteHolder(dataDir);
  if (!holder || !holder.serve) return false;

  // 3. Argv gate (default-deny).
  const parsed = parseDelegatedSweepArgs(args);
  if (!parsed.ok) {
    serr(
      `[sweep] a live \`gbrain serve\` (PID ${holder.pid}) holds this PGLite brain, and ` +
      `\`${parsed.refused}\` isn't supported through serve-delegated sweep. ` +
      remediation(holder.pid),
    );
    await setVerdict(1);
    return true;
  }

  // Engine-free source tier (env/dotfile); absent → the serve's bound/default.
  let sourceId = parsed.options.sourceId;
  if (!sourceId) {
    try {
      const { resolveSourceIdEngineFree } = await import('../core/source-resolver.ts');
      const resolved = resolveSourceIdEngineFree(null);
      if (resolved && resolved !== '__all__') sourceId = resolved;
    } catch { /* fall through to the serve's default */ }
  }

  // 4. Socket + secret.
  const sock = resolveSocketPath(dataDir);
  const secret = readIpcSecret(dataDir);
  if (!existsSync(sock) || !secret) {
    serr(
      `[sweep] a live \`gbrain serve\` (PID ${holder.pid}) holds this PGLite brain's ` +
      `single-writer lock but exposes no sweep IPC (older gbrain, or ` +
      `GBRAIN_SERVE_SYNC_IPC=0). ` + remediation(holder.pid, 'Restart that serve on this gbrain version.'),
    );
    await setVerdict(1);
    return true;
  }

  const options: DelegatedSweepOptions = { ...parsed.options, ...(sourceId ? { sourceId } : {}) };
  const clientToken = randomUUID();

  let start = await requestSweepStart(sock, { secret, clientToken, options });
  if (start === IPC_UNAVAILABLE) {
    const still = probeLivePgliteHolder(dataDir);
    if (!still || !still.serve) return false;
    start = await requestSweepStart(sock, { secret, clientToken, options });
    if (start === IPC_UNAVAILABLE) {
      serr(
        `[sweep] the live \`gbrain serve\` (PID ${holder.pid}) is not answering its IPC socket. ` +
        remediation(holder.pid, 'It may be wedged.'),
      );
      await setVerdict(1);
      return true;
    }
  }
  if ('degraded' in (start as object)) {
    serr(
      `[sweep] the running \`gbrain serve\` (PID ${holder.pid}) predates serve-delegated sweep. ` +
      remediation(holder.pid, 'Restart it on this gbrain version.'),
    );
    await setVerdict(1);
    return true;
  }
  const startResp = start as Exclude<SweepStartIpcResult, typeof IPC_UNAVAILABLE | { degraded: string }>;
  if (!startResp.ok) {
    const messages: Record<string, string> = {
      busy: `another delegated sweep is already running inside the serve — wait a moment and re-run.`,
      unauthorized: `the serve rejected the IPC secret — restart the serve (it re-provisions \`.gbrain-ipc-secret\`) and re-run.`,
      source_mismatch: `the serve is bound to a different source — run \`gbrain sweep --once --source <the serve's source>\`, or stop the serve.`,
      unsupported_kind: `the serve has delegation disabled (GBRAIN_SERVE_SYNC_IPC=0, an older serve, or a startup failure).`,
    };
    const detail = messages[startResp.error ?? ''] ??
      `the serve refused the delegated sweep (${startResp.error}).`;
    serr(`[sweep] ${detail} ${remediation(holder.pid, '')}`);
    await setVerdict(1);
    return true;
  }

  const jobId = startResp.jobId!;
  serr(
    `[sweep] live \`gbrain serve\` (PID ${holder.pid}) holds the PGLite lock — running ` +
    `the sweep inside it (job ${jobId}).`,
  );

  // Poll to completion (a sweep is bounded — default 5s budget).
  let failures = 0;
  for (;;) {
    await new Promise((r) => setTimeout(r, POLL_MS));
    const s = await requestSweepStatus(sock, { secret, jobId });
    if (s === IPC_UNAVAILABLE || 'degraded' in (s as object)) {
      failures++;
      if (failures % PID_PROBE_EVERY === 0) {
        const still = probeLivePgliteHolder(dataDir);
        if (!still || !still.serve) {
          serr(`[sweep] the serve (PID ${holder.pid}) died mid-sweep — re-run \`gbrain sweep --once\`.`);
          await setVerdict(1);
          return true;
        }
      }
      if (failures >= MAX_POLL_FAILURES) {
        serr(`[sweep] the serve (PID ${holder.pid}) stopped answering its IPC socket mid-sweep.`);
        await setVerdict(1);
        return true;
      }
      continue;
    }
    failures = 0;
    const status = s as SweepStatusResponse;
    if (!status.ok) {
      serr(
        status.error === 'unknown_job'
          ? `[sweep] the serve restarted mid-sweep (job ${jobId} is gone) — re-run \`gbrain sweep --once\`.`
          : `[sweep] delegated sweep failed: ${status.error}`,
      );
      await setVerdict(1);
      return true;
    }
    if (status.state === 'error') {
      serr(`[sweep] delegated sweep failed inside the serve: ${status.jobError ?? 'unknown error'}`);
      await setVerdict(1);
      return true;
    }
    if (status.state === 'done' && status.report) {
      const report = status.report;
      if (parsed.jsonMode) {
        console.log(JSON.stringify(report, null, 2));
      } else {
        console.log(`Sweep complete (${report.durationMs}ms, source=${status.sourceId ?? 'default'}, via serve PID ${holder.pid}):`);
        console.log(`  facts reconciled:   ${report.factsReconciled}`);
        console.log(`  links extracted:    ${report.linksExtracted}`);
        console.log(`  links removed:      ${report.linksRemoved}`);
        console.log(`  timeline extracted: ${report.timelineExtracted}`);
        console.log(`  corpus ingested:    ${report.corpusIngested}`);
        if (report.skipped.length > 0) {
          console.log('  skipped:');
          for (const sk of report.skipped) console.log(`    ${sk.reason}: ${sk.count}`);
        }
      }
      // Mirror runSweep's exit rule: total failure exits nonzero.
      const { isTotalFailure } = await import('./sweep.ts');
      if (isTotalFailure(report)) {
        serr('[sweep] total failure — every pass errored. See skipped reasons above.');
        await setVerdict(1);
      }
      return true;
    }
    // running → keep polling.
  }
}