agents 0.7.5 → 0.7.6

package/dist/index.js

@@ -3,7 +3,7 @@ import { camelCaseToKebabCase } from "./utils.js";
 import { createHeaderBasedEmailResolver, signAgentHeaders } from "./email.js";
 import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.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-CgXIwdcc.js";
+import { o as RPC_DO_PREFIX, r as MCPConnectionState, s as DisposableStore, t as MCPClientManager } from "./client-K8Z-u76l.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider.js";
 import { genericObservability } from "./observability/index.js";
 import { parseCronExpression } from "cron-schedule";
@@ -65,6 +65,14 @@ function getNextCronTime(cron) {
 	return parseCronExpression(cron).getNextDate();
 }
 const 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 = 1;
+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 = {};
@@ -83,7 +91,11 @@ 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]);
+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;
@@ -205,14 +217,11 @@ var Agent = class Agent extends Server {
 	*/
 	get state() {
 		if (this._state !== DEFAULT_STATE) return this._state;
-		const wasChanged = this.sql`
-        SELECT state FROM cf_agents_state WHERE id = ${STATE_WAS_CHANGED}
-      `;
 		const result = this.sql`
       SELECT state FROM cf_agents_state WHERE id = ${STATE_ROW_ID}
     `;
-		if (wasChanged[0]?.state === "true" || result[0]?.state) {
-			const state = result[0]?.state;
+		if (result.length > 0) {
+			const state = result[0].state;
 			try {
 				this._state = JSON.parse(state);
 			} catch (e) {
@@ -222,7 +231,6 @@ var Agent = class Agent extends Server {
 					this._setStateInternal(this.initialState);
 				} else {
 					this.sql`DELETE FROM cf_agents_state WHERE id = ${STATE_ROW_ID}`;
-					this.sql`DELETE FROM cf_agents_state WHERE id = ${STATE_WAS_CHANGED}`;
 					return;
 				}
 			}
@@ -232,9 +240,6 @@ var Agent = class Agent extends Server {
 		this._setStateInternal(this.initialState);
 		return this.initialState;
 	}
-	static {
-		this.options = { hibernate: true };
-	}
 	get _resolvedOptions() {
 		if (this._cachedOptions) return this._cachedOptions;
 		const ctor = this.constructor;
@@ -280,6 +285,138 @@ var Agent = class Agent extends Server {
 			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}
+    `;
+		if ((versionRow.length > 0 ? Number(versionRow[0].state) : 0) < 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);
+			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;
@@ -287,6 +424,7 @@ var Agent = class Agent extends Server {
 		this._destroyed = false;
 		this._rawStateAccessors = /* @__PURE__ */ new WeakMap();
 		this._persistenceHookMode = "none";
+		this._isFacet = false;
 		this._ParentClass = Object.getPrototypeOf(this).constructor;
 		this.initialState = DEFAULT_STATE;
 		this.observability = genericObservability;
@@ -295,117 +433,7 @@ var Agent = class Agent extends Server {
 			this._autoWrapCustomMethods();
 			wrappedClasses.add(this.constructor);
 		}
-		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_state (
-        id TEXT PRIMARY KEY NOT NULL,
-        state 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._ensureSchema();
 		this.mcp = new MCPClientManager(this._ParentClass.name, "0.0.1", {
 			storage: this.ctx.storage,
 			createAuthProvider: (callbackUrl) => this.createMcpOAuthProvider(callbackUrl)
@@ -605,6 +633,7 @@ var Agent = class Agent extends Server {
 				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();
@@ -655,10 +684,6 @@ var Agent = class Agent extends Server {
 		this.sql`
       INSERT OR REPLACE INTO cf_agents_state (id, state)
       VALUES (${STATE_ROW_ID}, ${JSON.stringify(nextState)})
-    `;
-		this.sql`
-      INSERT OR REPLACE INTO cf_agents_state (id, state)
-      VALUES (${STATE_WAS_CHANGED}, ${JSON.stringify(true)})
     `;
 		this._broadcastProtocol(JSON.stringify({
 			state: nextState,
@@ -786,6 +811,44 @@ var Agent = class Agent extends Server {
 		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
@@ -1185,6 +1248,7 @@ var Agent = class Agent extends Server {
 	* @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.");
 		const id = nanoid(9);
 		if (options?.retry) validateRetryOptions(options.retry, this._resolvedOptions.retry);
 		const retryJson = options?.retry ? JSON.stringify(options.retry) : null;
@@ -1281,6 +1345,7 @@ var Agent = class Agent extends Server {
 	* @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)`);
@@ -1388,6 +1453,7 @@ var Agent = class Agent extends Server {
 	* @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", {
@@ -1419,6 +1485,7 @@ var Agent = class Agent extends Server {
 	* ```
 	*/
 	async keepAlive() {
+		if (this._isFacet) throw new Error("keepAlive() is not supported in sub-agents. Use keepAlive() from the parent agent instead.");
 		const heartbeatSeconds = Math.ceil(KEEP_ALIVE_INTERVAL_MS / 1e3);
 		const schedule = await this.scheduleEvery(heartbeatSeconds, "_cf_keepAliveHeartbeat", void 0, { _idempotent: false });
 		let disposed = false;
@@ -1469,10 +1536,10 @@ var Agent = class Agent extends Server {
       LIMIT 1
     `;
 		if (!result) return;
-		if (result.length > 0 && "time" in result[0]) {
-			const nextTime = result[0].time * 1e3;
-			await this.ctx.storage.setAlarm(nextTime);
-		} else await this.ctx.storage.deleteAlarm();
+		let nextTimeMs = null;
+		if (result.length > 0 && "time" in result[0]) nextTimeMs = result[0].time * 1e3;
+		if (nextTimeMs !== null) await this.ctx.storage.setAlarm(nextTimeMs);
+		else await this.ctx.storage.deleteAlarm();
 	}
 	/**
 	* Override PartyServer's onAlarm hook as a no-op.
@@ -1573,6 +1640,81 @@ var Agent = class Agent extends Server {
 		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() {
@@ -1581,7 +1723,7 @@ var Agent = class Agent extends Server {
 		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`;
-		await this.ctx.storage.deleteAlarm();
+		if (!this._isFacet) await this.ctx.storage.deleteAlarm();
 		await this.ctx.storage.deleteAll();
 		this._disposables.dispose();
 		await this.mcp.dispose();
@@ -2317,7 +2459,7 @@ var Agent = class Agent extends Server {
 	* @param workflowId - ID of the workflow
 	* @param progress - Typed progress data (default: DefaultProgress)
 	*/
-	async onWorkflowProgress(_workflowName, _workflowId, _progress) {}
+	async onWorkflowProgress(workflowName, workflowId, progress) {}
 	/**
 	* Called when a workflow completes successfully.
 	* Override to handle completion.
@@ -2326,7 +2468,7 @@ var Agent = class Agent extends Server {
 	* @param workflowId - ID of the workflow
 	* @param result - Optional result data
 	*/
-	async onWorkflowComplete(_workflowName, _workflowId, _result) {}
+	async onWorkflowComplete(workflowName, workflowId, result) {}
 	/**
 	* Called when a workflow encounters an error.
 	* Override to handle errors.
@@ -2335,7 +2477,9 @@ var Agent = class Agent extends Server {
 	* @param workflowId - ID of the workflow
 	* @param error - Error message
 	*/
-	async onWorkflowError(_workflowName, _workflowId, _error) {}
+	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.
@@ -2344,7 +2488,7 @@ var Agent = class Agent extends Server {
 	* @param workflowId - ID of the workflow
 	* @param event - Custom event payload
 	*/
-	async onWorkflowEvent(_workflowName, _workflowId, _event) {}
+	async onWorkflowEvent(workflowName, workflowId, event) {}
 	/**
 	* Handle a workflow callback via RPC.
 	* @internal - Called by AgentWorkflow, do not call directly
@@ -2601,6 +2745,7 @@ var Agent = class Agent extends Server {
 		return Response.redirect(baseOrigin);
 	}
 };
+Agent.options = { hibernate: true };
 const wrappedClasses = /* @__PURE__ */ new Set();
 /**
 * Route a request to the appropriate Agent