@octavus/client-sdk 2.19.0 → 2.20.0

package/dist/index.d.cts

@@ -0,0 +1,884 @@
+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';
+
+/**
+ * Options for trigger execution (e.g., retry with rollback).
+ */
+interface TriggerOptions {
+    /**
+     * ID of the last message to keep in session state.
+     * Messages after this are removed before execution.
+     * Use `null` to truncate all messages (retry from empty history).
+     */
+    rollbackAfterMessageId?: string | null;
+}
+/**
+ * Transport interface for delivering events from server to client.
+ *
+ * Abstracts the connection mechanism (HTTP/SSE or WebSocket) behind a unified
+ * async iterator interface. Use `createHttpTransport` or `createSocketTransport`
+ * to create an implementation.
+ */
+interface Transport {
+    /**
+     * Trigger the agent and stream events.
+     * @param triggerName - The trigger name defined in the agent's protocol
+     * @param input - Input parameters for variable substitution
+     * @param options - Optional trigger options (e.g., rollback for retry)
+     */
+    trigger(triggerName: string, input?: Record<string, unknown>, options?: TriggerOptions): 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>;
+    /**
+     * Observe an already-active execution without triggering a new one.
+     * Returns events from the current execution.
+     *
+     * Only applicable to transports where execution happens independently of the
+     * client connection (e.g., polling). HTTP and WebSocket transports do not need
+     * to implement this.
+     */
+    observe?(): AsyncIterable<StreamEvent>;
+    /** Stop the current stream. Safe to call when no stream is active. */
+    stop(): void;
+}
+/**
+ * Connection states for socket transport.
+ *
+ * - `disconnected`: Not connected (initial state or after disconnect)
+ * - `connecting`: Connection attempt in progress
+ * - `connected`: Successfully connected and ready
+ * - `error`: Connection failed (check error in listener callback)
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * Callback for connection state changes.
+ */
+type ConnectionStateListener = (state: ConnectionState, error?: Error) => void;
+/**
+ * Socket transport with connection management capabilities.
+ *
+ * Extends the base Transport interface with methods for managing persistent
+ * WebSocket/SockJS connections. Use this when you need:
+ * - Eager connection (connect before first message)
+ * - Connection status UI indicators
+ * - Manual connection lifecycle control
+ *
+ * Created via `createSocketTransport()`.
+ */
+interface SocketTransport extends Transport {
+    /**
+     * Current connection state.
+     *
+     * - `disconnected`: Not connected (initial state)
+     * - `connecting`: Connection in progress
+     * - `connected`: Ready to send/receive
+     * - `error`: Connection failed
+     */
+    readonly connectionState: ConnectionState;
+    /**
+     * Subscribe to connection state changes.
+     *
+     * The listener is called immediately with the current state, then again
+     * whenever the state changes.
+     *
+     * @param listener - Callback invoked on state changes
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = transport.onConnectionStateChange((state, error) => {
+     *   setConnectionState(state);
+     *   if (error) setConnectionError(error);
+     * });
+     * ```
+     */
+    onConnectionStateChange(listener: ConnectionStateListener): () => void;
+    /**
+     * Eagerly establish the connection.
+     *
+     * By default, socket transport connects lazily on first `trigger()`. Call
+     * this method to establish the connection early (e.g., on component mount):
+     * - Faster first message response
+     * - Show accurate connection status in UI
+     * - Handle connection errors before user interaction
+     *
+     * Safe to call multiple times - resolves immediately if already connected.
+     *
+     * @example
+     * ```tsx
+     * useEffect(() => {
+     *   transport.connect()
+     *     .then(() => console.log('Connected'))
+     *     .catch((err) => console.error('Failed:', err));
+     *
+     *   return () => transport.disconnect();
+     * }, [transport]);
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the connection and clean up resources.
+     *
+     * The transport will reconnect automatically on next `trigger()` call.
+     */
+    disconnect(): void;
+}
+/**
+ * Check if a transport is a SocketTransport with connection management.
+ *
+ * @example
+ * ```typescript
+ * if (isSocketTransport(transport)) {
+ *   transport.connect(); // TypeScript knows this is available
+ * }
+ * ```
+ */
+declare function isSocketTransport(transport: Transport): transport is SocketTransport;
+
+/**
+ * Response from the upload URLs endpoint
+ */
+interface UploadUrlsResponse {
+    files: {
+        id: string;
+        uploadUrl: string;
+        downloadUrl: string;
+    }[];
+}
+/**
+ * Options for uploading files
+ */
+interface UploadFilesOptions {
+    /**
+     * Function to request upload URLs from the platform.
+     * Consumer apps must implement this to authenticate with the platform.
+     *
+     * @param files - Array of file metadata to request URLs for
+     * @returns Response with presigned upload and download URLs
+     *
+     * @example
+     * ```typescript
+     * requestUploadUrls: async (files) => {
+     *   const response = await fetch('/api/upload-urls', {
+     *     method: 'POST',
+     *     headers: { 'Content-Type': 'application/json' },
+     *     body: JSON.stringify({ sessionId, files }),
+     *   });
+     *   return response.json();
+     * }
+     * ```
+     */
+    requestUploadUrls: (files: {
+        filename: string;
+        mediaType: string;
+        size: number;
+    }[]) => Promise<UploadUrlsResponse>;
+    /**
+     * Callback for upload progress (0-100 per file).
+     * Called multiple times during upload with real-time progress.
+     *
+     * @param fileIndex - Index of the file being uploaded
+     * @param progress - Progress percentage (0-100)
+     */
+    onProgress?: (fileIndex: number, progress: number) => void;
+    /** Upload timeout per file in milliseconds. Default: 60000 (60s). Set to 0 to disable. */
+    timeoutMs?: number;
+    /** Max retry attempts per file after initial failure. Default: 2. Set to 0 to disable retries. */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds. Default: 1000 (1s). */
+    retryDelayMs?: number;
+}
+/**
+ * Upload files to the Octavus platform.
+ *
+ * This function:
+ * 1. Requests presigned upload URLs from the platform
+ * 2. Uploads each file directly to S3 with progress tracking
+ * 3. Returns file references that can be used in trigger input
+ *
+ * Uploads include automatic timeout (default 60s) and retry (default 2 retries)
+ * for transient failures like network errors or server issues.
+ *
+ * @param files - Files to upload (from file input or drag/drop)
+ * @param options - Upload configuration
+ * @returns Array of file references with download URLs
+ *
+ * @example
+ * ```typescript
+ * const fileRefs = await uploadFiles(fileInputRef.current.files, {
+ *   requestUploadUrls: async (files) => {
+ *     const response = await fetch('/api/upload-urls', {
+ *       method: 'POST',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       body: JSON.stringify({ sessionId, files }),
+ *     });
+ *     return response.json();
+ *   },
+ *   onProgress: (fileIndex, progress) => {
+ *     console.log(`File ${fileIndex}: ${progress}%`);
+ *   },
+ * });
+ * ```
+ */
+declare function uploadFiles(files: FileList | File[], options: UploadFilesOptions): Promise<FileReference[]>;
+
+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;
+    /**
+     * Register a file produced by this tool (e.g., a screenshot).
+     * Files are sent to the platform alongside the tool result so the LLM
+     * can see them as visual content rather than just a JSON URL.
+     */
+    addFile: (file: FileReference) => void;
+}
+/**
+ * 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.
+ */
+interface UserMessageInput {
+    /**
+     * Content of the message. Can be:
+     * - string: Creates a text part
+     * - object: Creates an object part (uses `type` field as typeName if present)
+     */
+    content?: string | Record<string, unknown>;
+    /**
+     * File attachments (shorthand). Can be:
+     * - FileList: From file input element (will be uploaded via uploadFiles)
+     * - File[]: Array of File objects (will be uploaded via uploadFiles)
+     * - FileReference[]: Already uploaded files (used directly)
+     */
+    files?: FileList | File[] | FileReference[];
+}
+interface OctavusChatOptions {
+    /**
+     * Transport for streaming events.
+     * Use `createHttpTransport` for HTTP/SSE or `createSocketTransport` for WebSocket/SockJS.
+     */
+    transport: Transport;
+    /**
+     * Function to request upload URLs from the platform.
+     * Required if you want to use file uploads with FileList/File[].
+     *
+     * @example
+     * ```typescript
+     * requestUploadUrls: async (files) => {
+     *   const response = await fetch('/api/upload-urls', {
+     *     method: 'POST',
+     *     headers: { 'Content-Type': 'application/json' },
+     *     body: JSON.stringify({ sessionId, files }),
+     *   });
+     *   return response.json();
+     * }
+     * ```
+     */
+    requestUploadUrls?: UploadFilesOptions['requestUploadUrls'];
+    /** Upload timeout and retry configuration. Defaults: 60s timeout, 2 retries, 1s delay. */
+    uploadOptions?: Pick<UploadFilesOptions, 'timeoutMs' | 'maxRetries' | 'retryDelayMs'>;
+    /**
+     * 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.
+     * 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 */
+    onStop?: () => void;
+    /** Callback when a resource is updated */
+    onResourceUpdate?: (name: string, value: unknown) => void;
+    /**
+     * Callback when execution starts with the session/execution ID.
+     * Useful for tracking the current execution for activity logs.
+     *
+     * @example
+     * ```typescript
+     * onStart: (sessionId) => {
+     *   setCurrentSessionId(sessionId);
+     * }
+     * ```
+     */
+    onStart?: (sessionId: string) => void;
+}
+type Listener = () => void;
+/**
+ * Framework-agnostic chat client for Octavus agents.
+ * Manages chat state and streaming, allowing reactive frameworks to subscribe to updates.
+ *
+ * @example HTTP transport (Next.js, etc.)
+ * ```typescript
+ * import { OctavusChat, createHttpTransport } from '@octavus/client-sdk';
+ *
+ * const chat = new OctavusChat({
+ *   transport: createHttpTransport({
+ *     request: (payload, options) =>
+ *       fetch('/api/trigger', {
+ *         method: 'POST',
+ *         headers: { 'Content-Type': 'application/json' },
+ *         body: JSON.stringify({ sessionId, ...payload }),
+ *         signal: options?.signal,
+ *       }),
+ *   }),
+ * });
+ * ```
+ *
+ * @example Socket transport (WebSocket, SockJS, Meteor)
+ * ```typescript
+ * import { OctavusChat, createSocketTransport } from '@octavus/client-sdk';
+ *
+ * const chat = new OctavusChat({
+ *   transport: createSocketTransport({
+ *     connect: () => new Promise((resolve, reject) => {
+ *       const ws = new WebSocket(`wss://api.octavus.ai/stream?sessionId=${sessionId}`);
+ *       ws.onopen = () => resolve(ws);
+ *       ws.onerror = () => reject(new Error('Connection failed'));
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+declare class OctavusChat {
+    private _messages;
+    private _status;
+    private _error;
+    private options;
+    private transport;
+    private streamingState;
+    private _pendingToolsByName;
+    private _pendingToolsByCallId;
+    private _pendingClientToolsCache;
+    private _completedToolResults;
+    private _clientToolAbortController;
+    private _serverToolResults;
+    private _pendingExecutionId;
+    private _readyToContinue;
+    private _finishEventReceived;
+    private _rollbackSynced;
+    private _lastTrigger;
+    private listeners;
+    constructor(options: OctavusChatOptions);
+    /**
+     * Update mutable options (callbacks and tool handlers) without recreating the instance.
+     * Used by the React hook to keep options fresh across renders, but can also be
+     * called directly by non-React consumers.
+     *
+     * `transport` and `initialMessages` are excluded since they're only consumed at construction time.
+     */
+    updateOptions(updates: Partial<Omit<OctavusChatOptions, 'transport' | 'initialMessages'>>): void;
+    get messages(): UIMessage[];
+    get status(): ChatStatus;
+    /**
+     * 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[]>;
+    /**
+     * Whether `retry()` can be called.
+     * True when a trigger has been sent and the chat is not currently streaming or awaiting input.
+     */
+    get canRetry(): boolean;
+    /**
+     * Replace the message list with externally-provided messages.
+     *
+     * Use this to sync with server-authoritative state (e.g., after an execution
+     * completes or when an observer detects new messages from another client).
+     *
+     * Must NOT be called while streaming — only when status is `idle` or `error`.
+     */
+    replaceMessages(messages: UIMessage[]): void;
+    /**
+     * Subscribe to state changes. The callback is called whenever messages, status, or error changes.
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: Listener): () => void;
+    private notifyListeners;
+    private setMessages;
+    private setStatus;
+    private setError;
+    private updatePendingClientToolsCache;
+    /**
+     * Trigger the agent and optionally add a user message to the chat.
+     *
+     * @param triggerName - The trigger name defined in the agent's protocol.yaml
+     * @param input - Input parameters for the trigger (variable substitutions)
+     * @param options.userMessage - If provided, adds a user message to the chat before triggering
+     *
+     * @example Send a text message
+     * ```typescript
+     * await chat.send('user-message',
+     *   { USER_MESSAGE: message },
+     *   { userMessage: { content: message } }
+     * );
+     * ```
+     *
+     * @example Send a message with file attachments
+     * ```typescript
+     * await chat.send('user-message',
+     *   { USER_MESSAGE: message, FILES: fileRefs },
+     *   { userMessage: { content: message, files: fileRefs } }
+     * );
+     * ```
+     */
+    send(triggerName: string, input?: Record<string, unknown>, sendOptions?: {
+        userMessage?: UserMessageInput;
+    }): Promise<void>;
+    /**
+     * Retry the last trigger from the same starting point.
+     * Rolls back messages to the state before the last trigger, re-adds the user message
+     * (if any), and re-executes. Files are not re-uploaded.
+     *
+     * No-op if no trigger has been sent yet.
+     *
+     * @example
+     * ```typescript
+     * // After an error or unsatisfactory result
+     * if (chat.canRetry) {
+     *   await chat.retry();
+     * }
+     * ```
+     */
+    retry(): Promise<void>;
+    /**
+     * Observe an already-active execution without triggering a new one.
+     *
+     * Only supported by transports that implement `observe()` (e.g., polling transport).
+     * Use this when the page loads and the session is already streaming — the transport
+     * will start consuming events without dispatching a new trigger.
+     *
+     * When using with `initialMessages`, exclude any in-progress assistant message
+     * from the initial messages to avoid duplication — the event stream will rebuild it.
+     */
+    observe(): Promise<void>;
+    private _executeTrigger;
+    /**
+     * Shared streaming logic for `send()`, `retry()`, and `observe()`.
+     * Sets up streaming state, consumes an event stream, and handles errors.
+     */
+    private _consumeStream;
+    /**
+     * Upload files directly without sending a message.
+     * Useful for showing upload progress before sending.
+     *
+     * @param files - Files to upload
+     * @param onProgress - Optional progress callback
+     * @returns Array of file references
+     *
+     * @example
+     * ```typescript
+     * const fileRefs = await chat.uploadFiles(fileInput.files, (i, progress) => {
+     *   console.log(`File ${i}: ${progress}%`);
+     * });
+     * // Later...
+     * await chat.send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });
+     * ```
+     */
+    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;
+    /**
+     * IMMUTABILITY RULES — all event handlers must follow these patterns:
+     *
+     * 1. Never mutate an existing part/message object. Some environments (e.g.
+     *    React Native with Reanimated) freeze objects between renders, so
+     *    mutations silently fail or throw.
+     *
+     * 2. Always create a new object via spread and assign it back:
+     *      GOOD: state.parts[i] = { ...part, text: part.text + delta };
+     *       BAD: part.text += delta; state.parts[i] = { ...part };
+     *
+     * 3. For nested worker parts, copy the parts array too:
+     *      const updatedParts = [...workerPart.parts];
+     *      updatedParts[i] = { ...part, status: 'done' };
+     *      state.parts[wi] = { ...workerPart, parts: updatedParts };
+     *
+     * 4. For the messages array, copy before mutating:
+     *      const messages = [...this._messages];
+     *      messages[i] = newMessage;   // or messages.pop()
+     *      this.setMessages(messages);
+     */
+    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;
+}
+
+/**
+ * Parse SSE stream events.
+ *
+ * @param response - The HTTP response with SSE body
+ * @param signal - Optional abort signal to cancel reading
+ */
+declare function parseSSEStream(response: Response, signal?: AbortSignal): AsyncGenerator<StreamEvent, void, unknown>;
+
+/** Start a new trigger execution */
+interface TriggerRequest {
+    type: 'trigger';
+    triggerName: string;
+    input?: Record<string, unknown>;
+    rollbackAfterMessageId?: string | null;
+}
+/** 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;
+}
+/**
+ * Options for creating an HTTP transport.
+ */
+interface HttpTransportOptions {
+    /**
+     * Function to make requests to your backend.
+     * Receives a discriminated union with `type` to identify the request kind.
+     *
+     * @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
+     * request: (payload, options) =>
+     *   fetch('/api/trigger', {
+     *     method: 'POST',
+     *     headers: { 'Content-Type': 'application/json' },
+     *     body: JSON.stringify({ sessionId, ...payload }),
+     *     signal: options?.signal,
+     *   })
+     * ```
+     */
+    request: (request: HttpRequest, options?: HttpRequestOptions) => Promise<Response>;
+}
+/**
+ * Create an HTTP transport using native fetch() and SSE parsing.
+ * This is the default transport for Next.js and other HTTP-based applications.
+ *
+ * @example
+ * ```typescript
+ * const transport = createHttpTransport({
+ *   request: (payload, options) =>
+ *     fetch('/api/trigger', {
+ *       method: 'POST',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       body: JSON.stringify({ sessionId, ...payload }),
+ *       signal: options?.signal,
+ *     }),
+ * });
+ * ```
+ */
+declare function createHttpTransport(options: HttpTransportOptions): Transport;
+
+/**
+ * Socket interface compatible with both WebSocket and SockJS.
+ *
+ * Uses MessageEvent for the message handler, which both WebSocket and SockJS support.
+ * The `| undefined` union accommodates SockJS's optional property typing.
+ */
+interface SocketLike {
+    send(data: string): void;
+    close(): void;
+    readyState: number;
+    onmessage: ((event: MessageEvent) => void) | null | undefined;
+    onclose: ((event: CloseEvent) => void) | null | undefined;
+}
+/**
+ * Options for creating a socket transport.
+ */
+interface SocketTransportOptions {
+    /**
+     * Function to create and connect the socket.
+     * Works directly with WebSocket and SockJS - no wrappers needed.
+     *
+     * @example Native WebSocket
+     * ```typescript
+     * connect: () => new Promise((resolve, reject) => {
+     *   const ws = new WebSocket('wss://api.example.com/stream?sessionId=xxx');
+     *   ws.onopen = () => resolve(ws);
+     *   ws.onerror = () => reject(new Error('Connection failed'));
+     * })
+     * ```
+     *
+     * @example SockJS
+     * ```typescript
+     * connect: () => new Promise((resolve, reject) => {
+     *   const sock = new SockJS('/chat-service');
+     *   sock.onopen = () => resolve(sock);
+     *   sock.onerror = () => reject(new Error('Connection failed'));
+     * })
+     * ```
+     */
+    connect: () => Promise<SocketLike>;
+    /**
+     * Called for every message received (parsed as JSON).
+     * Use this to handle custom (non-Octavus) events.
+     * Octavus StreamEvents are handled automatically by the transport.
+     *
+     * @example
+     * ```typescript
+     * onMessage: (data) => {
+     *   const msg = data as { type: string };
+     *   if (msg.type === 'typing-indicator') {
+     *     setIsTyping(true);
+     *   }
+     *   if (msg.type === 'presence-update') {
+     *     updatePresence(msg.users);
+     *   }
+     * }
+     * ```
+     */
+    onMessage?: (data: unknown) => void;
+    /**
+     * Called when the socket connection closes.
+     * Use this for cleanup or reconnection logic.
+     */
+    onClose?: () => void;
+}
+/**
+ * Create a socket transport that works with any WebSocket-like connection.
+ * Supports native WebSocket, SockJS, or any compatible socket implementation.
+ *
+ * The server should send StreamEvent format (same as SSE) over the socket.
+ * Unknown events are safely ignored using Zod validation.
+ *
+ * ## Connection Lifecycle
+ *
+ * By default, the socket connects **lazily** on the first `send()` call.
+ * Use `connect()` to establish the connection eagerly (e.g., on component mount):
+ *
+ * ```typescript
+ * // Eager connection for UI status indicators
+ * useEffect(() => {
+ *   transport.connect()
+ *     .then(() => console.log('Connected'))
+ *     .catch((err) => console.error('Failed:', err));
+ *
+ *   return () => transport.disconnect();
+ * }, [transport]);
+ * ```
+ *
+ * @example Basic usage with WebSocket
+ * ```typescript
+ * const transport = createSocketTransport({
+ *   connect: () => new Promise((resolve, reject) => {
+ *     const ws = new WebSocket(`wss://api.octavus.ai/stream?sessionId=${sessionId}`);
+ *     ws.onopen = () => resolve(ws);
+ *     ws.onerror = () => reject(new Error('Connection failed'));
+ *   }),
+ * });
+ * ```
+ *
+ * @example With SockJS and connection state
+ * ```typescript
+ * const transport = createSocketTransport({
+ *   connect: () => new Promise((resolve, reject) => {
+ *     const sock = new SockJS('/octavus-stream');
+ *     sock.onopen = () => resolve(sock);
+ *     sock.onerror = () => reject(new Error('Connection failed'));
+ *   }),
+ * });
+ *
+ * // Subscribe to connection state changes
+ * transport.onConnectionStateChange((state, error) => {
+ *   setConnectionState(state);
+ *   if (error) setConnectionError(error);
+ * });
+ * ```
+ */
+declare function createSocketTransport(options: SocketTransportOptions): SocketTransport;
+
+interface PollResult {
+    events: unknown[];
+    cursor: number;
+    status: 'idle' | 'streaming' | 'error';
+}
+/**
+ * Options for creating a polling transport.
+ */
+interface PollingTransportOptions {
+    /**
+     * Dispatch a trigger to the backend.
+     * Called when `send()` initiates a new execution.
+     * Return `{ error }` to surface the error to the chat.
+     */
+    onTrigger: (triggerName: string, input?: Record<string, unknown>) => Promise<{
+        error?: string;
+    }>;
+    /**
+     * Poll for execution events.
+     * Called repeatedly during streaming at `pollIntervalMs` intervals.
+     * The cursor tracks read position — pass 0 on first call.
+     */
+    onPoll: (cursor: number) => Promise<PollResult>;
+    /** Called when the user stops the execution. */
+    onStop: () => void;
+    /** Milliseconds between poll calls. Defaults to 500. */
+    pollIntervalMs?: number;
+}
+/**
+ * Create a polling transport for backends that use a poll-based event delivery
+ * model instead of SSE or WebSocket streaming.
+ *
+ * The transport dispatches a trigger via `onTrigger`, then polls `onPoll` at
+ * a fixed interval, yielding events as they arrive. From `OctavusChat`'s
+ * perspective this looks identical to an SSE stream.
+ *
+ * Supports `observe()` for resuming observation of an already-active execution
+ * (e.g., after a page refresh while the agent is streaming). `observe()` skips
+ * the trigger and goes straight to polling.
+ *
+ * @example
+ * ```typescript
+ * const transport = createPollingTransport({
+ *   onTrigger: (triggerName, input) => triggerServerAction(input?.USER_MESSAGE),
+ *   onPoll: (cursor) => pollServerAction(cursor),
+ *   onStop: () => stopServerAction(),
+ * });
+ *
+ * const { send, messages } = useOctavusChat({ transport });
+ * ```
+ */
+declare function createPollingTransport(options: PollingTransportOptions): Transport;
+
+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 PollResult, type PollingTransportOptions, type SocketLike, type SocketTransport, type SocketTransportOptions, type Transport, type TriggerOptions, type TriggerRequest, type UploadFilesOptions, type UploadUrlsResponse, type UserMessageInput, createHttpTransport, createPollingTransport, createSocketTransport, isSocketTransport, parseSSEStream, uploadFiles };