@octavus/client-sdk 1.0.0 → 2.1.0

package/README.md

@@ -21,11 +21,11 @@ import { OctavusChat, createHttpTransport } from '@octavus/client-sdk';
 
 // Create transport
 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,
     }),
 });
@@ -56,11 +56,11 @@ Best for Next.js, Express, and HTTP-based applications:
 import { createHttpTransport } from '@octavus/client-sdk';
 
 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,
     }),
 });

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { StreamEvent, FileReference, UIMessage, OctavusError } from '@octavus/core';
+import { StreamEvent, ToolResult, FileReference, UIMessage, OctavusError } from '@octavus/core';
 export * 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.
@@ -15,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;
 }
@@ -190,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.
@@ -233,6 +285,35 @@ 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[];
     /**
@@ -275,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,
  *       }),
  *   }),
  * });
@@ -306,6 +389,14 @@ declare class OctavusChat {
     private options;
     private transport;
     private streamingState;
+    private _pendingToolsByName;
+    private _pendingToolsByCallId;
+    private _pendingClientToolsCache;
+    private _completedToolResults;
+    private _clientToolAbortController;
+    private _serverToolResults;
+    private _pendingExecutionId;
+    private _readyToContinue;
     private listeners;
     constructor(options: OctavusChatOptions);
     get messages(): UIMessage[];
@@ -315,6 +406,25 @@ declare class OctavusChat {
      * 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
@@ -324,6 +434,7 @@ declare class OctavusChat {
     private setMessages;
     private setStatus;
     private setError;
+    private updatePendingClientToolsCache;
     /**
      * Trigger the agent and optionally add a user message to the chat.
      *
@@ -368,10 +479,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;
 }
 
 /**
@@ -382,10 +517,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;
 }
@@ -394,26 +541,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.
@@ -422,11 +568,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,
  *     }),
  * });
@@ -552,4 +698,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 };