@agentuity/react 0.0.30 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/react",
-	"version": "0.0.30",
+	"version": "0.0.32",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./dist/index.d.ts",
@@ -13,7 +13,8 @@
 	"files": [
 		"AGENTS.md",
 		"README.md",
-		"dist"
+		"dist",
+		"src"
 	],
 	"scripts": {
 		"clean": "rm -rf dist",
@@ -22,7 +23,7 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "0.0.29"
+		"@agentuity/core": "0.0.31"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.0"

package/src/context.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import { createContext, type Context, type ReactElement } from 'react';
+import { defaultBaseUrl } from './url';
+
+export interface ContextProviderArgs {
+	children?: React.ReactNode;
+	baseUrl?: string;
+}
+
+export const AgentuityContext: Context<ContextProviderArgs> = createContext<ContextProviderArgs>({
+	baseUrl: '',
+});
+
+export const AgentuityProvider = ({ baseUrl, children }: ContextProviderArgs): ReactElement => {
+	return (
+		<AgentuityContext.Provider value={{ baseUrl: baseUrl || defaultBaseUrl }}>
+			{children}
+		</AgentuityContext.Provider>
+	);
+};

package/src/env.ts

@@ -0,0 +1,6 @@
+export const getProcessEnv = (key: string): string | undefined => {
+	if (typeof process !== 'undefined' && process.env) {
+		return process.env[key];
+	}
+	return undefined;
+};

package/src/index.ts

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

package/src/run.ts

@@ -0,0 +1,96 @@
+import { useContext, useState } from 'react';
+import type { InferInput, InferOutput } from '@agentuity/core';
+import { buildUrl } from './url';
+import { AgentuityContext } from './context';
+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;
+	run: (input: TInput, options?: RunArgs) => Promise<TOutput>;
+	running: boolean;
+}
+
+export 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> => {
+	const context = useContext(AgentuityContext);
+	const [data, setData] = useState<TOutput>();
+	const [running, setRunning] = useState(false);
+
+	if (!context) {
+		throw new Error('useAgent must be used within a AgentuityProvider');
+	}
+
+	const run = async (input: TInput, options?: RunArgs): Promise<TOutput> => {
+		setRunning(true);
+		try {
+			const url = buildUrl(context.baseUrl!, `/agent/${name}`, options?.subpath, options?.query);
+			const signal = options?.signal ?? new AbortController().signal;
+			const response = await fetch(url, {
+				method: options?.method ?? 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					...(options?.headers ?? ''),
+				},
+				signal,
+				body:
+					input && typeof input === 'object' && options?.method !== 'GET'
+						? JSON.stringify(input)
+						: undefined,
+			});
+			if (!response.ok) {
+				throw new Error(`Error invoking agent ${name}: ${response.statusText}`);
+			}
+			// TODO: handle streams
+			const ct = response.headers.get('Content-Type') || '';
+			if (ct.includes('text/')) {
+				const text = await response.text();
+				const _data = text as TOutput;
+				setData(_data);
+				return _data;
+			}
+			if (ct.includes('/json')) {
+				const data = await response.json();
+				const _data = data as TOutput;
+				setData(_data);
+				return _data;
+			}
+			throw new Error(`Unsupported content type: ${ct}`);
+		} finally {
+			setRunning(false);
+		}
+	};
+
+	return { data, run, running };
+};

package/src/types.ts

@@ -0,0 +1,39 @@
+import type { StandardSchemaV1 } from '@agentuity/core';
+
+/**
+ * Agent definition interface
+ */
+export interface Agent<
+	TInput extends StandardSchemaV1 = StandardSchemaV1,
+	TOutput extends StandardSchemaV1 = StandardSchemaV1,
+> {
+	inputSchema: TInput;
+	outputSchema: TOutput;
+}
+
+/**
+ * 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>;
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AgentRegistry {}
+
+/**
+ * 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.
+ */
+export type AgentName = keyof AgentRegistry extends never ? string : keyof AgentRegistry;

package/src/url.ts

@@ -0,0 +1,25 @@
+import { getProcessEnv } from './env';
+
+export const buildUrl = (
+	base: string,
+	path: string,
+	subpath?: string,
+	query?: URLSearchParams
+): string => {
+	path = path.startsWith('/') ? path : `/${path}`;
+	let url = base.replace(/\/$/, '') + path;
+	if (subpath) {
+		subpath = subpath.startsWith('/') ? subpath : `/${subpath}`;
+		url += `/${subpath}`;
+	}
+	if (query) {
+		url += `?${query.toString()}`;
+	}
+	return url;
+};
+
+export const defaultBaseUrl: string =
+	getProcessEnv('NEXT_PUBLIC__AGENTUITY_URL') ||
+	getProcessEnv('VITE_AGENTUITY_URL') ||
+	getProcessEnv('AGENTUITY_URL') ||
+	'http://localhost:3000';

package/src/websocket.ts

@@ -0,0 +1,205 @@
+import { useContext, useEffect, 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';
+
+type onMessageHandler<T = unknown> = (data: T) => void;
+
+interface WebsocketArgs {
+	/**
+	 * 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)
+	 */
+	subpath?: string;
+	/**
+	 * Optional AbortSignal to cancel the websocket connection
+	 */
+	signal?: AbortSignal;
+}
+
+const serializeWSData = (
+	data: unknown
+): string | ArrayBufferLike | Blob | ArrayBufferView<ArrayBufferLike> => {
+	if (typeof data === 'string') {
+		return data;
+	}
+	if (typeof data === 'object') {
+		if (data instanceof ArrayBuffer || ArrayBuffer.isView(data) || data instanceof Blob) {
+			return data;
+		}
+		return JSON.stringify(data);
+	}
+	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;
+	send: (data: TInput) => void;
+	setHandler: (handler: onMessageHandler<TOutput>) => void;
+	readyState: WebSocket['readyState'];
+	close: () => void;
+}
+
+export const useWebsocket = <TInput, TOutput>(
+	path: string,
+	options?: WebsocketArgs
+): WebsocketResponse<TInput, TOutput> => {
+	const context = useContext(AgentuityContext);
+
+	if (!context) {
+		throw new Error('useWebsocket must be used within a AgentuityProvider');
+	}
+
+	const manualClose = useRef(false);
+	const wsRef = useRef<WebSocket | undefined>(undefined);
+	const pending = useRef<TOutput[]>([]);
+	const queued = useRef<TInput[]>([]);
+	const [data, setData] = useState<TOutput>();
+	const handler = useRef<onMessageHandler<TOutput> | undefined>(undefined);
+	const [connected, setConnected] = useState(false);
+
+	useEffect(() => {
+		if (options?.signal) {
+			const listener = () => {
+				wsRef.current?.close();
+				wsRef.current = undefined;
+				manualClose.current = true;
+			};
+			options.signal.addEventListener('abort', listener);
+			return () => {
+				options.signal?.removeEventListener('abort', listener);
+			};
+		}
+	}, []);
+
+	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);
+				if (queued.current.length > 0) {
+					queued.current.forEach((msg: unknown) => wsRef.current!.send(serializeWSData(msg)));
+					queued.current = [];
+				}
+			};
+			wsRef.current.onclose = () => {
+				wsRef.current = undefined;
+				queued.current = [];
+				setConnected(false);
+				if (manualClose.current) {
+					return;
+				}
+				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));
+		} else {
+			queued.current.push(data);
+		}
+	};
+
+	const setHandler = (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;
+		}
+	};
+
+	return {
+		connected,
+		close,
+		data,
+		send,
+		setHandler,
+		readyState: wsRef.current?.readyState ?? WebSocket.CLOSED,
+	};
+};
+
+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: AgentName,
+	options?: WebsocketArgs
+): UseAgentWebsocketResponse<TInput, TOutput> => {
+	const [data, setData] = useState<TOutput>();
+	const { connected, close, send, setHandler, readyState } = useWebsocket<TInput, TOutput>(
+		`/agent/${agent}`,
+		options
+	);
+
+	useEffect(() => {
+		setHandler(setData);
+	}, []);
+
+	return {
+		connected,
+		close,
+		data,
+		send,
+		readyState,
+	};
+};