+
+ );
+}
diff --git a/apps/testing/webrtc-test/.agents/agentuity/sdk/agent/AGENTS.md b/apps/testing/webrtc-test/.agents/agentuity/sdk/agent/AGENTS.md
new file mode 100644
index 000000000..3c5330d3c
--- /dev/null
+++ b/apps/testing/webrtc-test/.agents/agentuity/sdk/agent/AGENTS.md
@@ -0,0 +1,308 @@
+# Agents Folder Guide
+
+This folder contains AI agents for your Agentuity application. Each agent is organized in its own subdirectory.
+
+## Generated Types
+
+The `src/generated/` folder contains auto-generated TypeScript files:
+
+- `registry.ts` - Agent registry with strongly-typed agent definitions and schema types
+- `routes.ts` - Route registry for API, WebSocket, and SSE endpoints
+- `app.ts` - Application entry point (regenerated on every build)
+
+**Important:** Never edit files in `src/generated/` - they are overwritten on every build.
+
+Import generated types in your agents:
+
+```typescript
+import type { HelloInput, HelloOutput } from '../generated/registry';
+```
+
+## Directory Structure
+
+Each agent folder must contain:
+
+- **agent.ts** (required) - Agent definition with schema and handler
+
+Example structure:
+
+```
+src/agent/
+├── hello/
+│ └── agent.ts
+├── process-data/
+│ └── agent.ts
+└── (generated files in src/generated/)
+```
+
+**Note:** HTTP routes are defined separately in `src/api/` - see the API folder guide for details.
+
+## Creating an Agent
+
+### Basic Agent (agent.ts)
+
+```typescript
+import { createAgent } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+
+const agent = createAgent('my-agent', {
+ description: 'What this agent does',
+ schema: {
+ input: s.object({
+ name: s.string(),
+ age: s.number(),
+ }),
+ output: s.string(),
+ },
+ handler: async (ctx, input) => {
+ // Access context: ctx.app, ctx.config, ctx.logger, ctx.kv, ctx.vector, ctx.stream
+ return `Hello, ${input.name}! You are ${input.age} years old.`;
+ },
+});
+
+export default agent;
+```
+
+### Agent with Lifecycle (setup/shutdown)
+
+```typescript
+import { createAgent } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+
+const agent = createAgent('lifecycle-agent', {
+ description: 'Agent with setup and shutdown',
+ schema: {
+ input: s.object({ message: s.string() }),
+ output: s.object({ result: s.string() }),
+ },
+ setup: async (app) => {
+ // Initialize resources (runs once on startup)
+ // app contains: appName, version, startedAt, config
+ return {
+ agentId: `agent-${Math.random().toString(36).substr(2, 9)}`,
+ connectionPool: ['conn-1', 'conn-2'],
+ };
+ },
+ handler: async (ctx, input) => {
+ // Access setup config via ctx.config (fully typed)
+ ctx.logger.info('Agent ID:', ctx.config.agentId);
+ ctx.logger.info('Connections:', ctx.config.connectionPool);
+ return { result: `Processed: ${input.message}` };
+ },
+ shutdown: async (app, config) => {
+ // Cleanup resources (runs on shutdown)
+ console.log('Shutting down agent:', config.agentId);
+ },
+});
+
+export default agent;
+```
+
+### Agent with Event Listeners
+
+```typescript
+import { createAgent } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+
+const agent = createAgent('event-agent', {
+ schema: {
+ input: s.object({ data: s.string() }),
+ output: s.string(),
+ },
+ handler: async (ctx, input) => {
+ return `Processed: ${input.data}`;
+ },
+});
+
+agent.addEventListener('started', (eventName, agent, ctx) => {
+ ctx.logger.info('Agent started');
+});
+
+agent.addEventListener('completed', (eventName, agent, ctx) => {
+ ctx.logger.info('Agent completed');
+});
+
+agent.addEventListener('errored', (eventName, agent, ctx, error) => {
+ ctx.logger.error('Agent errored:', error);
+});
+
+export default agent;
+```
+
+## Agent Context (ctx)
+
+The handler receives a context object with:
+
+- **ctx.app** - Application state (appName, version, startedAt, config from createApp)
+- **ctx.config** - Agent-specific config (from setup return value, fully typed)
+- **ctx.logger** - Structured logger (info, warn, error, debug, trace)
+- **ctx.tracer** - OpenTelemetry tracer for custom spans
+- **ctx.sessionId** - Unique session identifier
+- **ctx.kv** - Key-value storage
+- **ctx.vector** - Vector storage for embeddings
+- **ctx.stream** - Stream storage for real-time data
+- **ctx.state** - In-memory request-scoped state (Map)
+- **ctx.thread** - Thread information for multi-turn conversations
+- **ctx.session** - Session information
+- **ctx.waitUntil** - Schedule background tasks
+
+## Examples
+
+### Using Key-Value Storage
+
+```typescript
+handler: async (ctx, input) => {
+ await ctx.kv.set('user:123', { name: 'Alice', age: 30 });
+ const user = await ctx.kv.get('user:123');
+ await ctx.kv.delete('user:123');
+ const keys = await ctx.kv.list('user:*');
+ return user;
+};
+```
+
+### Using Vector Storage
+
+```typescript
+handler: async (ctx, input) => {
+ await ctx.vector.upsert('docs', [
+ { id: '1', values: [0.1, 0.2, 0.3], metadata: { text: 'Hello' } },
+ ]);
+ const results = await ctx.vector.query('docs', [0.1, 0.2, 0.3], { topK: 5 });
+ return results;
+};
+```
+
+### Using Streams
+
+```typescript
+handler: async (ctx, input) => {
+ const stream = await ctx.stream.create('agent-logs');
+ await ctx.stream.write(stream.id, 'Processing step 1');
+ await ctx.stream.write(stream.id, 'Processing step 2');
+ return { streamId: stream.id };
+};
+```
+
+### Background Tasks with waitUntil
+
+```typescript
+handler: async (ctx, input) => {
+ // Schedule background work that continues after response
+ ctx.waitUntil(async () => {
+ await ctx.kv.set('processed', Date.now());
+ ctx.logger.info('Background task complete');
+ });
+
+ return { status: 'processing' };
+};
+```
+
+### Calling Another Agent
+
+```typescript
+// Import the agent directly
+import otherAgent from '../other-agent/agent';
+
+handler: async (ctx, input) => {
+ const result = await otherAgent.run({ data: input.value });
+ return `Other agent returned: ${result}`;
+};
+```
+
+## Subagents (Nested Agents)
+
+Agents can have subagents organized one level deep. This is useful for grouping related functionality.
+
+### Directory Structure for Subagents
+
+```
+src/agent/
+└── team/ # Parent agent
+ ├── agent.ts # Parent agent
+ ├── members/ # Subagent
+ │ └── agent.ts
+ └── tasks/ # Subagent
+ └── agent.ts
+```
+
+### Parent Agent
+
+```typescript
+import { createAgent } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+
+const agent = createAgent('team', {
+ description: 'Team Manager',
+ schema: {
+ input: s.object({ action: s.union([s.literal('info'), s.literal('count')]) }),
+ output: s.object({
+ message: s.string(),
+ timestamp: s.string(),
+ }),
+ },
+ handler: async (ctx, { action }) => {
+ return {
+ message: 'Team parent agent - manages members and tasks',
+ timestamp: new Date().toISOString(),
+ };
+ },
+});
+
+export default agent;
+```
+
+### Subagent (Accessing Parent)
+
+```typescript
+import { createAgent } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+import parentAgent from '../agent';
+
+const agent = createAgent('team.members', {
+ description: 'Members Subagent',
+ schema: {
+ input: s.object({
+ action: s.union([s.literal('list'), s.literal('add'), s.literal('remove')]),
+ name: s.optional(s.string()),
+ }),
+ output: s.object({
+ members: s.array(s.string()),
+ parentInfo: s.optional(s.string()),
+ }),
+ },
+ handler: async (ctx, { action, name }) => {
+ // Call parent agent directly
+ const parentResult = await parentAgent.run({ action: 'info' });
+ const parentInfo = `Parent says: ${parentResult.message}`;
+
+ let members = ['Alice', 'Bob'];
+ if (action === 'add' && name) {
+ members.push(name);
+ }
+
+ return { members, parentInfo };
+ },
+});
+
+export default agent;
+```
+
+### Key Points About Subagents
+
+- **One level deep**: Only one level of nesting is supported (no nested subagents)
+- **Access parent**: Import and call parent agents directly
+- **Agent names**: Subagents have dotted names like `"team.members"`
+- **Shared context**: Subagents share the same app context (kv, logger, etc.)
+
+## Rules
+
+- Each agent folder name becomes the agent's route name (e.g., `hello/` → `/agent/hello`)
+- **agent.ts** must export default the agent instance
+- The first argument to `createAgent()` is the agent name (must match folder structure)
+- Input/output schemas are enforced with @agentuity/schema validation
+- Setup return value type automatically flows to ctx.config (fully typed)
+- Use ctx.logger for logging, not console.log
+- Import agents directly to call them (recommended approach)
+- Subagents are one level deep only (team/members/, not team/members/subagent/)
+
+
diff --git a/apps/testing/webrtc-test/.agents/agentuity/sdk/api/AGENTS.md b/apps/testing/webrtc-test/.agents/agentuity/sdk/api/AGENTS.md
new file mode 100644
index 000000000..e6c32b3fb
--- /dev/null
+++ b/apps/testing/webrtc-test/.agents/agentuity/sdk/api/AGENTS.md
@@ -0,0 +1,367 @@
+# APIs Folder Guide
+
+This folder contains REST API routes for your Agentuity application. Each API is organized in its own subdirectory.
+
+## Generated Types
+
+The `src/generated/` folder contains auto-generated TypeScript files:
+
+- `routes.ts` - Route registry with strongly-typed route definitions and schema types
+- `registry.ts` - Agent registry (for calling agents from routes)
+- `app.ts` - Application entry point (regenerated on every build)
+
+**Important:** Never edit files in `src/generated/` - they are overwritten on every build.
+
+Import generated types in your routes:
+
+```typescript
+import type { POST_Api_UsersInput, POST_Api_UsersOutput } from '../generated/routes';
+```
+
+## Directory Structure
+
+Each API folder must contain:
+
+- **route.ts** (required) - HTTP route definitions using Hono router
+
+Example structure:
+
+```
+src/api/
+├── index.ts (optional, mounted at /api)
+├── status/
+│ └── route.ts (mounted at /api/status)
+├── users/
+│ └── route.ts (mounted at /api/users)
+├── agent-call/
+ └── route.ts (mounted at /api/agent-call)
+```
+
+## Creating an API
+
+### Basic API (route.ts)
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter();
+
+// GET /api/status
+router.get('/', (c) => {
+ return c.json({
+ status: 'ok',
+ timestamp: new Date().toISOString(),
+ version: '1.0.0',
+ });
+});
+
+// POST /api/status
+router.post('/', async (c) => {
+ const body = await c.req.json();
+ return c.json({ received: body });
+});
+
+export default router;
+```
+
+### API with Request Validation
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+import { validator } from 'hono/validator';
+
+const router = createRouter();
+
+const createUserSchema = s.object({
+ name: s.string(),
+ email: s.string(),
+ age: s.number(),
+});
+
+router.post(
+ '/',
+ validator('json', (value, c) => {
+ const result = createUserSchema['~standard'].validate(value);
+ if (result.issues) {
+ return c.json({ error: 'Validation failed', issues: result.issues }, 400);
+ }
+ return result.value;
+ }),
+ async (c) => {
+ const data = c.req.valid('json');
+ // data is fully typed: { name: string, email: string, age: number }
+ return c.json({
+ success: true,
+ user: data,
+ });
+ }
+);
+
+export default router;
+```
+
+### API Calling Agents
+
+APIs can call agents directly by importing them:
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+import helloAgent from '@agent/hello';
+
+const router = createRouter();
+
+router.get('/', async (c) => {
+ // Call an agent directly
+ const result = await helloAgent.run({ name: 'API Caller', age: 42 });
+
+ return c.json({
+ success: true,
+ agentResult: result,
+ });
+});
+
+router.post('/with-input', async (c) => {
+ const body = await c.req.json();
+ const { name, age } = body;
+
+ // Call agent with dynamic input
+ const result = await helloAgent.run({ name, age });
+
+ return c.json({
+ success: true,
+ agentResult: result,
+ });
+});
+
+export default router;
+```
+
+### API with Agent Validation
+
+Use `agent.validator()` for automatic input validation from agent schemas:
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+import myAgent from '@agent/my-agent';
+
+const router = createRouter();
+
+// POST with automatic validation using agent's input schema
+router.post('/', myAgent.validator(), async (c) => {
+ const data = c.req.valid('json'); // Fully typed from agent schema!
+ const result = await myAgent.run(data);
+ return c.json({ success: true, result });
+});
+
+export default router;
+```
+
+### API with Logging
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter();
+
+router.get('/log-test', (c) => {
+ c.var.logger.info('Info message');
+ c.var.logger.error('Error message');
+ c.var.logger.warn('Warning message');
+ c.var.logger.debug('Debug message');
+ c.var.logger.trace('Trace message');
+
+ return c.text('Check logs');
+});
+
+export default router;
+```
+
+## Route Context (c)
+
+The route handler receives a Hono context object with:
+
+- **c.req** - Request object (c.req.json(), c.req.param(), c.req.query(), etc.)
+- **c.json()** - Return JSON response
+- **c.text()** - Return text response
+- **c.html()** - Return HTML response
+- **c.redirect()** - Redirect to URL
+- **c.var.logger** - Structured logger (info, warn, error, debug, trace)
+- **c.var.kv** - Key-value storage
+- **c.var.vector** - Vector storage
+- **c.var.stream** - Stream management
+- **Import agents directly** - Import and call agents directly (recommended)
+
+## HTTP Methods
+
+```typescript
+const router = createRouter();
+
+router.get('/path', (c) => {
+ /* ... */
+});
+router.post('/path', (c) => {
+ /* ... */
+});
+router.put('/path', (c) => {
+ /* ... */
+});
+router.patch('/path', (c) => {
+ /* ... */
+});
+router.delete('/path', (c) => {
+ /* ... */
+});
+router.options('/path', (c) => {
+ /* ... */
+});
+```
+
+## Path Parameters
+
+```typescript
+// GET /api/users/:id
+router.get('/:id', (c) => {
+ const id = c.req.param('id');
+ return c.json({ userId: id });
+});
+
+// GET /api/posts/:postId/comments/:commentId
+router.get('/:postId/comments/:commentId', (c) => {
+ const postId = c.req.param('postId');
+ const commentId = c.req.param('commentId');
+ return c.json({ postId, commentId });
+});
+```
+
+## Query Parameters
+
+```typescript
+// GET /api/search?q=hello&limit=10
+router.get('/search', (c) => {
+ const query = c.req.query('q');
+ const limit = c.req.query('limit') || '20';
+ return c.json({ query, limit: parseInt(limit) });
+});
+```
+
+## Request Body
+
+```typescript
+// JSON body
+router.post('/', async (c) => {
+ const body = await c.req.json();
+ return c.json({ received: body });
+});
+
+// Form data
+router.post('/upload', async (c) => {
+ const formData = await c.req.formData();
+ const file = formData.get('file');
+ return c.json({ fileName: file?.name });
+});
+```
+
+## Error Handling
+
+```typescript
+import myAgent from '@agent/my-agent';
+
+router.get('/', async (c) => {
+ try {
+ const result = await myAgent.run({ data: 'test' });
+ return c.json({ success: true, result });
+ } catch (error) {
+ c.var.logger.error('Agent call failed:', error);
+ return c.json(
+ {
+ success: false,
+ error: error instanceof Error ? error.message : String(error),
+ },
+ 500
+ );
+ }
+});
+```
+
+## Response Types
+
+```typescript
+// JSON response
+return c.json({ data: 'value' });
+
+// Text response
+return c.text('Hello World');
+
+// HTML response
+return c.html('WebRTC Data Channel Test
+ +
+
+
+
+ {state !== 'idle' && (
+
+
+
+
+ )}
+
+
+
+
+
+
+
+
+
+
+
+
+ {state === 'idle' ? (
+
+ ) : (
+
+ )}
+
+
+
+
+
+ {/* Cursor Tracking Canvas */}
+ {state !== 'idle' && (
+
+ State: {state}
+
+
+ My Peer ID: {peerId || 'N/A'}
+
+
+ Remote Peers:{' '}
+ {remotePeerIds.length > 0 ? remotePeerIds.join(', ') : 'Waiting...'}
+
+
+ Data Channel: {dataChannelOpen ? 'Open' : 'Closed'}
+
+
+ Screen Share: {isScreenSharing ? 'On' : 'Off'}
+
+
+ Reconnect: {reconnectStatus}
+
+ {reconnectAttempt !== null && (
+
+ Reconnect Attempt: {reconnectAttempt}
+
+ )}
+ {error && (
+
+ Error: {error}
+
+ )}
+
+
+ )}
+
+ {/* Video Section */}
+ {(enableVideo || enableAudio) && state !== 'idle' && (
+ Cursor Tracking
++ Move your mouse over the canvas to share your cursor position with peers. + {remoteCursors.size > 0 && ` (${remoteCursors.size} remote cursor${remoteCursors.size > 1 ? 's' : ''})`} +
+ +
+
+ )}
+
+ {dataChannelOpen && (
+ Media
+
+ {/* Local Video */}
+
+
+
+
+ {/* Remote Videos */}
+ {remotePeerIds.map((remotePeerId) => (
+ You
+
+
+ {enableAudio && (
+
+ )}
+ {enableVideo && (
+
+ )}
+
+
+
+
+
+
+
+
+
+
+
+
+ Recording: {recordingState}
+
+
+ Recording Size:{' '}
+ {recordingSize !== null ? `${recordingSize} bytes` : 'N/A'}
+
+
+ Recording MIME:{' '}
+ {recordingMimeType ?? 'N/A'}
+
+
+
+ ))}
+
+ {remotePeerId.slice(0, 15)}...
+
+
+
+
+ )}
+
+
+ setInputMessage(e.target.value)}
+ onKeyDown={(e) => e.key === 'Enter' && sendMessage()}
+ placeholder="Type a message..."
+ data-testid="message-input"
+ style={{ flex: 1, padding: '0.5rem' }}
+ />
+
+
+
+
+
+ Messages
+ {messages.length === 0 ? ( +No messages yet
+ ) : ( + messages.map((msg) => ( +
+ {msg.from === 'local' ? 'You' : `Remote (${msg.peerId})`}:{' '}
+ {msg.data}
+
+ ))
+ )}
+ Hello
'); + +// Custom status code +return c.json({ error: 'Not found' }, 404); + +// Redirect +return c.redirect('/new-path'); + +// Headers +return c.json({ data: 'value' }, 200, { + 'X-Custom-Header': 'value', +}); +``` + +## Streaming Routes + +```typescript +import { createRouter, stream, sse, websocket } from '@agentuity/runtime'; + +const router = createRouter(); + +// Stream response (use with POST) +router.post( + '/events', + stream((c) => { + return new ReadableStream({ + start(controller) { + controller.enqueue('event 1\n'); + controller.enqueue('event 2\n'); + controller.close(); + }, + }); + }) +); + +// Server-Sent Events (use with GET) +router.get( + '/notifications', + sse((c, stream) => { + stream.writeSSE({ data: 'Hello', event: 'message' }); + stream.writeSSE({ data: 'World', event: 'message' }); + }) +); + +// WebSocket (use with GET) +router.get( + '/ws', + websocket((c, ws) => { + ws.onOpen(() => { + ws.send('Connected!'); + }); + ws.onMessage((event) => { + ws.send(`Echo: ${event.data}`); + }); + }) +); + +export default router; +``` + +## Rules + +- Each API folder name becomes the route name (e.g., `status/` → `/api/status`) +- **route.ts** must export default the router instance +- Use c.var.logger for logging, not console.log +- Import agents directly to call them (e.g., `import agent from '@agent/name'`) +- Validation should use @agentuity/schema or agent.validator() for type safety +- Return appropriate HTTP status codes +- APIs run at `/api/{folderName}` by default + + diff --git a/apps/testing/webrtc-test/.agents/agentuity/sdk/web/AGENTS.md b/apps/testing/webrtc-test/.agents/agentuity/sdk/web/AGENTS.md new file mode 100644 index 000000000..2a6eb0da5 --- /dev/null +++ b/apps/testing/webrtc-test/.agents/agentuity/sdk/web/AGENTS.md @@ -0,0 +1,511 @@ +# Web Folder Guide + +This folder contains your React-based web application that communicates with your Agentuity agents. + +## Generated Types + +The `src/generated/` folder contains auto-generated TypeScript files: + +- `routes.ts` - Route registry with type-safe API, WebSocket, and SSE route definitions +- `registry.ts` - Agent registry with input/output types + +**Important:** Never edit files in `src/generated/` - they are overwritten on every build. + +Import generated types in your components: + +```typescript +// Routes are typed automatically via module augmentation +import { useAPI } from '@agentuity/react'; + +// The route 'GET /api/users' is fully typed +const { data } = useAPI('GET /api/users'); +``` + +## Directory Structure + +Required files: + +- **App.tsx** (required) - Main React application component +- **frontend.tsx** (required) - Frontend entry point with client-side rendering +- **index.html** (required) - HTML template +- **public/** (optional) - Static assets (images, CSS, JS files) + +Example structure: + +``` +src/web/ +├── App.tsx +├── frontend.tsx +├── index.html +└── public/ + ├── styles.css + ├── logo.svg + └── script.js +``` + +## Creating the Web App + +### App.tsx - Main Component + +```typescript +import { AgentuityProvider, useAPI } from '@agentuity/react'; +import { useState } from 'react'; + +function HelloForm() { + const [name, setName] = useState('World'); + const { invoke, isLoading, data: greeting } = useAPI('POST /api/hello'); + + return ( +
+ setName(e.target.value)}
+ disabled={isLoading}
+ />
+
+
+
+
+ );
+}
+
+export function App() {
+ return (
+ {greeting ?? 'Waiting for response'}
+
+
+ Welcome to Agentuity
+
+
+ {result &&
+ );
+}
+```
+
+**useAPI Return Values:**
+
+| Property | Type | Description |
+| ------------ | ------------------------ | ----------------------------------------- |
+| `data` | `T \| undefined` | Response data (typed from route schema) |
+| `error` | `Error \| null` | Error if request failed |
+| `isLoading` | `boolean` | True during initial load |
+| `isFetching` | `boolean` | True during any fetch (including refetch) |
+| `isSuccess` | `boolean` | True if last request succeeded |
+| `isError` | `boolean` | True if last request failed |
+| `invoke` | `(input?) => PromiseCreated: {result.name}
} +
+
+ );
+}
+```
+
+**useWebsocket Return Values:**
+
+| Property | Type | Description |
+| --------------- | ---------------- | ---------------------------------------- |
+| `isConnected` | `boolean` | True when WebSocket is connected |
+| `data` | `T \| undefined` | Most recent message received |
+| `messages` | `T[]` | Array of all received messages |
+| `send` | `(data) => void` | Send a message (typed from route schema) |
+| `clearMessages` | `() => void` | Clear the messages array |
+| `close` | `() => void` | Close the connection |
+| `error` | `Error \| null` | Error if connection failed |
+| `isError` | `boolean` | True if there's an error |
+| `reset` | `() => void` | Reset state and reconnect |
+| `readyState` | `number` | WebSocket ready state |
+
+### useEventStream - Server-Sent Events
+
+For server-to-client streaming (one-way). Use when server pushes updates to client.
+
+```typescript
+import { useEventStream } from '@agentuity/react';
+
+function NotificationsComponent() {
+ const { isConnected, data, error, close, reset } = useEventStream('/api/notifications');
+
+ return (
+ Status: {isConnected ? 'Connected' : 'Disconnected'}
+ +
+ {messages.map((msg, i) => (
+
+
+ {JSON.stringify(msg)}
+ ))} +
+
+ );
+}
+```
+
+**useEventStream Return Values:**
+
+| Property | Type | Description |
+| ------------- | ---------------- | ---------------------------------- |
+| `isConnected` | `boolean` | True when EventSource is connected |
+| `data` | `T \| undefined` | Most recent event data |
+| `error` | `Error \| null` | Error if connection failed |
+| `isError` | `boolean` | True if there's an error |
+| `close` | `() => void` | Close the connection |
+| `reset` | `() => void` | Reset state and reconnect |
+| `readyState` | `number` | EventSource ready state |
+
+### useAgentuity - Access Context
+
+Access the Agentuity context for base URL and configuration.
+
+```typescript
+import { useAgentuity } from '@agentuity/react';
+
+function MyComponent() {
+ const { baseUrl } = useAgentuity();
+
+ return Connected: {isConnected ? 'Yes' : 'No'}
+ {error &&Error: {error.message}
} +Latest: {JSON.stringify(data)}
+ +API Base: {baseUrl}
; +} +``` + +### useAuth - Authentication State + +Access and manage authentication state. + +```typescript +import { useAuth } from '@agentuity/react'; + +function AuthStatus() { + const { isAuthenticated, authHeader, setAuthHeader, authLoading } = useAuth(); + + const handleLogin = async (token: string) => { + setAuthHeader?.(`Bearer ${token}`); + }; + + const handleLogout = () => { + setAuthHeader?.(null); + }; + + if (authLoading) returnLoading...
; + + return ( +
+ {isAuthenticated ? (
+
+ ) : (
+
+ )}
+
+ );
+}
+```
+
+**useAuth Return Values:**
+
+| Property | Type | Description |
+| ----------------- | ------------------- | ------------------------------------------- |
+| `isAuthenticated` | `boolean` | True if user has auth token and not loading |
+| `authHeader` | `string \| null` | Current auth header (e.g., "Bearer ...") |
+| `setAuthHeader` | `(token) => void` | Set auth header (null to clear) |
+| `authLoading` | `boolean` | True during auth state changes |
+| `setAuthLoading` | `(loading) => void` | Set auth loading state |
+
+## Complete Example
+
+```typescript
+import { AgentuityProvider, useAPI, useWebsocket } from '@agentuity/react';
+import { useEffect, useState } from 'react';
+
+function Dashboard() {
+ const [count, setCount] = useState(0);
+ const { invoke, data: agentResult } = useAPI('POST /api/process');
+ const { isConnected, send, data: wsMessage } = useWebsocket('/api/live');
+
+ useEffect(() => {
+ if (isConnected) {
+ const interval = setInterval(() => {
+ send({ ping: Date.now() });
+ }, 1000);
+ return () => clearInterval(interval);
+ }
+ }, [isConnected, send]);
+
+ return (
+
+
+ );
+}
+
+export function App() {
+ return (
+ My Agentuity App
+ +
+
+
+ Count: {count}
+ +
+
+
+
+ {JSON.stringify(agentResult)}
+
+ WebSocket:
+ {isConnected ? JSON.stringify(wsMessage) : 'Not connected'}
+
+ 
+```
+
+## Styling
+
+### Inline Styles
+
+```typescript
+
+ Styled content
+
+```
+
+### CSS Files
+
+Create `public/styles.css`:
+
+```css
+body {
+ background-color: #09090b;
+ color: #fff;
+ font-family: sans-serif;
+}
+```
+
+Import in `index.html`:
+
+```html
+
+```
+
+### Style Tag in Component
+
+```typescript
+
+
+
+
+```
+
+## RPC-Style API Client
+
+For non-React contexts (like utility functions or event handlers), use `createClient`:
+
+```typescript
+import { createClient } from '@agentuity/react';
+
+// Create a typed client (uses global baseUrl and auth from AgentuityProvider)
+const api = createClient();
+
+// Type-safe RPC-style calls - routes become nested objects
+// Route 'GET /api/users' becomes api.users.get()
+// Route 'POST /api/users' becomes api.users.post()
+// Route 'GET /api/users/:id' becomes api.users.id.get({ id: '123' })
+
+async function fetchData() {
+ const users = await api.users.get();
+ const newUser = await api.users.post({ name: 'Alice', email: 'alice@example.com' });
+ const user = await api.users.id.get({ id: '123' });
+ return { users, newUser, user };
+}
+```
+
+**When to use `createClient` vs `useAPI`:**
+
+| Use Case | Recommendation |
+| ------------------------- | -------------- |
+| React component rendering | `useAPI` hook |
+| Event handlers | Either works |
+| Utility functions | `createClient` |
+| Non-React code | `createClient` |
+| Need loading/error state | `useAPI` hook |
+| Need caching/refetch | `useAPI` hook |
+
+## Best Practices
+
+- Wrap your app with **AgentuityProvider** for hooks to work
+- **Always use `useAPI` instead of `fetch()`** for type safety and error handling
+- Use **useAPI** for type-safe HTTP requests (GET, POST, PUT, DELETE)
+- Use **useWebsocket** for bidirectional real-time communication
+- Use **useEventStream** for server-to-client streaming
+- Use **useAuth** for authentication state management
+- Handle loading and error states in UI
+- Place reusable components in separate files
+- Keep static assets in the **public/** folder
+
+## Rules
+
+- **App.tsx** must export a function named `App`
+- **frontend.tsx** must render the `App` component to `#root`
+- **index.html** must have a ``
+- Routes are typed via module augmentation from `src/generated/routes.ts`
+- The web app is served at `/` by default
+- Static files in `public/` are served at `/public/*`
+- Module script tag: ``
+- **Never use raw `fetch()` calls** - always use `useAPI` or `createClient`
+
+
diff --git a/apps/testing/webrtc-test/.gitignore b/apps/testing/webrtc-test/.gitignore
new file mode 100644
index 000000000..0b627cce3
--- /dev/null
+++ b/apps/testing/webrtc-test/.gitignore
@@ -0,0 +1,43 @@
+# dependencies (bun install)
+
+node_modules
+
+# output
+
+out
+dist
+*.tgz
+
+# code coverage
+
+coverage
+*.lcov
+
+# logs
+
+/logs
+*.log
+report.*.json
+
+# dotenv environment variable files
+
+.env
+.env.*
+
+# caches
+
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+
+.idea
+
+# Finder (MacOS) folder config
+
+.DS_Store
+
+# Agentuity build files
+
+.agentuity
diff --git a/apps/testing/webrtc-test/.vscode/settings.json b/apps/testing/webrtc-test/.vscode/settings.json
new file mode 100644
index 000000000..13d25f367
--- /dev/null
+++ b/apps/testing/webrtc-test/.vscode/settings.json
@@ -0,0 +1,14 @@
+{
+ "search.exclude": {
+ "**/.git/**": true,
+ "**/node_modules/**": true,
+ "**/bun.lock": true,
+ "**/.agentuity/**": true
+ },
+ "json.schemas": [
+ {
+ "fileMatch": ["agentuity.json"],
+ "url": "https://agentuity.dev/schema/cli/v1/agentuity.json"
+ }
+ ]
+}
diff --git a/apps/testing/webrtc-test/AGENTS.md b/apps/testing/webrtc-test/AGENTS.md
new file mode 100644
index 000000000..20cd550e1
--- /dev/null
+++ b/apps/testing/webrtc-test/AGENTS.md
@@ -0,0 +1,64 @@
+# Agent Guidelines for webrtc-test
+
+## Commands
+
+- **Build**: `bun run build` (compiles your application)
+- **Dev**: `bun run dev` (starts development server)
+- **Typecheck**: `bun run typecheck` (runs TypeScript type checking)
+- **Deploy**: `bun run deploy` (deploys your app to the Agentuity cloud)
+
+## Agent-Friendly CLI
+
+The Agentuity CLI is designed to be agent-friendly with programmatic interfaces, structured output, and comprehensive introspection.
+
+Read the [AGENTS.md](./node_modules/@agentuity/cli/AGENTS.md) file in the Agentuity CLI for more information on how to work with this project.
+
+## Instructions
+
+- This project uses Bun instead of NodeJS and TypeScript for all source code
+- This is an Agentuity Agent project
+
+## Web Frontend (src/web/)
+
+The `src/web/` folder contains your React frontend, which is automatically bundled by the Agentuity build system.
+
+**File Structure:**
+
+- `index.html` - Main HTML file with ``;
+ // Session script sets cookies and window.__AGENTUITY_SESSION__ (dynamic, not cached)
+ const sessionScript = '';
+
+ // In production, the beacon is already in HTML as a CDN asset (data-agentuity-beacon marker)
+ // Inject config/session BEFORE the beacon marker so config exists when beacon runs
+ const beaconMarker = '
+