@octavus/client-sdk 2.19.0 → 2.20.0

package/dist/index.cjs

@@ -0,0 +1,2050 @@
+"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_core5.AppError,
+  ConflictError: () => import_core5.ConflictError,
+  ForbiddenError: () => import_core5.ForbiddenError,
+  MAIN_THREAD: () => import_core5.MAIN_THREAD,
+  NotFoundError: () => import_core5.NotFoundError,
+  OCTAVUS_SKILL_TOOLS: () => import_core5.OCTAVUS_SKILL_TOOLS,
+  OctavusChat: () => OctavusChat,
+  OctavusError: () => import_core5.OctavusError,
+  ValidationError: () => import_core5.ValidationError,
+  createApiErrorEvent: () => import_core5.createApiErrorEvent,
+  createErrorEvent: () => import_core5.createErrorEvent,
+  createHttpTransport: () => createHttpTransport,
+  createInternalErrorEvent: () => import_core5.createInternalErrorEvent,
+  createPollingTransport: () => createPollingTransport,
+  createSocketTransport: () => createSocketTransport,
+  errorToStreamEvent: () => import_core5.errorToStreamEvent,
+  generateId: () => import_core5.generateId,
+  getSkillSlugFromToolCall: () => import_core5.getSkillSlugFromToolCall,
+  isAbortError: () => import_core5.isAbortError,
+  isAuthenticationError: () => import_core5.isAuthenticationError,
+  isFileReference: () => import_core5.isFileReference,
+  isFileReferenceArray: () => import_core5.isFileReferenceArray,
+  isMainThread: () => import_core5.isMainThread,
+  isOctavusSkillTool: () => import_core5.isOctavusSkillTool,
+  isOtherThread: () => import_core5.isOtherThread,
+  isProviderError: () => import_core5.isProviderError,
+  isRateLimitError: () => import_core5.isRateLimitError,
+  isRetryableError: () => import_core5.isRetryableError,
+  isSocketTransport: () => isSocketTransport,
+  isToolError: () => import_core5.isToolError,
+  isValidationError: () => import_core5.isValidationError,
+  parseSSEStream: () => parseSSEStream,
+  resolveThread: () => import_core5.resolveThread,
+  safeParseStreamEvent: () => import_core5.safeParseStreamEvent,
+  safeParseUIMessage: () => import_core5.safeParseUIMessage,
+  safeParseUIMessages: () => import_core5.safeParseUIMessages,
+  threadForPart: () => import_core5.threadForPart,
+  uploadFiles: () => uploadFiles
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/chat.ts
+var import_core = require("@octavus/core");
+
+// src/files.ts
+var UPLOAD_DEFAULTS = {
+  timeoutMs: 6e4,
+  maxRetries: 2,
+  retryDelayMs: 1e3
+};
+var UploadError = class extends Error {
+  constructor(message, retryable, status) {
+    super(message);
+    this.retryable = retryable;
+    this.status = status;
+    this.name = "UploadError";
+  }
+};
+function uploadFileWithProgress(url, file, onProgress, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    if (timeoutMs !== void 0 && timeoutMs > 0) {
+      xhr.timeout = timeoutMs;
+      xhr.addEventListener("timeout", () => {
+        reject(new UploadError(`Upload timed out after ${timeoutMs}ms`, true));
+      });
+    }
+    xhr.upload.addEventListener("progress", (event) => {
+      if (event.lengthComputable) {
+        const progress = Math.round(event.loaded / event.total * 100);
+        onProgress?.(progress);
+      }
+    });
+    xhr.addEventListener("load", () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve();
+      } else {
+        const detail = xhr.responseText ? `: ${xhr.responseText}` : "";
+        const retryable = xhr.status >= 500 || xhr.status === 429;
+        reject(
+          new UploadError(
+            `Upload failed with status ${xhr.status}${detail}`,
+            retryable,
+            xhr.status
+          )
+        );
+      }
+    });
+    xhr.addEventListener("error", () => {
+      reject(new UploadError("Upload failed: network error", true));
+    });
+    xhr.addEventListener("abort", () => {
+      reject(new UploadError("Upload aborted", false));
+    });
+    xhr.open("PUT", url);
+    xhr.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+    xhr.send(file);
+  });
+}
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function uploadFileWithRetry(url, file, onProgress, timeoutMs, maxRetries, retryDelayMs) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      await uploadFileWithProgress(url, file, onProgress, timeoutMs);
+      return;
+    } catch (err) {
+      lastError = err;
+      const isRetryable = err instanceof UploadError && err.retryable;
+      if (!isRetryable || attempt >= maxRetries) {
+        break;
+      }
+      onProgress?.(0);
+      await delay(retryDelayMs);
+    }
+  }
+  throw lastError;
+}
+async function uploadFiles(files, options) {
+  const fileArray = Array.from(files);
+  if (fileArray.length === 0) {
+    return [];
+  }
+  const timeoutMs = options.timeoutMs ?? UPLOAD_DEFAULTS.timeoutMs;
+  const maxRetries = options.maxRetries ?? UPLOAD_DEFAULTS.maxRetries;
+  const retryDelayMs = options.retryDelayMs ?? UPLOAD_DEFAULTS.retryDelayMs;
+  const { files: uploadInfos } = await options.requestUploadUrls(
+    fileArray.map((f) => ({
+      filename: f.name,
+      mediaType: f.type || "application/octet-stream",
+      size: f.size
+    }))
+  );
+  const references = [];
+  for (let i = 0; i < fileArray.length; i++) {
+    const file = fileArray[i];
+    const uploadInfo = uploadInfos[i];
+    await uploadFileWithRetry(
+      uploadInfo.uploadUrl,
+      file,
+      options.onProgress ? (progress) => options.onProgress(i, progress) : void 0,
+      timeoutMs,
+      maxRetries,
+      retryDelayMs
+    );
+    references.push({
+      id: uploadInfo.id,
+      mediaType: file.type || "application/octet-stream",
+      url: uploadInfo.downloadUrl,
+      filename: file.name,
+      size: file.size
+    });
+  }
+  return references;
+}
+
+// src/chat.ts
+var OPERATION_BLOCK_TYPES = /* @__PURE__ */ new Set(["set-resource", "serialize-thread", "generate-image"]);
+function createUserMessage(input, files) {
+  const parts = [];
+  if (files && files.length > 0) {
+    for (const file of files) {
+      parts.push({
+        type: "file",
+        id: file.id,
+        mediaType: file.mediaType,
+        url: file.url,
+        filename: file.filename,
+        size: file.size
+      });
+    }
+  }
+  if (input.content !== void 0) {
+    if (typeof input.content === "string") {
+      parts.push({ type: "text", text: input.content, status: "done" });
+    } else {
+      const typeName = input.content.type ?? "object";
+      parts.push({
+        type: "object",
+        id: (0, import_core.generateId)(),
+        typeName,
+        object: input.content,
+        status: "done"
+      });
+    }
+  }
+  return {
+    id: (0, import_core.generateId)(),
+    role: "user",
+    parts,
+    status: "done",
+    createdAt: /* @__PURE__ */ new Date()
+  };
+}
+function parsePartialJson(jsonText) {
+  if (!jsonText.trim()) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(jsonText);
+  } catch {
+  }
+  let fixed = jsonText;
+  let openBraces = 0;
+  let openBrackets = 0;
+  let inString = false;
+  let escaped = false;
+  for (const char of fixed) {
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (!inString) {
+      if (char === "{") openBraces += 1;
+      else if (char === "}") openBraces -= 1;
+      else if (char === "[") openBrackets += 1;
+      else if (char === "]") openBrackets -= 1;
+    }
+  }
+  if (escaped) {
+    fixed += "\\";
+  }
+  if (inString) {
+    fixed += '"';
+  }
+  while (openBrackets > 0) {
+    fixed += "]";
+    openBrackets -= 1;
+  }
+  while (openBraces > 0) {
+    fixed += "}";
+    openBraces -= 1;
+  }
+  try {
+    return JSON.parse(fixed);
+  } catch {
+    return void 0;
+  }
+}
+function createEmptyStreamingState() {
+  return {
+    messageId: (0, import_core.generateId)(),
+    parts: [],
+    activeBlock: null,
+    blocks: /* @__PURE__ */ new Map(),
+    currentTextPartIndex: null,
+    currentReasoningPartIndex: null,
+    currentObjectPartIndex: null,
+    accumulatedJson: "",
+    activeWorkers: /* @__PURE__ */ new Map(),
+    toolInputBuffers: /* @__PURE__ */ new Map()
+  };
+}
+function buildMessageFromState(state, status) {
+  return {
+    id: state.messageId,
+    role: "assistant",
+    parts: [...state.parts],
+    status,
+    createdAt: /* @__PURE__ */ new Date()
+  };
+}
+function finalizeParts(parts, workerError) {
+  return 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" };
+    }
+    if (part.type === "worker" && part.status === "running") {
+      return {
+        ...part,
+        status: "error",
+        error: workerError,
+        parts: finalizeParts(part.parts)
+        // Recursive for nested parts
+      };
+    }
+    return part;
+  });
+}
+var OctavusChat = class {
+  // Private state
+  _messages;
+  _status = "idle";
+  _error = null;
+  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;
+  // Flag indicating automatic client tools have completed and are ready to continue
+  // We wait for the finish event before actually continuing to avoid race conditions
+  _readyToContinue = false;
+  // Flag indicating the finish event with client-tool-calls reason has been received
+  // Used to handle the race condition where finish arrives before async tools complete
+  _finishEventReceived = false;
+  // Tracks whether the rollback anchor has been synced for the current trigger execution.
+  // Prevents continuation start events from overwriting the pre-trigger rollback point.
+  _rollbackSynced = false;
+  // Last trigger snapshot for retry support
+  _lastTrigger = null;
+  // Listener sets for reactive frameworks
+  listeners = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.options = options;
+    this._messages = options.initialMessages ?? [];
+    this.transport = options.transport;
+  }
+  /**
+   * Update mutable options (callbacks and tool handlers) without recreating the instance.
+   * Used by the React hook to keep options fresh across renders, but can also be
+   * called directly by non-React consumers.
+   *
+   * `transport` and `initialMessages` are excluded since they're only consumed at construction time.
+   */
+  updateOptions(updates) {
+    this.options = { ...this.options, ...updates };
+  }
+  // =========================================================================
+  // Public Getters
+  // =========================================================================
+  get messages() {
+    return this._messages;
+  }
+  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;
+  }
+  /**
+   * Whether `retry()` can be called.
+   * True when a trigger has been sent and the chat is not currently streaming or awaiting input.
+   */
+  get canRetry() {
+    return this._lastTrigger !== null && this._status !== "streaming" && this._status !== "awaiting-input";
+  }
+  // =========================================================================
+  // Public State Management
+  // =========================================================================
+  /**
+   * Replace the message list with externally-provided messages.
+   *
+   * Use this to sync with server-authoritative state (e.g., after an execution
+   * completes or when an observer detects new messages from another client).
+   *
+   * Must NOT be called while streaming — only when status is `idle` or `error`.
+   */
+  replaceMessages(messages) {
+    this._messages = messages;
+    this.notifyListeners();
+  }
+  // =========================================================================
+  // Subscription Methods (for reactive frameworks)
+  // =========================================================================
+  /**
+   * Subscribe to state changes. The callback is called whenever messages, status, or error changes.
+   * @returns Unsubscribe function
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  notifyListeners() {
+    this.listeners.forEach((l) => l());
+  }
+  // =========================================================================
+  // Private Setters (notify listeners)
+  // =========================================================================
+  setMessages(messages) {
+    this._messages = messages;
+    this.notifyListeners();
+  }
+  setStatus(status) {
+    this._status = status;
+    this.notifyListeners();
+  }
+  setError(error) {
+    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
+  // =========================================================================
+  /**
+   * Trigger the agent and optionally add a user message to the chat.
+   *
+   * @param triggerName - The trigger name defined in the agent's protocol.yaml
+   * @param input - Input parameters for the trigger (variable substitutions)
+   * @param options.userMessage - If provided, adds a user message to the chat before triggering
+   *
+   * @example Send a text message
+   * ```typescript
+   * await chat.send('user-message',
+   *   { USER_MESSAGE: message },
+   *   { userMessage: { content: message } }
+   * );
+   * ```
+   *
+   * @example Send a message with file attachments
+   * ```typescript
+   * await chat.send('user-message',
+   *   { USER_MESSAGE: message, FILES: fileRefs },
+   *   { userMessage: { content: message, files: fileRefs } }
+   * );
+   * ```
+   */
+  async send(triggerName, input, sendOptions) {
+    this.transport.stop();
+    let fileRefs;
+    if (sendOptions?.userMessage?.files) {
+      const files = sendOptions.userMessage.files;
+      if ((0, import_core.isFileReferenceArray)(files)) {
+        fileRefs = files;
+      } else if (this.options.requestUploadUrls) {
+        fileRefs = await uploadFiles(files, {
+          requestUploadUrls: this.options.requestUploadUrls,
+          ...this.options.uploadOptions
+        });
+      } else {
+        throw new Error(
+          "File upload requires requestUploadUrls option. Either provide FileReference[] or configure requestUploadUrls."
+        );
+      }
+    }
+    let processedInput = input;
+    if (input?.FILES !== void 0 && !(0, import_core.isFileReferenceArray)(input.FILES)) {
+      if (this.options.requestUploadUrls) {
+        const inputFiles = input.FILES;
+        const uploadedRefs = fileRefs ?? await uploadFiles(inputFiles, {
+          requestUploadUrls: this.options.requestUploadUrls,
+          ...this.options.uploadOptions
+        });
+        processedInput = { ...input, FILES: uploadedRefs };
+        fileRefs = fileRefs ?? uploadedRefs;
+      }
+    }
+    const currentMessages = this._messages;
+    this._lastTrigger = {
+      triggerName,
+      input: processedInput,
+      sendOptions: sendOptions?.userMessage ? { userMessage: { content: sendOptions.userMessage.content, files: fileRefs } } : void 0,
+      rollbackAfterMessageId: currentMessages[currentMessages.length - 1]?.id ?? null,
+      messageCount: currentMessages.length
+    };
+    if (sendOptions?.userMessage !== void 0) {
+      const userMsg = createUserMessage(sendOptions.userMessage, fileRefs);
+      this.setMessages([...this._messages, userMsg]);
+    }
+    await this._executeTrigger(triggerName, processedInput);
+  }
+  /**
+   * Retry the last trigger from the same starting point.
+   * Rolls back messages to the state before the last trigger, re-adds the user message
+   * (if any), and re-executes. Files are not re-uploaded.
+   *
+   * No-op if no trigger has been sent yet.
+   *
+   * @example
+   * ```typescript
+   * // After an error or unsatisfactory result
+   * if (chat.canRetry) {
+   *   await chat.retry();
+   * }
+   * ```
+   */
+  async retry() {
+    if (!this._lastTrigger) return;
+    this.transport.stop();
+    const { triggerName, input, sendOptions, rollbackAfterMessageId, messageCount } = this._lastTrigger;
+    const baseMessages = this._messages.slice(0, messageCount);
+    if (sendOptions?.userMessage) {
+      const fileRefs = sendOptions.userMessage.files;
+      const userMsg = createUserMessage(sendOptions.userMessage, fileRefs);
+      this.setMessages([...baseMessages, userMsg]);
+    } else {
+      this.setMessages(baseMessages);
+    }
+    await this._executeTrigger(triggerName, input, { rollbackAfterMessageId });
+  }
+  /**
+   * Observe an already-active execution without triggering a new one.
+   *
+   * Only supported by transports that implement `observe()` (e.g., polling transport).
+   * Use this when the page loads and the session is already streaming — the transport
+   * will start consuming events without dispatching a new trigger.
+   *
+   * When using with `initialMessages`, exclude any in-progress assistant message
+   * from the initial messages to avoid duplication — the event stream will rebuild it.
+   */
+  async observe() {
+    if (!this.transport.observe) {
+      throw new Error("Transport does not support observe()");
+    }
+    await this._consumeStream(this.transport.observe());
+  }
+  async _executeTrigger(triggerName, input, triggerOptions) {
+    await this._consumeStream(this.transport.trigger(triggerName, input, triggerOptions));
+  }
+  /**
+   * Shared streaming logic for `send()`, `retry()`, and `observe()`.
+   * Sets up streaming state, consumes an event stream, and handles errors.
+   */
+  async _consumeStream(stream) {
+    this.setStatus("streaming");
+    this.setError(null);
+    this.streamingState = createEmptyStreamingState();
+    this._pendingToolsByName.clear();
+    this._pendingToolsByCallId.clear();
+    this._completedToolResults = [];
+    this._serverToolResults = [];
+    this._pendingExecutionId = null;
+    this._readyToContinue = false;
+    this._finishEventReceived = false;
+    this._rollbackSynced = false;
+    this.updatePendingClientToolsCache();
+    try {
+      for await (const event of stream) {
+        if (this.streamingState === null) break;
+        this.handleStreamEvent(event, this.streamingState);
+      }
+    } catch (err) {
+      const errorObj = import_core.OctavusError.isInstance(err) ? err : new import_core.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 = finalizeParts(state.parts, "Stream error");
+          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;
+      this.options.onError?.(errorObj);
+    }
+  }
+  /**
+   * Upload files directly without sending a message.
+   * Useful for showing upload progress before sending.
+   *
+   * @param files - Files to upload
+   * @param onProgress - Optional progress callback
+   * @returns Array of file references
+   *
+   * @example
+   * ```typescript
+   * const fileRefs = await chat.uploadFiles(fileInput.files, (i, progress) => {
+   *   console.log(`File ${i}: ${progress}%`);
+   * });
+   * // Later...
+   * await chat.send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });
+   * ```
+   */
+  async uploadFiles(files, onProgress) {
+    if (!this.options.requestUploadUrls) {
+      throw new Error("File upload requires requestUploadUrls option");
+    }
+    return await uploadFiles(files, {
+      requestUploadUrls: this.options.requestUploadUrls,
+      onProgress,
+      ...this.options.uploadOptions
+    });
+  }
+  /**
+   * 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,
+      thread: pendingTool.thread,
+      workerId: pendingTool.workerId
+    };
+    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" && 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._readyToContinue = false;
+    this._finishEventReceived = false;
+    this.updatePendingClientToolsCache();
+    this.transport.stop();
+    const state = this.streamingState;
+    if (state && state.parts.length > 0) {
+      const finalParts = finalizeParts(state.parts, "Stopped by user");
+      const finalMessage = {
+        id: state.messageId,
+        role: "assistant",
+        parts: finalParts,
+        status: "done",
+        createdAt: /* @__PURE__ */ new Date()
+      };
+      const messages = [...this._messages];
+      const lastMsg = messages[messages.length - 1];
+      if (lastMsg?.id === state.messageId) {
+        messages[messages.length - 1] = finalMessage;
+      } else {
+        messages.push(finalMessage);
+      }
+      this.setMessages(messages);
+    }
+    this.streamingState = null;
+    this.setStatus("idle");
+    this.options.onStop?.();
+  }
+  // =========================================================================
+  // Private Helpers
+  // =========================================================================
+  /**
+   * IMMUTABILITY RULES — all event handlers must follow these patterns:
+   *
+   * 1. Never mutate an existing part/message object. Some environments (e.g.
+   *    React Native with Reanimated) freeze objects between renders, so
+   *    mutations silently fail or throw.
+   *
+   * 2. Always create a new object via spread and assign it back:
+   *      GOOD: state.parts[i] = { ...part, text: part.text + delta };
+   *       BAD: part.text += delta; state.parts[i] = { ...part };
+   *
+   * 3. For nested worker parts, copy the parts array too:
+   *      const updatedParts = [...workerPart.parts];
+   *      updatedParts[i] = { ...part, status: 'done' };
+   *      state.parts[wi] = { ...workerPart, parts: updatedParts };
+   *
+   * 4. For the messages array, copy before mutating:
+   *      const messages = [...this._messages];
+   *      messages[i] = newMessage;   // or messages.pop()
+   *      this.setMessages(messages);
+   */
+  handleStreamEvent(event, state) {
+    switch (event.type) {
+      case "start":
+        if (event.executionId) {
+          this.options.onStart?.(event.executionId);
+        }
+        if (!this._rollbackSynced && this._lastTrigger) {
+          if (event.lastMessageId !== void 0) {
+            this._lastTrigger.rollbackAfterMessageId = event.lastMessageId;
+          }
+          this._rollbackSynced = true;
+        }
+        break;
+      case "block-start": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        const block = {
+          blockId: event.blockId,
+          blockName: event.blockName,
+          blockType: event.blockType,
+          display: event.display,
+          description: event.description,
+          outputToChat: event.outputToChat ?? true,
+          thread: event.thread,
+          reasoning: "",
+          text: "",
+          toolCalls: /* @__PURE__ */ new Map()
+        };
+        state.blocks.set(event.blockId, block);
+        state.activeBlock = block;
+        const isOperation = OPERATION_BLOCK_TYPES.has(event.blockType);
+        const isHidden = event.display === "hidden";
+        if (isOperation && !isHidden) {
+          const thread = event.thread;
+          const operationPart = {
+            type: "operation",
+            operationId: event.blockId,
+            name: event.description ?? event.blockName,
+            operationType: event.blockType,
+            status: "running",
+            thread: (0, import_core.threadForPart)(thread)
+          };
+          if (workerState) {
+            const workerPart = state.parts[workerState.partIndex];
+            state.parts[workerState.partIndex] = {
+              ...workerPart,
+              parts: [...workerPart.parts, operationPart]
+            };
+          } else {
+            state.parts.push(operationPart);
+          }
+        }
+        state.currentTextPartIndex = null;
+        state.currentReasoningPartIndex = null;
+        this.updateStreamingMessage();
+        break;
+      }
+      case "block-end": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          const operationPartIndex = workerPart.parts.findIndex(
+            (p) => p.type === "operation" && p.operationId === event.blockId
+          );
+          if (operationPartIndex >= 0) {
+            const part = workerPart.parts[operationPartIndex];
+            const updatedParts = [...workerPart.parts];
+            updatedParts[operationPartIndex] = { ...part, status: "done" };
+            state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+          }
+        } else {
+          const operationPartIndex = state.parts.findIndex(
+            (p) => p.type === "operation" && p.operationId === event.blockId
+          );
+          if (operationPartIndex >= 0) {
+            const part = state.parts[operationPartIndex];
+            state.parts[operationPartIndex] = { ...part, status: "done" };
+          }
+        }
+        if (state.activeBlock?.blockId === event.blockId) {
+          state.activeBlock = null;
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "reasoning-start": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        const reasoningPart = {
+          type: "reasoning",
+          text: "",
+          status: "streaming",
+          thread: (0, import_core.threadForPart)(state.activeBlock?.thread)
+        };
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          const newParts = [...workerPart.parts, reasoningPart];
+          workerState.currentReasoningPartIndex = newParts.length - 1;
+          state.parts[workerState.partIndex] = { ...workerPart, parts: newParts };
+        } else {
+          state.parts.push(reasoningPart);
+          state.currentReasoningPartIndex = state.parts.length - 1;
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "reasoning-delta": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          if (workerState.currentReasoningPartIndex !== null) {
+            const workerPart = state.parts[workerState.partIndex];
+            const part = workerPart.parts[workerState.currentReasoningPartIndex];
+            const updatedParts = [...workerPart.parts];
+            updatedParts[workerState.currentReasoningPartIndex] = {
+              ...part,
+              text: part.text + event.delta
+            };
+            state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+          }
+        } else {
+          if (state.currentReasoningPartIndex !== null) {
+            const part = state.parts[state.currentReasoningPartIndex];
+            state.parts[state.currentReasoningPartIndex] = {
+              ...part,
+              text: part.text + event.delta
+            };
+          }
+          if (state.activeBlock) {
+            state.activeBlock.reasoning += event.delta;
+          }
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "reasoning-end": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          if (workerState.currentReasoningPartIndex !== null) {
+            const workerPart = state.parts[workerState.partIndex];
+            const part = workerPart.parts[workerState.currentReasoningPartIndex];
+            const updatedParts = [...workerPart.parts];
+            updatedParts[workerState.currentReasoningPartIndex] = {
+              ...part,
+              status: "done"
+            };
+            state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+            workerState.currentReasoningPartIndex = null;
+          }
+        } else if (state.currentReasoningPartIndex !== null) {
+          const part = state.parts[state.currentReasoningPartIndex];
+          state.parts[state.currentReasoningPartIndex] = { ...part, status: "done" };
+          state.currentReasoningPartIndex = null;
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "text-start": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        const thread = (0, import_core.threadForPart)(state.activeBlock?.thread);
+        const shouldAddPart = state.activeBlock?.outputToChat !== false || thread !== void 0;
+        if (workerState || shouldAddPart) {
+          if (event.responseType) {
+            const objectPart = {
+              type: "object",
+              id: event.id,
+              typeName: event.responseType,
+              partial: void 0,
+              object: void 0,
+              status: "streaming",
+              thread
+            };
+            if (workerState) {
+              const workerPart = state.parts[workerState.partIndex];
+              const newParts = [...workerPart.parts, objectPart];
+              workerState.currentObjectPartIndex = newParts.length - 1;
+              workerState.accumulatedJson = "";
+              workerState.currentTextPartIndex = null;
+              state.parts[workerState.partIndex] = { ...workerPart, parts: newParts };
+            } else {
+              state.parts.push(objectPart);
+              state.currentObjectPartIndex = state.parts.length - 1;
+              state.accumulatedJson = "";
+              state.currentTextPartIndex = null;
+            }
+          } else {
+            const textPart = {
+              type: "text",
+              text: "",
+              status: "streaming",
+              thread
+            };
+            if (workerState) {
+              const workerPart = state.parts[workerState.partIndex];
+              const newParts = [...workerPart.parts, textPart];
+              workerState.currentTextPartIndex = newParts.length - 1;
+              workerState.currentObjectPartIndex = null;
+              state.parts[workerState.partIndex] = { ...workerPart, parts: newParts };
+            } else {
+              state.parts.push(textPart);
+              state.currentTextPartIndex = state.parts.length - 1;
+              state.currentObjectPartIndex = null;
+            }
+          }
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "text-delta": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          if (workerState.currentObjectPartIndex !== null) {
+            workerState.accumulatedJson += event.delta;
+            const part = workerPart.parts[workerState.currentObjectPartIndex];
+            const parsed = parsePartialJson(workerState.accumulatedJson);
+            if (parsed !== void 0) {
+              const updatedParts = [...workerPart.parts];
+              updatedParts[workerState.currentObjectPartIndex] = { ...part, partial: parsed };
+              state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+            }
+          } else if (workerState.currentTextPartIndex !== null) {
+            const part = workerPart.parts[workerState.currentTextPartIndex];
+            const updatedParts = [...workerPart.parts];
+            updatedParts[workerState.currentTextPartIndex] = {
+              ...part,
+              text: part.text + event.delta
+            };
+            state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+          }
+        } else {
+          if (state.currentObjectPartIndex !== null) {
+            state.accumulatedJson += event.delta;
+            const part = state.parts[state.currentObjectPartIndex];
+            const parsed = parsePartialJson(state.accumulatedJson);
+            if (parsed !== void 0) {
+              state.parts[state.currentObjectPartIndex] = { ...part, partial: parsed };
+            }
+          } else if (state.currentTextPartIndex !== null) {
+            const part = state.parts[state.currentTextPartIndex];
+            state.parts[state.currentTextPartIndex] = {
+              ...part,
+              text: part.text + event.delta
+            };
+          }
+          if (state.activeBlock) {
+            state.activeBlock.text += event.delta;
+          }
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "text-end": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          const updatedParts = [...workerPart.parts];
+          if (workerState.currentObjectPartIndex !== null) {
+            const part = workerPart.parts[workerState.currentObjectPartIndex];
+            try {
+              const finalObject = JSON.parse(workerState.accumulatedJson);
+              updatedParts[workerState.currentObjectPartIndex] = {
+                ...part,
+                object: finalObject,
+                partial: finalObject,
+                status: "done"
+              };
+            } catch {
+              updatedParts[workerState.currentObjectPartIndex] = {
+                ...part,
+                status: "error",
+                error: "Failed to parse response as JSON"
+              };
+            }
+            workerState.currentObjectPartIndex = null;
+            workerState.accumulatedJson = "";
+          } else if (workerState.currentTextPartIndex !== null) {
+            const part = workerPart.parts[workerState.currentTextPartIndex];
+            updatedParts[workerState.currentTextPartIndex] = {
+              ...part,
+              status: "done"
+            };
+            workerState.currentTextPartIndex = null;
+          }
+          state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+        } else if (state.currentObjectPartIndex !== null) {
+          const part = state.parts[state.currentObjectPartIndex];
+          try {
+            const finalObject = JSON.parse(state.accumulatedJson);
+            state.parts[state.currentObjectPartIndex] = {
+              ...part,
+              object: finalObject,
+              partial: finalObject,
+              status: "done"
+            };
+          } catch {
+            state.parts[state.currentObjectPartIndex] = {
+              ...part,
+              status: "error",
+              error: "Failed to parse response as JSON"
+            };
+          }
+          state.currentObjectPartIndex = null;
+          state.accumulatedJson = "";
+        } else if (state.currentTextPartIndex !== null) {
+          const part = state.parts[state.currentTextPartIndex];
+          state.parts[state.currentTextPartIndex] = { ...part, status: "done" };
+          state.currentTextPartIndex = null;
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "tool-input-start": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        const toolPart = {
+          type: "tool-call",
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          displayName: event.title,
+          args: {},
+          result: void 0,
+          error: void 0,
+          status: "pending",
+          thread: (0, import_core.threadForPart)(state.activeBlock?.thread)
+        };
+        if (workerState) {
+          workerState.toolInputBuffers.set(event.toolCallId, "");
+          const workerPart = state.parts[workerState.partIndex];
+          state.parts[workerState.partIndex] = {
+            ...workerPart,
+            parts: [...workerPart.parts, toolPart]
+          };
+        } else {
+          state.toolInputBuffers.set(event.toolCallId, "");
+          state.parts.push(toolPart);
+          if (state.activeBlock) {
+            state.activeBlock.toolCalls.set(event.toolCallId, toolPart);
+          }
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "tool-input-delta": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          const existing = workerState.toolInputBuffers.get(event.toolCallId) ?? "";
+          const accumulated = existing + event.inputTextDelta;
+          workerState.toolInputBuffers.set(event.toolCallId, accumulated);
+          const workerPart = state.parts[workerState.partIndex];
+          const toolPartIndex = workerPart.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const toolPart = workerPart.parts[toolPartIndex];
+            const parsed = parsePartialJson(accumulated);
+            if (parsed !== void 0) {
+              const updatedParts = [...workerPart.parts];
+              updatedParts[toolPartIndex] = {
+                ...toolPart,
+                args: parsed
+              };
+              state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+              this.updateStreamingMessage();
+            }
+          }
+        } else {
+          const existing = state.toolInputBuffers.get(event.toolCallId) ?? "";
+          const accumulated = existing + event.inputTextDelta;
+          state.toolInputBuffers.set(event.toolCallId, accumulated);
+          const toolPartIndex = state.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const toolPart = state.parts[toolPartIndex];
+            const parsed = parsePartialJson(accumulated);
+            if (parsed !== void 0) {
+              state.parts[toolPartIndex] = {
+                ...toolPart,
+                args: parsed
+              };
+              this.updateStreamingMessage();
+            }
+          }
+        }
+        break;
+      }
+      case "tool-input-end":
+        break;
+      case "tool-input-available": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          workerState.toolInputBuffers.delete(event.toolCallId);
+          const workerPart = state.parts[workerState.partIndex];
+          const toolPartIndex = workerPart.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const part = workerPart.parts[toolPartIndex];
+            const updatedParts = [...workerPart.parts];
+            updatedParts[toolPartIndex] = {
+              ...part,
+              args: event.input,
+              status: "running"
+            };
+            state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+            this.updateStreamingMessage();
+          }
+        } else {
+          state.toolInputBuffers.delete(event.toolCallId);
+          const toolPartIndex = state.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const part = state.parts[toolPartIndex];
+            state.parts[toolPartIndex] = {
+              ...part,
+              args: event.input,
+              status: "running"
+            };
+            this.updateStreamingMessage();
+          }
+        }
+        break;
+      }
+      case "tool-output-available": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          const toolPartIndex = workerPart.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const part = workerPart.parts[toolPartIndex];
+            const updatedParts = [...workerPart.parts];
+            updatedParts[toolPartIndex] = {
+              ...part,
+              result: event.output,
+              status: "done"
+            };
+            state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+            this.updateStreamingMessage();
+          }
+        } else {
+          const toolPartIndex = state.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const part = state.parts[toolPartIndex];
+            state.parts[toolPartIndex] = {
+              ...part,
+              result: event.output,
+              status: "done"
+            };
+            this.updateStreamingMessage();
+          }
+        }
+        break;
+      }
+      case "tool-output-error": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          const toolPartIndex = workerPart.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const part = workerPart.parts[toolPartIndex];
+            const updatedParts = [...workerPart.parts];
+            updatedParts[toolPartIndex] = {
+              ...part,
+              error: event.error,
+              status: "error"
+            };
+            state.parts[workerState.partIndex] = { ...workerPart, parts: updatedParts };
+            this.updateStreamingMessage();
+          }
+        } else {
+          const toolPartIndex = state.parts.findIndex(
+            (p) => p.type === "tool-call" && p.toolCallId === event.toolCallId
+          );
+          if (toolPartIndex >= 0) {
+            const part = state.parts[toolPartIndex];
+            state.parts[toolPartIndex] = {
+              ...part,
+              error: event.error,
+              status: "error"
+            };
+            this.updateStreamingMessage();
+          }
+        }
+        break;
+      }
+      case "source": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        const thread = (0, import_core.threadForPart)(state.activeBlock?.thread);
+        let sourcePart;
+        if (event.sourceType === "url") {
+          sourcePart = {
+            type: "source",
+            sourceType: "url",
+            id: event.id,
+            url: event.url,
+            title: event.title,
+            thread
+          };
+        } else {
+          sourcePart = {
+            type: "source",
+            sourceType: "document",
+            id: event.id,
+            mediaType: event.mediaType,
+            title: event.title,
+            filename: event.filename,
+            thread
+          };
+        }
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          state.parts[workerState.partIndex] = {
+            ...workerPart,
+            parts: [...workerPart.parts, sourcePart]
+          };
+        } else {
+          state.parts.push(sourcePart);
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "file-available": {
+        const workerId = event.workerId;
+        const workerState = workerId ? state.activeWorkers.get(workerId) : void 0;
+        const filePart = {
+          type: "file",
+          id: event.id,
+          mediaType: event.mediaType,
+          url: event.url,
+          filename: event.filename,
+          size: event.size,
+          toolCallId: event.toolCallId,
+          thread: (0, import_core.threadForPart)(state.activeBlock?.thread)
+        };
+        if (workerState) {
+          const workerPart = state.parts[workerState.partIndex];
+          state.parts[workerState.partIndex] = {
+            ...workerPart,
+            parts: [...workerPart.parts, filePart]
+          };
+        } else {
+          state.parts.push(filePart);
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "resource-update":
+        this.options.onResourceUpdate?.(event.name, event.value);
+        break;
+      case "worker-start": {
+        const existingIndex = state.parts.findIndex(
+          (p) => p.type === "worker" && p.workerId === event.workerId
+        );
+        let partIndex;
+        if (existingIndex !== -1) {
+          const existingPart = state.parts[existingIndex];
+          state.parts[existingIndex] = { ...existingPart, status: "running" };
+          partIndex = existingIndex;
+        } else {
+          const workerPart = {
+            type: "worker",
+            workerId: event.workerId,
+            workerSlug: event.workerSlug,
+            description: event.description,
+            parts: [],
+            status: "running"
+          };
+          state.parts.push(workerPart);
+          partIndex = state.parts.length - 1;
+        }
+        const workerState = {
+          partIndex,
+          currentTextPartIndex: null,
+          currentReasoningPartIndex: null,
+          currentObjectPartIndex: null,
+          accumulatedJson: "",
+          toolInputBuffers: /* @__PURE__ */ new Map()
+        };
+        state.activeWorkers.set(event.workerId, workerState);
+        this.updateStreamingMessage();
+        break;
+      }
+      case "worker-result": {
+        const workerState = state.activeWorkers.get(event.workerId);
+        if (workerState !== void 0) {
+          const part = state.parts[workerState.partIndex];
+          state.parts[workerState.partIndex] = {
+            ...part,
+            output: event.output,
+            error: event.error,
+            status: event.error ? "error" : "done",
+            parts: part.parts.map((p) => {
+              if (p.type === "text" || p.type === "reasoning") {
+                if (p.status === "streaming") {
+                  return { ...p, status: "done" };
+                }
+              }
+              if (p.type === "object" && p.status === "streaming") {
+                return { ...p, status: "done" };
+              }
+              return p;
+            })
+          };
+          state.activeWorkers.delete(event.workerId);
+        }
+        this.updateStreamingMessage();
+        break;
+      }
+      case "finish": {
+        if (event.finishReason === "client-tool-calls") {
+          this._finishEventReceived = true;
+          if (this._pendingToolsByCallId.size > 0) {
+            this.setStatus("awaiting-input");
+          } else if (this._readyToContinue) {
+            this._readyToContinue = false;
+            this._finishEventReceived = false;
+            void this.continueWithClientToolResults();
+          }
+          return;
+        }
+        const finalMessage = buildMessageFromState(state, "done");
+        finalMessage.parts = finalMessage.parts.map((part) => {
+          if (part.type === "text" || part.type === "reasoning") {
+            return { ...part, status: "done" };
+          }
+          if (part.type === "object" && part.status === "streaming") {
+            return { ...part, status: "done" };
+          }
+          return part;
+        });
+        const messages = [...this._messages];
+        const lastMsg = messages[messages.length - 1];
+        if (finalMessage.parts.length > 0) {
+          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.setStatus("idle");
+        this.streamingState = null;
+        this.options.onFinish?.();
+        break;
+      }
+      case "error": {
+        throw new import_core.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() {
+    const state = this.streamingState;
+    if (!state) return;
+    const msg = buildMessageFromState(state, "streaming");
+    const messages = [...this._messages];
+    const lastMsg = messages[messages.length - 1];
+    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];
+      state.parts[toolPartIndex] = {
+        ...part,
+        result: output,
+        status: "done"
+      };
+      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];
+      state.parts[toolPartIndex] = {
+        ...part,
+        error,
+        status: "error"
+      };
+      this.updateStreamingMessage();
+    }
+  }
+  /**
+   * Continue execution with collected client tool results.
+   */
+  async continueWithClientToolResults() {
+    if (this._completedToolResults.length === 0) return;
+    if (this._pendingExecutionId === null) {
+      const errorObj = new import_core.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 = import_core.OctavusError.isInstance(err) ? err : new import_core.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,
+          thread: tc.thread,
+          workerId: tc.workerId
+        };
+        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 collectedFiles = [];
+          const result = await handler(tc.args, {
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            signal: this._clientToolAbortController.signal,
+            addFile: (file) => collectedFiles.push(file)
+          });
+          this._completedToolResults.push({
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            result,
+            files: collectedFiles.length > 0 ? collectedFiles : void 0,
+            outputVariable: tc.outputVariable,
+            blockIndex: tc.blockIndex,
+            thread: tc.thread,
+            workerId: tc.workerId
+          });
+          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,
+            thread: tc.thread,
+            workerId: tc.workerId
+          });
+          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,
+          thread: tc.thread,
+          workerId: tc.workerId
+        });
+        this.emitToolOutputError(tc.toolCallId, errorMessage);
+      }
+    }
+    if (this._pendingToolsByCallId.size === 0 && this._completedToolResults.length > 0) {
+      this._readyToContinue = true;
+      if (this._finishEventReceived) {
+        this._readyToContinue = false;
+        this._finishEventReceived = false;
+        void this.continueWithClientToolResults();
+      }
+    }
+  }
+};
+
+// src/stream/reader.ts
+var import_core2 = require("@octavus/core");
+async function* parseSSEStream(response, signal) {
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error("Response body is not readable");
+  }
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    let reading = true;
+    while (reading) {
+      if (signal?.aborted) {
+        return;
+      }
+      let readResult;
+      try {
+        readResult = await reader.read();
+      } catch (err) {
+        if ((0, import_core2.isAbortError)(err)) {
+          return;
+        }
+        throw err;
+      }
+      const { done, value } = readResult;
+      if (done) {
+        reading = false;
+        continue;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith("data: ") && line !== "data: [DONE]") {
+          try {
+            const parsed = (0, import_core2.safeParseStreamEvent)(JSON.parse(line.slice(6)));
+            if (parsed.success) {
+              yield parsed.data;
+            }
+          } catch {
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/transports/types.ts
+function isSocketTransport(transport) {
+  return "connect" in transport && "disconnect" in transport && "connectionState" in transport && "onConnectionStateChange" in transport;
+}
+
+// src/transports/http.ts
+var import_core3 = require("@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 ((0, import_core3.isAbortError)(err)) {
+        return;
+      }
+      throw err;
+    }
+  }
+  return {
+    async *trigger(triggerName, input, triggerOptions) {
+      abortController = new AbortController();
+      const request = { type: "trigger", triggerName, input };
+      if (triggerOptions?.rollbackAfterMessageId !== void 0) {
+        request.rollbackAfterMessageId = triggerOptions.rollbackAfterMessageId;
+      }
+      const response = options.request(request, { 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();
+      abortController = null;
+    }
+  };
+}
+
+// src/transports/socket.ts
+var import_core4 = require("@octavus/core");
+var SOCKET_OPEN = 1;
+function createSocketTransport(options) {
+  let socket = null;
+  let eventQueue = [];
+  let eventResolver = null;
+  let isStreaming = false;
+  let connectionState = "disconnected";
+  let connectionError;
+  let connectionPromise = null;
+  const connectionListeners = /* @__PURE__ */ new Set();
+  function setConnectionState(state, error) {
+    connectionState = state;
+    connectionError = error;
+    connectionListeners.forEach((listener) => listener(state, error));
+  }
+  function enqueueEvent(event) {
+    if (eventResolver) {
+      eventResolver(event);
+      eventResolver = null;
+    } else {
+      eventQueue.push(event);
+    }
+  }
+  function nextEvent() {
+    if (eventQueue.length > 0) {
+      return Promise.resolve(eventQueue.shift());
+    }
+    if (!isStreaming) {
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve) => {
+      eventResolver = resolve;
+    });
+  }
+  function setupSocketHandlers(sock) {
+    sock.onmessage = (e) => {
+      try {
+        const data = typeof e.data === "string" ? JSON.parse(e.data) : e.data;
+        options.onMessage?.(data);
+        const result = (0, import_core4.safeParseStreamEvent)(data);
+        if (result.success) {
+          const event = result.data;
+          enqueueEvent(event);
+          if (event.type === "finish" || event.type === "error") {
+            isStreaming = false;
+          }
+        }
+      } catch {
+      }
+    };
+    sock.onclose = () => {
+      socket = null;
+      connectionPromise = null;
+      setConnectionState("disconnected");
+      options.onClose?.();
+      isStreaming = false;
+      if (eventResolver) {
+        eventResolver(null);
+        eventResolver = null;
+      }
+    };
+  }
+  async function ensureConnected() {
+    if (socket?.readyState === SOCKET_OPEN) {
+      return;
+    }
+    if (connectionPromise) {
+      await connectionPromise;
+      return;
+    }
+    setConnectionState("connecting");
+    connectionPromise = (async () => {
+      try {
+        const sock = await options.connect();
+        socket = sock;
+        setupSocketHandlers(sock);
+        setConnectionState("connected");
+      } catch (err) {
+        socket = null;
+        connectionPromise = null;
+        const error = err instanceof Error ? err : new Error("Connection failed");
+        setConnectionState("error", error);
+        throw error;
+      }
+    })();
+    await connectionPromise;
+  }
+  return {
+    // =========================================================================
+    // Connection Management
+    // =========================================================================
+    get connectionState() {
+      return connectionState;
+    },
+    onConnectionStateChange(listener) {
+      connectionListeners.add(listener);
+      listener(connectionState, connectionError);
+      return () => connectionListeners.delete(listener);
+    },
+    async connect() {
+      await ensureConnected();
+    },
+    disconnect() {
+      if (socket) {
+        socket.close();
+        socket = null;
+      }
+      connectionPromise = null;
+      isStreaming = false;
+      if (eventResolver) {
+        eventResolver(null);
+        eventResolver = null;
+      }
+      setConnectionState("disconnected");
+    },
+    // =========================================================================
+    // Streaming
+    // =========================================================================
+    async *trigger(triggerName, input, triggerOptions) {
+      await ensureConnected();
+      eventQueue = [];
+      eventResolver = null;
+      isStreaming = true;
+      const message = { type: "trigger", triggerName, input };
+      if (triggerOptions?.rollbackAfterMessageId !== void 0) {
+        message.rollbackAfterMessageId = triggerOptions.rollbackAfterMessageId;
+      }
+      socket.send(JSON.stringify(message));
+      while (true) {
+        const event = await nextEvent();
+        if (event === null) break;
+        yield event;
+        if (event.type === "finish" || event.type === "error") break;
+      }
+    },
+    stop() {
+      if (socket?.readyState === SOCKET_OPEN) {
+        socket.send(JSON.stringify({ type: "stop" }));
+      }
+      isStreaming = false;
+      if (eventResolver) {
+        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 = [];
+      eventResolver = null;
+      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/transports/polling.ts
+var DEFAULT_POLL_INTERVAL_MS = 500;
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+function createPollingTransport(options) {
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  let abortController = null;
+  function startPolling() {
+    abortController?.abort();
+    abortController = new AbortController();
+    return abortController.signal;
+  }
+  async function* pollLoop(signal) {
+    let cursor = 0;
+    while (!signal.aborted) {
+      const result = await options.onPoll(cursor);
+      if (signal.aborted) break;
+      cursor = result.cursor;
+      for (const event of result.events) {
+        yield event;
+      }
+      if (result.status === "error" && !result.events.some(
+        (event) => typeof event === "object" && event !== null && "type" in event && event.type === "error"
+      )) {
+        throw new Error("Execution failed");
+      }
+      if (result.status !== "streaming") break;
+      await sleep(pollIntervalMs, signal);
+    }
+  }
+  return {
+    async *trigger(triggerName, input) {
+      const signal = startPolling();
+      const result = await options.onTrigger(triggerName, input);
+      if (result.error) throw new Error(result.error);
+      if (signal.aborted) return;
+      yield* pollLoop(signal);
+    },
+    // eslint-disable-next-line require-yield, @typescript-eslint/require-await
+    async *continueWithToolResults() {
+      throw new Error("continueWithToolResults is not supported by polling transport");
+    },
+    async *observe() {
+      yield* pollLoop(startPolling());
+    },
+    stop() {
+      abortController?.abort();
+      abortController = null;
+      options.onStop();
+    }
+  };
+}
+
+// src/index.ts
+var import_core5 = require("@octavus/core");
+// 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
+});
+//# sourceMappingURL=index.cjs.map