bs-agent 0.0.9 → 0.0.12

package/README.md

@@ -1,420 +1,443 @@
 # @buildship/agent
 
-A React library for integrating BuildShip AI agents into your frontend
-applications with support for streaming responses, file handling, and
-client-side widgets.
-
-## Features
-
-- **Real-time Streaming**: Built on Server-Sent Events (SSE) for live agent
-  responses
-- **Session Management**: Automatic conversation persistence with localStorage
-- **File Support**: Upload and send files to your agents
-- **Client Tools/Widgets**: Render interactive components from agent responses
-- **TypeScript**: Full type safety with comprehensive TypeScript definitions
-- **Multi-Agent**: Support for multiple agents in a single application
-
-## Installation
+A type-safe TypeScript SDK for [BuildShip](https://buildship.com) agents with
+streaming support.
+
+- 🔄 **Streaming-first** — real-time text, reasoning, tool calls & handoffs via
+  SSE
+- 🧩 **Client tools** — headless handlers, interactive widgets, pause/resume
+- ⚛️ **React bindings** — hooks & context for chat UIs with session management
+- 💬 **Multi-turn** — session-based conversations with persistent history
+- 🛑 **Abort** — cancel any streaming request mid-flight
+- 🐛 **Debug data** — structured debug entries for every tool call, reasoning
+  step & handoff
+- 📦 **Zero extra deps** — native `fetch` + `ReadableStream`, only `zod` as a
+  dependency
+
+## Install
 
 ```bash
 npm install @buildship/agent
 ```
 
+The package exposes two entry points:
+
+```ts
+import { ... } from "@buildship/agent/core";   // Vanilla JS/TS — works anywhere
+import { ... } from "@buildship/agent/react";   // React hooks, context & components
+```
+
+---
+
+# Core (`@buildship/agent/core`)
+
+The core module provides a class-based API that works in any JavaScript
+environment — Node.js, browser, Edge Runtime, etc.
+
 ## Quick Start
 
-```tsx
-import { AgentContextProvider, useAgentContext } from "@buildship/agent";
+```ts
+import { BuildShipAgent, z } from "@buildship/agent/core";
 
-// 1. Wrap your app with the provider
-function App() {
-  return (
-    <AgentContextProvider>
-      <YourApp />
-    </AgentContextProvider>
-  );
-}
+const agent = new BuildShipAgent({
+  agentId: "YOUR_AGENT_ID",
+  accessKey: "YOUR_ACCESS_KEY", // optional
+  baseUrl: "https://your-project.buildship.run",
+});
 
-// 2. Use the agent in your components
-function ChatComponent() {
-  const agent = useAgentContext(
-    "your-agent-id",
-    "https://your-agent-url.com",
-    "your-access-key",
-  );
+// Simple one-shot
+const session = await agent.execute("Hello!", {
+  onText: (text) => process.stdout.write(text),
+  onComplete: (fullText) => console.log("\nDone:", fullText),
+  onError: (err) => console.error(err),
+});
+```
 
-  const handleSend = () => {
-    agent.handleSend("Hello, agent!");
-  };
+## Multi-Turn Conversations
 
-  return (
-    <div>
-      {agent.messages.map((msg, idx) => (
-        <div key={idx}>
-          <strong>{msg.role}:</strong> {msg.content}
-        </div>
-      ))}
-      <button onClick={handleSend} disabled={agent.inProgress}>
-        Send Message
-      </button>
-    </div>
-  );
-}
+```ts
+// First message returns a session
+const session = await agent.execute("What is 2 + 2?", {
+  onText: (t) => process.stdout.write(t),
+  onComplete: () => console.log(),
+});
+
+// Continue with the same session ID
+const continued = agent.session(session.getSessionId());
+await continued.execute("Now multiply that by 3", {
+  onText: (t) => process.stdout.write(t),
+  onComplete: () => console.log(),
+});
 ```
 
-## Setup
+## Client Tools
 
-### AgentContextProvider
+Define tools the agent can invoke on the client side. Use **Zod schemas** for
+type-safe parameter definitions:
 
-The `AgentContextProvider` must wrap your application to enable agent
-functionality. It manages:
+```ts
+import { BuildShipAgent, z } from "@buildship/agent/core";
 
-- Global session state across all agents
-- Automatic localStorage persistence
-- Agent runner registry
+const agent = new BuildShipAgent({ agentId: "..." });
 
-```tsx
-import { AgentContextProvider } from "@buildship/agent";
+// Fire-and-forget tool
+agent.registerClientTool({
+  name: "show_notification",
+  description: "Display a notification to the user",
+  parameters: z.object({
+    title: z.string().describe("Notification title"),
+    message: z.string().describe("Notification body"),
+  }),
+  handler: (args) => {
+    showNotification(args.title, args.message);
+  },
+});
 
-function App() {
-  return (
-    <AgentContextProvider>{/* Your app components */}</AgentContextProvider>
-  );
-}
+// Blocking tool — agent pauses until result is returned
+agent.registerClientTool({
+  name: "get_location",
+  description: "Get the user's current location",
+  parameters: z.object({}),
+  await: true,
+  handler: async () => {
+    const pos = await navigator.geolocation.getCurrentPosition();
+    return { lat: pos.coords.latitude, lng: pos.coords.longitude };
+  },
+});
 ```
 
-## Basic Usage
+### Pause & Resume (Manual)
 
-### Using the Agent Hook
+For blocking tools without a handler, the agent pauses and you resume manually:
 
-The `useAgentContext` hook is the primary interface for interacting with agents:
+```ts
+agent.registerClientTool({
+  name: "confirm_action",
+  description: "Ask the user to confirm an action",
+  parameters: z.object({
+    action: z.string().describe("The action to confirm"),
+  }),
+  await: true,
+  // No handler — you handle it manually
+});
 
-```tsx
-import { useAgentContext } from "@buildship/agent";
+const session = await agent.execute("Delete my account", {
+  onText: (t) => process.stdout.write(t),
+  onPaused: (toolName, args) => {
+    console.log(`Agent paused for: ${toolName}`, args);
+  },
+});
 
-function AgentChat() {
-  const agent = useAgentContext(
-    "my-agent-id", // Unique identifier for your agent
-    "https://agent-url.com", // Your agent's endpoint URL
-    "your-access-key", // Access key for authenticated requests (sent as Bearer token)
+if (session.isPaused()) {
+  const tool = session.getPausedTool();
+  // ... show confirmation UI, then resume:
+  await session.resume(
+    { confirmed: true },
+    {
+      onText: (t) => process.stdout.write(t),
+    },
   );
+}
+```
 
-  // Send a message
-  const sendMessage = async () => {
-    await agent.handleSend("What's the weather today?");
-  };
+## Abort
 
-  // Display messages
-  return (
-    <div>
-      {agent.messages.map((message, idx) => (
-        <div key={idx}>
-          <strong>{message.role === "user" ? "You" : "Agent"}:</strong>
-          <p>{message.content}</p>
-        </div>
-      ))}
+```ts
+const session = agent.session(sessionId);
 
-      {agent.inProgress && <div>Agent is thinking...</div>}
+session.execute("Write a long essay...", {
+  onText: (text) => {
+    process.stdout.write(text);
+    if (userCancelled) session.abort();
+  },
+});
+```
 
-      <button onClick={sendMessage} disabled={agent.inProgress}>
-        Send
-      </button>
-    </div>
-  );
+## Stream Callbacks
+
+```ts
+interface StreamCallbacks {
+  /** Called for each text chunk from the agent. */
+  onText?: (text: string) => void;
+  /** Called for each reasoning chunk (models with chain-of-thought). */
+  onReasoning?: (delta: string, index: number) => void;
+  /** Called when control is handed off to a sub-agent. */
+  onAgentHandoff?: (agentName: string) => void;
+  /** Called when a tool execution starts. */
+  onToolStart?: (toolName: string, toolType: ToolType) => void;
+  /** Called when a tool execution completes. */
+  onToolEnd?: (toolName: string, result?: any, error?: string) => void;
+  /** Called when agent pauses for a blocking client tool. */
+  onPaused?: (toolName: string, args: any) => void;
+  /** Called when the stream completes successfully. */
+  onComplete?: (fullText: string) => void;
+  /** Called if an error occurs during streaming. */
+  onError?: (error: Error) => void;
+  /** Called for every raw SSE event. Useful for debug panels. */
+  onEvent?: (event: StreamEvent) => void;
 }
 ```
 
-### AgentRunner API
+## Core API Reference
 
-The `useAgentContext` hook returns an `AgentRunner` object with:
+### `BuildShipAgent`
 
-| Property               | Type                            | Description                               |
-| ---------------------- | ------------------------------- | ----------------------------------------- |
-| `messages`             | `Message[]`                     | Array of conversation messages            |
-| `inProgress`           | `boolean`                       | Whether the agent is currently processing |
-| `sessionId`            | `string`                        | Current conversation session ID           |
-| `sessions`             | `Session[]`                     | All sessions for this agent               |
-| `debugData`            | `Record<string, DebugDataType>` | Debug information indexed by executionId  |
-| `handleSend`           | `Function`                      | Send a message to the agent               |
-| `switchSession`        | `Function`                      | Switch to a different session             |
-| `deleteSession`        | `Function`                      | Delete a session                          |
-| `addOptimisticMessage` | `Function`                      | Add message to UI without sending         |
-| `abort`                | `Function`                      | Cancel current agent execution            |
+| Method                                  | Description                                                |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `execute(message, callbacks, context?)` | Start a new conversation. Returns `AgentSession`.          |
+| `session(sessionId)`                    | Continue an existing conversation. Returns `AgentSession`. |
+| `registerClientTool(tool)`              | Register a client-side tool.                               |
+| `unregisterClientTool(name)`            | Remove a registered tool.                                  |
 
-### Session Management
+### `AgentSession`
 
-```tsx
-function SessionList() {
-  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+| Method                                  | Description                                          |
+| --------------------------------------- | ---------------------------------------------------- |
+| `execute(message, callbacks, context?)` | Send a message in this session.                      |
+| `resume(result, callbacks)`             | Resume after a blocking tool pause.                  |
+| `isPaused()`                            | Check if waiting for a tool result.                  |
+| `getPausedTool()`                       | Get paused tool info (`{ callId, toolName, args }`). |
+| `getSessionId()`                        | Get the session ID.                                  |
+| `abort()`                               | Cancel the current stream.                           |
 
-  return (
-    <div>
-      {agent.sessions.map((session) => (
-        <div key={session.id}>
-          <button onClick={() => agent.switchSession(session.id)}>
-            {session.name || "Untitled Session"}
-          </button>
-          <button onClick={() => agent.deleteSession(session.id)}>
-            Delete
-          </button>
-        </div>
-      ))}
+### Stream Events
 
-      {/* Create new session */}
-      <button onClick={() => agent.switchSession()}>New Session</button>
-    </div>
-  );
-}
-```
+All events share a `meta` object with `executionId` and `sequence`.
 
-## File Handling
+| Event Type        | Description                        | Data                                                              |
+| ----------------- | ---------------------------------- | ----------------------------------------------------------------- |
+| `text_delta`      | Text chunk from the agent          | `string`                                                          |
+| `reasoning_delta` | Chain-of-thought reasoning chunk   | `{ delta: string, index: number }`                                |
+| `tool_call_start` | A tool execution started           | `{ callId, toolName, toolType, inputs?, serverName?, paused? }`   |
+| `tool_call_end`   | A tool execution completed         | `{ callId, toolName, toolType, result?, error?, executionTime? }` |
+| `agent_handoff`   | Control transferred to a sub-agent | `{ agentName: string }`                                           |
 
-To send files to your agent:
+### Tool Types
 
-### 1. Upload Files to Storage
+```ts
+type ToolType = "flow" | "node" | "mcp" | "client" | "builtin" | "agent";
+```
 
-First, upload files to a publicly accessible URL (e.g., Firebase Storage, AWS
-S3):
+---
 
-```tsx
-async function uploadFiles(files: File[]): Promise<Record<string, string>> {
-  // Upload to your storage provider
-  const fileMap: Record<string, string> = {};
+# React (`@buildship/agent/react`)
 
-  for (const file of files) {
-    const url = await uploadToStorage(file); // Your upload logic
-    const fileId = file.name.replace(/[^a-zA-Z0-9]/g, "_").toLowerCase();
-    fileMap[fileId] = url;
-  }
+The React module provides hooks, context providers, and components for building
+chat UIs with full session management, client tool support, and debug panels.
 
-  return fileMap;
-}
-```
+## Setup
 
-### 2. Send Files with Message
+Wrap your app (or the chat area) with `AgentContextProvider`:
 
 ```tsx
-function FileUpload() {
-  const agent = useAgentContext("agent-id", "agent-url", "access-key");
-  const [files, setFiles] = useState<File[]>([]);
-
-  const handleSendWithFiles = async () => {
-    // Upload files and get URL mapping
-    const fileMap = await uploadFiles(files);
-
-    // Create input with file references
-    const fileIds = Object.keys(fileMap).join(", ");
-    const input = `Analyze these files: ${fileIds}`;
-
-    // Send to agent with file context
-    await agent.handleSend(input, {
-      context: {
-        mapped_file_ids_with_url: fileMap,
-      },
-    });
-  };
+import { AgentContextProvider } from "@buildship/agent/react";
 
+function App() {
   return (
-    <div>
-      <input
-        type="file"
-        multiple
-        onChange={(e) => setFiles(Array.from(e.target.files || []))}
-      />
-      <button onClick={handleSendWithFiles}>Send with Files</button>
-    </div>
+    <AgentContextProvider>
+      <ChatPage />
+    </AgentContextProvider>
   );
 }
 ```
 
-### File Context Structure
+## `useAgent` Hook
 
-```typescript
-{
-  context: {
-    mapped_file_ids_with_url: {
-      "file_name_pdf": "https://storage.url/file1.pdf",
-      "image_png": "https://storage.url/image.png"
-    }
-  }
-}
-```
-
-## Client Tools / Widgets
-
-Client tools allow your agent to render interactive widgets directly in the chat
-interface.
-
-### 1. Define Tool Configuration
-
-Create tool configurations with Zod schemas:
+The main hook for interacting with an agent. Manages messages, streaming,
+sessions, and debug data.
 
 ```tsx
-import { z } from "zod";
-
-export const chartToolConfig = {
-  name: "render_chart",
-  description: "Renders a bar chart with the provided data",
-  schema: z.object({
-    title: z.string().describe("Chart title"),
-    data: z
-      .array(
-        z.object({
-          label: z.string(),
-          value: z.number(),
-        }),
-      )
-      .describe("Data points for the chart"),
-  }),
-};
+import { useAgent } from "@buildship/agent/react";
+
+function ChatPage() {
+  const {
+    messages, // Message[] — full conversation history
+    inProgress, // boolean — true while streaming
+    handleSend, // (input, options?) => Promise — send a message
+    resumeTool, // (callId, result) => Promise — resume a paused tool
+    abort, // () => void — cancel the current stream
+    sessionId, // string — current session ID
+    sessions, // Session[] — all sessions for this agent
+    switchSession, // (sessionId?) => void — switch to a session (or create new)
+    deleteSession, // (sessionId) => void — delete a session
+    addOptimisticMessage, // (input) => void — add a user message immediately
+    debugData, // Record<string, DebugDataType> — debug entries by execution ID
+  } = useAgent(
+    "agent-id",
+    "https://your-project.buildship.run/executeAgent/AGENT_ID",
+    "access-key",
+  );
 
-// Create your widget component
-export function ChartWidget({ title, data }) {
   return (
     <div>
-      <h3>{title}</h3>
-      {/* Your chart rendering logic */}
+      {messages.map((msg, i) => (
+        <div key={i} className={msg.role}>
+          {msg.content}
+        </div>
+      ))}
+
+      <button onClick={() => handleSend("Hello!")} disabled={inProgress}>
+        Send
+      </button>
     </div>
   );
 }
 ```
 
-### 2. Create Widget Registry
+### `handleSend` Options
 
-```tsx
-import type { ComponentType } from "react";
-import type { ClientToolDefinition } from "@buildship/agent";
-import { z } from "zod";
+```ts
+handleSend(input: string, options?: {
+  context?: Record<string, unknown>;  // Additional context passed to the agent
+  skipUserMessage?: boolean;          // Don't add a user message to the conversation
+});
+```
 
-// Import all your widgets
-import { ChartWidget, chartToolConfig } from "./widgets/chart";
-import { MapWidget, mapToolConfig } from "./widgets/map";
+## `useAgentContext` Hook
 
-const allConfigs = [chartToolConfig, mapToolConfig];
+An alternative to `useAgent` for multi-agent setups. Initializes agents
+declaratively and shares state through context.
 
-// Registry for rendering widgets
-export const widgetRegistry: Record<string, ComponentType<any>> = {
-  [chartToolConfig.name]: ChartWidget,
-  [mapToolConfig.name]: MapWidget,
-};
+```tsx
+import { useAgentContext } from "@buildship/agent/react";
 
-// Convert to agent tool definitions
-export function getToolDefinitions(): ClientToolDefinition[] {
-  return allConfigs.map((config) => {
-    const parameters = z.toJSONSchema(config.schema);
-
-    // Remove $schema property for LLM compatibility
-    if (
-      parameters &&
-      typeof parameters === "object" &&
-      "$schema" in parameters
-    ) {
-      const { $schema, ...rest } = parameters as any;
-      return {
-        name: config.name,
-        description: config.description,
-        parameters: rest,
-      };
-    }
-
-    return {
-      name: config.name,
-      description: config.description,
-      parameters,
-    };
-  });
+function ChatPage() {
+  const agent = useAgentContext(
+    "agent-id",
+    "https://your-project.buildship.run/executeAgent/AGENT_ID",
+    "access-key",
+  );
+
+  // Same return shape as useAgent
+  const { messages, handleSend, inProgress, sessions, ... } = agent;
 }
 ```
 
-### 3. Pass Tools to Agent
+## Client Tools (React)
 
-```tsx
-import { getToolDefinitions } from "./widget-registry";
+### `useClientTool` — Headless Tools
 
-function ChatWithWidgets() {
-  const agent = useAgentContext("agent-id", "agent-url", "access-key");
-  const tools = getToolDefinitions();
+Register a tool that runs code without rendering any UI:
 
-  const handleSend = async (input: string) => {
-    await agent.handleSend(input, {
-      clientTools: tools,
-    });
-  };
+```tsx
+import { useClientTool } from "@buildship/agent/react";
+import { z } from "@buildship/agent/core";
+
+function ChatPage() {
+  // Fire-and-forget — runs handler, result is discarded
+  useClientTool("agent-id", {
+    name: "show_notification",
+    description: "Display a notification to the user",
+    parameters: z.object({
+      title: z.string(),
+      message: z.string(),
+    }),
+    handler: (inputs) => {
+      toast(inputs.title, inputs.message);
+    },
+  });
 
-  return (
-    <div>
-      <button onClick={() => handleSend("Show me a chart")}>
-        Ask for Chart
-      </button>
-    </div>
-  );
+  // Blocking tool — agent pauses, handler result is sent back
+  useClientTool("agent-id", {
+    name: "get_location",
+    description: "Get the user's current GPS location",
+    parameters: z.object({}),
+    await: true,
+    handler: async () => {
+      const pos = await getCurrentPosition();
+      return { lat: pos.coords.latitude, lng: pos.coords.longitude };
+    },
+  });
+
+  // ...
 }
 ```
 
-### 4. Render Widgets in Messages
+### `useClientTool` — Widget Tools
 
-```tsx
-import { widgetRegistry } from "./widget-registry";
+Register a tool that renders interactive UI inline in the conversation:
 
-function MessageDisplay() {
-  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+```tsx
+import { useClientTool, ToolRenderer } from "@buildship/agent/react";
+import { z } from "@buildship/agent/core";
+
+function ChatPage() {
+  const { messages } = useAgent("agent-id", agentUrl);
+
+  // Register a widget tool with a render function
+  useClientTool("agent-id", {
+    name: "feedback_form",
+    description: "Collects user feedback",
+    parameters: z.object({
+      question: z.string().describe("The feedback question"),
+    }),
+    await: true, // Agent pauses until user submits
+    render: ({ inputs, submit, status, result }) => (
+      <div>
+        <p>{inputs.question}</p>
+        {status === "pending" ? (
+          <button onClick={() => submit({ answer: "Great!" })}>Submit</button>
+        ) : (
+          <p>✅ Submitted: {JSON.stringify(result)}</p>
+        )}
+      </div>
+    ),
+  });
 
+  // Render messages with embedded widgets
   return (
     <div>
-      {agent.messages.map((message) => (
-        <div key={message.executionId}>
-          {/* Render message parts (text + widgets) */}
-          {message.parts?.map((part, idx) => {
-            if (part.type === "text") {
-              return <p key={idx}>{part.text}</p>;
-            } else if (part.type === "widget") {
-              const Widget = widgetRegistry[part.toolName];
-              if (!Widget) return null;
-              return <Widget key={idx} {...part.inputs} />;
-            }
-            return null;
-          })}
-
-          {/* Fallback: render plain content if no parts */}
-          {!message.parts && <p>{message.content}</p>}
-        </div>
-      ))}
+      {messages.map((msg) =>
+        msg.parts?.map((part) => {
+          if (part.type === "text") {
+            return <p key={part.firstSequence}>{part.text}</p>;
+          }
+          if (part.type === "widget") {
+            return (
+              <ToolRenderer key={part.callId} agentId="agent-id" part={part} />
+            );
+          }
+          return null;
+        }),
+      )}
     </div>
   );
 }
 ```
 
-## API Reference
-
-### handleSend Options
+### `ClientToolConfig`
 
-```typescript
-agent.handleSend(input: string, options?: {
-  // Custom context data for the agent
-  context?: Record<string, unknown>;
-
-  // Don't add user message to UI (for optimistic updates)
-  skipUserMessage?: boolean;
-
-  // Additional HTTP headers
-  additionalHeaders?: Record<string, string>;
+```ts
+interface ClientToolConfig {
+  name: string; // Must match the tool name the agent knows
+  description: string; // Description of what the tool does
+  parameters: ZodSchema | Record<string, any>; // Zod schema or raw JSON Schema
+  await?: boolean; // If true, agent pauses until result
+  handler?: (inputs: any) => any | Promise<any>; // For headless tools
+  render?: (props: ClientToolRenderProps) => any; // For widget tools
+}
+```
 
-  // Server-side tool definitions
-  tools?: ClientToolDefinition[];
+### `ClientToolRenderProps`
 
-  // Client-side widget definitions
-  clientTools?: ClientToolDefinition[];
-})
+```ts
+interface ClientToolRenderProps<T = any> {
+  inputs: T; // Parsed inputs from the agent
+  submit: (result: any) => void; // Submit a result (only for await: true tools)
+  status: "pending" | "submitted"; // Widget status
+  result?: any; // Persisted result after submission
+}
 ```
 
-### Types
+## Messages & Parts
 
-#### Message
+Messages can contain rich, interleaved content via `parts`:
 
-```typescript
+```ts
 type Message = {
   role: "user" | "agent";
   content: string; // Full text content
-  parts?: MessagePart[]; // Structured parts (text + widgets)
+  parts?: MessagePart[]; // Rich content (text + widgets)
   executionId?: string; // Links to debug data
 };
 
@@ -425,13 +448,39 @@ type MessagePart =
       toolName: string;
       callId: string;
       inputs: any;
-      sequence: number;
+      paused?: boolean;
+      status?: "pending" | "submitted";
+      result?: any;
     };
 ```
 
-#### Session
+> **Tip:** When rendering messages, iterate over `msg.parts` instead of
+> `msg.content` to get both text and widgets interleaved in the correct order.
+
+## Sessions
+
+Sessions are automatically persisted to local storage and synced across tabs.
+
+```tsx
+const { sessions, switchSession, deleteSession, sessionId } = useAgent(...);
+
+// List all sessions
+sessions.map((s) => (
+  <button key={s.id} onClick={() => switchSession(s.id)}>
+    {s.name} ({s.messages.length} messages)
+  </button>
+));
+
+// Create a new session
+switchSession(); // No argument = new session
+
+// Delete a session
+deleteSession(sessionId);
+```
+
+### Session Type
 
-```typescript
+```ts
 type Session = {
   id: string;
   createdAt: number;
@@ -441,123 +490,160 @@ type Session = {
 };
 ```
 
-#### ClientToolDefinition
-
-```typescript
-type ClientToolDefinition = {
-  name: string; // Unique tool identifier
-  description: string; // Human-readable description for LLM
-  parameters: unknown; // JSON Schema object
-};
-```
-
-## Advanced Features
+## Debug Data
 
-### Debug Data
-
-Access detailed execution information:
+Debug data captures structured information about every tool call, reasoning
+step, and agent handoff during execution. It's stored by `executionId` (matching
+the user message it belongs to).
 
 ```tsx
-function DebugView() {
-  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+const { debugData, messages } = useAgent(...);
 
-  return (
-    <div>
-      {Object.entries(agent.debugData).map(([executionId, debug]) => (
-        <details key={executionId}>
-          <summary>Execution {executionId}</summary>
-          <pre>{JSON.stringify(debug, null, 2)}</pre>
-        </details>
-      ))}
-    </div>
-  );
-}
+// Get debug data for a specific message
+const messageDebug = debugData[message.executionId];
+
+// Each entry is one of:
+type DebugDataType = Array<ToolExecutionItem | ReasoningItem | HandoffItem>;
 ```
 
-### Custom Headers
+### Debug Entry Types
+
+```ts
+type ToolExecutionItem = {
+  itemType: "tool_call";
+  toolName: string;
+  callId: string;
+  toolType: ToolType; // "flow" | "node" | "mcp" | "client" | "builtin" | "agent"
+  status: "progress" | "complete" | "error";
+  inputs?: unknown;
+  output?: unknown;
+  error?: string;
+  serverName?: string; // For MCP tools
+};
 
-```tsx
-await agent.handleSend("message", {
-  additionalHeaders: {
-    "X-Custom-Header": "value",
-    Authorization: "Bearer token",
-  },
-});
+type ReasoningItem = {
+  itemType: "reasoning";
+  reasoning: string;
+  index?: number;
+};
+
+type HandoffItem = {
+  itemType: "handoff";
+  agentName: string;
+};
 ```
 
-### Abort Requests
+## React API Reference
 
-```tsx
-function CancellableRequest() {
-  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+### Hooks
 
-  return (
-    <div>
-      <button onClick={() => agent.handleSend("Long task...")}>Start</button>
-      <button onClick={() => agent.abort()} disabled={!agent.inProgress}>
-        Cancel
-      </button>
-    </div>
-  );
-}
-```
+| Hook                                       | Description                                      |
+| ------------------------------------------ | ------------------------------------------------ |
+| `useAgent(agentId, agentUrl, accessKey?)`  | Main hook — messages, streaming, sessions, debug |
+| `useAgentContext(agentId, agentUrl, key?)` | Context-based alternative for multi-agent setups |
+| `useClientTool(agentId, config)`           | Register a client tool (headless or widget)      |
 
-### Optimistic Updates
+### Components
 
-```tsx
-function OptimisticMessage() {
-  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+| Component                                   | Description                                        |
+| ------------------------------------------- | -------------------------------------------------- |
+| `<AgentContextProvider>`                    | Provides shared agent state (sessions, debug data) |
+| `<ToolRenderer agentId={id} part={part} />` | Renders a widget tool from a message part          |
 
-  const handleSend = async (input: string) => {
-    // Add message to UI immediately
-    agent.addOptimisticMessage(input);
+### Utilities
 
-    // Send to agent without adding duplicate
-    await agent.handleSend(input, { skipUserMessage: true });
-  };
+| Export                                | Description                                                          |
+| ------------------------------------- | -------------------------------------------------------------------- |
+| `tryParseJSON(value)`                 | Safely parse a JSON string, returns parsed object or original string |
+| `updateAgentMessageParts(msg, event)` | Append/merge parts into an agent message                             |
 
-  return <button onClick={() => handleSend("Hello")}>Send</button>;
-}
-```
+## Full Example
 
-## Storage and Persistence
+```tsx
+import {
+  AgentContextProvider,
+  useAgent,
+  useClientTool,
+  ToolRenderer,
+} from "@buildship/agent/react";
+import { z } from "@buildship/agent/core";
 
-The library automatically persists conversations to localStorage:
+const AGENT_ID = "my-agent";
+const AGENT_URL = "https://my-project.buildship.run/executeAgent/my-agent";
 
-- **Sessions**: Stored under `buildship:agent:conversations`
-- **Debug Data**: Stored under `buildship:agent:debug`
+function App() {
+  return (
+    <AgentContextProvider>
+      <Chat />
+    </AgentContextProvider>
+  );
+}
 
-Sessions are automatically synced across browser tabs and survive page
-refreshes.
+function Chat() {
+  const { messages, handleSend, inProgress, resumeTool, abort, debugData } =
+    useAgent(AGENT_ID, AGENT_URL);
+  const [input, setInput] = useState("");
+
+  // Register a widget tool
+  useClientTool(AGENT_ID, {
+    name: "poll",
+    description: "Ask the user to vote on options",
+    parameters: z.object({
+      question: z.string(),
+      options: z.array(z.string()),
+    }),
+    await: true,
+    render: ({ inputs, submit, status }) => (
+      <div>
+        <p>{inputs.question}</p>
+        {status === "pending" ? (
+          inputs.options.map((opt) => (
+            <button key={opt} onClick={() => submit({ vote: opt })}>
+              {opt}
+            </button>
+          ))
+        ) : (
+          <p>✅ Vote recorded</p>
+        )}
+      </div>
+    ),
+  });
 
-## TypeScript Support
+  const send = () => {
+    if (!input.trim()) return;
+    handleSend(input);
+    setInput("");
+  };
 
-The package is written in TypeScript and exports all types:
+  return (
+    <div>
+      {messages.map((msg, i) => (
+        <div key={i}>
+          <strong>{msg.role}:</strong>
+          {msg.parts?.map((part) =>
+            part.type === "text" ? (
+              <span key={part.firstSequence}>{part.text}</span>
+            ) : (
+              <ToolRenderer key={part.callId} agentId={AGENT_ID} part={part} />
+            ),
+          ) ?? msg.content}
+        </div>
+      ))}
 
-```tsx
-import type {
-  Message,
-  Session,
-  ClientToolDefinition,
-  AgentRunner,
-  DebugDataType,
-  MessagePart,
-} from "@buildship/agent";
+      <input
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        onKeyDown={(e) => e.key === "Enter" && send()}
+      />
+      <button onClick={send} disabled={inProgress}>
+        Send
+      </button>
+      {inProgress && <button onClick={abort}>Stop</button>}
+    </div>
+  );
+}
 ```
 
-## Best Practices
-
-1. **Single Provider**: Only use one `AgentContextProvider` at the root of your
-   app
-2. **Tool Descriptions**: Write clear, detailed descriptions for client tools to
-   help the LLM understand when to use them
-3. **File URLs**: Ensure file URLs are publicly accessible or use signed URLs
-   with sufficient expiration
-4. **Error Handling**: Wrap `handleSend` calls in try-catch blocks for error
-   handling
-5. **Widget Registry**: Keep your widget registry centralized for easier
-   maintenance
-
 ## License
 
 MIT