orchestrator-client 5.7.3 → 5.7.10

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_FLOW_TIMEOUT_MS: () => DEFAULT_FLOW_TIMEOUT_MS,
   EVENT_ERROR_EVENT_RECORDED: () => EVENT_ERROR_EVENT_RECORDED,
   EVENT_MESSAGE_ADDED: () => EVENT_MESSAGE_ADDED,
   EVENT_MESSAGE_STREAMING: () => EVENT_MESSAGE_STREAMING,
@@ -41,6 +42,10 @@ __export(index_exports, {
   EVENT_TASK_ITERATION_CHANGED: () => EVENT_TASK_ITERATION_CHANGED,
   EVENT_TASK_RESULT_UPDATED: () => EVENT_TASK_RESULT_UPDATED,
   EVENT_TASK_STATUS_CHANGED: () => EVENT_TASK_STATUS_CHANGED,
+  Flow: () => Flow,
+  FlowCancelledError: () => FlowCancelledError,
+  FlowError: () => FlowError,
+  FlowTimeoutError: () => FlowTimeoutError,
   Orchestrator: () => Orchestrator,
   OrchestratorAPIError: () => OrchestratorAPIError,
   OrchestratorAsync: () => OrchestratorAsync,
@@ -51,8 +56,13 @@ __export(index_exports, {
   OrchestratorNotFoundError: () => OrchestratorNotFoundError,
   RealtimeClient: () => RealtimeClient,
   VERSION: () => VERSION,
+  camelToSnake: () => camelToSnake,
   createInsecureFetch: () => createInsecureFetch,
-  loadConfig: () => loadConfig
+  deepCamelCase: () => deepCamelCase,
+  extractJsonFromMessage: () => extractJsonFromMessage,
+  loadConfig: () => loadConfig,
+  setupDefaultClient: () => setupDefaultClient,
+  snakeToCamel: () => snakeToCamel
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -73,8 +83,8 @@ var OrchestratorConnectionError = class extends OrchestratorError {
   }
 };
 var OrchestratorAuthError = class extends OrchestratorError {
-  constructor(message, statusCode = 401) {
-    super(message, { statusCode });
+  constructor(message, statusCode = 401, errorCode) {
+    super(message, { statusCode, errorCode });
     this.name = "OrchestratorAuthError";
   }
 };
@@ -101,6 +111,28 @@ var OrchestratorConfigError = class extends OrchestratorError {
   }
 };
 
+// src/utils.ts
+function snakeToCamel(str) {
+  return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function camelToSnake(str) {
+  return str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+function deepCamelCase(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(deepCamelCase);
+  }
+  if (typeof obj === "object" && obj !== null) {
+    return Object.fromEntries(
+      Object.entries(obj).map(([key, value]) => [
+        snakeToCamel(key),
+        deepCamelCase(value)
+      ])
+    );
+  }
+  return obj;
+}
+
 // src/client.ts
 var RETRY_BACKOFF_BASE = 500;
 var DEFAULT_TIMEOUT_MS = 3e4;
@@ -120,22 +152,66 @@ function buildTaskSummary(t) {
   return {
     id: t.id ?? "",
     status: t.status ?? "",
-    workflowId: t.workflowId ?? t.workflow_id ?? "",
+    workflowId: t.workflowId ?? "",
     iteration: t.iteration ?? 0,
-    maxIterations: t.maxIterations ?? t.max_iterations ?? 0,
-    goalPrompt: t.goalPrompt ?? t.goal_prompt ?? "",
+    maxIterations: t.maxIterations ?? 0,
+    goalPrompt: t.goalPrompt ?? "",
     result: t.result ?? "",
-    resultLocalized: t.resultLocalized ?? t.result_localized ?? null,
-    approvalReason: t.approvalReason ?? t.approval_reason ?? "",
-    ticketId: t.ticketId ?? t.ticket_id ?? null,
-    availableTools: t.availableTools ?? t.available_tools ?? null,
+    resultLocalized: t.resultLocalized ?? null,
+    approvalReason: t.approvalReason ?? "",
+    ticketId: t.ticketId ?? null,
+    availableTools: t.availableTools ?? null,
     insight: t.insight ?? null,
-    insightLocalized: t.insightLocalized ?? t.insight_localized ?? null,
-    createdAt: t.createdAt ?? t.created_at ?? "",
-    updatedAt: t.updatedAt ?? t.updated_at ?? "",
-    pendingTranslationsForLocales: t.pendingTranslationsForLocales ?? t.pending_translations_for_locales ?? null
+    insightLocalized: t.insightLocalized ?? null,
+    createdAt: t.createdAt ?? "",
+    updatedAt: t.updatedAt ?? "",
+    pendingTranslationsForLocales: t.pendingTranslationsForLocales ?? null
   };
 }
+function parseApiErrorBody(body, fallbackMessage) {
+  let errorCode = body.error_code ?? null;
+  if (!errorCode && body.error && typeof body.error === "object") {
+    const nested = body.error;
+    errorCode = nested.code ?? null;
+  }
+  let message = null;
+  if (typeof body.error === "string") {
+    message = body.error;
+  } else if (typeof body.message === "string") {
+    message = body.message;
+  }
+  let details = body.details ?? null;
+  const detail = body.detail;
+  if (typeof detail === "string") {
+    message = detail;
+  } else if (detail && typeof detail === "object" && !Array.isArray(detail)) {
+    const detailObj = detail;
+    if (!errorCode) {
+      errorCode = detailObj.error_code ?? null;
+    }
+    if (typeof detailObj.error === "string") {
+      message = detailObj.error;
+    } else if (typeof detailObj.message === "string") {
+      message = detailObj.message;
+    }
+    if (!details) {
+      details = detailObj;
+    }
+  }
+  if (!message) {
+    message = fallbackMessage;
+  }
+  const missingFields = body.missing_fields;
+  if (Array.isArray(missingFields) && missingFields.length > 0) {
+    const fields = missingFields.filter(
+      (f) => typeof f === "string"
+    );
+    if (fields.length > 0) {
+      message = `${message} (missing: ${fields.join(", ")})`;
+    }
+  }
+  return { message, errorCode, details };
+}
 var OrchestratorAsync = class {
   constructor(opts = {}) {
     this._abortController = null;
@@ -149,7 +225,7 @@ var OrchestratorAsync = class {
     this._timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this._maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
     this._locale = opts.locale;
-    this._fetch = opts.fetch ?? globalThis.fetch;
+    this._fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
     if (opts.insecure && !opts.fetch && typeof process !== "undefined" && process.versions?.node) {
       this._insecure = true;
     }
@@ -163,6 +239,11 @@ var OrchestratorAsync = class {
   _makeUrl(path) {
     return `${this._baseUrl}${path}`;
   }
+  _makeAbsoluteUrl(path) {
+    const raw = this._makeUrl(path);
+    const base = typeof globalThis.location !== "undefined" ? globalThis.location.href : void 0;
+    return new URL(raw, base);
+  }
   async _resolveHeaders() {
     const headers = {};
     if (this._apiKey) {
@@ -179,7 +260,7 @@ var OrchestratorAsync = class {
     return headers;
   }
   async _request(method, path, opts) {
-    const url = new URL(this._makeUrl(path));
+    const url = this._makeAbsoluteUrl(path);
     if (opts?.params) {
       for (const [key, value] of Object.entries(opts.params)) {
         if (value !== void 0) {
@@ -207,16 +288,21 @@ var OrchestratorAsync = class {
           signal
         });
         clearTimeout(timeoutId);
-        if (response.status === 401) {
-          throw new OrchestratorAuthError(
-            `Authentication failed for ${method} ${path}`,
-            401
-          );
-        }
-        if (response.status === 403) {
+        if (response.status === 401 || response.status === 403) {
+          const defaultAuthMsg = response.status === 401 ? `Authentication failed for ${method} ${path}` : `Access denied for ${method} ${path}`;
+          let authErrorCode = null;
+          let authErrorMsg = defaultAuthMsg;
+          try {
+            const body = await response.clone().json();
+            const parsed = parseApiErrorBody(body, defaultAuthMsg);
+            authErrorMsg = parsed.message;
+            authErrorCode = parsed.errorCode;
+          } catch {
+          }
           throw new OrchestratorAuthError(
-            `Access denied for ${method} ${path}`,
-            403
+            authErrorMsg,
+            response.status,
+            authErrorCode
           );
         }
         if (response.status === 404) {
@@ -243,21 +329,27 @@ var OrchestratorAsync = class {
         if (response.ok) {
           const contentType = response.headers.get("content-type") ?? "";
           if (contentType.includes("application/json")) {
-            return response.json();
+            return deepCamelCase(await response.json());
           }
           return { _text: await response.text() };
         }
-        let errorMessage;
+        const defaultMessage = `API Error with status ${response.status}`;
+        let errorMessage = defaultMessage;
         let errorCode = null;
         let errorDetails = null;
         try {
-          const body = await response.json();
-          const error = body.error ?? body;
-          errorCode = error.code ?? null;
-          errorMessage = error.message ?? await response.text();
-          errorDetails = error.details ?? null;
+          const clonedResponse = response.clone();
+          const body = await clonedResponse.json();
+          const parsed = parseApiErrorBody(body, JSON.stringify(body));
+          errorMessage = parsed.message;
+          errorCode = parsed.errorCode;
+          errorDetails = parsed.details;
         } catch {
-          errorMessage = await response.text();
+          try {
+            errorMessage = await response.text();
+          } catch {
+            errorMessage = defaultMessage;
+          }
         }
         throw new OrchestratorAPIError(
           errorMessage,
@@ -327,7 +419,7 @@ var OrchestratorAsync = class {
       params: {
         page: params?.page,
         limit: params?.limit,
-        order_by: params?.orderBy,
+        order_by: params?.orderBy ? camelToSnake(params.orderBy) : void 0,
         order_direction: params?.orderDirection,
         workflow_id: params?.workflowId
       },
@@ -400,10 +492,10 @@ var OrchestratorAsync = class {
     };
   }
   async getArchivedMessageContent(taskId, messageId) {
-    return this._get(
-      "/task/message/archived-content",
-      { task_id: taskId, message_id: messageId }
-    );
+    return this._get("/task/message/archived-content", {
+      task_id: taskId,
+      message_id: messageId
+    });
   }
   async getTaskCompactions(taskId) {
     return this._get("/task/compactions", {
@@ -462,19 +554,39 @@ var OrchestratorAsync = class {
   // ------------------------------------------------------------------
   // Attachments
   // ------------------------------------------------------------------
-  async uploadAttachment(file, filename) {
+  async uploadAttachment(file, filename, options) {
     const formData = new FormData();
     formData.append("file", file, filename);
     const headers = await this._resolveHeaders();
     const response = await this._fetch(this._makeUrl("/attachment"), {
       method: "POST",
       headers: { ...headers },
-      body: formData
+      body: formData,
+      signal: options?.signal
     });
     if (!response.ok) {
+      const defaultMessage = `Attachment upload failed: ${response.statusText}`;
+      let errorMessage = defaultMessage;
+      let errorCode = null;
+      let errorDetails = null;
+      try {
+        const body = await response.clone().json();
+        const parsed = parseApiErrorBody(body, defaultMessage);
+        errorMessage = parsed.message;
+        errorCode = parsed.errorCode;
+        errorDetails = parsed.details;
+      } catch {
+        try {
+          errorMessage = await response.text() || defaultMessage;
+        } catch {
+          errorMessage = defaultMessage;
+        }
+      }
       throw new OrchestratorAPIError(
-        `Attachment upload failed: ${response.statusText}`,
-        response.status
+        errorMessage,
+        response.status,
+        errorCode,
+        errorDetails ?? void 0
       );
     }
     const data = await response.json();
@@ -942,7 +1054,7 @@ var OrchestratorAsync = class {
   // ------------------------------------------------------------------
   async listErrors(params) {
     const authHeaders = await this._resolveHeaders();
-    const url = new URL(this._makeUrl("/errors"));
+    const url = this._makeAbsoluteUrl("/errors");
     if (params?.page !== void 0)
       url.searchParams.set("page", String(params.page));
     if (params?.limit !== void 0)
@@ -992,10 +1104,24 @@ var OrchestratorAsync = class {
     if (since) params.since = since;
     return this._get("/errors/stats", params);
   }
-  async countErrors(since) {
-    const params = {};
-    if (since) params.since = since;
-    return this._get("/errors/count", params);
+  async countErrors(since, severity) {
+    const authHeaders = await this._resolveHeaders();
+    const url = new URL(this._makeUrl("/errors/count"));
+    if (since) url.searchParams.set("since", since);
+    for (const s of severity ?? []) {
+      url.searchParams.append("severity", s);
+    }
+    const response = await this._fetch(url.toString(), {
+      method: "GET",
+      headers: { ...authHeaders }
+    });
+    if (!response.ok) {
+      throw new OrchestratorAPIError(
+        `countErrors failed: ${response.statusText}`,
+        response.status
+      );
+    }
+    return deepCamelCase(await response.json());
   }
   async purgeErrors() {
     return this._delete("/errors");
@@ -1027,7 +1153,35 @@ var OrchestratorAsync = class {
     return this._get("/configuration/system/status");
   }
   async updateSettings(settings) {
-    return this._post("/configuration/system/settings", settings);
+    const body = {};
+    if (settings.agentModelId !== void 0) {
+      body.agent_model_id = settings.agentModelId;
+    }
+    if (settings.orchestratorModelId !== void 0) {
+      body.orchestrator_model_id = settings.orchestratorModelId;
+    }
+    if (settings.compactorModelId !== void 0) {
+      body.compactor_model_id = settings.compactorModelId;
+    }
+    if (settings.journalModelId !== void 0) {
+      body.journal_model_id = settings.journalModelId;
+    }
+    if (settings.summaryModelId !== void 0) {
+      body.summary_model_id = settings.summaryModelId;
+    }
+    if (settings.translateModelId !== void 0) {
+      body.translate_model_id = settings.translateModelId;
+    }
+    if (settings.maxConcurrentTasksPerReplica !== void 0) {
+      body.max_concurrent_tasks_per_replica = settings.maxConcurrentTasksPerReplica;
+    }
+    if (settings.subagentsEnabled !== void 0) {
+      body.subagents_enabled = settings.subagentsEnabled;
+    }
+    if (settings.localizationTargets !== void 0) {
+      body.localization_targets = settings.localizationTargets;
+    }
+    return this._post("/configuration/system/settings", body);
   }
   async getConfigurationStatus() {
     return this._get("/configuration/status");
@@ -1047,9 +1201,7 @@ var OrchestratorAsync = class {
     return { message: data.message ?? "" };
   }
   async getLLMBackendStatus() {
-    return this._get(
-      "/configuration/llmbackend/status"
-    );
+    return this._get("/configuration/llmbackend/status");
   }
   async addLLMBackend(host, apiKey) {
     const data = await this._post(
@@ -1066,9 +1218,7 @@ var OrchestratorAsync = class {
     return { message: data.message ?? "" };
   }
   async getMCPServerStatus() {
-    return this._get(
-      "/configuration/mcpserver/status"
-    );
+    return this._get("/configuration/mcpserver/status");
   }
   async addMCPServer(host, apiKey) {
     const data = await this._post(
@@ -1257,8 +1407,8 @@ var Orchestrator = class {
   // ------------------------------------------------------------------
   // Attachments
   // ------------------------------------------------------------------
-  uploadAttachment(file, filename) {
-    return runSync(this._async.uploadAttachment(file, filename));
+  uploadAttachment(file, filename, options) {
+    return runSync(this._async.uploadAttachment(file, filename, options));
   }
   downloadAttachment(attachmentId) {
     return runSync(this._async.downloadAttachment(attachmentId));
@@ -1459,8 +1609,8 @@ var Orchestrator = class {
   getErrorStats(since) {
     return runSync(this._async.getErrorStats(since));
   }
-  countErrors(since) {
-    return runSync(this._async.countErrors(since));
+  countErrors(since, severity) {
+    return runSync(this._async.countErrors(since, severity));
   }
   purgeErrors() {
     return runSync(this._async.purgeErrors());
@@ -1763,12 +1913,18 @@ var RealtimeClient = class {
   /**
    * Dispatch a message envelope to registered handlers and subscribers.
    * The server sends: socket.emit("message", {type: "message", event: {..., event_type: "...", ...}})
+   *
+   * All event payloads are deep-converted from snake_case to camelCase so
+   * consumers receive consistent camelCase objects (same convention as the
+   * REST responses from _request).  The raw event_type string is extracted
+   * before conversion so the handler-map lookup still works.
    */
   _dispatch(payload) {
     const envelope = payload;
-    const event = envelope.event ?? envelope;
-    const eventType = event.event_type;
+    const rawEvent = envelope.event ?? envelope;
+    const eventType = rawEvent.event_type;
     if (!eventType) return;
+    const event = deepCamelCase(rawEvent);
     const handlers = this._handlers.get(eventType);
     if (handlers) {
       for (const h of handlers) {
@@ -1977,10 +2133,303 @@ var RealtimeClient = class {
   }
 };
 
+// src/flow.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "translation"
+]);
+var DEFAULT_FLOW_TIMEOUT_MS = 6e5;
+var _defaultClient;
+var _defaultRealtime;
+function setupDefaultClient(client, realtime) {
+  _defaultClient = client;
+  _defaultRealtime = realtime;
+}
+function getDefaultClient() {
+  if (!_defaultClient) {
+    throw new Error(
+      "No default OrchestratorAsync set. Call setupDefaultClient() during application startup, or pass client to flow.run()."
+    );
+  }
+  return _defaultClient;
+}
+function getDefaultRealtime() {
+  return _defaultRealtime;
+}
+var FlowError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FlowError";
+  }
+};
+var FlowTimeoutError = class extends FlowError {
+  constructor(message) {
+    super(message);
+    this.name = "FlowTimeoutError";
+  }
+};
+var FlowCancelledError = class extends FlowError {
+  constructor(taskId) {
+    super(`Task ${taskId} was cancelled`);
+    this.name = "FlowCancelledError";
+    this.taskId = taskId;
+  }
+};
+function extractJsonFromMessage(content) {
+  const cleaned = content.replace(/^\ufeff|\u200b|\u200c|\u200d/, "").trim();
+  if (cleaned.startsWith("{")) {
+    try {
+      return JSON.parse(cleaned);
+    } catch {
+    }
+  }
+  const start = content.indexOf("{");
+  const end = content.lastIndexOf("}");
+  if (start !== -1 && end !== -1 && end > start) {
+    try {
+      return JSON.parse(content.slice(start, end + 1));
+    } catch {
+    }
+  }
+  const jsonFenceMatch = content.match(/```(?:json)\s*\n([\s\S]*?)\n```/i);
+  if (jsonFenceMatch) {
+    try {
+      return JSON.parse(jsonFenceMatch[1].trim());
+    } catch {
+    }
+  }
+  const anyFenceMatch = content.match(/```(?:[\w]*)\s*\n([\s\S]*?)\n```/);
+  if (anyFenceMatch) {
+    try {
+      return JSON.parse(anyFenceMatch[1].trim());
+    } catch {
+    }
+  }
+  const bareBraceMatch = content.match(/\{[\s\S]*\}/);
+  if (bareBraceMatch) {
+    try {
+      return JSON.parse(bareBraceMatch[0]);
+    } catch {
+    }
+  }
+  throw new FlowError(
+    "Could not extract a valid JSON object from the agent's final message. The agent did not format its answer as required."
+  );
+}
+var Flow = class {
+  constructor() {
+    // -- Workflow-level defaults (override in subclass) --------------------
+    /** Orchestrator workflow type — `"proactive"` by default. */
+    this.workflowId = "proactive";
+    /** Maximum agent turns before the orchestrator forces a failure. */
+    this.maxIterations = 100;
+    /** LLM reasoning budget: `"low"`, `"medium"`, or `"high"`. */
+    this.reasoningEffort = "medium";
+    /**
+     * Maximum milliseconds to wait for the orchestrator task to reach a
+     * terminal state.  When exceeded, {@link FlowTimeoutError} is raised.
+     */
+    this.flowTimeoutMs = DEFAULT_FLOW_TIMEOUT_MS;
+  }
+  /**
+   * Optional system-prompt override.
+   * When set, this replaces the orchestrator's default system prompt.
+   */
+  get systemPrompt() {
+    return void 0;
+  }
+  /**
+   * Optional developer-prompt override appended after system prompt.
+   */
+  get developerPrompt() {
+    return void 0;
+  }
+  /**
+   * Restrict which MCP / built-in tools the agent may use.
+   * `undefined` means *all* tools are available.  An empty array means
+   * *no* tools — text-only reasoning.
+   */
+  get availableTools() {
+    return void 0;
+  }
+  /**
+   * Per-task feature toggles sent in the creation request.
+   * By default summaries and translation are disabled since flow
+   * output is typically machine-consumed, not human-read.
+   * Override in subclasses that produce human-facing content.
+   */
+  get taskOptions() {
+    return { disableSummaries: true, disableTranslation: true };
+  }
+  /**
+   * Override the agent model for this flow.
+   */
+  get agentModelId() {
+    return void 0;
+  }
+  /**
+   * Override the orchestrator (validation) model for this flow.
+   */
+  get orchestratorModelId() {
+    return void 0;
+  }
+  /**
+   * Cancel the underlying orchestrator task, if one is running.
+   *
+   * Calling `cancel()` after `run()` has returned is a no-op.
+   * The `run()` promise will reject with {@link FlowCancelledError}
+   * after the orchestrator task transitions to `"cancelled"`.
+   */
+  async cancel(client) {
+    if (!this._lastTaskId) return;
+    const resolvedClient = client ?? getDefaultClient();
+    await resolvedClient.cancelTask(this._lastTaskId);
+  }
+  // -- Lifecycle ---------------------------------------------------------
+  /**
+   * Execute the flow end-to-end.
+   *
+   * @returns The parsed result.
+   * @throws {FlowError} If the task fails, times out, or cannot be parsed.
+   */
+  async run(params) {
+    const client = params?.client ?? getDefaultClient();
+    const realtime = params?.realtime ?? getDefaultRealtime();
+    const timeoutMs = params?.timeoutMs ?? this.flowTimeoutMs;
+    console.log(
+      `[Flow] Starting ${this.constructor.name} \u2014 workflow=${this.workflowId} goal=${this.goalPrompt.slice(0, 80)}`
+    );
+    const response = await client.createTask({
+      workflowId: this.workflowId,
+      goalPrompt: this.goalPrompt,
+      systemPrompt: this.systemPrompt,
+      developerPrompt: this.developerPrompt,
+      availableTools: this.availableTools,
+      options: this.taskOptions,
+      maxIterations: this.maxIterations,
+      reasoningEffort: this.reasoningEffort,
+      agentModelId: this.agentModelId,
+      orchestratorModelId: this.orchestratorModelId
+    });
+    this._lastTaskId = response.taskId;
+    const taskId = response.taskId;
+    console.log(
+      `[Flow] Task created \u2014 taskId=${taskId} status=${response.status}`
+    );
+    const status = await this._waitForTerminal(client, taskId, {
+      realtime,
+      timeoutMs
+    });
+    if (status.status === "cancelled") {
+      throw new FlowCancelledError(taskId);
+    }
+    const finalMessage = await this._getFinalMessage(client, taskId);
+    console.log(
+      `[Flow] ${this.constructor.name} completed \u2014 taskId=${taskId} messageLen=${finalMessage.length}`
+    );
+    return this.parseResult(finalMessage);
+  }
+  // -- Completion waiting -----------------------------------------------
+  async _waitForTerminal(client, taskId, opts) {
+    const { realtime, timeoutMs } = opts;
+    const status = await client.getTaskStatus(taskId);
+    if (TERMINAL_STATUSES.has(status.status)) {
+      console.log(
+        `[Flow] Task ${taskId} already terminal \u2014 status=${status.status}`
+      );
+      return status;
+    }
+    if (realtime) {
+      await this._waitViaSocketIO(taskId, realtime, timeoutMs);
+    } else {
+      console.log(
+        `[Flow] No RealtimeClient available \u2014 polling task ${taskId} with backoff (timeout=${timeoutMs}ms)`
+      );
+      await this._waitViaPolling(client, taskId, timeoutMs);
+    }
+    return client.getTaskStatus(taskId);
+  }
+  async _waitViaSocketIO(taskId, realtime, timeoutMs) {
+    realtime.subscribeTask(taskId);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new FlowTimeoutError(
+            `Task ${taskId} did not reach a terminal state within ${timeoutMs}ms`
+          )
+        );
+      }, timeoutMs);
+      const handler = (...args) => {
+        const event = args[0] ?? {};
+        if (event.task_id !== taskId) return;
+        const newStatus = event.new_status ?? "";
+        if (TERMINAL_STATUSES.has(newStatus)) {
+          cleanup();
+          resolve();
+        }
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        realtime.off("task_status_changed", handler);
+        realtime.unsubscribeTask(taskId);
+      };
+      realtime.on("task_status_changed", handler);
+    });
+  }
+  async _waitViaPolling(client, taskId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let delay = 1e3;
+    while (Date.now() < deadline) {
+      const status = await client.getTaskStatus(taskId);
+      if (TERMINAL_STATUSES.has(status.status)) return;
+      await this._sleep(delay);
+      delay = Math.min(Math.round(delay * 1.5), 1e4);
+    }
+    throw new FlowTimeoutError(
+      `Task ${taskId} did not reach a terminal state within ${timeoutMs}ms (polling fallback)`
+    );
+  }
+  // -- Conversation helpers ---------------------------------------------
+  async _getFinalMessage(client, taskId) {
+    const conversation = await client.getTaskConversation(taskId, {
+      includeSummaries: false,
+      excludeArchived: false
+    });
+    const messages = conversation.conversation;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.role === "assistant" && msg.content?.trim()) {
+        return msg.content;
+      }
+    }
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.role === "assistant" && msg.archived && msg.id != null) {
+        const archived = await client.getArchivedMessageContent(taskId, msg.id);
+        if (archived.content?.trim()) {
+          return archived.content;
+        }
+      }
+    }
+    const status = await client.getTaskStatus(taskId);
+    throw new FlowError(
+      `No assistant message with content found in task ${taskId}. Status: ${status.status}. Result: ${(status.result ?? "").slice(0, 200) || "empty"}. Messages in conversation: ${messages.length}.`
+    );
+  }
+  // -- Helper -----------------------------------------------------------
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
 // src/index.ts
 var VERSION = "5.6.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_FLOW_TIMEOUT_MS,
   EVENT_ERROR_EVENT_RECORDED,
   EVENT_MESSAGE_ADDED,
   EVENT_MESSAGE_STREAMING,
@@ -1992,6 +2441,10 @@ var VERSION = "5.6.0";
   EVENT_TASK_ITERATION_CHANGED,
   EVENT_TASK_RESULT_UPDATED,
   EVENT_TASK_STATUS_CHANGED,
+  Flow,
+  FlowCancelledError,
+  FlowError,
+  FlowTimeoutError,
   Orchestrator,
   OrchestratorAPIError,
   OrchestratorAsync,
@@ -2002,7 +2455,12 @@ var VERSION = "5.6.0";
   OrchestratorNotFoundError,
   RealtimeClient,
   VERSION,
+  camelToSnake,
   createInsecureFetch,
-  loadConfig
+  deepCamelCase,
+  extractJsonFromMessage,
+  loadConfig,
+  setupDefaultClient,
+  snakeToCamel
 });
 //# sourceMappingURL=index.cjs.map