@agentuity/cli 0.0.100 → 0.0.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (264) hide show
  1. package/AGENTS.md +19 -188
  2. package/bin/cli.ts +13 -6
  3. package/dist/api.d.ts +1 -0
  4. package/dist/api.d.ts.map +1 -1
  5. package/dist/api.js +1 -1
  6. package/dist/api.js.map +1 -1
  7. package/dist/cli.d.ts.map +1 -1
  8. package/dist/cli.js +41 -12
  9. package/dist/cli.js.map +1 -1
  10. package/dist/cmd/ai/index.d.ts.map +1 -1
  11. package/dist/cmd/ai/index.js +6 -1
  12. package/dist/cmd/ai/index.js.map +1 -1
  13. package/dist/cmd/ai/prompt/agent.d.ts +7 -0
  14. package/dist/cmd/ai/prompt/agent.d.ts.map +1 -1
  15. package/dist/cmd/ai/prompt/agent.js +12 -323
  16. package/dist/cmd/ai/prompt/agent.js.map +1 -1
  17. package/dist/cmd/ai/prompt/api.d.ts +7 -0
  18. package/dist/cmd/ai/prompt/api.d.ts.map +1 -1
  19. package/dist/cmd/ai/prompt/api.js +12 -260
  20. package/dist/cmd/ai/prompt/api.js.map +1 -1
  21. package/dist/cmd/ai/prompt/version.d.ts +35 -0
  22. package/dist/cmd/ai/prompt/version.d.ts.map +1 -0
  23. package/dist/cmd/ai/prompt/version.js +55 -0
  24. package/dist/cmd/ai/prompt/version.js.map +1 -0
  25. package/dist/cmd/ai/prompt/web.d.ts +7 -0
  26. package/dist/cmd/ai/prompt/web.d.ts.map +1 -1
  27. package/dist/cmd/ai/prompt/web.js +12 -283
  28. package/dist/cmd/ai/prompt/web.js.map +1 -1
  29. package/dist/cmd/ai/skills/generate.d.ts +3 -0
  30. package/dist/cmd/ai/skills/generate.d.ts.map +1 -0
  31. package/dist/cmd/ai/skills/generate.js +65 -0
  32. package/dist/cmd/ai/skills/generate.js.map +1 -0
  33. package/dist/cmd/ai/skills/generator.d.ts +4 -0
  34. package/dist/cmd/ai/skills/generator.d.ts.map +1 -0
  35. package/dist/cmd/ai/skills/generator.js +402 -0
  36. package/dist/cmd/ai/skills/generator.js.map +1 -0
  37. package/dist/cmd/ai/skills/index.d.ts +4 -0
  38. package/dist/cmd/ai/skills/index.d.ts.map +1 -0
  39. package/dist/cmd/ai/skills/index.js +21 -0
  40. package/dist/cmd/ai/skills/index.js.map +1 -0
  41. package/dist/cmd/auth/signup.d.ts.map +1 -1
  42. package/dist/cmd/auth/signup.js +1 -0
  43. package/dist/cmd/auth/signup.js.map +1 -1
  44. package/dist/cmd/build/ast.d.ts +2 -1
  45. package/dist/cmd/build/ast.d.ts.map +1 -1
  46. package/dist/cmd/build/ast.js +135 -47
  47. package/dist/cmd/build/ast.js.map +1 -1
  48. package/dist/cmd/build/entry-generator.d.ts.map +1 -1
  49. package/dist/cmd/build/entry-generator.js +255 -188
  50. package/dist/cmd/build/entry-generator.js.map +1 -1
  51. package/dist/cmd/build/vite/agent-discovery.d.ts.map +1 -1
  52. package/dist/cmd/build/vite/agent-discovery.js +103 -45
  53. package/dist/cmd/build/vite/agent-discovery.js.map +1 -1
  54. package/dist/cmd/build/vite/bun-dev-server.d.ts +7 -1
  55. package/dist/cmd/build/vite/bun-dev-server.d.ts.map +1 -1
  56. package/dist/cmd/build/vite/bun-dev-server.js +52 -26
  57. package/dist/cmd/build/vite/bun-dev-server.js.map +1 -1
  58. package/dist/cmd/build/vite/docs-generator.d.ts +13 -0
  59. package/dist/cmd/build/vite/docs-generator.d.ts.map +1 -0
  60. package/dist/cmd/build/vite/docs-generator.js +81 -0
  61. package/dist/cmd/build/vite/docs-generator.js.map +1 -0
  62. package/dist/cmd/build/vite/index.d.ts +3 -3
  63. package/dist/cmd/build/vite/index.d.ts.map +1 -1
  64. package/dist/cmd/build/vite/index.js +9 -7
  65. package/dist/cmd/build/vite/index.js.map +1 -1
  66. package/dist/cmd/build/vite/lifecycle-generator.d.ts +1 -1
  67. package/dist/cmd/build/vite/lifecycle-generator.d.ts.map +1 -1
  68. package/dist/cmd/build/vite/lifecycle-generator.js +19 -5
  69. package/dist/cmd/build/vite/lifecycle-generator.js.map +1 -1
  70. package/dist/cmd/build/vite/metadata-generator.d.ts.map +1 -1
  71. package/dist/cmd/build/vite/metadata-generator.js +203 -7
  72. package/dist/cmd/build/vite/metadata-generator.js.map +1 -1
  73. package/dist/cmd/build/vite/prompt-generator.d.ts +23 -0
  74. package/dist/cmd/build/vite/prompt-generator.d.ts.map +1 -0
  75. package/dist/cmd/build/vite/prompt-generator.js +123 -0
  76. package/dist/cmd/build/vite/prompt-generator.js.map +1 -0
  77. package/dist/cmd/build/vite/registry-generator.d.ts +3 -3
  78. package/dist/cmd/build/vite/registry-generator.d.ts.map +1 -1
  79. package/dist/cmd/build/vite/registry-generator.js +644 -103
  80. package/dist/cmd/build/vite/registry-generator.js.map +1 -1
  81. package/dist/cmd/build/vite/route-discovery.d.ts +4 -0
  82. package/dist/cmd/build/vite/route-discovery.d.ts.map +1 -1
  83. package/dist/cmd/build/vite/route-discovery.js.map +1 -1
  84. package/dist/cmd/build/vite/server-bundler.d.ts +4 -0
  85. package/dist/cmd/build/vite/server-bundler.d.ts.map +1 -1
  86. package/dist/cmd/build/vite/server-bundler.js +63 -17
  87. package/dist/cmd/build/vite/server-bundler.js.map +1 -1
  88. package/dist/cmd/build/vite/vite-asset-server-config.d.ts.map +1 -1
  89. package/dist/cmd/build/vite/vite-asset-server-config.js +4 -0
  90. package/dist/cmd/build/vite/vite-asset-server-config.js.map +1 -1
  91. package/dist/cmd/build/vite/vite-builder.d.ts +1 -1
  92. package/dist/cmd/build/vite/vite-builder.d.ts.map +1 -1
  93. package/dist/cmd/build/vite/vite-builder.js +118 -96
  94. package/dist/cmd/build/vite/vite-builder.js.map +1 -1
  95. package/dist/cmd/build/vite-bundler.js +6 -6
  96. package/dist/cmd/build/vite-bundler.js.map +1 -1
  97. package/dist/cmd/cloud/deploy.d.ts.map +1 -1
  98. package/dist/cmd/cloud/deploy.js +89 -32
  99. package/dist/cmd/cloud/deploy.js.map +1 -1
  100. package/dist/cmd/cloud/keyvalue/create-namespace.d.ts.map +1 -1
  101. package/dist/cmd/cloud/keyvalue/create-namespace.js +3 -1
  102. package/dist/cmd/cloud/keyvalue/create-namespace.js.map +1 -1
  103. package/dist/cmd/cloud/keyvalue/delete-namespace.d.ts.map +1 -1
  104. package/dist/cmd/cloud/keyvalue/delete-namespace.js +3 -1
  105. package/dist/cmd/cloud/keyvalue/delete-namespace.js.map +1 -1
  106. package/dist/cmd/cloud/keyvalue/delete.d.ts.map +1 -1
  107. package/dist/cmd/cloud/keyvalue/delete.js +3 -1
  108. package/dist/cmd/cloud/keyvalue/delete.js.map +1 -1
  109. package/dist/cmd/cloud/keyvalue/set.d.ts.map +1 -1
  110. package/dist/cmd/cloud/keyvalue/set.js +4 -2
  111. package/dist/cmd/cloud/keyvalue/set.js.map +1 -1
  112. package/dist/cmd/cloud/stream/get.d.ts.map +1 -1
  113. package/dist/cmd/cloud/stream/get.js +2 -13
  114. package/dist/cmd/cloud/stream/get.js.map +1 -1
  115. package/dist/cmd/cloud/vector/delete-namespace.d.ts +3 -0
  116. package/dist/cmd/cloud/vector/delete-namespace.d.ts.map +1 -0
  117. package/dist/cmd/cloud/vector/delete-namespace.js +77 -0
  118. package/dist/cmd/cloud/vector/delete-namespace.js.map +1 -0
  119. package/dist/cmd/cloud/vector/index.d.ts.map +1 -1
  120. package/dist/cmd/cloud/vector/index.js +21 -4
  121. package/dist/cmd/cloud/vector/index.js.map +1 -1
  122. package/dist/cmd/cloud/vector/list-namespaces.d.ts +3 -0
  123. package/dist/cmd/cloud/vector/list-namespaces.d.ts.map +1 -0
  124. package/dist/cmd/cloud/vector/list-namespaces.js +42 -0
  125. package/dist/cmd/cloud/vector/list-namespaces.js.map +1 -0
  126. package/dist/cmd/cloud/vector/stats.d.ts +3 -0
  127. package/dist/cmd/cloud/vector/stats.d.ts.map +1 -0
  128. package/dist/cmd/cloud/vector/stats.js +142 -0
  129. package/dist/cmd/cloud/vector/stats.js.map +1 -0
  130. package/dist/cmd/cloud/vector/upsert.d.ts +3 -0
  131. package/dist/cmd/cloud/vector/upsert.d.ts.map +1 -0
  132. package/dist/cmd/cloud/vector/upsert.js +192 -0
  133. package/dist/cmd/cloud/vector/upsert.js.map +1 -0
  134. package/dist/cmd/dev/file-watcher.d.ts.map +1 -1
  135. package/dist/cmd/dev/file-watcher.js +94 -33
  136. package/dist/cmd/dev/file-watcher.js.map +1 -1
  137. package/dist/cmd/dev/index.d.ts.map +1 -1
  138. package/dist/cmd/dev/index.js +298 -61
  139. package/dist/cmd/dev/index.js.map +1 -1
  140. package/dist/cmd/dev/skills.d.ts +10 -0
  141. package/dist/cmd/dev/skills.d.ts.map +1 -0
  142. package/dist/cmd/dev/skills.js +57 -0
  143. package/dist/cmd/dev/skills.js.map +1 -0
  144. package/dist/cmd/dev/sync.d.ts.map +1 -1
  145. package/dist/cmd/dev/sync.js +19 -3
  146. package/dist/cmd/dev/sync.js.map +1 -1
  147. package/dist/cmd/index.d.ts.map +1 -1
  148. package/dist/cmd/index.js +1 -0
  149. package/dist/cmd/index.js.map +1 -1
  150. package/dist/cmd/project/create.d.ts.map +1 -1
  151. package/dist/cmd/project/create.js +3 -0
  152. package/dist/cmd/project/create.js.map +1 -1
  153. package/dist/cmd/project/template-flow.d.ts +1 -0
  154. package/dist/cmd/project/template-flow.d.ts.map +1 -1
  155. package/dist/cmd/project/template-flow.js +30 -5
  156. package/dist/cmd/project/template-flow.js.map +1 -1
  157. package/dist/cmd/setup/index.d.ts.map +1 -1
  158. package/dist/cmd/setup/index.js +1 -0
  159. package/dist/cmd/setup/index.js.map +1 -1
  160. package/dist/cmd/upgrade/index.d.ts +15 -0
  161. package/dist/cmd/upgrade/index.d.ts.map +1 -1
  162. package/dist/cmd/upgrade/index.js +59 -4
  163. package/dist/cmd/upgrade/index.js.map +1 -1
  164. package/dist/config.d.ts.map +1 -1
  165. package/dist/config.js +8 -0
  166. package/dist/config.js.map +1 -1
  167. package/dist/domain.d.ts +45 -0
  168. package/dist/domain.d.ts.map +1 -0
  169. package/dist/domain.js +200 -0
  170. package/dist/domain.js.map +1 -0
  171. package/dist/index.d.ts +0 -1
  172. package/dist/index.d.ts.map +1 -1
  173. package/dist/index.js +0 -1
  174. package/dist/index.js.map +1 -1
  175. package/dist/schema-generator.d.ts +2 -0
  176. package/dist/schema-generator.d.ts.map +1 -1
  177. package/dist/schema-generator.js +18 -0
  178. package/dist/schema-generator.js.map +1 -1
  179. package/dist/steps.d.ts +1 -1
  180. package/dist/steps.d.ts.map +1 -1
  181. package/dist/steps.js +16 -5
  182. package/dist/steps.js.map +1 -1
  183. package/dist/tui/prompt.d.ts +1 -2
  184. package/dist/tui/prompt.d.ts.map +1 -1
  185. package/dist/tui/prompt.js +8 -4
  186. package/dist/tui/prompt.js.map +1 -1
  187. package/dist/tui.d.ts +16 -0
  188. package/dist/tui.d.ts.map +1 -1
  189. package/dist/tui.js +23 -2
  190. package/dist/tui.js.map +1 -1
  191. package/dist/types.d.ts +9 -2
  192. package/dist/types.d.ts.map +1 -1
  193. package/dist/types.js +3 -3
  194. package/dist/types.js.map +1 -1
  195. package/package.json +5 -8
  196. package/src/api.ts +1 -1
  197. package/src/cli.ts +47 -12
  198. package/src/cmd/ai/index.ts +6 -1
  199. package/src/cmd/ai/prompt/agent.md +306 -0
  200. package/src/cmd/ai/prompt/agent.ts +12 -322
  201. package/src/cmd/ai/prompt/api.md +360 -0
  202. package/src/cmd/ai/prompt/api.ts +13 -260
  203. package/src/cmd/ai/prompt/version.ts +61 -0
  204. package/src/cmd/ai/prompt/web.md +509 -0
  205. package/src/cmd/ai/prompt/web.ts +12 -282
  206. package/src/cmd/ai/skills/generate.ts +75 -0
  207. package/src/cmd/ai/skills/generator.ts +519 -0
  208. package/src/cmd/ai/skills/index.ts +23 -0
  209. package/src/cmd/auth/signup.ts +1 -0
  210. package/src/cmd/build/ast.ts +161 -48
  211. package/src/cmd/build/entry-generator.ts +258 -187
  212. package/src/cmd/build/vite/agent-discovery.ts +151 -58
  213. package/src/cmd/build/vite/bun-dev-server.ts +57 -27
  214. package/src/cmd/build/vite/docs-generator.ts +87 -0
  215. package/src/cmd/build/vite/index.ts +9 -7
  216. package/src/cmd/build/vite/lifecycle-generator.ts +19 -5
  217. package/src/cmd/build/vite/metadata-generator.ts +251 -7
  218. package/src/cmd/build/vite/prompt-generator.ts +169 -0
  219. package/src/cmd/build/vite/registry-generator.ts +750 -108
  220. package/src/cmd/build/vite/route-discovery.ts +4 -0
  221. package/src/cmd/build/vite/server-bundler.ts +73 -23
  222. package/src/cmd/build/vite/vite-asset-server-config.ts +5 -0
  223. package/src/cmd/build/vite/vite-builder.ts +134 -100
  224. package/src/cmd/build/vite-bundler.ts +6 -6
  225. package/src/cmd/cloud/deploy.ts +114 -36
  226. package/src/cmd/cloud/keyvalue/create-namespace.ts +3 -1
  227. package/src/cmd/cloud/keyvalue/delete-namespace.ts +3 -1
  228. package/src/cmd/cloud/keyvalue/delete.ts +3 -1
  229. package/src/cmd/cloud/keyvalue/set.ts +4 -2
  230. package/src/cmd/cloud/stream/get.ts +2 -9
  231. package/src/cmd/cloud/vector/delete-namespace.ts +89 -0
  232. package/src/cmd/cloud/vector/index.ts +21 -4
  233. package/src/cmd/cloud/vector/list-namespaces.ts +46 -0
  234. package/src/cmd/cloud/vector/stats.ts +160 -0
  235. package/src/cmd/cloud/vector/upsert.ts +216 -0
  236. package/src/cmd/dev/file-watcher.ts +109 -34
  237. package/src/cmd/dev/index.ts +364 -60
  238. package/src/cmd/dev/skills.ts +82 -0
  239. package/src/cmd/dev/sync.ts +41 -6
  240. package/src/cmd/index.ts +1 -0
  241. package/src/cmd/project/create.ts +3 -0
  242. package/src/cmd/project/template-flow.ts +37 -5
  243. package/src/cmd/setup/index.ts +1 -0
  244. package/src/cmd/upgrade/index.ts +68 -4
  245. package/src/config.ts +9 -0
  246. package/src/domain.ts +273 -0
  247. package/src/index.ts +0 -5
  248. package/src/runtime-bootstrap.md +1 -1
  249. package/src/schema-generator.ts +23 -0
  250. package/src/steps.ts +16 -5
  251. package/src/tui/prompt.ts +11 -5
  252. package/src/tui.ts +21 -2
  253. package/src/types/md.d.ts +8 -0
  254. package/src/types.ts +12 -3
  255. package/dist/cmd/cloud/domain.d.ts +0 -17
  256. package/dist/cmd/cloud/domain.d.ts.map +0 -1
  257. package/dist/cmd/cloud/domain.js +0 -79
  258. package/dist/cmd/cloud/domain.js.map +0 -1
  259. package/dist/runtime-bootstrap.d.ts +0 -56
  260. package/dist/runtime-bootstrap.d.ts.map +0 -1
  261. package/dist/runtime-bootstrap.js +0 -95
  262. package/dist/runtime-bootstrap.js.map +0 -1
  263. package/src/cmd/cloud/domain.ts +0 -100
  264. package/src/runtime-bootstrap.ts +0 -131
package/src/cmd/ai/prompt/web.md ADDED
@@ -0,0 +1,509 @@
1
+ # Web Folder Guide
2
+
3
+ This folder contains your React-based web application that communicates with your Agentuity agents.
4
+
5
+ ## Generated Types
6
+
7
+ The `src/generated/` folder contains auto-generated TypeScript files:
8
+
9
+ - `routes.ts` - Route registry with type-safe API, WebSocket, and SSE route definitions
10
+ - `registry.ts` - Agent registry with input/output types
11
+
12
+ **Important:** Never edit files in `src/generated/` - they are overwritten on every build.
13
+
14
+ Import generated types in your components:
15
+
16
+ ```typescript
17
+ // Routes are typed automatically via module augmentation
18
+ import { useAPI } from '@agentuity/react';
19
+
20
+ // The route 'GET /api/users' is fully typed
21
+ const { data } = useAPI('GET /api/users');
22
+ ```
23
+
24
+ ## Directory Structure
25
+
26
+ Required files:
27
+
28
+ - **App.tsx** (required) - Main React application component
29
+ - **frontend.tsx** (required) - Frontend entry point with client-side rendering
30
+ - **index.html** (required) - HTML template
31
+ - **public/** (optional) - Static assets (images, CSS, JS files)
32
+
33
+ Example structure:
34
+
35
+ ```
36
+ src/web/
37
+ ├── App.tsx
38
+ ├── frontend.tsx
39
+ ├── index.html
40
+ └── public/
41
+ ├── styles.css
42
+ ├── logo.svg
43
+ └── script.js
44
+ ```
45
+
46
+ ## Creating the Web App
47
+
48
+ ### App.tsx - Main Component
49
+
50
+ ```typescript
51
+ import { AgentuityProvider, useAPI } from '@agentuity/react';
52
+ import { useState } from 'react';
53
+
54
+ function HelloForm() {
55
+ const [name, setName] = useState('World');
56
+ const { invoke, isLoading, data: greeting } = useAPI('POST /api/hello');
57
+
58
+ return (
59
+ <div>
60
+ <input
61
+ type="text"
62
+ value={name}
63
+ onChange={(e) => setName(e.target.value)}
64
+ disabled={isLoading}
65
+ />
66
+
67
+ <button
68
+ onClick={() => invoke({ name })}
69
+ disabled={isLoading}
70
+ >
71
+ {isLoading ? 'Running...' : 'Say Hello'}
72
+ </button>
73
+
74
+ <div>{greeting ?? 'Waiting for response'}</div>
75
+ </div>
76
+ );
77
+ }
78
+
79
+ export function App() {
80
+ return (
81
+ <AgentuityProvider>
82
+ <div style={{ fontFamily: 'sans-serif', padding: '2rem' }}>
83
+ <h1>Welcome to Agentuity</h1>
84
+ <HelloForm />
85
+ </div>
86
+ </AgentuityProvider>
87
+ );
88
+ }
89
+ ```
90
+
91
+ ### frontend.tsx - Entry Point
92
+
93
+ ```typescript
94
+ import { createRoot } from 'react-dom/client';
95
+ import { App } from './App';
96
+
97
+ const root = document.getElementById('root');
98
+ if (!root) throw new Error('Root element not found');
99
+
100
+ createRoot(root).render(<App />);
101
+ ```
102
+
103
+ ### index.html - HTML Template
104
+
105
+ ```html
106
+ <!DOCTYPE html>
107
+ <html lang="en">
108
+ <head>
109
+ <meta charset="UTF-8" />
110
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
111
+ <title>My Agentuity App</title>
112
+ </head>
113
+ <body>
114
+ <div id="root"></div>
115
+ <script type="module" src="/web/frontend.tsx"></script>
116
+ </body>
117
+ </html>
118
+ ```
119
+
120
+ ## React Hooks
121
+
122
+ All hooks from `@agentuity/react` must be used within an `AgentuityProvider`. **Always use these hooks instead of raw `fetch()` calls** - they provide type safety, automatic error handling, and integration with the Agentuity platform.
123
+
124
+ ### useAPI - Type-Safe API Calls
125
+
126
+ The primary hook for making HTTP requests. **Use this instead of `fetch()`.**
127
+
128
+ ```typescript
129
+ import { useAPI } from '@agentuity/react';
130
+
131
+ function MyComponent() {
132
+ // GET requests auto-execute and return refetch
133
+ const { data, isLoading, error, refetch } = useAPI('GET /api/users');
134
+
135
+ // POST/PUT/DELETE return invoke for manual execution
136
+ const { invoke, data: result, isLoading: saving } = useAPI('POST /api/users');
137
+
138
+ const handleCreate = async () => {
139
+ // Input is fully typed from route schema!
140
+ await invoke({ name: 'Alice', email: 'alice@example.com' });
141
+ };
142
+
143
+ return (
144
+ <div>
145
+ <button onClick={handleCreate} disabled={saving}>
146
+ {saving ? 'Creating...' : 'Create User'}
147
+ </button>
148
+ {result && <p>Created: {result.name}</p>}
149
+ </div>
150
+ );
151
+ }
152
+ ```
153
+
154
+ **useAPI Return Values:**
155
+
156
+ | Property | Type | Description |
157
+ |----------|------|-------------|
158
+ | `data` | `T \| undefined` | Response data (typed from route schema) |
159
+ | `error` | `Error \| null` | Error if request failed |
160
+ | `isLoading` | `boolean` | True during initial load |
161
+ | `isFetching` | `boolean` | True during any fetch (including refetch) |
162
+ | `isSuccess` | `boolean` | True if last request succeeded |
163
+ | `isError` | `boolean` | True if last request failed |
164
+ | `invoke` | `(input?) => Promise<T>` | Manual trigger (POST/PUT/DELETE) |
165
+ | `refetch` | `() => Promise<void>` | Refetch data (GET) |
166
+ | `reset` | `() => void` | Reset state to initial |
167
+
168
+ ### useAPI Options
169
+
170
+ ```typescript
171
+ // GET with query parameters and caching
172
+ const { data } = useAPI({
173
+ route: 'GET /api/search',
174
+ query: { q: 'react', limit: '10' },
175
+ staleTime: 5000, // Cache for 5 seconds
176
+ refetchInterval: 10000, // Auto-refetch every 10 seconds
177
+ enabled: true, // Set to false to disable auto-fetch
178
+ });
179
+
180
+ // POST with callbacks
181
+ const { invoke } = useAPI({
182
+ route: 'POST /api/users',
183
+ onSuccess: (data) => console.log('Created:', data),
184
+ onError: (error) => console.error('Failed:', error),
185
+ });
186
+
187
+ // Streaming responses with onChunk
188
+ const { invoke } = useAPI({
189
+ route: 'POST /api/stream',
190
+ onChunk: (chunk) => console.log('Received chunk:', chunk),
191
+ delimiter: '\n', // Split stream by newlines (default)
192
+ });
193
+
194
+ // Custom headers
195
+ const { data } = useAPI({
196
+ route: 'GET /api/protected',
197
+ headers: { 'X-Custom-Header': 'value' },
198
+ });
199
+ ```
200
+
201
+ ### useWebsocket - WebSocket Connection
202
+
203
+ For bidirectional real-time communication. Automatically handles reconnection.
204
+
205
+ ```typescript
206
+ import { useWebsocket } from '@agentuity/react';
207
+
208
+ function ChatComponent() {
209
+ const { isConnected, data, send, messages, clearMessages, error, reset } = useWebsocket('/api/chat');
210
+
211
+ return (
212
+ <div>
213
+ <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
214
+ <button onClick={() => send({ message: 'Hello' })}>Send</button>
215
+ <div>
216
+ {messages.map((msg, i) => (
217
+ <p key={i}>{JSON.stringify(msg)}</p>
218
+ ))}
219
+ </div>
220
+ <button onClick={clearMessages}>Clear</button>
221
+ </div>
222
+ );
223
+ }
224
+ ```
225
+
226
+ **useWebsocket Return Values:**
227
+
228
+ | Property | Type | Description |
229
+ |----------|------|-------------|
230
+ | `isConnected` | `boolean` | True when WebSocket is connected |
231
+ | `data` | `T \| undefined` | Most recent message received |
232
+ | `messages` | `T[]` | Array of all received messages |
233
+ | `send` | `(data) => void` | Send a message (typed from route schema) |
234
+ | `clearMessages` | `() => void` | Clear the messages array |
235
+ | `close` | `() => void` | Close the connection |
236
+ | `error` | `Error \| null` | Error if connection failed |
237
+ | `isError` | `boolean` | True if there's an error |
238
+ | `reset` | `() => void` | Reset state and reconnect |
239
+ | `readyState` | `number` | WebSocket ready state |
240
+
241
+ ### useEventStream - Server-Sent Events
242
+
243
+ For server-to-client streaming (one-way). Use when server pushes updates to client.
244
+
245
+ ```typescript
246
+ import { useEventStream } from '@agentuity/react';
247
+
248
+ function NotificationsComponent() {
249
+ const { isConnected, data, error, close, reset } = useEventStream('/api/notifications');
250
+
251
+ return (
252
+ <div>
253
+ <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
254
+ {error && <p>Error: {error.message}</p>}
255
+ <p>Latest: {JSON.stringify(data)}</p>
256
+ <button onClick={close}>Disconnect</button>
257
+ </div>
258
+ );
259
+ }
260
+ ```
261
+
262
+ **useEventStream Return Values:**
263
+
264
+ | Property | Type | Description |
265
+ |----------|------|-------------|
266
+ | `isConnected` | `boolean` | True when EventSource is connected |
267
+ | `data` | `T \| undefined` | Most recent event data |
268
+ | `error` | `Error \| null` | Error if connection failed |
269
+ | `isError` | `boolean` | True if there's an error |
270
+ | `close` | `() => void` | Close the connection |
271
+ | `reset` | `() => void` | Reset state and reconnect |
272
+ | `readyState` | `number` | EventSource ready state |
273
+
274
+ ### useAgentuity - Access Context
275
+
276
+ Access the Agentuity context for base URL and configuration.
277
+
278
+ ```typescript
279
+ import { useAgentuity } from '@agentuity/react';
280
+
281
+ function MyComponent() {
282
+ const { baseUrl } = useAgentuity();
283
+
284
+ return <p>API Base: {baseUrl}</p>;
285
+ }
286
+ ```
287
+
288
+ ### useAuth - Authentication State
289
+
290
+ Access and manage authentication state.
291
+
292
+ ```typescript
293
+ import { useAuth } from '@agentuity/react';
294
+
295
+ function AuthStatus() {
296
+ const { isAuthenticated, authHeader, setAuthHeader, authLoading } = useAuth();
297
+
298
+ const handleLogin = async (token: string) => {
299
+ setAuthHeader?.(`Bearer ${token}`);
300
+ };
301
+
302
+ const handleLogout = () => {
303
+ setAuthHeader?.(null);
304
+ };
305
+
306
+ if (authLoading) return <p>Loading...</p>;
307
+
308
+ return (
309
+ <div>
310
+ {isAuthenticated ? (
311
+ <button onClick={handleLogout}>Logout</button>
312
+ ) : (
313
+ <button onClick={() => handleLogin('my-token')}>Login</button>
314
+ )}
315
+ </div>
316
+ );
317
+ }
318
+ ```
319
+
320
+ **useAuth Return Values:**
321
+
322
+ | Property | Type | Description |
323
+ |----------|------|-------------|
324
+ | `isAuthenticated` | `boolean` | True if user has auth token and not loading |
325
+ | `authHeader` | `string \| null` | Current auth header (e.g., "Bearer ...") |
326
+ | `setAuthHeader` | `(token) => void` | Set auth header (null to clear) |
327
+ | `authLoading` | `boolean` | True during auth state changes |
328
+ | `setAuthLoading` | `(loading) => void` | Set auth loading state |
329
+
330
+ ## Complete Example
331
+
332
+ ```typescript
333
+ import { AgentuityProvider, useAPI, useWebsocket } from '@agentuity/react';
334
+ import { useEffect, useState } from 'react';
335
+
336
+ function Dashboard() {
337
+ const [count, setCount] = useState(0);
338
+ const { invoke, data: agentResult } = useAPI('POST /api/process');
339
+ const { isConnected, send, data: wsMessage } = useWebsocket('/api/live');
340
+
341
+ useEffect(() => {
342
+ if (isConnected) {
343
+ const interval = setInterval(() => {
344
+ send({ ping: Date.now() });
345
+ }, 1000);
346
+ return () => clearInterval(interval);
347
+ }
348
+ }, [isConnected, send]);
349
+
350
+ return (
351
+ <div style={{ fontFamily: 'sans-serif', padding: '2rem' }}>
352
+ <h1>My Agentuity App</h1>
353
+
354
+ <div>
355
+ <p>Count: {count}</p>
356
+ <button onClick={() => setCount(c => c + 1)}>
357
+ Increment
358
+ </button>
359
+ </div>
360
+
361
+ <div>
362
+ <button onClick={() => invoke({ name: 'Jeff', age: 30 })}>
363
+ Call API
364
+ </button>
365
+ <p>{JSON.stringify(agentResult)}</p>
366
+ </div>
367
+
368
+ <div>
369
+ <strong>WebSocket:</strong>
370
+ {isConnected ? JSON.stringify(wsMessage) : 'Not connected'}
371
+ </div>
372
+ </div>
373
+ );
374
+ }
375
+
376
+ export function App() {
377
+ return (
378
+ <AgentuityProvider>
379
+ <Dashboard />
380
+ </AgentuityProvider>
381
+ );
382
+ }
383
+ ```
384
+
385
+ ## Static Assets
386
+
387
+ Place static files in the **public/** folder:
388
+
389
+ ```
390
+ src/web/public/
391
+ ├── logo.svg
392
+ ├── styles.css
393
+ └── script.js
394
+ ```
395
+
396
+ Reference them in your HTML or components:
397
+
398
+ ```html
399
+ <!-- In index.html -->
400
+ <link rel="stylesheet" href="/public/styles.css" />
401
+ <script src="/public/script.js"></script>
402
+ ```
403
+
404
+ ```typescript
405
+ // In React components
406
+ <img src="/public/logo.svg" alt="Logo" />
407
+ ```
408
+
409
+ ## Styling
410
+
411
+ ### Inline Styles
412
+
413
+ ```typescript
414
+ <div style={{ backgroundColor: '#000', color: '#fff', padding: '1rem' }}>
415
+ Styled content
416
+ </div>
417
+ ```
418
+
419
+ ### CSS Files
420
+
421
+ Create `public/styles.css`:
422
+
423
+ ```css
424
+ body {
425
+ background-color: #09090b;
426
+ color: #fff;
427
+ font-family: sans-serif;
428
+ }
429
+ ```
430
+
431
+ Import in `index.html`:
432
+
433
+ ```html
434
+ <link rel="stylesheet" href="/public/styles.css" />
435
+ ```
436
+
437
+ ### Style Tag in Component
438
+
439
+ ```typescript
440
+ <div>
441
+ <button className="glow-btn">Click me</button>
442
+ <style>{`
443
+ .glow-btn {
444
+ background: linear-gradient(to right, #155e75, #3b82f6);
445
+ border: none;
446
+ padding: 0.75rem 1.5rem;
447
+ color: white;
448
+ cursor: pointer;
449
+ }
450
+ `}</style>
451
+ </div>
452
+ ```
453
+
454
+ ## RPC-Style API Client
455
+
456
+ For non-React contexts (like utility functions or event handlers), use `createClient`:
457
+
458
+ ```typescript
459
+ import { createClient } from '@agentuity/react';
460
+
461
+ // Create a typed client (uses global baseUrl and auth from AgentuityProvider)
462
+ const api = createClient();
463
+
464
+ // Type-safe RPC-style calls - routes become nested objects
465
+ // Route 'GET /api/users' becomes api.users.get()
466
+ // Route 'POST /api/users' becomes api.users.post()
467
+ // Route 'GET /api/users/:id' becomes api.users.id.get({ id: '123' })
468
+
469
+ async function fetchData() {
470
+ const users = await api.users.get();
471
+ const newUser = await api.users.post({ name: 'Alice', email: 'alice@example.com' });
472
+ const user = await api.users.id.get({ id: '123' });
473
+ return { users, newUser, user };
474
+ }
475
+ ```
476
+
477
+ **When to use `createClient` vs `useAPI`:**
478
+
479
+ | Use Case | Recommendation |
480
+ |----------|----------------|
481
+ | React component rendering | `useAPI` hook |
482
+ | Event handlers | Either works |
483
+ | Utility functions | `createClient` |
484
+ | Non-React code | `createClient` |
485
+ | Need loading/error state | `useAPI` hook |
486
+ | Need caching/refetch | `useAPI` hook |
487
+
488
+ ## Best Practices
489
+
490
+ - Wrap your app with **AgentuityProvider** for hooks to work
491
+ - **Always use `useAPI` instead of `fetch()`** for type safety and error handling
492
+ - Use **useAPI** for type-safe HTTP requests (GET, POST, PUT, DELETE)
493
+ - Use **useWebsocket** for bidirectional real-time communication
494
+ - Use **useEventStream** for server-to-client streaming
495
+ - Use **useAuth** for authentication state management
496
+ - Handle loading and error states in UI
497
+ - Place reusable components in separate files
498
+ - Keep static assets in the **public/** folder
499
+
500
+ ## Rules
501
+
502
+ - **App.tsx** must export a function named `App`
503
+ - **frontend.tsx** must render the `App` component to `#root`
504
+ - **index.html** must have a `<div id="root"></div>`
505
+ - Routes are typed via module augmentation from `src/generated/routes.ts`
506
+ - The web app is served at `/` by default
507
+ - Static files in `public/` are served at `/public/*`
508
+ - Module script tag: `<script type="module" src="/web/frontend.tsx"></script>`
509
+ - **Never use raw `fetch()` calls** - always use `useAPI` or `createClient`