agents 0.7.1 → 0.7.2

package/dist/{client-storage-yDVwzgfF.d.ts → client-storage-BPjfP_is.d.ts}

@@ -554,7 +554,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): RPCClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
+  ): StreamableHTTPClientTransport | SSEClientTransport | RPCClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -601,4 +601,4 @@ export {
   MaybePromise as x,
   StreamableHTTPEdgeClientTransport as y
 };
-//# sourceMappingURL=client-storage-yDVwzgfF.d.ts.map
+//# sourceMappingURL=client-storage-BPjfP_is.d.ts.map

package/dist/experimental/forever.d.ts

@@ -1,5 +1,5 @@
 import { RetryOptions } from "../retries.js";
-import "../client-storage-yDVwzgfF.js";
+import "../client-storage-BPjfP_is.js";
 import { Agent, Schedule } from "../index.js";
 
 //#region src/experimental/forever.d.ts
@@ -92,12 +92,13 @@ declare function withFibers<TBase extends AgentLike>(Base: TBase, options?: {
     _checkInterruptedFibers(): Promise<void>; /** @internal */
     _cleanupOrphanedHeartbeats(): void; /** @internal */
     _maybeCleanupFibers(): void;
-    readonly alarm: () => Promise<void>;
     sql: <T = Record<string, string | number | boolean | null>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]) => T[];
     scheduleEvery: <T = string>(intervalSeconds: number, callback: keyof Agent<Cloudflare.Env, unknown, Record<string, unknown>>, payload?: T | undefined, options?: {
       retry?: RetryOptions;
+      _idempotent?: boolean;
     }) => Promise<Schedule<T>>;
     cancelSchedule: (id: string) => Promise<boolean>;
+    alarm: () => Promise<void>;
     keepAlive: () => Promise<() => void>;
     keepAliveWhile: <T>(fn: () => Promise<T>) => Promise<T>;
   };

package/dist/index.d.ts

@@ -7,7 +7,7 @@ import { RetryOptions } from "./retries.js";
 import {
   r as MCPConnectionState,
   w as TransportType
-} from "./client-storage-yDVwzgfF.js";
+} from "./client-storage-BPjfP_is.js";
 import {
   AgentMcpOAuthProvider,
   AgentsOAuthProvider,
@@ -596,7 +596,23 @@ declare class Agent<
     }
   ): Promise<Schedule<T>>;
   /**
-   * 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. A different interval or payload is
+   * treated as a distinct schedule and creates a new row.
+   *
+   * 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
@@ -611,6 +627,7 @@ declare class Agent<
     payload?: T,
     options?: {
       retry?: RetryOptions;
+      _idempotent?: boolean;
     }
   ): Promise<Schedule<T>>;
   /**
@@ -688,15 +705,25 @@ declare class Agent<
    */
   _cf_keepAliveHeartbeat(): Promise<void>;
   private _scheduleNextAlarm;
+  /**
+   * Override PartyServer's onAlarm hook as a no-op.
+   * Agent handles alarm logic directly in the alarm() method override,
+   * but super.alarm() calls onAlarm() after #ensureInitialized(),
+   * so we suppress the default "Implement onAlarm" warning.
+   */
+  onAlarm(): void;
   /**
    * Method called when an alarm fires.
    * Executes any scheduled tasks that are due.
    *
+   * Calls super.alarm() first to ensure PartyServer's #ensureInitialized()
+   * runs, which hydrates this.name from storage and calls onStart() if needed.
+   *
    * @remarks
    * To schedule a task, please use the `this.schedule` method instead.
    * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
    */
-  readonly alarm: () => Promise<void>;
+  alarm(): Promise<void>;
   /**
    * Destroy the Agent, removing all state and scheduled tasks
    */

package/dist/index.js

@@ -293,85 +293,6 @@ var Agent = class Agent extends Server {
 		this.initialState = DEFAULT_STATE;
 		this.observability = genericObservability;
 		this._flushingQueue = false;
-		this.alarm = async () => {
-			const now = Math.floor(Date.now() / 1e3);
-			const result = this.sql`
-      SELECT * FROM cf_agents_schedules WHERE time <= ${now}
-    `;
-			if (result && Array.isArray(result)) for (const row of result) {
-				const callback = this[row.callback];
-				if (!callback) {
-					console.error(`callback ${row.callback} not found`);
-					continue;
-				}
-				if (row.type === "interval" && row.running === 1) {
-					const executionStartedAt = row.execution_started_at ?? 0;
-					const hungTimeoutSeconds = this._resolvedOptions.hungScheduleTimeoutSeconds;
-					const elapsedSeconds = now - executionStartedAt;
-					if (elapsedSeconds < hungTimeoutSeconds) {
-						console.warn(`Skipping interval schedule ${row.id}: previous execution still running`);
-						continue;
-					}
-					console.warn(`Forcing reset of hung interval schedule ${row.id} (started ${elapsedSeconds}s ago)`);
-				}
-				if (row.type === "interval") this.sql`UPDATE cf_agents_schedules SET running = 1, execution_started_at = ${now} WHERE id = ${row.id}`;
-				await __DO_NOT_USE_WILL_BREAK__agentContext.run({
-					agent: this,
-					connection: void 0,
-					request: void 0,
-					email: void 0
-				}, async () => {
-					const { maxAttempts, baseDelayMs, maxDelayMs } = resolveRetryConfig(parseRetryOptions(row), this._resolvedOptions.retry);
-					const parsedPayload = JSON.parse(row.payload);
-					try {
-						this._emit("schedule:execute", {
-							callback: row.callback,
-							id: row.id
-						});
-						await tryN(maxAttempts, async (attempt) => {
-							if (attempt > 1) this._emit("schedule:retry", {
-								callback: row.callback,
-								id: row.id,
-								attempt,
-								maxAttempts
-							});
-							await callback.bind(this)(parsedPayload, row);
-						}, {
-							baseDelayMs,
-							maxDelayMs
-						});
-					} catch (e) {
-						console.error(`error executing callback "${row.callback}" after ${maxAttempts} attempts`, e);
-						this._emit("schedule:error", {
-							callback: row.callback,
-							id: row.id,
-							error: e instanceof Error ? e.message : String(e),
-							attempts: maxAttempts
-						});
-						try {
-							await this.onError(e);
-						} catch {}
-					}
-				});
-				if (this._destroyed) return;
-				if (row.type === "cron") {
-					const nextExecutionTime = getNextCronTime(row.cron);
-					const nextTimestamp = Math.floor(nextExecutionTime.getTime() / 1e3);
-					this.sql`
-            UPDATE cf_agents_schedules SET time = ${nextTimestamp} WHERE id = ${row.id}
-          `;
-				} else if (row.type === "interval") {
-					const nextTimestamp = Math.floor(Date.now() / 1e3) + (row.intervalSeconds ?? 0);
-					this.sql`
-            UPDATE cf_agents_schedules SET running = 0, time = ${nextTimestamp} WHERE id = ${row.id}
-          `;
-				} else this.sql`
-            DELETE FROM cf_agents_schedules WHERE id = ${row.id}
-          `;
-			}
-			if (this._destroyed) return;
-			await this._scheduleNextAlarm();
-		};
 		if (!wrappedClasses.has(this.constructor)) {
 			this._autoWrapCustomMethods();
 			wrappedClasses.add(this.constructor);
@@ -1300,7 +1221,23 @@ var Agent = class Agent extends Server {
 		throw new Error(`Invalid schedule type: ${JSON.stringify(when)}(${typeof when}) trying to schedule ${callback}`);
 	}
 	/**
-	* 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. A different interval or payload is
+	* treated as a distinct schedule and creates a new row.
+	*
+	* 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
@@ -1316,13 +1253,37 @@ var Agent = class Agent extends Server {
 		if (typeof callback !== "string") throw new Error("Callback must be a string");
 		if (typeof this[callback] !== "function") throw new Error(`this.${callback} is not a function`);
 		if (options?.retry) validateRetryOptions(options.retry, this._resolvedOptions.retry);
+		const idempotent = options?._idempotent !== false;
+		const payloadJson = JSON.stringify(payload);
+		if (idempotent) {
+			const existing = this.sql`
+        SELECT * FROM cf_agents_schedules
+        WHERE type = 'interval'
+          AND callback = ${callback}
+          AND intervalSeconds = ${intervalSeconds}
+          AND payload IS ${payloadJson}
+        LIMIT 1
+      `;
+			if (existing.length > 0) {
+				const row = existing[0];
+				return {
+					callback: row.callback,
+					id: row.id,
+					intervalSeconds: row.intervalSeconds,
+					payload: JSON.parse(row.payload),
+					retry: parseRetryOptions(row),
+					time: row.time,
+					type: "interval"
+				};
+			}
+		}
 		const id = nanoid(9);
 		const time = new Date(Date.now() + intervalSeconds * 1e3);
 		const timestamp = Math.floor(time.getTime() / 1e3);
 		const retryJson = options?.retry ? JSON.stringify(options.retry) : null;
 		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();
 		const schedule = {
@@ -1425,7 +1386,7 @@ var Agent = class Agent extends Server {
 	*/
 	async keepAlive() {
 		const heartbeatSeconds = Math.ceil(KEEP_ALIVE_INTERVAL_MS / 1e3);
-		const schedule = await this.scheduleEvery(heartbeatSeconds, "_cf_keepAliveHeartbeat");
+		const schedule = await this.scheduleEvery(heartbeatSeconds, "_cf_keepAliveHeartbeat", void 0, { _idempotent: false });
 		let disposed = false;
 		return () => {
 			if (disposed) return;
@@ -1480,6 +1441,104 @@ var Agent = class Agent extends Server {
 		}
 	}
 	/**
+	* Override PartyServer's onAlarm hook as a no-op.
+	* Agent handles alarm logic directly in the alarm() method override,
+	* but super.alarm() calls onAlarm() after #ensureInitialized(),
+	* so we suppress the default "Implement onAlarm" warning.
+	*/
+	onAlarm() {}
+	/**
+	* Method called when an alarm fires.
+	* Executes any scheduled tasks that are due.
+	*
+	* Calls super.alarm() first to ensure PartyServer's #ensureInitialized()
+	* runs, which hydrates this.name from storage and calls onStart() if needed.
+	*
+	* @remarks
+	* To schedule a task, please use the `this.schedule` method instead.
+	* See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
+	*/
+	async alarm() {
+		await super.alarm();
+		const now = Math.floor(Date.now() / 1e3);
+		const result = this.sql`
+      SELECT * FROM cf_agents_schedules WHERE time <= ${now}
+    `;
+		if (result && Array.isArray(result)) for (const row of result) {
+			const callback = this[row.callback];
+			if (!callback) {
+				console.error(`callback ${row.callback} not found`);
+				continue;
+			}
+			if (row.type === "interval" && row.running === 1) {
+				const executionStartedAt = row.execution_started_at ?? 0;
+				const hungTimeoutSeconds = this._resolvedOptions.hungScheduleTimeoutSeconds;
+				const elapsedSeconds = now - executionStartedAt;
+				if (elapsedSeconds < hungTimeoutSeconds) {
+					console.warn(`Skipping interval schedule ${row.id}: previous execution still running`);
+					continue;
+				}
+				console.warn(`Forcing reset of hung interval schedule ${row.id} (started ${elapsedSeconds}s ago)`);
+			}
+			if (row.type === "interval") this.sql`UPDATE cf_agents_schedules SET running = 1, execution_started_at = ${now} WHERE id = ${row.id}`;
+			await __DO_NOT_USE_WILL_BREAK__agentContext.run({
+				agent: this,
+				connection: void 0,
+				request: void 0,
+				email: void 0
+			}, async () => {
+				const { maxAttempts, baseDelayMs, maxDelayMs } = resolveRetryConfig(parseRetryOptions(row), this._resolvedOptions.retry);
+				const parsedPayload = JSON.parse(row.payload);
+				try {
+					this._emit("schedule:execute", {
+						callback: row.callback,
+						id: row.id
+					});
+					await tryN(maxAttempts, async (attempt) => {
+						if (attempt > 1) this._emit("schedule:retry", {
+							callback: row.callback,
+							id: row.id,
+							attempt,
+							maxAttempts
+						});
+						await callback.bind(this)(parsedPayload, row);
+					}, {
+						baseDelayMs,
+						maxDelayMs
+					});
+				} catch (e) {
+					console.error(`error executing callback "${row.callback}" after ${maxAttempts} attempts`, e);
+					this._emit("schedule:error", {
+						callback: row.callback,
+						id: row.id,
+						error: e instanceof Error ? e.message : String(e),
+						attempts: maxAttempts
+					});
+					try {
+						await this.onError(e);
+					} catch {}
+				}
+			});
+			if (this._destroyed) return;
+			if (row.type === "cron") {
+				const nextExecutionTime = getNextCronTime(row.cron);
+				const nextTimestamp = Math.floor(nextExecutionTime.getTime() / 1e3);
+				this.sql`
+            UPDATE cf_agents_schedules SET time = ${nextTimestamp} WHERE id = ${row.id}
+          `;
+			} else if (row.type === "interval") {
+				const nextTimestamp = Math.floor(Date.now() / 1e3) + (row.intervalSeconds ?? 0);
+				this.sql`
+            UPDATE cf_agents_schedules SET running = 0, time = ${nextTimestamp} WHERE id = ${row.id}
+          `;
+			} else this.sql`
+            DELETE FROM cf_agents_schedules WHERE id = ${row.id}
+          `;
+		}
+		if (this._destroyed) return;
+		await this._scheduleNextAlarm();
+	}
+	/**
 	* Destroy the Agent, removing all state and scheduled tasks
 	*/
 	async destroy() {