fix: make scheduleEvery() idempotent on callback name

scheduleEvery() now deduplicates by callback name: calling it multiple
times with the same callback returns the existing schedule instead of
creating a duplicate. If the interval or payload changed, the existing
schedule is updated in place.

This fixes the common pattern of calling scheduleEvery() inside
onStart(), which runs on every Durable Object wake. Previously each
wake created a new interval schedule, leading to duplicate executions.

keepAlive() opts out of idempotency via an internal _idempotent: false
flag so multiple concurrent keepAlive calls still get independent
schedules with independent disposers.

Closes #1049

Author: ask-bonk[bot]

.changeset/idempotent-schedule-every.md

@@ -0,0 +1,9 @@
+---
+"agents": patch
+---
+
+Make `scheduleEvery()` idempotent on callback name
+
+`scheduleEvery()` now deduplicates by callback name: calling it multiple times with the same callback returns the existing schedule instead of creating a duplicate. If the interval or payload changed, the existing schedule is updated in place.
+
+This fixes the common pattern of calling `scheduleEvery()` inside `onStart()`, which runs on every Durable Object wake. Previously each wake created a new interval schedule, leading to a thundering herd of duplicate executions.

docs/scheduling.md

@@ -172,6 +172,42 @@ await this.scheduleEvery(45, "healthCheck", {});
 await this.scheduleEvery(90, "syncData", { destination: "warehouse" });
 ```
 
+**Idempotency:**
+
+`scheduleEvery()` is idempotent on the callback name — calling it multiple times with the same callback does not create duplicate schedules. This makes it safe to call in `onStart()`, which runs on every Durable Object wake:
+
+```typescript
+class MyAgent extends Agent {
+  async onStart() {
+    // Safe: only one schedule is created, no matter how many times the DO wakes
+    await this.scheduleEvery(30, "tick");
+  }
+
+  async tick() {
+    console.log("tick", new Date().toISOString());
+  }
+}
+```
+
+If you call `scheduleEvery()` again with the same callback but a different interval or payload, the existing schedule is updated in place (rather than creating a duplicate):
+
+```typescript
+// First call creates the schedule
+await this.scheduleEvery(30, "poll");
+
+// Second call with different interval updates the existing schedule
+await this.scheduleEvery(60, "poll");
+// Only one "poll" schedule exists, now running every 60 seconds
+```
+
+Different callbacks always get their own independent schedules:
+
+```typescript
+// These create two separate schedules (different callbacks)
+await this.scheduleEvery(30, "poll");
+await this.scheduleEvery(30, "healthCheck");
+```
+
 **Key differences from cron:**
 
 | Feature             | Cron                           | Interval               |
@@ -757,6 +793,7 @@ Schedule a task to run repeatedly at a fixed interval.
 
 **Behavior:**
 
+- **Idempotent on callback name** — calling with the same callback returns the existing schedule instead of creating a duplicate. If the interval or payload changed, the existing schedule is updated in place.
 - First execution occurs after `intervalSeconds` (not immediately)
 - If callback is still running when next execution is due, it's skipped (overlap prevention)
 - If callback throws an error, the interval continues

packages/agents/src/index.ts

@@ -2174,7 +2174,23 @@ export class Agent<
   }
 
   /**
-   * Schedule a task to run repeatedly at a fixed interval
+   * Schedule a task to run repeatedly at a fixed interval.
+   *
+   * This method is **idempotent** — calling it multiple times with the same
+   * `callback`, `intervalSeconds`, and `payload` returns the existing schedule
+   * instead of creating a duplicate. If the interval or payload has changed,
+   * the existing schedule is updated in place.
+   *
+   * This makes it safe to call in `onStart()`, which runs on every Durable
+   * Object wake:
+   *
+   * ```ts
+   * async onStart() {
+   *   // Only one schedule is created, no matter how many times the DO wakes
+   *   await this.scheduleEvery(30, "tick");
+   * }
+   * ```
+   *
    * @template T Type of the payload data
    * @param intervalSeconds Number of seconds between executions
    * @param callback Name of the method to call
@@ -2187,7 +2203,7 @@ export class Agent<
     intervalSeconds: number,
     callback: keyof this,
     payload?: T,
-    options?: { retry?: RetryOptions }
+    options?: { retry?: RetryOptions; _idempotent?: boolean }
   ): Promise<Schedule<T>> {
     // DO alarms have a max schedule time of 30 days
     const MAX_INTERVAL_SECONDS = 30 * 24 * 60 * 60; // 30 days in seconds
@@ -2214,6 +2230,80 @@ export class Agent<
       validateRetryOptions(options.retry, this._resolvedOptions.retry);
     }
 
+    const idempotent = options?._idempotent !== false;
+    const payloadJson = JSON.stringify(payload);
+
+    // Idempotency: check for an existing interval schedule with the same callback
+    if (idempotent) {
+      const existing = this.sql<{
+        id: string;
+        callback: string;
+        payload: string;
+        type: string;
+        time: number;
+        intervalSeconds: number;
+        retry_options: string | null;
+      }>`
+        SELECT * FROM cf_agents_schedules
+        WHERE type = 'interval' AND callback = ${callback}
+        LIMIT 1
+      `;
+
+      if (existing.length > 0) {
+        const row = existing[0];
+        const retryJson = options?.retry ? JSON.stringify(options.retry) : null;
+
+        // If interval or payload changed, update in place
+        if (
+          row.intervalSeconds !== intervalSeconds ||
+          row.payload !== payloadJson
+        ) {
+          const newTime = Math.floor(
+            (Date.now() + intervalSeconds * 1000) / 1000
+          );
+          this.sql`
+            UPDATE cf_agents_schedules
+            SET intervalSeconds = ${intervalSeconds},
+                payload = ${payloadJson},
+                time = ${newTime},
+                running = 0,
+                retry_options = ${retryJson}
+            WHERE id = ${row.id}
+          `;
+
+          await this._scheduleNextAlarm();
+
+          const schedule: Schedule<T> = {
+            callback: callback as string,
+            id: row.id,
+            intervalSeconds,
+            payload: payload as T,
+            retry: options?.retry,
+            time: newTime,
+            type: "interval"
+          };
+
+          this._emit("schedule:create", {
+            callback: callback as string,
+            id: row.id
+          });
+
+          return schedule;
+        }
+
+        // Exact match — return existing schedule as-is (no-op)
+        return {
+          callback: row.callback,
+          id: row.id,
+          intervalSeconds: row.intervalSeconds,
+          payload: JSON.parse(row.payload) as T,
+          retry: parseRetryOptions(row as unknown as Record<string, unknown>),
+          time: row.time,
+          type: "interval"
+        };
+      }
+    }
+
     const id = nanoid(9);
     const time = new Date(Date.now() + intervalSeconds * 1000);
     const timestamp = Math.floor(time.getTime() / 1000);
@@ -2222,7 +2312,7 @@ export class Agent<
 
     this.sql`
       INSERT OR REPLACE INTO cf_agents_schedules (id, callback, payload, type, intervalSeconds, time, running, retry_options)
-      VALUES (${id}, ${callback}, ${JSON.stringify(payload)}, 'interval', ${intervalSeconds}, ${timestamp}, 0, ${retryJson})
+      VALUES (${id}, ${callback}, ${payloadJson}, 'interval', ${intervalSeconds}, ${timestamp}, 0, ${retryJson})
     `;
 
     await this._scheduleNextAlarm();
@@ -2357,7 +2447,9 @@ export class Agent<
     const heartbeatSeconds = Math.ceil(KEEP_ALIVE_INTERVAL_MS / 1000);
     const schedule = await this.scheduleEvery(
       heartbeatSeconds,
-      "_cf_keepAliveHeartbeat" as keyof this
+      "_cf_keepAliveHeartbeat" as keyof this,
+      undefined,
+      { _idempotent: false }
     );
 
     let disposed = false;

packages/agents/src/tests/agents/schedule.ts

@@ -222,4 +222,52 @@ export class TestScheduleAgent extends Agent<Record<string, unknown>> {
 
     return schedule.id;
   }
+
+  // --- Idempotency test helpers ---
+
+  // A second callback for testing that idempotency is per-callback
+  secondIntervalCallback() {
+    // Intentionally empty
+  }
+
+  @callable()
+  async createIntervalScheduleWithPayload(
+    intervalSeconds: number,
+    payload: string
+  ): Promise<string> {
+    const schedule = await this.scheduleEvery(
+      intervalSeconds,
+      "intervalCallback",
+      payload
+    );
+    return schedule.id;
+  }
+
+  @callable()
+  async createSecondIntervalSchedule(intervalSeconds: number): Promise<string> {
+    const schedule = await this.scheduleEvery(
+      intervalSeconds,
+      "secondIntervalCallback"
+    );
+    return schedule.id;
+  }
+
+  @callable()
+  async countIntervalSchedules(): Promise<number> {
+    const result = this.sql<{ count: number }>`
+      SELECT COUNT(*) as count FROM cf_agents_schedules WHERE type = 'interval'
+    `;
+    return result[0].count;
+  }
+
+  @callable()
+  async countIntervalSchedulesForCallback(
+    callbackName: string
+  ): Promise<number> {
+    const result = this.sql<{ count: number }>`
+      SELECT COUNT(*) as count FROM cf_agents_schedules
+      WHERE type = 'interval' AND callback = ${callbackName}
+    `;
+    return result[0].count;
+  }
 }