Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.0 KB
Raw Blame
/**
 * The one in-process scheduler for the automatic facts drain (drain.ts), used
 * by stdio `gbrain serve` and `gbrain serve --http`. Its own unref'd timer
 * (never the 3-second idle maintenance sweep) ticks every 10 minutes; a tick
 * runs one bounded drain when the owner saw no foreground activity since the
 * previous tick, or when 30 minutes passed since the last run, so sustained
 * MCP traffic still gets a run at least every 30 minutes. At most one run is
 * in flight; `stop()` aborts it (the signal reaches the job handler) and
 * waits a bounded time for it to settle. A tick the owner vetoes (`canRun`,
 * e.g. while a delegated sync owns the event loop) is skipped, so the
 * 30-minute bound excludes an uninterrupted delegated sync.
 */
import type { BrainEngine } from '../engine.ts';
import { runFactsDrain, type FactsDrainOwner, type FactsDrainRunResult } from './drain.ts';

export const FACTS_DRAIN_TICK_MS = 10 * 60_000;
export const FACTS_DRAIN_MAX_GAP_MS = 30 * 60_000;
const STOP_SETTLE_MS = 5_000;

export interface FactsDrainSchedulerOpts {
  owner: FactsDrainOwner;
  tickMs?: number;
  maxGapMs?: number;
  wallClockMs?: number;
  /** Epoch ms of the owner's last foreground activity; omitted = always quiet. */
  lastActivityAt?: () => number;
  /** Owner veto for this tick (delegated sync running, engine degraded, shutting down). */
  canRun?: () => boolean | Promise<boolean>;
  setInterval?: (fn: () => unknown, ms: number) => unknown;
  clearInterval?: (handle: unknown) => void;
  now?: () => number;
  log?: (line: string) => void;
  /** Test seam: replaces runFactsDrain. */
  run?: (engine: BrainEngine, opts: { owner: FactsDrainOwner; signal: AbortSignal; wallClockMs?: number; log?: (line: string) => void }) => Promise<FactsDrainRunResult>;
}

export interface FactsDrainScheduler {
  /** Run one tick's decision now (tests and owners that want an early check). */
  tick(): Promise<FactsDrainRunResult | null>;
  stop(): Promise<void>;
  readonly running: boolean;
}

export function startFactsDrainScheduler(engine: BrainEngine, opts: FactsDrainSchedulerOpts): FactsDrainScheduler {
  const tickMs = opts.tickMs ?? FACTS_DRAIN_TICK_MS;
  const maxGapMs = opts.maxGapMs ?? FACTS_DRAIN_MAX_GAP_MS;
  const now = opts.now ?? Date.now;
  const run = opts.run ?? runFactsDrain;
  const abort = new AbortController();
  let lastRunAt = now();
  let lastTickAt = now();
  let inflight: Promise<FactsDrainRunResult | null> | null = null;
  let stopped = false;

  const tick = async (): Promise<FactsDrainRunResult | null> => {
    if (stopped || inflight || engine.kind !== 'pglite') return null;
    const at = now();
    const previousTick = lastTickAt;
    lastTickAt = at;
    const quiet = (opts.lastActivityAt?.() ?? 0) < previousTick;
    if (!quiet && at - lastRunAt < maxGapMs) return null;
    try {
      if (opts.canRun && !(await opts.canRun())) return null;
    } catch {
      return null;
    }
    lastRunAt = at;
    inflight = run(engine, { owner: opts.owner, signal: abort.signal, wallClockMs: opts.wallClockMs, ...(opts.log ? { log: opts.log } : {}) })
      .catch(() => null)
      .finally(() => { inflight = null; });
    return inflight;
  };

  const set = opts.setInterval ?? ((fn: () => unknown, ms: number) => setInterval(fn, ms));
  const clear = opts.clearInterval ?? ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
  const handle = engine.kind === 'pglite' ? set(() => tick(), tickMs) : null;
  (handle as { unref?: () => void } | null)?.unref?.();

  return {
    tick,
    get running() { return inflight !== null; },
    async stop() {
      if (stopped) return;
      stopped = true;
      if (handle !== null) clear(handle);
      abort.abort(new Error('shutdown'));
      const current = inflight;
      if (!current) return;
      let timer: ReturnType<typeof setTimeout> | undefined;
      await Promise.race([current, new Promise(resolve => { timer = setTimeout(resolve, STOP_SETTLE_MS); timer.unref?.(); })]);
      clearTimeout(timer);
    },
  };
}