@standardagents/react 0.10.0 → 0.10.1-dev.616ec2e

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+React hooks and components for Standard Agents - connect to AI agent threads with real-time updates, send messages, manage files, and listen for custom events.
 
 ## Installation
 
@@ -16,41 +16,37 @@ yarn add @standardagents/react
 
 ```tsx
 import {
-  StandardAgentsProvider,
+  AgentBuilderProvider,
   ThreadProvider,
   useThread,
-  sendMessage,
 } from "@standardagents/react"
 
 function App() {
   return (
-    <StandardAgentsProvider config={{ endpoint: "https://your-api.com" }}>
+    <AgentBuilderProvider config={{ endpoint: "https://your-api.com" }}>
       <ThreadProvider threadId="thread-123">
         <ChatInterface />
       </ThreadProvider>
-    </StandardAgentsProvider>
+    </AgentBuilderProvider>
   )
 }
 
 function ChatInterface() {
-  // No thread ID needed - inherited from ThreadProvider context
-  const messages = useThread()
+  const { messages, sendMessage, status } = useThread()
 
   const handleSend = async (text: string) => {
-    await sendMessage("thread-123", {
-      role: "user",
-      content: text,
-    })
+    await sendMessage({ role: "user", content: text })
   }
 
   return (
     <div>
+      <p>Status: {status}</p>
       {messages.map((msg) => (
         <div key={msg.id}>
           <strong>{msg.role}:</strong> {msg.content}
         </div>
       ))}
-      <input onSubmit={(e) => handleSend(e.currentTarget.value)} />
+      <input onKeyDown={(e) => e.key === "Enter" && handleSend(e.currentTarget.value)} />
     </div>
   )
 }
@@ -69,292 +65,247 @@ All API requests and WebSocket connections will automatically include this token
 
 ## API Reference
 
-### `StandardAgentsProvider`
+### `AgentBuilderProvider`
 
 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`)
+- `config.endpoint: string` - The API endpoint URL
 
 ```tsx
-<StandardAgentsProvider config={{ endpoint: "https://api.example.com" }}>
+<AgentBuilderProvider config={{ endpoint: "https://api.example.com" }}>
   {children}
-</StandardAgentsProvider>
+</AgentBuilderProvider>
 ```
 
 ---
 
 ### `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`.
+Context provider that establishes a WebSocket connection to a specific thread. Must be nested inside `AgentBuilderProvider`.
 
 **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`)
+- `useWorkblocks?: boolean` - Transform tool calls into workblocks (default: `false`)
 - `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}>
+<AgentBuilderProvider config={{ endpoint: "https://api.example.com" }}>
+  <ThreadProvider threadId="thread-123" live={true}>
     <YourComponents />
   </ThreadProvider>
-</StandardAgentsProvider>
+</AgentBuilderProvider>
 ```
 
 ---
 
-### `useThread(options?)`
+### `useThread()`
 
-Hook to subscribe to thread messages. Must be used within a `ThreadProvider`.
+Hook to access the full thread context. Must be used within a `ThreadProvider`.
 
-**Parameters:**
-
-- `options?: UseThreadOptions` - Configuration options
-
-**Options:**
-
-- `useWorkblocks?: boolean` - Group tool calls into workblocks (default: `true`)
+**Returns:** `ThreadContextValue`
 
-**Returns:** `ThreadMessage[]` - Array of messages or workblocks
+- `threadId: string` - The thread ID
+- `messages: Message[]` - Array of messages
+- `workblocks: ThreadMessage[]` - Messages transformed to workblocks (if `useWorkblocks` is true)
+- `status: ConnectionStatus` - WebSocket connection status (`"connecting"` | `"connected"` | `"disconnected"` | `"reconnecting"`)
+- `loading: boolean` - Whether messages are loading (alias: `isLoading`)
+- `error: Error | null` - Any error that occurred
+- `options: ThreadProviderOptions` - Options passed to the provider
+- `sendMessage: (payload: SendMessagePayload) => Promise<Message>` - Send a message
+- `stopExecution: () => Promise<void>` - Stop current execution
+- `onEvent: <T>(eventType, listener) => () => void` - Subscribe to custom events (alias: `subscribeToEvent`)
+- `files: ThreadFile[]` - All files (pending + committed)
+- `addFiles: (files: File[] | FileList) => void` - Upload files
+- `removeFile: (id: string) => void` - Remove a pending file
+- `getFileUrl: (file: ThreadFile) => string` - Get file URL
+- `getThumbnailUrl: (file: ThreadFile) => string` - Get thumbnail URL
+- `getPreviewUrl: (file: ThreadFile) => string | null` - Get preview URL
 
 **Example:**
 
 ```tsx
-function ThreadView() {
-  // Thread ID inherited from ThreadProvider context
-  const messages = useThread()
+function ChatView() {
+  const {
+    messages,
+    sendMessage,
+    stopExecution,
+    status,
+    isLoading,
+    files,
+    addFiles,
+  } = 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>
-  )
-}
+      <p>Status: {status}</p>
+      {isLoading && <p>Loading...</p>}
 
-// 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`.
+      {messages.map((msg) => (
+        <div key={msg.id}>
+          <strong>{msg.role}:</strong> {msg.content}
+        </div>
+      ))}
 
-**Returns:** `string` - The thread ID
+      <input
+        type="file"
+        multiple
+        onChange={(e) => e.target.files && addFiles(e.target.files)}
+      />
 
-**Example:**
+      <div>
+        {files.map((file) => (
+          <span key={file.id}>{file.name} ({file.status})</span>
+        ))}
+      </div>
 
-```tsx
-function CurrentThreadId() {
-  const threadId = useThreadId()
-  return <span>Thread: {threadId}</span>
+      <button onClick={() => sendMessage({ role: "user", content: "Hello!" })}>Send</button>
+      <button onClick={stopExecution}>Stop</button>
+    </div>
+  )
 }
 ```
 
 ---
 
-### `sendMessage(threadId, payload, options?)`
+### `useThreadEvent<T>(eventType)`
 
-Send a message to a thread. This is a standalone function that works outside of React components.
+Hook to listen for custom events emitted by the agent. Must be used within a `ThreadProvider`.
 
 **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
+- `eventType: string` - The custom event type to listen for
 
-**Returns:** `Promise<Message>` - The created message
+**Returns:** `T | null` - The latest event value, or `null` if no event received yet
 
 **Example:**
 
 ```tsx
-import { sendMessage, useThreadId } from "@standardagents/react"
-
-function SendButton() {
-  const threadId = useThreadId()
+function TodoProgress() {
+  const todos = useThreadEvent<{ todos: string[]; completed: number }>("todo-updated")
 
-  const handleSend = async () => {
-    await sendMessage(threadId, {
-      role: "user",
-      content: "Hello, agent!",
-    })
-  }
+  if (!todos) return <div>Waiting for updates...</div>
 
-  return <button onClick={handleSend}>Send</button>
+  return (
+    <div>
+      <p>Progress: {todos.completed} / {todos.todos.length}</p>
+      <ul>
+        {todos.todos.map((todo, i) => (
+          <li key={i}>{todo}</li>
+        ))}
+      </ul>
+    </div>
+  )
 }
-
-// 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?)`
+### `onThreadEvent<T>(eventType, callback)`
 
-Cancel an in-flight thread execution.
+Hook to listen for custom events with a callback. Must be used within a `ThreadProvider`.
 
 **Parameters:**
 
-- `threadId: string` - The thread ID
-- `options?: { endpoint?: string }` - Override endpoint
-
-**Returns:** `Promise<void>`
+- `eventType: string` - The custom event type to listen for
+- `callback: (data: T) => void` - Called when event is received
 
 **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)
-    }
-  }
+function Notifications() {
+  onThreadEvent<{ message: string }>("notification", (data) => {
+    alert(data.message)
+  })
 
-  return (
-    <button onClick={handleStop} disabled={stopping}>
-      {stopping ? "Stopping..." : "Stop Execution"}
-    </button>
-  )
+  return null
 }
 ```
 
 ---
 
-### `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:**
+## File Management
 
-- `T` - The expected shape of the event data
-
-**Returns:** `T | null` - The latest event value, or `null` if no event received yet
-
-**Example:**
+The `useThread()` hook provides file management capabilities:
 
 ```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>
+function FileUploader() {
+  const { files, addFiles, removeFile, getFileUrl, getPreviewUrl } = useThread()
 
   return (
     <div>
-      <p>
-        Progress: {todos.completed} / {todos.todos.length}
-      </p>
-      <ul>
-        {todos.todos.map((todo, i) => (
-          <li key={i}>{todo}</li>
-        ))}
-      </ul>
+      <input
+        type="file"
+        multiple
+        accept="image/*,.pdf,.txt"
+        onChange={(e) => e.target.files && addFiles(e.target.files)}
+      />
+
+      {files.map((file) => (
+        <div key={file.id}>
+          {file.isImage && file.status !== 'uploading' && (
+            <img src={getPreviewUrl(file) || ''} alt={file.name} />
+          )}
+          <span>{file.name}</span>
+          <span>{file.status}</span>
+          {file.status === 'uploading' && <span>Uploading...</span>}
+          {file.status === 'error' && <span>Error: {file.error}</span>}
+          {file.status !== 'committed' && (
+            <button onClick={() => removeFile(file.id)}>Remove</button>
+          )}
+        </div>
+      ))}
     </div>
   )
 }
 ```
 
-**Backend Event Emission:**
+### File States
 
-```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,
-})
-```
+- `uploading` - File is being uploaded
+- `ready` - Upload complete, file ready to attach to message
+- `committed` - File is attached to a sent message
+- `error` - Upload failed
 
 ---
 
-## Message Types
-
-### Regular Message
+## Types
 
 ```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
+  created_at: number
+  attachments?: string // JSON array of AttachmentRef
 }
-```
-
-### 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 SendMessagePayload {
+  role: "user" | "assistant" | "system"
+  content: string
+  silent?: boolean
+  attachments?: string[]  // Paths of files to attach
 }
 
-interface WorkItem {
+interface ThreadFile {
   id: string
-  type: "tool_call" | "tool_result"
   name: string
-  input?: string
-  content?: string
-  status: "success" | "error" | null
-  tool_call_id?: string
+  mimeType: string
+  size: number
+  isImage: boolean
+  status: "uploading" | "ready" | "committed" | "error"
+  error?: string
+  path?: string
+  localPreviewUrl: string | null
 }
+
+type ConnectionStatus = "connecting" | "connected" | "disconnected" | "reconnecting"
 ```
 
 ---
@@ -362,74 +313,53 @@ interface WorkItem {
 ## Complete Example
 
 ```tsx
+import { useState, useEffect } from "react"
 import {
-  StandardAgentsProvider,
+  AgentBuilderProvider,
   ThreadProvider,
   useThread,
-  useThreadId,
-  sendMessage,
-  stopThread,
-  onThreadEvent,
+  useThreadEvent,
 } 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}>
+    <AgentBuilderProvider config={{ endpoint: "https://api.example.com" }}>
+      <ThreadProvider threadId="thread-123">
         <AgentChat />
       </ThreadProvider>
-    </StandardAgentsProvider>
+    </AgentBuilderProvider>
   )
 }
 
 function AgentChat() {
   const [input, setInput] = useState("")
-  const [isExecuting, setIsExecuting] = useState(false)
 
-  // Get thread ID from context
-  const threadId = useThreadId()
+  const {
+    messages,
+    sendMessage,
+    stopExecution,
+    status,
+    isLoading,
+    files,
+    addFiles,
+    removeFile,
+    getPreviewUrl,
+  } = useThread()
 
-  // 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 progress = useThreadEvent<{ 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)
-    }
+    await sendMessage({ role: "user", content: input })
+    setInput("")
   }
 
   return (
     <div>
-      {/* Progress indicator */}
       {progress && (
         <div>
           <p>{progress.step}</p>
@@ -437,43 +367,39 @@ function AgentChat() {
         </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>
+      {isLoading && <p>Loading messages...</p>}
+
+      {messages.map((msg) => (
+        <div key={msg.id}>
+          <strong>{msg.role}:</strong> {msg.content}
+        </div>
+      ))}
+
+      <input
+        type="file"
+        multiple
+        onChange={(e) => e.target.files && addFiles(e.target.files)}
+      />
+
+      {files.filter(f => f.status !== 'committed').map((file) => (
+        <div key={file.id}>
+          {file.isImage && getPreviewUrl(file) && (
+            <img src={getPreviewUrl(file)!} alt={file.name} width={50} />
+          )}
+          <span>{file.name} ({file.status})</span>
+          <button onClick={() => removeFile(file.id)}>x</button>
+        </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>}
+        <button onClick={handleSend}>Send</button>
+        <button onClick={stopExecution}>Stop</button>
+        <span>Status: {status}</span>
       </div>
     </div>
   )
@@ -484,61 +410,14 @@ function AgentChat() {
 
 ## TypeScript Support
 
-The package is written in TypeScript and includes full type definitions.
+The package includes full TypeScript definitions:
 
 ```tsx
 import type {
   Message,
-  WorkMessage,
-  ThreadMessage,
   SendMessagePayload,
-  UseThreadOptions,
-  ThreadProviderOptions,
+  ThreadFile,
+  ConnectionStatus,
+  ThreadContextValue,
 } 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
-```