agents 0.23.0 → 0.25.0

package/dist/react.js

@@ -1,12 +1,44 @@
 import { camelCaseToKebabCase } from "./utils.js";
 import "./types.js";
-import { AgentConnectionError, createStubProxy, isTerminalCloseEvent } from "./client.js";
+import { r as CAPNWEB_TRANSPORT_VALUE, t as CAPNWEB_TRANSPORT_QUERY } from "./transport-protocol-BxyngQ_R.js";
+import { d as boundCapnWebSocket, i as NativeCallQueue, l as nativeCall, n as AgentConnectionError, o as createCloseClassifier, s as createStubProxy, u as splitCallOptions } from "./client-4OlMIJx-.js";
 import { buildSubAgentPathUnchecked } from "./sub-routing.js";
-import { n as applyAgentToolEvent, r as createAgentToolEventState } from "./agent-tools-y7zLfw4Q.js";
+import { SOCKET_ADDRESS_PENDING } from "./socket-address.js";
+import { i as createAgentToolEventState, n as agentToolEventDedupeKey, r as applyAgentToolEvent } from "./agent-tools-CdJC-8Dc.js";
 import { usePartySocket } from "partysocket/react";
 import { use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 //#region src/react.tsx
 const queryCache = /* @__PURE__ */ new Map();
+function socketDestinationKey(options) {
+	return JSON.stringify([
+		options.host ?? null,
+		options.basePath ?? null,
+		options.party ?? null,
+		options.prefix ?? null,
+		options.room ?? null,
+		options.path ?? null,
+		options.protocol ?? null,
+		options.protocols ?? null
+	]);
+}
+function createReadyEntry() {
+	let resolvePromise;
+	const entry = {
+		promise: new Promise((r) => {
+			resolvePromise = r;
+		}),
+		resolved: false,
+		resolve: () => {
+			entry.resolved = true;
+			resolvePromise();
+		}
+	};
+	return entry;
+}
+/** The host `usePartySocket` connects to when none is given. */
+function defaultSocketHost() {
+	return typeof window !== "undefined" ? window.location.host : "dummy-domain.com";
+}
 function createCacheKey(agentNamespace, name, subChainOrDeps, deps) {
 	if (deps === void 0) return JSON.stringify([
 		agentNamespace,
@@ -64,7 +96,14 @@ const _testUtils = {
 };
 function useAgent(options) {
 	const agentNamespace = camelCaseToKebabCase(options.agent);
-	const { query, queryDeps, cacheTtl, sub: subOption, path: userPath, defaultCallTimeout, onConnectionError, shouldReconnectOnClose, ...restOptions } = options;
+	const { query, queryDeps, cacheTtl, sub: subOption, path: userPath, defaultCallTimeout, onConnectionError, shouldReconnectOnClose, transport = "cf-websocket", ...restOptions } = options;
+	const capnWebRef = useRef(null);
+	const transportRef = useRef(transport);
+	transportRef.current = transport;
+	const nativeQueueRef = useRef(new NativeCallQueue());
+	const socketClass = useMemo(() => transport === "capnweb" ? { WebSocket: boundCapnWebSocket((socket) => {
+		capnWebRef.current = socket;
+	}) } : {}, [transport]);
 	const subChain = useMemo(() => (subOption ?? []).map((s) => ({
 		agent: s.agent,
 		name: s.name
@@ -101,9 +140,12 @@ function useAgent(options) {
 			socket.send(pending.request);
 			pending.sentOn = socket;
 		}
+		const native = transportRef.current === "capnweb" ? capnWebRef.current : null;
+		if (native) nativeQueueRef.current.flush(native);
 	};
 	/** Reject (and remove) every still-queued (never transmitted) call. */
 	const rejectQueuedCalls = (reason) => {
+		nativeQueueRef.current.rejectAll(reason);
 		const error = new Error(reason);
 		for (const [id, pending] of pendingCallsRef.current) if (pending.sentOn === null) {
 			if (pending.timeoutId) clearTimeout(pending.timeoutId);
@@ -174,42 +216,57 @@ function useAgent(options) {
 	const connectionErrorAddressKeyRef = useRef(null);
 	const shouldReconnectOnCloseRef = useRef(shouldReconnectOnClose);
 	shouldReconnectOnCloseRef.current = shouldReconnectOnClose;
-	const classifyReconnect = useCallback((event) => (shouldReconnectOnCloseRef.current?.(event) ?? true) && !isTerminalCloseEvent(event), []);
-	const [identity, setIdentity] = useState({
+	const maxRetriesRef = useRef(restOptions.maxRetries);
+	maxRetriesRef.current = restOptions.maxRetries;
+	const [closeClassifier] = useState(() => createCloseClassifier({
+		socket: () => socketRef.current,
+		shouldReconnectOnClose: () => shouldReconnectOnCloseRef.current,
+		maxRetries: () => maxRetriesRef.current
+	}));
+	const classifyReconnect = closeClassifier.shouldReconnectOnClose;
+	const [identity, setIdentity] = useState(() => ({
 		name: leafName,
 		agent: camelCaseToKebabCase(leafAgent),
-		identified: false
-	});
+		identified: false,
+		destination: null
+	}));
 	const previousIdentityRef = useRef({
 		name: null,
 		agent: null
 	});
-	const readyRef = useRef(void 0);
-	const resetReady = () => {
-		let resolve;
-		readyRef.current = {
-			promise: new Promise((r) => {
-				resolve = r;
-			}),
-			resolve
-		};
+	const readyRef = useRef(/* @__PURE__ */ new Map());
+	const readyFor = (destination) => {
+		let entry = readyRef.current.get(destination);
+		if (!entry) {
+			entry = createReadyEntry();
+			readyRef.current.set(destination, entry);
+		}
+		return entry;
+	};
+	const resetReady = (destination) => {
+		if (readyRef.current.get(destination)?.resolved !== false) readyRef.current.set(destination, createReadyEntry());
 	};
-	if (!readyRef.current) resetReady();
 	const mutableAgentRef = useRef(null);
 	const combinedPath = useMemo(() => buildSubPath(subChain, userPath), [subChain, userPath]);
+	const socketQuery = transport === "capnweb" ? {
+		...resolvedQuery,
+		[CAPNWEB_TRANSPORT_QUERY]: CAPNWEB_TRANSPORT_VALUE
+	} : resolvedQuery;
 	const socketOptions = options.basePath ? {
 		basePath: options.basePath,
 		path: combinedPath || void 0,
-		query: resolvedQuery,
+		query: socketQuery,
 		...restOptions,
+		...socketClass,
 		shouldReconnectOnClose: classifyReconnect
 	} : {
 		party: agentNamespace,
 		prefix: "agents",
 		room: options.name || "default",
 		path: combinedPath || void 0,
-		query: resolvedQuery,
+		query: socketQuery,
 		...restOptions,
+		...socketClass,
 		shouldReconnectOnClose: classifyReconnect
 	};
 	const socketEnabled = !awaitingQueryRefresh && (restOptions.enabled ?? true);
@@ -218,10 +275,65 @@ function useAgent(options) {
 		options.basePath ?? null,
 		agentNamespace,
 		options.name || "default",
-		combinedPath || null
+		combinedPath || null,
+		transport
 	]);
+	const destination = socketDestinationKey({
+		...socketOptions,
+		host: socketOptions.host || defaultSocketHost()
+	});
+	const seedDestinationRef = useRef(destination);
 	const visibleConnectionError = connectionErrorAddressKeyRef.current === addressKey ? connectionError : null;
 	connectionErrorRef.current = visibleConnectionError;
+	const connectProgressRef = useRef(/* @__PURE__ */ new WeakMap());
+	const connectProgress = (socket) => {
+		if (!socket) return {
+			stateSeen: false,
+			pendingIdentity: null
+		};
+		let progress = connectProgressRef.current.get(socket);
+		if (!progress) {
+			progress = {
+				stateSeen: false,
+				pendingIdentity: null
+			};
+			connectProgressRef.current.set(socket, progress);
+		}
+		return progress;
+	};
+	const applyIdentity = (newName, newAgent, identifiedSocket) => {
+		const oldName = previousIdentityRef.current.name;
+		const oldAgent = previousIdentityRef.current.agent;
+		const currentAgent = mutableAgentRef.current;
+		if (currentAgent) {
+			currentAgent.name = newName;
+			currentAgent.agent = newAgent;
+			currentAgent.identified = true;
+		}
+		const identifiedDestination = identifiedSocket ? socketDestinationKey(identifiedSocket.partySocketOptions) : null;
+		setIdentity({
+			name: newName,
+			agent: newAgent,
+			identified: true,
+			destination: identifiedDestination
+		});
+		if (identifiedDestination !== null) readyFor(identifiedDestination).resolve();
+		if (oldName !== null && oldAgent !== null && (oldName !== newName || oldAgent !== newAgent)) if (options.onIdentityChange) options.onIdentityChange(oldName, newName, oldAgent, newAgent);
+		else {
+			const agentChanged = oldAgent !== newAgent;
+			const nameChanged = oldName !== newName;
+			let changeDescription = "";
+			if (agentChanged && nameChanged) changeDescription = `agent "${oldAgent}" → "${newAgent}", instance "${oldName}" → "${newName}"`;
+			else if (agentChanged) changeDescription = `agent "${oldAgent}" → "${newAgent}"`;
+			else changeDescription = `instance "${oldName}" → "${newName}"`;
+			console.warn(`[agents] Identity changed on reconnect: ${changeDescription}. This can happen with server-side routing (e.g., basePath with getAgentByName) where the instance is determined by auth/session. Provide onIdentityChange callback to handle this explicitly, or ignore if this is expected for your routing pattern.`);
+		}
+		previousIdentityRef.current = {
+			name: newName,
+			agent: newAgent
+		};
+		options.onIdentity?.(newName, newAgent);
+	};
 	const agent = usePartySocket({
 		...socketOptions,
 		enabled: socketEnabled,
@@ -240,42 +352,32 @@ function useAgent(options) {
 					return options.onMessage?.(message);
 				}
 				if (parsedMessage.type === "cf_agent_identity") {
-					const oldName = previousIdentityRef.current.name;
-					const oldAgent = previousIdentityRef.current.agent;
+					const identifiedSocket = message.target ?? socketRef.current;
 					const newName = parsedMessage.name;
 					const newAgent = parsedMessage.agent;
-					const currentAgent = mutableAgentRef.current;
-					if (currentAgent) {
-						currentAgent.name = newName;
-						currentAgent.agent = newAgent;
-						currentAgent.identified = true;
-					}
-					setIdentity({
-						name: newName,
-						agent: newAgent,
-						identified: true
-					});
-					readyRef.current?.resolve();
-					if (oldName !== null && oldAgent !== null && (oldName !== newName || oldAgent !== newAgent)) if (options.onIdentityChange) options.onIdentityChange(oldName, newName, oldAgent, newAgent);
-					else {
-						const agentChanged = oldAgent !== newAgent;
-						const nameChanged = oldName !== newName;
-						let changeDescription = "";
-						if (agentChanged && nameChanged) changeDescription = `agent "${oldAgent}" → "${newAgent}", instance "${oldName}" → "${newName}"`;
-						else if (agentChanged) changeDescription = `agent "${oldAgent}" → "${newAgent}"`;
-						else changeDescription = `instance "${oldName}" → "${newName}"`;
-						console.warn(`[agents] Identity changed on reconnect: ${changeDescription}. This can happen with server-side routing (e.g., basePath with getAgentByName) where the instance is determined by auth/session. Provide onIdentityChange callback to handle this explicitly, or ignore if this is expected for your routing pattern.`);
+					const progress = connectProgress(identifiedSocket);
+					if (parsedMessage.stateFollows === true && !progress.stateSeen) {
+						progress.pendingIdentity = [newName, newAgent];
+						return;
 					}
-					previousIdentityRef.current = {
-						name: newName,
-						agent: newAgent
-					};
-					options.onIdentity?.(newName, newAgent);
+					applyIdentity(newName, newAgent, identifiedSocket);
 					return;
 				}
 				if (parsedMessage.type === "cf_agent_state") {
 					setAgentState(parsedMessage.state);
-					options.onStateUpdate?.(parsedMessage.state, "server");
+					if (mutableAgentRef.current) mutableAgentRef.current.state = parsedMessage.state;
+					const stateSocket = message.target ?? socketRef.current;
+					try {
+						options.onStateUpdate?.(parsedMessage.state, "server");
+					} finally {
+						const progress = connectProgress(stateSocket);
+						progress.stateSeen = true;
+						const pending = progress.pendingIdentity;
+						if (pending) {
+							progress.pendingIdentity = null;
+							applyIdentity(pending[0], pending[1], stateSocket);
+						}
+					}
 					return;
 				}
 				if (parsedMessage.type === "cf_agent_state_error") {
@@ -319,24 +421,26 @@ function useAgent(options) {
 		onClose: (event) => {
 			const closedSocket = event.target ?? socketRef.current;
 			const isCurrentSocket = closedSocket === socketRef.current;
-			const terminalClose = isTerminalCloseEvent(event);
+			const finalClose = closeClassifier.takeFinalClose();
+			if (closedSocket) connectProgressRef.current.delete(closedSocket);
+			const reconnecting = !!closedSocket?.shouldReconnect && !finalClose;
 			if (closedSocket) {
 				rejectCallsSentOn(closedSocket, "Connection closed");
-				if (isCurrentSocket && !closedSocket.shouldReconnect) rejectQueuedCalls("Connection closed");
+				if (isCurrentSocket && !reconnecting) rejectQueuedCalls("Connection closed");
 			}
 			if (isCurrentSocket) {
-				resetReady();
+				if (closedSocket) resetReady(socketDestinationKey(closedSocket.partySocketOptions));
 				if (mutableAgentRef.current) mutableAgentRef.current.identified = false;
 				setIdentity((prev) => ({
 					...prev,
 					identified: false
 				}));
-				if (closedSocket?.shouldReconnect) {
+				if (reconnecting) {
 					if (isAsyncQuery) setAwaitingQueryRefresh(true);
 					deleteCacheEntry(cacheKeyRef.current);
 					setCacheInvalidatedAt(Date.now());
 				}
-				if (!closedSocket?.shouldReconnect && terminalClose) {
+				if (finalClose) {
 					const error = new AgentConnectionError(event);
 					connectionErrorAddressKeyRef.current = addressKey;
 					setConnectionError(error);
@@ -347,29 +451,49 @@ function useAgent(options) {
 		}
 	});
 	socketRef.current = agent;
+	const socketAddressPending = socketDestinationKey(agent.partySocketOptions) !== destination;
 	const prevSocketRef = useRef(null);
 	const prevAddressKeyRef = useRef(addressKey);
+	const prevDestinationRef = useRef(destination);
 	useEffect(() => {
 		const prev = prevSocketRef.current;
 		prevSocketRef.current = agent;
 		const prevAddress = prevAddressKeyRef.current;
 		prevAddressKeyRef.current = addressKey;
+		const prevDestination = prevDestinationRef.current;
+		prevDestinationRef.current = destination;
+		if (prevDestination !== destination) previousIdentityRef.current = {
+			name: null,
+			agent: null
+		};
 		if (prevAddress !== addressKey) {
 			connectionErrorAddressKeyRef.current = null;
 			setConnectionError(null);
 			rejectQueuedCalls("Call discarded: the agent address changed before the request could be sent");
 		}
+		for (const [key, entry] of readyRef.current) if (key !== destination && entry.resolved) readyRef.current.delete(key);
 		if (prev && prev !== agent) {
 			rejectCallsSentOn(prev, "Connection closed");
-			resetReady();
+			resetReady(socketDestinationKey(agent.partySocketOptions));
 			if (mutableAgentRef.current) mutableAgentRef.current.identified = false;
 			setIdentity((current) => current.identified ? {
 				...current,
 				identified: false
 			} : current);
 		}
-	}, [agent, addressKey]);
+	}, [
+		agent,
+		addressKey,
+		destination
+	]);
 	const call = useCallback((method, args = [], options) => {
+		if (transportRef.current === "capnweb") {
+			const native = capnWebRef.current;
+			const socket = socketRef.current;
+			if (native && socket?.readyState === WebSocket.OPEN) return nativeCall(native, method, args, options, defaultCallTimeoutRef.current);
+			if (socket && connectionErrorRef.current && socket.readyState === socket.CLOSED) return Promise.reject(/* @__PURE__ */ new Error("Connection closed"));
+			return nativeQueueRef.current.enqueue(method, args, options, defaultCallTimeoutRef.current);
+		}
 		return new Promise((resolve, reject) => {
 			const socket = socketRef.current;
 			if (socket && connectionErrorRef.current && socket.readyState === socket.CLOSED) {
@@ -378,9 +502,7 @@ function useAgent(options) {
 			}
 			const id = crypto.randomUUID();
 			let timeoutId;
-			const isLegacyFormat = options && ("onChunk" in options || "onDone" in options || "onError" in options);
-			const streamOptions = isLegacyFormat ? options : options?.stream;
-			const timeout = isLegacyFormat ? void 0 : options?.timeout;
+			const { stream: streamOptions, timeout } = splitCallOptions(options);
 			const effectiveTimeout = timeout !== void 0 ? timeout : streamOptions ? void 0 : defaultCallTimeoutRef.current;
 			if (effectiveTimeout) timeoutId = setTimeout(() => {
 				const pending = pendingCallsRef.current.get(id);
@@ -415,32 +537,29 @@ function useAgent(options) {
 			state: newState,
 			type: "cf_agent_state"
 		}));
+		if (mutableAgentRef.current) mutableAgentRef.current.state = newState;
 		setAgentState(newState);
 		options.onStateUpdate?.(newState, "client");
 	};
 	agent.call = call;
-	agent.agent = identity.agent;
-	agent.name = identity.name;
+	const identityIsCurrent = !!options.basePath || (identity.destination ?? seedDestinationRef.current) === destination;
+	agent.agent = identityIsCurrent ? identity.agent : camelCaseToKebabCase(leafAgent);
+	agent.name = identityIsCurrent ? identity.name : leafName;
 	agent.path = fullPath;
-	agent.identified = identity.identified;
-	agent.ready = readyRef.current.promise;
+	agent.identified = identityIsCurrent && identity.identified;
+	agent.ready = readyFor(destination).promise;
 	agent.state = agentState;
 	agent.connectionError = visibleConnectionError;
 	mutableAgentRef.current = agent;
 	agent.stub = useMemo(() => createStubProxy(call), [call]);
+	agent[SOCKET_ADDRESS_PENDING] = socketAddressPending;
 	agent.getHttpUrl = () => {
+		if (socketAddressPending) return "";
 		return (agent._url || agent._pkurl || "").replace("ws://", "http://").replace("wss://", "https://");
 	};
 	if (identity.agent !== identity.agent.toLowerCase()) console.warn("Agent name: " + identity.agent + " should probably be in lowercase. Received: " + identity.agent);
 	return agent;
 }
-function agentToolDedupeKey(message) {
-	return [
-		message.parentToolCallId ?? "",
-		message.event.runId,
-		String(message.sequence)
-	].join("\0");
-}
 function useAgentToolEvents(options) {
 	const { agent } = options;
 	const [state, setState] = useState(() => createAgentToolEventState());
@@ -455,7 +574,7 @@ function useAgentToolEvents(options) {
 				return;
 			}
 			if (message.type !== "agent-tool-event") return;
-			const key = agentToolDedupeKey(message);
+			const key = agentToolEventDedupeKey(message);
 			if (seenRef.current.has(key)) return;
 			seenRef.current.add(key);
 			setState((prev) => applyAgentToolEvent(prev, message));