agents 0.11.9 → 0.12.1

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";
@@ -40,6 +40,52 @@ var SqlError = class extends Error {
 		this.query = query;
 	}
 };
+var _connection2 = /* @__PURE__ */ new WeakMap();
+var _broadcast = /* @__PURE__ */ new WeakMap();
+var SubAgentConnectionBridge = class extends RpcTarget {
+	constructor(connection, broadcast) {
+		super();
+		_classPrivateFieldInitSpec(this, _connection2, void 0);
+		_classPrivateFieldInitSpec(this, _broadcast, void 0);
+		_classPrivateFieldSet2(_connection2, this, connection);
+		_classPrivateFieldSet2(_broadcast, this, broadcast);
+	}
+	send(message) {
+		_classPrivateFieldGet2(_connection2, this).send(message);
+	}
+	close(code, reason) {
+		_classPrivateFieldGet2(_connection2, this).close(code, reason);
+	}
+	setState(state) {
+		return _classPrivateFieldGet2(_connection2, this).setState(state);
+	}
+	broadcast(ownerPath, message, without) {
+		_classPrivateFieldGet2(_broadcast, this)?.call(this, ownerPath, message, without);
+	}
+};
+var _root = /* @__PURE__ */ new WeakMap();
+var _connectionId = /* @__PURE__ */ new WeakMap();
+var RootSubAgentConnectionBridge = class {
+	constructor(root, connectionId) {
+		_classPrivateFieldInitSpec(this, _root, void 0);
+		_classPrivateFieldInitSpec(this, _connectionId, void 0);
+		_classPrivateFieldSet2(_root, this, root);
+		_classPrivateFieldSet2(_connectionId, this, connectionId);
+	}
+	send(message) {
+		_classPrivateFieldGet2(_root, this)._cf_sendToSubAgentConnection(_classPrivateFieldGet2(_connectionId, this), message);
+	}
+	close(code, reason) {
+		_classPrivateFieldGet2(_root, this)._cf_closeSubAgentConnection(_classPrivateFieldGet2(_connectionId, this), code, reason);
+	}
+	setState(state) {
+		_classPrivateFieldGet2(_root, this)._cf_setSubAgentConnectionState(_classPrivateFieldGet2(_connectionId, this), state);
+		return state;
+	}
+	broadcast(ownerPath, message, without) {
+		_classPrivateFieldGet2(_root, this)._cf_broadcastToSubAgent(ownerPath, message, without);
+	}
+};
 /**
 * Decorator that marks a method as callable by clients
 * @param metadata Optional metadata about the callable method
@@ -74,7 +120,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";
@@ -99,13 +145,30 @@ const CF_READONLY_KEY = "_cf_readonly";
 */
 const CF_NO_PROTOCOL_KEY = "_cf_no_protocol";
 /**
+* Internal key used to store voice call state in connection state.
+* Used by the voice mixin to track whether a connection is in an active call.
+*/
+const CF_VOICE_IN_CALL_KEY = "_cf_voiceInCall";
+/**
+* Internal key used to remember the outer `/sub/...` URL for a
+* WebSocket accepted by the parent on behalf of a child facet.
+* Hibernated events then wake the parent, which forwards frames to
+* the child over serializable RPC while keeping native WebSocket I/O
+* parent-owned.
+*/
+const CF_SUB_AGENT_OUTER_URL_KEY = "_cf_subAgentOuterUrl";
+const CF_SUB_AGENT_TAGS_KEY = "_cf_subAgentTags";
+const SUB_AGENT_OUTER_URL_HEADER = "x-cf-agents-subagent-url";
+/**
 * The set of all internal keys stored in connection state that must be
 * hidden from user code and preserved across setState calls.
 */
 const CF_INTERNAL_KEYS = new Set([
 	CF_READONLY_KEY,
 	CF_NO_PROTOCOL_KEY,
-	"_cf_voiceInCall"
+	CF_VOICE_IN_CALL_KEY,
+	CF_SUB_AGENT_OUTER_URL_KEY,
+	CF_SUB_AGENT_TAGS_KEY
 ]);
 /** Check if a raw connection state object contains any internal keys. */
 function rawHasInternalKeys(raw) {
@@ -218,13 +281,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 +446,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 +462,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 +483,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 +538,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 +586,20 @@ var Agent = class Agent extends Server {
 		this._rawStateAccessors = /* @__PURE__ */ new WeakMap();
 		this._persistenceHookMode = "none";
 		this._isFacet = false;
+		this._suppressProtocolBroadcasts = false;
+		this._cf_virtualSubAgentConnections = /* @__PURE__ */ new Map();
 		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();
@@ -541,6 +651,7 @@ var Agent = class Agent extends Server {
 		};
 		const _onMessage = this.onMessage.bind(this);
 		this.onMessage = async (connection, message) => {
+			if (await this._cf_forwardSubAgentWebSocketMessage(connection, message)) return;
 			this._ensureConnectionWrapped(connection);
 			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
 				agent: this,
@@ -632,8 +743,11 @@ var Agent = class Agent extends Server {
 			});
 		};
 		const _onConnect = this.onConnect.bind(this);
-		this.onConnect = (connection, ctx) => {
+		this.onConnect = async (connection, ctx) => {
 			this._ensureConnectionWrapped(connection);
+			const subAgentOuterUrl = ctx.request.headers.get(SUB_AGENT_OUTER_URL_HEADER);
+			if (subAgentOuterUrl) this._unsafe_setConnectionFlag(connection, CF_SUB_AGENT_OUTER_URL_KEY, subAgentOuterUrl);
+			if (await this._cf_forwardSubAgentWebSocketConnect(connection, ctx.request, { gate: false })) return;
 			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
 				agent: this,
 				connection,
@@ -666,11 +780,13 @@ 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));
 			});
 		};
 		const _onClose = this.onClose.bind(this);
-		this.onClose = (connection, code, reason, wasClean) => {
+		this.onClose = async (connection, code, reason, wasClean) => {
+			if (await this._cf_forwardSubAgentWebSocketClose(connection, code, reason, wasClean)) return;
 			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
 				agent: this,
 				connection,
@@ -696,12 +812,18 @@ var Agent = class Agent extends Server {
 				if (await this.ctx.storage.get("cf_agents_is_facet")) this._isFacet = true;
 				const storedParentPath = await this.ctx.storage.get("cf_agents_parent_path");
 				if (isValidParentPath(storedParentPath)) this._parentPath = storedParentPath;
+				try {
+					await this._cf_hydrateSubAgentConnectionsFromRoot();
+				} catch (error) {
+					console.warn("[Agent] Unable to hydrate sub-agent WebSocket connections:", error);
+				}
 				await this._tryCatch(async () => {
 					await this.mcp.restoreConnectionsFromStorage(this.name);
 					await this._restoreRpcMcpServers();
 					this.broadcastMcpServers();
 					this._checkOrphanedWorkflows();
 					await this._checkRunFibers();
+					await this._reconcileAgentToolRuns();
 					this._insideOnStart = true;
 					this._warnedScheduleInOnStart.clear();
 					try {
@@ -743,6 +865,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 +1497,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 +1559,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 +1656,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 +1729,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,44 +1902,245 @@ 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
+	* List schedule rows owned by a descendant facet, scoped by
+	* `owner_path_key` so siblings remain isolated from each other.
+	* @internal
+	*/
+	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();
+		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 }`.
 	*
-	* 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.
+	* In facets, delegates the physical heartbeat to the root parent
+	* because facets do not have independent alarm slots.
 	*
 	* @example
 	* ```ts
@@ -1719,7 +2153,19 @@ var Agent = class Agent extends Server {
 	* ```
 	*/
 	async keepAlive() {
-		if (this._isFacet) return () => {};
+		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;
@@ -1773,8 +2219,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 +2247,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 +2320,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 +2523,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 +2572,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 +2584,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}
@@ -2045,8 +2651,349 @@ var Agent = class Agent extends Server {
 		});
 		if (decision instanceof Response) return decision;
 		const forwardReq = decision instanceof Request ? decision : request;
+		if (request.headers.get("Upgrade")?.toLowerCase() === "websocket") {
+			const acceptHeaders = new Headers(forwardReq.headers);
+			const routedUrl = new URL(forwardReq.url);
+			routedUrl.pathname = new URL(request.url).pathname;
+			acceptHeaders.set(SUB_AGENT_OUTER_URL_HEADER, routedUrl.toString());
+			return super.fetch(new Request(forwardReq, { headers: acceptHeaders }));
+		}
 		return this._cf_forwardToFacet(forwardReq, match);
 	}
+	broadcast(msg, without) {
+		if (this._isFacet) {
+			this._cf_broadcastToParentSubAgent(msg, without);
+			return;
+		}
+		for (const connection of super.getConnections()) {
+			if (without?.includes(connection.id)) continue;
+			if (this._cf_connectionHasSubAgentTarget(connection)) continue;
+			connection.send(msg);
+		}
+	}
+	getConnection(id) {
+		if (this._isFacet) {
+			const stored = this._cf_virtualSubAgentConnections.get(id);
+			if (stored) return this._cf_createSubAgentBridgeConnection(stored.bridge, stored.meta);
+		}
+		const connection = super.getConnection(id);
+		if (!connection || this._cf_connectionHasSubAgentTarget(connection)) return;
+		return connection;
+	}
+	*getConnections(tag) {
+		if (this._isFacet) {
+			for (const stored of this._cf_virtualSubAgentConnections.values()) if (!tag || stored.meta.tags.includes(tag)) yield this._cf_createSubAgentBridgeConnection(stored.bridge, stored.meta);
+		}
+		for (const connection of super.getConnections(tag)) {
+			if (this._cf_connectionHasSubAgentTarget(connection)) continue;
+			yield connection;
+		}
+	}
+	async _cf_broadcastToParentSubAgent(message, without) {
+		if (this._cf_currentSubAgentBridge) {
+			this._cf_currentSubAgentBridge.broadcast(this.selfPath, message, without);
+			return;
+		}
+		await (await this._rootAlarmOwner())._cf_broadcastToSubAgent(this.selfPath, message, without);
+	}
+	async _cf_broadcastToSubAgent(ownerPath, message, without) {
+		if (this._isFacet && this._cf_currentSubAgentBridge) {
+			this._cf_currentSubAgentBridge.broadcast(ownerPath, message, without);
+			return;
+		}
+		for (const connection of super.getConnections()) {
+			if (without?.includes(connection.id)) continue;
+			const targetPath = this._cf_subAgentTargetPath(connection);
+			if (!targetPath) continue;
+			if (!this._isSameAgentPath(targetPath, ownerPath)) continue;
+			connection.send(message);
+		}
+	}
+	async _cf_subAgentConnectionMetas(ownerPath) {
+		const metas = [];
+		for (const connection of super.getConnections()) {
+			const meta = this._cf_subAgentConnectionMetaForPath(connection, ownerPath);
+			if (meta) metas.push(meta);
+		}
+		return metas;
+	}
+	async _cf_sendToSubAgentConnection(connectionId, message) {
+		const connection = super.getConnection(connectionId);
+		if (!connection || !this._cf_connectionHasSubAgentTarget(connection)) return;
+		connection.send(message);
+	}
+	async _cf_closeSubAgentConnection(connectionId, code, reason) {
+		const connection = super.getConnection(connectionId);
+		if (!connection || !this._cf_connectionHasSubAgentTarget(connection)) return;
+		connection.close(code, reason);
+	}
+	async _cf_setSubAgentConnectionState(connectionId, state) {
+		const connection = super.getConnection(connectionId);
+		if (!connection || !this._cf_connectionHasSubAgentTarget(connection)) return null;
+		this._ensureConnectionWrapped(connection);
+		connection.setState(state);
+		return this._cf_getForwardedSubAgentState(connection);
+	}
+	_cf_subAgentConnectionMetaForPath(connection, ownerPath) {
+		this._ensureConnectionWrapped(connection);
+		const outerUri = this._unsafe_getConnectionFlag(connection, CF_SUB_AGENT_OUTER_URL_KEY);
+		if (typeof outerUri !== "string") return null;
+		const target = this._cf_subAgentPathFromOuterUri(outerUri, ownerPath);
+		if (!target) return null;
+		const raw = this._cf_getRawConnectionState(connection);
+		const rawTags = raw != null && typeof raw === "object" ? raw[CF_SUB_AGENT_TAGS_KEY] : void 0;
+		const tags = Array.isArray(rawTags) ? rawTags.filter((tag) => typeof tag === "string") : [...connection.tags];
+		return {
+			id: connection.id,
+			uri: target.uri,
+			tags,
+			state: this._cf_getForwardedSubAgentState(connection)
+		};
+	}
+	_cf_subAgentTargetPath(connection) {
+		this._ensureConnectionWrapped(connection);
+		const outerUri = this._unsafe_getConnectionFlag(connection, CF_SUB_AGENT_OUTER_URL_KEY);
+		if (typeof outerUri !== "string") return null;
+		return this._cf_subAgentPathFromOuterUri(outerUri)?.path ?? null;
+	}
+	_cf_subAgentPathFromOuterUri(outerUri, stopAt) {
+		const ctx = this.ctx;
+		const knownClasses = ctx.exports ? Object.keys(ctx.exports) : void 0;
+		const path = [...this.selfPath];
+		let currentUrl = outerUri;
+		while (true) {
+			const match = parseSubAgentPath(currentUrl, { knownClasses });
+			if (!match) break;
+			path.push({
+				className: match.childClass,
+				name: match.childName
+			});
+			const rewritten = new URL(currentUrl);
+			rewritten.pathname = match.remainingPath;
+			currentUrl = rewritten.toString();
+			if (stopAt && this._isSameAgentPath(path, stopAt)) return {
+				path,
+				uri: currentUrl
+			};
+		}
+		if (path.length === this.selfPath.length) return null;
+		if (stopAt) return null;
+		return {
+			path,
+			uri: currentUrl
+		};
+	}
+	_isSameAgentPath(a, b) {
+		if (a.length !== b.length) return false;
+		return a.every((step, index) => step.className === b[index]?.className && step.name === b[index]?.name);
+	}
+	_cf_connectionHasSubAgentTarget(connection) {
+		this._ensureConnectionWrapped(connection);
+		return typeof this._unsafe_getConnectionFlag(connection, CF_SUB_AGENT_OUTER_URL_KEY) === "string";
+	}
+	_cf_connectionTargetsSubAgent(connection) {
+		if (!connection.uri) return false;
+		const ctx = this.ctx;
+		return parseSubAgentPath(connection.uri, { knownClasses: ctx.exports ? Object.keys(ctx.exports) : void 0 }) !== null;
+	}
+	/**
+	* Returns true when the current request is addressed to a child facet of
+	* this agent rather than to this agent itself.
+	*
+	* Chat-style subclasses wrap `onConnect` before the base Agent forwarding
+	* wrapper runs, so they need a request-level check to avoid sending their
+	* own protocol frames on sockets that are about to be forwarded to a child.
+	*/
+	_cf_requestTargetsSubAgent(request) {
+		const ctx = this.ctx;
+		return parseSubAgentPath(request.url, { knownClasses: ctx.exports ? Object.keys(ctx.exports) : void 0 }) !== null;
+	}
+	async _cf_forwardSubAgentWebSocketConnect(connection, request, options) {
+		const routed = await this._cf_resolveSubAgentConnection(connection, request, options);
+		if (!routed) return false;
+		await routed.child._cf_handleSubAgentWebSocketConnect(this._cf_createSubAgentConnectionBridge(connection), routed.meta);
+		return true;
+	}
+	_cf_createSubAgentConnectionBridge(connection) {
+		return new SubAgentConnectionBridge(connection, (ownerPath, message, without) => {
+			this._cf_broadcastToSubAgent(ownerPath, message, without);
+		});
+	}
+	async _cf_forwardSubAgentWebSocketMessage(connection, message) {
+		const routed = await this._cf_resolveSubAgentConnection(connection);
+		if (!routed) return false;
+		await routed.child._cf_handleSubAgentWebSocketMessage(message, this._cf_createSubAgentConnectionBridge(connection), routed.meta);
+		return true;
+	}
+	async _cf_forwardSubAgentWebSocketClose(connection, code, reason, wasClean) {
+		const routed = await this._cf_resolveSubAgentConnection(connection);
+		if (!routed) return false;
+		await routed.child._cf_handleSubAgentWebSocketClose(code, reason, wasClean, this._cf_createSubAgentConnectionBridge(connection), routed.meta);
+		return true;
+	}
+	async _cf_resolveSubAgentConnection(connection, request, options = { gate: false }) {
+		this._ensureConnectionWrapped(connection);
+		const outerUri = this._unsafe_getConnectionFlag(connection, CF_SUB_AGENT_OUTER_URL_KEY);
+		const uri = typeof outerUri === "string" ? outerUri : connection.uri;
+		if (!uri) return null;
+		const ctx = this.ctx;
+		let match = parseSubAgentPath(uri, { knownClasses: ctx.exports ? Object.keys(ctx.exports) : void 0 });
+		if (!match) return null;
+		if (this._ParentClass.name === match.childClass && this.name === match.childName) {
+			const tailUri = new URL(uri);
+			tailUri.pathname = match.remainingPath;
+			match = parseSubAgentPath(tailUri.toString(), { knownClasses: ctx.exports ? Object.keys(ctx.exports) : void 0 });
+			if (!match) return null;
+		}
+		let forwardReq = request;
+		if (request && options.gate) {
+			const decision = await this.onBeforeSubAgent(request, {
+				className: match.childClass,
+				name: match.childName
+			});
+			if (decision instanceof Response) {
+				connection.close(1008, "Sub-agent connection rejected");
+				return null;
+			}
+			forwardReq = decision instanceof Request ? decision : request;
+		}
+		const child = await this._cf_resolveSubAgent(match.childClass, match.childName);
+		const childUri = new URL(forwardReq?.url ?? uri);
+		childUri.pathname = match.remainingPath;
+		const raw = this._cf_getRawConnectionState(connection);
+		const rawTags = raw != null && typeof raw === "object" ? raw[CF_SUB_AGENT_TAGS_KEY] : void 0;
+		const tags = Array.isArray(rawTags) ? rawTags.filter((tag) => typeof tag === "string") : [...connection.tags];
+		return {
+			child,
+			meta: {
+				id: connection.id,
+				uri: childUri.toString(),
+				tags,
+				state: this._cf_getForwardedSubAgentState(connection),
+				requestHeaders: forwardReq ? [...forwardReq.headers] : void 0
+			}
+		};
+	}
+	async _cf_handleSubAgentWebSocketConnect(bridge, meta) {
+		await this._cf_runWithSubAgentBridge(bridge, async () => {
+			const connection = this._cf_createSubAgentBridgeConnection(bridge, meta);
+			const request = new Request(meta.uri ?? "http://placeholder/", { headers: meta.requestHeaders });
+			if (await this._cf_forwardSubAgentWebSocketConnect(connection, request, { gate: true })) return;
+			if (this.shouldConnectionBeReadonly(connection, { request })) this.setConnectionReadonly(connection, true);
+			if (!this.shouldSendProtocolMessages(connection, { request })) this._setConnectionNoProtocol(connection);
+			const childTags = await this.getConnectionTags(connection, { request });
+			connection.tags = [connection.id, ...childTags.filter((tag) => tag !== connection.id)];
+			this._cf_storeVirtualSubAgentConnection(bridge, connection);
+			await this.onConnect(connection, { request });
+			this._cf_storeVirtualSubAgentConnection(bridge, connection);
+		});
+	}
+	async _cf_handleSubAgentWebSocketMessage(message, bridge, meta) {
+		const connection = this._cf_createSubAgentBridgeConnection(bridge, meta);
+		this._cf_storeVirtualSubAgentConnection(bridge, connection);
+		await this._cf_runWithSubAgentBridge(bridge, () => this.onMessage(connection, message));
+	}
+	async _cf_handleSubAgentWebSocketClose(code, reason, wasClean, bridge, meta) {
+		const connection = this._cf_createSubAgentBridgeConnection(bridge, meta);
+		this._cf_storeVirtualSubAgentConnection(bridge, connection);
+		await this._cf_runWithSubAgentBridge(bridge, () => this.onClose(connection, code, reason, wasClean));
+		this._cf_virtualSubAgentConnections.delete(meta.id);
+	}
+	async _cf_runWithSubAgentBridge(bridge, fn) {
+		const previous = this._cf_currentSubAgentBridge;
+		this._cf_currentSubAgentBridge = bridge;
+		try {
+			return await fn();
+		} finally {
+			this._cf_currentSubAgentBridge = previous;
+		}
+	}
+	_cf_createSubAgentBridgeConnection(bridge, meta) {
+		let stored = this._cf_virtualSubAgentConnections.get(meta.id);
+		if (stored) {
+			stored.bridge = bridge;
+			stored.meta = meta;
+			if (stored.connection) {
+				stored.connection.uri = meta.uri;
+				stored.connection.tags = meta.tags;
+				return stored.connection;
+			}
+		} else {
+			stored = {
+				bridge,
+				meta
+			};
+			this._cf_virtualSubAgentConnections.set(meta.id, stored);
+		}
+		const getStored = () => this._cf_virtualSubAgentConnections.get(meta.id) ?? stored;
+		const updateStoredState = (nextState) => {
+			const current = this._cf_virtualSubAgentConnections.get(meta.id);
+			if (current) current.meta = {
+				...current.meta,
+				state: nextState
+			};
+		};
+		const connection = {
+			id: meta.id,
+			uri: meta.uri,
+			tags: meta.tags,
+			server: this.name,
+			get state() {
+				return getStored().meta.state;
+			},
+			setState(next) {
+				const currentState = getStored().meta.state;
+				const state = typeof next === "function" ? next(currentState) : next;
+				updateStoredState(state);
+				getStored().bridge.setState(state);
+				return state;
+			},
+			send(message) {
+				getStored().bridge.send(message);
+			},
+			close(code, reason) {
+				getStored().bridge.close(code, reason);
+			},
+			addEventListener() {},
+			removeEventListener() {}
+		};
+		stored.connection = connection;
+		this._ensureConnectionWrapped(connection);
+		return connection;
+	}
+	_cf_storeVirtualSubAgentConnection(bridge, connection) {
+		this._unsafe_setConnectionFlag(connection, CF_SUB_AGENT_TAGS_KEY, [...connection.tags]);
+		const stored = this._cf_virtualSubAgentConnections.get(connection.id);
+		this._cf_virtualSubAgentConnections.set(connection.id, {
+			bridge,
+			meta: {
+				id: connection.id,
+				uri: connection.uri,
+				tags: [...connection.tags],
+				state: this._cf_getRawConnectionState(connection)
+			},
+			connection: stored?.connection ?? connection
+		});
+	}
+	async _cf_hydrateSubAgentConnectionsFromRoot() {
+		if (!this._isFacet || this._parentPath.length === 0) return;
+		const root = await this._rootAlarmOwner();
+		const metas = await root._cf_subAgentConnectionMetas(this.selfPath);
+		for (const meta of metas) this._cf_virtualSubAgentConnections.set(meta.id, {
+			bridge: new RootSubAgentConnectionBridge(root, meta.id),
+			meta
+		});
+	}
+	_cf_getRawConnectionState(connection) {
+		this._ensureConnectionWrapped(connection);
+		return this._rawStateAccessors.get(connection)?.getRaw() ?? null;
+	}
+	_cf_getForwardedSubAgentState(connection) {
+		const raw = this._cf_getRawConnectionState(connection);
+		if (raw == null || typeof raw !== "object") return raw;
+		const { [CF_SUB_AGENT_OUTER_URL_KEY]: _, ...rest } = raw;
+		return Object.keys(rest).length > 0 ? rest : null;
+	}
 	/**
 	* Parent-side middleware hook. Fires before a request is
 	* forwarded into a facet sub-agent. Mirrors `onBeforeConnect` /
@@ -2108,7 +3055,14 @@ var Agent = class Agent extends Server {
 		}
 		const rewritten = new URL(req.url);
 		rewritten.pathname = match.remainingPath;
-		const forwarded = new Request(rewritten, req);
+		const forwardedHeaders = new Headers(req.headers);
+		const forwardedInit = {
+			method: req.method,
+			headers: forwardedHeaders
+		};
+		if (req.headers.get("Upgrade")?.toLowerCase() === "websocket") forwardedHeaders.set(SUB_AGENT_OUTER_URL_HEADER, req.url);
+		if (req.body && req.method !== "GET" && req.method !== "HEAD") forwardedInit.body = await req.arrayBuffer();
+		const forwarded = new Request(rewritten, forwardedInit);
 		return fetcher.fetch(forwarded);
 	}
 	/**
@@ -2136,10 +3090,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 +3110,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 +3219,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 +3771,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 +3809,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 +3878,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 +3909,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