orchestrator-client 5.7.4 → 5.7.12

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,
@@ -54,7 +59,9 @@ __export(index_exports, {
   camelToSnake: () => camelToSnake,
   createInsecureFetch: () => createInsecureFetch,
   deepCamelCase: () => deepCamelCase,
+  extractJsonFromMessage: () => extractJsonFromMessage,
   loadConfig: () => loadConfig,
+  setupDefaultClient: () => setupDefaultClient,
   snakeToCamel: () => snakeToCamel
 });
 module.exports = __toCommonJS(index_exports);
@@ -232,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) {
@@ -248,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) {
@@ -1042,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)
@@ -1836,6 +1848,11 @@ var RealtimeClient = class {
     this._socket = null;
     this._handlers = /* @__PURE__ */ new Map();
     this._connected = false;
+    // Every room joined through any API (subscribeTask, joinRooms, subscribe(),
+    // subscribeEvents, etc.) is tracked here so it can be replayed on reconnect.
+    // Server-side room membership is tied to the socket connection and is lost
+    // on disconnect — the full set must be re-emitted on every reconnect.
+    this._rooms = /* @__PURE__ */ new Set();
     // Multi-subscriber room-diffing state (mirrors WebSocketProvider)
     this._subscriptions = /* @__PURE__ */ new Map();
     this._currentRooms = /* @__PURE__ */ new Set();
@@ -1872,6 +1889,10 @@ var RealtimeClient = class {
     this._socket.on("connect", () => {
       this._connected = true;
       this._currentRooms = /* @__PURE__ */ new Set();
+      if (this._rooms.size > 0) {
+        this._socket?.emit("join", { rooms: [...this._rooms] });
+        this._currentRooms = new Set(this._rooms);
+      }
       this._syncRooms();
     });
     this._socket.on("disconnect", () => {
@@ -1929,7 +1950,9 @@ var RealtimeClient = class {
    */
   subscribeTask(taskId) {
     if (!this._socket) throw new Error("RealtimeClient not connected");
-    this._socket.emit("join", { rooms: [`task:${taskId}`] });
+    const room = `task:${taskId}`;
+    this._socket.emit("join", { rooms: [room] });
+    this._rooms.add(room);
   }
   /**
    * Unsubscribe from realtime events for a specific task.
@@ -1937,7 +1960,9 @@ var RealtimeClient = class {
    */
   unsubscribeTask(taskId) {
     if (!this._socket) throw new Error("RealtimeClient not connected");
-    this._socket.emit("leave", { rooms: [`task:${taskId}`] });
+    const room = `task:${taskId}`;
+    this._socket.emit("leave", { rooms: [room] });
+    this._rooms.delete(room);
   }
   /**
    * Subscribe to event-type-scoped rooms.
@@ -1947,6 +1972,7 @@ var RealtimeClient = class {
     if (!this._socket) throw new Error("RealtimeClient not connected");
     const rooms = eventTypes.map((t) => `event:${t}`);
     this._socket.emit("join", { rooms });
+    for (const r of rooms) this._rooms.add(r);
   }
   /**
    * Unsubscribe from event-type-scoped rooms.
@@ -1955,6 +1981,7 @@ var RealtimeClient = class {
     if (!this._socket) throw new Error("RealtimeClient not connected");
     const rooms = eventTypes.map((t) => `event:${t}`);
     this._socket.emit("leave", { rooms });
+    for (const r of rooms) this._rooms.delete(r);
   }
   /**
    * Subscribe to the `all` broadcast room (receives all events).
@@ -1962,20 +1989,25 @@ var RealtimeClient = class {
   subscribeAll() {
     if (!this._socket) throw new Error("RealtimeClient not connected");
     this._socket.emit("join", { rooms: ["all"] });
+    this._rooms.add("all");
   }
   /**
    * Subscribe to a locale-specific room.
    */
   subscribeLocale(locale) {
     if (!this._socket) throw new Error("RealtimeClient not connected");
-    this._socket.emit("join", { rooms: [`locale:${locale}`] });
+    const room = `locale:${locale}`;
+    this._socket.emit("join", { rooms: [room] });
+    this._rooms.add(room);
   }
   /**
    * Unsubscribe from a locale-specific room.
    */
   unsubscribeLocale(locale) {
     if (!this._socket) throw new Error("RealtimeClient not connected");
-    this._socket.emit("leave", { rooms: [`locale:${locale}`] });
+    const room = `locale:${locale}`;
+    this._socket.emit("leave", { rooms: [room] });
+    this._rooms.delete(room);
   }
   /**
    * Join arbitrary rooms by name.
@@ -1983,6 +2015,7 @@ var RealtimeClient = class {
   joinRooms(rooms) {
     if (!this._socket) throw new Error("RealtimeClient not connected");
     this._socket.emit("join", { rooms });
+    for (const r of rooms) this._rooms.add(r);
   }
   /**
    * Leave arbitrary rooms by name.
@@ -1990,6 +2023,7 @@ var RealtimeClient = class {
   leaveRooms(rooms) {
     if (!this._socket) throw new Error("RealtimeClient not connected");
     this._socket.emit("leave", { rooms });
+    for (const r of rooms) this._rooms.delete(r);
   }
   // ------------------------------------------------------------------
   // Multi-subscriber API (mirrors WebSocketProvider room-diffing)
@@ -2047,6 +2081,8 @@ var RealtimeClient = class {
     const toLeave = [...this._currentRooms].filter((r) => !needed.has(r));
     if (toJoin.length) socket.emit("join", { rooms: toJoin });
     if (toLeave.length) socket.emit("leave", { rooms: toLeave });
+    for (const r of toJoin) this._rooms.add(r);
+    for (const r of toLeave) this._rooms.delete(r);
     this._currentRooms = needed;
   }
   /**
@@ -2121,10 +2157,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,
@@ -2136,6 +2465,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,
@@ -2149,7 +2482,9 @@ var VERSION = "5.6.0";
   camelToSnake,
   createInsecureFetch,
   deepCamelCase,
+  extractJsonFromMessage,
   loadConfig,
+  setupDefaultClient,
   snakeToCamel
 });
 //# sourceMappingURL=index.cjs.map