@cursor/july 0.1.76 → 0.1.78

package/src/ledger/janitor.ts

@@ -1,193 +0,0 @@
-/**
- * The ledger janitor: lazy crash recovery has a hole — a session with
- * pending events and no future events would wait forever — so serving runs
- * this loop. It scans `ledger/` by prefix, finds pending-with-expired-lease
- * sessions, claims them, and hands each claim to the execution callback.
- * Self-host runs the same loop; it is part of the library, not the control
- * plane.
- *
- * Nothing starts on construction: call `start()` for the interval loop or
- * `runOnce()` for an explicit pass (what unit tests use).
- */
-
-import type {
-  ClaimResult,
-  LedgerLease,
-  SessionLedger,
-} from "./session-ledger.js";
-
-export const DEFAULT_JANITOR_INTERVAL_MS = 15_000;
-
-export interface JanitorClaimedSession {
-  sessionId: string;
-  lease: LedgerLease;
-  head: number;
-  pending: string[];
-}
-
-export interface JanitorRunResult {
-  /** Ledgers scanned this pass. */
-  scanned: number;
-  /** Sessions this pass claimed and handed to the callback. */
-  claimed: JanitorClaimedSession[];
-  /** Orphan blob ids deleted (only when the sweep is enabled). */
-  orphansDeleted: string[];
-}
-
-export interface LedgerJanitorOptions {
-  ledger: SessionLedger;
-  /**
-   * Executes a recovered session: drain, run the turn, commit. Awaited so
-   * one pass never claims more sessions than it can serve.
-   */
-  onSession: (session: JanitorClaimedSession) => Promise<void> | void;
-  /** Scan cadence for `start()` (default {@link DEFAULT_JANITOR_INTERVAL_MS}). */
-  intervalMs?: number;
-  /**
-   * Also sweep unreferenced mailbox blobs each pass. Off by default —
-   * enable with `{ olderThanMs }` (see `SessionLedger.sweepOrphans`).
-   */
-  orphanSweep?: { olderThanMs?: number };
-  /** Called with per-session or sweep failures; the pass continues. */
-  onError?: (error: unknown, sessionId?: string) => void;
-  /** Time source for lease-expiry checks (default `Date.now`). */
-  clock?: () => number;
-}
-
-export interface LedgerJanitor {
-  start(): void;
-  /**
-   * Clear the interval AND await any in-flight pass: a running pass can
-   * claim a session and spawn a turn, so shutdown must not proceed while
-   * one is mid-scan.
-   */
-  stop(): Promise<void>;
-  runOnce(): Promise<JanitorRunResult>;
-}
-
-export function createLedgerJanitor(
-  options: LedgerJanitorOptions
-): LedgerJanitor {
-  const intervalMs = options.intervalMs ?? DEFAULT_JANITOR_INTERVAL_MS;
-  const clock = options.clock ?? Date.now;
-  const reportError =
-    options.onError ??
-    ((): void => {
-      // Recovery is best-effort per pass; an unobserved failure is retried
-      // on the next scan.
-    });
-
-  let timer: ReturnType<typeof setInterval> | undefined;
-  let running = false;
-  /** The settled-shape promise of the pass currently scanning, if any. */
-  let inFlight: Promise<void> | undefined;
-
-  const runPass = async (): Promise<JanitorRunResult> => {
-    // An unparseable ledger record is reported and skipped: it degrades
-    // that one session's recovery, never the whole agent's pass.
-    const ledgers = await options.ledger.listLedgers((key, error) => {
-      reportError(
-        new Error(
-          `janitor scan: skipping unparseable ledger record at ${key}: ${String(
-            error instanceof Error ? error.message : error
-          )}`
-        )
-      );
-    });
-    const claimed: JanitorClaimedSession[] = [];
-    for (const snapshot of ledgers) {
-      if (snapshot.pending.length === 0) {
-        continue;
-      }
-      if (snapshot.lease !== null && snapshot.lease.expiresAt > clock()) {
-        continue;
-      }
-      let claim: ClaimResult;
-      try {
-        claim = await options.ledger.claim(snapshot.sessionId);
-      } catch (error) {
-        reportError(error, snapshot.sessionId);
-        continue;
-      }
-      if (!claim.claimed) {
-        continue;
-      }
-      const session: JanitorClaimedSession = {
-        sessionId: snapshot.sessionId,
-        lease: claim.lease,
-        head: claim.head,
-        pending: claim.pending,
-      };
-      claimed.push(session);
-      try {
-        await options.onSession(session);
-      } catch (error) {
-        reportError(error, snapshot.sessionId);
-      }
-    }
-
-    let orphansDeleted: string[] = [];
-    if (options.orphanSweep !== undefined) {
-      try {
-        const swept = await options.ledger.sweepOrphans({
-          olderThanMs: options.orphanSweep.olderThanMs,
-        });
-        orphansDeleted = swept.deleted;
-      } catch (error) {
-        reportError(error);
-      }
-    }
-    return { scanned: ledgers.length, claimed, orphansDeleted };
-  };
-
-  const runOnce = (): Promise<JanitorRunResult> => {
-    const pass = runPass();
-    const settled = pass.then(
-      () => undefined,
-      () => undefined
-    );
-    inFlight = settled;
-    void settled.finally(() => {
-      if (inFlight === settled) {
-        inFlight = undefined;
-      }
-    });
-    return pass;
-  };
-
-  const tick = async (): Promise<void> => {
-    // Skip a tick rather than overlap passes when a scan outlasts the
-    // cadence — overlapping claims would just fence each other.
-    if (running) {
-      return;
-    }
-    running = true;
-    try {
-      await runOnce();
-    } catch (error) {
-      reportError(error);
-    } finally {
-      running = false;
-    }
-  };
-
-  return {
-    start(): void {
-      if (timer !== undefined) {
-        return;
-      }
-      timer = setInterval(() => {
-        void tick();
-      }, intervalMs);
-      timer.unref?.();
-    },
-    async stop(): Promise<void> {
-      if (timer !== undefined) {
-        clearInterval(timer);
-        timer = undefined;
-      }
-      await inFlight;
-    },
-    runOnce,
-  };
-}