@agentuity/react 0.0.43 → 0.0.44

package/README.md

@@ -30,7 +30,7 @@ import { AgentuityProvider } from '@agentuity/react';
 
 function App() {
 	return (
-		<AgentuityProvider baseUrl="http://localhost:3000">
+		<AgentuityProvider baseUrl="http://localhost:3500">
 			<YourApp />
 		</AgentuityProvider>
 	);
@@ -158,4 +158,4 @@ All hooks are fully typed and will infer input/output types from your agent defi
 
 ## License
 
-MIT
+Apache 2.0

package/dist/eventstream.d.ts

@@ -0,0 +1,36 @@
+import type { InferOutput } from '@agentuity/core';
+import type { AgentName, AgentRegistry } from './types';
+type onMessageHandler<T = unknown> = (data: T) => void;
+interface EventStreamArgs {
+    /**
+     * Optional query parameters to append to the EventStream URL
+     */
+    query?: URLSearchParams;
+    /**
+     * Optional subpath to append to the agent path (such as /agent/:agent_name/:subpath)
+     */
+    subpath?: string;
+    /**
+     * Optional AbortSignal to cancel the EventStream connection
+     */
+    signal?: AbortSignal;
+}
+interface EventStreamResponse<TOutput> {
+    connected: boolean;
+    data?: TOutput;
+    error: Error | null;
+    setHandler: (handler: onMessageHandler<TOutput>) => void;
+    readyState: number;
+    close: () => void;
+    reset: () => void;
+}
+export declare const useEventStream: <TOutput>(path: string, options?: EventStreamArgs) => EventStreamResponse<TOutput>;
+interface UseAgentEventStreamResponse<TOutput> extends Omit<EventStreamResponse<TOutput>, 'setHandler'> {
+    /**
+     * Data received from the agent via EventStream
+     */
+    data?: TOutput;
+}
+export declare const useAgentEventStream: <TName extends AgentName, TOutput = TName extends keyof AgentRegistry ? InferOutput<AgentRegistry[TName]["outputSchema"]> : never>(agent: TName, options?: EventStreamArgs) => UseAgentEventStreamResponse<TOutput>;
+export {};
+//# sourceMappingURL=eventstream.d.ts.map

package/dist/eventstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventstream.d.ts","sourceRoot":"","sources":["../src/eventstream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAIxD,KAAK,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAEvD,UAAU,eAAe;IACxB;;OAEG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,UAAU,mBAAmB,CAAC,OAAO;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,EACrC,MAAM,MAAM,EACZ,UAAU,eAAe,KACvB,mBAAmB,CAAC,OAAO,CA+I7B,CAAC;AAEF,UAAU,2BAA2B,CAAC,OAAO,CAC5C,SAAQ,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IACxD;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,eAAO,MAAM,mBAAmB,GAC/B,KAAK,SAAS,SAAS,EACvB,OAAO,GAAG,KAAK,SAAS,MAAM,aAAa,GACxC,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,CAAC,GACjD,KAAK,EAER,OAAO,KAAK,EACZ,UAAU,eAAe,KACvB,2BAA2B,CAAC,OAAO,CAmBrC,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './context';
 export * from './run';
 export * from './websocket';
+export * from './eventstream';
 export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC"}

package/dist/reconnect.d.ts

@@ -0,0 +1,22 @@
+export interface ReconnectOptions {
+    onReconnect: () => void;
+    threshold?: number;
+    baseDelay?: number;
+    factor?: number;
+    maxDelay?: number;
+    jitter?: number;
+    enabled?: () => boolean;
+}
+export interface ReconnectManager {
+    recordFailure: () => {
+        scheduled: boolean;
+        delay: number | null;
+    };
+    recordSuccess: () => void;
+    cancel: () => void;
+    reset: () => void;
+    dispose: () => void;
+    getAttempts: () => number;
+}
+export declare function createReconnectManager(opts: ReconnectOptions): ReconnectManager;
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../src/reconnect.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAChC,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAChC,aAAa,EAAE,MAAM;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClE,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CAqD/E"}

package/dist/serialization.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deserialize data received from WebSocket or EventStream.
+ * Attempts to parse as JSON if the data looks like JSON, otherwise returns as-is.
+ */
+export declare const deserializeData: <T>(data: string) => T;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,MAAM,MAAM,KAAG,CAWjD,CAAC"}

package/dist/websocket.d.ts

@@ -32,6 +32,6 @@ interface UseAgentWebsocketResponse<TInput, TOutput> extends Omit<WebsocketRespo
      */
     data?: TOutput;
 }
-export declare const useAgentWebsocket: <TName extends AgentName, TInput = TName extends keyof AgentRegistry ? InferInput<AgentRegistry[TName]["inputSchema"]> : never, TOutput = TName extends keyof AgentRegistry ? InferOutput<AgentRegistry[TName]["outputSchema"]> : never>(agent: AgentName, options?: WebsocketArgs) => UseAgentWebsocketResponse<TInput, TOutput>;
+export declare const useAgentWebsocket: <TName extends AgentName, TInput = TName extends keyof AgentRegistry ? InferInput<AgentRegistry[TName]["inputSchema"]> : never, TOutput = TName extends keyof AgentRegistry ? InferOutput<AgentRegistry[TName]["outputSchema"]> : never>(agent: TName, options?: WebsocketArgs) => UseAgentWebsocketResponse<TInput, TOutput>;
 export {};
 //# sourceMappingURL=websocket.d.ts.map

package/dist/websocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG/D,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD,KAAK,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAEvD,UAAU,aAAa;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AA8BD,UAAU,iBAAiB,CAAC,MAAM,EAAE,OAAO;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,UAAU,EAAE,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IACzD,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACpC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,eAAO,MAAM,YAAY,GAAI,MAAM,EAAE,OAAO,EAC3C,MAAM,MAAM,EACZ,UAAU,aAAa,KACrB,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAkHnC,CAAC;AAEF,UAAU,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAClD,SAAQ,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC;IAC9D;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,eAAO,MAAM,iBAAiB,GAC7B,KAAK,SAAS,SAAS,EACvB,MAAM,GAAG,KAAK,SAAS,MAAM,aAAa,GACvC,UAAU,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,CAAC,GAC/C,KAAK,EACR,OAAO,GAAG,KAAK,SAAS,MAAM,aAAa,GACxC,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,CAAC,GACjD,KAAK,EAER,OAAO,SAAS,EAChB,UAAU,aAAa,KACrB,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAoB3C,CAAC"}
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG/D,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAIxD,KAAK,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAEvD,UAAU,aAAa;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAiBD,UAAU,iBAAiB,CAAC,MAAM,EAAE,OAAO;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,UAAU,EAAE,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IACzD,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACpC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,eAAO,MAAM,YAAY,GAAI,MAAM,EAAE,OAAO,EAC3C,MAAM,MAAM,EACZ,UAAU,aAAa,KACrB,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAuJnC,CAAC;AAEF,UAAU,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAClD,SAAQ,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC;IAC9D;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,eAAO,MAAM,iBAAiB,GAC7B,KAAK,SAAS,SAAS,EACvB,MAAM,GAAG,KAAK,SAAS,MAAM,aAAa,GACvC,UAAU,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,CAAC,GAC/C,KAAK,EACR,OAAO,GAAG,KAAK,SAAS,MAAM,aAAa,GACxC,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,CAAC,GACjD,KAAK,EAER,OAAO,KAAK,EACZ,UAAU,aAAa,KACrB,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAoB3C,CAAC"}

package/package.json

@@ -1,6 +1,8 @@
 {
 	"name": "@agentuity/react",
-	"version": "0.0.43",
+	"version": "0.0.44",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./dist/index.d.ts",
@@ -23,7 +25,7 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "0.0.35"
+		"@agentuity/core": "0.0.43"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.0"

package/src/eventstream.ts

@@ -0,0 +1,219 @@
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import type { InferOutput } from '@agentuity/core';
+import { AgentuityContext } from './context';
+import { buildUrl } from './url';
+import type { AgentName, AgentRegistry } from './types';
+import { deserializeData } from './serialization';
+import { createReconnectManager } from './reconnect';
+
+type onMessageHandler<T = unknown> = (data: T) => void;
+
+interface EventStreamArgs {
+	/**
+	 * Optional query parameters to append to the EventStream URL
+	 */
+	query?: URLSearchParams;
+	/**
+	 * Optional subpath to append to the agent path (such as /agent/:agent_name/:subpath)
+	 */
+	subpath?: string;
+	/**
+	 * Optional AbortSignal to cancel the EventStream connection
+	 */
+	signal?: AbortSignal;
+}
+
+interface EventStreamResponse<TOutput> {
+	connected: boolean;
+	data?: TOutput;
+	error: Error | null;
+	setHandler: (handler: onMessageHandler<TOutput>) => void;
+	readyState: number;
+	close: () => void;
+	reset: () => void;
+}
+
+export const useEventStream = <TOutput>(
+	path: string,
+	options?: EventStreamArgs
+): EventStreamResponse<TOutput> => {
+	const context = useContext(AgentuityContext);
+
+	if (!context) {
+		throw new Error('useEventStream must be used within a AgentuityProvider');
+	}
+
+	const manualClose = useRef(false);
+	const esRef = useRef<EventSource | undefined>(undefined);
+	const pending = useRef<TOutput[]>([]);
+	const handler = useRef<onMessageHandler<TOutput> | undefined>(undefined);
+	const reconnectManagerRef = useRef<ReturnType<typeof createReconnectManager> | undefined>(
+		undefined
+	);
+
+	const [data, setData] = useState<TOutput>();
+	const [error, setError] = useState<Error | null>(null);
+	const [connected, setConnected] = useState(false);
+
+	const esUrl = useMemo(
+		() => buildUrl(context.baseUrl!, path, options?.subpath, options?.query),
+		[context.baseUrl, path, options?.subpath, options?.query?.toString()]
+	);
+
+	const connect = useCallback(() => {
+		if (manualClose.current) return;
+
+		esRef.current = new EventSource(esUrl);
+		let firstMessageReceived = false;
+
+		esRef.current.onopen = () => {
+			reconnectManagerRef.current?.recordSuccess();
+			setConnected(true);
+			setError(null);
+		};
+
+		esRef.current.onerror = () => {
+			setError(new Error('EventStream error'));
+			setConnected(false);
+
+			if (manualClose.current) {
+				return;
+			}
+
+			const result = reconnectManagerRef.current?.recordFailure();
+			if (result?.scheduled) {
+				const es = esRef.current;
+				if (es) {
+					es.onopen = null;
+					es.onerror = null;
+					es.onmessage = null;
+					es.close();
+				}
+				esRef.current = undefined;
+			}
+		};
+
+		esRef.current.onmessage = (event: MessageEvent) => {
+			if (!firstMessageReceived) {
+				reconnectManagerRef.current?.recordSuccess();
+				firstMessageReceived = true;
+			}
+			const payload = deserializeData<TOutput>(event.data);
+			setData(payload);
+			if (handler.current) {
+				handler.current(payload);
+			} else {
+				pending.current.push(payload);
+			}
+		};
+	}, [esUrl]);
+
+	useEffect(() => {
+		reconnectManagerRef.current = createReconnectManager({
+			onReconnect: connect,
+			threshold: 3,
+			baseDelay: 500,
+			factor: 2,
+			maxDelay: 30000,
+			jitter: 250,
+			enabled: () => !manualClose.current,
+		});
+		return () => reconnectManagerRef.current?.dispose();
+	}, [connect]);
+
+	const cleanup = useCallback(() => {
+		manualClose.current = true;
+		reconnectManagerRef.current?.dispose();
+		const es = esRef.current;
+		if (es) {
+			es.onopen = null;
+			es.onerror = null;
+			es.onmessage = null;
+			es.close();
+		}
+		esRef.current = undefined;
+		handler.current = undefined;
+		pending.current = [];
+		setConnected(false);
+	}, []);
+
+	useEffect(() => {
+		manualClose.current = false;
+		connect();
+
+		return () => {
+			cleanup();
+		};
+	}, [connect, cleanup]);
+
+	useEffect(() => {
+		if (options?.signal) {
+			const listener = () => {
+				cleanup();
+			};
+			options.signal.addEventListener('abort', listener);
+			return () => {
+				options.signal?.removeEventListener('abort', listener);
+			};
+		}
+	}, [options?.signal, cleanup]);
+
+	const reset = () => setError(null);
+
+	const setHandler = useCallback((h: onMessageHandler<TOutput>) => {
+		handler.current = h;
+		pending.current.forEach(h);
+		pending.current = [];
+	}, []);
+
+	const close = () => {
+		cleanup();
+	};
+
+	return {
+		connected,
+		close,
+		data,
+		error,
+		setHandler,
+		reset,
+		readyState: esRef.current?.readyState ?? EventSource.CLOSED,
+	};
+};
+
+interface UseAgentEventStreamResponse<TOutput>
+	extends Omit<EventStreamResponse<TOutput>, 'setHandler'> {
+	/**
+	 * Data received from the agent via EventStream
+	 */
+	data?: TOutput;
+}
+
+export const useAgentEventStream = <
+	TName extends AgentName,
+	TOutput = TName extends keyof AgentRegistry
+		? InferOutput<AgentRegistry[TName]['outputSchema']>
+		: never,
+>(
+	agent: TName,
+	options?: EventStreamArgs
+): UseAgentEventStreamResponse<TOutput> => {
+	const [data, setData] = useState<TOutput>();
+	const { connected, close, setHandler, readyState, error, reset } = useEventStream<TOutput>(
+		`/agent/${agent}`,
+		options
+	);
+
+	useEffect(() => {
+		setHandler(setData);
+	}, [agent, setHandler]);
+
+	return {
+		connected,
+		close,
+		data,
+		error,
+		reset,
+		readyState,
+	};
+};

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './context';
 export * from './run';
 export * from './websocket';
+export * from './eventstream';
 export * from './types';

package/src/reconnect.ts

@@ -0,0 +1,73 @@
+export interface ReconnectOptions {
+	onReconnect: () => void;
+	threshold?: number;
+	baseDelay?: number;
+	factor?: number;
+	maxDelay?: number;
+	jitter?: number;
+	enabled?: () => boolean;
+}
+
+export interface ReconnectManager {
+	recordFailure: () => { scheduled: boolean; delay: number | null };
+	recordSuccess: () => void;
+	cancel: () => void;
+	reset: () => void;
+	dispose: () => void;
+	getAttempts: () => number;
+}
+
+export function createReconnectManager(opts: ReconnectOptions): ReconnectManager {
+	let attempts = 0;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	const cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	};
+
+	const reset = () => {
+		attempts = 0;
+		cancel();
+	};
+
+	const recordSuccess = () => reset();
+
+	const computeDelay = (attemptAfterThreshold: number) => {
+		const base = opts.baseDelay ?? 500;
+		const factor = opts.factor ?? 2;
+		const max = opts.maxDelay ?? 30000;
+		const jitterMax = opts.jitter ?? 250;
+		const backoff = Math.min(base * Math.pow(factor, attemptAfterThreshold), max);
+		const jitter = jitterMax > 0 ? Math.random() * jitterMax : 0;
+		return backoff + jitter;
+	};
+
+	const recordFailure = () => {
+		attempts += 1;
+		const threshold = opts.threshold ?? 0;
+		if (opts.enabled && !opts.enabled()) {
+			return { scheduled: false, delay: null };
+		}
+
+		if (attempts - threshold >= 0) {
+			const after = Math.max(0, attempts - threshold);
+			const delay = computeDelay(after);
+			cancel();
+			timer = setTimeout(() => {
+				if (opts.enabled && !opts.enabled()) return;
+				opts.onReconnect();
+			}, delay);
+			return { scheduled: true, delay };
+		}
+		return { scheduled: false, delay: null };
+	};
+
+	const dispose = () => cancel();
+
+	const getAttempts = () => attempts;
+
+	return { recordFailure, recordSuccess, cancel, reset, dispose, getAttempts };
+}

package/src/serialization.ts

@@ -0,0 +1,16 @@
+/**
+ * Deserialize data received from WebSocket or EventStream.
+ * Attempts to parse as JSON if the data looks like JSON, otherwise returns as-is.
+ */
+export const deserializeData = <T>(data: string): T => {
+	if (data) {
+		if (data.startsWith('{') || data.startsWith('[')) {
+			try {
+				return JSON.parse(data) as T;
+			} catch (ex) {
+				console.error('error parsing data as JSON', ex, data);
+			}
+		}
+	}
+	return data as T;
+};

package/src/url.ts

@@ -22,4 +22,4 @@ export const defaultBaseUrl: string =
 	getProcessEnv('NEXT_PUBLIC__AGENTUITY_URL') ||
 	getProcessEnv('VITE_AGENTUITY_URL') ||
 	getProcessEnv('AGENTUITY_URL') ||
-	'http://localhost:3000';
+	'http://localhost:3500';

package/src/websocket.ts

@@ -1,8 +1,10 @@
-import { useContext, useEffect, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import type { InferInput, InferOutput } from '@agentuity/core';
 import { AgentuityContext } from './context';
 import { buildUrl } from './url';
 import type { AgentName, AgentRegistry } from './types';
+import { deserializeData } from './serialization';
+import { createReconnectManager } from './reconnect';
 
 type onMessageHandler<T = unknown> = (data: T) => void;
 
@@ -36,19 +38,6 @@ const serializeWSData = (
 	throw new Error('unsupported data type for websocket: ' + typeof data);
 };
 
-const deserializeData = <T>(data: string): T => {
-	if (data) {
-		if (data.startsWith('{') || data.startsWith('[')) {
-			try {
-				return JSON.parse(data) as T;
-			} catch (ex) {
-				console.error('error parsing websocket data as JSON', ex, data);
-			}
-		}
-	}
-	return data as T;
-};
-
 interface WebsocketResponse<TInput, TOutput> {
 	connected: boolean;
 	data?: TOutput;
@@ -74,77 +63,118 @@ export const useWebsocket = <TInput, TOutput>(
 	const wsRef = useRef<WebSocket | undefined>(undefined);
 	const pending = useRef<TOutput[]>([]);
 	const queued = useRef<TInput[]>([]);
+	const handler = useRef<onMessageHandler<TOutput> | undefined>(undefined);
+	const reconnectManagerRef = useRef<ReturnType<typeof createReconnectManager> | undefined>(
+		undefined
+	);
+
 	const [data, setData] = useState<TOutput>();
 	const [error, setError] = useState<Error | null>(null);
-	const handler = useRef<onMessageHandler<TOutput> | undefined>(undefined);
 	const [connected, setConnected] = useState(false);
 
+	const wsUrl = useMemo(() => {
+		const base = context.baseUrl!;
+		const wsBase = base.replace(/^http(s?):/, 'ws$1:');
+		return buildUrl(wsBase, path, options?.subpath, options?.query);
+	}, [context.baseUrl, path, options?.subpath, options?.query?.toString()]);
+
+	const connect = useCallback(() => {
+		if (manualClose.current) return;
+
+		wsRef.current = new WebSocket(wsUrl);
+
+		wsRef.current.onopen = () => {
+			reconnectManagerRef.current?.recordSuccess();
+			setConnected(true);
+			setError(null);
+			if (queued.current.length > 0) {
+				queued.current.forEach((msg: unknown) => wsRef.current!.send(serializeWSData(msg)));
+				queued.current = [];
+			}
+		};
+
+		wsRef.current.onerror = () => {
+			setError(new Error('WebSocket error'));
+		};
+
+		wsRef.current.onclose = (evt) => {
+			wsRef.current = undefined;
+			setConnected(false);
+			if (manualClose.current) {
+				queued.current = [];
+				return;
+			}
+			if (evt.code !== 1000) {
+				setError(new Error(`WebSocket closed: ${evt.code} ${evt.reason || ''}`));
+			}
+			reconnectManagerRef.current?.recordFailure();
+		};
+
+		wsRef.current.onmessage = (event: { data: string }) => {
+			const payload = deserializeData<TOutput>(event.data);
+			setData(payload);
+			if (handler.current) {
+				handler.current(payload);
+			} else {
+				pending.current.push(payload);
+			}
+		};
+	}, [wsUrl]);
+
+	useEffect(() => {
+		reconnectManagerRef.current = createReconnectManager({
+			onReconnect: connect,
+			threshold: 0,
+			baseDelay: 500,
+			factor: 2,
+			maxDelay: 30000,
+			jitter: 500,
+			enabled: () => !manualClose.current,
+		});
+		return () => reconnectManagerRef.current?.dispose();
+	}, [connect]);
+
+	const cleanup = useCallback(() => {
+		manualClose.current = true;
+		reconnectManagerRef.current?.dispose();
+		const ws = wsRef.current;
+		if (ws) {
+			ws.onopen = null;
+			ws.onerror = null;
+			ws.onclose = null;
+			ws.onmessage = null;
+			ws.close();
+		}
+		wsRef.current = undefined;
+		handler.current = undefined;
+		pending.current = [];
+		queued.current = [];
+		setConnected(false);
+	}, []);
+
+	useEffect(() => {
+		manualClose.current = false;
+		connect();
+
+		return () => {
+			cleanup();
+		};
+	}, [connect, cleanup]);
+
 	useEffect(() => {
 		if (options?.signal) {
 			const listener = () => {
-				wsRef.current?.close();
-				wsRef.current = undefined;
-				manualClose.current = true;
+				cleanup();
 			};
 			options.signal.addEventListener('abort', listener);
 			return () => {
 				options.signal?.removeEventListener('abort', listener);
 			};
 		}
-	}, []);
+	}, [options?.signal, cleanup]);
 
 	const reset = () => setError(null);
 
-	if (!wsRef.current) {
-		const wsUrl = buildUrl(
-			context.baseUrl!.replace(/^https?:/, 'ws:'),
-			path,
-			options?.subpath,
-			options?.query
-		);
-		const connect = () => {
-			wsRef.current = new WebSocket(wsUrl);
-			wsRef.current.onopen = () => {
-				setConnected(true);
-				setError(null);
-				if (queued.current.length > 0) {
-					queued.current.forEach((msg: unknown) => wsRef.current!.send(serializeWSData(msg)));
-					queued.current = [];
-				}
-			};
-			wsRef.current.onerror = () => {
-				setError(new Error('WebSocket error'));
-			};
-			wsRef.current.onclose = (evt) => {
-				wsRef.current = undefined;
-				queued.current = [];
-				setConnected(false);
-				if (manualClose.current) {
-					return;
-				}
-				if (evt.code !== 1000) {
-					setError(new Error(`WebSocket closed: ${evt.code} ${evt.reason || ''}`));
-				}
-				setTimeout(
-					() => {
-						connect();
-					},
-					Math.random() * 500 + 500
-				); // jitter reconnect
-			};
-			wsRef.current.onmessage = (event: { data: string }) => {
-				const payload = deserializeData<TOutput>(event.data);
-				setData(payload);
-				if (handler.current) {
-					handler.current(payload);
-				} else {
-					pending.current.push(payload);
-				}
-			};
-		};
-		connect();
-	}
-
 	const send = (data: TInput) => {
 		if (wsRef.current?.readyState === WebSocket.OPEN) {
 			wsRef.current.send(serializeWSData(data));
@@ -153,18 +183,14 @@ export const useWebsocket = <TInput, TOutput>(
 		}
 	};
 
-	const setHandler = (h: onMessageHandler<TOutput>) => {
+	const setHandler = useCallback((h: onMessageHandler<TOutput>) => {
 		handler.current = h;
 		pending.current.forEach(h);
 		pending.current = [];
-	};
+	}, []);
 
 	const close = () => {
-		manualClose.current = true;
-		if (wsRef.current) {
-			wsRef.current.close();
-			wsRef.current = undefined;
-		}
+		cleanup();
 	};
 
 	return {
@@ -196,7 +222,7 @@ export const useAgentWebsocket = <
 		? InferOutput<AgentRegistry[TName]['outputSchema']>
 		: never,
 >(
-	agent: AgentName,
+	agent: TName,
 	options?: WebsocketArgs
 ): UseAgentWebsocketResponse<TInput, TOutput> => {
 	const [data, setData] = useState<TOutput>();
@@ -207,7 +233,7 @@ export const useAgentWebsocket = <
 
 	useEffect(() => {
 		setHandler(setData);
-	}, []);
+	}, [agent, setHandler]);
 
 	return {
 		connected,