@agentuity/react 0.0.69 → 0.0.70

package/src/eventstream.ts

@@ -2,19 +2,39 @@ import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'r
 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';
+import { jsonEqual } from './memo';
+import type { SSERouteRegistry } from './types';
 
 type onMessageHandler<T = unknown> = (data: T) => void;
 
-interface EventStreamArgs {
+/**
+ * Extract SSE route keys (e.g., '/events', '/notifications')
+ */
+export type SSERouteKey = keyof SSERouteRegistry;
+
+/**
+ * Extract output type for an SSE route (SSE is typically one-way server->client)
+ */
+export type SSERouteOutput<TRoute extends SSERouteKey> = TRoute extends keyof SSERouteRegistry
+	? SSERouteRegistry[TRoute] extends { outputSchema: infer TSchema }
+		? TSchema extends undefined | never
+			? void
+			: InferOutput<TSchema>
+		: void
+	: void;
+
+/**
+ * Options for EventStream hooks
+ */
+export interface EventStreamOptions {
 	/**
 	 * 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)
+	 * Optional subpath to append to the EventStream path
 	 */
 	subpath?: string;
 	/**
@@ -23,20 +43,29 @@ interface EventStreamArgs {
 	signal?: AbortSignal;
 }
 
-interface EventStreamResponse<TOutput> {
-	connected: boolean;
+interface EventStreamResponseInternal<TOutput> {
+	/** Whether EventStream is currently connected */
+	isConnected: boolean;
+	/** Most recent data received from EventStream */
 	data?: TOutput;
+	/** Error if connection or message failed */
 	error: Error | null;
+	/** Whether an error has occurred */
+	isError: boolean;
+	/** Set handler for incoming messages (use data property instead) */
 	setHandler: (handler: onMessageHandler<TOutput>) => void;
+	/** EventStream connection state (CONNECTING=0, OPEN=1, CLOSED=2) */
 	readyState: number;
+	/** Close the EventStream connection */
 	close: () => void;
+	/** Reset state to initial values */
 	reset: () => void;
 }
 
-export const useEventStream = <TOutput>(
+const useEventStreamInternal = <TOutput>(
 	path: string,
-	options?: EventStreamArgs
-): EventStreamResponse<TOutput> => {
+	options?: EventStreamOptions
+): EventStreamResponseInternal<TOutput> => {
 	const context = useContext(AgentuityContext);
 
 	if (!context) {
@@ -53,7 +82,8 @@ export const useEventStream = <TOutput>(
 
 	const [data, setData] = useState<TOutput>();
 	const [error, setError] = useState<Error | null>(null);
-	const [connected, setConnected] = useState(false);
+	const [isError, setIsError] = useState(false);
+	const [isConnected, setIsConnected] = useState(false);
 
 	const esUrl = useMemo(
 		() => buildUrl(context.baseUrl!, path, options?.subpath, options?.query),
@@ -68,13 +98,15 @@ export const useEventStream = <TOutput>(
 
 		esRef.current.onopen = () => {
 			reconnectManagerRef.current?.recordSuccess();
-			setConnected(true);
+			setIsConnected(true);
 			setError(null);
+			setIsError(false);
 		};
 
 		esRef.current.onerror = () => {
 			setError(new Error('EventStream error'));
-			setConnected(false);
+			setIsError(true);
+			setIsConnected(false);
 
 			if (manualClose.current) {
 				return;
@@ -99,7 +131,8 @@ export const useEventStream = <TOutput>(
 				firstMessageReceived = true;
 			}
 			const payload = deserializeData<TOutput>(event.data);
-			setData(payload);
+			// Use JSON memoization to prevent re-renders when data hasn't changed
+			setData((prev) => (prev !== undefined && jsonEqual(prev, payload) ? prev : payload));
 			if (handler.current) {
 				handler.current(payload);
 			} else {
@@ -134,7 +167,7 @@ export const useEventStream = <TOutput>(
 		esRef.current = undefined;
 		handler.current = undefined;
 		pending.current = [];
-		setConnected(false);
+		setIsConnected(false);
 	}, []);
 
 	useEffect(() => {
@@ -158,7 +191,10 @@ export const useEventStream = <TOutput>(
 		}
 	}, [options?.signal, cleanup]);
 
-	const reset = () => setError(null);
+	const reset = () => {
+		setError(null);
+		setIsError(false);
+	};
 
 	const setHandler = useCallback((h: onMessageHandler<TOutput>) => {
 		handler.current = h;
@@ -171,49 +207,60 @@ export const useEventStream = <TOutput>(
 	};
 
 	return {
-		connected,
+		isConnected,
 		close,
 		data,
 		error,
+		isError,
 		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
-	);
+/**
+ * Type-safe EventStream (SSE) hook for connecting to SSE routes.
+ *
+ * Provides automatic type inference for route outputs based on
+ * the SSERouteRegistry generated from your routes.
+ *
+ * @template TRoute - SSE route key from SSERouteRegistry (e.g., '/events', '/notifications')
+ *
+ * @example Simple SSE connection
+ * ```typescript
+ * const { isConnected, data } = useEventStream('/events');
+ *
+ * // data is fully typed based on route output schema!
+ * ```
+ *
+ * @example SSE with query parameters
+ * ```typescript
+ * const { isConnected, data } = useEventStream('/notifications', {
+ *   query: new URLSearchParams({ userId: '123' })
+ * });
+ * ```
+ */
+export function useEventStream<TRoute extends SSERouteKey>(
+	route: TRoute,
+	options?: EventStreamOptions
+): Omit<EventStreamResponseInternal<SSERouteOutput<TRoute>>, 'setHandler'> & {
+	data?: SSERouteOutput<TRoute>;
+} {
+	const [data, setData] = useState<SSERouteOutput<TRoute>>();
+	const { isConnected, close, setHandler, readyState, error, isError, reset } =
+		useEventStreamInternal<SSERouteOutput<TRoute>>(route as string, options);
 
 	useEffect(() => {
 		setHandler(setData);
-	}, [agent, setHandler]);
+	}, [route, setHandler]);
 
 	return {
-		connected,
+		isConnected,
 		close,
 		data,
 		error,
+		isError,
 		reset,
 		readyState,
 	};
-};
+}

package/src/index.ts

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

package/src/memo.ts

@@ -0,0 +1,32 @@
+/**
+ * Simple JSON-based equality check for memoization.
+ * Compares stringified JSON to avoid deep equality overhead.
+ */
+export function jsonEqual<T>(a: T, b: T): boolean {
+	if (a === b) return true;
+	if (a === undefined || b === undefined) return false;
+	if (a === null || b === null) return a === b;
+
+	try {
+		return JSON.stringify(a) === JSON.stringify(b);
+	} catch {
+		// Fallback for non-serializable values
+		return false;
+	}
+}
+
+/**
+ * Hook to memoize a value based on JSON equality instead of reference equality.
+ * Prevents unnecessary re-renders when data hasn't actually changed.
+ */
+import { useRef } from 'react';
+
+export function useJsonMemo<T>(value: T): T {
+	const ref = useRef<T>(value);
+
+	if (!jsonEqual(ref.current, value)) {
+		ref.current = value;
+	}
+
+	return ref.current;
+}

package/src/serialization.ts

@@ -4,12 +4,10 @@
  */
 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);
-			}
+		try {
+			return JSON.parse(data) as T;
+		} catch {
+			/* */
 		}
 	}
 	return data as T;

package/src/types.ts

@@ -1,39 +1,29 @@
-import type { StandardSchemaV1 } from '@agentuity/core';
-
 /**
- * Agent definition interface
+ * Route registry containing all typed API routes in the application.
+ * Auto-generated by the build tool from routes that use validator() middleware.
  */
-export interface Agent<
-	TInput extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined,
-	TOutput extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined,
-> {
-	inputSchema: TInput;
-	outputSchema: TOutput;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RouteRegistry {
+	// Will be augmented by generated code
+	// Format: 'METHOD /path': { inputSchema: ..., outputSchema: ... }
 }
 
 /**
- * Registry of all agents in the project.
- * This interface is designed to be augmented by generated code in the user's project.
- *
- * Example usage in generated code (.agentuity/types.d.ts):
- * ```typescript
- * import type { Agent } from '@agentuity/react';
- * import type { MyInputSchema, MyOutputSchema } from './schemas';
- *
- * declare module '@agentuity/react' {
- *   interface AgentRegistry {
- *     'my-agent': Agent<MyInputSchema, MyOutputSchema>;
- *     'another-agent': Agent<AnotherInput, AnotherOutput>;
- *   }
- * }
- * ```
+ * WebSocket route registry containing all typed WebSocket routes in the application.
+ * Auto-generated by the build tool from routes that use validator() middleware.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface AgentRegistry {}
+export interface WebSocketRouteRegistry {
+	// Will be augmented by generated code
+	// Format: '/path': { inputSchema: ..., outputSchema: ... }
+}
 
 /**
- * Union type of all registered agent names.
- * Falls back to `string` when AgentRegistry is empty (before augmentation).
- * After augmentation, this becomes a strict union of agent names for full type safety.
+ * SSE route registry containing all typed SSE routes in the application.
+ * Auto-generated by the build tool from routes that use validator() middleware.
  */
-export type AgentName = keyof AgentRegistry extends never ? string : keyof AgentRegistry;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface SSERouteRegistry {
+	// Will be augmented by generated code
+	// Format: '/path': { inputSchema: ..., outputSchema: ... }
+}

package/src/url.ts

@@ -18,8 +18,15 @@ export const buildUrl = (
 	return url;
 };
 
+const tryOrigin = () => {
+	if (typeof window !== 'undefined') {
+		return window.location.origin;
+	}
+};
+
 export const defaultBaseUrl: string =
 	getProcessEnv('NEXT_PUBLIC_AGENTUITY_URL') ||
 	getProcessEnv('VITE_AGENTUITY_URL') ||
 	getProcessEnv('AGENTUITY_URL') ||
+	tryOrigin() ||
 	'http://localhost:3500';

package/src/websocket.ts

@@ -2,19 +2,52 @@ import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'r
 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';
+import { jsonEqual } from './memo';
+import type { WebSocketRouteRegistry } from './types';
 
 type onMessageHandler<T = unknown> = (data: T) => void;
 
-interface WebsocketArgs {
+/**
+ * Extract WebSocket route keys (e.g., '/ws', '/chat')
+ */
+export type WebSocketRouteKey = keyof WebSocketRouteRegistry;
+
+/**
+ * Extract input type for a WebSocket route
+ */
+export type WebSocketRouteInput<TRoute extends WebSocketRouteKey> =
+	TRoute extends keyof WebSocketRouteRegistry
+		? WebSocketRouteRegistry[TRoute] extends { inputSchema: infer TSchema }
+			? TSchema extends undefined | never
+				? never
+				: InferInput<TSchema>
+			: never
+		: never;
+
+/**
+ * Extract output type for a WebSocket route
+ */
+export type WebSocketRouteOutput<TRoute extends WebSocketRouteKey> =
+	TRoute extends keyof WebSocketRouteRegistry
+		? WebSocketRouteRegistry[TRoute] extends { outputSchema: infer TSchema }
+			? TSchema extends undefined | never
+				? void
+				: InferOutput<TSchema>
+			: void
+		: void;
+
+/**
+ * Options for WebSocket hooks
+ */
+export interface WebsocketOptions {
 	/**
 	 * Optional query parameters to append to the websocket URL
 	 */
 	query?: URLSearchParams;
 	/**
-	 * Optional subpath to append to the agent path (such as /agent/:agent_name/:subpath)
+	 * Optional subpath to append to the websocket path
 	 */
 	subpath?: string;
 	/**
@@ -38,21 +71,31 @@ const serializeWSData = (
 	throw new Error('unsupported data type for websocket: ' + typeof data);
 };
 
-interface WebsocketResponse<TInput, TOutput> {
-	connected: boolean;
+interface WebsocketResponseInternal<TInput, TOutput> {
+	/** Whether WebSocket is currently connected */
+	isConnected: boolean;
+	/** Most recent data received from WebSocket */
 	data?: TOutput;
+	/** Error if connection or message failed */
 	error: Error | null;
+	/** Whether an error has occurred */
+	isError: boolean;
+	/** Send data through the WebSocket */
 	send: (data: TInput) => void;
+	/** Set handler for incoming messages (use data property instead) */
 	setHandler: (handler: onMessageHandler<TOutput>) => void;
+	/** WebSocket connection state (CONNECTING=0, OPEN=1, CLOSING=2, CLOSED=3) */
 	readyState: WebSocket['readyState'];
+	/** Close the WebSocket connection */
 	close: () => void;
+	/** Reset state to initial values */
 	reset: () => void;
 }
 
-export const useWebsocket = <TInput, TOutput>(
+const useWebsocketInternal = <TInput, TOutput>(
 	path: string,
-	options?: WebsocketArgs
-): WebsocketResponse<TInput, TOutput> => {
+	options?: WebsocketOptions
+): WebsocketResponseInternal<TInput, TOutput> => {
 	const context = useContext(AgentuityContext);
 
 	if (!context) {
@@ -70,7 +113,8 @@ export const useWebsocket = <TInput, TOutput>(
 
 	const [data, setData] = useState<TOutput>();
 	const [error, setError] = useState<Error | null>(null);
-	const [connected, setConnected] = useState(false);
+	const [isError, setIsError] = useState(false);
+	const [isConnected, setIsConnected] = useState(false);
 
 	const wsUrl = useMemo(() => {
 		const base = context.baseUrl!;
@@ -85,8 +129,9 @@ export const useWebsocket = <TInput, TOutput>(
 
 		wsRef.current.onopen = () => {
 			reconnectManagerRef.current?.recordSuccess();
-			setConnected(true);
+			setIsConnected(true);
 			setError(null);
+			setIsError(false);
 			if (queued.current.length > 0) {
 				queued.current.forEach((msg: unknown) => wsRef.current!.send(serializeWSData(msg)));
 				queued.current = [];
@@ -95,24 +140,27 @@ export const useWebsocket = <TInput, TOutput>(
 
 		wsRef.current.onerror = () => {
 			setError(new Error('WebSocket error'));
+			setIsError(true);
 		};
 
 		wsRef.current.onclose = (evt) => {
 			wsRef.current = undefined;
-			setConnected(false);
+			setIsConnected(false);
 			if (manualClose.current) {
 				queued.current = [];
 				return;
 			}
 			if (evt.code !== 1000) {
 				setError(new Error(`WebSocket closed: ${evt.code} ${evt.reason || ''}`));
+				setIsError(true);
 			}
 			reconnectManagerRef.current?.recordFailure();
 		};
 
 		wsRef.current.onmessage = (event: { data: string }) => {
 			const payload = deserializeData<TOutput>(event.data);
-			setData(payload);
+			// Use JSON memoization to prevent re-renders when data hasn't changed
+			setData((prev) => (prev !== undefined && jsonEqual(prev, payload) ? prev : payload));
 			if (handler.current) {
 				handler.current(payload);
 			} else {
@@ -149,7 +197,7 @@ export const useWebsocket = <TInput, TOutput>(
 		handler.current = undefined;
 		pending.current = [];
 		queued.current = [];
-		setConnected(false);
+		setIsConnected(false);
 	}, []);
 
 	useEffect(() => {
@@ -173,7 +221,10 @@ export const useWebsocket = <TInput, TOutput>(
 		}
 	}, [options?.signal, cleanup]);
 
-	const reset = () => setError(null);
+	const reset = () => {
+		setError(null);
+		setIsError(false);
+	};
 
 	const send = (data: TInput) => {
 		if (wsRef.current?.readyState === WebSocket.OPEN) {
@@ -194,10 +245,11 @@ export const useWebsocket = <TInput, TOutput>(
 	};
 
 	return {
-		connected,
+		isConnected,
 		close,
 		data,
 		error,
+		isError,
 		send,
 		setHandler,
 		reset,
@@ -205,43 +257,57 @@ export const useWebsocket = <TInput, TOutput>(
 	};
 };
 
-interface UseAgentWebsocketResponse<TInput, TOutput>
-	extends Omit<WebsocketResponse<TInput, TOutput>, 'setHandler'> {
-	/**
-	 * Data received from the agent via WebSocket
-	 */
-	data?: TOutput;
-}
-
-export 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> => {
-	const [data, setData] = useState<TOutput>();
-	const { connected, close, send, setHandler, readyState, error, reset } = useWebsocket<
-		TInput,
-		TOutput
-	>(`/agent/${agent}`, options);
+/**
+ * Type-safe WebSocket hook for connecting to WebSocket routes.
+ *
+ * Provides automatic type inference for route inputs and outputs based on
+ * the WebSocketRouteRegistry generated from your routes.
+ *
+ * @template TRoute - WebSocket route key from WebSocketRouteRegistry (e.g., '/ws', '/chat')
+ *
+ * @example Simple WebSocket connection
+ * ```typescript
+ * const { isConnected, data, send } = useWebsocket('/ws');
+ *
+ * // Send typed data
+ * send({ message: 'Hello' }); // Fully typed based on route schema!
+ * ```
+ *
+ * @example WebSocket with query parameters
+ * ```typescript
+ * const { isConnected, data, send } = useWebsocket('/chat', {
+ *   query: new URLSearchParams({ room: 'general' })
+ * });
+ * ```
+ */
+export function useWebsocket<TRoute extends WebSocketRouteKey>(
+	route: TRoute,
+	options?: WebsocketOptions
+): Omit<
+	WebsocketResponseInternal<WebSocketRouteInput<TRoute>, WebSocketRouteOutput<TRoute>>,
+	'setHandler'
+> & {
+	data?: WebSocketRouteOutput<TRoute>;
+} {
+	const [data, setData] = useState<WebSocketRouteOutput<TRoute>>();
+	const { isConnected, close, send, setHandler, readyState, error, isError, reset } =
+		useWebsocketInternal<WebSocketRouteInput<TRoute>, WebSocketRouteOutput<TRoute>>(
+			route as string,
+			options
+		);
 
 	useEffect(() => {
 		setHandler(setData);
-	}, [agent, setHandler]);
+	}, [route, setHandler]);
 
 	return {
-		connected,
+		isConnected,
 		close,
 		data,
 		error,
+		isError,
 		reset,
 		send,
 		readyState,
 	};
-};
+}

package/dist/run.d.ts

@@ -1,34 +0,0 @@
-import type { InferInput, InferOutput } from '@agentuity/core';
-import type { AgentName, AgentRegistry } from './types';
-interface RunArgs {
-    /**
-     * Optional query parameters to append to the URL
-     */
-    query?: URLSearchParams;
-    /**
-     * Optional headers to send with the request
-     */
-    headers?: Record<string, string>;
-    /**
-     * Optional subpath to append to the agent path (such as /agent/:agent_name/:subpath)
-     */
-    subpath?: string;
-    /**
-     * HTTP method to use (default: POST)
-     */
-    method?: string;
-    /**
-     * Optional AbortSignal to cancel the request
-     */
-    signal?: AbortSignal;
-}
-interface UseAgentResponse<TInput, TOutput> {
-    data?: TOutput;
-    error: Error | null;
-    run: (input: TInput, options?: RunArgs) => Promise<TOutput>;
-    reset: () => void;
-    running: boolean;
-}
-export declare const useAgent: <TName extends AgentName, TInput = TName extends keyof AgentRegistry ? InferInput<AgentRegistry[TName]["inputSchema"]> : never, TOutput = TName extends keyof AgentRegistry ? InferOutput<AgentRegistry[TName]["outputSchema"]> : never>(name: TName) => UseAgentResponse<TInput, TOutput>;
-export {};
-//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.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,UAAU,OAAO;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,UAAU,gBAAgB,CAAC,MAAM,EAAE,OAAO;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,QAAQ,GACpB,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,MAAM,KAAK,KACT,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAuElC,CAAC"}