@agno-hq/chat-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# @agno-hq/chat-react
+
+Headless React hook (`useAgnoChat`) plus drop-in UI components for streaming **any
+Agno agent, team, or workflow** from an [AgentOS](https://docs.agno.com) backend.
+
+It speaks the AgentOS HTTP run protocol directly: it POSTs to the run endpoint,
+parses the streamed events, and accumulates them into render-ready messages —
+content, tool calls, reasoning, citations, media — while exposing the raw event
+feed, live status, and human-in-the-loop pauses.
+
+```tsx
+import { AgnoChat } from '@agno-hq/chat-react'
+import '@agno-hq/chat-react/styles.css'
+
+export default function Page() {
+  return <AgnoChat baseUrl="http://localhost:7777" showEventLog allowFiles />
+}
+```
+
+That's the zero-wiring widget: it discovers the agents/teams/workflows on your
+AgentOS, shows a selector, and runs a full chat. For full control, use the hook.
+
+---
+
+## Install
+
+```bash
+npm install @agno-hq/chat-react
+```
+
+`react` and `react-dom` (>=18) are peer dependencies. The library ships
+compiled ESM + CommonJS bundles with bundled type declarations, so it works out
+of the box in any modern bundler (Vite, Next.js, Webpack, etc.) with no extra
+config. Import the stylesheet once (see below).
+
+---
+
+## The hook: `useAgnoChat`
+
+```tsx
+import { useAgnoChat, ChatWindow } from '@agno-hq/chat-react'
+import '@agno-hq/chat-react/styles.css'
+
+function Chat() {
+  const chat = useAgnoChat({
+    baseUrl: 'http://localhost:7777',
+    entity: { type: 'agent', id: 'agno_assist', name: 'Agno Assist' },
+    userId: 'user-123',
+  })
+
+  return <ChatWindow chat={chat} />
+}
+```
+
+`entity.type` is `'agent' | 'team' | 'workflow'` and `entity.id` is the
+agent/team/workflow id — the same hook drives all three.
+
+### What the hook returns
+
+| Value | Type | Description |
+|---|---|---|
+| `messages` | `ChatMessage[]` | Full transcript, oldest first. |
+| `streamingMessage` | `ChatMessage \| null` | The agent message currently streaming. |
+| `events` | `RunEventData[]` | Every raw event from the latest run, in order. |
+| `currentEvent` | `RunEventData \| null` | The most recent event. |
+| `status` | `'idle' \| 'streaming' \| 'paused' \| 'completed' \| 'error' \| 'cancelled'` | Run lifecycle. |
+| `activity` | `string \| null` | Live label, e.g. `"Calling get_weather"`, `"Reasoning"`. |
+| `isStreaming` / `isPaused` | `boolean` | Convenience flags. |
+| `error` | `string \| null` | Last error message. |
+| `sessionId` | `string \| undefined` | Auto-captured from the first run. |
+| `tools` | `ToolExecution[]` | Tool calls of the active message. |
+| `reasoning` | `ReasoningStep[]` | Reasoning steps of the active message. |
+| `pendingRequirements` | `RunRequirement[]` | Outstanding human-in-the-loop asks. |
+
+### Actions
+
+| Action | Description |
+|---|---|
+| `sendMessage(text, { files? })` | Send a message and stream the response. |
+| `cancel()` | Abort the active run (also calls the cancel endpoint). |
+| `continueRun({ tools?, stepRequirements? })` | Resume a paused run with resolved requirements. |
+| `respondToConfirmation(approve)` | Approve/reject pending tool confirmations, then continue. |
+| `submitUserInput(values)` | Provide values for pending input fields, then continue. |
+| `reset()` | Clear the transcript and start a new session. |
+| `setMessages(...)` | Replace the transcript (e.g. after restoring a session). |
+| `client` | The underlying `AgnoClient` for discovery/session calls. |
+
+---
+
+## Components
+
+All components are styled by `@agno-hq/chat-react/styles.css` (dark by default; add
+the `agno-light` class on a wrapper for light mode). Every piece is exported so
+you can compose your own layout.
+
+| Component | Purpose |
+|---|---|
+| `<AgnoChat>` | All-in-one widget: discovery, selector, chat, optional event log. |
+| `<ChatWindow chat={chat}>` | Full chat surface built from a `useAgnoChat` result. |
+| `<MessageList>` | Auto-scrolling transcript with live status + footer slot. |
+| `<Message>` | A single message: content, tools, reasoning, media, citations. |
+| `<ChatInput>` | Multiline input with file attach, send, and stop. |
+| `<ToolCalls>` | Collapsible tool-call cards (name, args, result, status). |
+| `<Reasoning>` | Collapsible reasoning-steps panel. |
+| `<Citations>` | References / source URLs. |
+| `<Multimedia>` | Images, video, and audio attachments. |
+| `<StatusIndicator>` | Animated "what is it doing now" line. |
+| `<EventLog>` | Developer feed of every raw run event. |
+| `<HumanInput>` | Human-in-the-loop panel (confirm / reject / input). |
+| `<EntitySelector>` | Dropdown of agents, teams, and workflows. |
+| `<SessionList>` | Sidebar of past sessions — click to load, trash to delete. |
+| `<Markdown>` | The built-in lightweight Markdown renderer. |
+
+### Bring your own Markdown
+
+The built-in renderer covers code blocks, inline code, bold/italic, links,
+headings and lists. For full GFM (tables, etc.), pass `renderMarkdown`:
+
+```tsx
+import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+
+<ChatWindow
+  chat={chat}
+  renderMarkdown={(c) => <ReactMarkdown remarkPlugins={[remarkGfm]}>{c}</ReactMarkdown>}
+/>
+```
+
+---
+
+## Human-in-the-loop
+
+When a run pauses for a tool confirmation or for user input, `status` becomes
+`'paused'` and `pendingRequirements` / the paused message's `tool_calls`
+describe what's needed. `<ChatWindow>` renders `<HumanInput>` automatically; to
+build your own UI, call:
+
+```tsx
+await chat.respondToConfirmation(true)        // approve pending tool calls
+await chat.respondToConfirmation(false)       // reject
+await chat.submitUserInput({ city: 'Lisbon' }) // fill input fields, then continue
+```
+
+Agents and teams resume via the `/continue` endpoint with resolved `tools`;
+workflows resume with `step_requirements`. The hook picks the right one based on
+the selected entity type.
+
+---
+
+## Session history
+
+The hook tracks past sessions for the selected entity:
+
+```tsx
+const chat = useAgnoChat({ baseUrl, entity })
+
+chat.sessions          // SessionEntry[]
+chat.sessionsLoading   // boolean
+await chat.refreshSessions()      // fetch the list
+await chat.loadSession(sessionId) // load a transcript into the chat
+await chat.deleteSession(sessionId)
+```
+
+Render them with `<SessionList>`:
+
+```tsx
+<SessionList
+  sessions={chat.sessions}
+  activeSessionId={chat.sessionId}
+  loading={chat.sessionsLoading}
+  onSelect={chat.loadSession}
+  onDelete={chat.deleteSession}
+  onNew={chat.reset}
+/>
+```
+
+The all-in-one widget shows this sidebar with `showSessions`:
+
+```tsx
+<AgnoChat baseUrl="http://localhost:7777" showSessions showEventLog />
+```
+
+---
+
+## Lower-level API
+
+```tsx
+import { AgnoClient, streamRun } from '@agno-hq/chat-react'
+
+const client = new AgnoClient({ baseUrl: 'http://localhost:7777', headers: { Authorization: 'Bearer …' } })
+
+await client.getEntities()                 // agents + teams + workflows
+await client.getSessions('agent', 'agno_assist')
+await client.getSessionRuns('agent', sessionId)   // rehydrate history
+await client.cancelRun('agent', 'agno_assist', runId)
+```
+
+`streamRun` is the raw streaming primitive (parses the wire format and emits
+normalised events) if you want to bypass the hook entirely.
+
+---
+
+## Running the example
+
+The `example/` folder is a Vite app demonstrating both the widget and the hook
+(with a live status panel + event log). It imports the library from source.
+
+```bash
+cd example
+npm install
+npm run dev
+```
+
+Then open the app, set your AgentOS URL (default `http://localhost:7777`), and
+pick an agent, team, or workflow.
+
+> Start an AgentOS first — see the Agno cookbooks under `cookbook/05_agent_os/`.
+
+### CORS
+
+The chat runs in the browser, so **your AgentOS must allow the page's origin**.
+The example dev server is pinned to port **5173** (`strictPort`), so add that
+origin when constructing AgentOS:
+
+```python
+AgentOS(..., cors_allowed_origins=["http://localhost:5173"])
+```
+
+A symptom of a CORS mismatch is an empty entity dropdown and a
+`Disallowed CORS origin` response to the preflight request.
+
+---
+
+## Notes
+
+- **Auth / headers** — pass `headers` (or a pre-built `client`) to send an
+  `Authorization` header on every request.
+- **Sessions** — `sessionId` is captured automatically on the first run. To
+  restore history, call `client.getSessionRuns(...)` and map runs into
+  `ChatMessage[]`, then `chat.setMessages(...)`.
+- **Wire format** — handles both AgentOS streaming shapes (the legacy flat event
+  objects and the `{ event, data }` SSE envelope).
+- **Dependencies** — the library itself depends only on React (peer). The
+  example additionally uses Vite.
+
+---
+
+## Local development
+
+```bash
+git clone https://github.com/agno-agi/agno-chat-react.git
+cd agno-chat-react
+npm install
+npm run typecheck          # tsc --noEmit
+npm run build              # tsup -> dist/ (ESM + CJS + .d.ts)
+```
+
+The published package is built with [tsup](https://tsup.egoist.dev) into
+`dist/` (ESM `index.js`, CommonJS `index.cjs`, type declarations, and
+`styles.css`). The `example/` app, however, resolves the library straight from
+`src/` via a Vite alias, so you can develop against live changes without
+rebuilding — see [Running the example](#running-the-example). `prepublishOnly`
+runs the typecheck and build automatically, so `npm publish` always ships a
+fresh `dist/`.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Agno