@octavus/react 2.19.0 → 2.21.0

package/dist/index.cjs

@@ -0,0 +1,240 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AppError: () => import_client_sdk2.AppError,
+  ConflictError: () => import_client_sdk2.ConflictError,
+  ForbiddenError: () => import_client_sdk2.ForbiddenError,
+  MAIN_THREAD: () => import_client_sdk2.MAIN_THREAD,
+  NotFoundError: () => import_client_sdk2.NotFoundError,
+  OCTAVUS_SKILL_TOOLS: () => import_client_sdk2.OCTAVUS_SKILL_TOOLS,
+  OctavusChat: () => import_client_sdk2.OctavusChat,
+  OctavusError: () => import_client_sdk2.OctavusError,
+  ValidationError: () => import_client_sdk2.ValidationError,
+  createApiErrorEvent: () => import_client_sdk2.createApiErrorEvent,
+  createErrorEvent: () => import_client_sdk2.createErrorEvent,
+  createHttpTransport: () => import_client_sdk2.createHttpTransport,
+  createInternalErrorEvent: () => import_client_sdk2.createInternalErrorEvent,
+  createPollingTransport: () => import_client_sdk2.createPollingTransport,
+  createSocketTransport: () => import_client_sdk2.createSocketTransport,
+  errorToStreamEvent: () => import_client_sdk2.errorToStreamEvent,
+  generateId: () => import_client_sdk2.generateId,
+  getSkillSlugFromToolCall: () => import_client_sdk2.getSkillSlugFromToolCall,
+  isAbortError: () => import_client_sdk2.isAbortError,
+  isAuthenticationError: () => import_client_sdk2.isAuthenticationError,
+  isFileReference: () => import_client_sdk2.isFileReference,
+  isFileReferenceArray: () => import_client_sdk2.isFileReferenceArray,
+  isMainThread: () => import_client_sdk2.isMainThread,
+  isOctavusSkillTool: () => import_client_sdk2.isOctavusSkillTool,
+  isOtherThread: () => import_client_sdk2.isOtherThread,
+  isProviderError: () => import_client_sdk2.isProviderError,
+  isRateLimitError: () => import_client_sdk2.isRateLimitError,
+  isRetryableError: () => import_client_sdk2.isRetryableError,
+  isSocketTransport: () => import_client_sdk2.isSocketTransport,
+  isToolError: () => import_client_sdk2.isToolError,
+  isValidationError: () => import_client_sdk2.isValidationError,
+  parseSSEStream: () => import_client_sdk2.parseSSEStream,
+  resolveThread: () => import_client_sdk2.resolveThread,
+  safeParseStreamEvent: () => import_client_sdk2.safeParseStreamEvent,
+  safeParseUIMessage: () => import_client_sdk2.safeParseUIMessage,
+  safeParseUIMessages: () => import_client_sdk2.safeParseUIMessages,
+  threadForPart: () => import_client_sdk2.threadForPart,
+  uploadFiles: () => import_client_sdk2.uploadFiles,
+  useAutoScroll: () => useAutoScroll,
+  useOctavusChat: () => useOctavusChat
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hooks/use-octavus-chat.ts
+var import_react = require("react");
+var import_client_sdk = require("@octavus/client-sdk");
+function useOctavusChat(options) {
+  const chatRef = (0, import_react.useRef)(null);
+  const transportRef = (0, import_react.useRef)(null);
+  const [sessionId, setSessionId] = (0, import_react.useState)(null);
+  const sessionIdSetterRef = (0, import_react.useRef)(setSessionId);
+  sessionIdSetterRef.current = setSessionId;
+  if (transportRef.current !== options.transport) {
+    chatRef.current?.stop();
+    setSessionId(null);
+    chatRef.current = new import_client_sdk.OctavusChat(options);
+    transportRef.current = options.transport;
+  }
+  const chat = chatRef.current;
+  chat.updateOptions({
+    clientTools: options.clientTools,
+    onError: options.onError,
+    onFinish: options.onFinish,
+    onStop: options.onStop,
+    onResourceUpdate: options.onResourceUpdate,
+    onStart: (id) => {
+      sessionIdSetterRef.current(id);
+      options.onStart?.(id);
+    },
+    requestUploadUrls: options.requestUploadUrls,
+    uploadOptions: options.uploadOptions
+  });
+  const transport = options.transport;
+  const subscribe = (0, import_react.useCallback)((callback) => chat.subscribe(callback), [chat]);
+  const getMessagesSnapshot = (0, import_react.useCallback)(() => chat.messages, [chat]);
+  const getStatusSnapshot = (0, import_react.useCallback)(() => chat.status, [chat]);
+  const getErrorSnapshot = (0, import_react.useCallback)(() => chat.error, [chat]);
+  const getPendingClientToolsSnapshot = (0, import_react.useCallback)(() => chat.pendingClientTools, [chat]);
+  const getCanRetrySnapshot = (0, import_react.useCallback)(() => chat.canRetry, [chat]);
+  const messages = (0, import_react.useSyncExternalStore)(subscribe, getMessagesSnapshot, getMessagesSnapshot);
+  const status = (0, import_react.useSyncExternalStore)(subscribe, getStatusSnapshot, getStatusSnapshot);
+  const error = (0, import_react.useSyncExternalStore)(subscribe, getErrorSnapshot, getErrorSnapshot);
+  const pendingClientTools = (0, import_react.useSyncExternalStore)(
+    subscribe,
+    getPendingClientToolsSnapshot,
+    getPendingClientToolsSnapshot
+  );
+  const canRetry = (0, import_react.useSyncExternalStore)(subscribe, getCanRetrySnapshot, getCanRetrySnapshot);
+  const socketTransport = (0, import_client_sdk.isSocketTransport)(transport) ? transport : null;
+  const [connectionState, setConnectionState] = (0, import_react.useState)(
+    socketTransport?.connectionState
+  );
+  const [connectionError, setConnectionError] = (0, import_react.useState)(void 0);
+  (0, import_react.useEffect)(() => {
+    if (!socketTransport) {
+      setConnectionState(void 0);
+      setConnectionError(void 0);
+      return;
+    }
+    const unsubscribe = socketTransport.onConnectionStateChange((state, err) => {
+      setConnectionState(state);
+      setConnectionError(err);
+    });
+    return unsubscribe;
+  }, [socketTransport]);
+  const send = (0, import_react.useCallback)(
+    (triggerName, input, sendOptions) => chat.send(triggerName, input, sendOptions),
+    [chat]
+  );
+  const stop = (0, import_react.useCallback)(() => chat.stop(), [chat]);
+  const retry = (0, import_react.useCallback)(() => chat.retry(), [chat]);
+  const observe = (0, import_react.useCallback)(() => chat.observe(), [chat]);
+  const replaceMessages = (0, import_react.useCallback)((msgs) => chat.replaceMessages(msgs), [chat]);
+  const uploadFiles2 = (0, import_react.useCallback)(
+    (files, onProgress) => chat.uploadFiles(files, onProgress),
+    [chat]
+  );
+  const connect = (0, import_react.useCallback)(
+    () => socketTransport?.connect() ?? Promise.resolve(),
+    [socketTransport]
+  );
+  const disconnect = (0, import_react.useCallback)(() => socketTransport?.disconnect(), [socketTransport]);
+  return {
+    messages,
+    status,
+    error,
+    sessionId,
+    connectionState,
+    connectionError,
+    pendingClientTools,
+    send,
+    stop,
+    retry,
+    observe,
+    replaceMessages,
+    canRetry,
+    connect: socketTransport ? connect : void 0,
+    disconnect: socketTransport ? disconnect : void 0,
+    uploadFiles: uploadFiles2
+  };
+}
+
+// src/hooks/use-auto-scroll.ts
+var import_react2 = require("react");
+var DEFAULT_THRESHOLD_PX = 80;
+function useAutoScroll(options = {}) {
+  const internalRef = (0, import_react2.useRef)(null);
+  const scrollRef = options.scrollRef ?? internalRef;
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD_PX;
+  const shouldAutoScrollRef = (0, import_react2.useRef)(true);
+  const handleScroll = (0, import_react2.useCallback)(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    shouldAutoScrollRef.current = distanceFromBottom <= threshold;
+  }, [scrollRef, threshold]);
+  const scrollOnUpdate = (0, import_react2.useCallback)(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    if (shouldAutoScrollRef.current) {
+      el.scrollTop = el.scrollHeight;
+      return;
+    }
+    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    shouldAutoScrollRef.current = distanceFromBottom <= threshold;
+  }, [scrollRef, threshold]);
+  const resetAutoScroll = (0, import_react2.useCallback)(() => {
+    shouldAutoScrollRef.current = true;
+  }, []);
+  return { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll };
+}
+
+// src/index.ts
+var import_client_sdk2 = require("@octavus/client-sdk");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppError,
+  ConflictError,
+  ForbiddenError,
+  MAIN_THREAD,
+  NotFoundError,
+  OCTAVUS_SKILL_TOOLS,
+  OctavusChat,
+  OctavusError,
+  ValidationError,
+  createApiErrorEvent,
+  createErrorEvent,
+  createHttpTransport,
+  createInternalErrorEvent,
+  createPollingTransport,
+  createSocketTransport,
+  errorToStreamEvent,
+  generateId,
+  getSkillSlugFromToolCall,
+  isAbortError,
+  isAuthenticationError,
+  isFileReference,
+  isFileReferenceArray,
+  isMainThread,
+  isOctavusSkillTool,
+  isOtherThread,
+  isProviderError,
+  isRateLimitError,
+  isRetryableError,
+  isSocketTransport,
+  isToolError,
+  isValidationError,
+  parseSSEStream,
+  resolveThread,
+  safeParseStreamEvent,
+  safeParseUIMessage,
+  safeParseUIMessages,
+  threadForPart,
+  uploadFiles,
+  useAutoScroll,
+  useOctavusChat
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/hooks/use-octavus-chat.ts","../src/hooks/use-auto-scroll.ts"],"sourcesContent":["export {\n  useOctavusChat,\n  type UseOctavusChatReturn,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from './hooks/use-octavus-chat';\n\nexport { useAutoScroll, type UseAutoScrollOptions } from './hooks/use-auto-scroll';\n\nexport type * from '@octavus/client-sdk';\nexport {\n  // Chat\n  OctavusChat,\n  // Files\n  uploadFiles,\n  // Stream\n  parseSSEStream,\n  // Transports\n  createHttpTransport,\n  createSocketTransport,\n  isSocketTransport,\n  createPollingTransport,\n  // Error classes\n  AppError,\n  NotFoundError,\n  ValidationError,\n  ConflictError,\n  ForbiddenError,\n  OctavusError,\n  // Error type guards\n  isRateLimitError,\n  isAuthenticationError,\n  isProviderError,\n  isToolError,\n  isRetryableError,\n  isValidationError,\n  // Error event helpers\n  createErrorEvent,\n  errorToStreamEvent,\n  createInternalErrorEvent,\n  createApiErrorEvent,\n  // Utilities\n  generateId,\n  isAbortError,\n  // Thread helpers\n  MAIN_THREAD,\n  resolveThread,\n  isMainThread,\n  threadForPart,\n  isOtherThread,\n  // Type guards\n  isFileReference,\n  isFileReferenceArray,\n  // Safe parse helpers\n  safeParseStreamEvent,\n  safeParseUIMessage,\n  safeParseUIMessages,\n  // Skills\n  OCTAVUS_SKILL_TOOLS,\n  isOctavusSkillTool,\n  getSkillSlugFromToolCall,\n} from '@octavus/client-sdk';\n","'use client';\n\nimport { useRef, useCallback, useSyncExternalStore, useState, useEffect } from 'react';\nimport {\n  OctavusChat,\n  type OctavusError,\n  isSocketTransport,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type UIMessage,\n  type Transport,\n  type ConnectionState,\n  type FileReference,\n  type UploadFilesOptions,\n  type UploadUrlsResponse,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from '@octavus/client-sdk';\n\nexport type {\n  OctavusChatOptions,\n  ChatStatus,\n  UserMessageInput,\n  FileReference,\n  UploadFilesOptions,\n  UploadUrlsResponse,\n  ClientToolContext,\n  ClientToolHandler,\n  InteractiveTool,\n};\n\nexport interface UseOctavusChatReturn {\n  /** All messages including the currently streaming one */\n  messages: UIMessage[];\n  /** Current status of the chat */\n  status: ChatStatus;\n  /**\n   * Error if status is 'error'.\n   * Contains structured error information including type, source, and retryability.\n   * Use type guards like `isRateLimitError()` or `isProviderError()` to check specific error types.\n   */\n  error: OctavusError | null;\n  /**\n   * The current session/execution ID from the most recent `send()` call.\n   * Updated when the server responds with a `start` event containing an execution ID.\n   * Useful for tracking activity logs or debugging.\n   *\n   * For workers, this is the execution ID. For interactive sessions, this is the session ID.\n   */\n  sessionId: string | null;\n  /**\n   * Socket connection state (socket transport only).\n   * For HTTP transport, this is always `undefined`.\n   *\n   * - `disconnected`: Not connected (initial state before first send)\n   * - `connecting`: Connection attempt in progress\n   * - `connected`: Successfully connected\n   * - `error`: Connection failed (check `connectionError`)\n   */\n  connectionState: ConnectionState | undefined;\n  /**\n   * Connection error if `connectionState` is 'error'.\n   */\n  connectionError: Error | undefined;\n  /**\n   * Pending interactive tool calls keyed by tool name.\n   * Each tool has bound `submit()` and `cancel()` methods.\n   *\n   * @example\n   * ```tsx\n   * const feedbackTools = pendingClientTools['request-feedback'] ?? [];\n   *\n   * {feedbackTools.map(tool => (\n   *   <FeedbackModal\n   *     key={tool.toolCallId}\n   *     {...tool.args}\n   *     onSubmit={(result) => tool.submit(result)}\n   *     onCancel={() => tool.cancel()}\n   *   />\n   * ))}\n   * ```\n   */\n  pendingClientTools: Record<string, InteractiveTool[]>;\n  /**\n   * Trigger the agent and optionally add a user message to the chat.\n   *\n   * @param triggerName - The trigger name defined in the agent's protocol.yaml\n   * @param input - Input parameters for the trigger (variable substitutions)\n   * @param options.userMessage - If provided, adds a user message to the chat before triggering\n   */\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput },\n  ) => Promise<void>;\n  /** Stop the current streaming and finalize any partial message */\n  stop: () => void;\n  /**\n   * Retry the last trigger from the same starting point.\n   * Rolls back messages, re-adds the user message (if any), and re-executes.\n   * No-op if no trigger has been sent yet.\n   */\n  retry: () => Promise<void>;\n  /**\n   * Observe an already-active execution without triggering a new one.\n   * Only works with transports that support `observe()` (e.g., polling transport).\n   * Use when the page loads and the session is already streaming.\n   */\n  observe: () => Promise<void>;\n  /**\n   * Replace the message list with externally-provided messages.\n   * Use to sync with server-authoritative state (e.g., multi-observer scenarios).\n   * Must NOT be called while streaming.\n   */\n  replaceMessages: (messages: UIMessage[]) => void;\n  /**\n   * Whether `retry()` can be called.\n   * True when a trigger has been sent and the chat is not currently streaming or awaiting input.\n   */\n  canRetry: boolean;\n  /**\n   * Eagerly connect to the socket (socket transport only).\n   * Returns a promise that resolves when connected or rejects on error.\n   * Safe to call multiple times - subsequent calls resolve immediately if already connected.\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  connect: (() => Promise<void>) | undefined;\n  /**\n   * Disconnect the socket (socket transport only).\n   * The transport will reconnect automatically on next send().\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  disconnect: (() => void) | undefined;\n  /**\n   * Upload files directly without sending a message.\n   * Useful for showing upload progress before sending.\n   *\n   * @param files - Files to upload\n   * @param onProgress - Optional progress callback\n   * @returns Array of file references\n   *\n   * @example\n   * ```typescript\n   * const fileRefs = await uploadFiles(fileInput.files, (i, progress) => {\n   *   console.log(`File ${i}: ${progress}%`);\n   * });\n   * // Later...\n   * await send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });\n   * ```\n   */\n  uploadFiles: (\n    files: FileList | File[],\n    onProgress?: (fileIndex: number, progress: number) => void,\n  ) => Promise<FileReference[]>;\n}\n\n/**\n * React hook for interacting with Octavus agents.\n * Provides chat state management and streaming support.\n *\n * When the transport changes (e.g., sessionId changes), the hook automatically\n * reinitializes with a fresh chat instance. Use `initialMessages` if you need\n * to preserve messages across transport changes.\n *\n * @example Basic usage with HTTP transport\n * ```tsx\n * import { useOctavusChat, createHttpTransport } from '@octavus/react';\n *\n * function Chat({ sessionId }) {\n *   const transport = useMemo(\n *     () => createHttpTransport({\n *       request: (payload, options) =>\n *         fetch('/api/trigger', {\n *           method: 'POST',\n *           headers: { 'Content-Type': 'application/json' },\n *           body: JSON.stringify({ sessionId, ...payload }),\n *           signal: options?.signal,\n *         }),\n *     }),\n *     [sessionId],\n *   );\n *\n *   const { messages, status, send } = useOctavusChat({ transport });\n *\n *   return (\n *     <div>\n *       {messages.map((msg) => (\n *         <Message key={msg.id} message={msg} />\n *       ))}\n *       <button onClick={() => send('user-message', { USER_MESSAGE: 'Hello' })}>\n *         Send\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example Socket transport with eager connection\n * ```tsx\n * import { useOctavusChat, createSocketTransport } from '@octavus/react';\n *\n * function Chat() {\n *   const transport = useMemo(\n *     () => createSocketTransport({\n *       connect: () => new Promise((resolve, reject) => {\n *         const sock = new SockJS('/octavus');\n *         sock.onopen = () => resolve(sock);\n *         sock.onerror = () => reject(new Error('Connection failed'));\n *       }),\n *     }),\n *     [],\n *   );\n *\n *   const { messages, status, send, connectionState, connect, disconnect } =\n *     useOctavusChat({ transport });\n *\n *   // Eager connection on mount\n *   useEffect(() => {\n *     connect?.();\n *     return () => disconnect?.();\n *   }, [connect, disconnect]);\n *\n *   return (\n *     <div>\n *       <StatusIndicator state={connectionState} />\n *       {messages.map((msg) => <Message key={msg.id} message={msg} />)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn {\n  const chatRef = useRef<OctavusChat | null>(null);\n  const transportRef = useRef<Transport | null>(null);\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  const sessionIdSetterRef = useRef(setSessionId);\n  sessionIdSetterRef.current = setSessionId;\n\n  if (transportRef.current !== options.transport) {\n    chatRef.current?.stop();\n    setSessionId(null);\n    chatRef.current = new OctavusChat(options);\n    transportRef.current = options.transport;\n  }\n\n  const chat = chatRef.current!;\n\n  // Keep all mutable options (callbacks, tool handlers) fresh on every render.\n  // This ensures handlers always reference the latest closures instead of going stale.\n  chat.updateOptions({\n    clientTools: options.clientTools,\n    onError: options.onError,\n    onFinish: options.onFinish,\n    onStop: options.onStop,\n    onResourceUpdate: options.onResourceUpdate,\n    onStart: (id) => {\n      sessionIdSetterRef.current(id);\n      options.onStart?.(id);\n    },\n    requestUploadUrls: options.requestUploadUrls,\n    uploadOptions: options.uploadOptions,\n  });\n  const transport = options.transport;\n\n  const subscribe = useCallback((callback: () => void) => chat.subscribe(callback), [chat]);\n  const getMessagesSnapshot = useCallback(() => chat.messages, [chat]);\n  const getStatusSnapshot = useCallback(() => chat.status, [chat]);\n  const getErrorSnapshot = useCallback(() => chat.error, [chat]);\n  const getPendingClientToolsSnapshot = useCallback(() => chat.pendingClientTools, [chat]);\n  const getCanRetrySnapshot = useCallback(() => chat.canRetry, [chat]);\n\n  const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);\n  const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);\n  const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);\n  const pendingClientTools = useSyncExternalStore(\n    subscribe,\n    getPendingClientToolsSnapshot,\n    getPendingClientToolsSnapshot,\n  );\n  const canRetry = useSyncExternalStore(subscribe, getCanRetrySnapshot, getCanRetrySnapshot);\n\n  const socketTransport = isSocketTransport(transport) ? transport : null;\n  const [connectionState, setConnectionState] = useState<ConnectionState | undefined>(\n    socketTransport?.connectionState,\n  );\n  const [connectionError, setConnectionError] = useState<Error | undefined>(undefined);\n\n  useEffect(() => {\n    if (!socketTransport) {\n      setConnectionState(undefined);\n      setConnectionError(undefined);\n      return;\n    }\n\n    const unsubscribe = socketTransport.onConnectionStateChange((state, err) => {\n      setConnectionState(state);\n      setConnectionError(err);\n    });\n\n    return unsubscribe;\n  }, [socketTransport]);\n\n  const send = useCallback(\n    (\n      triggerName: string,\n      input?: Record<string, unknown>,\n      sendOptions?: { userMessage?: UserMessageInput },\n    ) => chat.send(triggerName, input, sendOptions),\n    [chat],\n  );\n\n  const stop = useCallback(() => chat.stop(), [chat]);\n  const retry = useCallback(() => chat.retry(), [chat]);\n  const observe = useCallback(() => chat.observe(), [chat]);\n  const replaceMessages = useCallback((msgs: UIMessage[]) => chat.replaceMessages(msgs), [chat]);\n\n  const uploadFiles = useCallback(\n    (files: FileList | File[], onProgress?: (fileIndex: number, progress: number) => void) =>\n      chat.uploadFiles(files, onProgress),\n    [chat],\n  );\n\n  // Stable references for connect/disconnect (socket transport only)\n  const connect = useCallback(\n    () => socketTransport?.connect() ?? Promise.resolve(),\n    [socketTransport],\n  );\n  const disconnect = useCallback(() => socketTransport?.disconnect(), [socketTransport]);\n\n  return {\n    messages,\n    status,\n    error,\n    sessionId,\n    connectionState,\n    connectionError,\n    pendingClientTools,\n    send,\n    stop,\n    retry,\n    observe,\n    replaceMessages,\n    canRetry,\n    connect: socketTransport ? connect : undefined,\n    disconnect: socketTransport ? disconnect : undefined,\n    uploadFiles,\n  };\n}\n","'use client';\n\nimport { type RefObject, useRef, useCallback } from 'react';\n\nconst DEFAULT_THRESHOLD_PX = 80;\n\nexport interface UseAutoScrollOptions {\n  /**\n   * Provide your own ref if you need to share the scroll container\n   * with other logic. When omitted, an internal ref is created.\n   */\n  scrollRef?: RefObject<HTMLDivElement | null>;\n\n  /**\n   * Distance from the bottom (in pixels) within which auto-scroll\n   * stays active. Defaults to 80.\n   */\n  threshold?: number;\n}\n\n/**\n * Smart auto-scroll for chat interfaces.\n *\n * Scrolls to bottom when new content arrives, but pauses if the user\n * has scrolled up to read earlier messages. Re-enables once the user\n * scrolls back near the bottom.\n *\n * @example\n * ```tsx\n * const { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll } = useAutoScroll();\n *\n * useEffect(() => {\n *   const id = requestAnimationFrame(scrollOnUpdate);\n *   return () => cancelAnimationFrame(id);\n * }, [messages, scrollOnUpdate]);\n *\n * <div ref={scrollRef} onScroll={handleScroll}>...</div>\n *\n * // On send: resetAutoScroll() to force-scroll on next update\n * ```\n */\nexport function useAutoScroll(options: UseAutoScrollOptions = {}) {\n  const internalRef = useRef<HTMLDivElement>(null);\n  const scrollRef = options.scrollRef ?? internalRef;\n  const threshold = options.threshold ?? DEFAULT_THRESHOLD_PX;\n  const shouldAutoScrollRef = useRef(true);\n\n  const handleScroll = useCallback(() => {\n    const el = scrollRef.current;\n    if (!el) return;\n    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;\n    shouldAutoScrollRef.current = distanceFromBottom <= threshold;\n  }, [scrollRef, threshold]);\n\n  const scrollOnUpdate = useCallback(() => {\n    const el = scrollRef.current;\n    if (!el) return;\n\n    if (shouldAutoScrollRef.current) {\n      el.scrollTop = el.scrollHeight;\n      return;\n    }\n\n    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;\n    shouldAutoScrollRef.current = distanceFromBottom <= threshold;\n  }, [scrollRef, threshold]);\n\n  const resetAutoScroll = useCallback(() => {\n    shouldAutoScrollRef.current = true;\n  }, []);\n\n  return { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll };\n}\n"],"mappings":"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","names":["uploadFiles","import_react","import_client_sdk"]}

package/dist/index.d.cts

@@ -0,0 +1,244 @@
+import { OctavusChatOptions, UIMessage, ChatStatus, OctavusError, ConnectionState, InteractiveTool, UserMessageInput, FileReference } from '@octavus/client-sdk';
+export * from '@octavus/client-sdk';
+export { AppError, ChatStatus, ClientToolContext, ClientToolHandler, ConflictError, ForbiddenError, InteractiveTool, MAIN_THREAD, NotFoundError, OCTAVUS_SKILL_TOOLS, OctavusChat, OctavusChatOptions, OctavusError, UserMessageInput, ValidationError, createApiErrorEvent, createErrorEvent, createHttpTransport, createInternalErrorEvent, createPollingTransport, createSocketTransport, errorToStreamEvent, generateId, getSkillSlugFromToolCall, isAbortError, isAuthenticationError, isFileReference, isFileReferenceArray, isMainThread, isOctavusSkillTool, isOtherThread, isProviderError, isRateLimitError, isRetryableError, isSocketTransport, isToolError, isValidationError, parseSSEStream, resolveThread, safeParseStreamEvent, safeParseUIMessage, safeParseUIMessages, threadForPart, uploadFiles } from '@octavus/client-sdk';
+import { RefObject } from 'react';
+
+interface UseOctavusChatReturn {
+    /** All messages including the currently streaming one */
+    messages: UIMessage[];
+    /** Current status of the chat */
+    status: ChatStatus;
+    /**
+     * Error if status is 'error'.
+     * Contains structured error information including type, source, and retryability.
+     * Use type guards like `isRateLimitError()` or `isProviderError()` to check specific error types.
+     */
+    error: OctavusError | null;
+    /**
+     * The current session/execution ID from the most recent `send()` call.
+     * Updated when the server responds with a `start` event containing an execution ID.
+     * Useful for tracking activity logs or debugging.
+     *
+     * For workers, this is the execution ID. For interactive sessions, this is the session ID.
+     */
+    sessionId: string | null;
+    /**
+     * Socket connection state (socket transport only).
+     * For HTTP transport, this is always `undefined`.
+     *
+     * - `disconnected`: Not connected (initial state before first send)
+     * - `connecting`: Connection attempt in progress
+     * - `connected`: Successfully connected
+     * - `error`: Connection failed (check `connectionError`)
+     */
+    connectionState: ConnectionState | undefined;
+    /**
+     * Connection error if `connectionState` is 'error'.
+     */
+    connectionError: Error | undefined;
+    /**
+     * 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()}
+     *   />
+     * ))}
+     * ```
+     */
+    pendingClientTools: Record<string, InteractiveTool[]>;
+    /**
+     * 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
+     */
+    send: (triggerName: string, input?: Record<string, unknown>, options?: {
+        userMessage?: UserMessageInput;
+    }) => Promise<void>;
+    /** Stop the current streaming and finalize any partial message */
+    stop: () => void;
+    /**
+     * Retry the last trigger from the same starting point.
+     * Rolls back messages, re-adds the user message (if any), and re-executes.
+     * No-op if no trigger has been sent yet.
+     */
+    retry: () => Promise<void>;
+    /**
+     * Observe an already-active execution without triggering a new one.
+     * Only works with transports that support `observe()` (e.g., polling transport).
+     * Use when the page loads and the session is already streaming.
+     */
+    observe: () => Promise<void>;
+    /**
+     * Replace the message list with externally-provided messages.
+     * Use to sync with server-authoritative state (e.g., multi-observer scenarios).
+     * Must NOT be called while streaming.
+     */
+    replaceMessages: (messages: UIMessage[]) => void;
+    /**
+     * Whether `retry()` can be called.
+     * True when a trigger has been sent and the chat is not currently streaming or awaiting input.
+     */
+    canRetry: boolean;
+    /**
+     * Eagerly connect to the socket (socket transport only).
+     * Returns a promise that resolves when connected or rejects on error.
+     * Safe to call multiple times - subsequent calls resolve immediately if already connected.
+     *
+     * For HTTP transport, this is `undefined`.
+     */
+    connect: (() => Promise<void>) | undefined;
+    /**
+     * Disconnect the socket (socket transport only).
+     * The transport will reconnect automatically on next send().
+     *
+     * For HTTP transport, this is `undefined`.
+     */
+    disconnect: (() => void) | undefined;
+    /**
+     * 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 uploadFiles(fileInput.files, (i, progress) => {
+     *   console.log(`File ${i}: ${progress}%`);
+     * });
+     * // Later...
+     * await send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });
+     * ```
+     */
+    uploadFiles: (files: FileList | File[], onProgress?: (fileIndex: number, progress: number) => void) => Promise<FileReference[]>;
+}
+/**
+ * React hook for interacting with Octavus agents.
+ * Provides chat state management and streaming support.
+ *
+ * When the transport changes (e.g., sessionId changes), the hook automatically
+ * reinitializes with a fresh chat instance. Use `initialMessages` if you need
+ * to preserve messages across transport changes.
+ *
+ * @example Basic usage with HTTP transport
+ * ```tsx
+ * import { useOctavusChat, createHttpTransport } from '@octavus/react';
+ *
+ * function Chat({ sessionId }) {
+ *   const transport = useMemo(
+ *     () => createHttpTransport({
+ *       request: (payload, options) =>
+ *         fetch('/api/trigger', {
+ *           method: 'POST',
+ *           headers: { 'Content-Type': 'application/json' },
+ *           body: JSON.stringify({ sessionId, ...payload }),
+ *           signal: options?.signal,
+ *         }),
+ *     }),
+ *     [sessionId],
+ *   );
+ *
+ *   const { messages, status, send } = useOctavusChat({ transport });
+ *
+ *   return (
+ *     <div>
+ *       {messages.map((msg) => (
+ *         <Message key={msg.id} message={msg} />
+ *       ))}
+ *       <button onClick={() => send('user-message', { USER_MESSAGE: 'Hello' })}>
+ *         Send
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Socket transport with eager connection
+ * ```tsx
+ * import { useOctavusChat, createSocketTransport } from '@octavus/react';
+ *
+ * function Chat() {
+ *   const transport = useMemo(
+ *     () => createSocketTransport({
+ *       connect: () => new Promise((resolve, reject) => {
+ *         const sock = new SockJS('/octavus');
+ *         sock.onopen = () => resolve(sock);
+ *         sock.onerror = () => reject(new Error('Connection failed'));
+ *       }),
+ *     }),
+ *     [],
+ *   );
+ *
+ *   const { messages, status, send, connectionState, connect, disconnect } =
+ *     useOctavusChat({ transport });
+ *
+ *   // Eager connection on mount
+ *   useEffect(() => {
+ *     connect?.();
+ *     return () => disconnect?.();
+ *   }, [connect, disconnect]);
+ *
+ *   return (
+ *     <div>
+ *       <StatusIndicator state={connectionState} />
+ *       {messages.map((msg) => <Message key={msg.id} message={msg} />)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;
+
+interface UseAutoScrollOptions {
+    /**
+     * Provide your own ref if you need to share the scroll container
+     * with other logic. When omitted, an internal ref is created.
+     */
+    scrollRef?: RefObject<HTMLDivElement | null>;
+    /**
+     * Distance from the bottom (in pixels) within which auto-scroll
+     * stays active. Defaults to 80.
+     */
+    threshold?: number;
+}
+/**
+ * Smart auto-scroll for chat interfaces.
+ *
+ * Scrolls to bottom when new content arrives, but pauses if the user
+ * has scrolled up to read earlier messages. Re-enables once the user
+ * scrolls back near the bottom.
+ *
+ * @example
+ * ```tsx
+ * const { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll } = useAutoScroll();
+ *
+ * useEffect(() => {
+ *   const id = requestAnimationFrame(scrollOnUpdate);
+ *   return () => cancelAnimationFrame(id);
+ * }, [messages, scrollOnUpdate]);
+ *
+ * <div ref={scrollRef} onScroll={handleScroll}>...</div>
+ *
+ * // On send: resetAutoScroll() to force-scroll on next update
+ * ```
+ */
+declare function useAutoScroll(options?: UseAutoScrollOptions): {
+    scrollRef: RefObject<HTMLDivElement | null>;
+    handleScroll: () => void;
+    scrollOnUpdate: () => void;
+    resetAutoScroll: () => void;
+};
+
+export { type UseAutoScrollOptions, type UseOctavusChatReturn, useAutoScroll, useOctavusChat };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { OctavusChatOptions, UIMessage, ChatStatus, OctavusError, ConnectionState, InteractiveTool, UserMessageInput, FileReference } from '@octavus/client-sdk';
 export * from '@octavus/client-sdk';
 export { AppError, ChatStatus, ClientToolContext, ClientToolHandler, ConflictError, ForbiddenError, InteractiveTool, MAIN_THREAD, NotFoundError, OCTAVUS_SKILL_TOOLS, OctavusChat, OctavusChatOptions, OctavusError, UserMessageInput, ValidationError, createApiErrorEvent, createErrorEvent, createHttpTransport, createInternalErrorEvent, createPollingTransport, createSocketTransport, errorToStreamEvent, generateId, getSkillSlugFromToolCall, isAbortError, isAuthenticationError, isFileReference, isFileReferenceArray, isMainThread, isOctavusSkillTool, isOtherThread, isProviderError, isRateLimitError, isRetryableError, isSocketTransport, isToolError, isValidationError, parseSSEStream, resolveThread, safeParseStreamEvent, safeParseUIMessage, safeParseUIMessages, threadForPart, uploadFiles } from '@octavus/client-sdk';
+import { RefObject } from 'react';
 
 interface UseOctavusChatReturn {
     /** All messages including the currently streaming one */
@@ -200,4 +201,44 @@ interface UseOctavusChatReturn {
  */
 declare function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;
 
-export { type UseOctavusChatReturn, useOctavusChat };
+interface UseAutoScrollOptions {
+    /**
+     * Provide your own ref if you need to share the scroll container
+     * with other logic. When omitted, an internal ref is created.
+     */
+    scrollRef?: RefObject<HTMLDivElement | null>;
+    /**
+     * Distance from the bottom (in pixels) within which auto-scroll
+     * stays active. Defaults to 80.
+     */
+    threshold?: number;
+}
+/**
+ * Smart auto-scroll for chat interfaces.
+ *
+ * Scrolls to bottom when new content arrives, but pauses if the user
+ * has scrolled up to read earlier messages. Re-enables once the user
+ * scrolls back near the bottom.
+ *
+ * @example
+ * ```tsx
+ * const { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll } = useAutoScroll();
+ *
+ * useEffect(() => {
+ *   const id = requestAnimationFrame(scrollOnUpdate);
+ *   return () => cancelAnimationFrame(id);
+ * }, [messages, scrollOnUpdate]);
+ *
+ * <div ref={scrollRef} onScroll={handleScroll}>...</div>
+ *
+ * // On send: resetAutoScroll() to force-scroll on next update
+ * ```
+ */
+declare function useAutoScroll(options?: UseAutoScrollOptions): {
+    scrollRef: RefObject<HTMLDivElement | null>;
+    handleScroll: () => void;
+    scrollOnUpdate: () => void;
+    resetAutoScroll: () => void;
+};
+
+export { type UseAutoScrollOptions, type UseOctavusChatReturn, useAutoScroll, useOctavusChat };

package/dist/index.js

@@ -100,6 +100,36 @@ function useOctavusChat(options) {
   };
 }
 
+// src/hooks/use-auto-scroll.ts
+import { useRef as useRef2, useCallback as useCallback2 } from "react";
+var DEFAULT_THRESHOLD_PX = 80;
+function useAutoScroll(options = {}) {
+  const internalRef = useRef2(null);
+  const scrollRef = options.scrollRef ?? internalRef;
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD_PX;
+  const shouldAutoScrollRef = useRef2(true);
+  const handleScroll = useCallback2(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    shouldAutoScrollRef.current = distanceFromBottom <= threshold;
+  }, [scrollRef, threshold]);
+  const scrollOnUpdate = useCallback2(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    if (shouldAutoScrollRef.current) {
+      el.scrollTop = el.scrollHeight;
+      return;
+    }
+    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    shouldAutoScrollRef.current = distanceFromBottom <= threshold;
+  }, [scrollRef, threshold]);
+  const resetAutoScroll = useCallback2(() => {
+    shouldAutoScrollRef.current = true;
+  }, []);
+  return { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll };
+}
+
 // src/index.ts
 import {
   OctavusChat as OctavusChat2,
@@ -180,6 +210,7 @@ export {
   safeParseUIMessages,
   threadForPart,
   uploadFiles,
+  useAutoScroll,
   useOctavusChat
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks/use-octavus-chat.ts","../src/index.ts"],"sourcesContent":["'use client';\n\nimport { useRef, useCallback, useSyncExternalStore, useState, useEffect } from 'react';\nimport {\n  OctavusChat,\n  type OctavusError,\n  isSocketTransport,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type UIMessage,\n  type Transport,\n  type ConnectionState,\n  type FileReference,\n  type UploadFilesOptions,\n  type UploadUrlsResponse,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from '@octavus/client-sdk';\n\nexport type {\n  OctavusChatOptions,\n  ChatStatus,\n  UserMessageInput,\n  FileReference,\n  UploadFilesOptions,\n  UploadUrlsResponse,\n  ClientToolContext,\n  ClientToolHandler,\n  InteractiveTool,\n};\n\nexport interface UseOctavusChatReturn {\n  /** All messages including the currently streaming one */\n  messages: UIMessage[];\n  /** Current status of the chat */\n  status: ChatStatus;\n  /**\n   * Error if status is 'error'.\n   * Contains structured error information including type, source, and retryability.\n   * Use type guards like `isRateLimitError()` or `isProviderError()` to check specific error types.\n   */\n  error: OctavusError | null;\n  /**\n   * The current session/execution ID from the most recent `send()` call.\n   * Updated when the server responds with a `start` event containing an execution ID.\n   * Useful for tracking activity logs or debugging.\n   *\n   * For workers, this is the execution ID. For interactive sessions, this is the session ID.\n   */\n  sessionId: string | null;\n  /**\n   * Socket connection state (socket transport only).\n   * For HTTP transport, this is always `undefined`.\n   *\n   * - `disconnected`: Not connected (initial state before first send)\n   * - `connecting`: Connection attempt in progress\n   * - `connected`: Successfully connected\n   * - `error`: Connection failed (check `connectionError`)\n   */\n  connectionState: ConnectionState | undefined;\n  /**\n   * Connection error if `connectionState` is 'error'.\n   */\n  connectionError: Error | undefined;\n  /**\n   * Pending interactive tool calls keyed by tool name.\n   * Each tool has bound `submit()` and `cancel()` methods.\n   *\n   * @example\n   * ```tsx\n   * const feedbackTools = pendingClientTools['request-feedback'] ?? [];\n   *\n   * {feedbackTools.map(tool => (\n   *   <FeedbackModal\n   *     key={tool.toolCallId}\n   *     {...tool.args}\n   *     onSubmit={(result) => tool.submit(result)}\n   *     onCancel={() => tool.cancel()}\n   *   />\n   * ))}\n   * ```\n   */\n  pendingClientTools: Record<string, InteractiveTool[]>;\n  /**\n   * Trigger the agent and optionally add a user message to the chat.\n   *\n   * @param triggerName - The trigger name defined in the agent's protocol.yaml\n   * @param input - Input parameters for the trigger (variable substitutions)\n   * @param options.userMessage - If provided, adds a user message to the chat before triggering\n   */\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput },\n  ) => Promise<void>;\n  /** Stop the current streaming and finalize any partial message */\n  stop: () => void;\n  /**\n   * Retry the last trigger from the same starting point.\n   * Rolls back messages, re-adds the user message (if any), and re-executes.\n   * No-op if no trigger has been sent yet.\n   */\n  retry: () => Promise<void>;\n  /**\n   * Observe an already-active execution without triggering a new one.\n   * Only works with transports that support `observe()` (e.g., polling transport).\n   * Use when the page loads and the session is already streaming.\n   */\n  observe: () => Promise<void>;\n  /**\n   * Replace the message list with externally-provided messages.\n   * Use to sync with server-authoritative state (e.g., multi-observer scenarios).\n   * Must NOT be called while streaming.\n   */\n  replaceMessages: (messages: UIMessage[]) => void;\n  /**\n   * Whether `retry()` can be called.\n   * True when a trigger has been sent and the chat is not currently streaming or awaiting input.\n   */\n  canRetry: boolean;\n  /**\n   * Eagerly connect to the socket (socket transport only).\n   * Returns a promise that resolves when connected or rejects on error.\n   * Safe to call multiple times - subsequent calls resolve immediately if already connected.\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  connect: (() => Promise<void>) | undefined;\n  /**\n   * Disconnect the socket (socket transport only).\n   * The transport will reconnect automatically on next send().\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  disconnect: (() => void) | undefined;\n  /**\n   * Upload files directly without sending a message.\n   * Useful for showing upload progress before sending.\n   *\n   * @param files - Files to upload\n   * @param onProgress - Optional progress callback\n   * @returns Array of file references\n   *\n   * @example\n   * ```typescript\n   * const fileRefs = await uploadFiles(fileInput.files, (i, progress) => {\n   *   console.log(`File ${i}: ${progress}%`);\n   * });\n   * // Later...\n   * await send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });\n   * ```\n   */\n  uploadFiles: (\n    files: FileList | File[],\n    onProgress?: (fileIndex: number, progress: number) => void,\n  ) => Promise<FileReference[]>;\n}\n\n/**\n * React hook for interacting with Octavus agents.\n * Provides chat state management and streaming support.\n *\n * When the transport changes (e.g., sessionId changes), the hook automatically\n * reinitializes with a fresh chat instance. Use `initialMessages` if you need\n * to preserve messages across transport changes.\n *\n * @example Basic usage with HTTP transport\n * ```tsx\n * import { useOctavusChat, createHttpTransport } from '@octavus/react';\n *\n * function Chat({ sessionId }) {\n *   const transport = useMemo(\n *     () => createHttpTransport({\n *       request: (payload, options) =>\n *         fetch('/api/trigger', {\n *           method: 'POST',\n *           headers: { 'Content-Type': 'application/json' },\n *           body: JSON.stringify({ sessionId, ...payload }),\n *           signal: options?.signal,\n *         }),\n *     }),\n *     [sessionId],\n *   );\n *\n *   const { messages, status, send } = useOctavusChat({ transport });\n *\n *   return (\n *     <div>\n *       {messages.map((msg) => (\n *         <Message key={msg.id} message={msg} />\n *       ))}\n *       <button onClick={() => send('user-message', { USER_MESSAGE: 'Hello' })}>\n *         Send\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example Socket transport with eager connection\n * ```tsx\n * import { useOctavusChat, createSocketTransport } from '@octavus/react';\n *\n * function Chat() {\n *   const transport = useMemo(\n *     () => createSocketTransport({\n *       connect: () => new Promise((resolve, reject) => {\n *         const sock = new SockJS('/octavus');\n *         sock.onopen = () => resolve(sock);\n *         sock.onerror = () => reject(new Error('Connection failed'));\n *       }),\n *     }),\n *     [],\n *   );\n *\n *   const { messages, status, send, connectionState, connect, disconnect } =\n *     useOctavusChat({ transport });\n *\n *   // Eager connection on mount\n *   useEffect(() => {\n *     connect?.();\n *     return () => disconnect?.();\n *   }, [connect, disconnect]);\n *\n *   return (\n *     <div>\n *       <StatusIndicator state={connectionState} />\n *       {messages.map((msg) => <Message key={msg.id} message={msg} />)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn {\n  const chatRef = useRef<OctavusChat | null>(null);\n  const transportRef = useRef<Transport | null>(null);\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  const sessionIdSetterRef = useRef(setSessionId);\n  sessionIdSetterRef.current = setSessionId;\n\n  if (transportRef.current !== options.transport) {\n    chatRef.current?.stop();\n    setSessionId(null);\n    chatRef.current = new OctavusChat(options);\n    transportRef.current = options.transport;\n  }\n\n  const chat = chatRef.current!;\n\n  // Keep all mutable options (callbacks, tool handlers) fresh on every render.\n  // This ensures handlers always reference the latest closures instead of going stale.\n  chat.updateOptions({\n    clientTools: options.clientTools,\n    onError: options.onError,\n    onFinish: options.onFinish,\n    onStop: options.onStop,\n    onResourceUpdate: options.onResourceUpdate,\n    onStart: (id) => {\n      sessionIdSetterRef.current(id);\n      options.onStart?.(id);\n    },\n    requestUploadUrls: options.requestUploadUrls,\n    uploadOptions: options.uploadOptions,\n  });\n  const transport = options.transport;\n\n  const subscribe = useCallback((callback: () => void) => chat.subscribe(callback), [chat]);\n  const getMessagesSnapshot = useCallback(() => chat.messages, [chat]);\n  const getStatusSnapshot = useCallback(() => chat.status, [chat]);\n  const getErrorSnapshot = useCallback(() => chat.error, [chat]);\n  const getPendingClientToolsSnapshot = useCallback(() => chat.pendingClientTools, [chat]);\n  const getCanRetrySnapshot = useCallback(() => chat.canRetry, [chat]);\n\n  const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);\n  const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);\n  const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);\n  const pendingClientTools = useSyncExternalStore(\n    subscribe,\n    getPendingClientToolsSnapshot,\n    getPendingClientToolsSnapshot,\n  );\n  const canRetry = useSyncExternalStore(subscribe, getCanRetrySnapshot, getCanRetrySnapshot);\n\n  const socketTransport = isSocketTransport(transport) ? transport : null;\n  const [connectionState, setConnectionState] = useState<ConnectionState | undefined>(\n    socketTransport?.connectionState,\n  );\n  const [connectionError, setConnectionError] = useState<Error | undefined>(undefined);\n\n  useEffect(() => {\n    if (!socketTransport) {\n      setConnectionState(undefined);\n      setConnectionError(undefined);\n      return;\n    }\n\n    const unsubscribe = socketTransport.onConnectionStateChange((state, err) => {\n      setConnectionState(state);\n      setConnectionError(err);\n    });\n\n    return unsubscribe;\n  }, [socketTransport]);\n\n  const send = useCallback(\n    (\n      triggerName: string,\n      input?: Record<string, unknown>,\n      sendOptions?: { userMessage?: UserMessageInput },\n    ) => chat.send(triggerName, input, sendOptions),\n    [chat],\n  );\n\n  const stop = useCallback(() => chat.stop(), [chat]);\n  const retry = useCallback(() => chat.retry(), [chat]);\n  const observe = useCallback(() => chat.observe(), [chat]);\n  const replaceMessages = useCallback((msgs: UIMessage[]) => chat.replaceMessages(msgs), [chat]);\n\n  const uploadFiles = useCallback(\n    (files: FileList | File[], onProgress?: (fileIndex: number, progress: number) => void) =>\n      chat.uploadFiles(files, onProgress),\n    [chat],\n  );\n\n  // Stable references for connect/disconnect (socket transport only)\n  const connect = useCallback(\n    () => socketTransport?.connect() ?? Promise.resolve(),\n    [socketTransport],\n  );\n  const disconnect = useCallback(() => socketTransport?.disconnect(), [socketTransport]);\n\n  return {\n    messages,\n    status,\n    error,\n    sessionId,\n    connectionState,\n    connectionError,\n    pendingClientTools,\n    send,\n    stop,\n    retry,\n    observe,\n    replaceMessages,\n    canRetry,\n    connect: socketTransport ? connect : undefined,\n    disconnect: socketTransport ? disconnect : undefined,\n    uploadFiles,\n  };\n}\n","export {\n  useOctavusChat,\n  type UseOctavusChatReturn,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from './hooks/use-octavus-chat';\n\nexport type * from '@octavus/client-sdk';\nexport {\n  // Chat\n  OctavusChat,\n  // Files\n  uploadFiles,\n  // Stream\n  parseSSEStream,\n  // Transports\n  createHttpTransport,\n  createSocketTransport,\n  isSocketTransport,\n  createPollingTransport,\n  // Error classes\n  AppError,\n  NotFoundError,\n  ValidationError,\n  ConflictError,\n  ForbiddenError,\n  OctavusError,\n  // Error type guards\n  isRateLimitError,\n  isAuthenticationError,\n  isProviderError,\n  isToolError,\n  isRetryableError,\n  isValidationError,\n  // Error event helpers\n  createErrorEvent,\n  errorToStreamEvent,\n  createInternalErrorEvent,\n  createApiErrorEvent,\n  // Utilities\n  generateId,\n  isAbortError,\n  // Thread helpers\n  MAIN_THREAD,\n  resolveThread,\n  isMainThread,\n  threadForPart,\n  isOtherThread,\n  // Type guards\n  isFileReference,\n  isFileReferenceArray,\n  // Safe parse helpers\n  safeParseStreamEvent,\n  safeParseUIMessage,\n  safeParseUIMessages,\n  // Skills\n  OCTAVUS_SKILL_TOOLS,\n  isOctavusSkillTool,\n  getSkillSlugFromToolCall,\n} from '@octavus/client-sdk';\n"],"mappings":"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","names":["uploadFiles","OctavusChat","isSocketTransport"]}
+{"version":3,"sources":["../src/hooks/use-octavus-chat.ts","../src/hooks/use-auto-scroll.ts","../src/index.ts"],"sourcesContent":["'use client';\n\nimport { useRef, useCallback, useSyncExternalStore, useState, useEffect } from 'react';\nimport {\n  OctavusChat,\n  type OctavusError,\n  isSocketTransport,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type UIMessage,\n  type Transport,\n  type ConnectionState,\n  type FileReference,\n  type UploadFilesOptions,\n  type UploadUrlsResponse,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from '@octavus/client-sdk';\n\nexport type {\n  OctavusChatOptions,\n  ChatStatus,\n  UserMessageInput,\n  FileReference,\n  UploadFilesOptions,\n  UploadUrlsResponse,\n  ClientToolContext,\n  ClientToolHandler,\n  InteractiveTool,\n};\n\nexport interface UseOctavusChatReturn {\n  /** All messages including the currently streaming one */\n  messages: UIMessage[];\n  /** Current status of the chat */\n  status: ChatStatus;\n  /**\n   * Error if status is 'error'.\n   * Contains structured error information including type, source, and retryability.\n   * Use type guards like `isRateLimitError()` or `isProviderError()` to check specific error types.\n   */\n  error: OctavusError | null;\n  /**\n   * The current session/execution ID from the most recent `send()` call.\n   * Updated when the server responds with a `start` event containing an execution ID.\n   * Useful for tracking activity logs or debugging.\n   *\n   * For workers, this is the execution ID. For interactive sessions, this is the session ID.\n   */\n  sessionId: string | null;\n  /**\n   * Socket connection state (socket transport only).\n   * For HTTP transport, this is always `undefined`.\n   *\n   * - `disconnected`: Not connected (initial state before first send)\n   * - `connecting`: Connection attempt in progress\n   * - `connected`: Successfully connected\n   * - `error`: Connection failed (check `connectionError`)\n   */\n  connectionState: ConnectionState | undefined;\n  /**\n   * Connection error if `connectionState` is 'error'.\n   */\n  connectionError: Error | undefined;\n  /**\n   * Pending interactive tool calls keyed by tool name.\n   * Each tool has bound `submit()` and `cancel()` methods.\n   *\n   * @example\n   * ```tsx\n   * const feedbackTools = pendingClientTools['request-feedback'] ?? [];\n   *\n   * {feedbackTools.map(tool => (\n   *   <FeedbackModal\n   *     key={tool.toolCallId}\n   *     {...tool.args}\n   *     onSubmit={(result) => tool.submit(result)}\n   *     onCancel={() => tool.cancel()}\n   *   />\n   * ))}\n   * ```\n   */\n  pendingClientTools: Record<string, InteractiveTool[]>;\n  /**\n   * Trigger the agent and optionally add a user message to the chat.\n   *\n   * @param triggerName - The trigger name defined in the agent's protocol.yaml\n   * @param input - Input parameters for the trigger (variable substitutions)\n   * @param options.userMessage - If provided, adds a user message to the chat before triggering\n   */\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput },\n  ) => Promise<void>;\n  /** Stop the current streaming and finalize any partial message */\n  stop: () => void;\n  /**\n   * Retry the last trigger from the same starting point.\n   * Rolls back messages, re-adds the user message (if any), and re-executes.\n   * No-op if no trigger has been sent yet.\n   */\n  retry: () => Promise<void>;\n  /**\n   * Observe an already-active execution without triggering a new one.\n   * Only works with transports that support `observe()` (e.g., polling transport).\n   * Use when the page loads and the session is already streaming.\n   */\n  observe: () => Promise<void>;\n  /**\n   * Replace the message list with externally-provided messages.\n   * Use to sync with server-authoritative state (e.g., multi-observer scenarios).\n   * Must NOT be called while streaming.\n   */\n  replaceMessages: (messages: UIMessage[]) => void;\n  /**\n   * Whether `retry()` can be called.\n   * True when a trigger has been sent and the chat is not currently streaming or awaiting input.\n   */\n  canRetry: boolean;\n  /**\n   * Eagerly connect to the socket (socket transport only).\n   * Returns a promise that resolves when connected or rejects on error.\n   * Safe to call multiple times - subsequent calls resolve immediately if already connected.\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  connect: (() => Promise<void>) | undefined;\n  /**\n   * Disconnect the socket (socket transport only).\n   * The transport will reconnect automatically on next send().\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  disconnect: (() => void) | undefined;\n  /**\n   * Upload files directly without sending a message.\n   * Useful for showing upload progress before sending.\n   *\n   * @param files - Files to upload\n   * @param onProgress - Optional progress callback\n   * @returns Array of file references\n   *\n   * @example\n   * ```typescript\n   * const fileRefs = await uploadFiles(fileInput.files, (i, progress) => {\n   *   console.log(`File ${i}: ${progress}%`);\n   * });\n   * // Later...\n   * await send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });\n   * ```\n   */\n  uploadFiles: (\n    files: FileList | File[],\n    onProgress?: (fileIndex: number, progress: number) => void,\n  ) => Promise<FileReference[]>;\n}\n\n/**\n * React hook for interacting with Octavus agents.\n * Provides chat state management and streaming support.\n *\n * When the transport changes (e.g., sessionId changes), the hook automatically\n * reinitializes with a fresh chat instance. Use `initialMessages` if you need\n * to preserve messages across transport changes.\n *\n * @example Basic usage with HTTP transport\n * ```tsx\n * import { useOctavusChat, createHttpTransport } from '@octavus/react';\n *\n * function Chat({ sessionId }) {\n *   const transport = useMemo(\n *     () => createHttpTransport({\n *       request: (payload, options) =>\n *         fetch('/api/trigger', {\n *           method: 'POST',\n *           headers: { 'Content-Type': 'application/json' },\n *           body: JSON.stringify({ sessionId, ...payload }),\n *           signal: options?.signal,\n *         }),\n *     }),\n *     [sessionId],\n *   );\n *\n *   const { messages, status, send } = useOctavusChat({ transport });\n *\n *   return (\n *     <div>\n *       {messages.map((msg) => (\n *         <Message key={msg.id} message={msg} />\n *       ))}\n *       <button onClick={() => send('user-message', { USER_MESSAGE: 'Hello' })}>\n *         Send\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example Socket transport with eager connection\n * ```tsx\n * import { useOctavusChat, createSocketTransport } from '@octavus/react';\n *\n * function Chat() {\n *   const transport = useMemo(\n *     () => createSocketTransport({\n *       connect: () => new Promise((resolve, reject) => {\n *         const sock = new SockJS('/octavus');\n *         sock.onopen = () => resolve(sock);\n *         sock.onerror = () => reject(new Error('Connection failed'));\n *       }),\n *     }),\n *     [],\n *   );\n *\n *   const { messages, status, send, connectionState, connect, disconnect } =\n *     useOctavusChat({ transport });\n *\n *   // Eager connection on mount\n *   useEffect(() => {\n *     connect?.();\n *     return () => disconnect?.();\n *   }, [connect, disconnect]);\n *\n *   return (\n *     <div>\n *       <StatusIndicator state={connectionState} />\n *       {messages.map((msg) => <Message key={msg.id} message={msg} />)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn {\n  const chatRef = useRef<OctavusChat | null>(null);\n  const transportRef = useRef<Transport | null>(null);\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  const sessionIdSetterRef = useRef(setSessionId);\n  sessionIdSetterRef.current = setSessionId;\n\n  if (transportRef.current !== options.transport) {\n    chatRef.current?.stop();\n    setSessionId(null);\n    chatRef.current = new OctavusChat(options);\n    transportRef.current = options.transport;\n  }\n\n  const chat = chatRef.current!;\n\n  // Keep all mutable options (callbacks, tool handlers) fresh on every render.\n  // This ensures handlers always reference the latest closures instead of going stale.\n  chat.updateOptions({\n    clientTools: options.clientTools,\n    onError: options.onError,\n    onFinish: options.onFinish,\n    onStop: options.onStop,\n    onResourceUpdate: options.onResourceUpdate,\n    onStart: (id) => {\n      sessionIdSetterRef.current(id);\n      options.onStart?.(id);\n    },\n    requestUploadUrls: options.requestUploadUrls,\n    uploadOptions: options.uploadOptions,\n  });\n  const transport = options.transport;\n\n  const subscribe = useCallback((callback: () => void) => chat.subscribe(callback), [chat]);\n  const getMessagesSnapshot = useCallback(() => chat.messages, [chat]);\n  const getStatusSnapshot = useCallback(() => chat.status, [chat]);\n  const getErrorSnapshot = useCallback(() => chat.error, [chat]);\n  const getPendingClientToolsSnapshot = useCallback(() => chat.pendingClientTools, [chat]);\n  const getCanRetrySnapshot = useCallback(() => chat.canRetry, [chat]);\n\n  const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);\n  const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);\n  const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);\n  const pendingClientTools = useSyncExternalStore(\n    subscribe,\n    getPendingClientToolsSnapshot,\n    getPendingClientToolsSnapshot,\n  );\n  const canRetry = useSyncExternalStore(subscribe, getCanRetrySnapshot, getCanRetrySnapshot);\n\n  const socketTransport = isSocketTransport(transport) ? transport : null;\n  const [connectionState, setConnectionState] = useState<ConnectionState | undefined>(\n    socketTransport?.connectionState,\n  );\n  const [connectionError, setConnectionError] = useState<Error | undefined>(undefined);\n\n  useEffect(() => {\n    if (!socketTransport) {\n      setConnectionState(undefined);\n      setConnectionError(undefined);\n      return;\n    }\n\n    const unsubscribe = socketTransport.onConnectionStateChange((state, err) => {\n      setConnectionState(state);\n      setConnectionError(err);\n    });\n\n    return unsubscribe;\n  }, [socketTransport]);\n\n  const send = useCallback(\n    (\n      triggerName: string,\n      input?: Record<string, unknown>,\n      sendOptions?: { userMessage?: UserMessageInput },\n    ) => chat.send(triggerName, input, sendOptions),\n    [chat],\n  );\n\n  const stop = useCallback(() => chat.stop(), [chat]);\n  const retry = useCallback(() => chat.retry(), [chat]);\n  const observe = useCallback(() => chat.observe(), [chat]);\n  const replaceMessages = useCallback((msgs: UIMessage[]) => chat.replaceMessages(msgs), [chat]);\n\n  const uploadFiles = useCallback(\n    (files: FileList | File[], onProgress?: (fileIndex: number, progress: number) => void) =>\n      chat.uploadFiles(files, onProgress),\n    [chat],\n  );\n\n  // Stable references for connect/disconnect (socket transport only)\n  const connect = useCallback(\n    () => socketTransport?.connect() ?? Promise.resolve(),\n    [socketTransport],\n  );\n  const disconnect = useCallback(() => socketTransport?.disconnect(), [socketTransport]);\n\n  return {\n    messages,\n    status,\n    error,\n    sessionId,\n    connectionState,\n    connectionError,\n    pendingClientTools,\n    send,\n    stop,\n    retry,\n    observe,\n    replaceMessages,\n    canRetry,\n    connect: socketTransport ? connect : undefined,\n    disconnect: socketTransport ? disconnect : undefined,\n    uploadFiles,\n  };\n}\n","'use client';\n\nimport { type RefObject, useRef, useCallback } from 'react';\n\nconst DEFAULT_THRESHOLD_PX = 80;\n\nexport interface UseAutoScrollOptions {\n  /**\n   * Provide your own ref if you need to share the scroll container\n   * with other logic. When omitted, an internal ref is created.\n   */\n  scrollRef?: RefObject<HTMLDivElement | null>;\n\n  /**\n   * Distance from the bottom (in pixels) within which auto-scroll\n   * stays active. Defaults to 80.\n   */\n  threshold?: number;\n}\n\n/**\n * Smart auto-scroll for chat interfaces.\n *\n * Scrolls to bottom when new content arrives, but pauses if the user\n * has scrolled up to read earlier messages. Re-enables once the user\n * scrolls back near the bottom.\n *\n * @example\n * ```tsx\n * const { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll } = useAutoScroll();\n *\n * useEffect(() => {\n *   const id = requestAnimationFrame(scrollOnUpdate);\n *   return () => cancelAnimationFrame(id);\n * }, [messages, scrollOnUpdate]);\n *\n * <div ref={scrollRef} onScroll={handleScroll}>...</div>\n *\n * // On send: resetAutoScroll() to force-scroll on next update\n * ```\n */\nexport function useAutoScroll(options: UseAutoScrollOptions = {}) {\n  const internalRef = useRef<HTMLDivElement>(null);\n  const scrollRef = options.scrollRef ?? internalRef;\n  const threshold = options.threshold ?? DEFAULT_THRESHOLD_PX;\n  const shouldAutoScrollRef = useRef(true);\n\n  const handleScroll = useCallback(() => {\n    const el = scrollRef.current;\n    if (!el) return;\n    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;\n    shouldAutoScrollRef.current = distanceFromBottom <= threshold;\n  }, [scrollRef, threshold]);\n\n  const scrollOnUpdate = useCallback(() => {\n    const el = scrollRef.current;\n    if (!el) return;\n\n    if (shouldAutoScrollRef.current) {\n      el.scrollTop = el.scrollHeight;\n      return;\n    }\n\n    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;\n    shouldAutoScrollRef.current = distanceFromBottom <= threshold;\n  }, [scrollRef, threshold]);\n\n  const resetAutoScroll = useCallback(() => {\n    shouldAutoScrollRef.current = true;\n  }, []);\n\n  return { scrollRef, handleScroll, scrollOnUpdate, resetAutoScroll };\n}\n","export {\n  useOctavusChat,\n  type UseOctavusChatReturn,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from './hooks/use-octavus-chat';\n\nexport { useAutoScroll, type UseAutoScrollOptions } from './hooks/use-auto-scroll';\n\nexport type * from '@octavus/client-sdk';\nexport {\n  // Chat\n  OctavusChat,\n  // Files\n  uploadFiles,\n  // Stream\n  parseSSEStream,\n  // Transports\n  createHttpTransport,\n  createSocketTransport,\n  isSocketTransport,\n  createPollingTransport,\n  // Error classes\n  AppError,\n  NotFoundError,\n  ValidationError,\n  ConflictError,\n  ForbiddenError,\n  OctavusError,\n  // Error type guards\n  isRateLimitError,\n  isAuthenticationError,\n  isProviderError,\n  isToolError,\n  isRetryableError,\n  isValidationError,\n  // Error event helpers\n  createErrorEvent,\n  errorToStreamEvent,\n  createInternalErrorEvent,\n  createApiErrorEvent,\n  // Utilities\n  generateId,\n  isAbortError,\n  // Thread helpers\n  MAIN_THREAD,\n  resolveThread,\n  isMainThread,\n  threadForPart,\n  isOtherThread,\n  // Type guards\n  isFileReference,\n  isFileReferenceArray,\n  // Safe parse helpers\n  safeParseStreamEvent,\n  safeParseUIMessage,\n  safeParseUIMessages,\n  // Skills\n  OCTAVUS_SKILL_TOOLS,\n  isOctavusSkillTool,\n  getSkillSlugFromToolCall,\n} from '@octavus/client-sdk';\n"],"mappings":"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","names":["uploadFiles","useRef","useCallback","OctavusChat","isSocketTransport"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octavus/react",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "description": "React bindings for Octavus agents",
   "license": "MIT",
   "author": "Octavus AI <dev@octavus.ai>",
@@ -25,12 +25,19 @@
   ],
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -40,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@octavus/client-sdk": "^2.19.0"
+    "@octavus/client-sdk": "^2.21.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0"