agents 0.7.0 → 0.7.2

package/dist/{agent-DnmmRjyv.d.ts → agent-eZnMHidZ.d.ts}

@@ -7,6 +7,17 @@ type BaseEvent<
   Payload extends Record<string, unknown> = Record<string, never>
 > = {
   type: T;
+  /**
+   * The class name of the agent that emitted this event
+   * (e.g. "MyChatAgent").
+   * Always present on events emitted by an Agent instance.
+   */
+  agent?: string;
+  /**
+   * The instance name (Durable Object ID name) of the agent.
+   * Always present on events emitted by an Agent instance.
+   */
+  name?: string;
   /**
    * The payload of the event
    */
@@ -145,6 +156,13 @@ type AgentObservabilityEvent =
         attempts: number;
       }
     >
+  | BaseEvent<
+      "queue:create",
+      {
+        callback: string;
+        id: string;
+      }
+    >
   | BaseEvent<
       "queue:retry",
       {
@@ -170,6 +188,30 @@ type AgentObservabilityEvent =
         connectionId: string;
       }
     >
+  | BaseEvent<
+      "disconnect",
+      {
+        connectionId: string;
+        code: number;
+        reason: string;
+      }
+    >
+  | BaseEvent<
+      "email:receive",
+      {
+        from: string;
+        to: string;
+        subject?: string;
+      }
+    >
+  | BaseEvent<
+      "email:reply",
+      {
+        from: string;
+        to: string;
+        subject?: string;
+      }
+    >
   | BaseEvent<
       "workflow:start",
       {
@@ -228,4 +270,4 @@ type AgentObservabilityEvent =
     >;
 //#endregion
 export { MCPObservabilityEvent as n, AgentObservabilityEvent as t };
-//# sourceMappingURL=agent-DnmmRjyv.d.ts.map
+//# sourceMappingURL=agent-eZnMHidZ.d.ts.map

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

@@ -1,4 +1,4 @@
-import { n as MCPObservabilityEvent } from "./agent-DnmmRjyv.js";
+import { n as MCPObservabilityEvent } from "./agent-eZnMHidZ.js";
 import { AgentMcpOAuthProvider } from "./mcp/do-oauth-client-provider.js";
 import { McpAgent } from "./mcp/index.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -601,4 +601,4 @@ export {
   MaybePromise as x,
   StreamableHTTPEdgeClientTransport as y
 };
-//# sourceMappingURL=client-storage-tusTuoSF.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-tusTuoSF.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-tusTuoSF.js";
+} from "./client-storage-BPjfP_is.js";
 import {
   AgentMcpOAuthProvider,
   AgentsOAuthProvider,
@@ -23,7 +23,7 @@ import {
   WorkflowPage,
   WorkflowQueryCriteria
 } from "./workflow-types.js";
-import { Observability } from "./observability/index.js";
+import { Observability, ObservabilityEvent } from "./observability/index.js";
 import { MessageType } from "./types.js";
 import {
   Connection,
@@ -325,7 +325,10 @@ declare class Agent<
    * Emit an observability event with auto-generated timestamp.
    * @internal
    */
-  private _emit;
+  protected _emit(
+    type: ObservabilityEvent["type"],
+    payload?: Record<string, unknown>
+  ): void;
   /**
    * Execute SQL queries against the Agent's database
    * @template T Type of the returned rows
@@ -593,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
@@ -608,6 +627,7 @@ declare class Agent<
     payload?: T,
     options?: {
       retry?: RetryOptions;
+      _idempotent?: boolean;
     }
   ): Promise<Schedule<T>>;
   /**
@@ -685,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

@@ -260,6 +260,8 @@ var Agent = class Agent extends Server {
 	_emit(type, payload = {}) {
 		this.observability?.emit({
 			type,
+			agent: this._ParentClass.name,
+			name: this.name,
 			payload,
 			timestamp: Date.now()
 		});
@@ -291,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);
@@ -457,7 +380,11 @@ var Agent = class Agent extends Server {
 			this.broadcastMcpServers();
 		}));
 		this._disposables.add(this.mcp.onObservabilityEvent((event) => {
-			this.observability?.emit(event);
+			this.observability?.emit({
+				...event,
+				agent: this._ParentClass.name,
+				name: this.name
+			});
 		}));
 		{
 			const proto = Object.getPrototypeOf(this);
@@ -620,6 +547,22 @@ var Agent = class Agent extends Server {
 				return this._tryCatch(() => _onConnect(connection, ctx));
 			});
 		};
+		const _onClose = this.onClose.bind(this);
+		this.onClose = (connection, code, reason, wasClean) => {
+			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
+				agent: this,
+				connection,
+				request: void 0,
+				email: void 0
+			}, () => {
+				this._emit("disconnect", {
+					connectionId: connection.id,
+					code,
+					reason
+				});
+				return _onClose(connection, code, reason, wasClean);
+			});
+		};
 		const _onStart = this.onStart.bind(this);
 		this.onStart = async (props) => {
 			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
@@ -917,6 +860,11 @@ var Agent = class Agent extends Server {
 			request: void 0,
 			email
 		}, async () => {
+			this._emit("email:receive", {
+				from: email.from,
+				to: email.to,
+				subject: email.headers.get("subject") ?? void 0
+			});
 			if ("onEmail" in this && typeof this.onEmail === "function") return this._tryCatch(() => this.onEmail(email));
 			else {
 				console.log("Received email from:", email.from, "to:", email.to);
@@ -967,6 +915,12 @@ var Agent = class Agent extends Server {
 				raw: msg.asRaw(),
 				to: email.from
 			});
+			const rawSubject = email.headers.get("subject");
+			this._emit("email:reply", {
+				from: email.to,
+				to: email.from,
+				subject: options.subject ?? (rawSubject ? `Re: ${rawSubject}` : void 0)
+			});
 		});
 	}
 	async _tryCatch(fn) {
@@ -1065,6 +1019,10 @@ var Agent = class Agent extends Server {
       INSERT OR REPLACE INTO cf_agents_queues (id, payload, callback, retry_options)
       VALUES (${id}, ${JSON.stringify(payload)}, ${callback}, ${retryJson})
     `;
+		this._emit("queue:create", {
+			callback,
+			id
+		});
 		this._flushQueue().catch((e) => {
 			console.error("Error flushing queue:", e);
 		});
@@ -1263,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
@@ -1279,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 = {
@@ -1388,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;
@@ -1443,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() {