Class SessionCronStore

packages/agent-core/src/tools/cron/session-store.ts:44–151

const MAX_ID_ATTEMPTS = 8;

export class SessionCronStore {
  /**
   * Backing map. `Map` preserves insertion order in JS, which we rely on
   * for {@link list}.
   */
  private readonly tasks = new Map<string, CronTask>();

  /**
   * Generate a fresh 8-hex id and add the task. `createdAt` is set to
   * the supplied `nowMs` — the store never reads its own clock.
   *
   * Throws if the PRNG fails to produce an unused id within
   * {@link MAX_ID_ATTEMPTS} attempts. That should be unreachable in
   * practice; surfacing it as a throw beats silently retrying forever.
   */
  add(init: SessionCronTaskInit, nowMs: number): CronTask {
    const id = this.generateUniqueId();
    const task: CronTask = {
      ...init,
      id,
      createdAt: nowMs,
    };
    this.tasks.set(id, task);
    return task;
  }

  /**
   * Insert a previously-persisted task verbatim — id and createdAt
   * stay as they are on disk. Used by `CronManager.loadFromDisk()` to
   * rehydrate the store on resume. Unlike {@link add}, this does NOT
   * generate a new id; the caller is responsible for ensuring the id
   * matches the expected shape (the persistence layer's regex /
   * shape-guard handle this upstream).
   *
   * Overwrites any existing in-memory task with the same id — reload
   * is a "replace" operation, not a "merge". Callers that want merge
   * semantics should clear the store first.
   */
  adopt(task: CronTask): void {
    this.tasks.set(task.id, task);
  }

  /**
   * Stamp `lastFiredAt` on the in-memory task. Used by the scheduler
   * cursor-advance callback so the value flows back to disk via the
   * manager's persistence path. Returns the updated record (so the
   * manager can hand it straight to the per-id JSON writer), or
   * `undefined` when no task with that id is present — the latter
   * happens harmlessly if a task was concurrently removed between the
   * scheduler's fire and the cursor callback.
   */
  markFired(id: string, lastFiredAt: number): CronTask | undefined {
    const existing = this.tasks.get(id);
    if (existing === undefined) return undefined;
    const updated: CronTask = { ...existing, lastFiredAt };
    this.tasks.set(id, updated);
    return updated;
  }