agents 0.10.2 → 0.11.0

package/dist/index.js

@@ -1,6 +1,3192 @@
 import { MessageType } from "./types.js";
-import { createHeaderBasedEmailResolver } from "./email.js";
+import { camelCaseToKebabCase } from "./utils.js";
+import { createHeaderBasedEmailResolver, signAgentHeaders } from "./email.js";
 import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
-import { a as callable, c as routeAgentEmail, i as StreamingResponse, l as routeAgentRequest, n as DEFAULT_AGENT_STATIC_OPTIONS, o as getAgentByName, r as SqlError, s as getCurrentAgent, t as Agent, u as unstable_callable } from "./src-f7-4oW_C.js";
+import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-BVdP0e3Z.js";
+import { isErrorRetryable, tryN, validateRetryOptions } from "./retries.js";
+import { o as RPC_DO_PREFIX, r as MCPConnectionState, s as DisposableStore, t as MCPClientManager } from "./client-QBjFV5de.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider.js";
+import { genericObservability } from "./observability/index.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { parseCronExpression } from "cron-schedule";
+import { nanoid } from "nanoid";
+import { EmailMessage } from "cloudflare:email";
+import { RpcTarget } from "cloudflare:workers";
+import { Server, getServerByName, routePartykitRequest } from "partyserver";
+//#region src/index.ts
+let _Symbol$dispose;
+/**
+* Type guard for RPC request messages
+*/
+function isRPCRequest(msg) {
+	return typeof msg === "object" && msg !== null && "type" in msg && msg.type === MessageType.RPC && "id" in msg && typeof msg.id === "string" && "method" in msg && typeof msg.method === "string" && "args" in msg && Array.isArray(msg.args);
+}
+/**
+* Type guard for state update messages
+*/
+function isStateUpdateMessage(msg) {
+	return typeof msg === "object" && msg !== null && "type" in msg && msg.type === MessageType.CF_AGENT_STATE && "state" in msg;
+}
+const callableMetadata = /* @__PURE__ */ new WeakMap();
+/**
+* Error class for SQL execution failures, containing the query that failed
+*/
+var SqlError = class extends Error {
+	constructor(query, cause) {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		super(`SQL query failed: ${message}`, { cause });
+		this.name = "SqlError";
+		this.query = query;
+	}
+};
+/**
+* Decorator that marks a method as callable by clients
+* @param metadata Optional metadata about the callable method
+*/
+function callable(metadata = {}) {
+	return function callableDecorator(target, _context) {
+		if (!callableMetadata.has(target)) callableMetadata.set(target, metadata);
+		return target;
+	};
+}
+let didWarnAboutUnstableCallable = false;
+/**
+* Decorator that marks a method as callable by clients
+* @deprecated this has been renamed to callable, and unstable_callable will be removed in the next major version
+* @param metadata Optional metadata about the callable method
+*/
+const unstable_callable = (metadata = {}) => {
+	if (!didWarnAboutUnstableCallable) {
+		didWarnAboutUnstableCallable = true;
+		console.warn("unstable_callable is deprecated, use callable instead. unstable_callable will be removed in the next major version.");
+	}
+	return callable(metadata);
+};
+const _fiberALS = new AsyncLocalStorage();
+function getNextCronTime(cron) {
+	return parseCronExpression(cron).getNextDate();
+}
+const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 3e4;
+/**
+* Schema version for the Agent's internal SQLite tables.
+* Bump this when adding new tables, columns, or migrations.
+* The constructor stores this as a row in cf_agents_state and checks it
+* on wake to skip DDL on established DOs.
+*/
+const CURRENT_SCHEMA_VERSION = 3;
+const SCHEMA_VERSION_ROW_ID = "cf_schema_version";
+const STATE_ROW_ID = "cf_state_row_id";
+const STATE_WAS_CHANGED = "cf_state_was_changed";
+const DEFAULT_STATE = {};
+/**
+* Internal key used to store the readonly flag in connection state.
+* Prefixed with _cf_ to avoid collision with user state keys.
+*/
+const CF_READONLY_KEY = "_cf_readonly";
+/**
+* Internal key used to store the no-protocol flag in connection state.
+* When set, protocol messages (identity, state sync, MCP servers) are not
+* sent to this connection — neither on connect nor via broadcasts.
+*/
+const CF_NO_PROTOCOL_KEY = "_cf_no_protocol";
+/**
+* The set of all internal keys stored in connection state that must be
+* hidden from user code and preserved across setState calls.
+*/
+const CF_INTERNAL_KEYS = new Set([
+	CF_READONLY_KEY,
+	CF_NO_PROTOCOL_KEY,
+	"_cf_voiceInCall"
+]);
+/** Check if a raw connection state object contains any internal keys. */
+function rawHasInternalKeys(raw) {
+	for (const key of Object.keys(raw)) if (CF_INTERNAL_KEYS.has(key)) return true;
+	return false;
+}
+/** Return a copy of `raw` with all internal keys removed, or null if no user keys remain. */
+function stripInternalKeys(raw) {
+	const result = {};
+	let hasUserKeys = false;
+	for (const key of Object.keys(raw)) if (!CF_INTERNAL_KEYS.has(key)) {
+		result[key] = raw[key];
+		hasUserKeys = true;
+	}
+	return hasUserKeys ? result : null;
+}
+/** Return a copy containing only the internal keys present in `raw`. */
+function extractInternalFlags(raw) {
+	const result = {};
+	for (const key of Object.keys(raw)) if (CF_INTERNAL_KEYS.has(key)) result[key] = raw[key];
+	return result;
+}
+/** Max length for error strings broadcast to clients. */
+const MAX_ERROR_STRING_LENGTH = 500;
+/**
+* Sanitize an error string before broadcasting to clients.
+* MCP error strings may contain untrusted content from external OAuth
+* providers — truncate and strip control characters to limit XSS risk.
+*/
+const CONTROL_CHAR_RE = /* @__PURE__ */ new RegExp("[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F]", "g");
+function sanitizeErrorString(error) {
+	if (error === null) return null;
+	let sanitized = error.replace(CONTROL_CHAR_RE, "");
+	if (sanitized.length > MAX_ERROR_STRING_LENGTH) sanitized = sanitized.substring(0, MAX_ERROR_STRING_LENGTH) + "...";
+	return sanitized;
+}
+/**
+* Tracks which agent constructors have already emitted the onStateUpdate
+* deprecation warning, so it fires at most once per class.
+*/
+const _onStateUpdateWarnedClasses = /* @__PURE__ */ new WeakSet();
+/**
+* Tracks which agent constructors have already emitted the
+* sendIdentityOnConnect deprecation warning, so it fires at most once per class.
+*/
+const _sendIdentityWarnedClasses = /* @__PURE__ */ new WeakSet();
+/**
+* Default options for Agent configuration.
+* Child classes can override specific options without spreading.
+*/
+const DEFAULT_AGENT_STATIC_OPTIONS = {
+	hibernate: true,
+	sendIdentityOnConnect: true,
+	hungScheduleTimeoutSeconds: 30,
+	keepAliveIntervalMs: DEFAULT_KEEP_ALIVE_INTERVAL_MS,
+	retry: {
+		maxAttempts: 3,
+		baseDelayMs: 100,
+		maxDelayMs: 3e3
+	}
+};
+/**
+* Parse the raw `retry_options` TEXT column from a SQLite row into a
+* typed `RetryOptions` object, or `undefined` if not set.
+*/
+function parseRetryOptions(row) {
+	const raw = row.retry_options;
+	if (typeof raw !== "string") return void 0;
+	return JSON.parse(raw);
+}
+/**
+* Resolve per-task retry options against class-level defaults and call
+* `tryN`. This is the shared retry-execution path used by both queue
+* flush and schedule alarm handlers.
+*/
+function resolveRetryConfig(taskRetry, defaults) {
+	return {
+		maxAttempts: taskRetry?.maxAttempts ?? defaults.maxAttempts,
+		baseDelayMs: taskRetry?.baseDelayMs ?? defaults.baseDelayMs,
+		maxDelayMs: taskRetry?.maxDelayMs ?? defaults.maxDelayMs
+	};
+}
+function getCurrentAgent() {
+	const store = __DO_NOT_USE_WILL_BREAK__agentContext.getStore();
+	if (!store) return {
+		agent: void 0,
+		connection: void 0,
+		request: void 0,
+		email: void 0
+	};
+	return store;
+}
+/**
+* Wraps a method to run within the agent context, ensuring getCurrentAgent() works properly
+* @param agent The agent instance
+* @param method The method to wrap
+* @returns A wrapped method that runs within the agent context
+*/
+function withAgentContext(method) {
+	return function(...args) {
+		const { connection, request, email, agent } = getCurrentAgent();
+		if (agent === this) return method.apply(this, args);
+		return __DO_NOT_USE_WILL_BREAK__agentContext.run({
+			agent: this,
+			connection,
+			request,
+			email
+		}, () => {
+			return method.apply(this, args);
+		});
+	};
+}
+/**
+* Base class for creating Agent implementations
+* @template Env Environment type containing bindings
+* @template State State type to store within the Agent
+*/
+var Agent = class Agent extends Server {
+	/**
+	* Stable key for Workers AI session affinity (prefix-cache optimization).
+	*
+	* Uses the Durable Object ID, which is globally unique across all agent
+	* classes and stable for the lifetime of the instance. Pass this value as
+	* the `sessionAffinity` option when creating a Workers AI model so that
+	* requests from the same agent instance are routed to the same backend
+	* replica, improving KV-prefix-cache hit rates across conversation turns.
+	*
+	* @example
+	* ```typescript
+	* const workersai = createWorkersAI({ binding: this.env.AI });
+	* const model = workersai("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
+	*   sessionAffinity: this.sessionAffinity,
+	* });
+	* ```
+	*/
+	get sessionAffinity() {
+		return this.ctx.id.toString();
+	}
+	/**
+	* Current state of the Agent
+	*/
+	get state() {
+		if (this._state !== DEFAULT_STATE) return this._state;
+		const result = this.sql`
+      SELECT state FROM cf_agents_state WHERE id = ${STATE_ROW_ID}
+    `;
+		if (result.length > 0) {
+			const state = result[0].state;
+			try {
+				this._state = JSON.parse(state);
+			} catch (e) {
+				console.error("Failed to parse stored state, falling back to initialState:", e);
+				if (this.initialState !== DEFAULT_STATE) {
+					this._state = this.initialState;
+					this._setStateInternal(this.initialState);
+				} else {
+					this.sql`DELETE FROM cf_agents_state WHERE id = ${STATE_ROW_ID}`;
+					return;
+				}
+			}
+			return this._state;
+		}
+		if (this.initialState === DEFAULT_STATE) return;
+		this._setStateInternal(this.initialState);
+		return this.initialState;
+	}
+	get _resolvedOptions() {
+		if (this._cachedOptions) return this._cachedOptions;
+		const ctor = this.constructor;
+		const userRetry = ctor.options?.retry;
+		this._cachedOptions = {
+			hibernate: ctor.options?.hibernate ?? DEFAULT_AGENT_STATIC_OPTIONS.hibernate,
+			sendIdentityOnConnect: ctor.options?.sendIdentityOnConnect ?? DEFAULT_AGENT_STATIC_OPTIONS.sendIdentityOnConnect,
+			hungScheduleTimeoutSeconds: ctor.options?.hungScheduleTimeoutSeconds ?? DEFAULT_AGENT_STATIC_OPTIONS.hungScheduleTimeoutSeconds,
+			keepAliveIntervalMs: ctor.options?.keepAliveIntervalMs ?? DEFAULT_AGENT_STATIC_OPTIONS.keepAliveIntervalMs,
+			retry: {
+				maxAttempts: userRetry?.maxAttempts ?? DEFAULT_AGENT_STATIC_OPTIONS.retry.maxAttempts,
+				baseDelayMs: userRetry?.baseDelayMs ?? DEFAULT_AGENT_STATIC_OPTIONS.retry.baseDelayMs,
+				maxDelayMs: userRetry?.maxDelayMs ?? DEFAULT_AGENT_STATIC_OPTIONS.retry.maxDelayMs
+			}
+		};
+		return this._cachedOptions;
+	}
+	/**
+	* Emit an observability event with auto-generated timestamp.
+	* @internal
+	*/
+	_emit(type, payload = {}) {
+		this.observability?.emit({
+			type,
+			agent: this._ParentClass.name,
+			name: this.name,
+			payload,
+			timestamp: Date.now()
+		});
+	}
+	/**
+	* Execute SQL queries against the Agent's database
+	* @template T Type of the returned rows
+	* @param strings SQL query template strings
+	* @param values Values to be inserted into the query
+	* @returns Array of query results
+	*/
+	sql(strings, ...values) {
+		let query = "";
+		try {
+			query = strings.reduce((acc, str, i) => acc + str + (i < values.length ? "?" : ""), "");
+			return [...this.ctx.storage.sql.exec(query, ...values)];
+		} catch (e) {
+			throw new SqlError(query, e);
+		}
+	}
+	/**
+	* Create all internal tables and run migrations if needed.
+	* Called by the constructor on every wake. Idempotent — skips DDL when
+	* the stored schema version matches CURRENT_SCHEMA_VERSION.
+	*
+	* Protected so that test agents can re-run the real migration path
+	* after manipulating DB state (since ctx.abort() is unavailable in
+	* local dev and the constructor only runs once per DO instance).
+	*/
+	_ensureSchema() {
+		this.sql`
+      CREATE TABLE IF NOT EXISTS cf_agents_state (
+        id TEXT PRIMARY KEY NOT NULL,
+        state TEXT
+      )
+    `;
+		const versionRow = this.sql`
+      SELECT state FROM cf_agents_state WHERE id = ${SCHEMA_VERSION_ROW_ID}
+    `;
+		const schemaVersion = versionRow.length > 0 ? Number(versionRow[0].state) : 0;
+		if (schemaVersion < CURRENT_SCHEMA_VERSION) {
+			this.sql`
+          CREATE TABLE IF NOT EXISTS cf_agents_mcp_servers (
+            id TEXT PRIMARY KEY NOT NULL,
+            name TEXT NOT NULL,
+            server_url TEXT NOT NULL,
+            callback_url TEXT NOT NULL,
+            client_id TEXT,
+            auth_url TEXT,
+            server_options TEXT
+          )
+        `;
+			this.sql`
+        CREATE TABLE IF NOT EXISTS cf_agents_queues (
+          id TEXT PRIMARY KEY NOT NULL,
+          payload TEXT,
+          callback TEXT,
+          created_at INTEGER DEFAULT (unixepoch())
+        )
+      `;
+			this.sql`
+        CREATE TABLE IF NOT EXISTS cf_agents_schedules (
+          id TEXT PRIMARY KEY NOT NULL DEFAULT (randomblob(9)),
+          callback TEXT,
+          payload TEXT,
+          type TEXT NOT NULL CHECK(type IN ('scheduled', 'delayed', 'cron', 'interval')),
+          time INTEGER,
+          delayInSeconds INTEGER,
+          cron TEXT,
+          intervalSeconds INTEGER,
+          running INTEGER DEFAULT 0,
+          created_at INTEGER DEFAULT (unixepoch()),
+          execution_started_at INTEGER,
+          retry_options TEXT
+        )
+      `;
+			const addColumnIfNotExists = (sql) => {
+				try {
+					this.ctx.storage.sql.exec(sql);
+				} catch (e) {
+					if (!(e instanceof Error ? e.message : String(e)).toLowerCase().includes("duplicate column")) throw e;
+				}
+			};
+			addColumnIfNotExists("ALTER TABLE cf_agents_schedules ADD COLUMN intervalSeconds INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agents_schedules ADD COLUMN running INTEGER DEFAULT 0");
+			addColumnIfNotExists("ALTER TABLE cf_agents_schedules ADD COLUMN execution_started_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agents_schedules ADD COLUMN retry_options TEXT");
+			addColumnIfNotExists("ALTER TABLE cf_agents_queues ADD COLUMN retry_options TEXT");
+			{
+				const rows = this.ctx.storage.sql.exec("SELECT sql FROM sqlite_master WHERE type='table' AND name='cf_agents_schedules'").toArray();
+				if (rows.length > 0) {
+					if (!String(rows[0].sql).includes("'interval'")) {
+						this.ctx.storage.sql.exec("DROP TABLE IF EXISTS cf_agents_schedules_new");
+						this.ctx.storage.sql.exec(`
+              CREATE TABLE cf_agents_schedules_new (
+                id TEXT PRIMARY KEY NOT NULL DEFAULT (randomblob(9)),
+                callback TEXT,
+                payload TEXT,
+                type TEXT NOT NULL CHECK(type IN ('scheduled', 'delayed', 'cron', 'interval')),
+                time INTEGER,
+                delayInSeconds INTEGER,
+                cron TEXT,
+                intervalSeconds INTEGER,
+                running INTEGER DEFAULT 0,
+                created_at INTEGER DEFAULT (unixepoch()),
+                execution_started_at INTEGER,
+                retry_options TEXT
+              )
+            `);
+						this.ctx.storage.sql.exec(`
+              INSERT INTO cf_agents_schedules_new
+                (id, callback, payload, type, time, delayInSeconds, cron,
+                 intervalSeconds, running, created_at, execution_started_at, retry_options)
+              SELECT id, callback, payload, type, time, delayInSeconds, cron,
+                     intervalSeconds, running, created_at, execution_started_at, retry_options
+              FROM cf_agents_schedules
+            `);
+						this.ctx.storage.sql.exec("DROP TABLE cf_agents_schedules");
+						this.ctx.storage.sql.exec("ALTER TABLE cf_agents_schedules_new RENAME TO cf_agents_schedules");
+					}
+				}
+			}
+			this.sql`
+        CREATE TABLE IF NOT EXISTS cf_agents_workflows (
+          id TEXT PRIMARY KEY NOT NULL,
+          workflow_id TEXT NOT NULL UNIQUE,
+          workflow_name TEXT NOT NULL,
+          status TEXT NOT NULL CHECK(status IN (
+            'queued', 'running', 'paused', 'errored',
+            'terminated', 'complete', 'waiting',
+            'waitingForPause', 'unknown'
+          )),
+          metadata TEXT,
+          error_name TEXT,
+          error_message TEXT,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+          updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+          completed_at INTEGER
+        )
+      `;
+			this.sql`
+        CREATE INDEX IF NOT EXISTS idx_workflows_status ON cf_agents_workflows(status)
+      `;
+			this.sql`
+        CREATE INDEX IF NOT EXISTS idx_workflows_name ON cf_agents_workflows(workflow_name)
+      `;
+			this.ctx.storage.sql.exec("DELETE FROM cf_agents_state WHERE id = ?", STATE_WAS_CHANGED);
+			if (schemaVersion < 2) this.ctx.storage.sql.exec("DELETE FROM cf_agents_schedules WHERE callback = '_cf_keepAliveHeartbeat'");
+			this.sql`
+        CREATE TABLE IF NOT EXISTS cf_agents_runs (
+          id TEXT PRIMARY KEY NOT NULL,
+          name TEXT NOT NULL,
+          snapshot TEXT,
+          created_at INTEGER NOT NULL
+        )
+      `;
+			this.sql`
+        INSERT OR REPLACE INTO cf_agents_state (id, state)
+        VALUES (${SCHEMA_VERSION_ROW_ID}, ${String(CURRENT_SCHEMA_VERSION)})
+      `;
+		}
+	}
+	constructor(ctx, env) {
+		super(ctx, env);
+		this._state = DEFAULT_STATE;
+		this._disposables = new DisposableStore();
+		this._destroyed = false;
+		this._rawStateAccessors = /* @__PURE__ */ new WeakMap();
+		this._persistenceHookMode = "none";
+		this._isFacet = false;
+		this._insideOnStart = false;
+		this._warnedScheduleInOnStart = /* @__PURE__ */ new Set();
+		this._keepAliveRefs = 0;
+		this._runFiberActiveFibers = /* @__PURE__ */ new Set();
+		this._runFiberRecoveryInProgress = false;
+		this._ParentClass = Object.getPrototypeOf(this).constructor;
+		this.initialState = DEFAULT_STATE;
+		this.observability = genericObservability;
+		this._flushingQueue = false;
+		if (!wrappedClasses.has(this.constructor)) {
+			this._autoWrapCustomMethods();
+			wrappedClasses.add(this.constructor);
+		}
+		this._ensureSchema();
+		this.mcp = new MCPClientManager(this._ParentClass.name, "0.0.1", {
+			storage: this.ctx.storage,
+			createAuthProvider: (callbackUrl) => this.createMcpOAuthProvider(callbackUrl)
+		});
+		this._disposables.add(this.mcp.onServerStateChanged(async () => {
+			this.broadcastMcpServers();
+		}));
+		this._disposables.add(this.mcp.onObservabilityEvent((event) => {
+			this.observability?.emit({
+				...event,
+				agent: this._ParentClass.name,
+				name: this.name
+			});
+		}));
+		{
+			const proto = Object.getPrototypeOf(this);
+			const hasOwnNew = Object.prototype.hasOwnProperty.call(proto, "onStateChanged");
+			const hasOwnOld = Object.prototype.hasOwnProperty.call(proto, "onStateUpdate");
+			if (hasOwnNew && hasOwnOld) throw new Error("[Agent] Cannot override both onStateChanged and onStateUpdate. Remove onStateUpdate — it has been renamed to onStateChanged.");
+			if (hasOwnOld) {
+				const ctor = this.constructor;
+				if (!_onStateUpdateWarnedClasses.has(ctor)) {
+					_onStateUpdateWarnedClasses.add(ctor);
+					console.warn(`[Agent] onStateUpdate is deprecated. Rename to onStateChanged — the behavior is identical.`);
+				}
+			}
+			const base = Agent.prototype;
+			if (proto.onStateChanged !== base.onStateChanged) this._persistenceHookMode = "new";
+			else if (proto.onStateUpdate !== base.onStateUpdate) this._persistenceHookMode = "old";
+		}
+		const _onRequest = this.onRequest.bind(this);
+		this.onRequest = (request) => {
+			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
+				agent: this,
+				connection: void 0,
+				request,
+				email: void 0
+			}, async () => {
+				const oauthResponse = await this.handleMcpOAuthCallback(request);
+				if (oauthResponse) return oauthResponse;
+				return this._tryCatch(() => _onRequest(request));
+			});
+		};
+		const _onMessage = this.onMessage.bind(this);
+		this.onMessage = async (connection, message) => {
+			this._ensureConnectionWrapped(connection);
+			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
+				agent: this,
+				connection,
+				request: void 0,
+				email: void 0
+			}, async () => {
+				if (typeof message !== "string") return this._tryCatch(() => _onMessage(connection, message));
+				let parsed;
+				try {
+					parsed = JSON.parse(message);
+				} catch (_e) {
+					return this._tryCatch(() => _onMessage(connection, message));
+				}
+				if (isStateUpdateMessage(parsed)) {
+					if (this.isConnectionReadonly(connection)) {
+						connection.send(JSON.stringify({
+							type: MessageType.CF_AGENT_STATE_ERROR,
+							error: "Connection is readonly"
+						}));
+						return;
+					}
+					try {
+						this._setStateInternal(parsed.state, connection);
+					} catch (e) {
+						console.error("[Agent] State update rejected:", e);
+						connection.send(JSON.stringify({
+							type: MessageType.CF_AGENT_STATE_ERROR,
+							error: "State update rejected"
+						}));
+					}
+					return;
+				}
+				if (isRPCRequest(parsed)) {
+					try {
+						const { id, method, args } = parsed;
+						const methodFn = this[method];
+						if (typeof methodFn !== "function") throw new Error(`Method ${method} does not exist`);
+						if (!this._isCallable(method)) throw new Error(`Method ${method} is not callable`);
+						const metadata = callableMetadata.get(methodFn);
+						if (metadata?.streaming) {
+							const stream = new StreamingResponse(connection, id);
+							this._emit("rpc", {
+								method,
+								streaming: true
+							});
+							try {
+								await methodFn.apply(this, [stream, ...args]);
+							} catch (err) {
+								console.error(`Error in streaming method "${method}":`, err);
+								this._emit("rpc:error", {
+									method,
+									error: err instanceof Error ? err.message : String(err)
+								});
+								if (!stream.isClosed) stream.error(err instanceof Error ? err.message : String(err));
+							}
+							return;
+						}
+						const result = await methodFn.apply(this, args);
+						this._emit("rpc", {
+							method,
+							streaming: metadata?.streaming
+						});
+						const response = {
+							done: true,
+							id,
+							result,
+							success: true,
+							type: MessageType.RPC
+						};
+						connection.send(JSON.stringify(response));
+					} catch (e) {
+						const response = {
+							error: e instanceof Error ? e.message : "Unknown error occurred",
+							id: parsed.id,
+							success: false,
+							type: MessageType.RPC
+						};
+						connection.send(JSON.stringify(response));
+						console.error("RPC error:", e);
+						this._emit("rpc:error", {
+							method: parsed.method,
+							error: e instanceof Error ? e.message : String(e)
+						});
+					}
+					return;
+				}
+				return this._tryCatch(() => _onMessage(connection, message));
+			});
+		};
+		const _onConnect = this.onConnect.bind(this);
+		this.onConnect = (connection, ctx) => {
+			this._ensureConnectionWrapped(connection);
+			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
+				agent: this,
+				connection,
+				request: ctx.request,
+				email: void 0
+			}, async () => {
+				if (this.shouldConnectionBeReadonly(connection, ctx)) this.setConnectionReadonly(connection, true);
+				if (this.shouldSendProtocolMessages(connection, ctx)) {
+					if (this._resolvedOptions.sendIdentityOnConnect) {
+						const ctor = this.constructor;
+						if (ctor.options?.sendIdentityOnConnect === void 0 && !_sendIdentityWarnedClasses.has(ctor)) {
+							if (!new URL(ctx.request.url).pathname.includes(this.name)) {
+								_sendIdentityWarnedClasses.add(ctor);
+								console.warn(`[Agent] ${ctor.name}: sending instance name "${this.name}" to clients via sendIdentityOnConnect (the name is not visible in the URL with custom routing). If this name is sensitive, add \`static options = { sendIdentityOnConnect: false }\` to opt out. Set it to true to silence this message.`);
+							}
+						}
+						connection.send(JSON.stringify({
+							name: this.name,
+							agent: camelCaseToKebabCase(this._ParentClass.name),
+							type: MessageType.CF_AGENT_IDENTITY
+						}));
+					}
+					if (this.state) connection.send(JSON.stringify({
+						state: this.state,
+						type: MessageType.CF_AGENT_STATE
+					}));
+					connection.send(JSON.stringify({
+						mcp: this.getMcpServers(),
+						type: MessageType.CF_AGENT_MCP_SERVERS
+					}));
+				} else this._setConnectionNoProtocol(connection);
+				this._emit("connect", { connectionId: connection.id });
+				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({
+				agent: this,
+				connection: void 0,
+				request: void 0,
+				email: void 0
+			}, async () => {
+				if (await this.ctx.storage.get("cf_agents_is_facet")) this._isFacet = true;
+				await this._tryCatch(async () => {
+					await this.mcp.restoreConnectionsFromStorage(this.name);
+					await this._restoreRpcMcpServers();
+					this.broadcastMcpServers();
+					this._checkOrphanedWorkflows();
+					await this._checkRunFibers();
+					this._insideOnStart = true;
+					this._warnedScheduleInOnStart.clear();
+					try {
+						return await _onStart(props);
+					} finally {
+						this._insideOnStart = false;
+					}
+				});
+			});
+		};
+	}
+	/**
+	* Check for workflows referencing unknown bindings and warn with migration suggestion.
+	*/
+	_checkOrphanedWorkflows() {
+		const orphaned = this.sql`
+      SELECT 
+        workflow_name,
+        COUNT(*) as total,
+        SUM(CASE WHEN status NOT IN ('complete', 'errored', 'terminated') THEN 1 ELSE 0 END) as active,
+        SUM(CASE WHEN status IN ('complete', 'errored', 'terminated') THEN 1 ELSE 0 END) as completed
+      FROM cf_agents_workflows 
+      GROUP BY workflow_name
+    `.filter((row) => !this._findWorkflowBindingByName(row.workflow_name));
+		if (orphaned.length > 0) {
+			const currentBindings = this._getWorkflowBindingNames();
+			for (const { workflow_name: oldName, total, active, completed } of orphaned) {
+				const suggestion = currentBindings.length === 1 ? `this.migrateWorkflowBinding('${oldName}', '${currentBindings[0]}')` : `this.migrateWorkflowBinding('${oldName}', '<NEW_BINDING_NAME>')`;
+				const breakdown = active > 0 && completed > 0 ? ` (${active} active, ${completed} completed)` : active > 0 ? ` (${active} active)` : ` (${completed} completed)`;
+				console.warn(`[Agent] Found ${total} workflow(s) referencing unknown binding '${oldName}'${breakdown}. If you renamed the binding, call: ${suggestion}`);
+			}
+		}
+	}
+	/**
+	* Broadcast a protocol message only to connections that have protocol
+	* messages enabled. Connections where shouldSendProtocolMessages returned
+	* false are excluded automatically.
+	* @param msg The JSON-encoded protocol message
+	* @param excludeIds Additional connection IDs to exclude (e.g. the source)
+	*/
+	_broadcastProtocol(msg, excludeIds = []) {
+		const exclude = [...excludeIds];
+		for (const conn of this.getConnections()) if (!this.isConnectionProtocolEnabled(conn)) exclude.push(conn.id);
+		this.broadcast(msg, exclude);
+	}
+	_setStateInternal(nextState, source = "server") {
+		this.validateStateChange(nextState, source);
+		this._state = nextState;
+		this.sql`
+      INSERT OR REPLACE INTO cf_agents_state (id, state)
+      VALUES (${STATE_ROW_ID}, ${JSON.stringify(nextState)})
+    `;
+		this._broadcastProtocol(JSON.stringify({
+			state: nextState,
+			type: MessageType.CF_AGENT_STATE
+		}), source !== "server" ? [source.id] : []);
+		const { connection, request, email } = __DO_NOT_USE_WILL_BREAK__agentContext.getStore() || {};
+		this.ctx.waitUntil((async () => {
+			try {
+				await __DO_NOT_USE_WILL_BREAK__agentContext.run({
+					agent: this,
+					connection,
+					request,
+					email
+				}, async () => {
+					this._emit("state:update");
+					await this._callStatePersistenceHook(nextState, source);
+				});
+			} catch (e) {
+				try {
+					await this.onError(e);
+				} catch {}
+			}
+		})());
+	}
+	/**
+	* Update the Agent's state
+	* @param state New state to set
+	* @throws Error if called from a readonly connection context
+	*/
+	setState(state) {
+		const store = __DO_NOT_USE_WILL_BREAK__agentContext.getStore();
+		if (store?.connection && this.isConnectionReadonly(store.connection)) throw new Error("Connection is readonly");
+		this._setStateInternal(state, "server");
+	}
+	/**
+	* Wraps connection.state and connection.setState so that internal
+	* _cf_-prefixed flags (readonly, no-protocol) are hidden from user code
+	* and cannot be accidentally overwritten.
+	*
+	* Idempotent — safe to call multiple times on the same connection.
+	* After hibernation, the _rawStateAccessors WeakMap is empty but the
+	* connection's state getter still reads from the persisted WebSocket
+	* attachment. Calling this method re-captures the raw getter so that
+	* predicate methods (isConnectionReadonly, isConnectionProtocolEnabled)
+	* work correctly post-hibernation.
+	*/
+	_ensureConnectionWrapped(connection) {
+		if (this._rawStateAccessors.has(connection)) return;
+		const descriptor = Object.getOwnPropertyDescriptor(connection, "state");
+		let getRaw;
+		let setRaw;
+		if (descriptor?.get) {
+			getRaw = descriptor.get.bind(connection);
+			setRaw = connection.setState.bind(connection);
+		} else {
+			let rawState = connection.state ?? null;
+			getRaw = () => rawState;
+			setRaw = (state) => {
+				rawState = state;
+				return rawState;
+			};
+		}
+		this._rawStateAccessors.set(connection, {
+			getRaw,
+			setRaw
+		});
+		Object.defineProperty(connection, "state", {
+			configurable: true,
+			enumerable: true,
+			get() {
+				const raw = getRaw();
+				if (raw != null && typeof raw === "object" && rawHasInternalKeys(raw)) return stripInternalKeys(raw);
+				return raw;
+			}
+		});
+		Object.defineProperty(connection, "setState", {
+			configurable: true,
+			writable: true,
+			value(stateOrFn) {
+				const raw = getRaw();
+				const flags = raw != null && typeof raw === "object" ? extractInternalFlags(raw) : {};
+				const hasFlags = Object.keys(flags).length > 0;
+				let newUserState;
+				if (typeof stateOrFn === "function") newUserState = stateOrFn(hasFlags ? stripInternalKeys(raw) : raw);
+				else newUserState = stateOrFn;
+				if (hasFlags) {
+					if (newUserState != null && typeof newUserState === "object") return setRaw({
+						...newUserState,
+						...flags
+					});
+					return setRaw(flags);
+				}
+				return setRaw(newUserState);
+			}
+		});
+	}
+	/**
+	* Mark a connection as readonly or readwrite
+	* @param connection The connection to mark
+	* @param readonly Whether the connection should be readonly (default: true)
+	*/
+	setConnectionReadonly(connection, readonly = true) {
+		this._ensureConnectionWrapped(connection);
+		const accessors = this._rawStateAccessors.get(connection);
+		const raw = accessors.getRaw() ?? {};
+		if (readonly) accessors.setRaw({
+			...raw,
+			[CF_READONLY_KEY]: true
+		});
+		else {
+			const { [CF_READONLY_KEY]: _, ...rest } = raw;
+			accessors.setRaw(Object.keys(rest).length > 0 ? rest : null);
+		}
+	}
+	/**
+	* Check if a connection is marked as readonly.
+	*
+	* Safe to call after hibernation — re-wraps the connection if the
+	* in-memory accessor cache was cleared.
+	* @param connection The connection to check
+	* @returns True if the connection is readonly
+	*/
+	isConnectionReadonly(connection) {
+		this._ensureConnectionWrapped(connection);
+		return !!this._rawStateAccessors.get(connection).getRaw()?.[CF_READONLY_KEY];
+	}
+	/**
+	* ⚠️ INTERNAL — DO NOT USE IN APPLICATION CODE. ⚠️
+	*
+	* Read an internal `_cf_`-prefixed flag from the raw connection state,
+	* bypassing the user-facing state wrapper that strips internal keys.
+	*
+	* This exists for framework mixins (e.g. voice) that need to persist
+	* flags in the connection attachment across hibernation. Application
+	* code should use `connection.state` and `connection.setState()` instead.
+	*
+	* @internal
+	*/
+	_unsafe_getConnectionFlag(connection, key) {
+		this._ensureConnectionWrapped(connection);
+		return this._rawStateAccessors.get(connection).getRaw()?.[key];
+	}
+	/**
+	* ⚠️ INTERNAL — DO NOT USE IN APPLICATION CODE. ⚠️
+	*
+	* Write an internal `_cf_`-prefixed flag to the raw connection state,
+	* bypassing the user-facing state wrapper. The key must be registered
+	* in `CF_INTERNAL_KEYS` so it is preserved across user `setState` calls
+	* and hidden from `connection.state`.
+	*
+	* @internal
+	*/
+	_unsafe_setConnectionFlag(connection, key, value) {
+		this._ensureConnectionWrapped(connection);
+		const accessors = this._rawStateAccessors.get(connection);
+		const raw = accessors.getRaw() ?? {};
+		if (value === void 0) {
+			const { [key]: _, ...rest } = raw;
+			accessors.setRaw(Object.keys(rest).length > 0 ? rest : null);
+		} else accessors.setRaw({
+			...raw,
+			[key]: value
+		});
+	}
+	/**
+	* Override this method to determine if a connection should be readonly on connect
+	* @param _connection The connection that is being established
+	* @param _ctx Connection context
+	* @returns True if the connection should be readonly
+	*/
+	shouldConnectionBeReadonly(_connection, _ctx) {
+		return false;
+	}
+	/**
+	* Override this method to control whether protocol messages are sent to a
+	* connection. Protocol messages include identity (CF_AGENT_IDENTITY), state
+	* sync (CF_AGENT_STATE), and MCP server lists (CF_AGENT_MCP_SERVERS).
+	*
+	* When this returns `false` for a connection, that connection will not
+	* receive any protocol text frames — neither on connect nor via broadcasts.
+	* This is useful for binary-only clients (e.g. MQTT devices) that cannot
+	* handle JSON text frames.
+	*
+	* The connection can still send and receive regular messages, use RPC, and
+	* participate in all non-protocol communication.
+	*
+	* @param _connection The connection that is being established
+	* @param _ctx Connection context (includes the upgrade request)
+	* @returns True if protocol messages should be sent (default), false to suppress them
+	*/
+	shouldSendProtocolMessages(_connection, _ctx) {
+		return true;
+	}
+	/**
+	* Check if a connection has protocol messages enabled.
+	* Protocol messages include identity, state sync, and MCP server lists.
+	*
+	* Safe to call after hibernation — re-wraps the connection if the
+	* in-memory accessor cache was cleared.
+	* @param connection The connection to check
+	* @returns True if the connection receives protocol messages
+	*/
+	isConnectionProtocolEnabled(connection) {
+		this._ensureConnectionWrapped(connection);
+		return !this._rawStateAccessors.get(connection).getRaw()?.[CF_NO_PROTOCOL_KEY];
+	}
+	/**
+	* Mark a connection as having protocol messages disabled.
+	* Called internally when shouldSendProtocolMessages returns false.
+	*/
+	_setConnectionNoProtocol(connection) {
+		this._ensureConnectionWrapped(connection);
+		const accessors = this._rawStateAccessors.get(connection);
+		const raw = accessors.getRaw() ?? {};
+		accessors.setRaw({
+			...raw,
+			[CF_NO_PROTOCOL_KEY]: true
+		});
+	}
+	/**
+	* Called before the Agent's state is persisted and broadcast.
+	* Override to validate or reject an update by throwing an error.
+	*
+	* IMPORTANT: This hook must be synchronous.
+	*/
+	validateStateChange(nextState, source) {}
+	/**
+	* Called after the Agent's state has been persisted and broadcast to all clients.
+	* This is a notification hook — errors here are routed to onError and do not
+	* affect state persistence or client broadcasts.
+	*
+	* @param state Updated state
+	* @param source Source of the state update ("server" or a client connection)
+	*/
+	onStateChanged(state, source) {}
+	/**
+	* @deprecated Renamed to `onStateChanged` — the behavior is identical.
+	* `onStateUpdate` will be removed in the next major version.
+	*
+	* Called after the Agent's state has been persisted and broadcast to all clients.
+	* This is a server-side notification hook. For the client-side state callback,
+	* see the `onStateUpdate` option in `useAgent` / `AgentClient`.
+	*
+	* @param state Updated state
+	* @param source Source of the state update ("server" or a client connection)
+	*/
+	onStateUpdate(state, source) {}
+	/**
+	* Dispatch to the appropriate persistence hook based on the mode
+	* cached in the constructor. No prototype walks at call time.
+	*/
+	async _callStatePersistenceHook(state, source) {
+		switch (this._persistenceHookMode) {
+			case "new":
+				await this.onStateChanged(state, source);
+				break;
+			case "old":
+				await this.onStateUpdate(state, source);
+				break;
+		}
+	}
+	/**
+	* Called when the Agent receives an email via routeAgentEmail()
+	* Override this method to handle incoming emails
+	* @param payload Internal wire format — plain data + RpcTarget bridge
+	*/
+	async _onEmail(payload) {
+		const email = {
+			from: payload.from,
+			to: payload.to,
+			headers: payload.headers,
+			rawSize: payload.rawSize,
+			_secureRouted: payload._secureRouted,
+			getRaw: () => payload._bridge.getRaw(),
+			setReject: (reason) => payload._bridge.setReject(reason),
+			forward: (rcptTo, headers) => payload._bridge.forward(rcptTo, headers),
+			reply: (options) => payload._bridge.reply(options)
+		};
+		return __DO_NOT_USE_WILL_BREAK__agentContext.run({
+			agent: this,
+			connection: void 0,
+			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);
+				console.log("Subject:", email.headers.get("subject"));
+				console.log("Implement onEmail(email: AgentEmail): Promise<void> in your agent to process emails");
+			}
+		});
+	}
+	/**
+	* Reply to an email
+	* @param email The email to reply to
+	* @param options Options for the reply
+	* @param options.secret Secret for signing agent headers (enables secure reply routing).
+	*   Required if the email was routed via createSecureReplyEmailResolver.
+	*   Pass explicit `null` to opt-out of signing (not recommended for secure routing).
+	* @returns void
+	*/
+	async replyToEmail(email, options) {
+		return this._tryCatch(async () => {
+			if (email._secureRouted && options.secret === void 0) throw new Error("This email was routed via createSecureReplyEmailResolver. You must pass a secret to replyToEmail() to sign replies, or pass explicit null to opt-out (not recommended).");
+			const agentName = camelCaseToKebabCase(this._ParentClass.name);
+			const agentId = this.name;
+			const { createMimeMessage } = await import("mimetext");
+			const msg = createMimeMessage();
+			msg.setSender({
+				addr: email.to,
+				name: options.fromName
+			});
+			msg.setRecipient(email.from);
+			msg.setSubject(options.subject || `Re: ${email.headers.get("subject")}` || "No subject");
+			msg.addMessage({
+				contentType: options.contentType || "text/plain",
+				data: options.body
+			});
+			const messageId = `<${agentId}@${email.from.split("@")[1]}>`;
+			msg.setHeader("In-Reply-To", email.headers.get("Message-ID"));
+			msg.setHeader("Message-ID", messageId);
+			msg.setHeader("X-Agent-Name", agentName);
+			msg.setHeader("X-Agent-ID", agentId);
+			if (typeof options.secret === "string") {
+				const signedHeaders = await signAgentHeaders(options.secret, agentName, agentId);
+				msg.setHeader("X-Agent-Sig", signedHeaders["X-Agent-Sig"]);
+				msg.setHeader("X-Agent-Sig-Ts", signedHeaders["X-Agent-Sig-Ts"]);
+			}
+			if (options.headers) for (const [key, value] of Object.entries(options.headers)) msg.setHeader(key, value);
+			await email.reply({
+				from: email.to,
+				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) {
+		try {
+			return await fn();
+		} catch (e) {
+			throw this.onError(e);
+		}
+	}
+	/**
+	* Automatically wrap custom methods with agent context
+	* This ensures getCurrentAgent() works in all custom methods without decorators
+	*/
+	_autoWrapCustomMethods() {
+		const basePrototypes = [Agent.prototype, Server.prototype];
+		const baseMethods = /* @__PURE__ */ new Set();
+		for (const baseProto of basePrototypes) {
+			let proto = baseProto;
+			while (proto && proto !== Object.prototype) {
+				const methodNames = Object.getOwnPropertyNames(proto);
+				for (const methodName of methodNames) baseMethods.add(methodName);
+				proto = Object.getPrototypeOf(proto);
+			}
+		}
+		let proto = Object.getPrototypeOf(this);
+		let depth = 0;
+		while (proto && proto !== Object.prototype && depth < 10) {
+			const methodNames = Object.getOwnPropertyNames(proto);
+			for (const methodName of methodNames) {
+				const descriptor = Object.getOwnPropertyDescriptor(proto, methodName);
+				if (baseMethods.has(methodName) || methodName.startsWith("_") || !descriptor || !!descriptor.get || typeof descriptor.value !== "function") continue;
+				const wrappedFunction = withAgentContext(this[methodName]);
+				if (this._isCallable(methodName)) callableMetadata.set(wrappedFunction, callableMetadata.get(this[methodName]));
+				this.constructor.prototype[methodName] = wrappedFunction;
+			}
+			proto = Object.getPrototypeOf(proto);
+			depth++;
+		}
+	}
+	onError(connectionOrError, error) {
+		let theError;
+		if (connectionOrError && error) {
+			theError = error;
+			console.error("Error on websocket connection:", connectionOrError.id, theError);
+			console.error("Override onError(connection, error) to handle websocket connection errors");
+		} else {
+			theError = connectionOrError;
+			console.error("Error on server:", theError);
+			console.error("Override onError(error) to handle server errors");
+		}
+		throw theError;
+	}
+	/**
+	* Render content (not implemented in base class)
+	*/
+	render() {
+		throw new Error("Not implemented");
+	}
+	/**
+	* Retry an async operation with exponential backoff and jitter.
+	* Retries on all errors by default. Use `shouldRetry` to bail early on non-retryable errors.
+	*
+	* @param fn The async function to retry. Receives the current attempt number (1-indexed).
+	* @param options Retry configuration.
+	* @param options.maxAttempts Maximum number of attempts (including the first). Falls back to static options, then 3.
+	* @param options.baseDelayMs Base delay in ms for exponential backoff. Falls back to static options, then 100.
+	* @param options.maxDelayMs Maximum delay cap in ms. Falls back to static options, then 3000.
+	* @param options.shouldRetry Predicate called with the error and next attempt number. Return false to stop retrying immediately. Default: retry all errors.
+	* @returns The result of fn on success.
+	* @throws The last error if all attempts fail or shouldRetry returns false.
+	*/
+	async retry(fn, options) {
+		const defaults = this._resolvedOptions.retry;
+		if (options) validateRetryOptions(options, defaults);
+		return tryN(options?.maxAttempts ?? defaults.maxAttempts, fn, {
+			baseDelayMs: options?.baseDelayMs ?? defaults.baseDelayMs,
+			maxDelayMs: options?.maxDelayMs ?? defaults.maxDelayMs,
+			shouldRetry: options?.shouldRetry
+		});
+	}
+	/**
+	* Queue a task to be executed in the future
+	* @param callback Name of the method to call
+	* @param payload Payload to pass to the callback
+	* @param options Options for the queued task
+	* @param options.retry Retry options for the callback execution
+	* @returns The ID of the queued task
+	*/
+	async queue(callback, payload, options) {
+		const id = nanoid(9);
+		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 retryJson = options?.retry ? JSON.stringify(options.retry) : null;
+		this.sql`
+      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);
+		});
+		return id;
+	}
+	async _flushQueue() {
+		if (this._flushingQueue) return;
+		this._flushingQueue = true;
+		try {
+			while (true) {
+				const result = this.sql`
+        SELECT * FROM cf_agents_queues
+        ORDER BY created_at ASC
+      `;
+				if (!result || result.length === 0) break;
+				for (const row of result || []) {
+					const callback = this[row.callback];
+					if (!callback) {
+						console.error(`callback ${row.callback} not found`);
+						await this.dequeue(row.id);
+						continue;
+					}
+					const { connection, request, email } = __DO_NOT_USE_WILL_BREAK__agentContext.getStore() || {};
+					await __DO_NOT_USE_WILL_BREAK__agentContext.run({
+						agent: this,
+						connection,
+						request,
+						email
+					}, async () => {
+						const { maxAttempts, baseDelayMs, maxDelayMs } = resolveRetryConfig(parseRetryOptions(row), this._resolvedOptions.retry);
+						const parsedPayload = JSON.parse(row.payload);
+						try {
+							await tryN(maxAttempts, async (attempt) => {
+								if (attempt > 1) this._emit("queue:retry", {
+									callback: row.callback,
+									id: row.id,
+									attempt,
+									maxAttempts
+								});
+								await callback.bind(this)(parsedPayload, row);
+							}, {
+								baseDelayMs,
+								maxDelayMs
+							});
+						} catch (e) {
+							console.error(`queue callback "${row.callback}" failed after ${maxAttempts} attempts`, e);
+							this._emit("queue:error", {
+								callback: row.callback,
+								id: row.id,
+								error: e instanceof Error ? e.message : String(e),
+								attempts: maxAttempts
+							});
+							try {
+								await this.onError(e);
+							} catch {}
+						} finally {
+							this.dequeue(row.id);
+						}
+					});
+				}
+			}
+		} finally {
+			this._flushingQueue = false;
+		}
+	}
+	/**
+	* Dequeue a task by ID
+	* @param id ID of the task to dequeue
+	*/
+	dequeue(id) {
+		this.sql`DELETE FROM cf_agents_queues WHERE id = ${id}`;
+	}
+	/**
+	* Dequeue all tasks
+	*/
+	dequeueAll() {
+		this.sql`DELETE FROM cf_agents_queues`;
+	}
+	/**
+	* Dequeue all tasks by callback
+	* @param callback Name of the callback to dequeue
+	*/
+	dequeueAllByCallback(callback) {
+		this.sql`DELETE FROM cf_agents_queues WHERE callback = ${callback}`;
+	}
+	/**
+	* Get a queued task by ID
+	* @param id ID of the task to get
+	* @returns The task or undefined if not found
+	*/
+	getQueue(id) {
+		const result = this.sql`
+      SELECT * FROM cf_agents_queues WHERE id = ${id}
+    `;
+		if (!result || result.length === 0) return void 0;
+		const row = result[0];
+		return {
+			...row,
+			payload: JSON.parse(row.payload),
+			retry: parseRetryOptions(row)
+		};
+	}
+	/**
+	* Get all queues by key and value
+	* @param key Key to filter by
+	* @param value Value to filter by
+	* @returns Array of matching QueueItem objects
+	*/
+	getQueues(key, value) {
+		return this.sql`
+      SELECT * FROM cf_agents_queues
+    `.filter((row) => JSON.parse(row.payload)[key] === value).map((row) => ({
+			...row,
+			payload: JSON.parse(row.payload),
+			retry: parseRetryOptions(row)
+		}));
+	}
+	/**
+	* Schedule a task to be executed in the future
+	*
+	* Cron schedules are **idempotent by default** — calling `schedule("0 * * * *", "tick")`
+	* multiple times with the same callback, cron expression, and payload returns
+	* the existing schedule instead of creating a duplicate. Set `idempotent: false`
+	* to override this.
+	*
+	* For delayed and scheduled (Date) types, set `idempotent: true` to opt in
+	* to the same dedup behavior (matched on callback + payload). This is useful
+	* when calling `schedule()` in `onStart()` to avoid accumulating duplicate
+	* rows across Durable Object restarts.
+	*
+	* @template T Type of the payload data
+	* @param when When to execute the task (Date, seconds delay, or cron expression)
+	* @param callback Name of the method to call
+	* @param payload Data to pass to the callback
+	* @param options Options for the scheduled task
+	* @param options.retry Retry options for the callback execution
+	* @param options.idempotent Dedup by callback+payload. Defaults to `true` for cron, `false` otherwise.
+	* @returns Schedule object representing the scheduled task
+	*/
+	async schedule(when, callback, payload, options) {
+		if (this._isFacet) throw new Error("Scheduling is not supported in sub-agents. Schedule from the parent agent instead.");
+		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 retryJson = options?.retry ? JSON.stringify(options.retry) : null;
+		const payloadJson = JSON.stringify(payload);
+		if (this._insideOnStart && options?.idempotent === void 0 && typeof when !== "string" && !this._warnedScheduleInOnStart.has(callback)) {
+			this._warnedScheduleInOnStart.add(callback);
+			console.warn(`schedule("${callback}") called inside onStart() without { idempotent: true }. This creates a new row on every Durable Object restart, which can cause duplicate executions. Pass { idempotent: true } to deduplicate, or use scheduleEvery() for recurring tasks.`);
+		}
+		if (when instanceof Date) {
+			const timestamp = Math.floor(when.getTime() / 1e3);
+			if (options?.idempotent) {
+				const existing = this.sql`
+          SELECT * FROM cf_agents_schedules
+          WHERE type = 'scheduled'
+            AND callback = ${callback}
+            AND payload IS ${payloadJson}
+          LIMIT 1
+        `;
+				if (existing.length > 0) {
+					const row = existing[0];
+					await this._scheduleNextAlarm();
+					return {
+						callback: row.callback,
+						id: row.id,
+						payload: JSON.parse(row.payload),
+						retry: parseRetryOptions(row),
+						time: row.time,
+						type: "scheduled"
+					};
+				}
+			}
+			const id = nanoid(9);
+			this.sql`
+        INSERT OR REPLACE INTO cf_agents_schedules (id, callback, payload, type, time, retry_options)
+        VALUES (${id}, ${callback}, ${payloadJson}, 'scheduled', ${timestamp}, ${retryJson})
+      `;
+			await this._scheduleNextAlarm();
+			const schedule = {
+				callback,
+				id,
+				payload,
+				retry: options?.retry,
+				time: timestamp,
+				type: "scheduled"
+			};
+			this._emit("schedule:create", {
+				callback,
+				id
+			});
+			return schedule;
+		}
+		if (typeof when === "number") {
+			const time = new Date(Date.now() + when * 1e3);
+			const timestamp = Math.floor(time.getTime() / 1e3);
+			if (options?.idempotent) {
+				const existing = this.sql`
+          SELECT * FROM cf_agents_schedules
+          WHERE type = 'delayed'
+            AND callback = ${callback}
+            AND payload IS ${payloadJson}
+          LIMIT 1
+        `;
+				if (existing.length > 0) {
+					const row = existing[0];
+					await this._scheduleNextAlarm();
+					return {
+						callback: row.callback,
+						delayInSeconds: row.delayInSeconds,
+						id: row.id,
+						payload: JSON.parse(row.payload),
+						retry: parseRetryOptions(row),
+						time: row.time,
+						type: "delayed"
+					};
+				}
+			}
+			const id = nanoid(9);
+			this.sql`
+        INSERT OR REPLACE INTO cf_agents_schedules (id, callback, payload, type, delayInSeconds, time, retry_options)
+        VALUES (${id}, ${callback}, ${payloadJson}, 'delayed', ${when}, ${timestamp}, ${retryJson})
+      `;
+			await this._scheduleNextAlarm();
+			const schedule = {
+				callback,
+				delayInSeconds: when,
+				id,
+				payload,
+				retry: options?.retry,
+				time: timestamp,
+				type: "delayed"
+			};
+			this._emit("schedule:create", {
+				callback,
+				id
+			});
+			return schedule;
+		}
+		if (typeof when === "string") {
+			const nextExecutionTime = getNextCronTime(when);
+			const timestamp = Math.floor(nextExecutionTime.getTime() / 1e3);
+			if (options?.idempotent !== false) {
+				const existing = this.sql`
+          SELECT * FROM cf_agents_schedules
+          WHERE type = 'cron'
+            AND callback = ${callback}
+            AND cron = ${when}
+            AND payload IS ${payloadJson}
+          LIMIT 1
+        `;
+				if (existing.length > 0) {
+					const row = existing[0];
+					await this._scheduleNextAlarm();
+					return {
+						callback: row.callback,
+						cron: row.cron,
+						id: row.id,
+						payload: JSON.parse(row.payload),
+						retry: parseRetryOptions(row),
+						time: row.time,
+						type: "cron"
+					};
+				}
+			}
+			const id = nanoid(9);
+			this.sql`
+        INSERT OR REPLACE INTO cf_agents_schedules (id, callback, payload, type, cron, time, retry_options)
+        VALUES (${id}, ${callback}, ${payloadJson}, 'cron', ${when}, ${timestamp}, ${retryJson})
+      `;
+			await this._scheduleNextAlarm();
+			const schedule = {
+				callback,
+				cron: when,
+				id,
+				payload,
+				retry: options?.retry,
+				time: timestamp,
+				type: "cron"
+			};
+			this._emit("schedule:create", {
+				callback,
+				id
+			});
+			return schedule;
+		}
+		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.
+	*
+	* 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
+	* @param payload Data to pass to the callback
+	* @param options Options for the scheduled task
+	* @param options.retry Retry options for the callback execution
+	* @returns Schedule object representing the scheduled task
+	*/
+	async scheduleEvery(intervalSeconds, callback, payload, options) {
+		if (this._isFacet) throw new Error("Scheduling is not supported in sub-agents. Schedule from the parent agent instead.");
+		const MAX_INTERVAL_SECONDS = 720 * 60 * 60;
+		if (typeof intervalSeconds !== "number" || intervalSeconds <= 0) throw new Error("intervalSeconds must be a positive number");
+		if (intervalSeconds > MAX_INTERVAL_SECONDS) throw new Error(`intervalSeconds cannot exceed ${MAX_INTERVAL_SECONDS} seconds (30 days)`);
+		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];
+				await this._scheduleNextAlarm();
+				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}, ${payloadJson}, 'interval', ${intervalSeconds}, ${timestamp}, 0, ${retryJson})
+    `;
+		await this._scheduleNextAlarm();
+		const schedule = {
+			callback,
+			id,
+			intervalSeconds,
+			payload,
+			retry: options?.retry,
+			time: timestamp,
+			type: "interval"
+		};
+		this._emit("schedule:create", {
+			callback,
+			id
+		});
+		return schedule;
+	}
+	/**
+	* Get a scheduled task by ID
+	* @template T Type of the payload data
+	* @param id ID of the scheduled task
+	* @returns The Schedule object or undefined if not found
+	*/
+	getSchedule(id) {
+		const result = this.sql`
+      SELECT * FROM cf_agents_schedules WHERE id = ${id}
+    `;
+		if (!result || result.length === 0) return;
+		const row = result[0];
+		return {
+			...row,
+			payload: JSON.parse(row.payload),
+			retry: parseRetryOptions(row)
+		};
+	}
+	/**
+	* Get scheduled tasks matching the given criteria
+	* @template T Type of the payload data
+	* @param criteria Criteria to filter schedules
+	* @returns Array of matching Schedule objects
+	*/
+	getSchedules(criteria = {}) {
+		let query = "SELECT * FROM cf_agents_schedules WHERE 1=1";
+		const params = [];
+		if (criteria.id) {
+			query += " AND id = ?";
+			params.push(criteria.id);
+		}
+		if (criteria.type) {
+			query += " AND type = ?";
+			params.push(criteria.type);
+		}
+		if (criteria.timeRange) {
+			query += " AND time >= ? AND time <= ?";
+			const start = criteria.timeRange.start || /* @__PURE__ */ new Date(0);
+			const end = criteria.timeRange.end || /* @__PURE__ */ new Date(999999999999999);
+			params.push(Math.floor(start.getTime() / 1e3), Math.floor(end.getTime() / 1e3));
+		}
+		return this.ctx.storage.sql.exec(query, ...params).toArray().map((row) => ({
+			...row,
+			payload: JSON.parse(row.payload),
+			retry: parseRetryOptions(row)
+		}));
+	}
+	/**
+	* Cancel a scheduled task
+	* @param id ID of the task to cancel
+	* @returns true if the task was cancelled, false if the task was not found
+	*/
+	async cancelSchedule(id) {
+		if (this._isFacet) throw new Error("Scheduling is not supported in sub-agents. Schedule from the parent agent instead.");
+		const schedule = this.getSchedule(id);
+		if (!schedule) return false;
+		this._emit("schedule:cancel", {
+			callback: schedule.callback,
+			id: schedule.id
+		});
+		this.sql`DELETE FROM cf_agents_schedules WHERE id = ${id}`;
+		await this._scheduleNextAlarm();
+		return true;
+	}
+	/**
+	* Keep the Durable Object alive via alarm heartbeats.
+	* Returns a disposer function that stops the heartbeat when called.
+	*
+	* Use this when you have long-running work and need to prevent the
+	* DO from going idle (eviction after ~70-140s of inactivity).
+	* The heartbeat fires every `keepAliveIntervalMs` (default 30s) via the
+	* alarm system, without creating schedule rows or emitting observability
+	* events. Configure via `static options = { keepAliveIntervalMs: 5000 }`.
+	*
+	* @example
+	* ```ts
+	* const dispose = await this.keepAlive();
+	* try {
+	*   // ... long-running work ...
+	* } finally {
+	*   dispose();
+	* }
+	* ```
+	*/
+	async keepAlive() {
+		if (this._isFacet) throw new Error("keepAlive() is not supported in sub-agents. Use keepAlive() from the parent agent instead.");
+		this._keepAliveRefs++;
+		if (this._keepAliveRefs === 1) await this._scheduleNextAlarm();
+		let disposed = false;
+		return () => {
+			if (disposed) return;
+			disposed = true;
+			this._keepAliveRefs = Math.max(0, this._keepAliveRefs - 1);
+		};
+	}
+	/**
+	* Run an async function while keeping the Durable Object alive.
+	* The heartbeat is automatically stopped when the function completes
+	* (whether it succeeds or throws).
+	*
+	* This is the recommended way to use keepAlive — it guarantees cleanup
+	* so you cannot forget to dispose the heartbeat.
+	*
+	* @example
+	* ```ts
+	* const result = await this.keepAliveWhile(async () => {
+	*   const data = await longRunningComputation();
+	*   return data;
+	* });
+	* ```
+	*/
+	async keepAliveWhile(fn) {
+		const dispose = await this.keepAlive();
+		try {
+			return await fn();
+		} finally {
+			dispose();
+		}
+	}
+	/**
+	* Run a function as a durable fiber. The fiber is registered in SQLite
+	* before execution, checkpointable during execution via `ctx.stash()`,
+	* and recoverable after eviction via `onFiberRecovered`.
+	*
+	* - Row created in `cf_agents_runs` at start, deleted on completion
+	* - `keepAlive()` held for the duration — prevents idle eviction
+	* - Inline (await result) or fire-and-forget (`void this.runFiber(...)`)
+	*
+	* @param name Informational name for debugging and recovery filtering
+	* @param fn Async function to execute. Receives a FiberContext with stash/snapshot.
+	* @returns The return value of fn
+	*/
+	async runFiber(name, fn) {
+		const id = nanoid();
+		this.sql`
+      INSERT INTO cf_agents_runs (id, name, snapshot, created_at)
+      VALUES (${id}, ${name}, NULL, ${Date.now()})
+    `;
+		this._runFiberActiveFibers.add(id);
+		const dispose = await this.keepAlive();
+		try {
+			const stash = (data) => {
+				this.sql`
+          UPDATE cf_agents_runs SET snapshot = ${JSON.stringify(data)}
+          WHERE id = ${id}
+        `;
+			};
+			return await _fiberALS.run({
+				id,
+				stash
+			}, () => fn({
+				id,
+				stash,
+				snapshot: null
+			}));
+		} finally {
+			this._runFiberActiveFibers.delete(id);
+			this.sql`DELETE FROM cf_agents_runs WHERE id = ${id}`;
+			dispose();
+		}
+	}
+	/**
+	* Checkpoint data for the currently executing fiber.
+	* Uses AsyncLocalStorage to identify the correct fiber,
+	* so it works correctly even with concurrent fibers.
+	*
+	* Throws if called outside a `runFiber` callback.
+	*/
+	stash(data) {
+		const ctx = _fiberALS.getStore();
+		if (!ctx) throw new Error("stash() called outside a fiber");
+		ctx.stash(data);
+	}
+	/**
+	* Called when an interrupted fiber is detected after restart.
+	* Override to implement recovery (re-invoke work, notify clients, etc.).
+	*
+	* Internal framework fibers are filtered by `_handleInternalFiberRecovery`
+	* before this hook runs — users only see their own fibers.
+	*
+	* Default: logs a warning.
+	*/
+	async onFiberRecovered(_ctx) {
+		console.warn(`[Agent] Fiber "${_ctx.name}" (${_ctx.id}) was interrupted. Override onFiberRecovered to handle recovery.`);
+	}
+	/**
+	* Override point for subclasses to handle internal (framework) fibers
+	* before the user's recovery hook fires. Return `true` if handled.
+	* @internal
+	*/
+	async _handleInternalFiberRecovery(_ctx) {
+		return false;
+	}
+	/** @internal Detect fibers left by a dead process (runFiber system). */
+	async _checkRunFibers() {
+		if (this._runFiberRecoveryInProgress) return;
+		this._runFiberRecoveryInProgress = true;
+		try {
+			const rows = this.sql`SELECT id, name, snapshot FROM cf_agents_runs`;
+			for (const row of rows) {
+				if (this._runFiberActiveFibers.has(row.id)) continue;
+				let snapshot = null;
+				if (row.snapshot) try {
+					snapshot = JSON.parse(row.snapshot);
+				} catch {
+					console.warn(`[Agent] Corrupted snapshot for fiber ${row.id}, treating as null`);
+				}
+				const ctx = {
+					id: row.id,
+					name: row.name,
+					snapshot
+				};
+				try {
+					if (!await this._handleInternalFiberRecovery(ctx)) await this.onFiberRecovered(ctx);
+				} catch (e) {
+					console.error(`[Agent] Fiber recovery failed for "${ctx.name}" (${ctx.id}):`, e);
+				}
+				this.sql`DELETE FROM cf_agents_runs WHERE id = ${row.id}`;
+			}
+		} finally {
+			this._runFiberRecoveryInProgress = false;
+		}
+	}
+	/** @internal */
+	async _onAlarmHousekeeping() {
+		await this._checkRunFibers();
+	}
+	async _scheduleNextAlarm() {
+		const nowMs = Date.now();
+		const hungCutoffSeconds = Math.floor(nowMs / 1e3) - this._resolvedOptions.hungScheduleTimeoutSeconds;
+		const readySchedules = this.sql`
+      SELECT time FROM cf_agents_schedules
+      WHERE type != 'interval'
+        OR running = 0
+        OR coalesce(execution_started_at, 0) <= ${hungCutoffSeconds}
+      ORDER BY time ASC
+      LIMIT 1
+    `;
+		const recoveringIntervals = this.sql`
+      SELECT execution_started_at FROM cf_agents_schedules
+      WHERE type = 'interval'
+        AND running = 1
+        AND coalesce(execution_started_at, 0) > ${hungCutoffSeconds}
+      ORDER BY execution_started_at ASC
+      LIMIT 1
+    `;
+		let nextTimeMs = null;
+		if (readySchedules.length > 0 && "time" in readySchedules[0]) nextTimeMs = Math.max(readySchedules[0].time * 1e3, nowMs + 1);
+		if (recoveringIntervals.length > 0 && recoveringIntervals[0].execution_started_at !== null) {
+			const recoveryTimeMs = (recoveringIntervals[0].execution_started_at + this._resolvedOptions.hungScheduleTimeoutSeconds) * 1e3;
+			nextTimeMs = nextTimeMs === null ? recoveryTimeMs : Math.min(nextTimeMs, recoveryTimeMs);
+		}
+		if (this._keepAliveRefs > 0) {
+			const keepAliveMs = nowMs + this._resolvedOptions.keepAliveIntervalMs;
+			nextTimeMs = nextTimeMs === null ? keepAliveMs : Math.min(nextTimeMs, keepAliveMs);
+		}
+		if (nextTimeMs !== null) await this.ctx.storage.setAlarm(nextTimeMs);
+		else await this.ctx.storage.deleteAlarm();
+	}
+	/**
+	* 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)) {
+			const DUPLICATE_SCHEDULE_THRESHOLD = 10;
+			const oneShotCounts = /* @__PURE__ */ new Map();
+			for (const row of result) if (row.type === "delayed" || row.type === "scheduled") oneShotCounts.set(row.callback, (oneShotCounts.get(row.callback) ?? 0) + 1);
+			for (const [cb, count] of oneShotCounts) if (count >= DUPLICATE_SCHEDULE_THRESHOLD) try {
+				console.warn(`Processing ${count} stale "${cb}" schedules in a single alarm cycle. This usually means schedule() is being called repeatedly without the idempotent option. Consider using scheduleEvery() for recurring tasks or passing { idempotent: true } to schedule().`);
+				this._emit("schedule:duplicate_warning", {
+					callback: cb,
+					count,
+					type: "one-shot"
+				});
+			} catch {}
+			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);
+					let parsedPayload;
+					try {
+						parsedPayload = JSON.parse(row.payload);
+					} catch (e) {
+						console.error(`Failed to parse payload for schedule "${row.id}" (callback "${row.callback}")`, e);
+						this._emit("schedule:error", {
+							callback: row.callback,
+							id: row.id,
+							error: e instanceof Error ? e.message : String(e),
+							attempts: 0
+						});
+						return;
+					}
+					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._onAlarmHousekeeping();
+		await this._scheduleNextAlarm();
+	}
+	/**
+	* Marks this agent as running inside a facet (sub-agent). Once set,
+	* scheduling methods throw a clear error instead of crashing on
+	* `setAlarm()` (which is not supported in facets).
+	* @internal
+	*/
+	async _cf_markAsFacet() {
+		this._isFacet = true;
+		await this.ctx.storage.put("cf_agents_is_facet", true);
+	}
+	/**
+	* Get or create a named sub-agent — a child Durable Object (facet)
+	* with its own isolated SQLite storage running on the same machine.
+	*
+	* The child class must extend `Agent` and be exported from the worker
+	* entry point. The first call for a given name triggers the child's
+	* `onStart()`. Subsequent calls return the existing instance.
+	*
+	* @experimental Requires the `"experimental"` compatibility flag.
+	*
+	* @param cls The Agent subclass (must be exported from the worker)
+	* @param name Unique name for this child instance
+	* @returns A typed RPC stub for calling methods on the child
+	*
+	* @example
+	* ```typescript
+	* const searcher = await this.subAgent(SearchAgent, "main-search");
+	* const results = await searcher.search("cloudflare agents");
+	* ```
+	*/
+	async subAgent(cls, name) {
+		const ctx = this.ctx;
+		if (!ctx.facets || !ctx.exports) throw new Error("subAgent() requires the \"experimental\" compatibility flag. Add it to your wrangler.jsonc compatibility_flags.");
+		if (!ctx.exports[cls.name]) throw new Error(`Sub-agent class "${cls.name}" not found in worker exports. Make sure the class is exported from your worker entry point and that the export name matches the class name.`);
+		const facetKey = `${cls.name}\0${name}`;
+		const stub = ctx.facets.get(facetKey, () => ({ class: ctx.exports[cls.name] }));
+		const req = new Request("http://dummy-example.cloudflare.com/cdn-cgi/partyserver/set-name/");
+		req.headers.set("x-partykit-room", name);
+		await stub.fetch(req).then((res) => res.text());
+		await stub._cf_markAsFacet();
+		return stub;
+	}
+	/**
+	* Forcefully abort a running sub-agent. The child stops executing
+	* immediately and will be restarted on next {@link subAgent} call.
+	* Pending RPC calls receive the reason as an error.
+	* Transitively aborts the child's own children.
+	*
+	* @experimental Requires the `"experimental"` compatibility flag.
+	*
+	* @param cls The Agent subclass used when creating the child
+	* @param name Name of the child to abort
+	* @param reason Error thrown to pending/future RPC callers
+	*/
+	abortSubAgent(cls, name, reason) {
+		const ctx = this.ctx;
+		if (!ctx.facets) throw new Error("abortSubAgent() requires the \"experimental\" compatibility flag.");
+		const facetKey = `${cls.name}\0${name}`;
+		ctx.facets.abort(facetKey, reason);
+	}
+	/**
+	* Delete a sub-agent: abort it if running, then permanently wipe its
+	* storage. Transitively deletes the child's own children.
+	*
+	* @experimental Requires the `"experimental"` compatibility flag.
+	*
+	* @param cls The Agent subclass used when creating the child
+	* @param name Name of the child to delete
+	*/
+	deleteSubAgent(cls, name) {
+		const ctx = this.ctx;
+		if (!ctx.facets) throw new Error("deleteSubAgent() requires the \"experimental\" compatibility flag.");
+		const facetKey = `${cls.name}\0${name}`;
+		ctx.facets.delete(facetKey);
+	}
+	/**
+	* Destroy the Agent, removing all state and scheduled tasks
+	*/
+	async destroy() {
+		this.sql`DROP TABLE IF EXISTS cf_agents_mcp_servers`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_state`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_schedules`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_queues`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_workflows`;
+		if (!this._isFacet) await this.ctx.storage.deleteAlarm();
+		await this.ctx.storage.deleteAll();
+		this._disposables.dispose();
+		await this.mcp.dispose();
+		this._destroyed = true;
+		setTimeout(() => {
+			this.ctx.abort("destroyed");
+		}, 0);
+		this._emit("destroy");
+	}
+	/**
+	* Check if a method is callable
+	* @param method The method name to check
+	* @returns True if the method is marked as callable
+	*/
+	_isCallable(method) {
+		return callableMetadata.has(this[method]);
+	}
+	/**
+	* Get all methods marked as callable on this Agent
+	* @returns A map of method names to their metadata
+	*/
+	getCallableMethods() {
+		const result = /* @__PURE__ */ new Map();
+		let prototype = Object.getPrototypeOf(this);
+		while (prototype && prototype !== Object.prototype) {
+			for (const name of Object.getOwnPropertyNames(prototype)) {
+				if (name === "constructor") continue;
+				if (result.has(name)) continue;
+				try {
+					const fn = prototype[name];
+					if (typeof fn === "function") {
+						const meta = callableMetadata.get(fn);
+						if (meta) result.set(name, meta);
+					}
+				} catch (e) {
+					if (!(e instanceof TypeError)) throw e;
+				}
+			}
+			prototype = Object.getPrototypeOf(prototype);
+		}
+		return result;
+	}
+	/**
+	* Start a workflow and track it in this Agent's database.
+	* Automatically injects agent identity into the workflow params.
+	*
+	* @template P - Type of params to pass to the workflow
+	* @param workflowName - Name of the workflow binding in env (e.g., 'MY_WORKFLOW')
+	* @param params - Params to pass to the workflow
+	* @param options - Optional workflow options
+	* @returns The workflow instance ID
+	*
+	* @example
+	* ```typescript
+	* const workflowId = await this.runWorkflow(
+	*   'MY_WORKFLOW',
+	*   { taskId: '123', data: 'process this' }
+	* );
+	* ```
+	*/
+	async runWorkflow(workflowName, params, options) {
+		const workflow = this._findWorkflowBindingByName(workflowName);
+		if (!workflow) throw new Error(`Workflow binding '${workflowName}' not found in environment`);
+		const agentBindingName = options?.agentBinding ?? this._findAgentBindingName();
+		if (!agentBindingName) throw new Error("Could not detect Agent binding name from class name. Pass it explicitly via options.agentBinding");
+		const workflowId = options?.id ?? nanoid();
+		const augmentedParams = {
+			...params,
+			__agentName: this.name,
+			__agentBinding: agentBindingName,
+			__workflowName: workflowName
+		};
+		const instance = await workflow.create({
+			id: workflowId,
+			params: augmentedParams
+		});
+		const id = nanoid();
+		const metadataJson = options?.metadata ? JSON.stringify(options.metadata) : null;
+		try {
+			this.sql`
+        INSERT INTO cf_agents_workflows (id, workflow_id, workflow_name, status, metadata)
+        VALUES (${id}, ${instance.id}, ${workflowName}, 'queued', ${metadataJson})
+      `;
+		} catch (e) {
+			if (e instanceof Error && e.message.includes("UNIQUE constraint failed")) throw new Error(`Workflow with ID "${workflowId}" is already being tracked`);
+			throw e;
+		}
+		this._emit("workflow:start", {
+			workflowId: instance.id,
+			workflowName
+		});
+		return instance.id;
+	}
+	/**
+	* Send an event to a running workflow.
+	* The workflow can wait for this event using step.waitForEvent().
+	*
+	* @param workflowName - Name of the workflow binding in env (e.g., 'MY_WORKFLOW')
+	* @param workflowId - ID of the workflow instance
+	* @param event - Event to send
+	*
+	* @example
+	* ```typescript
+	* await this.sendWorkflowEvent(
+	*   'MY_WORKFLOW',
+	*   workflowId,
+	*   { type: 'approval', payload: { approved: true } }
+	* );
+	* ```
+	*/
+	async sendWorkflowEvent(workflowName, workflowId, event) {
+		const workflow = this._findWorkflowBindingByName(workflowName);
+		if (!workflow) throw new Error(`Workflow binding '${workflowName}' not found in environment`);
+		const instance = await workflow.get(workflowId);
+		await tryN(3, async () => instance.sendEvent(event), {
+			shouldRetry: isErrorRetryable,
+			baseDelayMs: 200,
+			maxDelayMs: 3e3
+		});
+		this._emit("workflow:event", {
+			workflowId,
+			eventType: event.type
+		});
+	}
+	/**
+	* Approve a waiting workflow.
+	* Sends an approval event to the workflow that can be received by waitForApproval().
+	*
+	* @param workflowId - ID of the workflow to approve
+	* @param data - Optional approval data (reason, metadata)
+	*
+	* @example
+	* ```typescript
+	* await this.approveWorkflow(workflowId, {
+	*   reason: 'Approved by admin',
+	*   metadata: { approvedBy: userId }
+	* });
+	* ```
+	*/
+	async approveWorkflow(workflowId, data) {
+		const workflowInfo = this.getWorkflow(workflowId);
+		if (!workflowInfo) throw new Error(`Workflow ${workflowId} not found in tracking table`);
+		await this.sendWorkflowEvent(workflowInfo.workflowName, workflowId, {
+			type: "approval",
+			payload: {
+				approved: true,
+				reason: data?.reason,
+				metadata: data?.metadata
+			}
+		});
+		this._emit("workflow:approved", {
+			workflowId,
+			reason: data?.reason
+		});
+	}
+	/**
+	* Reject a waiting workflow.
+	* Sends a rejection event to the workflow that will cause waitForApproval() to throw.
+	*
+	* @param workflowId - ID of the workflow to reject
+	* @param data - Optional rejection data (reason)
+	*
+	* @example
+	* ```typescript
+	* await this.rejectWorkflow(workflowId, {
+	*   reason: 'Request denied by admin'
+	* });
+	* ```
+	*/
+	async rejectWorkflow(workflowId, data) {
+		const workflowInfo = this.getWorkflow(workflowId);
+		if (!workflowInfo) throw new Error(`Workflow ${workflowId} not found in tracking table`);
+		await this.sendWorkflowEvent(workflowInfo.workflowName, workflowId, {
+			type: "approval",
+			payload: {
+				approved: false,
+				reason: data?.reason
+			}
+		});
+		this._emit("workflow:rejected", {
+			workflowId,
+			reason: data?.reason
+		});
+	}
+	/**
+	* Terminate a running workflow.
+	* This immediately stops the workflow and sets its status to "terminated".
+	*
+	* @param workflowId - ID of the workflow to terminate (must be tracked via runWorkflow)
+	* @throws Error if workflow not found in tracking table
+	* @throws Error if workflow binding not found in environment
+	* @throws Error if workflow is already completed/errored/terminated (from Cloudflare)
+	*
+	* @example
+	* ```typescript
+	* await this.terminateWorkflow(workflowId);
+	* ```
+	*/
+	async terminateWorkflow(workflowId) {
+		const workflowInfo = this.getWorkflow(workflowId);
+		if (!workflowInfo) throw new Error(`Workflow ${workflowId} not found in tracking table`);
+		const workflow = this._findWorkflowBindingByName(workflowInfo.workflowName);
+		if (!workflow) throw new Error(`Workflow binding '${workflowInfo.workflowName}' not found in environment`);
+		const instance = await workflow.get(workflowId);
+		await tryN(3, async () => instance.terminate(), {
+			shouldRetry: isErrorRetryable,
+			baseDelayMs: 200,
+			maxDelayMs: 3e3
+		});
+		const status = await instance.status();
+		this._updateWorkflowTracking(workflowId, status);
+		this._emit("workflow:terminated", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
+	}
+	/**
+	* Pause a running workflow.
+	* The workflow can be resumed later with resumeWorkflow().
+	*
+	* @param workflowId - ID of the workflow to pause (must be tracked via runWorkflow)
+	* @throws Error if workflow not found in tracking table
+	* @throws Error if workflow binding not found in environment
+	* @throws Error if workflow is not running (from Cloudflare)
+	*
+	* @example
+	* ```typescript
+	* await this.pauseWorkflow(workflowId);
+	* ```
+	*/
+	async pauseWorkflow(workflowId) {
+		const workflowInfo = this.getWorkflow(workflowId);
+		if (!workflowInfo) throw new Error(`Workflow ${workflowId} not found in tracking table`);
+		const workflow = this._findWorkflowBindingByName(workflowInfo.workflowName);
+		if (!workflow) throw new Error(`Workflow binding '${workflowInfo.workflowName}' not found in environment`);
+		const instance = await workflow.get(workflowId);
+		await tryN(3, async () => instance.pause(), {
+			shouldRetry: isErrorRetryable,
+			baseDelayMs: 200,
+			maxDelayMs: 3e3
+		});
+		const status = await instance.status();
+		this._updateWorkflowTracking(workflowId, status);
+		this._emit("workflow:paused", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
+	}
+	/**
+	* Resume a paused workflow.
+	*
+	* @param workflowId - ID of the workflow to resume (must be tracked via runWorkflow)
+	* @throws Error if workflow not found in tracking table
+	* @throws Error if workflow binding not found in environment
+	* @throws Error if workflow is not paused (from Cloudflare)
+	*
+	* @example
+	* ```typescript
+	* await this.resumeWorkflow(workflowId);
+	* ```
+	*/
+	async resumeWorkflow(workflowId) {
+		const workflowInfo = this.getWorkflow(workflowId);
+		if (!workflowInfo) throw new Error(`Workflow ${workflowId} not found in tracking table`);
+		const workflow = this._findWorkflowBindingByName(workflowInfo.workflowName);
+		if (!workflow) throw new Error(`Workflow binding '${workflowInfo.workflowName}' not found in environment`);
+		const instance = await workflow.get(workflowId);
+		await tryN(3, async () => instance.resume(), {
+			shouldRetry: isErrorRetryable,
+			baseDelayMs: 200,
+			maxDelayMs: 3e3
+		});
+		const status = await instance.status();
+		this._updateWorkflowTracking(workflowId, status);
+		this._emit("workflow:resumed", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
+	}
+	/**
+	* Restart a workflow instance.
+	* This re-runs the workflow from the beginning with the same ID.
+	*
+	* @param workflowId - ID of the workflow to restart (must be tracked via runWorkflow)
+	* @param options - Optional settings
+	* @param options.resetTracking - If true (default), resets created_at and clears error fields.
+	*                                If false, preserves original timestamps.
+	* @throws Error if workflow not found in tracking table
+	* @throws Error if workflow binding not found in environment
+	*
+	* @example
+	* ```typescript
+	* // Reset tracking (default)
+	* await this.restartWorkflow(workflowId);
+	*
+	* // Preserve original timestamps
+	* await this.restartWorkflow(workflowId, { resetTracking: false });
+	* ```
+	*/
+	async restartWorkflow(workflowId, options = {}) {
+		const { resetTracking = true } = options;
+		const workflowInfo = this.getWorkflow(workflowId);
+		if (!workflowInfo) throw new Error(`Workflow ${workflowId} not found in tracking table`);
+		const workflow = this._findWorkflowBindingByName(workflowInfo.workflowName);
+		if (!workflow) throw new Error(`Workflow binding '${workflowInfo.workflowName}' not found in environment`);
+		const instance = await workflow.get(workflowId);
+		await tryN(3, async () => instance.restart(), {
+			shouldRetry: isErrorRetryable,
+			baseDelayMs: 200,
+			maxDelayMs: 3e3
+		});
+		if (resetTracking) {
+			const now = Math.floor(Date.now() / 1e3);
+			this.sql`
+        UPDATE cf_agents_workflows
+        SET status = 'queued',
+            created_at = ${now},
+            updated_at = ${now},
+            completed_at = NULL,
+            error_name = NULL,
+            error_message = NULL
+        WHERE workflow_id = ${workflowId}
+      `;
+		} else {
+			const status = await instance.status();
+			this._updateWorkflowTracking(workflowId, status);
+		}
+		this._emit("workflow:restarted", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
+	}
+	/**
+	* Find a workflow binding by its name.
+	*/
+	_findWorkflowBindingByName(workflowName) {
+		const binding = this.env[workflowName];
+		if (binding && typeof binding === "object" && "create" in binding && "get" in binding) return binding;
+	}
+	/**
+	* Get all workflow binding names from the environment.
+	*/
+	_getWorkflowBindingNames() {
+		const names = [];
+		for (const [key, value] of Object.entries(this.env)) if (value && typeof value === "object" && "create" in value && "get" in value) names.push(key);
+		return names;
+	}
+	/**
+	* Get the status of a workflow and update the tracking record.
+	*
+	* @param workflowName - Name of the workflow binding in env (e.g., 'MY_WORKFLOW')
+	* @param workflowId - ID of the workflow instance
+	* @returns The workflow status
+	*/
+	async getWorkflowStatus(workflowName, workflowId) {
+		const workflow = this._findWorkflowBindingByName(workflowName);
+		if (!workflow) throw new Error(`Workflow binding '${workflowName}' not found in environment`);
+		const status = await (await workflow.get(workflowId)).status();
+		this._updateWorkflowTracking(workflowId, status);
+		return status;
+	}
+	/**
+	* Get a tracked workflow by ID.
+	*
+	* @param workflowId - Workflow instance ID
+	* @returns Workflow info or undefined if not found
+	*/
+	getWorkflow(workflowId) {
+		const rows = this.sql`
+      SELECT * FROM cf_agents_workflows WHERE workflow_id = ${workflowId}
+    `;
+		if (!rows || rows.length === 0) return;
+		return this._rowToWorkflowInfo(rows[0]);
+	}
+	/**
+	* Query tracked workflows with cursor-based pagination.
+	*
+	* @param criteria - Query criteria including optional cursor for pagination
+	* @returns WorkflowPage with workflows, total count, and next cursor
+	*
+	* @example
+	* ```typescript
+	* // First page
+	* const page1 = this.getWorkflows({ status: 'running', limit: 20 });
+	*
+	* // Next page
+	* if (page1.nextCursor) {
+	*   const page2 = this.getWorkflows({
+	*     status: 'running',
+	*     limit: 20,
+	*     cursor: page1.nextCursor
+	*   });
+	* }
+	* ```
+	*/
+	getWorkflows(criteria = {}) {
+		const limit = Math.min(criteria.limit ?? 50, 100);
+		const isAsc = criteria.orderBy === "asc";
+		const total = this._countWorkflows(criteria);
+		let query = "SELECT * FROM cf_agents_workflows WHERE 1=1";
+		const params = [];
+		if (criteria.status) {
+			const statuses = Array.isArray(criteria.status) ? criteria.status : [criteria.status];
+			const placeholders = statuses.map(() => "?").join(", ");
+			query += ` AND status IN (${placeholders})`;
+			params.push(...statuses);
+		}
+		if (criteria.workflowName) {
+			query += " AND workflow_name = ?";
+			params.push(criteria.workflowName);
+		}
+		if (criteria.metadata) for (const [key, value] of Object.entries(criteria.metadata)) {
+			query += ` AND json_extract(metadata, '$.' || ?) = ?`;
+			params.push(key, value);
+		}
+		if (criteria.cursor) {
+			const cursor = this._decodeCursor(criteria.cursor);
+			if (isAsc) query += " AND (created_at > ? OR (created_at = ? AND workflow_id > ?))";
+			else query += " AND (created_at < ? OR (created_at = ? AND workflow_id < ?))";
+			params.push(cursor.createdAt, cursor.createdAt, cursor.workflowId);
+		}
+		query += ` ORDER BY created_at ${isAsc ? "ASC" : "DESC"}, workflow_id ${isAsc ? "ASC" : "DESC"}`;
+		query += " LIMIT ?";
+		params.push(limit + 1);
+		const rows = this.ctx.storage.sql.exec(query, ...params).toArray();
+		const hasMore = rows.length > limit;
+		const workflows = (hasMore ? rows.slice(0, limit) : rows).map((row) => this._rowToWorkflowInfo(row));
+		return {
+			workflows,
+			total,
+			nextCursor: hasMore && workflows.length > 0 ? this._encodeCursor(workflows[workflows.length - 1]) : null
+		};
+	}
+	/**
+	* Count workflows matching criteria (for pagination total).
+	*/
+	_countWorkflows(criteria) {
+		let query = "SELECT COUNT(*) as count FROM cf_agents_workflows WHERE 1=1";
+		const params = [];
+		if (criteria.status) {
+			const statuses = Array.isArray(criteria.status) ? criteria.status : [criteria.status];
+			const placeholders = statuses.map(() => "?").join(", ");
+			query += ` AND status IN (${placeholders})`;
+			params.push(...statuses);
+		}
+		if (criteria.workflowName) {
+			query += " AND workflow_name = ?";
+			params.push(criteria.workflowName);
+		}
+		if (criteria.metadata) for (const [key, value] of Object.entries(criteria.metadata)) {
+			query += ` AND json_extract(metadata, '$.' || ?) = ?`;
+			params.push(key, value);
+		}
+		if (criteria.createdBefore) {
+			query += " AND created_at < ?";
+			params.push(Math.floor(criteria.createdBefore.getTime() / 1e3));
+		}
+		return this.ctx.storage.sql.exec(query, ...params).toArray()[0]?.count ?? 0;
+	}
+	/**
+	* Encode a cursor from workflow info for pagination.
+	* Stores createdAt as Unix timestamp in seconds (matching DB storage).
+	*/
+	_encodeCursor(workflow) {
+		return btoa(JSON.stringify({
+			c: Math.floor(workflow.createdAt.getTime() / 1e3),
+			i: workflow.workflowId
+		}));
+	}
+	/**
+	* Decode a pagination cursor.
+	* Returns createdAt as Unix timestamp in seconds (matching DB storage).
+	*/
+	_decodeCursor(cursor) {
+		try {
+			const data = JSON.parse(atob(cursor));
+			if (typeof data.c !== "number" || typeof data.i !== "string") throw new Error("Invalid cursor structure");
+			return {
+				createdAt: data.c,
+				workflowId: data.i
+			};
+		} catch {
+			throw new Error("Invalid pagination cursor. The cursor may be malformed or corrupted.");
+		}
+	}
+	/**
+	* Delete a workflow tracking record.
+	*
+	* @param workflowId - ID of the workflow to delete
+	* @returns true if a record was deleted, false if not found
+	*/
+	deleteWorkflow(workflowId) {
+		const existing = this.sql`
+      SELECT COUNT(*) as count FROM cf_agents_workflows WHERE workflow_id = ${workflowId}
+    `;
+		if (!existing[0] || existing[0].count === 0) return false;
+		this.sql`DELETE FROM cf_agents_workflows WHERE workflow_id = ${workflowId}`;
+		return true;
+	}
+	/**
+	* Delete workflow tracking records matching criteria.
+	* Useful for cleaning up old completed/errored workflows.
+	*
+	* @param criteria - Criteria for which workflows to delete
+	* @returns Number of records matching criteria (expected deleted count)
+	*
+	* @example
+	* ```typescript
+	* // Delete all completed workflows created more than 7 days ago
+	* const deleted = this.deleteWorkflows({
+	*   status: 'complete',
+	*   createdBefore: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
+	* });
+	*
+	* // Delete all errored and terminated workflows
+	* const deleted = this.deleteWorkflows({
+	*   status: ['errored', 'terminated']
+	* });
+	* ```
+	*/
+	deleteWorkflows(criteria = {}) {
+		let query = "DELETE FROM cf_agents_workflows WHERE 1=1";
+		const params = [];
+		if (criteria.status) {
+			const statuses = Array.isArray(criteria.status) ? criteria.status : [criteria.status];
+			const placeholders = statuses.map(() => "?").join(", ");
+			query += ` AND status IN (${placeholders})`;
+			params.push(...statuses);
+		}
+		if (criteria.workflowName) {
+			query += " AND workflow_name = ?";
+			params.push(criteria.workflowName);
+		}
+		if (criteria.metadata) for (const [key, value] of Object.entries(criteria.metadata)) {
+			query += ` AND json_extract(metadata, '$.' || ?) = ?`;
+			params.push(key, value);
+		}
+		if (criteria.createdBefore) {
+			query += " AND created_at < ?";
+			params.push(Math.floor(criteria.createdBefore.getTime() / 1e3));
+		}
+		return this.ctx.storage.sql.exec(query, ...params).rowsWritten;
+	}
+	/**
+	* Migrate workflow tracking records from an old binding name to a new one.
+	* Use this after renaming a workflow binding in wrangler.toml.
+	*
+	* @param oldName - Previous workflow binding name
+	* @param newName - New workflow binding name
+	* @returns Number of records migrated
+	*
+	* @example
+	* ```typescript
+	* // After renaming OLD_WORKFLOW to NEW_WORKFLOW in wrangler.toml
+	* async onStart() {
+	*   const migrated = this.migrateWorkflowBinding('OLD_WORKFLOW', 'NEW_WORKFLOW');
+	* }
+	* ```
+	*/
+	migrateWorkflowBinding(oldName, newName) {
+		if (!this._findWorkflowBindingByName(newName)) throw new Error(`Workflow binding '${newName}' not found in environment`);
+		const count = this.sql`
+      SELECT COUNT(*) as count FROM cf_agents_workflows WHERE workflow_name = ${oldName}
+    `[0]?.count ?? 0;
+		if (count > 0) {
+			this.sql`UPDATE cf_agents_workflows SET workflow_name = ${newName} WHERE workflow_name = ${oldName}`;
+			console.log(`[Agent] Migrated ${count} workflow(s) from '${oldName}' to '${newName}'`);
+		}
+		return count;
+	}
+	/**
+	* Update workflow tracking record from InstanceStatus
+	*/
+	_updateWorkflowTracking(workflowId, status) {
+		const statusName = status.status;
+		const now = Math.floor(Date.now() / 1e3);
+		const completedAt = [
+			"complete",
+			"errored",
+			"terminated"
+		].includes(statusName) ? now : null;
+		const errorName = status.error?.name ?? null;
+		const errorMessage = status.error?.message ?? null;
+		this.sql`
+      UPDATE cf_agents_workflows
+      SET status = ${statusName},
+          error_name = ${errorName},
+          error_message = ${errorMessage},
+          updated_at = ${now},
+          completed_at = ${completedAt}
+      WHERE workflow_id = ${workflowId}
+    `;
+	}
+	/**
+	* Convert a database row to WorkflowInfo
+	*/
+	_rowToWorkflowInfo(row) {
+		return {
+			id: row.id,
+			workflowId: row.workflow_id,
+			workflowName: row.workflow_name,
+			status: row.status,
+			metadata: row.metadata ? JSON.parse(row.metadata) : null,
+			error: row.error_name ? {
+				name: row.error_name,
+				message: row.error_message ?? ""
+			} : null,
+			createdAt: /* @__PURE__ */ new Date(row.created_at * 1e3),
+			updatedAt: /* @__PURE__ */ new Date(row.updated_at * 1e3),
+			completedAt: row.completed_at ? /* @__PURE__ */ new Date(row.completed_at * 1e3) : null
+		};
+	}
+	/**
+	* Find the binding name for this Agent's namespace by matching class name.
+	* Returns undefined if no match found - use options.agentBinding as fallback.
+	*/
+	_findAgentBindingName() {
+		const className = this._ParentClass.name;
+		for (const [key, value] of Object.entries(this.env)) if (value && typeof value === "object" && "idFromName" in value && typeof value.idFromName === "function") {
+			if (key === className || camelCaseToKebabCase(key) === camelCaseToKebabCase(className)) return key;
+		}
+	}
+	_findBindingNameForNamespace(namespace) {
+		for (const [key, value] of Object.entries(this.env)) if (value === namespace) return key;
+	}
+	async _restoreRpcMcpServers() {
+		const rpcServers = this.mcp.getRpcServersFromStorage();
+		for (const server of rpcServers) {
+			if (this.mcp.mcpConnections[server.id]) continue;
+			const opts = server.server_options ? JSON.parse(server.server_options) : {};
+			const namespace = this.env[opts.bindingName];
+			if (!namespace) {
+				console.warn(`[Agent] Cannot restore RPC MCP server "${server.name}": binding "${opts.bindingName}" not found in env`);
+				continue;
+			}
+			const normalizedName = server.server_url.replace(RPC_DO_PREFIX, "");
+			try {
+				await this.mcp.connect(`${RPC_DO_PREFIX}${normalizedName}`, {
+					reconnect: { id: server.id },
+					transport: {
+						type: "rpc",
+						namespace,
+						name: normalizedName,
+						props: opts.props
+					}
+				});
+				const conn = this.mcp.mcpConnections[server.id];
+				if (conn && conn.connectionState === MCPConnectionState.CONNECTED) await this.mcp.discoverIfConnected(server.id);
+			} catch (error) {
+				console.error(`[Agent] Error restoring RPC MCP server "${server.name}":`, error);
+			}
+		}
+	}
+	/**
+	* Handle a callback from a workflow.
+	* Called when the Agent receives a callback at /_workflow/callback.
+	* Override this to handle all callback types in one place.
+	*
+	* @param callback - The callback payload
+	*/
+	async onWorkflowCallback(callback) {
+		const now = Math.floor(Date.now() / 1e3);
+		switch (callback.type) {
+			case "progress":
+				this.sql`
+          UPDATE cf_agents_workflows
+          SET status = 'running', updated_at = ${now}
+          WHERE workflow_id = ${callback.workflowId} AND status IN ('queued', 'waiting')
+        `;
+				await this.onWorkflowProgress(callback.workflowName, callback.workflowId, callback.progress);
+				break;
+			case "complete":
+				this.sql`
+          UPDATE cf_agents_workflows
+          SET status = 'complete', updated_at = ${now}, completed_at = ${now}
+          WHERE workflow_id = ${callback.workflowId}
+            AND status NOT IN ('terminated', 'paused')
+        `;
+				await this.onWorkflowComplete(callback.workflowName, callback.workflowId, callback.result);
+				break;
+			case "error":
+				this.sql`
+          UPDATE cf_agents_workflows
+          SET status = 'errored', updated_at = ${now}, completed_at = ${now},
+              error_name = 'WorkflowError', error_message = ${callback.error}
+          WHERE workflow_id = ${callback.workflowId}
+            AND status NOT IN ('terminated', 'paused')
+        `;
+				await this.onWorkflowError(callback.workflowName, callback.workflowId, callback.error);
+				break;
+			case "event":
+				await this.onWorkflowEvent(callback.workflowName, callback.workflowId, callback.event);
+				break;
+		}
+	}
+	/**
+	* Called when a workflow reports progress.
+	* Override to handle progress updates.
+	*
+	* @param workflowName - Workflow binding name
+	* @param workflowId - ID of the workflow
+	* @param progress - Typed progress data (default: DefaultProgress)
+	*/
+	async onWorkflowProgress(workflowName, workflowId, progress) {}
+	/**
+	* Called when a workflow completes successfully.
+	* Override to handle completion.
+	*
+	* @param workflowName - Workflow binding name
+	* @param workflowId - ID of the workflow
+	* @param result - Optional result data
+	*/
+	async onWorkflowComplete(workflowName, workflowId, result) {}
+	/**
+	* Called when a workflow encounters an error.
+	* Override to handle errors.
+	*
+	* @param workflowName - Workflow binding name
+	* @param workflowId - ID of the workflow
+	* @param error - Error message
+	*/
+	async onWorkflowError(workflowName, workflowId, error) {
+		console.error(`Workflow error [${workflowName}/${workflowId}]: ${error}\nOverride onWorkflowError() in your Agent to handle workflow errors.`);
+	}
+	/**
+	* Called when a workflow sends a custom event.
+	* Override to handle custom events.
+	*
+	* @param workflowName - Workflow binding name
+	* @param workflowId - ID of the workflow
+	* @param event - Custom event payload
+	*/
+	async onWorkflowEvent(workflowName, workflowId, event) {}
+	/**
+	* Handle a workflow callback via RPC.
+	* @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
+	*/
+	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
+	*/
+	async _workflow_updateState(action, state) {
+		await this.__unsafe_ensureInitialized();
+		if (action === "set") this.setState(state);
+		else if (action === "merge") {
+			const currentState = this.state ?? {};
+			this.setState({
+				...currentState,
+				...state
+			});
+		} else if (action === "reset") this.setState(this.initialState);
+	}
+	async addMcpServer(serverName, urlOrBinding, callbackHostOrOptions, agentsPrefix, options) {
+		const isHttpTransport = typeof urlOrBinding === "string";
+		const normalizedUrl = isHttpTransport ? new URL(urlOrBinding).href : void 0;
+		const existingServer = this.mcp.listServers().find((s) => s.name === serverName && (!isHttpTransport || new URL(s.server_url).href === normalizedUrl));
+		if (existingServer && this.mcp.mcpConnections[existingServer.id]) {
+			const conn = this.mcp.mcpConnections[existingServer.id];
+			if (conn.connectionState === MCPConnectionState.AUTHENTICATING && conn.options.transport.authProvider?.authUrl) return {
+				id: existingServer.id,
+				state: MCPConnectionState.AUTHENTICATING,
+				authUrl: conn.options.transport.authProvider.authUrl
+			};
+			if (conn.connectionState === MCPConnectionState.FAILED) throw new Error(`MCP server "${serverName}" is in failed state: ${conn.connectionError}`);
+			return {
+				id: existingServer.id,
+				state: MCPConnectionState.READY
+			};
+		}
+		if (typeof urlOrBinding !== "string") {
+			const rpcOpts = callbackHostOrOptions;
+			const normalizedName = serverName.toLowerCase().replace(/\s+/g, "-");
+			const reconnectId = existingServer?.id;
+			const { id } = await this.mcp.connect(`${RPC_DO_PREFIX}${normalizedName}`, {
+				reconnect: reconnectId ? { id: reconnectId } : void 0,
+				transport: {
+					type: "rpc",
+					namespace: urlOrBinding,
+					name: normalizedName,
+					props: rpcOpts?.props
+				}
+			});
+			const conn = this.mcp.mcpConnections[id];
+			if (conn && conn.connectionState === MCPConnectionState.CONNECTED) {
+				const discoverResult = await this.mcp.discoverIfConnected(id);
+				if (discoverResult && !discoverResult.success) throw new Error(`Failed to discover MCP server capabilities: ${discoverResult.error}`);
+			} else if (conn && conn.connectionState === MCPConnectionState.FAILED) throw new Error(`Failed to connect to MCP server "${serverName}" via RPC: ${conn.connectionError}`);
+			const bindingName = this._findBindingNameForNamespace(urlOrBinding);
+			if (bindingName) this.mcp.saveRpcServerToStorage(id, serverName, normalizedName, bindingName, rpcOpts?.props);
+			return {
+				id,
+				state: MCPConnectionState.READY
+			};
+		}
+		const httpOptions = callbackHostOrOptions;
+		let resolvedCallbackHost;
+		let resolvedAgentsPrefix;
+		let resolvedOptions;
+		let resolvedCallbackPath;
+		if (typeof httpOptions === "object" && httpOptions !== null) {
+			resolvedCallbackHost = httpOptions.callbackHost;
+			resolvedCallbackPath = httpOptions.callbackPath;
+			resolvedAgentsPrefix = httpOptions.agentsPrefix ?? "agents";
+			resolvedOptions = {
+				client: httpOptions.client,
+				transport: httpOptions.transport,
+				retry: httpOptions.retry
+			};
+		} else {
+			resolvedCallbackHost = httpOptions;
+			resolvedAgentsPrefix = agentsPrefix ?? "agents";
+			resolvedOptions = options;
+		}
+		if (!this._resolvedOptions.sendIdentityOnConnect && resolvedCallbackHost && !resolvedCallbackPath) throw new Error("callbackPath is required in addMcpServer options when sendIdentityOnConnect is false — the default callback URL would expose the instance name. Provide a callbackPath and route the callback request to this agent via getAgentByName.");
+		if (!resolvedCallbackHost) {
+			const { request, connection } = getCurrentAgent();
+			if (request) {
+				const requestUrl = new URL(request.url);
+				resolvedCallbackHost = `${requestUrl.protocol}//${requestUrl.host}`;
+			} else if (connection?.uri) {
+				const connectionUrl = new URL(connection.uri);
+				resolvedCallbackHost = `${connectionUrl.protocol}//${connectionUrl.host}`;
+			}
+		}
+		let callbackUrl;
+		if (resolvedCallbackHost) {
+			const normalizedHost = resolvedCallbackHost.replace(/\/$/, "");
+			callbackUrl = resolvedCallbackPath ? `${normalizedHost}/${resolvedCallbackPath.replace(/^\//, "")}` : `${normalizedHost}/${resolvedAgentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
+		}
+		const id = nanoid(8);
+		let authProvider;
+		if (callbackUrl) {
+			authProvider = this.createMcpOAuthProvider(callbackUrl);
+			authProvider.serverId = id;
+		}
+		const transportType = resolvedOptions?.transport?.type ?? "auto";
+		let headerTransportOpts = {};
+		if (resolvedOptions?.transport?.headers) headerTransportOpts = {
+			eventSourceInit: { fetch: (url, init) => fetch(url, {
+				...init,
+				headers: resolvedOptions?.transport?.headers
+			}) },
+			requestInit: { headers: resolvedOptions?.transport?.headers }
+		};
+		await this.mcp.registerServer(id, {
+			url: normalizedUrl,
+			name: serverName,
+			callbackUrl,
+			client: resolvedOptions?.client,
+			transport: {
+				...headerTransportOpts,
+				authProvider,
+				type: transportType
+			},
+			retry: resolvedOptions?.retry
+		});
+		const result = await this.mcp.connectToServer(id);
+		if (result.state === MCPConnectionState.FAILED) throw new Error(`Failed to connect to MCP server at ${normalizedUrl}: ${result.error}`);
+		if (result.state === MCPConnectionState.AUTHENTICATING) {
+			if (!callbackUrl) throw new Error("This MCP server requires OAuth authentication. Provide callbackHost in addMcpServer options to enable the OAuth flow.");
+			return {
+				id,
+				state: result.state,
+				authUrl: result.authUrl
+			};
+		}
+		const discoverResult = await this.mcp.discoverIfConnected(id);
+		if (discoverResult && !discoverResult.success) throw new Error(`Failed to discover MCP server capabilities: ${discoverResult.error}`);
+		return {
+			id,
+			state: MCPConnectionState.READY
+		};
+	}
+	async removeMcpServer(id) {
+		await this.mcp.removeServer(id);
+	}
+	getMcpServers() {
+		const mcpState = {
+			prompts: this.mcp.listPrompts(),
+			resources: this.mcp.listResources(),
+			servers: {},
+			tools: this.mcp.listTools()
+		};
+		const servers = this.mcp.listServers();
+		if (servers && Array.isArray(servers) && servers.length > 0) for (const server of servers) {
+			const serverConn = this.mcp.mcpConnections[server.id];
+			let defaultState = "not-connected";
+			if (!serverConn && server.auth_url) defaultState = "authenticating";
+			mcpState.servers[server.id] = {
+				auth_url: server.auth_url,
+				capabilities: serverConn?.serverCapabilities ?? null,
+				error: sanitizeErrorString(serverConn?.connectionError ?? null),
+				instructions: serverConn?.instructions ?? null,
+				name: server.name,
+				server_url: server.server_url,
+				state: serverConn?.connectionState ?? defaultState
+			};
+		}
+		return mcpState;
+	}
+	/**
+	* Create the OAuth provider used when connecting to MCP servers that require authentication.
+	*
+	* Override this method in a subclass to supply a custom OAuth provider implementation,
+	* for example to use pre-registered client credentials, mTLS-based authentication,
+	* or any other OAuth flow beyond dynamic client registration.
+	*
+	* @example
+	* // Custom OAuth provider
+	* class MyAgent extends Agent {
+	*   createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider {
+	*     return new MyCustomOAuthProvider(
+	*       this.ctx.storage,
+	*       this.name,
+	*       callbackUrl
+	*     );
+	*   }
+	* }
+	*
+	* @param callbackUrl The OAuth callback URL for the authorization flow
+	* @returns An {@link AgentMcpOAuthProvider} instance used by {@link addMcpServer}
+	*/
+	createMcpOAuthProvider(callbackUrl) {
+		return new DurableObjectOAuthClientProvider(this.ctx.storage, this.name, callbackUrl);
+	}
+	broadcastMcpServers() {
+		this._broadcastProtocol(JSON.stringify({
+			mcp: this.getMcpServers(),
+			type: MessageType.CF_AGENT_MCP_SERVERS
+		}));
+	}
+	/**
+	* Handle MCP OAuth callback request if it's an OAuth callback.
+	*
+	* This method encapsulates the entire OAuth callback flow:
+	* 1. Checks if the request is an MCP OAuth callback
+	* 2. Processes the OAuth code exchange
+	* 3. Establishes the connection if successful
+	* 4. Broadcasts MCP server state updates
+	* 5. Returns the appropriate HTTP response
+	*
+	* @param request The incoming HTTP request
+	* @returns Response if this was an OAuth callback, null otherwise
+	*/
+	async handleMcpOAuthCallback(request) {
+		if (!this.mcp.isCallbackRequest(request)) return null;
+		const result = await this.mcp.handleCallbackRequest(request);
+		if (result.authSuccess) this.mcp.establishConnection(result.serverId).catch((error) => {
+			console.error("[Agent handleMcpOAuthCallback] Connection establishment failed:", error);
+		});
+		this.broadcastMcpServers();
+		return this.handleOAuthCallbackResponse(result, request);
+	}
+	/**
+	* Handle OAuth callback response using MCPClientManager configuration
+	* @param result OAuth callback result
+	* @param request The original request (needed for base URL)
+	* @returns Response for the OAuth callback
+	*/
+	handleOAuthCallbackResponse(result, request) {
+		const config = this.mcp.getOAuthCallbackConfig();
+		if (config?.customHandler) return config.customHandler(result);
+		const baseOrigin = new URL(request.url).origin;
+		if (config?.successRedirect && result.authSuccess) try {
+			return Response.redirect(new URL(config.successRedirect, baseOrigin).href);
+		} catch (e) {
+			console.error("Invalid successRedirect URL:", config.successRedirect, e);
+			return Response.redirect(baseOrigin);
+		}
+		if (config?.errorRedirect && !result.authSuccess) try {
+			const errorUrl = `${config.errorRedirect}?error=${encodeURIComponent(result.authError || "Unknown error")}`;
+			return Response.redirect(new URL(errorUrl, baseOrigin).href);
+		} catch (e) {
+			console.error("Invalid errorRedirect URL:", config.errorRedirect, e);
+			return Response.redirect(baseOrigin);
+		}
+		return Response.redirect(baseOrigin);
+	}
+};
+Agent.options = { hibernate: true };
+const wrappedClasses = /* @__PURE__ */ new Set();
+/**
+* Route a request to the appropriate Agent
+* @param request Request to route
+* @param env Environment containing Agent bindings
+* @param options Routing options
+* @returns Response from the Agent or undefined if no route matched
+*/
+async function routeAgentRequest(request, env, options) {
+	return routePartykitRequest(request, env, {
+		prefix: "agents",
+		...options
+	});
+}
+var _email = /* @__PURE__ */ new WeakMap();
+_Symbol$dispose = Symbol.dispose;
+var EmailBridge = class extends RpcTarget {
+	constructor(email) {
+		super();
+		_classPrivateFieldInitSpec(this, _email, void 0);
+		_classPrivateFieldSet2(_email, this, email);
+	}
+	async getRaw() {
+		const reader = _classPrivateFieldGet2(_email, this).raw.getReader();
+		const chunks = [];
+		let done = false;
+		while (!done) {
+			const { value, done: readerDone } = await reader.read();
+			done = readerDone;
+			if (value) chunks.push(value);
+		}
+		const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+		const combined = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const chunk of chunks) {
+			combined.set(chunk, offset);
+			offset += chunk.length;
+		}
+		return combined;
+	}
+	setReject(reason) {
+		_classPrivateFieldGet2(_email, this).setReject(reason);
+	}
+	forward(rcptTo, headers) {
+		return _classPrivateFieldGet2(_email, this).forward(rcptTo, headers);
+	}
+	reply(options) {
+		return _classPrivateFieldGet2(_email, this).reply(new EmailMessage(options.from, options.to, options.raw));
+	}
+	[_Symbol$dispose]() {}
+};
+const agentMapCache = /* @__PURE__ */ new WeakMap();
+/**
+* Route an email to the appropriate Agent
+* @param email The email to route
+* @param env The environment containing the Agent bindings
+* @param options The options for routing the email
+* @returns A promise that resolves when the email has been routed
+*/
+async function routeAgentEmail(email, env, options) {
+	const routingInfo = await options.resolver(email, env);
+	if (!routingInfo) {
+		if (options.onNoRoute) await options.onNoRoute(email);
+		else console.warn("No routing information found for email, dropping message");
+		return;
+	}
+	if (!agentMapCache.has(env)) {
+		const map = {};
+		const originalNames = [];
+		for (const [key, value] of Object.entries(env)) if (value && typeof value === "object" && "idFromName" in value && typeof value.idFromName === "function") {
+			map[key] = value;
+			map[camelCaseToKebabCase(key)] = value;
+			map[key.toLowerCase()] = value;
+			originalNames.push(key);
+		}
+		agentMapCache.set(env, {
+			map,
+			originalNames
+		});
+	}
+	const cached = agentMapCache.get(env);
+	const namespace = cached.map[routingInfo.agentName];
+	if (!namespace) {
+		const availableAgents = cached.originalNames.join(", ");
+		throw new Error(`Agent namespace '${routingInfo.agentName}' not found in environment. Available agents: ${availableAgents}`);
+	}
+	const agent = await getAgentByName(namespace, routingInfo.agentId);
+	const bridge = new EmailBridge(email);
+	await agent._onEmail({
+		from: email.from,
+		to: email.to,
+		headers: email.headers,
+		rawSize: email.rawSize,
+		_secureRouted: routingInfo._secureRouted,
+		_bridge: bridge
+	});
+}
+/**
+* Get or create an Agent by name
+* @template Env Environment type containing bindings
+* @template T Type of the Agent class
+* @param namespace Agent namespace
+* @param name Name of the Agent instance
+* @param options Options for Agent creation
+* @returns Promise resolving to an Agent instance stub
+*/
+async function getAgentByName(namespace, name, options) {
+	return getServerByName(namespace, name, options);
+}
+/**
+* A wrapper for streaming responses in callable methods
+*/
+var StreamingResponse = class {
+	constructor(connection, id) {
+		this._closed = false;
+		this._connection = connection;
+		this._id = id;
+	}
+	/**
+	* Whether the stream has been closed (via end() or error())
+	*/
+	get isClosed() {
+		return this._closed;
+	}
+	/**
+	* Send a chunk of data to the client
+	* @param chunk The data to send
+	* @returns false if stream is already closed (no-op), true if sent
+	*/
+	send(chunk) {
+		if (this._closed) {
+			console.warn("StreamingResponse.send() called after stream was closed - data not sent");
+			return false;
+		}
+		const response = {
+			done: false,
+			id: this._id,
+			result: chunk,
+			success: true,
+			type: MessageType.RPC
+		};
+		this._connection.send(JSON.stringify(response));
+		return true;
+	}
+	/**
+	* End the stream and send the final chunk (if any)
+	* @param finalChunk Optional final chunk of data to send
+	* @returns false if stream is already closed (no-op), true if sent
+	*/
+	end(finalChunk) {
+		if (this._closed) return false;
+		this._closed = true;
+		const response = {
+			done: true,
+			id: this._id,
+			result: finalChunk,
+			success: true,
+			type: MessageType.RPC
+		};
+		this._connection.send(JSON.stringify(response));
+		return true;
+	}
+	/**
+	* Send an error to the client and close the stream
+	* @param message Error message to send
+	* @returns false if stream is already closed (no-op), true if sent
+	*/
+	error(message) {
+		if (this._closed) return false;
+		this._closed = true;
+		const response = {
+			error: message,
+			id: this._id,
+			success: false,
+			type: MessageType.RPC
+		};
+		this._connection.send(JSON.stringify(response));
+		return true;
+	}
+};
+//#endregion
 export { Agent, DEFAULT_AGENT_STATIC_OPTIONS, DurableObjectOAuthClientProvider, MessageType, SqlError, StreamingResponse, __DO_NOT_USE_WILL_BREAK__agentContext, callable, createHeaderBasedEmailResolver, getAgentByName, getCurrentAgent, routeAgentEmail, routeAgentRequest, unstable_callable };
+
+//# sourceMappingURL=index.js.map