Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.7 KB
Raw Blame
/** Post-sync human reporting and best-effort nudges for the sync CLI. */
import { formatManagedSyncFailure, managedSyncRetryCommand } from '../../core/persistence/sync-failures.ts';
import type { BrainEngine } from '../../core/engine.ts';
import { isEmbeddingInfraCode, STRICT_REQUIRES_MANAGED } from '../../core/sync.ts';
import { serr } from '../../core/console-prefix.ts';
import { printManagedSyncDiagnostic, printManagedSyncNotes } from '../sync-diagnostics.ts';
import type { SyncResult } from '../sync.ts';

/**
 * v0.42.7 (#1696, D5): which terminal sync statuses warrant the end-of-sync
 * extraction-lag nudge. Fires on every non-error completion — crucially
 * `first_sync` (a fresh / --full import is the BIGGEST un-extracted backlog) and
 * `up_to_date` (a no-op sync over a brain with a pre-existing backlog still
 * warrants the nudge). Excludes `dry_run` (preview) / `blocked_by_failures` /
 * `partial` (inconsistent state). Pure so D5's contract is unit-testable
 * without driving the CLI.
 */
export function shouldNudgeAfterSync(status: SyncResult['status']): boolean {
  return status === 'synced' || status === 'first_sync' || status === 'up_to_date';
}

/**
 * #3068 / #5012: partials that do not converge on a plain retry exit
 * non-zero so cron and monitoring see them: a failed pull, connector items
 * that failed to import, and a connector that stopped early without a cause.
 * Timeout-class partials keep exit 0 (the next run continues).
 */
export function isFailedPartial(result: Pick<SyncResult, 'status' | 'reason'>): boolean {
  return result.status === 'partial'
    && (result.reason === 'pull_failed' || result.reason === 'connector_item_failures' || result.reason === 'connector_partial');
}

/**
 * Post-sync backup-coverage refresh (monthly, stale-only). The sync CLI is a
 * trusted local engine holder (D4), so the compute piggybacks here; the
 * shared choke point (getBackupStatus) makes a fresh cache a no-op file read.
 * Best-effort — never blocks or fails a sync.
 */
export async function maybeBackupCoverageRefresh(engine: BrainEngine): Promise<void> {
  try {
    const { backupCheckDisabled, isBackupStatusStale, loadBackupStatus } = await import(
      '../../core/backup/status-file.ts'
    );
    if (backupCheckDisabled() || !isBackupStatusStale(loadBackupStatus())) return;
    const { getBackupStatus } = await import('../../core/backup/coverage.ts');
    await getBackupStatus(engine, { localGitProbes: true, computedBy: 'sync' });
  } catch {
    /* best-effort — never block sync on it */
  }
}

/**
 * v0.42.7 (#1696), #6803 (D1): end-of-sync nudge when the brain (or a source)
 * carries a link/timeline extraction backlog. It IS doctor's
 * `links_extraction_lag` (one statement and verdict, core/extraction-lag.ts),
 * so it prints iff doctor would warn (attendance-blocked pages excluded), and
 * names both routes: plain `gbrain extract --stale` (30 min per run, resumes)
 * and `--catch-up` (finishes in one run), with an estimate at its stated basis.
 * Always stderr (never stdout — keeps `--json` clean), suppressible via
 * GBRAIN_SYNC_NO_EXTRACT_NUDGE, best-effort (never throws). Source-prefix-aware
 * via serr when called inside a withSourcePrefix scope.
 */
export async function maybeExtractionNudge(engine: BrainEngine, sourceId?: string): Promise<void> {
  if (process.env.GBRAIN_SYNC_NO_EXTRACT_NUDGE) return;
  try {
    const { checkLinksExtractionLag } = await import('../doctor.ts');
    const check = await checkLinksExtractionLag(engine, { sourceId });
    const d = check.details as { total: number; stale: number; attendance_blocked: number; mention_due: number | null; mention_last_pass_at: string | null; routes?: unknown } | undefined;
    if (check.status === 'ok' || !d?.routes) return;
    const { extractionNudgeLines } = await import('../../core/extraction-lag.ts');
    const lag = { total: d.total, actionable: d.stale, attendance_blocked: d.attendance_blocked, mention_due: d.mention_due, mention_last_pass_at: d.mention_last_pass_at };
    for (const line of extractionNudgeLines(lag, { sourceId })) serr(line);
  } catch { /* nudge is best-effort — never block sync on it */ }
}

/**
 * Render a SyncResult to a Writable sink.
 *
 * `sink` defaults to `process.stdout` so existing single-source callers
 * see identical output. The `--all` and single-source paths pass
 * `process.stderr` when `--json` is set, so banners stay off stdout and the
 * JSON envelope pipes cleanly through `jq` (D4).
 */
export function printSyncResult(result: SyncResult, sink: NodeJS.WriteStream = process.stdout) {
  if (printManagedSyncDiagnostic(result, sink)) {
    if (result.runId) sink.write(`  Committed counts are cumulative for run ${result.runId}: added=${result.added}, modified=${result.modified}, deleted=${result.deleted}.\n`);
    return;
  }
  const write = (line: string) => sink.write(line + '\n');
  const writeUncommittedNote = (u: NonNullable<SyncResult['uncommitted']>) =>
    write(
      `  NOTE: ${u.added + u.modified + u.deleted} uncommitted file(s) not synced ` +
      `(${u.added} untracked/added, ${u.modified} modified, ${u.deleted} deleted) — ` +
      `commit them or run 'gbrain sync --working-tree'.`,
    );
  switch (result.status) {
    case 'up_to_date':
      write('Already up to date.');
      if (result.uncommitted) writeUncommittedNote(result.uncommitted);
      break;
    case 'synced':
      // Connector sources have no commit range.
      write(result.toCommit ? `Synced ${result.fromCommit?.slice(0, 8) ?? '<initial>'}..${result.toCommit.slice(0, 8)}:` : 'Synced:');
      write(`  +${result.added} added, ~${result.modified} modified, -${result.deleted} soft-deleted (recoverable 72h), R${result.renamed} renamed`);
      write(`  ${result.chunksCreated} chunks created${result.embedded > 0 ? `, ${result.embedded} pages embedded` : ''}`);
      if (result.uncommitted) writeUncommittedNote(result.uncommitted);
      break;
    case 'first_sync':
      write(`First sync complete. Checkpoint: ${result.toCommit.slice(0, 8)}`);
      write(`  ${result.added} file(s) imported, ${result.chunksCreated} chunks${result.embedded > 0 ? `, ${result.embedded} pages embedded` : ''}`);
      break;
    case 'dry_run':
      if (result.managedCursor) write(`Sync dry run${result.toCommit ? ` to ${result.toCommit.slice(0, 8)}` : ''}: would add ${result.added}, modify ${result.modified}, soft-delete ${result.deleted}, rename ${result.renamed}${result.added + result.modified + result.deleted + result.renamed === 0 ? ' (no syncable changes)' : ''}.`);
      break;
    case 'blocked_by_failures': {
      if (result.runId || (result.pass && result.failures?.length)) {
        write(result.runId ? `Sync BLOCKED at ${result.toCommit}: committed counts are cumulative for run ${result.runId}.`
          : `Sync BLOCKED at ${result.toCommit.slice(0, 8)}: ${result.failedFiles ?? 0} file(s) failed.`);
        for (const failure of result.failures ?? []) write(`  ${formatManagedSyncFailure(failure)}`);
        const retries = [...new Set((result.failures ?? []).map(failure => managedSyncRetryCommand(failure)))];
        write(retries.length
          ? `  Fix the cause, then run: ${retries.join(' ; ')} (this admits a fresh run after active work drains).`
          : '  Fix the cause, then run gbrain sync --no-pull with the same source and options; it retries the recorded failure and admits a fresh run after active work drains.');
        break;
      }
      if (!result.toCommit) {
        write(`Sync BLOCKED: ${result.failedFiles ?? 0} file(s) failed to import (named above); fix them, then re-run 'gbrain sync'.`);
        break;
      }
      write(`Sync BLOCKED at ${result.toCommit.slice(0, 8)}: ${result.failedFiles ?? 0} file(s) failed.`);
      write(`  See ~/.gbrain/sync-failures.jsonl for details, or run 'gbrain doctor'.`);
      // #3875: code-aware recovery hint — provider-infra failures are not
      // fixed by --skip-failed (that would silently unindex good files).
      const infraCodes = (result.failureCodes ?? []).filter(c => isEmbeddingInfraCode(c.code));
      if ((result.failureCodes ?? []).some(c => c.code === STRICT_REQUIRES_MANAGED)) {
        write(`  ${STRICT_REQUIRES_MANAGED}: ${result.failureAdvice ?? 'the source is git-canonical and this brain does not have managed persistence. Do not use --skip-failed.'}`);
      } else if (infraCodes.length > 0) {
        write(
          `  Embedding provider errors (${infraCodes.map(c => `${c.code} x${c.count}`).join(', ')}): ` +
          `check provider health, then re-run 'gbrain sync' (or 'gbrain sync --full'). ` +
          `Do NOT use --skip-failed for provider errors.`,
        );
      } else {
        write(`  Pinpoint with 'gbrain frontmatter validate <path>', fix, then re-run 'gbrain sync', or 'gbrain sync --skip-failed' to move on.`);
      }
      break;
    }
    case 'partial':
      // #3068: a failed (non-timeout) pull with zero imports gets its own
      // message — "imported 0 of 0" reads like success, but the local
      // checkout may be behind a remote we could not fetch.
      if (result.reason === 'pull_failed') {
        write(
          `Sync INCOMPLETE at ${result.fromCommit?.slice(0, 8) ?? '<initial>'}: ` +
          `git pull failed — the local checkout may be behind its remote.`,
        );
        write(`  Fix the pull (see the warning above), then re-run 'gbrain sync' (last_commit unchanged; safe to retry).`);
        break;
      }
      if (result.reason === 'connector_item_failures') {
        write(
          `Sync PARTIAL [connector_item_failures]: ${result.failedFiles ?? 0} connector item(s) failed to import; ` +
          `${result.filesImported ?? result.added + result.modified} page(s) written.`,
        );
        write(`  The failure reasons are in the warnings above. Fix the cause, then re-run 'gbrain sync --source <id>' (the cursor did not advance past failed items; see 'gbrain sources status <id>'). Docs: docs/guides/google-connect.md#held-items`);
        break;
      }
      if (result.reason === 'connector_partial') {
        write(
          `Sync PARTIAL [connector_partial]: the connector stopped before finishing and reported no cause; ` +
          `${result.filesImported ?? result.added + result.modified} page(s) written.`,
        );
        write(`  Check the warnings above (expired or revoked credentials print there), fix the cause, then re-run 'gbrain sync --source <id>'.`);
        break;
      }
      // #5984: a managed cursor knows its manifest size; the drain summary prints the next step.
      if (result.managedCursor) {
        write(`Sync PARTIAL at ${result.fromCommit?.slice(0, 8) ?? '<initial>'}: ${result.managedCursor.index} of ${result.managedCursor.total} manifest entries processed, reason=${result.reason ?? 'timeout'} (last_commit unchanged; safe to retry).`);
        break;
      }
      // v0.41.13.0 (T7 / D-V3-5): --timeout fired before the bookmark write
      // so last_commit is UNCHANGED. The next sync re-walks the same diff
      // and content_hash short-circuits already-imported files at ~10ms each.
      // The reason field distinguishes generic timeout (mid-import) from
      // pull_timeout (subprocess wedge / SIGTERM during git pull).
      write(
        `Sync PARTIAL at ${result.fromCommit?.slice(0, 8) ?? '<initial>'}: ` +
        `imported ${result.filesImported ?? 0} of ${result.added + result.modified} file(s), ` +
        `reason=${result.reason ?? 'timeout'}.`,
      );
      write(`  Re-run 'gbrain sync' to continue (last_commit unchanged; safe to retry).`);
      break;
  }
  const holds = result.connectorHolds;
  if (holds) write(`  ${holds.held} connector item(s) held after repeated failures${holds.newly_held ? ` (${holds.newly_held} new)` : ''}; they do not block freshness. See them with '${holds.status_command}', re-attempt with '${holds.retry_command}'.`);
  printManagedSyncNotes(result, write);
}