@octavus/client-sdk 0.2.0 → 2.0.0

package/README.md

@@ -0,0 +1,196 @@
+# @octavus/client-sdk
+
+Framework-agnostic client SDK for Octavus agents.
+
+## Installation
+
+```bash
+npm install @octavus/client-sdk
+```
+
+## Overview
+
+This package provides a framework-agnostic client for streaming Octavus agent responses. It handles message state management, streaming events, and transport abstraction.
+
+For React applications, use [`@octavus/react`](https://www.npmjs.com/package/@octavus/react) instead—it provides React hooks that wrap this SDK.
+
+## Quick Start
+
+```typescript
+import { OctavusChat, createHttpTransport } from '@octavus/client-sdk';
+
+// Create transport
+const transport = createHttpTransport({
+  request: (payload, options) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, ...payload }),
+      signal: options?.signal,
+    }),
+});
+
+// Create chat client
+const chat = new OctavusChat({ transport });
+
+// Subscribe to state changes
+const unsubscribe = chat.subscribe(() => {
+  console.log('Messages:', chat.messages);
+  console.log('Status:', chat.status);
+});
+
+// Send a message
+await chat.send('user-message', { USER_MESSAGE: 'Hello!' }, { userMessage: { content: 'Hello!' } });
+
+// Cleanup
+unsubscribe();
+```
+
+## Transports
+
+### HTTP Transport (SSE)
+
+Best for Next.js, Express, and HTTP-based applications:
+
+```typescript
+import { createHttpTransport } from '@octavus/client-sdk';
+
+const transport = createHttpTransport({
+  request: (payload, options) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, ...payload }),
+      signal: options?.signal,
+    }),
+});
+```
+
+### Socket Transport (WebSocket/SockJS)
+
+Best for real-time applications with persistent connections:
+
+```typescript
+import { createSocketTransport } from '@octavus/client-sdk';
+
+const transport = createSocketTransport({
+  connect: () =>
+    new Promise((resolve, reject) => {
+      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);
+      ws.onopen = () => resolve(ws);
+      ws.onerror = () => reject(new Error('Connection failed'));
+    }),
+});
+
+// Optional: eagerly connect and monitor state
+transport.onConnectionStateChange((state, error) => {
+  console.log('Connection state:', state);
+});
+await transport.connect();
+```
+
+## Chat Client
+
+### Creating a Chat Instance
+
+```typescript
+const chat = new OctavusChat({
+  transport,
+  initialMessages: [], // Optional: restore from server
+  onError: (error) => console.error(error),
+  onFinish: () => console.log('Done'),
+  onResourceUpdate: (name, value) => console.log(`Resource ${name}:`, value),
+});
+```
+
+### Sending Messages
+
+```typescript
+// Text message
+await chat.send('user-message', { USER_MESSAGE: message }, { userMessage: { content: message } });
+
+// With file attachments
+await chat.send(
+  'user-message',
+  { USER_MESSAGE: message, FILES: fileRefs },
+  { userMessage: { content: message, files: fileRefs } },
+);
+```
+
+### State Properties
+
+```typescript
+chat.messages; // UIMessage[] - all messages
+chat.status; // 'idle' | 'streaming' | 'error'
+chat.error; // OctavusError | null
+```
+
+### Stopping Generation
+
+```typescript
+chat.stop(); // Stops streaming and finalizes partial content
+```
+
+## File Uploads
+
+```typescript
+// Upload files separately (for progress tracking)
+const fileRefs = await chat.uploadFiles(fileInput.files, (index, progress) => {
+  console.log(`File ${index}: ${progress}%`);
+});
+
+// Use the references in a message
+await chat.send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });
+```
+
+Note: File uploads require configuring `requestUploadUrls` in the chat options.
+
+## Message Types
+
+Messages contain ordered `parts` with typed content:
+
+```typescript
+type UIMessagePart =
+  | UITextPart // Text content with streaming status
+  | UIReasoningPart // Model reasoning/thinking content
+  | UIToolCallPart // Tool call with args, result, and status
+  | UIOperationPart // Internal operations (e.g., set-resource)
+  | UISourcePart // URL or document sources
+  | UIFilePart // File attachments (uploaded or generated)
+  | UIObjectPart; // Structured output objects
+```
+
+Each part includes a `type` discriminator and relevant fields. See TypeScript types for full field definitions.
+
+## Error Handling
+
+Errors are structured with type classification:
+
+```typescript
+import { isRateLimitError, isAuthenticationError } from '@octavus/client-sdk';
+
+const chat = new OctavusChat({
+  transport,
+  onError: (error) => {
+    if (isRateLimitError(error)) {
+      showRetryButton(error.retryAfter);
+    } else if (isAuthenticationError(error)) {
+      redirectToLogin();
+    }
+  },
+});
+```
+
+## Re-exports
+
+This package re-exports everything from `@octavus/core`, so you don't need to install it separately.
+
+## Related Packages
+
+- [`@octavus/react`](https://www.npmjs.com/package/@octavus/react) - React hooks and bindings
+- [`@octavus/server-sdk`](https://www.npmjs.com/package/@octavus/server-sdk) - Server-side SDK
+- [`@octavus/core`](https://www.npmjs.com/package/@octavus/core) - Shared types
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { StreamEvent, FileReference, UIMessage } from '@octavus/core';
+import { StreamEvent, ToolResult, FileReference, UIMessage, OctavusError } from '@octavus/core';
 export * from '@octavus/core';
-export { isFileReference, isFileReferenceArray, isOtherThread } from '@octavus/core';
+export { AppError, ConflictError, ForbiddenError, MAIN_THREAD, NotFoundError, OCTAVUS_SKILL_TOOLS, OctavusError, ValidationError, createApiErrorEvent, createErrorEvent, createInternalErrorEvent, errorToStreamEvent, generateId, getSkillSlugFromToolCall, isAbortError, isAuthenticationError, isFileReference, isFileReferenceArray, isMainThread, isOctavusSkillTool, isOtherThread, isProviderError, isRateLimitError, isRetryableError, isToolError, isValidationError, resolveThread, safeParseStreamEvent, safeParseUIMessage, safeParseUIMessages, threadForPart } from '@octavus/core';
 
 /**
  * Transport interface for delivering events from server to client.
@@ -16,6 +16,13 @@ interface Transport {
      * @param input - Input parameters for variable substitution
      */
     trigger(triggerName: string, input?: Record<string, unknown>): AsyncIterable<StreamEvent>;
+    /**
+     * Continue execution with tool results after client-side tool handling.
+     *
+     * @param executionId - The execution ID from the client-tool-request event
+     * @param results - All tool results (server + client) to send
+     */
+    continueWithToolResults(executionId: string, results: ToolResult[]): AsyncIterable<StreamEvent>;
     /** Stop the current stream. Safe to call when no stream is active. */
     stop(): void;
 }
@@ -191,7 +198,51 @@ interface UploadFilesOptions {
  */
 declare function uploadFiles(files: FileList | File[], options: UploadFilesOptions): Promise<FileReference[]>;
 
-type ChatStatus = 'idle' | 'streaming' | 'error';
+type ChatStatus = 'idle' | 'streaming' | 'error' | 'awaiting-input';
+/**
+ * Context provided to client tool handlers.
+ */
+interface ClientToolContext {
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Name of the tool being called */
+    toolName: string;
+    /** Signal for cancellation if user stops generation */
+    signal: AbortSignal;
+}
+/**
+ * Handler function for client-side tool execution.
+ * Can be:
+ * - An async function that executes automatically and returns a result
+ * - The string 'interactive' to indicate the tool requires user interaction
+ */
+type ClientToolHandler = ((args: Record<string, unknown>, ctx: ClientToolContext) => Promise<unknown>) | 'interactive';
+/**
+ * Interactive tool call awaiting user interaction.
+ * The `submit` and `cancel` methods are pre-bound to this tool call's ID.
+ */
+interface InteractiveTool {
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Name of the tool being called */
+    toolName: string;
+    /** Arguments passed to the tool */
+    args: Record<string, unknown>;
+    /**
+     * Submit a result for this tool call.
+     * Call this when the user has provided input.
+     *
+     * @param result - The result from user interaction
+     */
+    submit: (result: unknown) => void;
+    /**
+     * Cancel this tool call with an optional reason.
+     * Call this when the user dismisses the UI without providing input.
+     *
+     * @param reason - Optional reason for cancellation (default: 'User cancelled')
+     */
+    cancel: (reason?: string) => void;
+}
 /**
  * Input for creating a user message.
  * Supports text content, structured object content, and file attachments.
@@ -234,10 +285,59 @@ interface OctavusChatOptions {
      * ```
      */
     requestUploadUrls?: UploadFilesOptions['requestUploadUrls'];
+    /**
+     * Client-side tool handlers.
+     * Register handlers for tools that should execute in the browser.
+     *
+     * - If a tool has a handler function: executes automatically
+     * - If a tool is marked as 'interactive': appears in `pendingClientTools` with bound `submit()`/`cancel()`
+     *
+     * @example Automatic client tool
+     * ```typescript
+     * clientTools: {
+     *   'get-browser-location': async () => {
+     *     const pos = await new Promise((resolve, reject) => {
+     *       navigator.geolocation.getCurrentPosition(resolve, reject);
+     *     });
+     *     return { lat: pos.coords.latitude, lng: pos.coords.longitude };
+     *   },
+     * }
+     * ```
+     *
+     * @example Interactive client tool (user input required)
+     * ```typescript
+     * clientTools: {
+     *   'request-feedback': 'interactive',
+     * }
+     * // Then render UI based on pendingClientTools['request-feedback']
+     * // and call tool.submit(result) or tool.cancel()
+     * ```
+     */
+    clientTools?: Record<string, ClientToolHandler>;
     /** Initial messages (for session refresh) */
     initialMessages?: UIMessage[];
-    /** Callback when an error occurs */
-    onError?: (error: Error) => void;
+    /**
+     * Callback when an error occurs.
+     * Receives an OctavusError with structured error information.
+     *
+     * @example
+     * ```typescript
+     * onError: (error) => {
+     *   console.error('Chat error:', {
+     *     type: error.errorType,
+     *     message: error.message,
+     *     retryable: error.retryable,
+     *     provider: error.provider,
+     *   });
+     *
+     *   // Handle specific error types
+     *   if (isRateLimitError(error)) {
+     *     showRetryButton(error.retryAfter);
+     *   }
+     * }
+     * ```
+     */
+    onError?: (error: OctavusError) => void;
     /** Callback when streaming finishes successfully */
     onFinish?: () => void;
     /** Callback when streaming is stopped by user */
@@ -256,10 +356,12 @@ type Listener = () => void;
  *
  * const chat = new OctavusChat({
  *   transport: createHttpTransport({
- *     triggerRequest: (triggerName, input) =>
+ *     request: (payload, options) =>
  *       fetch('/api/trigger', {
  *         method: 'POST',
- *         body: JSON.stringify({ sessionId, triggerName, input }),
+ *         headers: { 'Content-Type': 'application/json' },
+ *         body: JSON.stringify({ sessionId, ...payload }),
+ *         signal: options?.signal,
  *       }),
  *   }),
  * });
@@ -287,11 +389,41 @@ declare class OctavusChat {
     private options;
     private transport;
     private streamingState;
+    private _pendingToolsByName;
+    private _pendingToolsByCallId;
+    private _pendingClientToolsCache;
+    private _completedToolResults;
+    private _clientToolAbortController;
+    private _serverToolResults;
+    private _pendingExecutionId;
     private listeners;
     constructor(options: OctavusChatOptions);
     get messages(): UIMessage[];
     get status(): ChatStatus;
-    get error(): Error | null;
+    /**
+     * The current error, if any.
+     * Contains structured error information including type, source, and retryability.
+     */
+    get error(): OctavusError | null;
+    /**
+     * Pending interactive tool calls keyed by tool name.
+     * Each tool has bound `submit()` and `cancel()` methods.
+     *
+     * @example
+     * ```tsx
+     * const feedbackTools = pendingClientTools['request-feedback'] ?? [];
+     *
+     * {feedbackTools.map(tool => (
+     *   <FeedbackModal
+     *     key={tool.toolCallId}
+     *     {...tool.args}
+     *     onSubmit={(result) => tool.submit(result)}
+     *     onCancel={() => tool.cancel()}
+     *   />
+     * ))}
+     * ```
+     */
+    get pendingClientTools(): Record<string, InteractiveTool[]>;
     /**
      * Subscribe to state changes. The callback is called whenever messages, status, or error changes.
      * @returns Unsubscribe function
@@ -301,6 +433,7 @@ declare class OctavusChat {
     private setMessages;
     private setStatus;
     private setError;
+    private updatePendingClientToolsCache;
     /**
      * Trigger the agent and optionally add a user message to the chat.
      *
@@ -345,10 +478,34 @@ declare class OctavusChat {
      * ```
      */
     uploadFiles(files: FileList | File[], onProgress?: (fileIndex: number, progress: number) => void): Promise<FileReference[]>;
+    /**
+     * Internal: Submit a result for a pending tool.
+     * Called by bound submit/cancel methods on InteractiveTool.
+     */
+    private submitToolResult;
     /** Stop the current streaming and finalize any partial message */
     stop(): void;
     private handleStreamEvent;
     private updateStreamingMessage;
+    /**
+     * Emit a tool-output-available event for a client tool result.
+     */
+    private emitToolOutputAvailable;
+    /**
+     * Emit a tool-output-error event for a client tool result.
+     */
+    private emitToolOutputError;
+    /**
+     * Continue execution with collected client tool results.
+     */
+    private continueWithClientToolResults;
+    /**
+     * Handle client tool request event.
+     *
+     * IMPORTANT: Interactive tools must be registered synchronously (before any await)
+     * to avoid a race condition where the finish event is processed before tools are added.
+     */
+    private handleClientToolRequest;
 }
 
 /**
@@ -359,10 +516,22 @@ declare class OctavusChat {
  */
 declare function parseSSEStream(response: Response, signal?: AbortSignal): AsyncGenerator<StreamEvent, void, unknown>;
 
-/**
- * Request options passed to the triggerRequest function.
- */
-interface TriggerRequestOptions {
+/** Start a new trigger execution */
+interface TriggerRequest {
+    type: 'trigger';
+    triggerName: string;
+    input?: Record<string, unknown>;
+}
+/** Continue execution after client-side tool handling */
+interface ContinueRequest {
+    type: 'continue';
+    executionId: string;
+    toolResults: ToolResult[];
+}
+/** All request types supported by the HTTP transport */
+type HttpRequest = TriggerRequest | ContinueRequest;
+/** Request options passed to the request callback */
+interface HttpRequestOptions {
     /** Abort signal to cancel the request */
     signal?: AbortSignal;
 }
@@ -371,26 +540,25 @@ interface TriggerRequestOptions {
  */
 interface HttpTransportOptions {
     /**
-     * Function to make the trigger request.
-     * Called each time `send()` is invoked on the chat.
+     * Function to make requests to your backend.
+     * Receives a discriminated union with `type` to identify the request kind.
      *
-     * @param triggerName - The trigger name (e.g., 'user-message')
-     * @param input - Input parameters for the trigger
-     * @param options - Optional request options including abort signal
+     * @param request - The request payload (check `request.type` for the kind)
+     * @param options - Request options including abort signal
      * @returns Response with SSE stream body
      *
      * @example
      * ```typescript
-     * triggerRequest: (triggerName, input, options) =>
-     *   fetch('/api/octavus', {
+     * request: (payload, options) =>
+     *   fetch('/api/trigger', {
      *     method: 'POST',
      *     headers: { 'Content-Type': 'application/json' },
-     *     body: JSON.stringify({ sessionId, triggerName, input }),
+     *     body: JSON.stringify({ sessionId, ...payload }),
      *     signal: options?.signal,
-     *   }),
+     *   })
      * ```
      */
-    triggerRequest: (triggerName: string, input?: Record<string, unknown>, options?: TriggerRequestOptions) => Promise<Response>;
+    request: (request: HttpRequest, options?: HttpRequestOptions) => Promise<Response>;
 }
 /**
  * Create an HTTP transport using native fetch() and SSE parsing.
@@ -399,11 +567,11 @@ interface HttpTransportOptions {
  * @example
  * ```typescript
  * const transport = createHttpTransport({
- *   triggerRequest: (triggerName, input, options) =>
- *     fetch('/api/octavus', {
+ *   request: (payload, options) =>
+ *     fetch('/api/trigger', {
  *       method: 'POST',
  *       headers: { 'Content-Type': 'application/json' },
- *       body: JSON.stringify({ sessionId, triggerName, input }),
+ *       body: JSON.stringify({ sessionId, ...payload }),
  *       signal: options?.signal,
  *     }),
  * });
@@ -529,4 +697,4 @@ interface SocketTransportOptions {
  */
 declare function createSocketTransport(options: SocketTransportOptions): SocketTransport;
 
-export { type ChatStatus, type ConnectionState, type ConnectionStateListener, type HttpTransportOptions, OctavusChat, type OctavusChatOptions, type SocketLike, type SocketTransport, type SocketTransportOptions, type Transport, type TriggerRequestOptions, type UploadFilesOptions, type UploadUrlsResponse, type UserMessageInput, createHttpTransport, createSocketTransport, isSocketTransport, parseSSEStream, uploadFiles };
+export { type ChatStatus, type ClientToolContext, type ClientToolHandler, type ConnectionState, type ConnectionStateListener, type ContinueRequest, type HttpRequest, type HttpRequestOptions, type HttpTransportOptions, type InteractiveTool, OctavusChat, type OctavusChatOptions, type SocketLike, type SocketTransport, type SocketTransportOptions, type Transport, type TriggerRequest, type UploadFilesOptions, type UploadUrlsResponse, type UserMessageInput, createHttpTransport, createSocketTransport, isSocketTransport, parseSSEStream, uploadFiles };