Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.9 KB
Raw Blame
/**
 * GBRA-133 (PR 2b): the managed no-op fast path. An idle tick (sync-pass-run.ts `stampIdlePass`, the pass kind
 * `syncPassKind` decides) stamps `last_sync_at` and the pass row under the drain lease and changes nothing else, yet the
 * managed branch still ran every settle after it: each one reads the state it would act on, finds nothing and returns.
 * The pin already reads most of that state, so the tick records here what it read, and each settle below is skipped when
 * the fact it acts on is absent. The tick itself, its lease, its pass row and its result are unchanged, and every settle
 * that can still find work on an idle tick (the upstream observation, the remember replay, the ghost-page report) runs.
 *
 * `GBRAIN_SYNC_IDLE_FAST_PATH=0` runs every settle again.
 */
import type { BrainEngine } from '../engine.ts';
import { loadSyncFailures } from '../sync-failure-ledger.ts';
import { GIT_HOLD_SUMMARY_OP, summaryFingerprint } from './sync-holds.ts';
import { currentDrainLease } from './sync-lease.ts';

/** Each settle an idle-clear tick skips, with why it has nothing to do then. */
export const IDLE_SKIPS = {
  hold_report: 'no hold of the incarnation and a zero hold summary, so buildHoldReport returns no fields (performManagedPass reads lease.idleClear itself)',
  settled_failures: 'no managed-sync-failure row of the source and no ledger row of the source, so nothing is cleared, settled or pruned',
  needs_human_sweep: 'no hold of the incarnation, so no hold turns needs_human and no soak event is counted',
  sync_tail: 'the pin read no owed tail under the lease (tailClear), so withSyncTail reads none',
  slug_heal: 'no hold of the incarnation, so no frontmatter_slug_conflict hold to heal',
  origin_heal: 'no hold of the incarnation, so no origin_conflict hold to heal',
} as const;
export type IdleSkip = keyof typeof IDLE_SKIPS;

/** What an idle tick's pin read: an owed tail, the incarnation's holds, its hold summary count and any failure row of the source. */
export interface IdleFacts { tail: boolean; holds: number; holdSummary: number; failures: boolean }

/** The facts the pin's other reads do not carry, read in the same round trip as them. */
export async function readIdleFacts(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, incarnation: string): Promise<Pick<IdleFacts, 'holdSummary' | 'failures'>> {
  const [row] = await engine.executeRaw<{ failures: boolean; hold_summary: number | string }>(
    `SELECT EXISTS(SELECT 1 FROM op_checkpoints WHERE op='managed-sync-failure' AND completed_keys->0->>'source_id'=$1) AS failures,
      COALESCE((SELECT (completed_keys->0->>'count')::int FROM op_checkpoints WHERE op=$2 AND fingerprint=$3),0) AS hold_summary`,
    [sourceId, GIT_HOLD_SUMMARY_OP, summaryFingerprint(sourceId, incarnation)]);
  return { failures: row?.failures === true, holdSummary: Number(row?.hold_summary ?? 0) };
}

/** Whether an idle tick with these facts leaves the settles in IDLE_SKIPS nothing to do. */
export function idleClear(facts: IdleFacts): boolean {
  // cwd-dotenv-ok: a kill switch that only turns the idle skips off (every settle runs, as before); it names no path.
  return process.env.GBRAIN_SYNC_IDLE_FAST_PATH !== '0' && !facts.tail && facts.holds === 0 && facts.holdSummary === 0 && !facts.failures;
}

/**
 * The settles the last pass under this source's drain lease leaves nothing to do; empty outside the lease or after any
 * pass that was not an idle-clear tick. Read inside the lease: a caller that settles after releasing it keeps the set.
 */
export function idleSkips(sourceId: string): ReadonlySet<IdleSkip> {
  const lease = currentDrainLease(sourceId);
  if (!lease?.idleClear) return new Set();
  const skips = new Set<IdleSkip>(['hold_report', 'needs_human_sweep', 'slug_heal', 'origin_heal']);
  if (lease.tailClear) skips.add('sync_tail');
  if (!loadSyncFailures().some(row => row.source_id === sourceId)) skips.add('settled_failures');
  return skips;
}