@hugex/ai 2.8.12 → 2.8.13

package/README.md

@@ -1,8 +1,18 @@
 # @hugex/ai
 
-HugeX Agent runtime for Cloudflare Workers — flow execution (`FlowEngine`), session state (`AgentDO`), server route handlers, and the React client hook (`useAgent`).
+HugeX Agent runtime — a React client hook (`useAgent`) plus optional server handlers for hosting the agent backend on Cloudflare Workers.
 
-Flows are **designed** in the [HugeX platform](https://hugex.co/) (**Agent Design**) and **saved** to HX Core. Tenant apps install this package, wire the worker routes, and connect the UI with `useAgent`.
+Flows are **designed** in the [HugeX platform](https://hugex.co/) (**Agent Design**) and **saved** to HX Core. Most integrations only need the **client** half: install `@hugex/ai`, point `useAgent` at an already-deployed WebSocket endpoint, and render chat UI from the agent store.
+
+## Two parts
+
+| Part | Import | Runs in | When you need it |
+|---|---|---|---|
+| **Client** | `@hugex/ai/client` | Your React app (browser) | **Always** — connect UI to an agent session |
+| **Server** | `@hugex/ai` | Cloudflare Worker | **Only if you host the agent runtime** (tenant Worker deployment) |
+| **Shared types** | `@hugex/ai/common` | Either | Wire-protocol and flow types |
+
+**You do not run `useAgent` on Cloudflare Workers.** The hook is frontend-only. It opens a WebSocket to a session endpoint; that endpoint is usually served by a HugeX tenant Worker you or HugeX already deployed. Your SPA can run anywhere — same origin, a separate frontend host, or a local dev server — as long as it can reach the WebSocket URL.
 
 ## Install
 
@@ -10,77 +20,43 @@ Flows are **designed** in the [HugeX platform](https://hugex.co/) (**Agent Desig
 pnpm add @hugex/ai
 ```
 
-Peer dependencies are declared in the package — align versions with your tenant app.
+Peer dependencies are declared in the package — align versions with your app.
 
-## Exports
+## Integration paths
 
-| Import | Purpose |
-|---|---|
-| `@hugex/ai` | Server: `handleAgentsRoutes`, `handleAuthRoutes`, `handleCommonRoutes`, `handleIntancesRoutes`, `AgentDO` |
-| `@hugex/ai/client` | Client: `useAgent`, `useAgentStore`, `getAgentStore` |
-| `@hugex/ai/common` | Shared types: `NodeType`, WS `messageTypes`, flow/message types |
+### Frontend only (most common)
 
-## Worker setup (required)
+Use `@hugex/ai/client` in your React app. You need:
 
-Each tenant Worker chains the route handlers and re-exports the Durable Object:
+1. **flowId** — the agent graph id from Agent Design
+2. **sessionId** — a stable id for this chat session (UUID recommended)
+3. **WebSocket endpoint** — URL of a deployed agent server (see [WebSocket paths](#websocket-paths))
 
-```ts
-// workers/app.ts
-import {
-  handleAgentsRoutes,
-  handleAuthRoutes,
-  handleCommonRoutes,
-  handleIntancesRoutes,
-} from '@hugex/ai';
+No Worker code, wrangler config, or server imports required in your frontend repo.
 
-export default {
-  async fetch(request, env, ctx) {
-    const common = await handleCommonRoutes(request, env, ctx);
-    if (common instanceof Response) return common;
-
-    const auth = await handleAuthRoutes(request, env, ctx);
-    if (auth instanceof Response) return auth;
-
-    const agent = await handleAgentsRoutes(request, env, ctx);
-    if (agent instanceof Response) return agent;
-
-    const instances = await handleIntancesRoutes(request, env, ctx);
-    if (instances instanceof Response) return instances;
-
-    // Then delegate to your app's SSR/router handler.
-    return yourAppHandler(request, { cloudflare: { env, ctx }, state: { ...auth } });
-  },
-} satisfies ExportedHandler<Env>;
-
-export { AgentDO } from '@hugex/ai';
-```
+| Scenario | `host` | Notes |
+|---|---|---|
+| App and agent server share a domain | omit | `basePath` is relative to the page origin |
+| App on a different host (SPA, mobile web, local dev) | set to agent server host | e.g. `tenant.data.ora.socketServer` |
+| Multiple agents on one screen | + `storeKey` | Isolates chat state per agent |
 
-`wrangler.jsonc` must bind the Durable Object:
+### Self-hosted runtime (tenant Worker)
 
-```jsonc
-{
-  "durable_objects": {
-    "bindings": [{ "class_name": "AgentDO", "name": "AGENT" }]
-  },
-  "migrations": [{ "tag": "v2", "new_sqlite_classes": ["AgentDO"] }]
-}
-```
+Only needed when **your** Cloudflare Worker must serve agent WebSocket routes (`/api/agent/flow/...`, `/api/ora/connect/...`) and run `AgentDO` sessions. See [Cloudflare Workers (optional)](#cloudflare-workers-optional--host-the-runtime).
 
-Required env vars (typical): `HX_CORE_URL`, `HX_ORA_URL`, `HX_API_KEY`, tenant Vectorize binding `VDB_<tenant>_1024`, `AI` (Workers AI).
+HugeX-managed tenant deployments already include this — frontend teams typically skip this section.
 
 ## Flow IDs and agent configuration
 
-A **flow** is the graph you edit in hx-ai **Agent Design** (`/ai/agents/:id`). The URL param `id` is the **flowId** (e.g. `1rShqGMrANRGmXTN1mjTJB`).
-
-At runtime:
+A **flow** is the graph you edit in **Agent Design** (`/ai/agents/:id`). The URL param `id` is the **flowId** (e.g. `1rShqGMrANRGmXTN1mjTJB`).
 
 | Concept | Value | Notes |
 |---|---|---|
-| **flowId** | Agent Design `:id` | Identifies which flow graph to run; also used as the Cloudflare `agent` name |
-| **sessionId** | UUID (or stable string) | One chat session; maps to one `AgentDO` instance |
-| **DO name** | `` `${flowId}::${sessionId}` `` | Server-side session key |
+| **flowId** | Agent Design `:id` | Identifies which flow graph to run |
+| **sessionId** | UUID (or stable string) | One chat session; server maps this to session state |
+| **Session key** | `` `${flowId}::${sessionId}` `` | Server-side identifier (used when hosting the runtime) |
 
-Flow metadata (tenant, visibility, status) lives in HX Core KV. The DO loads flow **state** (nodes/edges) from `GET {HX_CORE_URL}/ora/flow/{flowId}/state` on WebSocket connect.
+Flow metadata (tenant, visibility, status) lives in HX Core. The runtime loads flow **state** (nodes/edges) from HX Core on WebSocket connect.
 
 ### Node types (flow graph)
 
@@ -97,9 +73,9 @@ Design-time node data (configured in Agent Design panels):
 
 Rules: exactly one Start, at least one Answer, all paths connected.
 
-## `useAgent` — client hook
+## `useAgent` — client integration
 
-`useAgent` opens a WebSocket to the session DO, decodes the `TYPE::CONTENT` wire protocol, and writes conversation state into the agent store. UI components subscribe to the store and call `send`, `clearHistory`, etc.
+`useAgent` opens a WebSocket to the agent session, decodes the `TYPE::CONTENT` wire protocol, and writes conversation state into the agent store. UI components subscribe to the store and call `send`, `clearHistory`, etc.
 
 ### Options
 
@@ -119,16 +95,16 @@ Returns `{ connection, store, send, clearHistory, sendAuth, setIdentity, approve
 
 ### WebSocket paths
 
-Two server routes exist in `@hugex/ai`:
+These routes are served by the **agent backend** (typically a deployed tenant Worker). Your frontend connects to them; it does not implement them.
 
 | Route | Auth | Typical use |
 |---|---|---|
 | `/api/agent/flow/{flowId}/{sessionId}` | JWT / `access_token` query | Tenant chat UIs, Run panel |
-| `/api/ora/connect/{flowId}/{sessionId}` | Agent API key (`authorization` query/header) | hx-ai design assistant |
+| `/api/ora/connect/{flowId}/{sessionId}` | Agent API key (`authorization` query/header) | Design assistant, tooling |
 
-### Pattern 1 — tenant chat (single agent)
+### Pattern 1 — same-origin chat
 
-Same-origin tenant app; no `host` needed. Uses the global store (`useAgentStore`).
+Frontend and agent server share a domain. No `host` needed. Uses the global store (`useAgentStore`).
 
 ```tsx
 import { useAgent, useAgentStore } from '@hugex/ai/client';
@@ -146,19 +122,19 @@ function Chat({ flowId, sessionId }: { flowId: string; sessionId: string }) {
 }
 ```
 
-Reference: `ora-base/app/secure/chat/components/ChatView.tsx`.
+### Pattern 2 — cross-origin chat
 
-### Pattern 2 — Run panel (design-time test)
-
-Flow under design in Agent Design; `flowId` from route params; session from run store; JWT via `query`:
+Frontend runs on a different host (SPA, local dev, separate deployment). Set `host` to the deployed agent server.
 
 ```tsx
+import { useAgent, useAgentStore } from '@hugex/ai/client';
+
 const flowId = '…'; // from your route or config
-const sessionId = '…'; // from run session store
-const socketUrl = tenant.data.ora.socketServer; // tenant worker host
+const sessionId = '…'; // from session store
+const socketHost = '…'; // deployed agent server host (no path)
 
 const { send, sendAuth, clearHistory } = useAgent({
-  host: socketUrl,
+  host: socketHost,
   basePath: `api/agent/flow/${flowId}/${sessionId}`,
   agent: flowId,
   name: sessionId,
@@ -168,38 +144,36 @@ const { send, sendAuth, clearHistory } = useAgent({
 const messages = useAgentStore((s) => s.messages);
 ```
 
-Reference: `hx-ai/.../RunStatusPanel.tsx`.
-
-Start-node flags (`allow_images`, `allow_documents`, `memory_enabled`) are read from the canvas nodes to drive the Run UI.
+Start-node flags (`allow_images`, `allow_documents`, `memory_enabled`) can be read from flow config (`flowConfig` in the store) or from your design metadata to drive the UI.
 
 ### Pattern 3 — multiple agents on one screen (`storeKey`)
 
-When two agents mount together (e.g. **Run panel** + **design assistant** in Agent Design), pass a stable `storeKey` so their chat state does not collide:
+When two agents mount together, pass a stable `storeKey` so their chat state does not collide:
 
 ```tsx
 const { send, sendAuth, store } = useAgent({
-  host: ORA_SOCKET_HOST,
-  basePath: `api/ora/connect/${ORA_FLOW_ID}/${sessionId}`,
-  agent: ORA_FLOW_ID,
+  host: AGENT_SERVER_HOST,
+  basePath: `api/ora/connect/${FLOW_ID}/${sessionId}`,
+  agent: FLOW_ID,
   name: sessionId,
-  query: { authorization: ORA_AUTH_KEY },
+  query: { authorization: AGENT_API_KEY },
   user: email ?? undefined,
-  storeKey: 'agent-design', // stable for this component's lifetime
+  storeKey: 'my-panel', // stable for this component's lifetime
 });
 
 const messages = store((s) => s.messages);
 const status = store((s) => s.status);
 ```
 
-Reference: `hx-ai/.../AgentPanel.tsx`. Child components that need the same isolated state must use the **same** `storeKey` via `getAgentStore('agent-design')`.
+Child components that need the same isolated state must use the **same** `storeKey` via `getAgentStore('my-panel')`.
 
 **Rule:** `storeKey` must be constant for the component lifetime (do not derive from per-render state).
 
-## Runtime credentials (`sendAuth`)
+### Runtime credentials (`sendAuth`)
 
 Tools may reference `{{ auth.NAME }}` placeholders. Push credentials with `sendAuth(name, value)` — they never appear in chat history.
 
-**Important:** re-push credentials **before every `send`**, not once on connect. Durable Object hibernation clears in-memory auth mid-connection without disconnecting the WebSocket.
+**Important:** re-push credentials **before every `send`**, not once on connect. Server-side session hibernation can clear in-memory auth mid-connection without disconnecting the WebSocket.
 
 ```ts
 const sendTurn = async (text: string) => {
@@ -211,13 +185,13 @@ const sendTurn = async (text: string) => {
 
 `clearHistory()` wipes server auth too — re-push after clearing.
 
-## Store fields (reactive UI)
+### Store fields (reactive UI)
 
 Subscribe via `useAgentStore` (global) or `store` (isolated):
 
 | Field | Use |
 |---|---|
-| `messages` | Chat history (replayed from DO on connect via `HIS::`) |
+| `messages` | Chat history (replayed on connect via `HIS::`) |
 | `typingMessage` | Streaming assistant text (`TS` / `TSC`) |
 | `reasoningMessage` | Streaming reasoning (`RS` / `RSC`) |
 | `status` | `'connecting' \| 'connected' \| 'disconnected'` — gate input on `'connected'` |
@@ -226,7 +200,7 @@ Subscribe via `useAgentStore` (global) or `store` (isolated):
 | `composioAuth` | OAuth redirect when a connected tool requires manual authorization |
 | `approvals` | Human-in-the-loop tool approvals |
 
-## Wire protocol (summary)
+### Wire protocol (summary)
 
 Inbound frames use `TYPE::CONTENT`:
 
@@ -241,7 +215,64 @@ Inbound frames use `TYPE::CONTENT`:
 
 Outbound: `M:` user message, `CH:` clear history, `AUT:` runtime credential, `UID:` session identity.
 
-Full reference: wire protocol details in the HugeX runtime source (`WEBSOCKET_EVENTS.md`).
+## Cloudflare Workers (optional — host the runtime)
+
+Use this section only when **you** deploy the agent backend on Cloudflare Workers (e.g. a tenant Worker). Frontend-only integrations can skip it entirely.
+
+### Exports (server)
+
+| Import | Purpose |
+|---|---|
+| `@hugex/ai` | `handleAgentsRoutes`, `handleAuthRoutes`, `handleCommonRoutes`, `handleIntancesRoutes`, `AgentDO` |
+
+### Worker setup
+
+Chain the route handlers and re-export the Durable Object:
+
+```ts
+// workers/app.ts
+import {
+  handleAgentsRoutes,
+  handleAuthRoutes,
+  handleCommonRoutes,
+  handleIntancesRoutes,
+} from '@hugex/ai';
+
+export default {
+  async fetch(request, env, ctx) {
+    const common = await handleCommonRoutes(request, env, ctx);
+    if (common instanceof Response) return common;
+
+    const auth = await handleAuthRoutes(request, env, ctx);
+    if (auth instanceof Response) return auth;
+
+    const agent = await handleAgentsRoutes(request, env, ctx);
+    if (agent instanceof Response) return agent;
+
+    const instances = await handleIntancesRoutes(request, env, ctx);
+    if (instances instanceof Response) return instances;
+
+    return yourAppHandler(request, { cloudflare: { env, ctx }, state: { ...auth } });
+  },
+} satisfies ExportedHandler<Env>;
+
+export { AgentDO } from '@hugex/ai';
+```
+
+`wrangler.jsonc` must bind the Durable Object:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "class_name": "AgentDO", "name": "AGENT" }]
+  },
+  "migrations": [{ "tag": "v2", "new_sqlite_classes": ["AgentDO"] }]
+}
+```
+
+Required env vars (typical): `HX_CORE_URL`, `HX_ORA_URL`, `HX_API_KEY`, tenant Vectorize binding `VDB_<tenant>_1024`, `AI` (Workers AI).
+
+Session memory, secrets (`{{ secrets.NAME }}`), Vectorize memo, and tool execution run inside `AgentDO`; shared data is fetched from HX Core / hx-ora APIs.
 
 ## Bundler
 
@@ -253,6 +284,21 @@ optimizeDeps: {
 },
 ```
 
+## Architecture (high level)
+
+```
+Agent Design  ──save──►  HX Core (flow state + KV metadata)
+                              ▲
+Agent backend (optional)  ──fetch──┘
+  WebSocket routes → session runtime (per flowId::sessionId)
+  FlowEngine runs Start → … → Answer
+
+React app (useAgent)  ◄──WebSocket TYPE::CONTENT──►  Agent backend
+```
+
+- **Frontend:** any React host — imports `@hugex/ai/client`, connects via WebSocket.
+- **Backend:** Cloudflare Worker with `@hugex/ai` server exports — only when you host the runtime.
+
 ## Release (maintainers)
 
 From the `ora/` source repo:
@@ -263,20 +309,6 @@ task publish:ai -- --dry-run  # build + npm pack only
 task build:ai                 # build to ../ai without publish
 ```
 
-## Architecture (high level)
-
-```
-hx-ai Agent Design  ──save──►  HX Core (flow state + KV metadata)
-                                      ▲
-Tenant Worker (@hugex/ai)  ──fetch──┘
-  ├ handleAgentsRoutes → WebSocket → AgentDO (per flowId::sessionId)
-  └ FlowEngine runs Start → … → Answer
-
-Client (useAgent)  ◄──WebSocket TYPE::CONTENT──►  AgentDO
-```
-
-Session memory, secrets (`{{ secrets.NAME }}`), Vectorize memo, and tool execution run inside the DO; shared data is fetched from HX Core / hx-ora APIs.
-
 ## License
 
 Included with your HugeX deployment — install and use this package as documented in this README. Full terms are in the `LICENSE` file included in this npm package (also listed under **License** on this page).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hugex/ai",
-  "version": "2.8.12",
+  "version": "2.8.13",
   "description": "Ora AI Agent Framework",
   "author": "a@hugex.co",
   "license": "SEE LICENSE IN LICENSE",