@standardagents/client 0.1.0-dev.ffffff

package/LICENSE.txt

@@ -0,0 +1,48 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2025 FormKit Inc. All Rights Reserved.
+
+UNLICENSED - DO NOT USE
+
+This software and associated documentation files (the "Software") are the sole
+and exclusive property of FormKit Inc. ("FormKit").
+
+USE RESTRICTIONS
+
+The Software is UNLICENSED and proprietary. NO PERMISSION is granted to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, or to permit persons to whom the Software is furnished to do so,
+under any circumstances, without prior written authorization from FormKit Inc.
+
+UNAUTHORIZED USE PROHIBITED
+
+Any use of this Software without a valid, written license agreement signed by
+authorized officers of FormKit Inc. is strictly prohibited and constitutes
+unauthorized use and infringement of FormKit's intellectual property rights.
+
+LICENSING INQUIRIES
+
+Organizations interested in licensing this Software should contact:
+enterprise@formkit.com
+
+A written license agreement must be executed before any use of this Software
+is authorized.
+
+NO WARRANTY
+
+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
+FORMKIT INC. 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.
+
+GOVERNING LAW
+
+This license shall be governed by and construed in accordance with the laws
+of the jurisdiction in which FormKit Inc. is incorporated, without regard to
+its conflict of law provisions.
+
+FormKit Inc.
+https://formkit.com
+enterprise@formkit.com

package/README.md

@@ -0,0 +1,320 @@
+# @standardagents/client
+
+Framework-agnostic client library for Standard Agents - provides HTTP/WebSocket communication, connection management, and shared utilities used by `@standardagents/react` and `@standardagents/vue`.
+
+## Installation
+
+```bash
+npm install @standardagents/client
+# or
+pnpm add @standardagents/client
+# or
+yarn add @standardagents/client
+```
+
+> **Note:** Most users should use `@standardagents/react` or `@standardagents/vue` instead. This package is for advanced use cases or building custom framework integrations.
+
+## Quick Start
+
+```typescript
+import { AgentBuilderClient, ThreadConnectionManager } from '@standardagents/client'
+
+// Create a client
+const client = new AgentBuilderClient('https://api.example.com')
+
+// Fetch messages from a thread
+const messages = await client.getMessages('thread-123')
+
+// Send a message
+await client.sendMessage('thread-123', {
+  role: 'user',
+  content: 'Hello!',
+})
+
+// Connect to live updates with automatic reconnection
+const connection = new ThreadConnectionManager(client, 'thread-123', {
+  onStatusChange: (status) => console.log('Status:', status),
+  onMessage: (event) => console.log('New message:', event.data),
+  onChunk: (event) => console.log('Streaming chunk:', event.chunk),
+  onEvent: (event) => console.log('Custom event:', event.eventType, event.data),
+})
+
+connection.connect()
+```
+
+## Authentication
+
+The client reads the authentication token from `localStorage` using the key `agentbuilder_auth_token`:
+
+```typescript
+// Set the token before making requests
+localStorage.setItem('agentbuilder_auth_token', 'your-token-here')
+```
+
+All API requests and WebSocket connections will automatically include this token.
+
+## API Reference
+
+### `AgentBuilderClient`
+
+HTTP client for the Standard Agents API.
+
+#### Constructor
+
+```typescript
+const client = new AgentBuilderClient(endpoint: string)
+```
+
+#### Methods
+
+##### `getEndpoint(): string`
+
+Returns the configured endpoint URL.
+
+##### `createThread(payload): Promise<Thread>`
+
+Create a new thread.
+
+```typescript
+const thread = await client.createThread({
+  agent_id: 'my-agent',
+  user_id: 'user-123', // optional
+})
+```
+
+##### `getThread(threadId): Promise<Thread>`
+
+Get thread metadata.
+
+```typescript
+const thread = await client.getThread('thread-123')
+```
+
+##### `getMessages(threadId, options?): Promise<Message[]>`
+
+Fetch messages from a thread.
+
+```typescript
+const messages = await client.getMessages('thread-123', {
+  limit: 50,
+  offset: 0,
+  depth: 0,
+  includeSilent: false,
+})
+```
+
+##### `sendMessage(threadId, payload): Promise<Message>`
+
+Send a message to a thread.
+
+```typescript
+const message = await client.sendMessage('thread-123', {
+  role: 'user',
+  content: 'Hello!',
+  silent: false, // optional
+})
+```
+
+##### `stopExecution(threadId): Promise<void>`
+
+Cancel an in-flight execution.
+
+```typescript
+await client.stopExecution('thread-123')
+```
+
+##### `connectMessageWebSocket(threadId, callbacks?, options?): WebSocket`
+
+Create a WebSocket connection for streaming messages.
+
+```typescript
+const ws = client.connectMessageWebSocket('thread-123', {
+  onOpen: () => console.log('Connected'),
+  onMessage: (event) => console.log('Message:', event),
+  onChunk: (event) => console.log('Chunk:', event),
+  onError: (event) => console.error('Error:', event),
+  onClose: (event) => console.log('Closed:', event),
+}, {
+  includeSilent: false,
+  depth: 0,
+})
+```
+
+##### `connectLogWebSocket(threadId, callbacks?): WebSocket`
+
+Create a WebSocket connection for log events and custom events.
+
+```typescript
+const ws = client.connectLogWebSocket('thread-123', {
+  onOpen: () => console.log('Connected'),
+  onLog: (event) => console.log('Log:', event),
+  onCustom: (event) => console.log('Custom:', event),
+  onStopped: (event) => console.log('Stopped:', event),
+  onClose: (event) => console.log('Closed:', event),
+})
+```
+
+---
+
+### `ThreadConnectionManager`
+
+Manages WebSocket connections with automatic reconnection and heartbeat.
+
+#### Constructor
+
+```typescript
+const manager = new ThreadConnectionManager(
+  client: AgentBuilderClient,
+  threadId: string,
+  callbacks?: ThreadConnectionCallbacks,
+  options?: ThreadConnectionOptions
+)
+```
+
+**Callbacks:**
+
+- `onStatusChange?: (status: ConnectionStatus) => void` - Called when connection status changes
+- `onMessage?: (event: MessageDataEvent) => void` - Called when a complete message is received
+- `onChunk?: (event: MessageChunkEvent) => void` - Called when a streaming chunk is received
+- `onEvent?: (event: ThreadEvent) => void` - Called when a custom event is received
+- `onError?: (error: Error | Event) => void` - Called on connection errors
+
+**Options:**
+
+- `depth?: number` - Message depth level (default: `0`)
+- `includeSilent?: boolean` - Include silent messages (default: `false`)
+- `maxReconnectDelay?: number` - Max reconnection delay in ms (default: `30000`)
+- `heartbeatInterval?: number` - Heartbeat interval in ms (default: `30000`)
+
+#### Methods
+
+##### `connect(): void`
+
+Establish the WebSocket connection.
+
+##### `disconnect(): void`
+
+Close the connection and stop reconnection attempts.
+
+##### `getStatus(): ConnectionStatus`
+
+Returns the current connection status: `'connecting' | 'connected' | 'reconnecting' | 'disconnected'`
+
+##### `getThreadId(): string`
+
+Returns the thread ID.
+
+##### `updateCallbacks(callbacks): void`
+
+Update callbacks after construction.
+
+##### `updateOptions(options): void`
+
+Update options after construction.
+
+#### Reconnection Behavior
+
+The connection manager automatically reconnects on unexpected disconnections using exponential backoff:
+
+- Initial delay: 1 second
+- Doubles each attempt: 1s, 2s, 4s, 8s, 16s
+- Maximum delay: 30 seconds (configurable)
+- Resets to 1s after successful connection
+
+---
+
+### `transformToWorkblocks(messages): ThreadMessage[]`
+
+Groups tool calls with their results into workblock structures for easier UI rendering.
+
+```typescript
+import { transformToWorkblocks } from '@standardagents/client'
+
+const messages = await client.getMessages('thread-123')
+const workblocks = transformToWorkblocks(messages)
+
+// Each workblock contains:
+// - type: 'workblock'
+// - workItems: array of tool calls and results
+// - status: 'pending' | 'completed'
+```
+
+---
+
+## Types
+
+```typescript
+import type {
+  Message,
+  WorkMessage,
+  WorkItem,
+  ThreadMessage,
+  Thread,
+  SendMessagePayload,
+  GetMessagesOptions,
+  CreateThreadPayload,
+  ConnectionStatus,
+  ThreadConnectionCallbacks,
+  ThreadConnectionOptions,
+} from '@standardagents/client'
+```
+
+### 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
+  tool_calls?: string // JSON string
+  tool_call_id?: string
+}
+
+interface WorkMessage {
+  type: 'workblock'
+  id: string
+  content: string | null
+  reasoning_content?: string | null
+  status: 'pending' | 'completed'
+  workItems: WorkItem[]
+  created_at: number
+  depth?: number
+}
+
+interface WorkItem {
+  id: string
+  type: 'tool_call' | 'tool_result'
+  name: string
+  input?: string
+  content?: string
+  status: 'success' | 'error' | null
+  tool_call_id?: string
+}
+
+type ThreadMessage = Message | WorkMessage
+```
+
+---
+
+## Local Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build package
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Run tests
+pnpm test
+```