agents 0.12.0 → 0.12.2

package/dist/index.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
@@ -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) {
@@ -524,6 +587,7 @@ var Agent = class Agent extends Server {
 		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();
@@ -587,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,
@@ -678,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,
@@ -717,7 +785,8 @@ var Agent = class Agent extends Server {
 			});
 		};
 		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,
@@ -743,6 +812,11 @@ 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();
@@ -2577,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` /
@@ -2640,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);
 	}
 	/**