@standardagents/react 0.8.1

package/README.md

@@ -0,0 +1,544 @@
+# @standardagents/react
+
+React hooks and components for Standard Agents - connect to AI agent threads with real-time updates, send messages, and listen for custom events.
+
+## Installation
+
+```bash
+npm install @standardagents/react
+# or
+pnpm add @standardagents/react
+# or
+yarn add @standardagents/react
+```
+
+## Quick Start
+
+```tsx
+import {
+  StandardAgentsProvider,
+  ThreadProvider,
+  useThread,
+  sendMessage,
+} from "@standardagents/react"
+
+function App() {
+  return (
+    <StandardAgentsProvider config={{ endpoint: "https://your-api.com" }}>
+      <ThreadProvider threadId="thread-123">
+        <ChatInterface />
+      </ThreadProvider>
+    </StandardAgentsProvider>
+  )
+}
+
+function ChatInterface() {
+  // No thread ID needed - inherited from ThreadProvider context
+  const messages = useThread()
+
+  const handleSend = async (text: string) => {
+    await sendMessage("thread-123", {
+      role: "user",
+      content: text,
+    })
+  }
+
+  return (
+    <div>
+      {messages.map((msg) => (
+        <div key={msg.id}>
+          <strong>{msg.role}:</strong> {msg.content}
+        </div>
+      ))}
+      <input onSubmit={(e) => handleSend(e.currentTarget.value)} />
+    </div>
+  )
+}
+```
+
+## Authentication
+
+The package reads the authentication token from `localStorage` using the key `standardagents_auth_token`:
+
+```tsx
+// Set the token before using the hooks
+localStorage.setItem("standardagents_auth_token", "your-token-here")
+```
+
+All API requests and WebSocket connections will automatically include this token.
+
+## API Reference
+
+### `StandardAgentsProvider`
+
+Context provider that configures the Standard Agents client for all child components.
+
+**Props:**
+
+- `config.endpoint: string` - The API endpoint URL (e.g., `https://api.example.com`)
+
+```tsx
+<StandardAgentsProvider config={{ endpoint: "https://api.example.com" }}>
+  {children}
+</StandardAgentsProvider>
+```
+
+---
+
+### `ThreadProvider`
+
+Context provider that establishes a WebSocket connection to a specific thread. Must be nested inside `StandardAgentsProvider`. Provides thread context to child hooks like `useThread` and `onThreadEvent`.
+
+**Props:**
+
+- `threadId: string` - The thread ID to connect to
+- `preload?: boolean` - Fetch existing messages on mount (default: `true`)
+- `live?: boolean` - Enable WebSocket for real-time updates (default: `true`)
+- `depth?: number` - Message depth level for nested conversations (default: `0`)
+- `includeSilent?: boolean` - Include silent messages (default: `false`)
+- `endpoint?: string` - Override the endpoint from context
+
+```tsx
+<StandardAgentsProvider config={{ endpoint: "https://api.example.com" }}>
+  <ThreadProvider threadId="thread-123" live={true} depth={0}>
+    <YourComponents />
+  </ThreadProvider>
+</StandardAgentsProvider>
+```
+
+---
+
+### `useThread(options?)`
+
+Hook to subscribe to thread messages. Must be used within a `ThreadProvider`.
+
+**Parameters:**
+
+- `options?: UseThreadOptions` - Configuration options
+
+**Options:**
+
+- `useWorkblocks?: boolean` - Group tool calls into workblocks (default: `true`)
+
+**Returns:** `ThreadMessage[]` - Array of messages or workblocks
+
+**Example:**
+
+```tsx
+function ThreadView() {
+  // Thread ID inherited from ThreadProvider context
+  const messages = useThread()
+
+  return (
+    <div>
+      {messages.map((item) => {
+        if (item.type === "workblock") {
+          return <WorkblockView key={item.id} workblock={item} />
+        }
+        return <MessageView key={item.id} message={item} />
+      })}
+    </div>
+  )
+}
+
+// Disable workblocks transformation
+function RawMessagesView() {
+  const messages = useThread({ useWorkblocks: false })
+  // Returns raw messages without workblock grouping
+}
+```
+
+---
+
+### `useThreadId()`
+
+Hook to get the current thread ID from context. Must be used within a `ThreadProvider`.
+
+**Returns:** `string` - The thread ID
+
+**Example:**
+
+```tsx
+function CurrentThreadId() {
+  const threadId = useThreadId()
+  return <span>Thread: {threadId}</span>
+}
+```
+
+---
+
+### `sendMessage(threadId, payload, options?)`
+
+Send a message to a thread. This is a standalone function that works outside of React components.
+
+**Parameters:**
+
+- `threadId: string` - The thread ID
+- `payload: SendMessagePayload` - The message to send
+  - `role: 'user' | 'assistant'` - Message role
+  - `content: string | null` - Message content
+  - `silent?: boolean` - Silent message (not shown to user, default: `false`)
+- `options?: { endpoint?: string }` - Override endpoint
+
+**Returns:** `Promise<Message>` - The created message
+
+**Example:**
+
+```tsx
+import { sendMessage, useThreadId } from "@standardagents/react"
+
+function SendButton() {
+  const threadId = useThreadId()
+
+  const handleSend = async () => {
+    await sendMessage(threadId, {
+      role: "user",
+      content: "Hello, agent!",
+    })
+  }
+
+  return <button onClick={handleSend}>Send</button>
+}
+
+// Send a silent message (for context injection)
+await sendMessage("thread-123", {
+  role: "user",
+  content: "Additional context",
+  silent: true,
+})
+
+// Send an assistant message (for injecting responses)
+await sendMessage("thread-123", {
+  role: "assistant",
+  content: "Custom assistant response",
+})
+```
+
+---
+
+### `stopThread(threadId, options?)`
+
+Cancel an in-flight thread execution.
+
+**Parameters:**
+
+- `threadId: string` - The thread ID
+- `options?: { endpoint?: string }` - Override endpoint
+
+**Returns:** `Promise<void>`
+
+**Example:**
+
+```tsx
+import { stopThread, useThreadId } from "@standardagents/react"
+
+function StopButton() {
+  const threadId = useThreadId()
+  const [stopping, setStopping] = useState(false)
+
+  const handleStop = async () => {
+    setStopping(true)
+    try {
+      await stopThread(threadId)
+    } catch (error) {
+      console.error("Failed to stop thread:", error)
+    } finally {
+      setStopping(false)
+    }
+  }
+
+  return (
+    <button onClick={handleStop} disabled={stopping}>
+      {stopping ? "Stopping..." : "Stop Execution"}
+    </button>
+  )
+}
+```
+
+---
+
+### `onThreadEvent<T>(eventType)`
+
+Hook to listen for custom events emitted by the agent via WebSocket. Must be used within a `ThreadProvider`.
+
+**Parameters:**
+
+- `eventType: string` - The custom event type to listen for
+
+**Type Parameter:**
+
+- `T` - The expected shape of the event data
+
+**Returns:** `T | null` - The latest event value, or `null` if no event received yet
+
+**Example:**
+
+```tsx
+import { onThreadEvent } from "@standardagents/react"
+
+function TodoProgress() {
+  // Thread ID inherited from ThreadProvider context
+  const todos = onThreadEvent<{ todos: string[]; completed: number }>(
+    "todo-updated"
+  )
+
+  if (!todos) return <div>Waiting for updates...</div>
+
+  return (
+    <div>
+      <p>
+        Progress: {todos.completed} / {todos.todos.length}
+      </p>
+      <ul>
+        {todos.todos.map((todo, i) => (
+          <li key={i}>{todo}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+**Backend Event Emission:**
+
+```typescript
+// In your agent's tool or hook (using @standardagents/builder)
+import { emitThreadEvent } from "@standardagents/builder"
+
+// Emit an event to all connected clients
+emitThreadEvent(flow, "todo-updated", {
+  todos: ["Task 1", "Task 2"],
+  completed: 1,
+})
+```
+
+---
+
+## Message Types
+
+### Regular Message
+
+```typescript
+interface Message {
+  id: string
+  role: "user" | "assistant" | "system" | "tool"
+  content: string | null
+  created_at: number // microseconds
+  reasoning_content?: string | null
+  silent?: boolean
+  depth?: number
+}
+```
+
+### Workblock
+
+When `useWorkblocks: true`, tool calls and results are grouped:
+
+```typescript
+interface WorkMessage {
+  type: "workblock"
+  id: string
+  content: string | null
+  reasoning_content?: string | null
+  status: "pending" | "completed"
+  workItems: WorkItem[]
+  created_at: number
+  depth?: number
+}
+
+interface WorkItem {
+  id: string
+  type: "tool_call" | "tool_result"
+  name: string
+  input?: string
+  content?: string
+  status: "success" | "error" | null
+  tool_call_id?: string
+}
+```
+
+---
+
+## Complete Example
+
+```tsx
+import {
+  StandardAgentsProvider,
+  ThreadProvider,
+  useThread,
+  useThreadId,
+  sendMessage,
+  stopThread,
+  onThreadEvent,
+} from "@standardagents/react"
+import { useState, useEffect } from "react"
+
+function App() {
+  // Set auth token
+  useEffect(() => {
+    localStorage.setItem("standardagents_auth_token", "your-token")
+  }, [])
+
+  return (
+    <StandardAgentsProvider config={{ endpoint: "https://api.example.com" }}>
+      <ThreadProvider threadId="thread-123" live={true}>
+        <AgentChat />
+      </ThreadProvider>
+    </StandardAgentsProvider>
+  )
+}
+
+function AgentChat() {
+  const [input, setInput] = useState("")
+  const [isExecuting, setIsExecuting] = useState(false)
+
+  // Get thread ID from context
+  const threadId = useThreadId()
+
+  // Subscribe to thread messages (no threadId needed)
+  const messages = useThread({ useWorkblocks: true })
+
+  // Listen for custom progress events (no threadId needed)
+  const progress = onThreadEvent<{ step: string; percent: number }>("progress")
+
+  const handleSend = async () => {
+    if (!input.trim()) return
+
+    setIsExecuting(true)
+    try {
+      await sendMessage(threadId, {
+        role: "user",
+        content: input,
+      })
+      setInput("")
+    } catch (error) {
+      console.error("Failed to send message:", error)
+    } finally {
+      setIsExecuting(false)
+    }
+  }
+
+  const handleStop = async () => {
+    try {
+      await stopThread(threadId)
+      setIsExecuting(false)
+    } catch (error) {
+      console.error("Failed to stop thread:", error)
+    }
+  }
+
+  return (
+    <div>
+      {/* Progress indicator */}
+      {progress && (
+        <div>
+          <p>{progress.step}</p>
+          <progress value={progress.percent} max={100} />
+        </div>
+      )}
+
+      {/* Message list */}
+      <div>
+        {messages.map((item) => {
+          if (item.type === "workblock") {
+            return (
+              <div key={item.id}>
+                <p>Executing tools...</p>
+                {item.workItems.map((work) => (
+                  <div key={work.id}>
+                    {work.type === "tool_call" && `🔧 ${work.name}`}
+                    {work.type === "tool_result" && `✅ ${work.status}`}
+                  </div>
+                ))}
+              </div>
+            )
+          }
+
+          return (
+            <div key={item.id}>
+              <strong>{item.role}:</strong> {item.content}
+            </div>
+          )
+        })}
+      </div>
+
+      {/* Input */}
+      <div>
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          onKeyDown={(e) => e.key === "Enter" && handleSend()}
+          disabled={isExecuting}
+        />
+        <button onClick={handleSend} disabled={isExecuting}>
+          Send
+        </button>
+        {isExecuting && <button onClick={handleStop}>Stop</button>}
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## TypeScript Support
+
+The package is written in TypeScript and includes full type definitions.
+
+```tsx
+import type {
+  Message,
+  WorkMessage,
+  ThreadMessage,
+  SendMessagePayload,
+  UseThreadOptions,
+  ThreadProviderOptions,
+} from "@standardagents/react"
+```
+
+---
+
+## Local Development
+
+### Building the Package
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build package
+pnpm build
+
+# Watch mode (rebuilds on changes)
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Run tests
+pnpm test
+```
+
+### Linking for Local Development
+
+Using `file:` protocol in your app's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@standardagents/react": "file:../path/to/packages/react"
+  }
+}
+```
+
+Or using `pnpm link`:
+
+```bash
+# In this package
+cd packages/react
+pnpm link --global
+
+# In your app
+pnpm link --global @standardagents/react
+```