@agentuity/react 0.0.3 → 0.0.5

package/AGENTS.md

@@ -0,0 +1,97 @@
+# Agent Guidelines for @agentuity/react
+
+## Package Overview
+
+React hooks and components for building Agentuity web applications. Provides type-safe hooks for calling agents and WebSocket communication.
+
+## Commands
+
+- **Build**: `bun run build` (compiles for browser target)
+- **Typecheck**: `bun run typecheck` (runs TypeScript type checking)
+- **Clean**: `bun run clean` (removes dist/)
+
+## Architecture
+
+- **Runtime**: Browser only (uses browser APIs like fetch, WebSocket)
+- **Build target**: Browser with ESNext
+- **Dependencies**: Requires `@agentuity/core` (workspace dependency)
+- **Peer dependencies**: React 18+ or 19+
+
+## Structure
+
+```
+src/
+├── index.ts        # Main entry point
+├── context.tsx     # AgentuityProvider and AgentuityContext
+├── run.ts          # useAgent hook for HTTP calls
+├── websocket.ts    # useWebsocket hook for WebSocket
+├── types.ts        # Type definitions for agent registry
+├── url.ts          # URL building utilities
+└── env.ts          # Environment helpers
+```
+
+## Code Style
+
+- **React hooks** - Follow React hooks conventions
+- **TypeScript generics** - Heavy use of generics for type safety
+- **Functional components** - All components are functional
+- **Context API** - Use React Context for configuration
+- **Error boundaries** - Throw errors that can be caught by error boundaries
+
+## Important Conventions
+
+- **Provider required** - All hooks must be used within `AgentuityProvider`
+- **Type inference** - Agent types are inferred from generated types (AgentRegistry)
+- **Base URL** - Defaults to current origin if not provided
+- **WebSocket protocol** - Auto-converts http:// to ws:// and https:// to wss://
+- **Serialization** - Automatically handles JSON serialization/deserialization
+
+## Hooks API
+
+### useAgent
+
+```typescript
+const { data, run } = useAgent('agentName');
+```
+
+- Returns last response in `data`
+- `run()` function for calling the agent
+- Supports custom headers, query params, subpaths
+
+### useWebsocket
+
+```typescript
+const { connected, send, setHandler, close } = useWebsocket('/path');
+```
+
+- Auto-reconnection on connection loss
+- Message queuing when disconnected
+- Type-safe message handlers
+
+## Generated Types
+
+This package expects a `AgentRegistry` type to be augmented by generated code:
+
+```typescript
+// Generated by bundler
+export interface AgentRegistry {
+  'my-agent': {
+    inputSchema: z.ZodObject<...>;
+    outputSchema: z.ZodObject<...>;
+  };
+}
+```
+
+## Testing
+
+- Test with React Testing Library
+- Mock fetch and WebSocket APIs
+- Test error boundaries
+- Test with and without provider
+
+## Publishing Checklist
+
+1. Run `bun run build` to compile for browser
+2. Verify `dist/` contains browser-compatible code (no Node.js APIs)
+3. Ensure peer dependencies are correctly specified
+4. Must publish **after** @agentuity/core

package/README.md

@@ -0,0 +1,152 @@
+# @agentuity/react
+
+React hooks and components for building Agentuity web applications.
+
+## Installation
+
+```bash
+bun add @agentuity/react
+```
+
+## Overview
+
+`@agentuity/react` provides React hooks and context providers for seamlessly integrating with Agentuity agents from your frontend application.
+
+## Features
+
+- **Type-safe agent calls** - Fully typed React hooks for calling agents
+- **WebSocket support** - Real-time bidirectional communication with agents
+- **Context provider** - Simple setup with React Context
+- **Automatic data management** - Built-in state management for agent responses
+
+## Quick Start
+
+### 1. Setup Provider
+
+Wrap your app with the `AgentuityProvider`:
+
+```tsx
+import { AgentuityProvider } from '@agentuity/react';
+
+function App() {
+  return (
+    <AgentuityProvider baseUrl="http://localhost:3000">
+      <YourApp />
+    </AgentuityProvider>
+  );
+}
+```
+
+### 2. Use Agents
+
+Call agents with type-safety using the `useAgent` hook:
+
+```tsx
+import { useAgent } from '@agentuity/react';
+
+function MyComponent() {
+  const { data, run } = useAgent('myAgent');
+
+  const handleClick = async () => {
+    const result = await run({ message: 'Hello' });
+    console.log(result);
+  };
+
+  return (
+    <div>
+      <button onClick={handleClick}>Call Agent</button>
+      {data && <div>Response: {JSON.stringify(data)}</div>}
+    </div>
+  );
+}
+```
+
+### 3. WebSocket Communication
+
+For real-time communication:
+
+```tsx
+import { useWebsocket } from '@agentuity/react';
+
+function ChatComponent() {
+  const { connected, send, setHandler } = useWebsocket('/chat');
+
+  useEffect(() => {
+    setHandler((message) => {
+      console.log('Received:', message);
+    });
+  }, []);
+
+  const sendMessage = () => {
+    send({ text: 'Hello, agent!' });
+  };
+
+  return (
+    <div>
+      <div>Status: {connected ? 'Connected' : 'Disconnected'}</div>
+      <button onClick={sendMessage} disabled={!connected}>
+        Send Message
+      </button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### AgentuityProvider
+
+Context provider for Agentuity configuration.
+
+**Props:**
+- `baseUrl?: string` - Base URL for agent API calls (defaults to current origin)
+- `children: ReactNode` - Child components
+
+### useAgent
+
+Hook for calling agents via HTTP.
+
+```typescript
+const { data, run } = useAgent<TName>(name);
+```
+
+**Parameters:**
+- `name: string` - Agent name
+
+**Returns:**
+- `data?: TOutput` - Last response data
+- `run: (input: TInput, options?: RunArgs) => Promise<TOutput>` - Function to invoke the agent
+
+**RunArgs:**
+- `query?: URLSearchParams` - Query parameters
+- `headers?: Record<string, string>` - Custom headers
+- `subpath?: string` - Subpath to append to agent URL
+- `method?: string` - HTTP method (default: POST)
+- `signal?: AbortSignal` - Abort signal for cancellation
+
+### useWebsocket
+
+Hook for WebSocket connections to agents.
+
+```typescript
+const { connected, send, setHandler, readyState, close } = useWebsocket<TInput, TOutput>(path, options);
+```
+
+**Parameters:**
+- `path: string` - WebSocket path
+- `options?: WebsocketArgs` - Connection options
+
+**Returns:**
+- `connected: boolean` - Connection status
+- `send: (data: TInput) => void` - Send data to server
+- `setHandler: (handler: (data: TOutput) => void) => void` - Set message handler
+- `readyState: number` - WebSocket ready state
+- `close: () => void` - Close connection
+
+## TypeScript
+
+All hooks are fully typed and will infer input/output types from your agent definitions when using the generated types.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/react",
-	"version": "0.0.3",
+	"version": "0.0.5",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -11,6 +11,7 @@
 		}
 	},
 	"files": [
+		"AGENTS.md",
 		"README.md",
 		"dist"
 	],