agents 0.24.0 → 0.26.0

package/dist/{src-BNU3ZiJM.js → src-BZeu-SCD.js}

@@ -1,27 +1,27 @@
 import { camelCaseToKebabCase, isInternalJsStubProp } from "./utils.js";
 import { getAgentByName } from "./agent-routing.js";
-import { AGENT_TOOL_MILESTONE_PART } from "./agent-tool-types.js";
+import { AGENT_TOOL_MILESTONE_PART, isAgentToolLifecycleChunk } from "./agent-tool-types.js";
 import { n as getCurrentAgent$1, t as __DO_NOT_USE_WILL_BREAK__agentContext } from "./current-agent-DhoDkSnH.js";
 import "./internal_context.js";
 import { copyCallableMetadata, decoratedMethods, getCallableMetadata, isCallableMethod } from "./callable-decorator.js";
 import "./types.js";
 import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _assertClassBrand, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-DZBYAB34.js";
+import { t as _classPrivateMethodInitSpec } from "./classPrivateMethodInitSpec-qMjJ6sHQ.js";
 import { signAgentHeaders } from "./email.js";
 import { sendAgentEmail } from "./email-send.js";
 import { n as withInvocationScope, r as writeSpanAttributes, t as tracer } from "./cloudflare-Dzvc7V2N.js";
 import { parseSubAgentPath } from "./sub-routing.js";
-import { a as getConnectionFlag, c as isConnectionReadonly, d as setConnectionProtocolEnabled, f as setConnectionReadonly, i as ensureConnectionWrapped, l as registerInternalConnectionKeys, o as getConnectionRawState, s as isConnectionProtocolEnabled, t as WebSockets, u as setConnectionFlag } from "./websockets-D7IzWbZb.js";
+import { a as getConnectionFlag, c as isConnectionReadonly, d as setConnectionProtocolEnabled, f as setConnectionReadonly, i as ensureConnectionWrapped, l as registerInternalConnectionKeys, o as getConnectionRawState, s as isConnectionProtocolEnabled, t as WebSockets, u as setConnectionFlag } from "./websockets-Ci-LZFHH.js";
 import { t as LifecycleCapability } from "./capability-B4WbF81e.js";
-import { t as _classPrivateMethodInitSpec } from "./classPrivateMethodInitSpec-qMjJ6sHQ.js";
-import { a as abortWithoutAlarmRetry, i as setLifecycleRouteTransport, n as setLifecycleEventSink, r as setLifecycleHostInvoker, t as Lifecycle } from "./lifecycle-Mm_jQh7r.js";
+import { a as abortWithoutAlarmRetry, i as setLifecycleRouteTransport, n as setLifecycleEventSink, r as setLifecycleHostInvoker, t as Lifecycle } from "./lifecycle-CFu6OV03.js";
 import { isErrorRetryable, tryN, validateRetryOptions } from "./retries.js";
 import { SqlError } from "./sql-error.js";
 import { a as ensureMcpServerTable, d as DisposableStore, i as normalizeServerId, l as RPC_DO_PREFIX, o as MCPConnectionState, t as MCPClientManager } from "./client-fyQrLGkD.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/client/do-oauth-client-provider.js";
 import { genericObservability } from "./observability/index.js";
-import { n as setSchedulerCallbackResolver, t as Scheduler } from "./scheduler-D_KHqxBa.js";
-import { n as setQueueCallbackResolver, t as Queue } from "./queue-BC9F5cUo.js";
-import { n as setTaskDefinitionResolver, r as setTaskRoutedMemoryLimitHandler, t as Tasks } from "./tasks-D4nLqVSI.js";
+import { n as setSchedulerCallbackResolver, t as Scheduler } from "./scheduler-DZ3xQfeK.js";
+import { n as setQueueCallbackResolver, t as Queue } from "./queue-BB-zfIYF.js";
+import { n as setTaskDefinitionResolver, r as setTaskRoutedMemoryLimitHandler, t as Tasks } from "./tasks-68DESxf0.js";
 import { State } from "./state/index.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { DurableObject, RpcTarget, exports } from "cloudflare:workers";
@@ -296,12 +296,47 @@ function _addColumnIfNotExists(sql) {
 */
 const CF_SUB_AGENT_OUTER_URL_KEY = "_cf_subAgentOuterUrl";
 const CF_SUB_AGENT_TAGS_KEY = "_cf_subAgentTags";
+/**
+* Set on a socket closed because its sub-agent was deleted. Its late
+* message/close events are dropped, so they can't reach a same-name
+* replacement created after the delete. Storage-frozen — never rename.
+*/
+const CF_SUB_AGENT_DELETED_KEY = "_cf_subAgentDeleted";
 /** Wire-frozen internal header carrying the outer URL on WS upgrades. */
 const SUB_AGENT_OUTER_URL_HEADER = "x-cf-agents-subagent-url";
+/**
+* The close frame a rejected sub-agent WebSocket receives in place of the
+* `onBeforeSubAgent` response, which a browser cannot read from a failed
+* handshake. A 4xx closes with `4000 + status`, which clients treat as
+* final; anything else closes with 1011 so the client retries.
+*/
+function subAgentRejectionClose(response) {
+	const { status } = response;
+	return {
+		code: status >= 400 && status < 500 ? 4e3 + status : 1011,
+		reason: `Sub-agent connection rejected (${status})`
+	};
+}
+/**
+* Upgrade a rejected sub-agent WebSocket only to close it, so the client
+* sees a close frame instead of a failed handshake that reconnects forever.
+*/
+function rejectSubAgentWebSocket(response) {
+	const { code, reason } = subAgentRejectionClose(response);
+	const [client, server] = Object.values(new WebSocketPair());
+	server.accept();
+	server.close(code, reason);
+	return new Response(null, {
+		status: 101,
+		webSocket: client
+	});
+}
 var _host = /* @__PURE__ */ new WeakMap();
 var _facetKeepAliveTokens = /* @__PURE__ */ new WeakMap();
 var _bridgeContext = /* @__PURE__ */ new WeakMap();
 var _virtualConnections = /* @__PURE__ */ new WeakMap();
+var _virtualConnectionsHydrated = /* @__PURE__ */ new WeakMap();
+var _virtualConnectionsHydration = /* @__PURE__ */ new WeakMap();
 var _connectionOperationTails = /* @__PURE__ */ new WeakMap();
 var _broadcastOperationTail = /* @__PURE__ */ new WeakMap();
 var _DynamicAgentsInternal_brand = /* @__PURE__ */ new WeakSet();
@@ -335,6 +370,8 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		_classPrivateFieldInitSpec(this, _facetKeepAliveTokens, /* @__PURE__ */ new Set());
 		_classPrivateFieldInitSpec(this, _bridgeContext, new AsyncLocalStorage());
 		_classPrivateFieldInitSpec(this, _virtualConnections, /* @__PURE__ */ new Map());
+		_classPrivateFieldInitSpec(this, _virtualConnectionsHydrated, false);
+		_classPrivateFieldInitSpec(this, _virtualConnectionsHydration, void 0);
 		_classPrivateFieldInitSpec(this, _connectionOperationTails, /* @__PURE__ */ new Map());
 		_classPrivateFieldInitSpec(this, _broadcastOperationTail, void 0);
 		_classPrivateFieldSet2(_host, this, host);
@@ -389,7 +426,7 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		if (!_classPrivateFieldGet2(_host, this).hasSubAgent(next.className, next.name)) {
 			const stalePath = targetPath.slice(0, selfPath.length + 1);
 			if (_classPrivateFieldGet2(_host, this)._isFacet) await (await this.rootAlarmOwner())._cf_cleanupFacetPrefix(stalePath);
-			else await _classPrivateFieldGet2(_host, this)._cf_cleanupFacetPrefix(stalePath);
+			else await this.cleanupPrefix(stalePath);
 			return false;
 		}
 		return (await _classPrivateFieldGet2(_host, this)._cf_resolveSubAgent(next.className, next.name))._cf_routeLifecycle(target, envelope);
@@ -403,7 +440,7 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		if (!root) throw new Error("Facet routing requires a root parent.");
 		const binding = _classPrivateFieldGet2(_host, this).ctx.exports?.[root.className];
 		if (!binding) throw new Error(`Unable to resolve root "${root.className}" for facet routing.`);
-		return await getAgentByName(binding, root.name);
+		return binding.get(binding.idFromName(root.name));
 	}
 	rootResolvesToSelf() {
 		const root = _classPrivateFieldGet2(_host, this)._parentPath[0];
@@ -505,6 +542,7 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 	* rows on the target facet after recovery.
 	*/
 	async checkRunFibersAtPath(ownerPath) {
+		await _classPrivateFieldGet2(_host, this).__unsafe_ensureInitialized();
 		const selfPath = _classPrivateFieldGet2(_host, this).selfPath;
 		if (!_classPrivateFieldGet2(_host, this)._isSameAgentPathPrefix(selfPath, ownerPath)) throw new Error(`Facet fiber owner path does not descend from ${JSON.stringify(selfPath)}.`);
 		if (selfPath.length === ownerPath.length) {
@@ -548,11 +586,12 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		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 (!_classPrivateFieldGet2(_host, this)._isSameAgentPathPrefix(selfPath, targetPath)) throw new Error("_cf_destroyDescendantFacet: target path does not descend from this agent.");
-		if (_classPrivateFieldGet2(_host, this)._parentPath.length === 0) await _classPrivateFieldGet2(_host, this)._cf_cleanupFacetPrefix(targetPath);
+		if (_classPrivateFieldGet2(_host, this)._parentPath.length === 0) await this.cleanupPrefix(targetPath);
 		if (selfPath.length === targetPath.length - 1) {
 			const target = targetPath[targetPath.length - 1];
 			const ctx = _classPrivateFieldGet2(_host, 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.");
+			await _assertClassBrand(_DynamicAgentsInternal_brand, this, _closeConnectionsForDeletedPath).call(this, targetPath);
 			try {
 				ctx.facets.delete(`${target.className}\0${target.name}`);
 			} catch {}
@@ -628,16 +667,31 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 			className,
 			name
 		}];
-		if (_classPrivateFieldGet2(_host, this)._isFacet) await (await this.rootAlarmOwner())._cf_cleanupFacetPrefix(childPath);
-		else await _classPrivateFieldGet2(_host, this)._cf_cleanupFacetPrefix(childPath);
+		const root = _classPrivateFieldGet2(_host, this)._isFacet ? await this.rootAlarmOwner() : void 0;
+		await _assertClassBrand(_DynamicAgentsInternal_brand, this, _closeConnectionsForDeletedPath).call(this, childPath, root);
 		try {
 			ctx.facets.delete(facetKey);
 		} catch {}
 		this.registry.forget(className, name);
+		if (root) await root._cf_cleanupFacetPrefix(childPath);
+		else await this.cleanupPrefix(childPath);
+	}
+	/** Root-side: close sockets whose `/sub/...` target is under `prefix`. */
+	closeConnectionsForPrefix(prefix, code, reason) {
+		for (const connection of _classPrivateFieldGet2(_host, this)._webSockets.getConnections()) {
+			const targetPath = this.connectionTargetPath(connection);
+			if (!targetPath) continue;
+			if (!_classPrivateFieldGet2(_host, this)._isSameAgentPathPrefix(prefix, targetPath)) continue;
+			_classPrivateFieldGet2(_host, this)._unsafe_setConnectionFlag(connection, CF_SUB_AGENT_DELETED_KEY, true);
+			try {
+				connection.close(code, reason);
+			} catch {}
+		}
 	}
 	/** Drop all facet-side virtual connections (test/rehydration hook). */
 	clearVirtualConnections() {
 		_classPrivateFieldGet2(_virtualConnections, this).clear();
+		_classPrivateFieldSet2(_virtualConnectionsHydrated, this, false);
 	}
 	/** Facet-side lookup of a virtual connection by id. */
 	getVirtualConnection(id) {
@@ -715,6 +769,7 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		await completion;
 	}
 	async broadcastToParent(message, without) {
+		if (_assertClassBrand(_DynamicAgentsInternal_brand, this, _broadcastHasNoRecipients).call(this, without)) return;
 		await this.routeBroadcast(_classPrivateFieldGet2(_host, this).selfPath, message, without);
 	}
 	async broadcastToPath(ownerPath, message, without) {
@@ -779,21 +834,27 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		return parseSubAgentPath(request.url, { knownClasses: ctx.exports ? Object.keys(ctx.exports) : void 0 }) !== null;
 	}
 	async forwardWebSocketConnect(connection, request, options) {
-		const routed = await _assertClassBrand(_DynamicAgentsInternal_brand, this, _resolveConnection).call(this, connection, request, options);
-		if (!routed) return false;
+		const routed = await _assertClassBrand(_DynamicAgentsInternal_brand, this, _resolveConnection).call(this, connection, {
+			create: true,
+			request,
+			gate: options.gate
+		});
+		if (routed.status !== "ok") return false;
 		await routed.child._cf_handleSubAgentWebSocketConnect(_assertClassBrand(_DynamicAgentsInternal_brand, this, _createConnectionBridge).call(this, connection), routed.meta);
 		return true;
 	}
 	async forwardWebSocketMessage(connection, message, replyBridge) {
-		const routed = await _assertClassBrand(_DynamicAgentsInternal_brand, this, _resolveConnection).call(this, connection);
-		if (!routed) return false;
+		const routed = await _assertClassBrand(_DynamicAgentsInternal_brand, this, _resolveConnection).call(this, connection, { create: false });
+		if (routed.status === "no-match") return false;
+		if (routed.status === "dropped") return true;
 		const bridge = _assertClassBrand(_DynamicAgentsInternal_brand, this, _createConnectionBridge).call(this, connection);
 		await routed.child._cf_handleSubAgentWebSocketMessage(message, bridge, routed.meta, replyBridge ?? bridge);
 		return true;
 	}
 	async forwardWebSocketClose(connection, code, reason, wasClean) {
-		const routed = await _assertClassBrand(_DynamicAgentsInternal_brand, this, _resolveConnection).call(this, connection);
-		if (!routed) return false;
+		const routed = await _assertClassBrand(_DynamicAgentsInternal_brand, this, _resolveConnection).call(this, connection, { create: false });
+		if (routed.status === "no-match") return false;
+		if (routed.status === "dropped") return true;
 		await routed.child._cf_handleSubAgentWebSocketClose(code, reason, wasClean, _assertClassBrand(_DynamicAgentsInternal_brand, this, _createConnectionBridge).call(this, connection), routed.meta);
 		return true;
 	}
@@ -922,7 +983,8 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		if (!_classPrivateFieldGet2(_host, this)._isFacet || _classPrivateFieldGet2(_host, this)._parentPath.length === 0) return;
 		if (this.rootResolvesToSelf()) return;
 		const metas = await (await this.rootAlarmOwner())._cf_subAgentConnectionMetas(_classPrivateFieldGet2(_host, this).selfPath);
-		for (const meta of metas) _classPrivateFieldGet2(_virtualConnections, this).set(meta.id, { meta });
+		for (const meta of metas) if (!_classPrivateFieldGet2(_virtualConnections, this).has(meta.id)) _classPrivateFieldGet2(_virtualConnections, this).set(meta.id, { meta });
+		_classPrivateFieldSet2(_virtualConnectionsHydrated, this, true);
 	}
 	getRawConnectionState(connection) {
 		return getConnectionRawState(connection);
@@ -964,6 +1026,7 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 	* one RPC method. Stateless — no cached references.
 	*/
 	async invoke(className, name, method, args) {
+		await _classPrivateFieldGet2(_host, this).__unsafe_ensureInitialized();
 		const stub = await this.resolve(className, name);
 		return await this.invokeStubMethod(stub, className, method, args);
 	}
@@ -974,6 +1037,7 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 	* to the next facet using that facet's own `ctx.facets`.
 	*/
 	async invokePath(path, method, args) {
+		await _classPrivateFieldGet2(_host, this).__unsafe_ensureInitialized();
 		const [self, next, ...rest] = path;
 		if (!self) throw new Error(`Sub-agent path invocation requires a non-empty path.`);
 		const ownClassName = _classPrivateFieldGet2(_host, this).constructor.name;
@@ -1017,6 +1081,46 @@ var DynamicAgentsInternal = class extends LifecycleCapability {
 		await _classPrivateFieldGet2(_host, this)._syncHostJobs();
 	}
 };
+/**
+* Non-creating counterpart to {@link resolve} for WebSocket message/close
+* forwarding. Returns `null` when the child has no registry row, and never
+* writes one. The connection's initial connect already went through
+* {@link resolve} on this hop, so the runtime/export checks there hold.
+*/
+async function _resolveExisting(className, name) {
+	const row = this.registry.row(className, name);
+	if (!row) return null;
+	const ctx = _classPrivateFieldGet2(_host, this).ctx;
+	const identityName = row.identity_version === "path-v2" && typeof row.identity_name === "string" ? row.identity_name : name;
+	const rootClassName = _classPrivateFieldGet2(_host, this)._parentPath[0]?.className ?? _classPrivateFieldGet2(_host, this).constructor.name;
+	const rootNs = ctx.exports[rootClassName];
+	const stub = ctx.facets.get(`${className}\0${name}`, () => ({
+		class: ctx.exports[className],
+		id: rootNs.idFromName(identityName)
+	}));
+	const childParentPath = _classPrivateFieldGet2(_host, this).selfPath;
+	try {
+		await _classPrivateFieldGet2(_host, this)._runFacetInitInvocation(async () => {
+			await stub._cf_initAsFacet(name, childParentPath, identityName);
+		});
+	} catch (error) {
+		if (!this.registry.row(className, name)) return null;
+		throw error;
+	}
+	return stub;
+}
+/**
+* Close every client socket targeting `path` or a descendant, so a client
+* attached to a deleted facet gets an explicit close instead of a socket
+* that goes nowhere (#2003). Only the root owns real sockets.
+*/
+async function _closeConnectionsForDeletedPath(path, root) {
+	if (!_classPrivateFieldGet2(_host, this)._isFacet) {
+		this.closeConnectionsForPrefix(path, 1001, "Sub-agent deleted");
+		return;
+	}
+	await (root ?? await this.rootAlarmOwner())._cf_closeSubAgentConnectionsForPrefix(path, 1001, "Sub-agent deleted");
+}
 function _reportConnectionOperationFailure(connectionId, operation, error) {
 	console.error("[Agent] Sub-agent connection operation failed:", {
 		connectionId,
@@ -1024,6 +1128,29 @@ function _reportConnectionOperationFailure(connectionId, operation, error) {
 		error
 	});
 }
+/**
+* Whether a hydrated mirror proves no root socket targets this facet
+* outside `without`. Stale mirror entries only cost a root call; a socket
+* missing from a hydrated mirror has not had its connect forwarded here
+* yet, so it has not been through `onConnect`. Synchronous so a skipped
+* broadcast never reorders later operations.
+*/
+function _broadcastHasNoRecipients(without) {
+	if (!_classPrivateFieldGet2(_virtualConnectionsHydrated, this)) {
+		_assertClassBrand(_DynamicAgentsInternal_brand, this, _hydrateVirtualConnectionsInBackground).call(this);
+		return false;
+	}
+	for (const id of _classPrivateFieldGet2(_virtualConnections, this).keys()) if (!without?.includes(id)) return false;
+	return true;
+}
+function _hydrateVirtualConnectionsInBackground() {
+	if (_classPrivateFieldGet2(_virtualConnectionsHydration, this)) return;
+	const hydration = this.hydrateConnectionsFromRoot().catch(() => {}).finally(() => {
+		_classPrivateFieldSet2(_virtualConnectionsHydration, this, void 0);
+	});
+	_classPrivateFieldSet2(_virtualConnectionsHydration, this, hydration);
+	_classPrivateFieldGet2(_host, this).ctx.waitUntil(hydration);
+}
 function _connectionMetaForPath(connection, ownerPath) {
 	ensureConnectionWrapped(connection);
 	const outerUri = _classPrivateFieldGet2(_host, this)._unsafe_getConnectionFlag(connection, CF_SUB_AGENT_OUTER_URL_KEY);
@@ -1074,20 +1201,31 @@ function _createConnectionBridge(connection) {
 		return _classPrivateFieldGet2(_host, this)._cf_broadcastToSubAgent(ownerPath, message, without);
 	});
 }
-async function _resolveConnection(connection, request, options = { gate: false }) {
+/**
+* Resolve a connection's `/sub/{class}/{name}` target.
+*
+* `create: true` (the initial connect) may wake or create the child, like
+* `subAgent()`. `create: false` (message/close on an already-forwarded
+* connection) only attaches to a child that still has a registry row; a
+* deleted child resolves to `"dropped"`, which the caller must treat as
+* consumed so a stale frame can't recreate it (#2003).
+*/
+async function _resolveConnection(connection, options) {
 	ensureConnectionWrapped(connection);
 	const outerUri = _classPrivateFieldGet2(_host, this)._unsafe_getConnectionFlag(connection, CF_SUB_AGENT_OUTER_URL_KEY);
 	const uri = typeof outerUri === "string" ? outerUri : connection.uri;
-	if (!uri) return null;
+	if (!uri) return { status: "no-match" };
+	if (_classPrivateFieldGet2(_host, this)._unsafe_getConnectionFlag(connection, "_cf_subAgentDeleted")) return { status: "dropped" };
 	const ctx = _classPrivateFieldGet2(_host, this).ctx;
 	let match = parseSubAgentPath(uri, { knownClasses: ctx.exports ? Object.keys(ctx.exports) : void 0 });
-	if (!match) return null;
+	if (!match) return { status: "no-match" };
 	if (_classPrivateFieldGet2(_host, this)._ParentClass.name === match.childClass && _classPrivateFieldGet2(_host, 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;
+		if (!match) return { status: "no-match" };
 	}
+	const { request } = options;
 	let forwardReq = request;
 	if (request && options.gate) {
 		const decision = await _classPrivateFieldGet2(_host, this).onBeforeSubAgent(request, {
@@ -1095,25 +1233,28 @@ async function _resolveConnection(connection, request, options = { gate: false }
 			name: match.childName
 		});
 		if (decision instanceof Response) {
-			connection.close(1008, "Sub-agent connection rejected");
-			return null;
+			const { code, reason } = subAgentRejectionClose(decision);
+			connection.close(code, reason);
+			return { status: "dropped" };
 		}
 		forwardReq = decision instanceof Request ? decision : request;
 	}
-	const child = await this.resolve(match.childClass, match.childName);
+	const child = options.create ? await this.resolve(match.childClass, match.childName) : await _assertClassBrand(_DynamicAgentsInternal_brand, this, _resolveExisting).call(this, match.childClass, match.childName);
+	if (!child) return { status: "dropped" };
 	const childUri = new URL(forwardReq?.url ?? uri);
 	childUri.pathname = match.remainingPath;
 	const raw = this.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 {
+		status: "ok",
 		child,
 		meta: {
 			id: connection.id,
 			uri: childUri.toString(),
 			tags,
 			state: this.getForwardedState(connection),
-			requestHeaders: forwardReq ? [...forwardReq.headers] : void 0
+			requestHeaders: forwardReq ? [...forwardReq.headers].filter(([name]) => name !== SUB_AGENT_OUTER_URL_HEADER) : void 0
 		}
 	};
 }
@@ -1248,7 +1389,7 @@ const DETACHED_NOTIFY_CALLBACK = "_cfDetachedNotifyFinish";
 * every capability uses for its own schema version) and checks it on wake to
 * skip DDL on established DOs.
 */
-const CURRENT_SCHEMA_VERSION = 11;
+const CURRENT_SCHEMA_VERSION = 14;
 const SCHEMA_VERSION_KEY = "cf_agents:schema_version";
 const LEGACY_SCHEMA_VERSION_ROW_ID = "cf_schema_version";
 const DEFAULT_STATE = {};
@@ -1323,9 +1464,9 @@ const DEFAULT_AGENT_STATIC_OPTIONS = {
 	/**
 	* Optional hard wall-clock ceiling (ms) on a single agent-tool re-attach
 	* (#1630). Caps the total wait even as the no-progress budget re-arms across
-	* stream-closes. Defaults to `Infinity` (no implicit cap), mirroring
-	* chat-recovery's `maxRecoveryWork` (#1672): a healthy, still-advancing child
-	* is followed for as long as it makes progress — a hung child is bounded by
+	* stream-closes. Defaults to `Infinity` (no implicit cap, #1672): a healthy,
+	* still-advancing child is followed for as long as it makes progress — a
+	* hung child is bounded by
 	* the no-progress budget, and a content-runaway by the child's own
 	* `maxRecoveryWork` / `shouldKeepRecovering`. Set a finite value to impose a
 	* wall-clock cap (which also tears the child down on `window-exceeded`).
@@ -1345,13 +1486,21 @@ const DEFAULT_AGENT_STATIC_OPTIONS = {
 };
 /** Compatibility alias for the lifecycle-owned current Agent accessor. */
 const getCurrentAgent = getCurrentAgent$1;
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
+/** Functions produced by {@link withAgentContext}, so they are wrapped once. */
+const agentContextWrappers = /* @__PURE__ */ new WeakSet();
 /**
 * Restore Agent context when a public method is entered outside a Lifecycle
 * hook, notably through native Durable Object RPC or cross-Agent re-entry.
 * Lifecycle already owns context for its capability and semantic user hooks.
+*
+* Native RPC bypasses the lifecycle's runtime handlers, so an `async` method
+* entered from outside this Agent's context first starts the lifecycle when
+* the call is the one that wakes a cold instance. Synchronous methods are
+* never deferred, so they keep their synchronous return type.
 */
 function withAgentContext(method) {
-	return function(...args) {
+	const enter = function(...args) {
 		const { agent } = getCurrentAgent();
 		if (agent === this) return method.apply(this, args);
 		return runInInvocation({
@@ -1363,6 +1512,16 @@ function withAgentContext(method) {
 			return method.apply(this, args);
 		});
 	};
+	if (!(method instanceof AsyncFunction)) {
+		agentContextWrappers.add(enter);
+		return enter;
+	}
+	const enterStarted = async function(...args) {
+		if (getCurrentAgent().agent !== this && !this.lifecycle.isStarted()) await this.lifecycle.start();
+		return enter.apply(this, args);
+	};
+	agentContextWrappers.add(enterStarted);
+	return enterStarted;
 }
 /**
 * Base class for creating Agent implementations
@@ -1573,7 +1732,10 @@ var Agent = class Agent extends DurableObject {
           id TEXT PRIMARY KEY NOT NULL,
           name TEXT NOT NULL,
           snapshot TEXT,
-          created_at INTEGER NOT NULL
+          created_at INTEGER NOT NULL,
+          completed_at INTEGER,
+          outcome TEXT,
+          error_message TEXT
         )
       `;
 			this.sql`
@@ -1652,6 +1814,10 @@ var Agent = class Agent extends DurableObject {
 			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached_no_progress_budget_ms INTEGER");
 			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN last_progress_at INTEGER");
 			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached_on_milestones TEXT");
+			addColumnIfNotExists("ALTER TABLE cf_agents_runs ADD COLUMN completed_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agents_runs ADD COLUMN outcome TEXT");
+			addColumnIfNotExists("ALTER TABLE cf_agents_runs ADD COLUMN error_message TEXT");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN event_delivery TEXT");
 			this.ctx.storage.kv.put(SCHEMA_VERSION_KEY, CURRENT_SCHEMA_VERSION);
 		}
 		this._schemaInitialization = {
@@ -1928,6 +2094,14 @@ var Agent = class Agent extends DurableObject {
 			}, async () => {
 				if (this.shouldConnectionBeReadonly(connection, ctx)) this.setConnectionReadonly(connection, true);
 				if (this.shouldSendProtocolMessages(connection, ctx)) {
+					const wasExcludedFromStateInitBroadcast = this._protocolBroadcastExcludeIds.has(connection.id);
+					let currentState;
+					this._protocolBroadcastExcludeIds.add(connection.id);
+					try {
+						currentState = this.state;
+					} finally {
+						if (!wasExcludedFromStateInitBroadcast) this._protocolBroadcastExcludeIds.delete(connection.id);
+					}
 					if (this._resolvedOptions.sendIdentityOnConnect) {
 						const ctor = this.constructor;
 						if (ctor.options?.sendIdentityOnConnect === void 0 && !_sendIdentityWarnedClasses.has(ctor) && !this._isFacet) {
@@ -1936,20 +2110,11 @@ var Agent = class Agent extends DurableObject {
 								console.warn(`[Agent] ${ctor.name}: sending instance name "${this.name}" to clients via sendIdentityOnConnect (the name is not visible in the URL with custom routing). If this name is sensitive, add \`static options = { sendIdentityOnConnect: false }\` to opt out. Set it to true to silence this message.`);
 							}
 						}
-						this._webSockets.sendIdentity(connection, {
+						this._webSockets.sendConnectFrames(connection, {
 							name: this.name,
 							agent: camelCaseToKebabCase(this._ParentClass.name)
 						});
-					}
-					const wasExcludedFromStateInitBroadcast = this._protocolBroadcastExcludeIds.has(connection.id);
-					let currentState;
-					this._protocolBroadcastExcludeIds.add(connection.id);
-					try {
-						currentState = this.state;
-					} finally {
-						if (!wasExcludedFromStateInitBroadcast) this._protocolBroadcastExcludeIds.delete(connection.id);
-					}
-					if (currentState !== void 0) this._webSockets.sendState(connection);
+					} else if (currentState !== void 0) this._webSockets.sendState(connection);
 					connection.send(JSON.stringify({
 						mcp: this.getMcpServers(),
 						type: "cf_agent_mcp_servers"
@@ -2366,19 +2531,21 @@ var Agent = class Agent extends DurableObject {
 				proto = Object.getPrototypeOf(proto);
 			}
 		}
+		const seen = /* @__PURE__ */ new Set();
 		let proto = Object.getPrototypeOf(this);
-		let depth = 0;
-		while (proto && proto !== Object.prototype && depth < 10) {
+		while (proto && proto !== Agent.prototype && proto !== Object.prototype) {
 			const methodNames = Object.getOwnPropertyNames(proto);
 			for (const methodName of methodNames) {
+				if (seen.has(methodName)) continue;
+				seen.add(methodName);
 				const descriptor = Object.getOwnPropertyDescriptor(proto, methodName);
-				if (baseMethods.has(methodName) || methodName.startsWith("_") || !descriptor || !!descriptor.get || typeof descriptor.value !== "function") continue;
-				const wrappedFunction = withAgentContext(this[methodName]);
-				if (this._isCallable(methodName)) copyCallableMetadata(this[methodName], wrappedFunction);
+				if (baseMethods.has(methodName) || methodName.startsWith("_") || !descriptor || !!descriptor.get || typeof descriptor.value !== "function" || agentContextWrappers.has(descriptor.value)) continue;
+				const method = descriptor.value;
+				const wrappedFunction = withAgentContext(method);
+				if (this._isCallable(methodName)) copyCallableMetadata(method, wrappedFunction);
 				this.constructor.prototype[methodName] = wrappedFunction;
 			}
 			proto = Object.getPrototypeOf(proto);
-			depth++;
 		}
 	}
 	onError(connectionOrError, error) {
@@ -2487,7 +2654,8 @@ var Agent = class Agent extends DurableObject {
 		return this._dynamicAgents.routeLifecycleToTarget(target, envelope);
 	}
 	/** Single native-RPC aperture for routed Lifecycle capabilities. */
-	_cf_routeLifecycle(target, envelope) {
+	async _cf_routeLifecycle(target, envelope) {
+		await this.__unsafe_ensureInitialized();
 		return this._dynamicAgents.routeLifecycle(target, envelope);
 	}
 	_rootAlarmOwner() {
@@ -2504,6 +2672,7 @@ var Agent = class Agent extends DurableObject {
 	* @internal
 	*/
 	async _cf_cleanupFacetPrefix(ownerPath) {
+		await this.__unsafe_ensureInitialized();
 		await this._dynamicAgents.cleanupPrefix(ownerPath);
 	}
 	/**
@@ -2512,7 +2681,8 @@ var Agent = class Agent extends DurableObject {
 	* physical alarm, so this lets facet work use the root alarm heartbeat.
 	* @internal
 	*/
-	_cf_acquireFacetKeepAlive(ownerPath) {
+	async _cf_acquireFacetKeepAlive(ownerPath) {
+		await this.__unsafe_ensureInitialized();
 		return this._dynamicAgents.acquireKeepAlive(ownerPath);
 	}
 	/**
@@ -2520,8 +2690,9 @@ var Agent = class Agent extends DurableObject {
 	* Idempotent so disposer calls can safely race or run twice.
 	* @internal
 	*/
-	_cf_releaseFacetKeepAlive(token) {
-		return this._dynamicAgents.releaseKeepAlive(token);
+	async _cf_releaseFacetKeepAlive(token) {
+		await this.__unsafe_ensureInitialized();
+		await this._dynamicAgents.releaseKeepAlive(token);
 	}
 	/**
 	* Register a facet's durable run row in the root-side index so root
@@ -2529,15 +2700,17 @@ var Agent = class Agent extends DurableObject {
 	* The facet remains authoritative for snapshots and recovery hooks.
 	* @internal
 	*/
-	_cf_registerFacetRun(ownerPath, runId) {
-		return this._dynamicAgents.registerRun(ownerPath, runId);
+	async _cf_registerFacetRun(ownerPath, runId) {
+		await this.__unsafe_ensureInitialized();
+		await this._dynamicAgents.registerRun(ownerPath, runId);
 	}
 	/**
 	* Remove a completed facet fiber from the root-side index.
 	* @internal
 	*/
-	_cf_unregisterFacetRun(ownerPath, runId) {
-		return this._dynamicAgents.unregisterRun(ownerPath, runId);
+	async _cf_unregisterFacetRun(ownerPath, runId) {
+		await this.__unsafe_ensureInitialized();
+		await this._dynamicAgents.unregisterRun(ownerPath, runId);
 	}
 	/**
 	* Schedule a task to be executed in the future
@@ -3222,6 +3395,7 @@ var Agent = class Agent extends DurableObject {
 		};
 		let root;
 		let registeredFacetRun = false;
+		let bodyOutcome;
 		let dispose = () => {};
 		try {
 			if ("initialSnapshot" in (options ?? {})) writeSnapshot(options?.initialSnapshot);
@@ -3235,16 +3409,29 @@ var Agent = class Agent extends DurableObject {
 				writeSnapshot(options?.wrapStash ? options.wrapStash(data) : data);
 			};
 			try {
-				const result = await _fiberALS.run({
-					id,
-					signal,
-					stash
-				}, () => fn({
-					id,
-					signal,
-					stash,
-					snapshot: null
-				}));
+				let result;
+				try {
+					result = await _fiberALS.run({
+						id,
+						signal,
+						stash
+					}, () => fn({
+						id,
+						signal,
+						stash,
+						snapshot: null
+					}));
+				} catch (error) {
+					bodyOutcome = {
+						status: signal.aborted ? "aborted" : "error",
+						error: this._fiberErrorMessage(error)
+					};
+					throw error;
+				}
+				bodyOutcome = {
+					status: "completed",
+					error: null
+				};
 				options?.beforeRunCleanup?.({ ok: true });
 				this._emit("fiber:run:completed", {
 					fiberId: id,
@@ -3269,18 +3456,29 @@ var Agent = class Agent extends DurableObject {
 			}
 		} finally {
 			this._runFiberActiveFibers.delete(id);
+			let rowDeleted = false;
 			try {
 				this._withAgentSpan("finalize_fiber", "fiber", {
 					"cloudflare.agents.fiber.id": id,
 					"cloudflare.agents.fiber.name": name
 				}, () => {
+					if (bodyOutcome) try {
+						this.sql`
+                  UPDATE cf_agents_runs
+                  SET completed_at = ${Date.now()},
+                      outcome = ${bodyOutcome.status},
+                      error_message = ${bodyOutcome.error}
+                  WHERE id = ${id}
+                `;
+					} catch {}
 					this.sql`DELETE FROM cf_agents_runs WHERE id = ${id}`;
 				});
+				rowDeleted = true;
 			} catch (error) {
 				console.error(`[Agent] Failed to finalize fiber "${name}" (${id}); leaving run row for recovery:`, error);
 			}
 			dispose();
-			if (root && registeredFacetRun) try {
+			if (root && registeredFacetRun && rowDeleted) try {
 				await root._cf_unregisterFacetRun(this.selfPath, id);
 			} catch (e) {
 				console.error("[Agent] Failed to unregister facet fiber:", e);
@@ -3337,7 +3535,11 @@ var Agent = class Agent extends DurableObject {
 		const fiberRecoveryMaxAgeMs = this._resolvedOptions.fiberRecoveryMaxAgeMs;
 		let madeProgress = false;
 		try {
-			const rows = this.sql`SELECT id, name, snapshot, created_at FROM cf_agents_runs`;
+			const rows = this.sql`
+        SELECT id, name, snapshot, created_at, completed_at, outcome,
+               error_message
+        FROM cf_agents_runs
+      `;
 			for (const row of rows) {
 				if (scanDeadlineMs > 0 && Date.now() - scanStartedAt > scanDeadlineMs) {
 					this._emit("fiber:recovery:skipped", {
@@ -3349,6 +3551,27 @@ var Agent = class Agent extends DurableObject {
 					break;
 				}
 				if (this._runFiberActiveFibers.has(row.id)) continue;
+				const managedRow = this._readFiber(row.id);
+				if (row.completed_at !== null && (!managedRow || row.outcome !== null)) {
+					if (managedRow) this.sql`
+              UPDATE cf_agents_fibers
+              SET status = ${row.outcome},
+                  error_message = ${row.error_message},
+                  completed_at = ${row.completed_at}
+              WHERE fiber_id = ${row.id}
+                AND status IN ('pending', 'running')
+            `;
+					this.sql`DELETE FROM cf_agents_runs WHERE id = ${row.id}`;
+					madeProgress = true;
+					if (managedRow) this._notifyManagedFiberTerminal(row.id);
+					continue;
+				}
+				if (managedRow && this._isTerminalFiberStatus(managedRow.status)) {
+					this.sql`DELETE FROM cf_agents_runs WHERE id = ${row.id}`;
+					madeProgress = true;
+					this._notifyManagedFiberTerminal(row.id);
+					continue;
+				}
 				const snapshot = this._parseFiberRecoverySnapshot(row.id, row.snapshot);
 				const ctx = {
 					id: row.id,
@@ -3357,7 +3580,6 @@ var Agent = class Agent extends DurableObject {
 					createdAt: row.created_at,
 					recoveryReason: "interrupted"
 				};
-				const managedRow = this._readFiber(row.id);
 				this._emit("fiber:recovery:detected", {
 					...this._fiberRecoveryPayload(ctx, managedRow),
 					elapsedMs: Date.now() - row.created_at
@@ -3370,12 +3592,6 @@ var Agent = class Agent extends DurableObject {
 					elapsedMs: Date.now() - row.created_at
 				});
 				if (managedRow) {
-					if (this._isTerminalFiberStatus(managedRow.status)) {
-						this.sql`DELETE FROM cf_agents_runs WHERE id = ${row.id}`;
-						madeProgress = true;
-						this._notifyManagedFiberTerminal(row.id);
-						continue;
-					}
 					const completedAt = Date.now();
 					this.sql`
             UPDATE cf_agents_fibers
@@ -3513,8 +3729,9 @@ var Agent = class Agent extends DurableObject {
 	* cleanup as `parent.deleteSubAgent(Cls, name)` from the parent.
 	* @internal
 	*/
-	_cf_destroyDescendantFacet(targetPath) {
-		return this._dynamicAgents.destroyDescendant(targetPath);
+	async _cf_destroyDescendantFacet(targetPath) {
+		await this.__unsafe_ensureInitialized();
+		await this._dynamicAgents.destroyDescendant(targetPath);
 	}
 	/**
 	* Whether any runFiber recovery work is still outstanding: orphaned
@@ -3552,6 +3769,15 @@ var Agent = class Agent extends DurableObject {
 	*/
 	async _syncHostJobs() {
 		if (this._destroyed) return;
+		if (this._isFacet) {
+			const work = this.lifecycle.jobs;
+			for (const id of [
+				HOST_JOB_DESTROY_ID,
+				HOST_JOB_KEEP_ALIVE_ID,
+				HOST_JOB_HOUSEKEEPING_ID
+			]) if (work.get(id)) await work.cancel(id);
+			return;
+		}
 		await this._withAgentSpan("schedule_agent_alarm", "alarm", {}, async () => {
 			const work = this.lifecycle.jobs;
 			const nowMs = Date.now();
@@ -3683,9 +3909,10 @@ var Agent = class Agent extends DurableObject {
 			className: match.childClass,
 			name: match.childName
 		});
-		if (decision instanceof Response) return decision;
+		const isWebSocketUpgrade = request.headers.get("Upgrade")?.toLowerCase() === "websocket";
+		if (decision instanceof Response) return isWebSocketUpgrade && !decision.webSocket ? rejectSubAgentWebSocket(decision) : decision;
 		const forwardReq = decision instanceof Request ? decision : request;
-		if (request.headers.get("Upgrade")?.toLowerCase() === "websocket") {
+		if (isWebSocketUpgrade) {
 			const acceptHeaders = new Headers(forwardReq.headers);
 			const routedUrl = new URL(forwardReq.url);
 			routedUrl.pathname = new URL(request.url).pathname;
@@ -3722,18 +3949,27 @@ var Agent = class Agent extends DurableObject {
 		}
 	}
 	async _cf_broadcastToSubAgent(ownerPath, message, without) {
+		await this.__unsafe_ensureInitialized();
 		await this._dynamicAgents.broadcastToPath(ownerPath, message, without);
 	}
-	_cf_subAgentConnectionMetas(ownerPath) {
+	async _cf_subAgentConnectionMetas(ownerPath) {
+		await this.__unsafe_ensureInitialized();
 		return this._dynamicAgents.connectionMetas(ownerPath);
 	}
-	_cf_sendToSubAgentConnection(connectionId, message) {
-		return this._dynamicAgents.sendToConnection(connectionId, message);
+	async _cf_sendToSubAgentConnection(connectionId, message) {
+		await this.__unsafe_ensureInitialized();
+		await this._dynamicAgents.sendToConnection(connectionId, message);
+	}
+	async _cf_closeSubAgentConnection(connectionId, code, reason) {
+		await this.__unsafe_ensureInitialized();
+		await this._dynamicAgents.closeConnection(connectionId, code, reason);
 	}
-	_cf_closeSubAgentConnection(connectionId, code, reason) {
-		return this._dynamicAgents.closeConnection(connectionId, code, reason);
+	async _cf_closeSubAgentConnectionsForPrefix(prefix, code, reason) {
+		await this.__unsafe_ensureInitialized();
+		this._dynamicAgents.closeConnectionsForPrefix(prefix, code, reason);
 	}
-	_cf_setSubAgentConnectionState(connectionId, state) {
+	async _cf_setSubAgentConnectionState(connectionId, state) {
+		await this.__unsafe_ensureInitialized();
 		return this._dynamicAgents.setConnectionState(connectionId, state);
 	}
 	_cf_connectionTargetsSubAgent(connection) {
@@ -4049,6 +4285,9 @@ var Agent = class Agent extends DurableObject {
 		const runId = options.runId ?? nanoid(12);
 		const agentType = cls.name;
 		const detached = this._parseDetachedOption(options.detached);
+		const eventDelivery = options.eventDelivery ?? "full";
+		if (eventDelivery !== "full" && eventDelivery !== "terminal") throw new Error(`runAgentTool: eventDelivery must be "full" or "terminal", got ${JSON.stringify(eventDelivery)}.`);
+		if (detached && eventDelivery === "terminal") throw new Error("runAgentTool: eventDelivery \"terminal\" is not supported for detached runs.");
 		const existing = this._readAgentToolRun(runId);
 		if (existing) {
 			if (detached) {
@@ -4139,13 +4378,14 @@ var Agent = class Agent extends DurableObject {
         input_redacted, status, display_metadata, display_order, started_at,
         detached, detached_on_finish, detached_notify_source,
         detached_max_budget_at, detached_no_progress_budget_ms,
-        detached_on_milestones
+        detached_on_milestones, event_delivery
       ) VALUES (
         ${runId}, ${options.parentToolCallId ?? null}, ${agentType},
         ${inputPreviewJson}, 1, 'starting', ${displayJson}, ${displayOrder},
         ${startedAt}, ${detached ? 1 : 0}, ${detached?.onFinishName ?? null},
         ${detached?.notifySource ?? null}, ${detachedMaxBudgetAt},
-        ${detachedNoProgressBudgetMs}, ${detachedOnMilestonesJson}
+        ${detachedNoProgressBudgetMs}, ${detachedOnMilestonesJson},
+        ${eventDelivery === "terminal" ? "terminal" : null}
       )
     `;
 		const runInfo = {
@@ -4170,7 +4410,10 @@ var Agent = class Agent extends DurableObject {
 		});
 		const child = await this.subAgent(cls, runId);
 		const adapter = this._asAgentToolChildAdapter(child);
-		const childStart = await adapter.startAgentToolRun(options.input, { runId });
+		const childStart = await adapter.startAgentToolRun(options.input, {
+			runId,
+			...eventDelivery === "terminal" ? { eventDelivery } : {}
+		});
 		this._markAgentToolRunning(runId);
 		if (detached) {
 			if (options.signal) console.warn(`[agents] runAgentTool: \`signal\` is ignored for a detached run (${runId}); a detached child must outlive the spawning turn. Use cancelAgentTool(runId) to cancel it.`);
@@ -4781,29 +5024,79 @@ var Agent = class Agent extends DurableObject {
 		else this.broadcast(body);
 	}
 	_broadcastAgentToolChunks(parentToolCallId, runId, chunks, sequence, replay, connection) {
+		const terminalOnly = this._isTerminalOnlyAgentToolRun(runId);
 		let next = sequence;
-		for (const chunk of chunks) this._broadcastAgentToolEvent(parentToolCallId, next++, {
-			kind: "chunk",
-			runId,
-			body: chunk.body
-		}, replay, connection);
+		for (const chunk of chunks) {
+			const chunkSequence = next++;
+			if (terminalOnly && !isAgentToolLifecycleChunk(chunk.body)) continue;
+			this._broadcastAgentToolEvent(parentToolCallId, chunkSequence, {
+				kind: "chunk",
+				runId,
+				body: chunk.body
+			}, replay, connection);
+		}
 		return next;
 	}
-	async _broadcastAgentToolStoredChunks(row, sequence, replay, connection) {
-		const child = await this._cf_resolveSubAgent(row.agent_type, row.run_id);
+	_isTerminalOnlyAgentToolRun(runId) {
+		return this.sql`
+      SELECT event_delivery FROM cf_agent_tool_runs WHERE run_id = ${runId}
+    `[0]?.event_delivery === "terminal";
+	}
+	async _broadcastAgentToolStoredChunks(row, sequence, replay, connection, timeoutMs) {
+		const deadline = this._agentToolRecoveryDeadline(timeoutMs);
+		const resolving = this._cf_resolveSubAgent(row.agent_type, row.run_id);
+		const child = deadline === void 0 ? await resolving : await this._settleWithinRecoveryTimeout(resolving, deadline());
+		if (child === void 0) return sequence;
 		const adapter = this._asAgentToolChildAdapter(child);
-		return this._broadcastAgentToolStoredChunksFromAdapter(adapter, row, sequence, replay, connection);
+		return this._broadcastAgentToolStoredChunksFromAdapter(adapter, row, sequence, replay, connection, deadline?.());
+	}
+	/**
+	* One budget shared by every step of a bounded recovery read, so a run's
+	* total time stays within `timeoutMs`. Returns the remaining milliseconds,
+	* never below 1 because a non-positive timeout means "unbounded".
+	*/
+	_agentToolRecoveryDeadline(timeoutMs) {
+		if (timeoutMs === void 0 || timeoutMs <= 0) return void 0;
+		const deadline = Date.now() + timeoutMs;
+		return () => Math.max(1, deadline - Date.now());
 	}
 	async _broadcastAgentToolStoredChunksFromAdapter(adapter, row, sequence, replay, connection, timeoutMs) {
-		const chunks = await this._getAgentToolChunksForRecovery(adapter, row.run_id, timeoutMs);
-		if (!chunks) return sequence;
-		return this._broadcastAgentToolChunks(row.parent_tool_call_id ?? void 0, row.run_id, chunks, sequence, replay, connection);
+		const deadline = this._agentToolRecoveryDeadline(timeoutMs);
+		const chunks = await this._getAgentToolChunksForRecovery(adapter, row.run_id, deadline?.());
+		const next = chunks ? this._broadcastAgentToolChunks(row.parent_tool_call_id ?? void 0, row.run_id, chunks, sequence, replay, connection) : sequence;
+		return this._broadcastAgentToolMilestones(adapter, row, next, replay, connection, deadline?.());
+	}
+	/**
+	* Milestones are persisted on the child run rather than in its chunk log, so
+	* replay re-emits them from the child's inspection. The client dedupes them
+	* on the milestone's own sequence, so a milestone already seen live is a no-op.
+	* They carry the next stored-chunk sequence without consuming it, matching
+	* the live path.
+	*/
+	async _broadcastAgentToolMilestones(adapter, row, sequence, replay, connection, timeoutMs) {
+		const milestones = (await this._settleWithinRecoveryTimeout(adapter.inspectAgentToolRun(row.run_id, { reconcile: false }), timeoutMs))?.milestones ?? [];
+		for (const milestone of milestones) this._broadcastAgentToolEvent(row.parent_tool_call_id ?? void 0, sequence, {
+			kind: "chunk",
+			runId: row.run_id,
+			body: JSON.stringify({
+				type: AGENT_TOOL_MILESTONE_PART,
+				data: {
+					name: milestone.name,
+					sequence: milestone.sequence,
+					at: milestone.at,
+					...milestone.data !== void 0 ? { data: milestone.data } : {}
+				}
+			})
+		}, replay, connection);
+		return sequence;
 	}
 	async _forwardAgentToolStream(stream, parentToolCallId, runId, sequence, signal, idleTimeoutMs) {
 		let next = sequence;
+		let forwarded = false;
 		if (signal?.aborted) return {
 			next,
-			ended: "aborted"
+			ended: "aborted",
+			forwarded
 		};
 		let ended = "done";
 		const reader = stream.getReader();
@@ -4831,12 +5124,18 @@ var Agent = class Agent extends DurableObject {
 			idleTimer = setTimeout(() => resolveIdle?.(), idleTimeoutMs);
 		};
 		let forwardedSinceProgress = false;
+		const terminalOnly = this._isTerminalOnlyAgentToolRun(runId);
 		try {
 			const forwardChunk = (chunk) => {
-				this._broadcastAgentToolEvent(parentToolCallId, next++, {
+				const lifecycle = isAgentToolLifecycleChunk(chunk.body);
+				const unstoredId = typeof chunk.unstoredId === "string" ? chunk.unstoredId : void 0;
+				const chunkSequence = lifecycle || unstoredId !== void 0 ? next : next++;
+				forwarded = true;
+				if (!terminalOnly || lifecycle) this._broadcastAgentToolEvent(parentToolCallId, chunkSequence, {
 					kind: "chunk",
 					runId,
-					body: chunk.body
+					body: chunk.body,
+					...unstoredId !== void 0 ? { unstoredId } : {}
 				});
 				this._observeForwardedProgress(runId, chunk.body);
 				forwardedSinceProgress = true;
@@ -4904,7 +5203,8 @@ var Agent = class Agent extends DurableObject {
 		}
 		return {
 			next,
-			ended
+			ended,
+			forwarded
 		};
 	}
 	/**
@@ -5105,9 +5405,9 @@ var Agent = class Agent extends DurableObject {
 	* dies and recovers again during deploy churn is still collected. A genuinely
 	* silent/hung child can never block recovery forever: it seals `interrupted`
 	* after one `noProgressTimeoutMs` window. `maxWindowMs` is an OPTIONAL hard
-	* wall-clock ceiling (default `Infinity` — uncapped, mirroring #1672's
-	* `maxRecoveryWork`); set it finite to also bound a child that keeps
-	* progressing, which seals `window-exceeded` and tears the child down.
+	* wall-clock ceiling (default `Infinity` — uncapped, #1672); set it finite
+	* to also bound a child that keeps progressing, which seals
+	* `window-exceeded` and tears the child down.
 	*
 	* Returns the terminal `result` (and `completedAt`) when the child reaches a
 	* terminal status, plus the advanced broadcast `sequence`. Returns
@@ -5152,18 +5452,22 @@ var Agent = class Agent extends DurableObject {
 		try {
 			while (!ceilingController.signal.aborted) {
 				let afterSequence = -1;
+				let storedCount = 0;
 				try {
 					const existing = await adapter.getAgentToolChunks(row.run_id);
 					const last = existing[existing.length - 1];
 					if (last) afterSequence = last.sequence;
+					storedCount = existing.length;
 				} catch {}
-				const beforeSequence = nextSequence;
+				nextSequence = storedCount + 1;
 				let streamEnded = "idle";
+				let forwardedAny = false;
 				try {
 					const stream = await adapter.tailAgentToolRun(row.run_id, { afterSequence });
 					const forwarded = await this._forwardAgentToolStream(stream, row.parent_tool_call_id ?? void 0, row.run_id, nextSequence, ceilingController.signal, noProgressTimeoutMs);
 					nextSequence = forwarded.next;
 					streamEnded = forwarded.ended;
+					forwardedAny = forwarded.forwarded;
 				} catch {}
 				const terminal = await collectTerminal(nextSequence);
 				if (terminal) return terminal;
@@ -5172,7 +5476,7 @@ var Agent = class Agent extends DurableObject {
 					break;
 				}
 				if (streamEnded !== "done") break;
-				if (nextSequence <= beforeSequence) break;
+				if (!forwardedAny) break;
 			}
 		} finally {
 			if (ceilingTimer !== void 0) clearTimeout(ceilingTimer);
@@ -5202,7 +5506,7 @@ var Agent = class Agent extends DurableObject {
 				display: this._parseAgentToolJson(row.display_metadata)
 			}, true, connection);
 			try {
-				sequence = await this._broadcastAgentToolStoredChunks(row, sequence, true, connection);
+				sequence = await this._broadcastAgentToolStoredChunks(row, sequence, true, connection, DEFAULT_AGENT_TOOL_RECOVERY_TIMEOUT_MS);
 			} catch {}
 			if (this._isAgentToolTerminal(row.status)) this._broadcastAgentToolTerminal(parentToolCallId, sequence, {
 				runId: row.run_id,
@@ -5389,13 +5693,17 @@ var Agent = class Agent extends DurableObject {
     `.map((row) => row.run_id);
 	}
 	async _getAgentToolChunksForRecovery(adapter, runId, timeoutMs) {
-		const chunks = adapter.getAgentToolChunks(runId).catch(() => void 0);
-		if (timeoutMs === void 0 || timeoutMs <= 0) return chunks;
+		return this._settleWithinRecoveryTimeout(adapter.getAgentToolChunks(runId), timeoutMs);
+	}
+	/** Resolve to `undefined` when `promise` rejects or outlasts `timeoutMs`. */
+	async _settleWithinRecoveryTimeout(promise, timeoutMs) {
+		const settled = promise.catch(() => void 0);
+		if (timeoutMs === void 0 || timeoutMs <= 0) return settled;
 		let timeoutId;
 		const timeout = new Promise((resolve) => {
 			timeoutId = setTimeout(() => resolve(void 0), timeoutMs);
 		});
-		const result = await Promise.race([chunks, timeout]);
+		const result = await Promise.race([settled, timeout]);
 		if (timeoutId !== void 0) clearTimeout(timeoutId);
 		return result;
 	}
@@ -6693,4 +7001,4 @@ var StreamingResponse = class {
 //#endregion
 export { routeAgentEmail as a, getCurrentAgent as i, DEFAULT_AGENT_STATIC_OPTIONS as n, StreamingResponse as r, Agent as t };
 
-//# sourceMappingURL=src-BNU3ZiJM.js.map
+//# sourceMappingURL=src-BZeu-SCD.js.map