@octavus/client-sdk 0.2.0 → 2.0.0

package/dist/index.js

@@ -2,7 +2,8 @@
 import {
   generateId,
   threadForPart,
-  isFileReferenceArray
+  isFileReferenceArray,
+  OctavusError
 } from "@octavus/core";
 
 // src/files.ts
@@ -180,6 +181,19 @@ var OctavusChat = class {
   options;
   transport;
   streamingState = null;
+  // Client tool state
+  // Keyed by toolName -> array of pending tools for that name
+  _pendingToolsByName = /* @__PURE__ */ new Map();
+  // Keyed by toolCallId -> pending tool state (for internal lookup when submitting)
+  _pendingToolsByCallId = /* @__PURE__ */ new Map();
+  // Cache for React useSyncExternalStore compatibility
+  _pendingClientToolsCache = {};
+  _completedToolResults = [];
+  _clientToolAbortController = null;
+  // Server tool results from mixed server+client tools (for continuation)
+  _serverToolResults = [];
+  // Execution ID for continuation (from client-tool-request event)
+  _pendingExecutionId = null;
   // Listener sets for reactive frameworks
   listeners = /* @__PURE__ */ new Set();
   constructor(options) {
@@ -196,9 +210,34 @@ var OctavusChat = class {
   get status() {
     return this._status;
   }
+  /**
+   * The current error, if any.
+   * Contains structured error information including type, source, and retryability.
+   */
   get error() {
     return this._error;
   }
+  /**
+   * 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() {
+    return this._pendingClientToolsCache;
+  }
   // =========================================================================
   // Subscription Methods (for reactive frameworks)
   // =========================================================================
@@ -228,6 +267,19 @@ var OctavusChat = class {
     this._error = error;
     this.notifyListeners();
   }
+  updatePendingClientToolsCache() {
+    const cache = {};
+    for (const [toolName, tools] of this._pendingToolsByName.entries()) {
+      cache[toolName] = tools.map((tool) => ({
+        toolCallId: tool.toolCallId,
+        toolName: tool.toolName,
+        args: tool.args,
+        submit: (result) => this.submitToolResult(tool.toolCallId, result),
+        cancel: (reason) => this.submitToolResult(tool.toolCallId, void 0, reason ?? "User cancelled")
+      }));
+    }
+    this._pendingClientToolsCache = cache;
+  }
   // =========================================================================
   // Public Methods
   // =========================================================================
@@ -289,13 +341,67 @@ var OctavusChat = class {
     this.setStatus("streaming");
     this.setError(null);
     this.streamingState = createEmptyStreamingState();
+    this._pendingToolsByName.clear();
+    this._pendingToolsByCallId.clear();
+    this._completedToolResults = [];
+    this._serverToolResults = [];
+    this._pendingExecutionId = null;
+    this.updatePendingClientToolsCache();
     try {
       for await (const event of this.transport.trigger(triggerName, processedInput)) {
         if (this.streamingState === null) break;
         this.handleStreamEvent(event, this.streamingState);
       }
     } catch (err) {
-      const errorObj = err instanceof Error ? err : new Error("Unknown error");
+      const errorObj = OctavusError.isInstance(err) ? err : new OctavusError({
+        errorType: "internal_error",
+        message: err instanceof Error ? err.message : "Unknown error",
+        source: "client",
+        retryable: false,
+        cause: err
+      });
+      const state = this.streamingState;
+      if (state !== null) {
+        const messages = [...this._messages];
+        const lastMsg = messages[messages.length - 1];
+        if (state.parts.length > 0) {
+          const finalParts = state.parts.map((part) => {
+            if (part.type === "text" || part.type === "reasoning") {
+              if (part.status === "streaming") {
+                return { ...part, status: "done" };
+              }
+            }
+            if (part.type === "object" && part.status === "streaming") {
+              return { ...part, status: "done" };
+            }
+            if (part.type === "tool-call") {
+              if (part.status === "pending" || part.status === "running") {
+                return { ...part, status: "cancelled" };
+              }
+            }
+            if (part.type === "operation" && part.status === "running") {
+              return { ...part, status: "cancelled" };
+            }
+            return part;
+          });
+          const finalMessage = {
+            id: state.messageId,
+            role: "assistant",
+            parts: finalParts,
+            status: "done",
+            createdAt: /* @__PURE__ */ new Date()
+          };
+          if (lastMsg?.id === state.messageId) {
+            messages[messages.length - 1] = finalMessage;
+          } else {
+            messages.push(finalMessage);
+          }
+          this.setMessages(messages);
+        } else if (lastMsg?.id === state.messageId) {
+          messages.pop();
+          this.setMessages(messages);
+        }
+      }
       this.setError(errorObj);
       this.setStatus("error");
       this.streamingState = null;
@@ -328,11 +434,58 @@ var OctavusChat = class {
       onProgress
     });
   }
+  /**
+   * Internal: Submit a result for a pending tool.
+   * Called by bound submit/cancel methods on InteractiveTool.
+   */
+  submitToolResult(toolCallId, result, error) {
+    const pendingTool = this._pendingToolsByCallId.get(toolCallId);
+    if (!pendingTool) {
+      return;
+    }
+    this._pendingToolsByCallId.delete(toolCallId);
+    const toolsForName = this._pendingToolsByName.get(pendingTool.toolName);
+    if (toolsForName) {
+      const filtered = toolsForName.filter((t) => t.toolCallId !== toolCallId);
+      if (filtered.length === 0) {
+        this._pendingToolsByName.delete(pendingTool.toolName);
+      } else {
+        this._pendingToolsByName.set(pendingTool.toolName, filtered);
+      }
+    }
+    this.updatePendingClientToolsCache();
+    const toolResult = {
+      toolCallId,
+      toolName: pendingTool.toolName,
+      result: error ? void 0 : result,
+      error,
+      outputVariable: pendingTool.outputVariable,
+      blockIndex: pendingTool.blockIndex
+    };
+    this._completedToolResults.push(toolResult);
+    if (error) {
+      this.emitToolOutputError(toolCallId, error);
+    } else {
+      this.emitToolOutputAvailable(toolCallId, result);
+    }
+    if (this._pendingToolsByCallId.size === 0) {
+      void this.continueWithClientToolResults();
+    }
+    this.notifyListeners();
+  }
   /** Stop the current streaming and finalize any partial message */
   stop() {
-    if (this._status !== "streaming") {
+    if (this._status !== "streaming" && this._status !== "awaiting-input") {
       return;
     }
+    this._clientToolAbortController?.abort();
+    this._clientToolAbortController = null;
+    this._pendingToolsByName.clear();
+    this._pendingToolsByCallId.clear();
+    this._completedToolResults = [];
+    this._serverToolResults = [];
+    this._pendingExecutionId = null;
+    this.updatePendingClientToolsCache();
     this.transport.stop();
     const state = this.streamingState;
     if (state && state.parts.length > 0) {
@@ -372,7 +525,7 @@ var OctavusChat = class {
       };
       const messages = [...this._messages];
       const lastMsg = messages[messages.length - 1];
-      if (lastMsg && lastMsg.id === state.messageId) {
+      if (lastMsg?.id === state.messageId) {
         messages[messages.length - 1] = finalMessage;
       } else {
         messages.push(finalMessage);
@@ -615,7 +768,7 @@ var OctavusChat = class {
         );
         if (toolPartIndex >= 0) {
           const part = state.parts[toolPartIndex];
-          part.error = event.errorText;
+          part.error = event.error;
           part.status = "error";
           state.parts[toolPartIndex] = { ...part };
           this.updateStreamingMessage();
@@ -668,6 +821,12 @@ var OctavusChat = class {
         this.options.onResourceUpdate?.(event.name, event.value);
         break;
       case "finish": {
+        if (event.finishReason === "client-tool-calls") {
+          if (this._pendingToolsByCallId.size > 0) {
+            this.setStatus("awaiting-input");
+          }
+          return;
+        }
         const finalMessage = buildMessageFromState(state, "done");
         finalMessage.parts = finalMessage.parts.map((part) => {
           if (part.type === "text" || part.type === "reasoning") {
@@ -681,7 +840,7 @@ var OctavusChat = class {
         if (finalMessage.parts.length > 0) {
           const messages = [...this._messages];
           const lastMsg = messages[messages.length - 1];
-          if (lastMsg && lastMsg.id === state.messageId) {
+          if (lastMsg?.id === state.messageId) {
             messages[messages.length - 1] = finalMessage;
           } else {
             messages.push(finalMessage);
@@ -693,10 +852,25 @@ var OctavusChat = class {
         this.options.onFinish?.();
         break;
       }
-      case "error":
-        throw new Error(event.errorText);
+      case "error": {
+        throw new OctavusError({
+          errorType: event.errorType,
+          message: event.message,
+          source: event.source,
+          retryable: event.retryable,
+          retryAfter: event.retryAfter,
+          code: event.code,
+          provider: event.provider,
+          tool: event.tool
+        });
+      }
       case "tool-request":
         break;
+      case "client-tool-request":
+        this._pendingExecutionId = event.executionId;
+        this._serverToolResults = event.serverToolResults ?? [];
+        void this.handleClientToolRequest(event.toolCalls, state);
+        break;
     }
   }
   updateStreamingMessage() {
@@ -705,13 +879,168 @@ var OctavusChat = class {
     const msg = buildMessageFromState(state, "streaming");
     const messages = [...this._messages];
     const lastMsg = messages[messages.length - 1];
-    if (lastMsg && lastMsg.id === state.messageId) {
+    if (lastMsg?.id === state.messageId) {
       messages[messages.length - 1] = msg;
     } else {
       messages.push(msg);
     }
     this.setMessages(messages);
   }
+  /**
+   * Emit a tool-output-available event for a client tool result.
+   */
+  emitToolOutputAvailable(toolCallId, output) {
+    const state = this.streamingState;
+    if (!state) return;
+    const toolPartIndex = state.parts.findIndex(
+      (p) => p.type === "tool-call" && p.toolCallId === toolCallId
+    );
+    if (toolPartIndex >= 0) {
+      const part = state.parts[toolPartIndex];
+      part.result = output;
+      part.status = "done";
+      state.parts[toolPartIndex] = { ...part };
+      this.updateStreamingMessage();
+    }
+  }
+  /**
+   * Emit a tool-output-error event for a client tool result.
+   */
+  emitToolOutputError(toolCallId, error) {
+    const state = this.streamingState;
+    if (!state) return;
+    const toolPartIndex = state.parts.findIndex(
+      (p) => p.type === "tool-call" && p.toolCallId === toolCallId
+    );
+    if (toolPartIndex >= 0) {
+      const part = state.parts[toolPartIndex];
+      part.error = error;
+      part.status = "error";
+      state.parts[toolPartIndex] = { ...part };
+      this.updateStreamingMessage();
+    }
+  }
+  /**
+   * Continue execution with collected client tool results.
+   */
+  async continueWithClientToolResults() {
+    if (this._completedToolResults.length === 0) return;
+    if (this._pendingExecutionId === null) {
+      const errorObj = new OctavusError({
+        errorType: "internal_error",
+        message: "Cannot continue execution: execution ID was lost.",
+        source: "client",
+        retryable: false
+      });
+      this.setError(errorObj);
+      this.setStatus("error");
+      this.options.onError?.(errorObj);
+      return;
+    }
+    const allResults = [...this._serverToolResults, ...this._completedToolResults];
+    const executionId = this._pendingExecutionId;
+    this._serverToolResults = [];
+    this._completedToolResults = [];
+    this._pendingExecutionId = null;
+    this.setStatus("streaming");
+    try {
+      for await (const event of this.transport.continueWithToolResults(executionId, allResults)) {
+        if (this.streamingState === null) break;
+        this.handleStreamEvent(event, this.streamingState);
+      }
+    } catch (err) {
+      const errorObj = OctavusError.isInstance(err) ? err : new OctavusError({
+        errorType: "internal_error",
+        message: err instanceof Error ? err.message : "Unknown error",
+        source: "client",
+        retryable: false,
+        cause: err
+      });
+      this.setError(errorObj);
+      this.setStatus("error");
+      this.streamingState = null;
+      this.options.onError?.(errorObj);
+    }
+  }
+  /**
+   * 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.
+   */
+  async handleClientToolRequest(toolCalls, state) {
+    this._clientToolAbortController = new AbortController();
+    for (const tc of toolCalls) {
+      const handler = this.options.clientTools?.[tc.toolName];
+      if (handler === "interactive") {
+        const toolState = {
+          toolCallId: tc.toolCallId,
+          toolName: tc.toolName,
+          args: tc.args,
+          source: tc.source,
+          outputVariable: tc.outputVariable,
+          blockIndex: tc.blockIndex
+        };
+        this._pendingToolsByCallId.set(tc.toolCallId, toolState);
+        const existing = this._pendingToolsByName.get(tc.toolName) ?? [];
+        this._pendingToolsByName.set(tc.toolName, [...existing, toolState]);
+      }
+    }
+    if (this._pendingToolsByCallId.size > 0) {
+      this.updatePendingClientToolsCache();
+    }
+    for (const tc of toolCalls) {
+      const handler = this.options.clientTools?.[tc.toolName];
+      if (handler === "interactive") {
+        const toolPartIndex = state.parts.findIndex(
+          (p) => p.type === "tool-call" && p.toolCallId === tc.toolCallId
+        );
+        if (toolPartIndex >= 0) {
+          const part = state.parts[toolPartIndex];
+          state.parts[toolPartIndex] = { ...part };
+        }
+      } else if (handler) {
+        try {
+          const result = await handler(tc.args, {
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            signal: this._clientToolAbortController.signal
+          });
+          this._completedToolResults.push({
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            result,
+            outputVariable: tc.outputVariable,
+            blockIndex: tc.blockIndex
+          });
+          this.emitToolOutputAvailable(tc.toolCallId, result);
+        } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : "Tool execution failed";
+          this._completedToolResults.push({
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            error: errorMessage,
+            outputVariable: tc.outputVariable,
+            blockIndex: tc.blockIndex
+          });
+          this.emitToolOutputError(tc.toolCallId, errorMessage);
+        }
+      } else {
+        const errorMessage = `No client handler for tool: ${tc.toolName}`;
+        this._completedToolResults.push({
+          toolCallId: tc.toolCallId,
+          toolName: tc.toolName,
+          error: errorMessage,
+          outputVariable: tc.outputVariable,
+          blockIndex: tc.blockIndex
+        });
+        this.emitToolOutputError(tc.toolCallId, errorMessage);
+      }
+    }
+    if (this._pendingToolsByCallId.size === 0 && this._completedToolResults.length > 0) {
+      await this.continueWithClientToolResults();
+    }
+  }
 };
 
 // src/stream/reader.ts
@@ -763,9 +1092,6 @@ async function* parseSSEStream(response, signal) {
   }
 }
 
-// src/index.ts
-import { isOtherThread, isFileReference, isFileReferenceArray as isFileReferenceArray2 } from "@octavus/core";
-
 // src/transports/types.ts
 function isSocketTransport(transport) {
   return "connect" in transport && "disconnect" in transport && "connectionState" in transport && "onConnectionStateChange" in transport;
@@ -775,32 +1101,45 @@ function isSocketTransport(transport) {
 import { isAbortError as isAbortError2 } from "@octavus/core";
 function createHttpTransport(options) {
   let abortController = null;
+  async function* streamResponse(responsePromise) {
+    try {
+      const response = await responsePromise;
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => `Request failed: ${response.status}`);
+        throw new Error(errorText);
+      }
+      if (!response.body) {
+        throw new Error("Response body is empty");
+      }
+      for await (const event of parseSSEStream(response, abortController.signal)) {
+        if (abortController?.signal.aborted) {
+          break;
+        }
+        yield event;
+      }
+    } catch (err) {
+      if (isAbortError2(err)) {
+        return;
+      }
+      throw err;
+    }
+  }
   return {
     async *trigger(triggerName, input) {
       abortController = new AbortController();
-      try {
-        const response = await options.triggerRequest(triggerName, input, {
-          signal: abortController.signal
-        });
-        if (!response.ok) {
-          const errorText = await response.text().catch(() => `Request failed: ${response.status}`);
-          throw new Error(errorText);
-        }
-        if (!response.body) {
-          throw new Error("Response body is empty");
-        }
-        for await (const event of parseSSEStream(response, abortController.signal)) {
-          if (abortController.signal.aborted) {
-            break;
-          }
-          yield event;
-        }
-      } catch (err) {
-        if (isAbortError2(err)) {
-          return;
-        }
-        throw err;
-      }
+      const response = options.request(
+        { type: "trigger", triggerName, input },
+        { signal: abortController.signal }
+      );
+      yield* streamResponse(response);
+    },
+    async *continueWithToolResults(executionId, toolResults) {
+      abortController = new AbortController();
+      const response = options.request(
+        { type: "continue", executionId, toolResults },
+        { signal: abortController.signal }
+      );
+      yield* streamResponse(response);
     },
     stop() {
       abortController?.abort();
@@ -956,18 +1295,104 @@ function createSocketTransport(options) {
         eventResolver(null);
         eventResolver = null;
       }
+    },
+    /**
+     * Continue execution with tool results after client-side tool handling.
+     * @param executionId - The execution ID from the client-tool-request event
+     * @param toolResults - All tool results (server + client) to send
+     */
+    async *continueWithToolResults(executionId, toolResults) {
+      await ensureConnected();
+      eventQueue = [];
+      isStreaming = true;
+      socket.send(
+        JSON.stringify({
+          type: "continue",
+          executionId,
+          toolResults
+        })
+      );
+      while (true) {
+        const event = await nextEvent();
+        if (event === null) break;
+        yield event;
+        if (event.type === "finish" || event.type === "error") break;
+      }
     }
   };
 }
+
+// src/index.ts
+import {
+  AppError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  ForbiddenError,
+  OctavusError as OctavusError2,
+  isRateLimitError,
+  isAuthenticationError,
+  isProviderError,
+  isToolError,
+  isRetryableError,
+  isValidationError,
+  createErrorEvent,
+  errorToStreamEvent,
+  createInternalErrorEvent,
+  createApiErrorEvent,
+  generateId as generateId2,
+  isAbortError as isAbortError3,
+  MAIN_THREAD,
+  resolveThread,
+  isMainThread,
+  threadForPart as threadForPart2,
+  isOtherThread,
+  isFileReference,
+  isFileReferenceArray as isFileReferenceArray2,
+  safeParseStreamEvent as safeParseStreamEvent3,
+  safeParseUIMessage,
+  safeParseUIMessages,
+  OCTAVUS_SKILL_TOOLS,
+  isOctavusSkillTool,
+  getSkillSlugFromToolCall
+} from "@octavus/core";
 export {
+  AppError,
+  ConflictError,
+  ForbiddenError,
+  MAIN_THREAD,
+  NotFoundError,
+  OCTAVUS_SKILL_TOOLS,
   OctavusChat,
+  OctavusError2 as OctavusError,
+  ValidationError,
+  createApiErrorEvent,
+  createErrorEvent,
   createHttpTransport,
+  createInternalErrorEvent,
   createSocketTransport,
+  errorToStreamEvent,
+  generateId2 as generateId,
+  getSkillSlugFromToolCall,
+  isAbortError3 as isAbortError,
+  isAuthenticationError,
   isFileReference,
   isFileReferenceArray2 as isFileReferenceArray,
+  isMainThread,
+  isOctavusSkillTool,
   isOtherThread,
+  isProviderError,
+  isRateLimitError,
+  isRetryableError,
   isSocketTransport,
+  isToolError,
+  isValidationError,
   parseSSEStream,
+  resolveThread,
+  safeParseStreamEvent3 as safeParseStreamEvent,
+  safeParseUIMessage,
+  safeParseUIMessages,
+  threadForPart2 as threadForPart,
   uploadFiles
 };
 //# sourceMappingURL=index.js.map