@standardagents/react 0.10.1-dev.616ec2e → 0.10.1-next.bbd142a

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