agents 0.7.1 → 0.7.3

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() {
@@ -2257,20 +2316,23 @@ var Agent = class Agent extends Server {
 	* @internal - Called by AgentWorkflow, do not call directly
 	*/
 	async _workflow_handleCallback(callback) {
+		await this.__unsafe_ensureInitialized();
 		await this.onWorkflowCallback(callback);
 	}
 	/**
 	* Broadcast a message to all connected clients via RPC.
 	* @internal - Called by AgentWorkflow, do not call directly
 	*/
-	_workflow_broadcast(message) {
+	async _workflow_broadcast(message) {
+		await this.__unsafe_ensureInitialized();
 		this.broadcast(JSON.stringify(message));
 	}
 	/**
 	* Update agent state via RPC.
 	* @internal - Called by AgentWorkflow, do not call directly
 	*/
-	_workflow_updateState(action, state) {
+	async _workflow_updateState(action, state) {
+		await this.__unsafe_ensureInitialized();
 		if (action === "set") this.setState(state);
 		else if (action === "merge") {
 			const currentState = this.state ?? {};