agents 0.11.8 → 0.12.0

package/dist/index.js

@@ -1,7 +1,7 @@
+import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
 import { MessageType } from "./types.js";
 import { camelCaseToKebabCase } from "./utils.js";
 import { createHeaderBasedEmailResolver, signAgentHeaders } from "./email.js";
-import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
 import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-Bqby-AHD.js";
 import { SUB_PREFIX, getSubAgentByName, parseSubAgentPath, routeSubAgentRequest } from "./sub-routing.js";
 import { isErrorRetryable, tryN, validateRetryOptions } from "./retries.js";
@@ -74,7 +74,7 @@ const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 3e4;
 * 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 CURRENT_SCHEMA_VERSION = 7;
 const SCHEMA_VERSION_ROW_ID = "cf_schema_version";
 const STATE_ROW_ID = "cf_state_row_id";
 const STATE_WAS_CHANGED = "cf_state_was_changed";
@@ -218,13 +218,13 @@ function getCurrentAgent() {
 */
 function withAgentContext(method) {
 	return function(...args) {
-		const { connection, request, email, agent } = getCurrentAgent();
+		const { agent } = getCurrentAgent();
 		if (agent === this) return method.apply(this, args);
 		return __DO_NOT_USE_WILL_BREAK__agentContext.run({
 			agent: this,
-			connection,
-			request,
-			email
+			connection: void 0,
+			request: void 0,
+			email: void 0
 		}, () => {
 			return method.apply(this, args);
 		});
@@ -383,7 +383,9 @@ var Agent = class Agent extends Server {
           running INTEGER DEFAULT 0,
           created_at INTEGER DEFAULT (unixepoch()),
           execution_started_at INTEGER,
-          retry_options TEXT
+          retry_options TEXT,
+          owner_path TEXT,
+          owner_path_key TEXT
         )
       `;
 			const addColumnIfNotExists = (sql) => {
@@ -397,6 +399,8 @@ var Agent = class Agent extends Server {
 			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_schedules ADD COLUMN owner_path TEXT");
+			addColumnIfNotExists("ALTER TABLE cf_agents_schedules ADD COLUMN owner_path_key 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();
@@ -416,15 +420,19 @@ var Agent = class Agent extends Server {
                 running INTEGER DEFAULT 0,
                 created_at INTEGER DEFAULT (unixepoch()),
                 execution_started_at INTEGER,
-                retry_options TEXT
+                retry_options TEXT,
+                owner_path TEXT,
+                owner_path_key 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)
+                 intervalSeconds, running, created_at, execution_started_at, retry_options,
+                 owner_path, owner_path_key)
               SELECT id, callback, payload, type, time, delayInSeconds, cron,
-                     intervalSeconds, running, created_at, execution_started_at, retry_options
+                     intervalSeconds, running, created_at, execution_started_at, retry_options,
+                     owner_path, owner_path_key
               FROM cf_agents_schedules
             `);
 						this.ctx.storage.sql.exec("DROP TABLE cf_agents_schedules");
@@ -467,6 +475,41 @@ var Agent = class Agent extends Server {
         )
       `;
 			this.sql`
+        CREATE TABLE IF NOT EXISTS cf_agents_facet_runs (
+          owner_path TEXT NOT NULL,
+          owner_path_key TEXT NOT NULL,
+          run_id TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          PRIMARY KEY (owner_path_key, run_id)
+        )
+      `;
+			this.sql`
+        CREATE INDEX IF NOT EXISTS idx_facet_runs_owner_path_key
+        ON cf_agents_facet_runs(owner_path_key)
+      `;
+			this.sql`
+        CREATE TABLE IF NOT EXISTS cf_agent_tool_runs (
+          run_id TEXT PRIMARY KEY,
+          parent_tool_call_id TEXT,
+          agent_type TEXT NOT NULL,
+          input_preview TEXT,
+          input_redacted INTEGER NOT NULL DEFAULT 1,
+          status TEXT NOT NULL,
+          summary TEXT,
+          output_json TEXT,
+          error_message TEXT,
+          display_metadata TEXT,
+          display_order INTEGER NOT NULL DEFAULT 0,
+          started_at INTEGER NOT NULL,
+          completed_at INTEGER
+        )
+      `;
+			this.sql`
+        CREATE INDEX IF NOT EXISTS idx_agent_tool_runs_parent_tool_call_id
+        ON cf_agent_tool_runs(parent_tool_call_id, display_order)
+      `;
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN output_json TEXT");
+			this.sql`
         INSERT OR REPLACE INTO cf_agents_state (id, state)
         VALUES (${SCHEMA_VERSION_ROW_ID}, ${String(CURRENT_SCHEMA_VERSION)})
       `;
@@ -480,16 +523,19 @@ var Agent = class Agent extends Server {
 		this._rawStateAccessors = /* @__PURE__ */ new WeakMap();
 		this._persistenceHookMode = "none";
 		this._isFacet = false;
+		this._suppressProtocolBroadcasts = false;
 		this._parentPath = [];
 		this._insideOnStart = false;
 		this._warnedScheduleInOnStart = /* @__PURE__ */ new Set();
 		this._keepAliveRefs = 0;
+		this._facetKeepAliveTokens = /* @__PURE__ */ new Set();
 		this._runFiberActiveFibers = /* @__PURE__ */ new Set();
 		this._runFiberRecoveryInProgress = false;
 		this._ParentClass = Object.getPrototypeOf(this).constructor;
 		this.initialState = DEFAULT_STATE;
 		this.observability = genericObservability;
 		this._flushingQueue = false;
+		this.maxConcurrentAgentTools = Infinity;
 		this._subAgentRegistryReady = false;
 		if (!wrappedClasses.has(this.constructor)) {
 			this._autoWrapCustomMethods();
@@ -666,6 +712,7 @@ var Agent = class Agent extends Server {
 					}));
 				} else this._setConnectionNoProtocol(connection);
 				this._emit("connect", { connectionId: connection.id });
+				await this._replayAgentToolRuns(connection);
 				return this._tryCatch(() => _onConnect(connection, ctx));
 			});
 		};
@@ -702,6 +749,7 @@ var Agent = class Agent extends Server {
 					this.broadcastMcpServers();
 					this._checkOrphanedWorkflows();
 					await this._checkRunFibers();
+					await this._reconcileAgentToolRuns();
 					this._insideOnStart = true;
 					this._warnedScheduleInOnStart.clear();
 					try {
@@ -743,6 +791,7 @@ var Agent = class Agent extends Server {
 	* @param excludeIds Additional connection IDs to exclude (e.g. the source)
 	*/
 	_broadcastProtocol(msg, excludeIds = []) {
+		if (this._suppressProtocolBroadcasts) return;
 		const exclude = [...excludeIds];
 		for (const conn of this.getConnections()) if (!this.isConnectionProtocolEnabled(conn)) exclude.push(conn.id);
 		this.broadcast(msg, exclude);
@@ -1374,39 +1423,60 @@ var Agent = class Agent extends Server {
 			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.");
+	_scheduleOwnerPathKey(path) {
+		if (!path) return null;
+		return path.map((step) => `${encodeURIComponent(step.className)}:${encodeURIComponent(step.name)}`).join("/");
+	}
+	_facetRunRowsForPrefix(ownerPath) {
+		return this.sql`
+      SELECT owner_path, owner_path_key, run_id, created_at
+      FROM cf_agents_facet_runs
+    `.filter((row) => {
+			try {
+				const rowOwnerPath = JSON.parse(row.owner_path);
+				return this._isSameAgentPathPrefix(ownerPath, rowOwnerPath);
+			} catch {
+				return false;
+			}
+		});
+	}
+	_deleteFacetRunRowsForPrefix(ownerPath) {
+		for (const row of this._facetRunRowsForPrefix(ownerPath)) this.sql`
+        DELETE FROM cf_agents_facet_runs
+        WHERE owner_path_key = ${row.owner_path_key}
+          AND run_id = ${row.run_id}
+      `;
+	}
+	async _rootAlarmOwner() {
+		const root = this._parentPath[0];
+		if (!root) throw new Error("Facet scheduler delegation requires a root parent.");
+		const binding = this.ctx.exports?.[root.className];
+		if (!binding) throw new Error(`Unable to resolve root scheduler "${root.className}" for sub-agent schedule delegation.`);
+		return await getServerByName(binding, root.name);
+	}
+	_validateScheduleCallback(when, callback, options) {
 		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.`);
 		}
+	}
+	/**
+	* Insert (or, for idempotent calls, return the existing row for) a
+	* schedule owned by either this top-level agent (`ownerPath === null`)
+	* or a descendant facet. Returns `{ schedule, created }` — `created`
+	* is `false` when an idempotent insert deduplicates onto an existing
+	* row, so callers can suppress the `schedule:create` event in that
+	* case to match historic semantics.
+	* @internal
+	*/
+	async _insertScheduleForOwner(ownerPath, when, callback, payload, options) {
+		const ownerPathJson = ownerPath ? JSON.stringify(ownerPath) : null;
+		const ownerPathKey = this._scheduleOwnerPathKey(ownerPath);
+		const retryJson = options?.retry ? JSON.stringify(options.retry) : null;
+		const payloadJson = JSON.stringify(payload);
 		if (when instanceof Date) {
 			const timestamp = Math.floor(when.getTime() / 1e3);
 			if (options?.idempotent) {
@@ -1415,90 +1485,96 @@ var Agent = class Agent extends Server {
           WHERE type = 'scheduled'
             AND callback = ${callback}
             AND payload IS ${payloadJson}
+            AND owner_path_key IS ${ownerPathKey}
           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"
+						schedule: {
+							callback: row.callback,
+							id: row.id,
+							payload: JSON.parse(row.payload),
+							retry: parseRetryOptions(row),
+							time: row.time,
+							type: "scheduled"
+						},
+						created: false
 					};
 				}
 			}
 			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})
+        INSERT OR REPLACE INTO cf_agents_schedules
+          (id, callback, payload, type, time, retry_options, owner_path, owner_path_key)
+        VALUES
+          (${id}, ${callback}, ${payloadJson}, 'scheduled', ${timestamp}, ${retryJson}, ${ownerPathJson}, ${ownerPathKey})
       `;
 			await this._scheduleNextAlarm();
-			const schedule = {
-				callback,
-				id,
-				payload,
-				retry: options?.retry,
-				time: timestamp,
-				type: "scheduled"
+			return {
+				schedule: {
+					callback,
+					id,
+					payload,
+					retry: options?.retry,
+					time: timestamp,
+					type: "scheduled"
+				},
+				created: true
 			};
-			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);
+			const timestamp = Math.floor((Date.now() + when * 1e3) / 1e3);
 			if (options?.idempotent) {
 				const existing = this.sql`
           SELECT * FROM cf_agents_schedules
           WHERE type = 'delayed'
             AND callback = ${callback}
             AND payload IS ${payloadJson}
+            AND owner_path_key IS ${ownerPathKey}
           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"
+						schedule: {
+							callback: row.callback,
+							delayInSeconds: row.delayInSeconds ?? 0,
+							id: row.id,
+							payload: JSON.parse(row.payload),
+							retry: parseRetryOptions(row),
+							time: row.time,
+							type: "delayed"
+						},
+						created: false
 					};
 				}
 			}
 			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})
+        INSERT OR REPLACE INTO cf_agents_schedules
+          (id, callback, payload, type, delayInSeconds, time, retry_options, owner_path, owner_path_key)
+        VALUES
+          (${id}, ${callback}, ${payloadJson}, 'delayed', ${when}, ${timestamp}, ${retryJson}, ${ownerPathJson}, ${ownerPathKey})
       `;
 			await this._scheduleNextAlarm();
-			const schedule = {
-				callback,
-				delayInSeconds: when,
-				id,
-				payload,
-				retry: options?.retry,
-				time: timestamp,
-				type: "delayed"
+			return {
+				schedule: {
+					callback,
+					delayInSeconds: when,
+					id,
+					payload,
+					retry: options?.retry,
+					time: timestamp,
+					type: "delayed"
+				},
+				created: true
 			};
-			this._emit("schedule:create", {
-				callback,
-				id
-			});
-			return schedule;
 		}
 		if (typeof when === "string") {
-			const nextExecutionTime = getNextCronTime(when);
-			const timestamp = Math.floor(nextExecutionTime.getTime() / 1e3);
+			const timestamp = Math.floor(getNextCronTime(when).getTime() / 1e3);
 			if (options?.idempotent !== false) {
 				const existing = this.sql`
           SELECT * FROM cf_agents_schedules
@@ -1506,79 +1582,70 @@ var Agent = class Agent extends Server {
             AND callback = ${callback}
             AND cron = ${when}
             AND payload IS ${payloadJson}
+            AND owner_path_key IS ${ownerPathKey}
           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"
+						schedule: {
+							callback: row.callback,
+							cron: row.cron ?? when,
+							id: row.id,
+							payload: JSON.parse(row.payload),
+							retry: parseRetryOptions(row),
+							time: row.time,
+							type: "cron"
+						},
+						created: false
 					};
 				}
 			}
 			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})
+        INSERT OR REPLACE INTO cf_agents_schedules
+          (id, callback, payload, type, cron, time, retry_options, owner_path, owner_path_key)
+        VALUES
+          (${id}, ${callback}, ${payloadJson}, 'cron', ${when}, ${timestamp}, ${retryJson}, ${ownerPathJson}, ${ownerPathKey})
       `;
 			await this._scheduleNextAlarm();
-			const schedule = {
-				callback,
-				cron: when,
-				id,
-				payload,
-				retry: options?.retry,
-				time: timestamp,
-				type: "cron"
+			return {
+				schedule: {
+					callback,
+					cron: when,
+					id,
+					payload,
+					retry: options?.retry,
+					time: timestamp,
+					type: "cron"
+				},
+				created: true
 			};
-			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
+	* Insert a schedule row owned by a descendant facet. Called via RPC
+	* from the facet's `schedule()`. Returns `{ schedule, created }`
+	* so the originating facet can suppress `schedule:create` on
+	* idempotent dedup. This method does not emit observability
+	* events itself.
+	* @internal
 	*/
-	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);
+	async _cf_scheduleForFacet(ownerPath, when, callback, payload, options) {
+		return this._insertScheduleForOwner(ownerPath, when, callback, payload, options);
+	}
+	/**
+	* Insert (or, for idempotent calls, return the existing row for) an
+	* interval schedule. Mirrors {@link _insertScheduleForOwner} —
+	* returns `{ schedule, created }` so callers can suppress
+	* `schedule:create` on dedup.
+	* @internal
+	*/
+	async _insertIntervalScheduleForOwner(ownerPath, intervalSeconds, callback, payload, options) {
+		const ownerPathJson = ownerPath ? JSON.stringify(ownerPath) : null;
+		const ownerPathKey = this._scheduleOwnerPathKey(ownerPath);
 		const idempotent = options?._idempotent !== false;
 		const payloadJson = JSON.stringify(payload);
 		if (idempotent) {
@@ -1588,73 +1655,165 @@ var Agent = class Agent extends Server {
           AND callback = ${callback}
           AND intervalSeconds = ${intervalSeconds}
           AND payload IS ${payloadJson}
+          AND owner_path_key IS ${ownerPathKey}
         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"
+					schedule: {
+						callback: row.callback,
+						id: row.id,
+						intervalSeconds: row.intervalSeconds ?? intervalSeconds,
+						payload: JSON.parse(row.payload),
+						retry: parseRetryOptions(row),
+						time: row.time,
+						type: "interval"
+					},
+					created: false
 				};
 			}
 		}
 		const id = nanoid(9);
-		const time = new Date(Date.now() + intervalSeconds * 1e3);
-		const timestamp = Math.floor(time.getTime() / 1e3);
+		const timestamp = Math.floor((Date.now() + intervalSeconds * 1e3) / 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})
+      INSERT OR REPLACE INTO cf_agents_schedules
+        (id, callback, payload, type, intervalSeconds, time, running, retry_options, owner_path, owner_path_key)
+      VALUES
+        (${id}, ${callback}, ${payloadJson}, 'interval', ${intervalSeconds}, ${timestamp}, 0, ${retryJson}, ${ownerPathJson}, ${ownerPathKey})
     `;
 		await this._scheduleNextAlarm();
-		const schedule = {
-			callback,
-			id,
-			intervalSeconds,
-			payload,
-			retry: options?.retry,
-			time: timestamp,
-			type: "interval"
+		return {
+			schedule: {
+				callback,
+				id,
+				intervalSeconds,
+				payload,
+				retry: options?.retry,
+				time: timestamp,
+				type: "interval"
+			},
+			created: true
 		};
-		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
+	* Insert an interval schedule row owned by a descendant facet.
+	* Called via RPC from the facet's `scheduleEvery()`. Returns
+	* `{ schedule, created }` so the originating facet can suppress
+	* `schedule:create` on idempotent dedup. This method does not
+	* emit observability events itself.
+	* @internal
 	*/
-	getSchedule(id) {
+	async _cf_scheduleEveryForFacet(ownerPath, intervalSeconds, callback, payload, options) {
+		return this._insertIntervalScheduleForOwner(ownerPath, intervalSeconds, callback, payload, options);
+	}
+	/**
+	* Cancel a schedule row owned by a descendant facet, scoped by
+	* `owner_path_key` so siblings can't reach each other's rows.
+	* Returns the canceled row's callback name so the originating
+	* facet can emit `schedule:cancel`. This method does not emit
+	* observability events itself.
+	* @internal
+	*/
+	async _cf_cancelScheduleForFacet(ownerPath, id) {
+		const ownerPathKey = this._scheduleOwnerPathKey(ownerPath);
 		const result = this.sql`
-      SELECT * FROM cf_agents_schedules WHERE id = ${id}
+      SELECT * FROM cf_agents_schedules
+      WHERE id = ${id} AND owner_path_key IS ${ownerPathKey}
     `;
-		if (!result || result.length === 0) return;
-		const row = result[0];
+		if (result.length === 0) return { ok: false };
+		const callback = result[0].callback;
+		this.sql`
+      DELETE FROM cf_agents_schedules
+      WHERE id = ${id} AND owner_path_key IS ${ownerPathKey}
+    `;
+		await this._scheduleNextAlarm();
 		return {
-			...row,
-			payload: JSON.parse(row.payload),
-			retry: parseRetryOptions(row)
+			ok: true,
+			callback
 		};
 	}
 	/**
-	* 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
+	* Clean root-owned bookkeeping for a sub-tree of facets. This
+	* bulk-cancels schedules whose `owner_path` starts with the given
+	* prefix and deletes root-side facet fiber recovery leases for the
+	* same sub-tree. Used by `deleteSubAgent` and recursive facet
+	* destroy. Emits `schedule:cancel` on this agent (the alarm-owning
+	* root) for each schedule row removed — the facets being torn down
+	* may not be alive to receive the events themselves.
+	* @internal
 	*/
-	getSchedules(criteria = {}) {
-		let query = "SELECT * FROM cf_agents_schedules WHERE 1=1";
-		const params = [];
+	async _cf_cleanupFacetPrefix(ownerPath) {
+		const rowsToDelete = this.sql`
+      SELECT * FROM cf_agents_schedules
+      WHERE owner_path IS NOT NULL
+    `.filter((row) => {
+			if (!row.owner_path) return false;
+			try {
+				const rowOwnerPath = JSON.parse(row.owner_path);
+				return this._isSameAgentPathPrefix(ownerPath, rowOwnerPath);
+			} catch {
+				return false;
+			}
+		});
+		for (const row of rowsToDelete) {
+			this._emit("schedule:cancel", {
+				callback: row.callback,
+				id: row.id
+			});
+			this.sql`DELETE FROM cf_agents_schedules WHERE id = ${row.id}`;
+		}
+		this._deleteFacetRunRowsForPrefix(ownerPath);
+		await this._scheduleNextAlarm();
+	}
+	_scheduleRowToSchedule(row) {
+		const base = {
+			callback: row.callback,
+			id: row.id,
+			payload: JSON.parse(row.payload),
+			retry: parseRetryOptions(row)
+		};
+		switch (row.type) {
+			case "scheduled": return {
+				...base,
+				time: row.time,
+				type: "scheduled"
+			};
+			case "delayed": return {
+				...base,
+				delayInSeconds: row.delayInSeconds ?? 0,
+				time: row.time,
+				type: "delayed"
+			};
+			case "cron": return {
+				...base,
+				cron: row.cron ?? "",
+				time: row.time,
+				type: "cron"
+			};
+			case "interval": return {
+				...base,
+				intervalSeconds: row.intervalSeconds ?? 0,
+				time: row.time,
+				type: "interval"
+			};
+		}
+	}
+	_getScheduleForOwner(ownerPath, id) {
+		const ownerPathKey = this._scheduleOwnerPathKey(ownerPath);
+		const result = this.sql`
+      SELECT * FROM cf_agents_schedules
+      WHERE id = ${id} AND owner_path_key IS ${ownerPathKey}
+    `;
+		if (!result || result.length === 0) return;
+		return this._scheduleRowToSchedule(result[0]);
+	}
+	_listSchedulesForOwner(ownerPath, criteria = {}) {
+		const ownerPathKey = this._scheduleOwnerPathKey(ownerPath);
+		let query = "SELECT * FROM cf_agents_schedules WHERE owner_path_key IS ?";
+		const params = [ownerPathKey];
 		if (criteria.id) {
 			query += " AND id = ?";
 			params.push(criteria.id);
@@ -1669,61 +1828,274 @@ var Agent = class Agent extends Server {
 			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)
-		}));
+		return this.ctx.storage.sql.exec(query, ...params).toArray().map((row) => this._scheduleRowToSchedule(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
+	* Read a single schedule row owned by a descendant facet.
+	* @internal
 	*/
-	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;
+	async _cf_getScheduleForFacet(ownerPath, id) {
+		return this._getScheduleForOwner(ownerPath, id);
 	}
 	/**
-	* 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 }`.
-	*
-	* No-op on facets. Facets share the parent's isolate and don't
-	* need a separate alarm heartbeat — the parent's own activity,
-	* any open WebSocket to the facet, and any in-flight Promise
-	* already keep the shared machine alive for the duration of
-	* real work.
-	*
-	* @example
-	* ```ts
-	* const dispose = await this.keepAlive();
-	* try {
-	*   // ... long-running work ...
-	* } finally {
-	*   dispose();
-	* }
-	* ```
+	* List schedule rows owned by a descendant facet, scoped by
+	* `owner_path_key` so siblings remain isolated from each other.
+	* @internal
 	*/
-	async keepAlive() {
-		if (this._isFacet) return () => {};
+	async _cf_listSchedulesForFacet(ownerPath, criteria = {}) {
+		return this._listSchedulesForOwner(ownerPath, criteria);
+	}
+	/**
+	* Acquire a root-owned keepAlive ref on behalf of a descendant facet.
+	* Facets share the root isolate but cannot set their own physical
+	* alarm, so this lets facet work use the root alarm heartbeat.
+	* @internal
+	*/
+	async _cf_acquireFacetKeepAlive(ownerPath) {
+		const token = `${this._scheduleOwnerPathKey(ownerPath) ?? "unknown"}:${nanoid(9)}`;
+		this._facetKeepAliveTokens.add(token);
 		this._keepAliveRefs++;
 		if (this._keepAliveRefs === 1) await this._scheduleNextAlarm();
-		let disposed = false;
-		return () => {
+		return token;
+	}
+	/**
+	* Release a root-owned keepAlive ref previously acquired for a facet.
+	* Idempotent so disposer calls can safely race or run twice.
+	* @internal
+	*/
+	async _cf_releaseFacetKeepAlive(token) {
+		if (!this._facetKeepAliveTokens.delete(token)) return;
+		this._keepAliveRefs = Math.max(0, this._keepAliveRefs - 1);
+		await this._scheduleNextAlarm();
+	}
+	/**
+	* Register a facet's durable run row in the root-side index so root
+	* alarm housekeeping can dispatch recovery checks into idle facets.
+	* The facet remains authoritative for snapshots and recovery hooks.
+	* @internal
+	*/
+	async _cf_registerFacetRun(ownerPath, runId) {
+		const ownerPathJson = JSON.stringify(ownerPath);
+		const ownerPathKey = this._scheduleOwnerPathKey(ownerPath);
+		if (!ownerPathKey) throw new Error("_cf_registerFacetRun requires a non-empty owner path.");
+		this.sql`
+      INSERT OR REPLACE INTO cf_agents_facet_runs
+        (owner_path, owner_path_key, run_id, created_at)
+      VALUES
+        (${ownerPathJson}, ${ownerPathKey}, ${runId}, ${Date.now()})
+    `;
+		await this._scheduleNextAlarm();
+	}
+	/**
+	* Remove a completed facet fiber from the root-side index.
+	* @internal
+	*/
+	async _cf_unregisterFacetRun(ownerPath, runId) {
+		const ownerPathKey = this._scheduleOwnerPathKey(ownerPath);
+		this.sql`
+      DELETE FROM cf_agents_facet_runs
+      WHERE owner_path_key IS ${ownerPathKey}
+        AND run_id = ${runId}
+    `;
+		await this._scheduleNextAlarm();
+	}
+	/**
+	* 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) {
+		this._validateScheduleCallback(when, callback, options);
+		const result = this._isFacet ? await (await this._rootAlarmOwner())._cf_scheduleForFacet(this.selfPath, when, callback, payload, options) : await this._insertScheduleForOwner(null, when, callback, payload, options);
+		if (result.created) this._emit("schedule:create", {
+			callback: result.schedule.callback,
+			id: result.schedule.id
+		});
+		return result.schedule;
+	}
+	/**
+	* 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) {
+		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 result = this._isFacet ? await (await this._rootAlarmOwner())._cf_scheduleEveryForFacet(this.selfPath, intervalSeconds, callback, payload, options) : await this._insertIntervalScheduleForOwner(null, intervalSeconds, callback, payload, options);
+		if (result.created) this._emit("schedule:create", {
+			callback: result.schedule.callback,
+			id: result.schedule.id
+		});
+		return result.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
+	* @deprecated Use {@link getScheduleById}. This synchronous API cannot cross
+	* Durable Object boundaries and throws inside sub-agents.
+	*/
+	getSchedule(id) {
+		if (this._isFacet) throw new Error("getSchedule() is synchronous and cannot read parent-owned sub-agent schedules. Use await this.getScheduleById(id) instead.");
+		return this._getScheduleForOwner(null, id);
+	}
+	/**
+	* Get a scheduled task by ID.
+	*
+	* Unlike the deprecated synchronous {@link getSchedule}, this works inside
+	* sub-agents by delegating to the top-level parent that owns the alarm.
+	*
+	* @template T Type of the payload data
+	* @param id ID of the scheduled task
+	* @returns The Schedule object or undefined if not found
+	*/
+	async getScheduleById(id) {
+		if (this._isFacet) return (await this._rootAlarmOwner())._cf_getScheduleForFacet(this.selfPath, id);
+		return this._getScheduleForOwner(null, id);
+	}
+	/**
+	* 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
+	* @deprecated Use {@link listSchedules}. This synchronous API cannot cross
+	* Durable Object boundaries and throws inside sub-agents.
+	*/
+	getSchedules(criteria = {}) {
+		if (this._isFacet) throw new Error("getSchedules() is synchronous and cannot read parent-owned sub-agent schedules. Use await this.listSchedules(criteria) instead.");
+		return this._listSchedulesForOwner(null, criteria);
+	}
+	/**
+	* List scheduled tasks matching the given criteria.
+	*
+	* Unlike the deprecated synchronous {@link getSchedules}, this works inside
+	* sub-agents by delegating to the top-level parent that owns the alarm.
+	*
+	* @template T Type of the payload data
+	* @param criteria Criteria to filter schedules
+	* @returns Array of matching Schedule objects
+	*/
+	async listSchedules(criteria = {}) {
+		if (this._isFacet) return (await this._rootAlarmOwner())._cf_listSchedulesForFacet(this.selfPath, criteria);
+		return this._listSchedulesForOwner(null, criteria);
+	}
+	/**
+	* Cancel a scheduled task.
+	*
+	* Schedules are isolated by owner: a top-level agent's
+	* `cancelSchedule(id)` only matches its own schedules, and a
+	* sub-agent's `cancelSchedule(id)` only matches schedules it
+	* created. To clear every schedule under a sub-agent (and its
+	* descendants), call `parent.deleteSubAgent(Cls, name)` from the
+	* parent — that bulk-cleans root-owned bookkeeping via
+	* {@link _cf_cleanupFacetPrefix}.
+	*
+	* @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) {
+			const result = await (await this._rootAlarmOwner())._cf_cancelScheduleForFacet(this.selfPath, id);
+			if (result.ok && result.callback) this._emit("schedule:cancel", {
+				callback: result.callback,
+				id
+			});
+			return result.ok;
+		}
+		const schedule = this._getScheduleForOwner(null, 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 }`.
+	*
+	* In facets, delegates the physical heartbeat to the root parent
+	* because facets do not have independent alarm slots.
+	*
+	* @example
+	* ```ts
+	* const dispose = await this.keepAlive();
+	* try {
+	*   // ... long-running work ...
+	* } finally {
+	*   dispose();
+	* }
+	* ```
+	*/
+	async keepAlive() {
+		if (this._isFacet) {
+			const root = await this._rootAlarmOwner();
+			const token = await root._cf_acquireFacetKeepAlive(this.selfPath);
+			let disposed = false;
+			return () => {
+				if (disposed) return;
+				disposed = true;
+				const release = root._cf_releaseFacetKeepAlive(token).catch((e) => {
+					console.error("[Agent] Failed to release facet keepAlive:", e);
+				});
+				this.ctx.waitUntil(release);
+			};
+		}
+		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);
@@ -1773,8 +2145,16 @@ var Agent = class Agent extends Server {
       VALUES (${id}, ${name}, NULL, ${Date.now()})
     `;
 		this._runFiberActiveFibers.add(id);
-		const dispose = await this.keepAlive();
+		let root;
+		let registeredFacetRun = false;
+		let dispose = () => {};
 		try {
+			if (this._isFacet) {
+				root = await this._rootAlarmOwner();
+				await root._cf_registerFacetRun(this.selfPath, id);
+				registeredFacetRun = true;
+			}
+			dispose = await this.keepAlive();
 			const stash = (data) => {
 				this.sql`
           UPDATE cf_agents_runs SET snapshot = ${JSON.stringify(data)}
@@ -1793,6 +2173,11 @@ var Agent = class Agent extends Server {
 			this._runFiberActiveFibers.delete(id);
 			this.sql`DELETE FROM cf_agents_runs WHERE id = ${id}`;
 			dispose();
+			if (root && registeredFacetRun) try {
+				await root._cf_unregisterFacetRun(this.selfPath, id);
+			} catch (e) {
+				console.error("[Agent] Failed to unregister facet fiber:", e);
+			}
 		}
 	}
 	/**
@@ -1861,6 +2246,179 @@ var Agent = class Agent extends Server {
 	/** @internal */
 	async _onAlarmHousekeeping() {
 		await this._checkRunFibers();
+		await this._checkFacetRunFibers();
+	}
+	_isSameAgentPathPrefix(prefix, path) {
+		if (prefix.length > path.length) return false;
+		return prefix.every((step, index) => step.className === path[index].className && step.name === path[index].name);
+	}
+	/**
+	* Root-side scan for durable fibers owned by descendant facets.
+	* `cf_agents_facet_runs` is only an index; actual snapshots and
+	* recovery hooks live in each facet's own `cf_agents_runs` table.
+	* @internal
+	*/
+	async _checkFacetRunFibers() {
+		if (this._parentPath.length > 0) return;
+		const rows = this.sql`
+      SELECT owner_path, owner_path_key, run_id, created_at
+      FROM cf_agents_facet_runs
+      ORDER BY created_at ASC
+    `;
+		const firstRowByOwner = /* @__PURE__ */ new Map();
+		for (const row of rows) if (!firstRowByOwner.has(row.owner_path_key)) firstRowByOwner.set(row.owner_path_key, row);
+		for (const row of firstRowByOwner.values()) {
+			let ownerPath;
+			try {
+				ownerPath = JSON.parse(row.owner_path);
+			} catch (e) {
+				console.warn(`[Agent] Corrupted facet fiber owner path for ${row.owner_path_key}; pruning stale lease.`, e);
+				this.sql`
+          DELETE FROM cf_agents_facet_runs
+          WHERE owner_path_key = ${row.owner_path_key}
+        `;
+				continue;
+			}
+			try {
+				if (await this._cf_checkRunFibersForFacet(ownerPath) === 0) this.sql`
+            DELETE FROM cf_agents_facet_runs
+            WHERE owner_path_key = ${row.owner_path_key}
+          `;
+			} catch (e) {
+				console.error(`[Agent] Facet fiber recovery check failed for ${row.owner_path_key}:`, e);
+			}
+		}
+	}
+	/**
+	* Dispatch a runFiber recovery check into the facet identified by
+	* `ownerPath`. Returns the number of remaining local `cf_agents_runs`
+	* rows on the target facet after recovery.
+	* @internal
+	*/
+	async _cf_checkRunFibersForFacet(ownerPath) {
+		const selfPath = this.selfPath;
+		if (!this._isSameAgentPathPrefix(selfPath, ownerPath)) throw new Error(`Facet fiber owner path does not descend from ${JSON.stringify(selfPath)}.`);
+		if (selfPath.length === ownerPath.length) {
+			await this._checkRunFibers();
+			return this.sql`
+        SELECT COUNT(*) as count FROM cf_agents_runs
+      `[0]?.count ?? 0;
+		}
+		const next = ownerPath[selfPath.length];
+		if (!this.hasSubAgent(next.className, next.name)) return 0;
+		return (await this._cf_resolveSubAgent(next.className, next.name))._cf_checkRunFibersForFacet(ownerPath);
+	}
+	/**
+	* Dispatch a scheduled callback into the facet identified by
+	* `ownerPath`. Walks one step at a time: if `ownerPath` matches
+	* `selfPath`, executes the callback locally; otherwise resolves
+	* the next descendant facet and recurses through its own RPC.
+	*
+	* Called by the root's `alarm()` (which owns the physical alarm
+	* for facet-owned schedules) and by intermediate facets while
+	* walking down the chain.
+	* @internal
+	*/
+	async _cf_dispatchScheduledCallback(ownerPath, row) {
+		const selfPath = this.selfPath;
+		if (!this._isSameAgentPathPrefix(selfPath, ownerPath)) throw new Error(`Schedule owner path does not descend from ${JSON.stringify(selfPath)}.`);
+		if (selfPath.length === ownerPath.length) {
+			await this._executeScheduleCallback(row);
+			return;
+		}
+		const next = ownerPath[selfPath.length];
+		if (!this.hasSubAgent(next.className, next.name)) throw new Error(`Scheduled sub-agent ${next.className} "${next.name}" no longer exists.`);
+		await (await this._cf_resolveSubAgent(next.className, next.name))._cf_dispatchScheduledCallback(ownerPath, row);
+	}
+	/**
+	* Recursively destroy a descendant facet identified by
+	* `targetPath`. Walks down from `selfPath` until reaching the
+	* target's immediate parent, where it cancels the target's
+	* parent-owned schedules (and any descendants), removes the
+	* target from the registry, and calls `ctx.facets.delete` to
+	* wipe the target's storage.
+	*
+	* Called by a facet's own `destroy()` (via the root) so that
+	* `this.destroy()` inside a sub-agent results in the same
+	* cleanup as `parent.deleteSubAgent(Cls, name)` from the parent.
+	* @internal
+	*/
+	async _cf_destroyDescendantFacet(targetPath) {
+		const selfPath = this.selfPath;
+		if (targetPath.length === 0) throw new Error("_cf_destroyDescendantFacet: target path must not be empty.");
+		if (selfPath.length >= targetPath.length) throw new Error("_cf_destroyDescendantFacet: target must be a strict descendant.");
+		if (!this._isSameAgentPathPrefix(selfPath, targetPath)) throw new Error("_cf_destroyDescendantFacet: target path does not descend from this agent.");
+		if (this._parentPath.length === 0) await this._cf_cleanupFacetPrefix(targetPath);
+		if (selfPath.length === targetPath.length - 1) {
+			const target = targetPath[targetPath.length - 1];
+			const ctx = this.ctx;
+			if (!ctx.facets) throw new Error("destroy() (delegated from facet) is not supported in this runtime — `ctx.facets` is unavailable. Update to the latest `compatibility_date` in your wrangler.jsonc.");
+			try {
+				ctx.facets.delete(`${target.className}\0${target.name}`);
+			} catch {}
+			this._forgetSubAgent(target.className, target.name);
+			return;
+		}
+		const next = targetPath[selfPath.length];
+		if (!this.hasSubAgent(next.className, next.name)) return;
+		await (await this._cf_resolveSubAgent(next.className, next.name))._cf_destroyDescendantFacet(targetPath);
+	}
+	async _executeScheduleCallback(row) {
+		const callback = this[row.callback];
+		if (!callback) {
+			console.error(`callback ${row.callback} not found`);
+			return;
+		}
+		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 {}
+			}
+		});
 	}
 	async _scheduleNextAlarm() {
 		const nowMs = Date.now();
@@ -1891,6 +2449,12 @@ var Agent = class Agent extends Server {
 			const keepAliveMs = nowMs + this._resolvedOptions.keepAliveIntervalMs;
 			nextTimeMs = nextTimeMs === null ? keepAliveMs : Math.min(nextTimeMs, keepAliveMs);
 		}
+		if ((this.sql`
+      SELECT COUNT(*) as count FROM cf_agents_facet_runs
+    `[0]?.count ?? 0) > 0) {
+			const facetRecoveryMs = nowMs + this._resolvedOptions.keepAliveIntervalMs;
+			nextTimeMs = nextTimeMs === null ? facetRecoveryMs : Math.min(nextTimeMs, facetRecoveryMs);
+		}
 		if (nextTimeMs !== null) await this.ctx.storage.setAlarm(nextTimeMs);
 		else await this.ctx.storage.deleteAlarm();
 	}
@@ -1934,11 +2498,7 @@ var Agent = class Agent extends Server {
 				});
 			} catch {}
 			for (const row of result) {
-				const callback = this[row.callback];
-				if (!callback) {
-					console.error(`callback ${row.callback} not found`);
-					continue;
-				}
+				let executed = false;
 				if (row.type === "interval" && row.running === 1) {
 					const executionStartedAt = row.execution_started_at ?? 0;
 					const hungTimeoutSeconds = this._resolvedOptions.hungScheduleTimeoutSeconds;
@@ -1950,59 +2510,31 @@ var Agent = class Agent extends Server {
 					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;
-					}
+				if (row.owner_path) try {
+					const ownerPath = JSON.parse(row.owner_path);
+					await this._cf_dispatchScheduledCallback(ownerPath, row);
+				} catch (e) {
+					console.error(`error dispatching scheduled callback "${row.callback}"`, e);
+					this._emit("schedule:error", {
+						callback: row.callback,
+						id: row.id,
+						error: e instanceof Error ? e.message : String(e),
+						attempts: 0
+					});
 					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 {}
-					}
-				});
+						await this.onError(e);
+					} catch {}
+					if (row.type === "interval") this.sql`
+                UPDATE cf_agents_schedules SET running = 0 WHERE id = ${row.id}
+              `;
+					continue;
+				}
+				else await this._executeScheduleCallback(row);
+				executed = true;
 				if (this._destroyed) return;
+				if (!executed) continue;
 				if (row.type === "cron") {
-					const nextExecutionTime = getNextCronTime(row.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}
@@ -2136,10 +2668,10 @@ var Agent = class Agent extends Server {
 	* We set `_isFacet` eagerly (before `__unsafe_ensureInitialized`
 	* runs `onStart()`) so any code that legitimately branches on it
 	* — e.g. skipping parent-owned alarms in schedule guards — sees
-	* the flag during the first `onStart()` run. Broadcast paths no
-	* longer special-case facets, since facets can be directly
-	* addressed via sub-agent routing and have their own WebSocket
-	* connections.
+	* the flag during the first `onStart()` run. Protocol broadcasts are
+	* suppressed only during this bootstrap window; afterward, facets can
+	* broadcast to their own WebSocket clients reached via sub-agent
+	* routing.
 	*
 	* The facet's name (and `this.name` getter) is handled entirely by
 	* partyserver via `ctx.id.name`, which is populated because the
@@ -2156,7 +2688,12 @@ var Agent = class Agent extends Server {
 		this._isFacet = true;
 		this._parentPath = parentPath;
 		await Promise.all([this.ctx.storage.put("cf_agents_is_facet", true), this.ctx.storage.put("cf_agents_parent_path", parentPath)]);
-		await this.__unsafe_ensureInitialized();
+		this._suppressProtocolBroadcasts = true;
+		try {
+			await this.__unsafe_ensureInitialized();
+		} finally {
+			this._suppressProtocolBroadcasts = false;
+		}
 	}
 	/**
 	* Ancestor chain for this agent, root-first. Empty for top-level
@@ -2260,6 +2797,529 @@ var Agent = class Agent extends Server {
 	async subAgent(cls, name) {
 		return await this._cf_resolveSubAgent(cls.name, name);
 	}
+	async onAgentToolStart(_run) {}
+	async onAgentToolFinish(_run, _result) {}
+	async runAgentTool(cls, options) {
+		const runId = options.runId ?? nanoid(12);
+		const agentType = cls.name;
+		const existing = this._readAgentToolRun(runId);
+		if (existing) {
+			if (this._isAgentToolTerminal(existing.status)) {
+				if (existing.status === "completed" && existing.output_json == null) try {
+					const child = await this.subAgent(cls, runId);
+					const inspection = await this._asAgentToolChildAdapter(child).inspectAgentToolRun(runId);
+					if (inspection?.status === "completed") {
+						const result = this._terminalResultFromInspection(agentType, inspection);
+						this._updateAgentToolTerminal(runId, result, inspection.completedAt);
+						return result;
+					}
+				} catch {}
+				return this._resultFromAgentToolRow(existing);
+			}
+			return await this._replayAndInterruptAgentToolRun(cls, existing, "Agent tool run was still running, but live-tail reattachment is not supported in this runtime.");
+		}
+		const displayOrder = options.displayOrder ?? 0;
+		const inputPreview = options.inputPreview ?? this._defaultAgentToolPreview(options.input);
+		const displayJson = options.display !== void 0 ? JSON.stringify(options.display) : null;
+		const inputPreviewJson = inputPreview !== void 0 ? JSON.stringify(inputPreview) : null;
+		const startedAt = Date.now();
+		if (this._activeAgentToolRunCount() >= this.maxConcurrentAgentTools) {
+			const error = `maxConcurrentAgentTools (${this.maxConcurrentAgentTools}) exceeded`;
+			this.sql`
+        INSERT INTO cf_agent_tool_runs (
+          run_id, parent_tool_call_id, agent_type, input_preview,
+          input_redacted, status, error_message, display_metadata,
+          display_order, started_at, completed_at
+        ) VALUES (
+          ${runId}, ${options.parentToolCallId ?? null}, ${agentType},
+          ${inputPreviewJson}, 1, 'error', ${error}, ${displayJson},
+          ${displayOrder}, ${startedAt}, ${Date.now()}
+        )
+      `;
+			this._broadcastAgentToolEvent(options.parentToolCallId, 0, {
+				kind: "started",
+				runId,
+				agentType,
+				inputPreview,
+				order: displayOrder,
+				display: options.display
+			});
+			this._broadcastAgentToolEvent(options.parentToolCallId, 1, {
+				kind: "error",
+				runId,
+				error
+			});
+			return {
+				runId,
+				agentType,
+				status: "error",
+				error
+			};
+		}
+		this.sql`
+      INSERT INTO cf_agent_tool_runs (
+        run_id, parent_tool_call_id, agent_type, input_preview,
+        input_redacted, status, display_metadata, display_order, started_at
+      ) VALUES (
+        ${runId}, ${options.parentToolCallId ?? null}, ${agentType},
+        ${inputPreviewJson}, 1, 'starting', ${displayJson}, ${displayOrder},
+        ${startedAt}
+      )
+    `;
+		const runInfo = {
+			runId,
+			parentToolCallId: options.parentToolCallId,
+			agentType,
+			inputPreview,
+			status: "starting",
+			display: options.display,
+			displayOrder,
+			startedAt
+		};
+		await this.onAgentToolStart(runInfo);
+		this._broadcastAgentToolEvent(options.parentToolCallId, 0, {
+			kind: "started",
+			runId,
+			agentType,
+			inputPreview,
+			order: displayOrder,
+			display: options.display
+		});
+		const child = await this.subAgent(cls, runId);
+		const adapter = this._asAgentToolChildAdapter(child);
+		const childStart = await adapter.startAgentToolRun(options.input, { runId });
+		this._markAgentToolRunning(runId);
+		let sequence = 1;
+		let parentAbortListener;
+		if (options.signal) if (options.signal.aborted) {
+			await adapter.cancelAgentToolRun(runId, options.signal.reason);
+			const result = {
+				runId,
+				agentType,
+				status: "aborted",
+				error: options.signal.reason instanceof Error ? options.signal.reason.message : String(options.signal.reason ?? "cancelled")
+			};
+			this._updateAgentToolTerminal(runId, result);
+			this._broadcastAgentToolTerminal(options.parentToolCallId, sequence, result);
+			await this.onAgentToolFinish({
+				...runInfo,
+				status: "aborted",
+				completedAt: Date.now()
+			}, result);
+			return result;
+		} else {
+			parentAbortListener = () => {
+				adapter.cancelAgentToolRun(runId, options.signal?.reason);
+			};
+			options.signal.addEventListener("abort", parentAbortListener, { once: true });
+		}
+		try {
+			if (adapter.tailAgentToolRun) {
+				const stream = await adapter.tailAgentToolRun(runId, { afterSequence: -1 });
+				sequence = await this._forwardAgentToolStream(stream, options.parentToolCallId, runId, sequence, options.signal);
+			} else {
+				const chunks = await adapter.getAgentToolChunks(runId);
+				sequence = this._broadcastAgentToolChunks(options.parentToolCallId, runId, chunks, sequence);
+			}
+			if (options.signal?.aborted) {
+				await adapter.cancelAgentToolRun(runId, options.signal.reason);
+				const result = {
+					runId,
+					agentType,
+					status: "aborted",
+					error: options.signal.reason instanceof Error ? options.signal.reason.message : String(options.signal.reason ?? "cancelled")
+				};
+				this._updateAgentToolTerminal(runId, result);
+				this._broadcastAgentToolTerminal(options.parentToolCallId, sequence, result);
+				await this.onAgentToolFinish({
+					...runInfo,
+					status: "aborted",
+					completedAt: Date.now()
+				}, result);
+				return result;
+			}
+			const inspection = await adapter.inspectAgentToolRun(runId) ?? childStart;
+			const result = this._terminalResultFromInspection(agentType, inspection);
+			this._updateAgentToolTerminal(runId, result, inspection.completedAt);
+			this._broadcastAgentToolTerminal(options.parentToolCallId, sequence, result);
+			await this.onAgentToolFinish({
+				...runInfo,
+				status: result.status,
+				completedAt: Date.now()
+			}, result);
+			return result;
+		} catch (error) {
+			if (options.signal?.aborted) {
+				await adapter.cancelAgentToolRun(runId, options.signal.reason);
+				const result = {
+					runId,
+					agentType,
+					status: "aborted",
+					error: options.signal.reason instanceof Error ? options.signal.reason.message : String(options.signal.reason ?? "cancelled")
+				};
+				this._updateAgentToolTerminal(runId, result);
+				this._broadcastAgentToolTerminal(options.parentToolCallId, sequence, result);
+				await this.onAgentToolFinish({
+					...runInfo,
+					status: "aborted",
+					completedAt: Date.now()
+				}, result);
+				return result;
+			}
+			const result = {
+				runId,
+				agentType,
+				status: "error",
+				error: error instanceof Error ? error.message : String(error)
+			};
+			this._updateAgentToolTerminal(runId, result);
+			this._broadcastAgentToolTerminal(options.parentToolCallId, sequence, result);
+			await this.onAgentToolFinish({
+				...runInfo,
+				status: "error",
+				completedAt: Date.now()
+			}, result);
+			return result;
+		} finally {
+			if (parentAbortListener && options.signal) options.signal.removeEventListener("abort", parentAbortListener);
+		}
+	}
+	hasAgentToolRun(classOrName, runId) {
+		const agentType = typeof classOrName === "string" ? classOrName : classOrName.name;
+		return (this.sql`
+      SELECT COUNT(*) AS n FROM cf_agent_tool_runs
+      WHERE run_id = ${runId} AND agent_type = ${agentType}
+    `[0]?.n ?? 0) > 0;
+	}
+	async clearAgentToolRuns(options) {
+		const rows = this.sql`
+      SELECT run_id, agent_type, status FROM cf_agent_tool_runs
+      ORDER BY started_at ASC
+    `;
+		const statusFilter = options?.status ? new Set(options.status) : null;
+		const retained = rows.filter((row) => {
+			if (statusFilter && !statusFilter.has(row.status)) return false;
+			if (options?.olderThan !== void 0) {
+				const full = this._readAgentToolRun(row.run_id);
+				if (!full || full.started_at >= options.olderThan) return false;
+			}
+			return true;
+		});
+		for (const row of retained) {
+			try {
+				const cls = this._agentToolClassByName(row.agent_type);
+				if (row.status === "starting" || row.status === "running") {
+					const child = await this.subAgent(cls, row.run_id);
+					await this._asAgentToolChildAdapter(child).cancelAgentToolRun(row.run_id, "clearing agent tool run");
+				}
+				await this.deleteSubAgent(cls, row.run_id);
+			} catch {}
+			this.sql`
+        DELETE FROM cf_agent_tool_runs WHERE run_id = ${row.run_id}
+      `;
+		}
+	}
+	_isAgentToolTerminal(status) {
+		return status === "completed" || status === "error" || status === "aborted" || status === "interrupted";
+	}
+	_activeAgentToolRunCount() {
+		return this.sql`
+      SELECT COUNT(*) AS n FROM cf_agent_tool_runs
+      WHERE status IN ('starting', 'running')
+    `[0]?.n ?? 0;
+	}
+	_defaultAgentToolPreview(input) {
+		if (typeof input === "string") return input.slice(0, 500);
+		if (input === null || input === void 0) return input;
+		try {
+			const json = JSON.stringify(input);
+			return json.length > 500 ? `${json.slice(0, 497)}...` : json;
+		} catch {
+			return String(input).slice(0, 500);
+		}
+	}
+	_readAgentToolRun(runId) {
+		return this.sql`
+      SELECT run_id, parent_tool_call_id, agent_type, input_preview, status,
+             summary, output_json, error_message, display_metadata, display_order,
+             started_at, completed_at
+      FROM cf_agent_tool_runs
+      WHERE run_id = ${runId}
+      LIMIT 1
+    `[0] ?? null;
+	}
+	_resultFromAgentToolRow(row) {
+		const output = this._parseAgentToolJson(row.output_json);
+		return {
+			runId: row.run_id,
+			agentType: row.agent_type,
+			status: row.status,
+			...output !== void 0 ? { output } : {},
+			...row.summary !== null ? { summary: row.summary } : {},
+			...row.error_message !== null ? { error: row.error_message } : {}
+		};
+	}
+	_terminalResultFromInspection(agentType, inspection) {
+		if (inspection.status === "completed") return {
+			runId: inspection.runId,
+			agentType,
+			status: "completed",
+			output: inspection.output,
+			summary: inspection.summary
+		};
+		if (inspection.status === "aborted") return {
+			runId: inspection.runId,
+			agentType,
+			status: "aborted",
+			error: inspection.error
+		};
+		return {
+			runId: inspection.runId,
+			agentType,
+			status: "error",
+			error: inspection.error ?? "Agent tool run failed"
+		};
+	}
+	_updateAgentToolTerminal(runId, result, completedAt = Date.now()) {
+		this.sql`
+      UPDATE cf_agent_tool_runs
+      SET status = ${result.status},
+          summary = ${result.summary ?? null},
+          output_json = ${this._stringifyAgentToolOutput(result.output)},
+          error_message = ${result.error ?? null},
+          completed_at = ${completedAt}
+      WHERE run_id = ${runId}
+        AND status NOT IN ('completed', 'error', 'aborted', 'interrupted')
+    `;
+		if (result.status === "completed" && result.output !== void 0) this.sql`
+        UPDATE cf_agent_tool_runs
+        SET output_json = COALESCE(output_json, ${this._stringifyAgentToolOutput(result.output)}),
+            summary = COALESCE(summary, ${result.summary ?? null})
+        WHERE run_id = ${runId} AND status = 'completed'
+      `;
+	}
+	_markAgentToolRunning(runId) {
+		this.sql`
+      UPDATE cf_agent_tool_runs
+      SET status = 'running'
+      WHERE run_id = ${runId} AND status = 'starting'
+    `;
+	}
+	_parseAgentToolJson(value) {
+		if (value === null) return void 0;
+		try {
+			return JSON.parse(value);
+		} catch {
+			return value;
+		}
+	}
+	_stringifyAgentToolOutput(output) {
+		if (output === void 0) return null;
+		const json = JSON.stringify(output);
+		return json === void 0 ? null : json;
+	}
+	_broadcastAgentToolEvent(parentToolCallId, sequence, event, replay, connection) {
+		const message = {
+			type: "agent-tool-event",
+			parentToolCallId,
+			sequence,
+			event,
+			...replay ? { replay } : {}
+		};
+		const body = JSON.stringify(message);
+		if (connection) connection.send(body);
+		else this.broadcast(body);
+	}
+	_broadcastAgentToolChunks(parentToolCallId, runId, chunks, sequence, replay, connection) {
+		let next = sequence;
+		for (const chunk of chunks) this._broadcastAgentToolEvent(parentToolCallId, next++, {
+			kind: "chunk",
+			runId,
+			body: chunk.body
+		}, replay, connection);
+		return next;
+	}
+	async _forwardAgentToolStream(stream, parentToolCallId, runId, sequence, signal) {
+		let next = sequence;
+		if (signal?.aborted) return next;
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		let bufferedBytes = "";
+		let abortListener;
+		if (signal) {
+			abortListener = () => {};
+			signal.addEventListener("abort", abortListener, { once: true });
+		}
+		try {
+			const forwardChunk = (chunk) => {
+				this._broadcastAgentToolEvent(parentToolCallId, next++, {
+					kind: "chunk",
+					runId,
+					body: chunk.body
+				});
+			};
+			const forwardLine = (line) => {
+				try {
+					const chunk = JSON.parse(line);
+					if (typeof chunk.body === "string") forwardChunk(chunk);
+				} catch {}
+			};
+			const flushBufferedBytes = (final = false) => {
+				while (true) {
+					const newline = bufferedBytes.indexOf("\n");
+					if (newline === -1) break;
+					const line = bufferedBytes.slice(0, newline).trim();
+					bufferedBytes = bufferedBytes.slice(newline + 1);
+					if (line.length > 0) forwardLine(line);
+				}
+				if (final && bufferedBytes.trim().length > 0) {
+					forwardLine(bufferedBytes);
+					bufferedBytes = "";
+				}
+			};
+			while (true) {
+				let readResult;
+				try {
+					readResult = await reader.read();
+				} catch (error) {
+					if (signal?.aborted) break;
+					throw error;
+				}
+				const { done, value } = readResult;
+				if (done) {
+					bufferedBytes += decoder.decode();
+					flushBufferedBytes(true);
+					break;
+				}
+				if (value instanceof Uint8Array) {
+					bufferedBytes += decoder.decode(value, { stream: true });
+					flushBufferedBytes();
+				} else forwardChunk(value);
+			}
+		} finally {
+			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
+			reader.releaseLock();
+		}
+		return next;
+	}
+	_broadcastAgentToolTerminal(parentToolCallId, sequence, result, replay, connection) {
+		if (result.status === "completed") this._broadcastAgentToolEvent(parentToolCallId, sequence, {
+			kind: "finished",
+			runId: result.runId,
+			summary: result.summary ?? ""
+		}, replay, connection);
+		else if (result.status === "aborted") this._broadcastAgentToolEvent(parentToolCallId, sequence, {
+			kind: "aborted",
+			runId: result.runId,
+			reason: result.error
+		}, replay, connection);
+		else if (result.status === "interrupted") this._broadcastAgentToolEvent(parentToolCallId, sequence, {
+			kind: "interrupted",
+			runId: result.runId,
+			error: result.error ?? "Agent tool run was interrupted"
+		}, replay, connection);
+		else this._broadcastAgentToolEvent(parentToolCallId, sequence, {
+			kind: "error",
+			runId: result.runId,
+			error: result.error ?? "Agent tool run failed"
+		}, replay, connection);
+	}
+	_asAgentToolChildAdapter(child) {
+		const candidate = child;
+		if (typeof candidate.startAgentToolRun !== "function" || typeof candidate.cancelAgentToolRun !== "function" || typeof candidate.inspectAgentToolRun !== "function" || typeof candidate.getAgentToolChunks !== "function") throw new Error("Agent tool child must implement the framework agent-tool adapter. Use a @cloudflare/think Think subclass or an AIChatAgent subclass.");
+		return candidate;
+	}
+	_agentToolClassByName(className) {
+		const cls = this.ctx.exports?.[className];
+		if (!cls) throw new Error(`Agent tool class "${className}" is not exported.`);
+		return cls;
+	}
+	async _replayAndInterruptAgentToolRun(cls, row, message) {
+		const parentToolCallId = row.parent_tool_call_id ?? void 0;
+		let sequence = 1;
+		try {
+			const child = await this.subAgent(cls, row.run_id);
+			const chunks = await this._asAgentToolChildAdapter(child).getAgentToolChunks(row.run_id);
+			sequence = this._broadcastAgentToolChunks(parentToolCallId, row.run_id, chunks, sequence);
+		} catch {}
+		const result = {
+			runId: row.run_id,
+			agentType: row.agent_type,
+			status: "interrupted",
+			error: message
+		};
+		this._updateAgentToolTerminal(row.run_id, result);
+		this._broadcastAgentToolTerminal(parentToolCallId, sequence, result);
+		return result;
+	}
+	async _replayAgentToolRuns(connection) {
+		const rows = this.sql`
+      SELECT run_id, parent_tool_call_id, agent_type, input_preview, status,
+             summary, output_json, error_message, display_metadata, display_order
+      FROM cf_agent_tool_runs
+      ORDER BY started_at ASC
+    `;
+		for (const row of rows) {
+			const parentToolCallId = row.parent_tool_call_id ?? void 0;
+			let sequence = 0;
+			this._broadcastAgentToolEvent(parentToolCallId, sequence++, {
+				kind: "started",
+				runId: row.run_id,
+				agentType: row.agent_type,
+				inputPreview: this._parseAgentToolJson(row.input_preview),
+				order: row.display_order,
+				display: this._parseAgentToolJson(row.display_metadata)
+			}, true, connection);
+			try {
+				const child = await this.subAgent(this._agentToolClassByName(row.agent_type), row.run_id);
+				const chunks = await this._asAgentToolChildAdapter(child).getAgentToolChunks(row.run_id);
+				sequence = this._broadcastAgentToolChunks(parentToolCallId, row.run_id, chunks, sequence, true, connection);
+			} catch {}
+			if (this._isAgentToolTerminal(row.status)) this._broadcastAgentToolTerminal(parentToolCallId, sequence, {
+				runId: row.run_id,
+				agentType: row.agent_type,
+				status: row.status,
+				output: this._parseAgentToolJson(row.output_json),
+				summary: row.summary ?? void 0,
+				error: row.error_message ?? void 0
+			}, true, connection);
+		}
+	}
+	async _reconcileAgentToolRuns() {
+		const rows = this.sql`
+      SELECT run_id, agent_type FROM cf_agent_tool_runs
+      WHERE status IN ('starting', 'running')
+      ORDER BY started_at ASC
+    `;
+		for (const row of rows) try {
+			const cls = this._agentToolClassByName(row.agent_type);
+			if (!this.hasSubAgent(cls, row.run_id)) {
+				this._updateAgentToolTerminal(row.run_id, {
+					runId: row.run_id,
+					agentType: row.agent_type,
+					status: "interrupted",
+					error: "Agent tool child was not found during parent recovery."
+				});
+				continue;
+			}
+			const child = await this.subAgent(cls, row.run_id);
+			const inspection = await this._asAgentToolChildAdapter(child).inspectAgentToolRun(row.run_id);
+			if (!inspection || inspection.status === "running" || inspection.status === "starting") this._updateAgentToolTerminal(row.run_id, {
+				runId: row.run_id,
+				agentType: row.agent_type,
+				status: "interrupted",
+				error: "Agent tool run was still running, but live-tail reattachment is not supported in this runtime."
+			});
+			else this._updateAgentToolTerminal(row.run_id, this._terminalResultFromInspection(row.agent_type, inspection), inspection.completedAt);
+		} catch {
+			this._updateAgentToolTerminal(row.run_id, {
+				runId: row.run_id,
+				agentType: row.agent_type,
+				status: "interrupted",
+				error: "Agent tool run could not be inspected during parent recovery."
+			});
+		}
+	}
 	/**
 	* Shared facet resolution — takes a CamelCase class name string
 	* (matching `ctx.exports`) rather than a class reference. Both
@@ -2289,7 +3349,14 @@ var Agent = class Agent extends Server {
 			id: facetId
 		}));
 		const childParentPath = this.selfPath;
-		await stub._cf_initAsFacet(name, childParentPath);
+		await __DO_NOT_USE_WILL_BREAK__agentContext.run({
+			agent: this,
+			connection: void 0,
+			request: void 0,
+			email: void 0
+		}, async () => {
+			await stub._cf_initAsFacet(name, childParentPath);
+		});
 		this._recordSubAgent(className, name);
 		return stub;
 	}
@@ -2320,10 +3387,16 @@ var Agent = class Agent extends Server {
 	* @param cls The Agent subclass used when creating the child
 	* @param name Name of the child to delete
 	*/
-	deleteSubAgent(cls, name) {
+	async deleteSubAgent(cls, name) {
 		const ctx = this.ctx;
 		if (!ctx.facets) throw new Error("deleteSubAgent() is not supported in this runtime — `ctx.facets` is unavailable. Update to the latest `compatibility_date` in your wrangler.jsonc.");
 		const facetKey = `${cls.name}\0${name}`;
+		const childPath = [...this.selfPath, {
+			className: cls.name,
+			name
+		}];
+		if (this._isFacet) await (await this._rootAlarmOwner())._cf_cleanupFacetPrefix(childPath);
+		else await this._cf_cleanupFacetPrefix(childPath);
 		try {
 			ctx.facets.delete(facetKey);
 		} catch {}
@@ -2383,16 +3456,28 @@ var Agent = class Agent extends Server {
 		}));
 	}
 	/**
-	* Destroy the Agent, removing all state and scheduled tasks
+	* Destroy the Agent, removing all state and scheduled tasks.
+	*
+	* On a top-level agent: drops every table, clears the alarm, and
+	* aborts the isolate.
+	*
+	* On a sub-agent (facet): delegates teardown to the immediate
+	* parent so the parent-owned schedule rows for this sub-agent
+	* (and any of its descendants) are cancelled, the parent's
+	* `cf_agents_sub_agents` registry entry is cleared, and
+	* `ctx.facets.delete` wipes the facet's own storage. The
+	* `ctx.facets.delete` call aborts this isolate, so this method
+	* may not return cleanly when invoked from inside the facet —
+	* callers should treat it as fire-and-forget.
 	*/
 	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`;
-		this.sql`DROP TABLE IF EXISTS cf_agents_sub_agents`;
-		if (!this._isFacet) await this.ctx.storage.deleteAlarm();
+		if (this._isFacet) {
+			this._emit("destroy");
+			await (await this._rootAlarmOwner())._cf_destroyDescendantFacet(this.selfPath);
+			return;
+		}
+		this._dropInternalTablesForDestroy();
+		await this.ctx.storage.deleteAlarm();
 		await this.ctx.storage.deleteAll();
 		this._disposables.dispose();
 		await this.mcp.dispose();
@@ -2402,6 +3487,18 @@ var Agent = class Agent extends Server {
 		}, 0);
 		this._emit("destroy");
 	}
+	/** @internal Drop every internal Agents SDK table during top-level destroy. */
+	_dropInternalTablesForDestroy() {
+		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`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_sub_agents`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_runs`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_facet_runs`;
+		this.sql`DROP TABLE IF EXISTS cf_agent_tool_runs`;
+	}
 	/**
 	* Check if a method is callable
 	* @param method The method name to check