@cursor/july 0.1.104 → 0.1.107

package/src/internal/local-control-plane.ts

@@ -3,6 +3,12 @@
  * and reminder documents + clocks, then fires into the kit the same way the
  * Cursor backend does over HTTP when `--no-control-plane` is set.
  *
+ * Reminder lifecycle (protocol v1): CP assigns id, arms timers, claims a due
+ * fire once, invokes a guest executor with an immutable descriptor, and
+ * applies the outcome with generation/fireCount CAS. Cancel/rekey racing an
+ * in-flight execution bumps generation so a stale outcome cannot resurrect
+ * the reminder. Legacy `fireReminder(id, fireCount)` remains for v1 runners.
+ *
  * v2 ingest lives here: `routeContinuation` stamps the mailbox (July twin
  * of hosted `routeVerifiedIngressContinuation`), and `attachScmEvents`
  * owns the `/v0/scm-events` long poll. v1 keeps engine-side scm-events.
@@ -17,10 +23,26 @@ import {
   routeLocalIngressContinuation,
 } from "./local-ingress.js";
 import type { PlatformTimers } from "./platform-timers.js";
+import {
+  applyOutcomeToRecord,
+  claimFromDescriptor,
+  intentToNewRecord,
+  REMINDER_CP_PROTOCOL_VERSION,
+  type ReminderControlPlane,
+  type ReminderCreateIntent,
+  type ReminderExecutionOutcome,
+  type ReminderFireClaim,
+  type ReminderGuestExecutor,
+  type ReminderOutcomeApplyResult,
+  recordGeneration,
+  toFireDescriptor,
+} from "./reminder-control-plane-protocol.js";
 import { MAX_TIMER_MS } from "./reminder-schedule.js";
 import { type ReminderRecord, ReminderStore } from "./reminder-store.js";
 
-export interface LocalControlPlane extends PlatformTimers {
+export interface LocalControlPlane
+  extends PlatformTimers,
+    ReminderControlPlane {
   /**
    * Stamp a v2 mailbox from the channel selector + live payload. Same
    * contract as hosted verified ingress. `/v1` is a no-op.
@@ -40,7 +62,16 @@ export interface LocalControlPlane extends PlatformTimers {
 
 export async function createLocalControlPlane(opts: {
   fireSchedule: (name: string) => Promise<unknown>;
-  fireReminder: (id: string, fireCount: number) => Promise<unknown>;
+  /**
+   * Legacy v1 path: CP calls this with (id, fireCount) and the runner mutates
+   * authoritative state. Prefer {@link executeReminder} for architecture v2.
+   */
+  fireReminder?: (id: string, fireCount: number) => Promise<unknown>;
+  /**
+   * Protocol guest executor. When set, due timers claim once, invoke this
+   * with an immutable descriptor, and apply the returned outcome via CAS.
+   */
+  executeReminder?: ReminderGuestExecutor;
   /**
    * Persist reminder documents under `<stateDir>/reminders`. Local serve
    * passes `<stateRoot>/control-plane`.
@@ -50,6 +81,12 @@ export async function createLocalControlPlane(opts: {
   armReminderClocks?: boolean;
   logger?: (line: string) => void;
 }): Promise<LocalControlPlane> {
+  if (opts.fireReminder === undefined && opts.executeReminder === undefined) {
+    throw new Error(
+      "createLocalControlPlane requires fireReminder and/or executeReminder"
+    );
+  }
+
   const logger = opts.logger ?? (() => {});
   const armReminderClocks = opts.armReminderClocks !== false;
   const store =
@@ -59,12 +96,22 @@ export async function createLocalControlPlane(opts: {
   const schedules = new Map<string, CronExpression>();
   const reminderTimers = new Map<string, NodeJS.Timeout>();
   const reminders = new Map<string, ReminderRecord>(
-    ((await store?.list()) ?? []).map((record) => [record.id, record])
+    ((await store?.list()) ?? []).map((record) => [
+      record.id,
+      { ...record, generation: record.generation ?? 0 },
+    ])
   );
+  /** In-flight claims keyed by reminder id (single-flight per id). */
+  const inflight = new Map<string, ReminderFireClaim>();
   let scheduleTimer: NodeJS.Timeout | undefined;
   let lastFiredMinute = -1;
   let scmRelay: { start(): void; stop(): Promise<void> } | undefined;
 
+  async function persist(record: ReminderRecord): Promise<void> {
+    reminders.set(record.id, record);
+    await store?.save(record);
+  }
+
   function armScheduleTicker(): void {
     if (scheduleTimer !== undefined || schedules.size === 0) {
       return;
@@ -115,23 +162,18 @@ export async function createLocalControlPlane(opts: {
 
   function armReminder(record: ReminderRecord): void {
     clearReminderTimer(record.id);
+    if (record.status !== "armed") {
+      return;
+    }
     const delay = Math.min(
       MAX_TIMER_MS,
       Math.max(0, record.nextFireAtMs - Date.now())
     );
     const timer = setTimeout(() => {
       reminderTimers.delete(record.id);
-      const current = reminders.get(record.id);
-      if (current === undefined || current.status !== "armed") {
-        return;
-      }
-      if (current.nextFireAtMs > Date.now() + 50) {
-        armReminder(current);
-        return;
-      }
-      void opts.fireReminder(current.id, current.fireCount).catch((error) => {
+      void onReminderDue(record.id).catch((error) => {
         logger(
-          `[agent-sdk] reminder "${current.id}" dispatch failed: ${
+          `[agent-sdk] reminder "${record.id}" dispatch failed: ${
             error instanceof Error ? error.message : String(error)
           }`
         );
@@ -141,58 +183,275 @@ export async function createLocalControlPlane(opts: {
     reminderTimers.set(record.id, timer);
   }
 
+  async function claimDue(id: string): Promise<ReminderRecord | undefined> {
+    const current = reminders.get(id);
+    if (current === undefined || current.status !== "armed") {
+      return undefined;
+    }
+    if (current.nextFireAtMs > Date.now() + 50) {
+      armReminder(current);
+      return undefined;
+    }
+    if (inflight.has(id)) {
+      return undefined;
+    }
+    const claimed: ReminderRecord = {
+      ...current,
+      status: "firing",
+      generation: recordGeneration(current),
+      updatedAt: new Date().toISOString(),
+    };
+    await persist(claimed);
+    inflight.set(id, {
+      id: claimed.id,
+      fireCount: claimed.fireCount,
+      generation: recordGeneration(claimed),
+    });
+    return claimed;
+  }
+
+  async function applyReminderOutcome(
+    claim: ReminderFireClaim,
+    outcome: ReminderExecutionOutcome
+  ): Promise<ReminderOutcomeApplyResult> {
+    const current = reminders.get(claim.id);
+    if (current === undefined) {
+      inflight.delete(claim.id);
+      return { applied: false, reason: "missing" };
+    }
+    const result = applyOutcomeToRecord(current, claim, outcome);
+    inflight.delete(claim.id);
+    if (!result.applied) {
+      if (current.status === "armed" && armReminderClocks) {
+        armReminder(current);
+      }
+      return result;
+    }
+    await persist(result.record);
+    if (armReminderClocks && result.record.status === "armed") {
+      armReminder(result.record);
+    } else {
+      clearReminderTimer(result.record.id);
+    }
+    return result;
+  }
+
+  async function onReminderDue(id: string): Promise<void> {
+    // Protocol path: claim → guest execute → CAS apply.
+    if (opts.executeReminder !== undefined) {
+      const claimed = await claimDue(id);
+      if (claimed === undefined) {
+        return;
+      }
+      const descriptor = toFireDescriptor(claimed, Date.now());
+      let outcome: ReminderExecutionOutcome;
+      try {
+        outcome = await opts.executeReminder(descriptor);
+      } catch (error) {
+        logger(
+          `[agent-sdk] reminder "${id}" guest execution failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        outcome = {
+          kind: "retry",
+          delayMs: 1_000,
+          reason: "guest_error",
+        };
+      }
+      const result = await applyReminderOutcome(
+        claimFromDescriptor(descriptor),
+        outcome
+      );
+      if (!result.applied) {
+        logger(
+          `[agent-sdk] reminder "${id}" outcome not applied: ${result.reason}`
+        );
+      }
+      return;
+    }
+
+    // Legacy v1: do not claim/firing — runner mutates via putReminder after fire.
+    const current = reminders.get(id);
+    if (current === undefined || current.status !== "armed") {
+      return;
+    }
+    if (current.nextFireAtMs > Date.now() + 50) {
+      armReminder(current);
+      return;
+    }
+    try {
+      await opts.fireReminder!(current.id, current.fireCount);
+    } catch (error) {
+      logger(
+        `[agent-sdk] reminder "${id}" dispatch failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
   return {
+    protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+
     routeContinuation: routeLocalIngressContinuation,
+
     attachScmEvents(relay) {
       scmRelay = relay;
       relay.start();
       logger("[agent-sdk] cursor-events: control-plane ingest started");
     },
+
     async upsertSchedule(input) {
       schedules.set(input.name, parseCron(input.cron));
       armScheduleTicker();
     },
+
     async deleteSchedule(name) {
       schedules.delete(name);
       if (schedules.size === 0) {
         stopScheduleTicker();
       }
     },
+
     async putReminder(record) {
-      reminders.set(record.id, record);
-      await store?.save(record);
-      if (armReminderClocks && record.status === "armed") {
-        armReminder(record);
+      const normalized: ReminderRecord = {
+        ...record,
+        generation: record.generation ?? 0,
+      };
+      await persist(normalized);
+      if (armReminderClocks && normalized.status === "armed") {
+        armReminder(normalized);
         return;
       }
-      clearReminderTimer(record.id);
+      clearReminderTimer(normalized.id);
+      if (normalized.status !== "firing") {
+        inflight.delete(normalized.id);
+      }
     },
+
     async getReminder(id) {
       return reminders.get(id);
     },
+
     async listReminders() {
       return [...reminders.values()];
     },
+
     async deleteReminder(id) {
       clearReminderTimer(id);
+      inflight.delete(id);
       reminders.delete(id);
       await store?.delete(id);
     },
-    startClocks() {
-      if (!armReminderClocks) {
-        return;
+
+    async createReminder(intent: ReminderCreateIntent) {
+      if (intent.protocolVersion !== REMINDER_CP_PROTOCOL_VERSION) {
+        throw new Error(
+          `Unsupported reminder CP protocol version ${String(intent.protocolVersion)}`
+        );
+      }
+      const record = intentToNewRecord(intent);
+      await persist(record);
+      if (armReminderClocks && record.status === "armed") {
+        armReminder(record);
+      }
+      return record;
+    },
+
+    async cancelReminder(id, reason = "explicit_cancel") {
+      const current = reminders.get(id);
+      if (current === undefined) {
+        return undefined;
+      }
+      if (
+        current.status === "completed" ||
+        current.status === "cancelled" ||
+        current.status === "disarmed"
+      ) {
+        return current;
+      }
+      clearReminderTimer(id);
+      inflight.delete(id);
+      const updated: ReminderRecord = {
+        ...current,
+        status: "cancelled",
+        disarmReason: reason,
+        generation: recordGeneration(current) + 1,
+        updatedAt: new Date().toISOString(),
+      };
+      await persist(updated);
+      return updated;
+    },
+
+    async rekeyReminders(channelId, oldToken, newToken) {
+      let n = 0;
+      for (const record of [...reminders.values()]) {
+        if (
+          record.channelId !== channelId ||
+          record.continuationToken !== oldToken
+        ) {
+          continue;
+        }
+        if (record.status !== "armed" && record.status !== "firing") {
+          continue;
+        }
+        const wasInflight = inflight.has(record.id);
+        inflight.delete(record.id);
+        let updated: ReminderRecord = {
+          ...record,
+          continuationToken: newToken,
+          status: "armed",
+          generation: recordGeneration(record) + 1,
+          updatedAt: new Date().toISOString(),
+        };
+        // Interrupted in-flight fire: retry the same fireCount soon.
+        if (wasInflight) {
+          updated = {
+            ...updated,
+            nextFireAtMs: Math.min(updated.nextFireAtMs, Date.now()),
+          };
+        }
+        await persist(updated);
+        if (armReminderClocks) {
+          armReminder(updated);
+        }
+        n += 1;
       }
+      return n;
+    },
+
+    applyReminderOutcome,
+
+    startClocks() {
       for (const record of reminders.values()) {
-        if (record.status === "armed") {
+        if (record.status === "firing") {
+          // Restart hydration: treat interrupted fires as armed for retry
+          // even when clocks are not armed (status must still recover).
+          const restored: ReminderRecord = {
+            ...record,
+            status: "armed",
+            updatedAt: new Date().toISOString(),
+          };
+          void persist(restored).then(() => {
+            if (armReminderClocks) {
+              armReminder(restored);
+            }
+          });
+          continue;
+        }
+        if (armReminderClocks && record.status === "armed") {
           armReminder(record);
         }
       }
     },
+
     stop() {
       stopScheduleTicker();
       for (const id of [...reminderTimers.keys()]) {
         clearReminderTimer(id);
       }
+      inflight.clear();
       if (scmRelay !== undefined) {
         void scmRelay.stop();
         scmRelay = undefined;