bs-agent 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BuildShip
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,558 @@
+# @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
+
+```bash
+npm install @buildship/agent
+```
+
+## Quick Start
+
+```tsx
+import { AgentContextProvider, useAgentContext } from "@buildship/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");
+
+  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 "@buildship/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 "@buildship/agent";
+
+function AgentChat() {
+  const agent = useAgentContext(
+    "my-agent-id", // Unique identifier for your agent
+    "https://agent-url.com", // Your agent's endpoint URL
+  );
+
+  // 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 |
+| `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            |
+
+### Session Management
+
+```tsx
+function SessionList() {
+  const agent = useAgentContext("agent-id", "agent-url");
+
+  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");
+  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.
+
+### 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 "@buildship/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");
+  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");
+
+  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>
+  );
+}
+```
+
+## 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
+};
+```
+
+## Advanced Features
+
+### Debug Data
+
+Access detailed execution information:
+
+```tsx
+function DebugView() {
+  const agent = useAgentContext("agent-id", "agent-url");
+
+  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");
+
+  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");
+
+  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,
+  AgentRunner,
+  DebugDataType,
+  MessagePart,
+} from "@buildship/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. **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