buildship-agent 1.0.0

package/README.md

@@ -0,0 +1,901 @@
+# super-agent
+
+A React library for building AI agent applications with streaming responses, interactive tools, and session management. Works with any AI agent backend that supports Server-Sent Events (SSE).
+
+## 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
+- **Interactive Tools**: Pause agent execution and collect user input with
+  `requiresResult` tools
+- **TypeScript**: Full type safety with comprehensive TypeScript definitions
+- **Multi-Agent**: Support for multiple agents in a single application
+
+## Installation
+
+```bash
+npm install super-agent
+```
+
+## Quick Start
+
+```tsx
+import { AgentContextProvider, useAgentContext } from "super-agent";
+
+// 1. Wrap your app with the provider
+function App() {
+  return (
+    <AgentContextProvider>
+      <YourApp />
+    </AgentContextProvider>
+  );
+}
+
+// 2. Use the agent in your components
+function ChatComponent() {
+  const agent = useAgentContext(
+    "your-agent-id",
+    "https://your-agent-url.com",
+    "your-access-key",
+  );
+
+  const handleSend = () => {
+    agent.handleSend("Hello, agent!");
+  };
+
+  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>
+  );
+}
+```
+
+## Setup
+
+### AgentContextProvider
+
+The `AgentContextProvider` must wrap your application to enable agent
+functionality. It manages:
+
+- Global session state across all agents
+- Automatic localStorage persistence
+- Agent runner registry
+
+```tsx
+import { AgentContextProvider } from "super-agent";
+
+function App() {
+  return (
+    <AgentContextProvider>{/* Your app components */}</AgentContextProvider>
+  );
+}
+```
+
+## Basic Usage
+
+### Using the Agent Hook
+
+The `useAgentContext` hook is the primary interface for interacting with agents:
+
+```tsx
+import { useAgentContext } from "super-agent";
+
+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)
+  );
+
+  // Send a message
+  const sendMessage = async () => {
+    await agent.handleSend("What's the weather today?");
+  };
+
+  // Display messages
+  return (
+    <div>
+      {agent.messages.map((message, idx) => (
+        <div key={idx}>
+          <strong>{message.role === "user" ? "You" : "Agent"}:</strong>
+          <p>{message.content}</p>
+        </div>
+      ))}
+
+      {agent.inProgress && <div>Agent is thinking...</div>}
+
+      <button onClick={sendMessage} disabled={agent.inProgress}>
+        Send
+      </button>
+    </div>
+  );
+}
+```
+
+### AgentRunner API
+
+The `useAgentContext` hook returns an `AgentRunner` object with:
+
+| Property               | Type                            | Description                                 |
+| ---------------------- | ------------------------------- | ------------------------------------------- |
+| `messages`             | `Message[]`                     | Array of conversation messages              |
+| `inProgress`           | `boolean`                       | Whether the agent is currently processing   |
+| `isPaused`             | `boolean`                       | Whether agent is paused waiting for results |
+| `pendingToolCalls`     | `PendingToolCall[]`             | Tools waiting for user input                |
+| `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                 |
+| `submitToolResults`    | `Function`                      | Submit results from interactive tools       |
+| `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              |
+
+### Session Management
+
+```tsx
+function SessionList() {
+  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+
+  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>
+      ))}
+
+      {/* Create new session */}
+      <button onClick={() => agent.switchSession()}>New Session</button>
+    </div>
+  );
+}
+```
+
+## File Handling
+
+To send files to your agent:
+
+### 1. Upload Files to Storage
+
+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> = {};
+
+  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;
+  }
+
+  return fileMap;
+}
+```
+
+### 2. Send Files with Message
+
+```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,
+      },
+    });
+  };
+
+  return (
+    <div>
+      <input
+        type="file"
+        multiple
+        onChange={(e) => setFiles(Array.from(e.target.files || []))}
+      />
+      <button onClick={handleSendWithFiles}>Send with Files</button>
+    </div>
+  );
+}
+```
+
+### File Context Structure
+
+```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. There are two types of client tools:
+
+- **Fire-and-forget tools** (default): Agent calls the tool and continues
+  immediately without waiting for a result
+- **Interactive tools** (`requiresResult: true`): Agent pauses execution and
+  waits for user input before continuing
+
+### 1. Define Tool Configuration
+
+Create tool configurations with Zod schemas:
+
+```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"),
+  }),
+};
+
+// Create your widget component
+export function ChartWidget({ title, data }) {
+  return (
+    <div>
+      <h3>{title}</h3>
+      {/* Your chart rendering logic */}
+    </div>
+  );
+}
+```
+
+### 2. Create Widget Registry
+
+```tsx
+import type { ComponentType } from "react";
+import type { ClientToolDefinition } from "super-agent";
+import { z } from "zod";
+
+// Import all your widgets
+import { ChartWidget, chartToolConfig } from "./widgets/chart";
+import { MapWidget, mapToolConfig } from "./widgets/map";
+
+const allConfigs = [chartToolConfig, mapToolConfig];
+
+// Registry for rendering widgets
+export const widgetRegistry: Record<string, ComponentType<any>> = {
+  [chartToolConfig.name]: ChartWidget,
+  [mapToolConfig.name]: MapWidget,
+};
+
+// 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,
+    };
+  });
+}
+```
+
+### 3. Pass Tools to Agent
+
+```tsx
+import { getToolDefinitions } from "./widget-registry";
+
+function ChatWithWidgets() {
+  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+  const tools = getToolDefinitions();
+
+  const handleSend = async (input: string) => {
+    await agent.handleSend(input, {
+      clientTools: tools,
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleSend("Show me a chart")}>
+        Ask for Chart
+      </button>
+    </div>
+  );
+}
+```
+
+### 4. Render Widgets in Messages
+
+```tsx
+import { widgetRegistry } from "./widget-registry";
+
+function MessageDisplay() {
+  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+
+  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>
+      ))}
+    </div>
+  );
+}
+```
+
+## Interactive Client Tools (Pause & Resume)
+
+Interactive client tools allow agents to pause execution and wait for user input
+before continuing. This is useful for scenarios like:
+
+- Flight/hotel selection from search results
+- Form inputs and confirmations
+- Date/time pickers
+- File selection
+- Custom decision points
+
+### How It Works
+
+1. Agent calls a tool with `requiresResult: true`
+2. Agent execution **pauses** (`isPaused` becomes `true`)
+3. Frontend renders UI and collects user input
+4. Frontend calls `submitToolResults()` with user's selection
+5. Agent **resumes** execution with the result and continues
+
+### Complete Example: Flight Booking
+
+```tsx
+import { useState, useEffect } from "react";
+import { useAgentContext } from "super-agent";
+import type { ClientToolDefinition } from "super-agent";
+
+// Define interactive tool
+const FLIGHT_PICKER_TOOL: ClientToolDefinition = {
+  name: "show_flight_picker",
+  description: "Show flight picker UI and get user's flight selection",
+  parameters: {
+    type: "object",
+    properties: {
+      origin: { type: "string", description: "Origin airport code" },
+      destination: { type: "string", description: "Destination airport code" },
+      date: { type: "string", description: "Travel date" },
+      flights: {
+        type: "array",
+        description: "Available flights",
+        items: {
+          type: "object",
+          properties: {
+            flightNumber: { type: "string" },
+            airline: { type: "string" },
+            price: { type: "number" },
+            departureTime: { type: "string" },
+          },
+        },
+      },
+    },
+    required: ["origin", "destination", "flights"],
+  },
+  requiresResult: true, // ✅ Agent will pause and wait
+};
+
+// Flight picker component
+function FlightPickerModal({ flights, onSelect, onCancel }) {
+  return (
+    <div className="modal">
+      <h3>Select a Flight</h3>
+      {flights.map((flight) => (
+        <div key={flight.flightNumber} className="flight-option">
+          <div>
+            {flight.airline} {flight.flightNumber}
+          </div>
+          <div>Departure: {flight.departureTime}</div>
+          <div>${flight.price}</div>
+          <button onClick={() => onSelect(flight)}>Select</button>
+        </div>
+      ))}
+      <button onClick={onCancel}>Cancel</button>
+    </div>
+  );
+}
+
+// Main chat component
+function FlightBookingChat() {
+  const agent = useAgentContext(
+    "flight-agent",
+    "https://api.example.com/executeAgent/flight-agent",
+    "your-access-key",
+  );
+
+  const [showFlightPicker, setShowFlightPicker] = useState(false);
+  const [currentToolCall, setCurrentToolCall] = useState(null);
+
+  // Monitor for pending tool calls
+  useEffect(() => {
+    if (agent.isPaused && agent.pendingToolCalls.length > 0) {
+      const toolCall = agent.pendingToolCalls[0];
+
+      if (toolCall.toolName === "show_flight_picker") {
+        setCurrentToolCall(toolCall);
+        setShowFlightPicker(true);
+      }
+    }
+  }, [agent.isPaused, agent.pendingToolCalls]);
+
+  const handleFlightSelect = async (selectedFlight) => {
+    if (!currentToolCall) return;
+
+    // Submit the result back to the agent
+    await agent.submitToolResults([
+      {
+        callId: currentToolCall.callId,
+        result: selectedFlight,
+      },
+    ]);
+
+    // Close the modal
+    setShowFlightPicker(false);
+    setCurrentToolCall(null);
+  };
+
+  const handleCancel = async () => {
+    if (!currentToolCall) return;
+
+    // Submit null/cancel result
+    await agent.submitToolResults([
+      {
+        callId: currentToolCall.callId,
+        result: { cancelled: true },
+      },
+    ]);
+
+    setShowFlightPicker(false);
+    setCurrentToolCall(null);
+  };
+
+  const handleSendMessage = async (input: string) => {
+    await agent.handleSend(input, {
+      clientTools: [FLIGHT_PICKER_TOOL],
+    });
+  };
+
+  return (
+    <div>
+      {/* Messages */}
+      <div className="messages">
+        {agent.messages.map((msg, idx) => (
+          <div key={idx} className={msg.role}>
+            {msg.content}
+          </div>
+        ))}
+
+        {agent.isPaused && <div className="status">Waiting for input...</div>}
+      </div>
+
+      {/* Flight Picker Modal */}
+      {showFlightPicker && currentToolCall && (
+        <FlightPickerModal
+          flights={currentToolCall.inputs.flights}
+          onSelect={handleFlightSelect}
+          onCancel={handleCancel}
+        />
+      )}
+
+      {/* Input */}
+      <input
+        type="text"
+        placeholder="Ask to book a flight..."
+        onKeyPress={(e) => {
+          if (e.key === "Enter") {
+            handleSendMessage(e.currentTarget.value);
+            e.currentTarget.value = "";
+          }
+        }}
+        disabled={agent.inProgress}
+      />
+    </div>
+  );
+}
+```
+
+### submitToolResults Options
+
+```typescript
+agent.submitToolResults(
+  toolResults: ClientToolResult[],
+  options?: {
+    input?: string;              // Optional follow-up message
+    context?: object;             // Additional context
+    additionalHeaders?: Record<string, string>;
+  }
+)
+```
+
+### Example: Multiple Tool Results
+
+If the agent calls multiple tools that require results:
+
+```tsx
+function MultiToolHandler() {
+  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+
+  const handleSubmitAll = async () => {
+    // Submit results for all pending tools at once
+    const results = agent.pendingToolCalls.map((toolCall) => ({
+      callId: toolCall.callId,
+      result: getResultForTool(toolCall.toolName, toolCall.inputs),
+    }));
+
+    await agent.submitToolResults(results);
+  };
+
+  return (
+    <div>
+      {agent.isPaused && (
+        <div>
+          <h3>Pending Actions ({agent.pendingToolCalls.length})</h3>
+          {agent.pendingToolCalls.map((toolCall) => (
+            <div key={toolCall.callId}>
+              <strong>{toolCall.toolName}</strong>
+              <pre>{JSON.stringify(toolCall.inputs, null, 2)}</pre>
+            </div>
+          ))}
+          <button onClick={handleSubmitAll}>Submit All</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Example: Resume with Follow-up Message
+
+```tsx
+const handleSubmitWithMessage = async (result: any) => {
+  await agent.submitToolResults(
+    [{ callId: currentToolCall.callId, result }],
+    {
+      input: "Great! Now book the hotel too.", // Optional follow-up
+    },
+  );
+};
+```
+
+### Fire-and-Forget Tools (No Pause)
+
+For tools that don't need user input, simply omit `requiresResult`:
+
+```tsx
+const NOTIFICATION_TOOL: ClientToolDefinition = {
+  name: "show_notification",
+  description: "Display a notification to the user",
+  parameters: {
+    type: "object",
+    properties: {
+      message: { type: "string" },
+      type: { type: "string", enum: ["info", "success", "warning", "error"] },
+    },
+  },
+  // No requiresResult - agent continues immediately
+};
+```
+
+### Best Practices for Interactive Tools
+
+1. **Clear Tool Descriptions**: Help the LLM understand when to use the tool
+
+   ```tsx
+   {
+     name: "show_flight_picker",
+     description: "Show a flight selection UI when the user asks to book or search for flights. Use this AFTER searching for available flights.",
+     // ...
+   }
+   ```
+
+2. **Handle Cancellation**: Always provide a way for users to cancel
+
+   ```tsx
+   await agent.submitToolResults([
+     {
+       callId: toolCall.callId,
+       result: { cancelled: true, reason: "User cancelled" },
+     },
+   ]);
+   ```
+
+3. **Loading States**: Show appropriate UI while paused
+
+   ```tsx
+   {
+     agent.isPaused && (
+       <div className="loading">Waiting for your selection...</div>
+     );
+   }
+   ```
+
+4. **Error Handling**: Wrap submitToolResults in try-catch
+
+   ```tsx
+   try {
+     await agent.submitToolResults([{ callId, result }]);
+   } catch (error) {
+     console.error("Failed to submit tool result:", error);
+     // Show error to user
+   }
+   ```
+
+5. **Type Safety**: Type your tool inputs and results
+   ```tsx
+   type FlightPickerInputs = {
+     origin: string;
+     destination: string;
+     flights: Flight[];
+   };
+   type FlightPickerResult = Flight | { cancelled: true };
+   ```
+
+## API Reference
+
+### handleSend Options
+
+```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>;
+
+  // Server-side tool definitions
+  tools?: ClientToolDefinition[];
+
+  // Client-side widget definitions
+  clientTools?: ClientToolDefinition[];
+})
+```
+
+### Types
+
+#### Message
+
+```typescript
+type Message = {
+  role: "user" | "agent";
+  content: string; // Full text content
+  parts?: MessagePart[]; // Structured parts (text + widgets)
+  executionId?: string; // Links to debug data
+};
+
+type MessagePart =
+  | { type: "text"; text: string; firstSequence: number; lastSequence: number }
+  | {
+      type: "widget";
+      toolName: string;
+      callId: string;
+      inputs: any;
+      sequence: number;
+    };
+```
+
+#### Session
+
+```typescript
+type Session = {
+  id: string;
+  createdAt: number;
+  updatedAt: number;
+  messages: Message[];
+  name?: string;
+};
+```
+
+#### ClientToolDefinition
+
+```typescript
+type ClientToolDefinition = {
+  name: string; // Unique tool identifier
+  description: string; // Human-readable description for LLM
+  parameters: unknown; // JSON Schema object
+  requiresResult?: boolean; // If true, agent pauses and waits for user input
+};
+
+type ClientToolResult = {
+  callId: string; // ID from the client_tool_call event
+  result: any; // User's input or selection
+};
+
+type PendingToolCall = {
+  toolName: string;
+  callId: string;
+  inputs: any;
+  requiresResult: boolean;
+};
+```
+
+## Advanced Features
+
+### Debug Data
+
+Access detailed execution information:
+
+```tsx
+function DebugView() {
+  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+
+  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>
+  );
+}
+```
+
+### Custom Headers
+
+```tsx
+await agent.handleSend("message", {
+  additionalHeaders: {
+    "X-Custom-Header": "value",
+    Authorization: "Bearer token",
+  },
+});
+```
+
+### Abort Requests
+
+```tsx
+function CancellableRequest() {
+  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+
+  return (
+    <div>
+      <button onClick={() => agent.handleSend("Long task...")}>Start</button>
+      <button onClick={() => agent.abort()} disabled={!agent.inProgress}>
+        Cancel
+      </button>
+    </div>
+  );
+}
+```
+
+### Optimistic Updates
+
+```tsx
+function OptimisticMessage() {
+  const agent = useAgentContext("agent-id", "agent-url", "access-key");
+
+  const handleSend = async (input: string) => {
+    // Add message to UI immediately
+    agent.addOptimisticMessage(input);
+
+    // Send to agent without adding duplicate
+    await agent.handleSend(input, { skipUserMessage: true });
+  };
+
+  return <button onClick={() => handleSend("Hello")}>Send</button>;
+}
+```
+
+## Storage and Persistence
+
+The library automatically persists conversations to localStorage:
+
+- **Sessions**: Stored under `buildship:agent:conversations`
+- **Debug Data**: Stored under `buildship:agent:debug`
+
+Sessions are automatically synced across browser tabs and survive page
+refreshes.
+
+## TypeScript Support
+
+The package is written in TypeScript and exports all types:
+
+```tsx
+import type {
+  Message,
+  Session,
+  ClientToolDefinition,
+  ClientToolResult,
+  PendingToolCall,
+  AgentRunner,
+  DebugDataType,
+  MessagePart,
+} from "super-agent";
+```
+
+## 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. **Interactive Tools**: Use `requiresResult: true` only when you truly need to
+   pause execution for user input. For simple notifications or displays, use
+   fire-and-forget tools
+4. **File URLs**: Ensure file URLs are publicly accessible or use signed URLs
+   with sufficient expiration
+5. **Error Handling**: Wrap `handleSend` and `submitToolResults` calls in
+   try-catch blocks for error handling
+6. **Widget Registry**: Keep your widget registry centralized for easier
+   maintenance
+7. **Pending Tool Management**: Always handle `isPaused` state and provide clear
+   UI for users when the agent is waiting for input
+
+## License
+
+MIT