@hugex/ai 2.8.7 → 2.8.8

package/README.md

@@ -0,0 +1,283 @@
+# @hugex/ai
+
+Ora agent runtime for Cloudflare Workers — flow execution (`FlowEngine`), session state (`AgentDO`), server route handlers, and the React client hook (`useAgent`).
+
+Flows are **designed** in [hx-ai](https://github.com/hugex/hx) (`AgentDesign.tsx`, React Flow canvas) and **saved** to HX Core. Tenant apps install this package, wire the worker routes, and connect the UI with `useAgent`.
+
+## Install
+
+```bash
+pnpm add @hugex/ai
+```
+
+Peer/runtime deps (React 19, `react-router` 7, `zod`, `zustand`, `ai`, etc.) are declared in the package — align versions with your tenant app.
+
+## Exports
+
+| 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 |
+
+## Worker setup (required)
+
+Each tenant Worker chains the route handlers and re-exports the Durable Object:
+
+```ts
+// workers/app.ts
+import {
+  handleAgentsRoutes,
+  handleAuthRoutes,
+  handleCommonRoutes,
+  handleIntancesRoutes,
+} from '@hugex/ai';
+import { createRequestHandler } from 'react-router';
+
+const requestHandler = createRequestHandler(
+  () => import('virtual:react-router/server-build'),
+  import.meta.env.MODE,
+);
+
+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 requestHandler(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).
+
+## 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:
+
+| 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 |
+
+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.
+
+### Node types (flow graph)
+
+Design-time node data (configured in Agent Design panels):
+
+| Node | Key data |
+|---|---|
+| **Start** | `greeting`, `allow_images`, `allow_documents`, `memory_*` toggles |
+| **LLM** | `template`, `model`, `tools`, `varMapping`, `outVars` |
+| **Memo** | `rag_id`, `query_key`, `topk` |
+| **Classifier** | `input_variable`, `items[]` |
+| **API** | `url`, `method`, `headers`, `body`, `varMapping` |
+| **Answer** | Required flow terminus |
+
+Rules: exactly one Start, at least one Answer, all paths connected.
+
+## `useAgent` — client hook
+
+`useAgent` opens a WebSocket to the session DO, decodes the `TYPE::CONTENT` wire protocol, and writes conversation state into a Zustand store. UI components subscribe to the store and call `send`, `clearHistory`, etc.
+
+### Options
+
+```ts
+useAgent({
+  host?: string;       // WS host; omit when same origin as the page
+  basePath?: string;   // path segment under host (see below)
+  agent?: string;      // flowId
+  name?: string;       // sessionId
+  query?: Record<string, string | null> | (() => Promise<Record<string, string | null>>);
+  user?: string;       // anonymous session label; sent as UID on connect
+  storeKey?: string;   // isolate store when multiple agents on one screen
+});
+```
+
+Returns `{ connection, store, send, clearHistory, sendAuth, setIdentity, approve, reject, ... }`.
+
+### WebSocket paths
+
+Two server routes exist in `@hugex/ai`:
+
+| 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 |
+
+### Pattern 1 — tenant chat (single agent)
+
+Same-origin tenant app; no `host` needed. Uses the global store (`useAgentStore`).
+
+```tsx
+import { useAgent, useAgentStore } from '@hugex/ai/client';
+
+function Chat({ flowId, sessionId }: { flowId: string; sessionId: string }) {
+  const { messages, typingMessage } = useAgentStore();
+
+  const { send, clearHistory } = useAgent({
+    basePath: `api/agent/flow/${flowId}/${sessionId}`,
+    agent: flowId,
+    name: sessionId,
+  });
+
+  // render messages, call send(text) on submit
+}
+```
+
+Reference: `ora-base/app/secure/chat/components/ChatView.tsx`.
+
+### Pattern 2 — Run panel (design-time test)
+
+Flow under design in Agent Design; `flowId` from route params; session from run store; JWT via `query`:
+
+```tsx
+const { id: flowId } = useParams<{ id: string }>();
+const sessionId = '…'; // from run session store
+const socketUrl = tenant.data.ora.socketServer; // e.g. tenant worker host
+
+const { send, sendAuth, clearHistory } = useAgent({
+  host: socketUrl,
+  basePath: `api/agent/flow/${flowId}/${sessionId}`,
+  agent: flowId,
+  name: sessionId,
+  query: async () => ({ access_token: await readAccessToken() }),
+});
+
+const messages = useAgentStore((s) => s.messages);
+```
+
+Reference: `hx-ai/.../RunStatusPanel.tsx` (opened from `AgentDesign.tsx`).
+
+Start-node flags (`allow_images`, `allow_documents`, `memory_enabled`) are read from the canvas nodes to drive the Run 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:
+
+```tsx
+const { send, sendAuth, store } = useAgent({
+  host: ORA_SOCKET_HOST,
+  basePath: `api/ora/connect/${ORA_FLOW_ID}/${sessionId}`,
+  agent: ORA_FLOW_ID,
+  name: sessionId,
+  query: { authorization: ORA_AUTH_KEY },
+  user: email ?? undefined,
+  storeKey: 'agent-design', // 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')`.
+
+**Rule:** `storeKey` must be constant for the component lifetime (do not derive from per-render state).
+
+## 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.
+
+```ts
+const sendTurn = async (text: string) => {
+  const token = await readAccessToken();
+  if (token) sendAuth('ACCESS_TOKEN', token);
+  send(text);
+};
+```
+
+`clearHistory()` wipes server auth too — re-push after clearing.
+
+## Store fields (reactive UI)
+
+Subscribe via `useAgentStore` (global) or `store` (isolated):
+
+| Field | Use |
+|---|---|
+| `messages` | Chat history (replayed from DO on connect via `HIS::`) |
+| `typingMessage` | Streaming assistant text (`TS` / `TSC`) |
+| `reasoningMessage` | Streaming reasoning (`RS` / `RSC`) |
+| `status` | `'connecting' \| 'connected' \| 'disconnected'` — gate input on `'connected'` |
+| `flowConfig` | Start-node config from server (`CFG::`: greeting, attachments) |
+| `events` | Tool/info events from `SE::` stream |
+| `composioAuth` | OAuth redirect when Composio manual auth is required |
+| `approvals` | Human-in-the-loop tool approvals |
+
+## Wire protocol (summary)
+
+Inbound frames use `TYPE::CONTENT`:
+
+| Code | Meaning |
+|---|---|
+| `HIS` | Full history replay |
+| `SE` | Server event (tools, memory, Composio, …) |
+| `TS` / `TSC` | Assistant text stream / complete |
+| `RS` / `RSC` | Reasoning stream / complete |
+| `CFG` | Flow config (attachments, greeting) |
+| `ERR` | Error string |
+
+Outbound: `M:` user message, `CH:` clear history, `AUT:` runtime credential, `UID:` session identity.
+
+Full reference: Ora `WEBSOCKET_EVENTS.md` (in the `ora/` source repo).
+
+## Vite
+
+Exclude `@hugex/ai` from `optimizeDeps` in tenant apps:
+
+```ts
+optimizeDeps: {
+  exclude: ['@hugex/ai'],
+},
+```
+
+## Release (maintainers)
+
+From the `ora/` source repo:
+
+```bash
+task publish:ai              # bump patch, build, publish
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hugex/ai",
-  "version": "2.8.7",
+  "version": "2.8.8",
   "description": "Ora AI Agent Framework",
   "author": "a@hugex.co",
   "license": "UNLICENSED",
@@ -45,7 +45,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",