@cursor/july 0.1.1

package/src/internal/reminder-runner.ts

@@ -0,0 +1,756 @@
+/**
+ * Per-session reminder runner: durable wake subscriptions with
+ * prompt XOR run, every/cron/delay/at schedules, and until as
+ * function XOR prompt.
+ */
+
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import type {
+  AuthContext,
+  ReminderCreateInput,
+  ReminderFireContext,
+  ReminderFireResult,
+  ReminderInfo,
+  ReminderUntilContext,
+} from "../types.js";
+import { parseDuration } from "./duration.js";
+import {
+  defaultBusyPolicy,
+  MAX_TIMER_MS,
+  nextCronFireMs,
+  ReminderValidationError,
+  resolveSchedule,
+} from "./reminder-schedule.js";
+import {
+  type ReminderBusyPolicy,
+  type ReminderRecord,
+  ReminderStore,
+} from "./reminder-store.js";
+import { APP_AUTH } from "./schedule-runner.js";
+import { SessionBusyError, type SessionEngine } from "./session-engine.js";
+
+export { ReminderValidationError } from "./reminder-schedule.js";
+
+export class UnknownReminderError extends Error {
+  constructor(
+    reminderId: string,
+    readonly availableReminderIds: string[]
+  ) {
+    super(`Unknown reminder "${reminderId}"`);
+    this.name = "UnknownReminderError";
+  }
+}
+
+interface LiveHandlers {
+  run?: (ctx: ReminderFireContext) => Promise<ReminderFireResult>;
+  untilFn?: (ctx: ReminderUntilContext) => Promise<boolean>;
+}
+
+function newReminderId(): string {
+  return `rem_${randomBytes(8).toString("hex")}`;
+}
+
+function toInfo(record: ReminderRecord): ReminderInfo {
+  return {
+    id: record.id,
+    purpose: record.purpose,
+    channelId: record.channelId,
+    continuationToken: record.continuationToken,
+    target: record.target,
+    scheduleKind: record.scheduleKind,
+    scheduleValue: record.scheduleValue,
+    prompt: record.prompt,
+    untilPrompt: record.untilPrompt,
+    busyPolicy: record.busyPolicy,
+    status: record.status,
+    disarmReason: record.disarmReason,
+    fireCount: record.fireCount,
+    nextFireAt: new Date(record.nextFireAtMs).toISOString(),
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    hasRunHandler: record.hasRunHandler === true,
+    hasUntilFn: record.hasUntilFn === true,
+  };
+}
+
+function buildFirePrompt(record: ReminderRecord): string {
+  const recurring =
+    record.scheduleKind === "every" || record.scheduleKind === "cron";
+  const lines = [
+    `[reminder] id=${record.id} purpose=${record.purpose}`,
+    record.prompt ??
+      "Reminder fired. Check current state and only act if needed.",
+  ];
+  if (record.untilPrompt !== undefined && record.untilPrompt.trim() !== "") {
+    lines.push("", `Stop condition: ${record.untilPrompt}`);
+    if (recurring) {
+      lines.push(
+        `When the stop condition is met, call reminders_cancel with id=${record.id}.`
+      );
+    } else {
+      lines.push(
+        "This is a one-shot reminder (auto-completes after this fire); no cancel needed unless you armed a separate recurring reminder."
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+export class ReminderRunner {
+  private readonly store: ReminderStore;
+  private readonly handlers = new Map<string, LiveHandlers>();
+  private readonly timers = new Map<string, NodeJS.Timeout>();
+  private readonly firing = new Set<string>();
+  /** Single-flight idle gates keyed by `channelId:continuationToken`. */
+  private readonly idleGates = new Map<string, Promise<void>>();
+  private started = false;
+
+  constructor(
+    private readonly engine: SessionEngine,
+    private readonly logger: (line: string) => void = () => {}
+  ) {
+    this.store = new ReminderStore(join(engine.stateRoot, "reminders"));
+  }
+
+  get storeRoot(): string {
+    return join(this.engine.stateRoot, "reminders");
+  }
+
+  /** Start deadline timers for armed reminders (call after restore). */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    const armed = await this.store.listArmed();
+    let restored = 0;
+    let disarmedOrphan = 0;
+    for (const record of armed) {
+      // Run / function-until handlers are in-memory only. After restart they
+      // are gone — disarm rather than falling back to a generic prompt fire.
+      if (
+        (record.hasRunHandler === true || record.hasUntilFn === true) &&
+        this.handlers.get(record.id) === undefined
+      ) {
+        await this.disarm(record, "handler_lost_on_restart");
+        disarmedOrphan += 1;
+        continue;
+      }
+      this.armTimer(record);
+      restored += 1;
+    }
+    if (restored > 0 || disarmedOrphan > 0) {
+      this.logger(
+        `[agent-serve] reminders: restored ${restored} armed reminder(s)` +
+          (disarmedOrphan > 0
+            ? `; disarmed ${disarmedOrphan} without live handlers`
+            : "")
+      );
+    }
+  }
+
+  stop(): void {
+    this.started = false;
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.idleGates.clear();
+  }
+
+  async create(input: ReminderCreateInput): Promise<ReminderInfo> {
+    const hasPrompt = input.prompt !== undefined;
+    const hasRun = input.run !== undefined;
+    if (hasPrompt === hasRun) {
+      throw new ReminderValidationError(
+        "reminders.create requires exactly one of prompt or run"
+      );
+    }
+    if (input.continuationToken.trim() === "") {
+      throw new ReminderValidationError("continuationToken is required");
+    }
+    if (input.channelId.trim() === "") {
+      throw new ReminderValidationError("channelId is required");
+    }
+    if (input.purpose.trim() === "") {
+      throw new ReminderValidationError("purpose is required");
+    }
+
+    const schedule = resolveSchedule(input);
+    const busyPolicy: ReminderBusyPolicy =
+      input.busyPolicy ?? defaultBusyPolicy(schedule.kind);
+    const now = new Date().toISOString();
+    const id = newReminderId();
+
+    const untilPrompt =
+      typeof input.until === "string" ? input.until : undefined;
+    const untilFn = typeof input.until === "function" ? input.until : undefined;
+    const hasRunHandler = input.run !== undefined;
+    const hasUntilFn = untilFn !== undefined;
+
+    const record: ReminderRecord = {
+      version: 1,
+      id,
+      purpose: input.purpose,
+      channelId: input.channelId,
+      continuationToken: input.continuationToken,
+      target: input.target,
+      scheduleKind: schedule.kind,
+      scheduleValue: schedule.value,
+      intervalMs: schedule.intervalMs,
+      prompt: input.prompt,
+      hasRunHandler,
+      hasUntilFn,
+      untilPrompt,
+      busyPolicy,
+      status: "armed",
+      fireCount: 0,
+      nextFireAtMs: schedule.nextFireAtMs,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await this.store.save(record);
+    this.handlers.set(id, {
+      run: input.run,
+      untilFn,
+    });
+    if (this.started) {
+      this.armTimer(record);
+    }
+
+    return toInfo(record);
+  }
+
+  async list(filter?: {
+    status?: ReminderRecord["status"];
+    purpose?: string;
+    continuationToken?: string;
+  }): Promise<ReminderInfo[]> {
+    const all = await this.store.list();
+    return all
+      .filter((r) => {
+        if (filter?.status !== undefined && r.status !== filter.status) {
+          return false;
+        }
+        if (filter?.purpose !== undefined && r.purpose !== filter.purpose) {
+          return false;
+        }
+        if (
+          filter?.continuationToken !== undefined &&
+          r.continuationToken !== filter.continuationToken
+        ) {
+          return false;
+        }
+        return true;
+      })
+      .map((r) => {
+        const live = this.handlers.get(r.id);
+        const info = toInfo(r);
+        if (live === undefined) return info;
+        return {
+          ...info,
+          hasRunHandler: live.run !== undefined || info.hasRunHandler,
+          hasUntilFn: live.untilFn !== undefined || info.hasUntilFn,
+        };
+      });
+  }
+
+  async cancel(
+    id: string,
+    reason = "explicit_cancel"
+  ): Promise<ReminderInfo | undefined> {
+    const record = await this.store.get(id);
+    if (record === undefined) {
+      return undefined;
+    }
+    if (record.status !== "armed") {
+      return toInfo(record);
+    }
+    this.clearTimer(id);
+    const updated: ReminderRecord = {
+      ...record,
+      status: "cancelled",
+      disarmReason: reason,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.store.save(updated);
+    this.handlers.delete(id);
+    return toInfo(updated);
+  }
+
+  /** Cancel all armed reminders matching a continuation token (e.g. PR closed). */
+  async cancelForContinuation(
+    continuationToken: string,
+    reason: string
+  ): Promise<number> {
+    const armed = await this.store.listArmed();
+    let n = 0;
+    for (const record of armed) {
+      if (record.continuationToken === continuationToken) {
+        await this.cancel(record.id, reason);
+        n += 1;
+      }
+    }
+    return n;
+  }
+
+  /** Fire one reminder immediately (dev / hillclimb). */
+  async dispatch(reminderId: string): Promise<{
+    reminderId: string;
+    outcome: "fired" | "noop";
+    reason?: string;
+  }> {
+    const record = await this.store.get(reminderId);
+    if (record === undefined) {
+      const ids = (await this.store.list()).map((r) => r.id);
+      throw new UnknownReminderError(reminderId, ids);
+    }
+    const result = await this.fire(record.id, { force: true });
+    return { reminderId, ...result };
+  }
+
+  private armTimer(record: ReminderRecord): void {
+    this.clearTimer(record.id);
+    if (!this.started || record.status !== "armed") return;
+    const nextFireAtMs = Number.isFinite(record.nextFireAtMs)
+      ? record.nextFireAtMs
+      : Date.now();
+    const delay = Math.min(
+      MAX_TIMER_MS,
+      Math.max(0, nextFireAtMs - Date.now())
+    );
+    const timer = setTimeout(() => {
+      void this.fire(record.id).catch(async (error) => {
+        this.logger(
+          `[agent-serve] reminder "${record.id}" fire failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        // Keep recurring reminders alive after unexpected throws.
+        // One-shots stay armed so a failed wake can be retried / dispatched.
+        try {
+          const current = await this.store.get(record.id);
+          if (current === undefined || current.status !== "armed") return;
+          const oneShot =
+            current.scheduleKind === "delay" || current.scheduleKind === "at";
+          if (oneShot) {
+            this.armTimer(current);
+            return;
+          }
+          await this.afterFire(current, "skip");
+        } catch (rescheduleError) {
+          this.logger(
+            `[agent-serve] reminder "${record.id}" reschedule after failure failed: ${
+              rescheduleError instanceof Error
+                ? rescheduleError.message
+                : String(rescheduleError)
+            }`
+          );
+        }
+      });
+    }, delay);
+    timer.unref?.();
+    this.timers.set(record.id, timer);
+  }
+
+  private clearTimer(id: string): void {
+    const timer = this.timers.get(id);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      this.timers.delete(id);
+    }
+  }
+
+  private async fire(
+    id: string,
+    opts: { force?: boolean } = {}
+  ): Promise<{ outcome: "fired" | "noop"; reason?: string }> {
+    if (this.firing.has(id)) {
+      return { outcome: "noop", reason: "already_firing" };
+    }
+    this.firing.add(id);
+    try {
+      const record = await this.store.get(id);
+      if (record === undefined || record.status !== "armed") {
+        this.clearTimer(id);
+        return { outcome: "noop", reason: "not_armed" };
+      }
+
+      if (!opts.force && record.nextFireAtMs > Date.now() + 50) {
+        // Spurious early wake — re-arm.
+        this.armTimer(record);
+        return { outcome: "noop", reason: "not_due" };
+      }
+
+      const live = this.handlers.get(id) ?? {};
+      if (
+        (record.hasRunHandler === true || record.hasUntilFn === true) &&
+        live.run === undefined &&
+        live.untilFn === undefined
+      ) {
+        await this.disarm(record, "handler_lost_on_restart");
+        return { outcome: "noop", reason: "handler_lost_on_restart" };
+      }
+
+      const untilCtx = this.buildUntilContext(record);
+
+      if (live.untilFn !== undefined) {
+        try {
+          const done = await live.untilFn(untilCtx);
+          if (done) {
+            await this.disarm(record, "until_fn");
+            return { outcome: "fired", reason: "until_fn" };
+          }
+        } catch (error) {
+          this.logger(
+            `[agent-serve] reminder "${id}" until() failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          );
+        }
+      }
+
+      if (
+        await this.isSessionBusy(record.channelId, record.continuationToken)
+      ) {
+        if (record.busyPolicy === "skipIfBusy") {
+          await this.afterFire(record, "skip");
+          this.logger(
+            `[agent-serve] reminder "${id}" (${record.purpose}) skipped: session busy`
+          );
+          return { outcome: "fired", reason: "skipped_busy" };
+        }
+        await this.whenSessionIdle(record.channelId, record.continuationToken);
+        const still = await this.store.get(id);
+        if (still === undefined || still.status !== "armed") {
+          return { outcome: "noop", reason: "disarmed_while_waiting" };
+        }
+      }
+
+      let result: ReminderFireResult;
+      if (live.run !== undefined) {
+        const fireCtx = this.buildFireContext(record);
+        result = await live.run(fireCtx);
+      } else if (record.prompt !== undefined) {
+        result = await this.deliverPrompt(record);
+      } else {
+        await this.disarm(record, "missing_handler");
+        return { outcome: "noop", reason: "missing_handler" };
+      }
+
+      // Cancel / disarm during the handler must win over reschedule.
+      const latest = await this.store.get(id);
+      if (result.action === "stop") {
+        if (latest !== undefined && latest.status === "armed") {
+          await this.disarm(latest, "run_stop");
+          this.logger(
+            `[agent-serve] reminder "${id}" (${record.purpose}) disarmed: run_stop`
+          );
+          return { outcome: "fired", reason: "run_stop" };
+        }
+        return {
+          outcome: "fired",
+          reason: latest?.disarmReason ?? "run_stop",
+        };
+      }
+      if (latest === undefined || latest.status !== "armed") {
+        return { outcome: "noop", reason: "disarmed_during_fire" };
+      }
+
+      if (result.action === "skip") {
+        await this.afterFire(latest, "skip", result.reschedule);
+        this.logger(
+          `[agent-serve] reminder "${id}" (${record.purpose}) skipped`
+        );
+        return { outcome: "fired", reason: "skipped" };
+      }
+      await this.afterFire(latest, "delivered", result.reschedule);
+      this.logger(
+        `[agent-serve] reminder "${id}" (${record.purpose}) delivered`
+      );
+      return { outcome: "fired", reason: "delivered" };
+    } finally {
+      this.firing.delete(id);
+    }
+  }
+
+  private async isSessionBusy(
+    channelId: string,
+    continuationToken: string
+  ): Promise<boolean> {
+    const existing = await this.engine.sessions.findByContinuation(
+      channelId,
+      continuationToken
+    );
+    if (existing === undefined) return false;
+    return this.engine.isTurnRunning(existing.sessionId);
+  }
+
+  private whenSessionIdle(
+    channelId: string,
+    continuationToken: string
+  ): Promise<void> {
+    const sessionKey = `${channelId}:${continuationToken}`;
+    const existing = this.idleGates.get(sessionKey);
+    if (existing !== undefined) return existing;
+
+    const gate = (async () => {
+      const session = await this.engine.sessions.findByContinuation(
+        channelId,
+        continuationToken
+      );
+      if (session === undefined) return;
+      await this.engine.waitForCompletion(session.sessionId);
+    })().finally(() => {
+      this.idleGates.delete(sessionKey);
+    });
+    this.idleGates.set(sessionKey, gate);
+    return gate;
+  }
+
+  /**
+   * Follow-ups must use the bound session's principal. If the session is gone,
+   * disarm rather than creating a fresh APP_AUTH conversation.
+   */
+  private async resolveFollowupAuth(
+    channelId: string,
+    continuationToken: string
+  ): Promise<AuthContext | null | undefined> {
+    const existing = await this.engine.sessions.findByContinuation(
+      channelId,
+      continuationToken
+    );
+    if (existing !== undefined) {
+      return existing.auth;
+    }
+    return undefined;
+  }
+
+  private async deliverPrompt(
+    record: ReminderRecord
+  ): Promise<ReminderFireResult> {
+    const auth = await this.resolveFollowupAuth(
+      record.channelId,
+      record.continuationToken
+    );
+    if (auth === undefined) {
+      await this.disarm(record, "session_gone");
+      return { action: "stop" };
+    }
+    return this.sendFollowup(record, buildFirePrompt(record), auth);
+  }
+
+  private async sendFollowup(
+    record: ReminderRecord,
+    message: string,
+    auth: AuthContext | null
+  ): Promise<ReminderFireResult> {
+    try {
+      const session = await this.engine.send(record.channelId, message, {
+        auth,
+        continuationToken: record.continuationToken,
+      });
+      this.engine.trackBackground(this.engine.waitForCompletion(session.id));
+      return { action: "delivered" };
+    } catch (error) {
+      if (error instanceof SessionBusyError) {
+        if (record.busyPolicy === "skipIfBusy") {
+          return { action: "skip" };
+        }
+        await this.whenSessionIdle(record.channelId, record.continuationToken);
+        try {
+          const session = await this.engine.send(record.channelId, message, {
+            auth,
+            continuationToken: record.continuationToken,
+          });
+          this.engine.trackBackground(
+            this.engine.waitForCompletion(session.id)
+          );
+          return { action: "delivered" };
+        } catch (retryError) {
+          this.logger(
+            `[agent-serve] reminder "${record.id}" followup failed after wait: ${
+              retryError instanceof Error
+                ? retryError.message
+                : String(retryError)
+            }`
+          );
+          return { action: "skip" };
+        }
+      }
+      throw error;
+    }
+  }
+
+  private buildFireContext(record: ReminderRecord): ReminderFireContext {
+    const self = this;
+    return {
+      id: record.id,
+      purpose: record.purpose,
+      fireCount: record.fireCount,
+      target: {
+        channelId: record.channelId,
+        continuationToken: record.continuationToken,
+        ...(record.target ?? {}),
+      },
+      host: this.engine.host,
+      mcp: this.engine.host.mcp,
+      appAuth: APP_AUTH,
+      async followup(args: { message: string }) {
+        const auth = await self.resolveFollowupAuth(
+          record.channelId,
+          record.continuationToken
+        );
+        if (auth === undefined) {
+          await self.disarm(record, "session_gone");
+          throw new Error(
+            `Reminder "${record.id}" followup: session gone for continuation`
+          );
+        }
+        const result = await self.sendFollowup(record, args.message, auth);
+        if (result.action === "skip") {
+          throw new Error(
+            `Reminder "${record.id}" followup skipped: session busy`
+          );
+        }
+        const existing = await self.engine.sessions.findByContinuation(
+          record.channelId,
+          record.continuationToken
+        );
+        if (existing === undefined) {
+          throw new Error(
+            `Reminder "${record.id}" followup: session not found for continuation`
+          );
+        }
+        const session = await self.engine.getChannelSession(
+          record.channelId,
+          existing.sessionId
+        );
+        if (session === null) {
+          throw new Error(
+            `Reminder "${record.id}" followup: channel session missing`
+          );
+        }
+        return session;
+      },
+      async cancel(reason = "handler_cancel") {
+        await self.cancel(record.id, reason);
+      },
+    };
+  }
+
+  private buildUntilContext(record: ReminderRecord): ReminderUntilContext {
+    return {
+      id: record.id,
+      purpose: record.purpose,
+      fireCount: record.fireCount,
+      target: {
+        channelId: record.channelId,
+        continuationToken: record.continuationToken,
+        ...(record.target ?? {}),
+      },
+      host: this.engine.host,
+      mcp: this.engine.host.mcp,
+    };
+  }
+
+  private async disarm(record: ReminderRecord, reason: string): Promise<void> {
+    this.clearTimer(record.id);
+    const updated: ReminderRecord = {
+      ...record,
+      status: "disarmed",
+      disarmReason: reason,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.store.save(updated);
+    this.handlers.delete(record.id);
+  }
+
+  private async afterFire(
+    record: ReminderRecord,
+    _outcome: "skip" | "delivered",
+    reschedule?: { delay?: string | number; at?: Date | string }
+  ): Promise<void> {
+    const current = await this.store.get(record.id);
+    if (current === undefined || current.status !== "armed") {
+      return;
+    }
+
+    const now = Date.now();
+    const oneShot =
+      current.scheduleKind === "delay" || current.scheduleKind === "at";
+
+    if (reschedule !== undefined) {
+      let nextFireAtMs: number;
+      if (reschedule.delay !== undefined) {
+        nextFireAtMs = now + parseDuration(reschedule.delay);
+      } else if (reschedule.at !== undefined) {
+        nextFireAtMs =
+          reschedule.at instanceof Date
+            ? reschedule.at.getTime()
+            : Date.parse(String(reschedule.at));
+        if (!Number.isFinite(nextFireAtMs)) {
+          throw new ReminderValidationError(
+            `Invalid reschedule.at for reminder "${current.id}"`
+          );
+        }
+      } else {
+        throw new ReminderValidationError(
+          `reschedule requires delay or at for reminder "${current.id}"`
+        );
+      }
+      const updated: ReminderRecord = {
+        ...current,
+        fireCount: current.fireCount + 1,
+        nextFireAtMs,
+        // Promote to one-shot-from-now semantics if they rescheduled
+        scheduleKind: reschedule.delay !== undefined ? "delay" : "at",
+        scheduleValue:
+          reschedule.delay !== undefined
+            ? String(reschedule.delay)
+            : String(reschedule.at),
+        updatedAt: new Date().toISOString(),
+      };
+      await this.store.save(updated);
+      this.armTimer(updated);
+      return;
+    }
+
+    if (oneShot) {
+      this.clearTimer(current.id);
+      const updated: ReminderRecord = {
+        ...current,
+        fireCount: current.fireCount + 1,
+        status: "completed",
+        disarmReason: "one_shot_complete",
+        updatedAt: new Date().toISOString(),
+      };
+      await this.store.save(updated);
+      this.handlers.delete(current.id);
+      return;
+    }
+
+    // Recurring
+    let nextFireAtMs: number;
+    if (current.scheduleKind === "every" && current.intervalMs !== undefined) {
+      nextFireAtMs = now + current.intervalMs;
+    } else if (current.scheduleKind === "cron") {
+      nextFireAtMs = nextCronFireMs(current.scheduleValue, now);
+    } else {
+      throw new Error(
+        `Reminder "${current.id}" has recurring status with scheduleKind=${current.scheduleKind}`
+      );
+    }
+    const updated: ReminderRecord = {
+      ...current,
+      fireCount: current.fireCount + 1,
+      nextFireAtMs,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.store.save(updated);
+    this.armTimer(updated);
+  }
+}
+
+// Re-export store record type for tests
+export type { ReminderRecord } from "./reminder-store.js";