orchestrator-client 5.7.4 → 5.7.10

package/dist/index.d.cts

@@ -580,6 +580,7 @@ declare class OrchestratorAsync {
     protected _insecure: boolean;
     close(): Promise<void>;
     protected _makeUrl(path: string): string;
+    protected _makeAbsoluteUrl(path: string): URL;
     protected _resolveHeaders(): Promise<Record<string, string>>;
     protected _request(method: string, path: string, opts?: {
         jsonBody?: unknown;
@@ -1180,6 +1181,166 @@ declare class OrchestratorConfigError extends OrchestratorError {
     constructor(message: string);
 }
 
+/**
+ * Flow abstraction — reusable orchestrator workflow patterns.
+ *
+ * Every {@link Flow} subclass describes a complete orchestrator workflow
+ * from trigger to parsed result.  The base class handles task creation,
+ * listening for completion via Socket.IO events, conversation retrieval,
+ * and result parsing; subclasses only need to define the workflow
+ * parameters and implement {@link Flow.parseResult}.
+ *
+ * Usage:
+ *
+ * ```ts
+ * class MyFlow extends Flow<MyResult> {
+ *   get goalPrompt() { return "Do the thing"; }
+ *   parseResult(finalMessage: string): MyResult { ... }
+ * }
+ *
+ * const result = await new MyFlow().run({ client: orchestrator });
+ * ```
+ *
+ * @module
+ */
+
+/** Default timeout for Socket.IO-based completion waiting (10 minutes). */
+declare const DEFAULT_FLOW_TIMEOUT_MS = 600000;
+/**
+ * Set the default {@link OrchestratorAsync} and optional
+ * {@link RealtimeClient} for all flows in this process.
+ *
+ * Call once during application startup so that `flow.run()` can be
+ * invoked without passing `client` explicitly.
+ */
+declare function setupDefaultClient(client: OrchestratorAsync, realtime?: RealtimeClient): void;
+/** Raised when a flow execution fails. */
+declare class FlowError extends Error {
+    constructor(message: string);
+}
+/** Raised when a flow's task does not reach a terminal state in time. */
+declare class FlowTimeoutError extends FlowError {
+    constructor(message: string);
+}
+/** Raised when a flow's orchestrator task was explicitly cancelled. */
+declare class FlowCancelledError extends FlowError {
+    /** The orchestrator task ID that was cancelled. */
+    taskId: string;
+    constructor(taskId: string);
+}
+/**
+ * Extract the first JSON object from an LLM message body.
+ *
+ * Strategy (in order of preference):
+ * 0. The entire trimmed message is parsed directly via `JSON.parse`.
+ * 1. A fenced code block explicitly tagged `json`.
+ * 2. Any fenced code block that parses as valid JSON.
+ * 3. The first `{…}` block that parses as valid JSON.
+ *
+ * @throws {FlowError} If nothing parses.
+ */
+declare function extractJsonFromMessage(content: string): Record<string, unknown>;
+/** Optional parameters for {@link Flow.run}. */
+interface FlowRunParams {
+    /** Orchestrator async client. Falls back to the module-level default. */
+    client?: OrchestratorAsync;
+    /**
+     * Optional realtime client for Socket.IO-based completion waiting.
+     * Falls back to the module-level default.  When neither is available
+     * the flow uses polling instead.
+     */
+    realtime?: RealtimeClient;
+    /**
+     * Maximum milliseconds to wait for completion.
+     * Defaults to {@link DEFAULT_FLOW_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Abstract base class for an orchestrator workflow flow.
+ *
+ * @typeParam T - The typed result produced by {@link parseResult}.
+ */
+declare abstract class Flow<T> {
+    /** Orchestrator workflow type — `"proactive"` by default. */
+    workflowId: string;
+    /** Maximum agent turns before the orchestrator forces a failure. */
+    maxIterations: number;
+    /** LLM reasoning budget: `"low"`, `"medium"`, or `"high"`. */
+    reasoningEffort: string;
+    /**
+     * Maximum milliseconds to wait for the orchestrator task to reach a
+     * terminal state.  When exceeded, {@link FlowTimeoutError} is raised.
+     */
+    flowTimeoutMs: number;
+    /**
+     * The task description the orchestrator agent receives.
+     * This is the primary instruction — it tells the agent *what* to do.
+     */
+    abstract get goalPrompt(): string;
+    /**
+     * Optional system-prompt override.
+     * When set, this replaces the orchestrator's default system prompt.
+     */
+    get systemPrompt(): string | undefined;
+    /**
+     * Optional developer-prompt override appended after system prompt.
+     */
+    get developerPrompt(): string | undefined;
+    /**
+     * 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(): string[] | undefined;
+    /**
+     * 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(): TaskOptions;
+    /**
+     * Override the agent model for this flow.
+     */
+    get agentModelId(): string | undefined;
+    /**
+     * Override the orchestrator (validation) model for this flow.
+     */
+    get orchestratorModelId(): string | undefined;
+    /**
+     * Parse the agent's final message into a typed result.
+     *
+     * Called *after* the task reaches `"completed"` and the final
+     * assistant message has been retrieved.
+     *
+     * @param finalMessage - The text content of the last assistant message.
+     * @throws {FlowError} If the message cannot be parsed as expected.
+     */
+    abstract parseResult(finalMessage: string): T;
+    private _lastTaskId?;
+    /**
+     * 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"`.
+     */
+    cancel(client?: OrchestratorAsync): Promise<void>;
+    /**
+     * Execute the flow end-to-end.
+     *
+     * @returns The parsed result.
+     * @throws {FlowError} If the task fails, times out, or cannot be parsed.
+     */
+    run(params?: FlowRunParams): Promise<T>;
+    private _waitForTerminal;
+    private _waitViaSocketIO;
+    private _waitViaPolling;
+    private _getFinalMessage;
+    private _sleep;
+}
+
 /**
  * Convert a snake_case string to camelCase.
  * Only converts single-underscore sequences followed by a lowercase letter.
@@ -1216,4 +1377,4 @@ declare function deepCamelCase<T>(obj: T): T;
  */
 declare const VERSION = "5.6.0";
 
-export { type ArchivedContent, type AttachmentMeta, type AttachmentUploadResponse, type AuthConfig, type CompactionEvent, type ComponentHealth, type ConfigurationStatus, type ConversationResult, EVENT_ERROR_EVENT_RECORDED, EVENT_MESSAGE_ADDED, EVENT_MESSAGE_STREAMING, EVENT_MESSAGE_SUMMARY_GENERATED, EVENT_MESSAGE_TRANSLATION_READY, EVENT_TASK_CREATED, EVENT_TASK_DELETED, EVENT_TASK_INSIGHT_UPDATED, EVENT_TASK_ITERATION_CHANGED, EVENT_TASK_RESULT_UPDATED, EVENT_TASK_STATUS_CHANGED, type ErrorCountResult, type ErrorEvent, type ErrorEventDetail, type ErrorEventListResult, type ErrorPurgeResult, type ErrorStatsResult, type EventHandler, type HealthDetail, type HealthStatus, type LLMBackendInfo, type LLMBackendStatus, type LLMModelContextInfo, type LLMModelVisionInfo, type LeaderStatus, type LockStatus, type MCPServerInfo, type MCPServerStatus, type MatrixConversationResult, type Message, type MessageDeleteMultipleResult, type MessageTranslation, type MessageTranslationReadyEvent, type MessageTranslationsResult, type MetricSnapshot, type MioContext, type MioMemoriesResult, type MioMemoryItem, Orchestrator, OrchestratorAPIError, OrchestratorAsync, OrchestratorAuthError, type OrchestratorClientOptions, type OrchestratorConfig, OrchestratorConfigError, OrchestratorConnectionError, OrchestratorError, OrchestratorNotFoundError, type Pagination$1 as Pagination, type ReadinessCheck, type ReadinessResult, RealtimeClient, type RealtimeClientOptions, type ReloadServicesResult, type ReloadStatus, type SlotInfo, type SlotsStatus, type SubagentsStatus, type SuccessResponse, type SummaryWorkerStatus, type SystemStatus, type SystemStatusSettings, type TaskCancelResponse, type TaskCreateResponse, type TaskDeleteResult, type TaskDetail, type TaskHandlerCluster, type TaskHandlerReplica, type TaskHandlerStatus, type TaskHandlerStatusLocal, type TaskJournal, type TaskListResult, type TaskOptions, type TaskSummary, type TokenWorkerStatus, type ToolCall, type ToolInfo, type ToolsListResult, VERSION, type VSATaskCreateResponse, type WebSocketClientInfo, type WebSocketStatus, type WorkflowStates, camelToSnake, createInsecureFetch, deepCamelCase, loadConfig, snakeToCamel };
+export { type ArchivedContent, type AttachmentMeta, type AttachmentUploadResponse, type AuthConfig, type CompactionEvent, type ComponentHealth, type ConfigurationStatus, type ConversationResult, DEFAULT_FLOW_TIMEOUT_MS, EVENT_ERROR_EVENT_RECORDED, EVENT_MESSAGE_ADDED, EVENT_MESSAGE_STREAMING, EVENT_MESSAGE_SUMMARY_GENERATED, EVENT_MESSAGE_TRANSLATION_READY, EVENT_TASK_CREATED, EVENT_TASK_DELETED, EVENT_TASK_INSIGHT_UPDATED, EVENT_TASK_ITERATION_CHANGED, EVENT_TASK_RESULT_UPDATED, EVENT_TASK_STATUS_CHANGED, type ErrorCountResult, type ErrorEvent, type ErrorEventDetail, type ErrorEventListResult, type ErrorPurgeResult, type ErrorStatsResult, type EventHandler, Flow, FlowCancelledError, FlowError, type FlowRunParams, FlowTimeoutError, type HealthDetail, type HealthStatus, type LLMBackendInfo, type LLMBackendStatus, type LLMModelContextInfo, type LLMModelVisionInfo, type LeaderStatus, type LockStatus, type MCPServerInfo, type MCPServerStatus, type MatrixConversationResult, type Message, type MessageDeleteMultipleResult, type MessageTranslation, type MessageTranslationReadyEvent, type MessageTranslationsResult, type MetricSnapshot, type MioContext, type MioMemoriesResult, type MioMemoryItem, Orchestrator, OrchestratorAPIError, OrchestratorAsync, OrchestratorAuthError, type OrchestratorClientOptions, type OrchestratorConfig, OrchestratorConfigError, OrchestratorConnectionError, OrchestratorError, OrchestratorNotFoundError, type Pagination$1 as Pagination, type ReadinessCheck, type ReadinessResult, RealtimeClient, type RealtimeClientOptions, type ReloadServicesResult, type ReloadStatus, type SlotInfo, type SlotsStatus, type SubagentsStatus, type SuccessResponse, type SummaryWorkerStatus, type SystemStatus, type SystemStatusSettings, type TaskCancelResponse, type TaskCreateResponse, type TaskDeleteResult, type TaskDetail, type TaskHandlerCluster, type TaskHandlerReplica, type TaskHandlerStatus, type TaskHandlerStatusLocal, type TaskJournal, type TaskListResult, type TaskOptions, type TaskSummary, type TokenWorkerStatus, type ToolCall, type ToolInfo, type ToolsListResult, VERSION, type VSATaskCreateResponse, type WebSocketClientInfo, type WebSocketStatus, type WorkflowStates, camelToSnake, createInsecureFetch, deepCamelCase, extractJsonFromMessage, loadConfig, setupDefaultClient, snakeToCamel };

package/dist/index.d.ts

@@ -580,6 +580,7 @@ declare class OrchestratorAsync {
     protected _insecure: boolean;
     close(): Promise<void>;
     protected _makeUrl(path: string): string;
+    protected _makeAbsoluteUrl(path: string): URL;
     protected _resolveHeaders(): Promise<Record<string, string>>;
     protected _request(method: string, path: string, opts?: {
         jsonBody?: unknown;
@@ -1180,6 +1181,166 @@ declare class OrchestratorConfigError extends OrchestratorError {
     constructor(message: string);
 }
 
+/**
+ * Flow abstraction — reusable orchestrator workflow patterns.
+ *
+ * Every {@link Flow} subclass describes a complete orchestrator workflow
+ * from trigger to parsed result.  The base class handles task creation,
+ * listening for completion via Socket.IO events, conversation retrieval,
+ * and result parsing; subclasses only need to define the workflow
+ * parameters and implement {@link Flow.parseResult}.
+ *
+ * Usage:
+ *
+ * ```ts
+ * class MyFlow extends Flow<MyResult> {
+ *   get goalPrompt() { return "Do the thing"; }
+ *   parseResult(finalMessage: string): MyResult { ... }
+ * }
+ *
+ * const result = await new MyFlow().run({ client: orchestrator });
+ * ```
+ *
+ * @module
+ */
+
+/** Default timeout for Socket.IO-based completion waiting (10 minutes). */
+declare const DEFAULT_FLOW_TIMEOUT_MS = 600000;
+/**
+ * Set the default {@link OrchestratorAsync} and optional
+ * {@link RealtimeClient} for all flows in this process.
+ *
+ * Call once during application startup so that `flow.run()` can be
+ * invoked without passing `client` explicitly.
+ */
+declare function setupDefaultClient(client: OrchestratorAsync, realtime?: RealtimeClient): void;
+/** Raised when a flow execution fails. */
+declare class FlowError extends Error {
+    constructor(message: string);
+}
+/** Raised when a flow's task does not reach a terminal state in time. */
+declare class FlowTimeoutError extends FlowError {
+    constructor(message: string);
+}
+/** Raised when a flow's orchestrator task was explicitly cancelled. */
+declare class FlowCancelledError extends FlowError {
+    /** The orchestrator task ID that was cancelled. */
+    taskId: string;
+    constructor(taskId: string);
+}
+/**
+ * Extract the first JSON object from an LLM message body.
+ *
+ * Strategy (in order of preference):
+ * 0. The entire trimmed message is parsed directly via `JSON.parse`.
+ * 1. A fenced code block explicitly tagged `json`.
+ * 2. Any fenced code block that parses as valid JSON.
+ * 3. The first `{…}` block that parses as valid JSON.
+ *
+ * @throws {FlowError} If nothing parses.
+ */
+declare function extractJsonFromMessage(content: string): Record<string, unknown>;
+/** Optional parameters for {@link Flow.run}. */
+interface FlowRunParams {
+    /** Orchestrator async client. Falls back to the module-level default. */
+    client?: OrchestratorAsync;
+    /**
+     * Optional realtime client for Socket.IO-based completion waiting.
+     * Falls back to the module-level default.  When neither is available
+     * the flow uses polling instead.
+     */
+    realtime?: RealtimeClient;
+    /**
+     * Maximum milliseconds to wait for completion.
+     * Defaults to {@link DEFAULT_FLOW_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Abstract base class for an orchestrator workflow flow.
+ *
+ * @typeParam T - The typed result produced by {@link parseResult}.
+ */
+declare abstract class Flow<T> {
+    /** Orchestrator workflow type — `"proactive"` by default. */
+    workflowId: string;
+    /** Maximum agent turns before the orchestrator forces a failure. */
+    maxIterations: number;
+    /** LLM reasoning budget: `"low"`, `"medium"`, or `"high"`. */
+    reasoningEffort: string;
+    /**
+     * Maximum milliseconds to wait for the orchestrator task to reach a
+     * terminal state.  When exceeded, {@link FlowTimeoutError} is raised.
+     */
+    flowTimeoutMs: number;
+    /**
+     * The task description the orchestrator agent receives.
+     * This is the primary instruction — it tells the agent *what* to do.
+     */
+    abstract get goalPrompt(): string;
+    /**
+     * Optional system-prompt override.
+     * When set, this replaces the orchestrator's default system prompt.
+     */
+    get systemPrompt(): string | undefined;
+    /**
+     * Optional developer-prompt override appended after system prompt.
+     */
+    get developerPrompt(): string | undefined;
+    /**
+     * 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(): string[] | undefined;
+    /**
+     * 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(): TaskOptions;
+    /**
+     * Override the agent model for this flow.
+     */
+    get agentModelId(): string | undefined;
+    /**
+     * Override the orchestrator (validation) model for this flow.
+     */
+    get orchestratorModelId(): string | undefined;
+    /**
+     * Parse the agent's final message into a typed result.
+     *
+     * Called *after* the task reaches `"completed"` and the final
+     * assistant message has been retrieved.
+     *
+     * @param finalMessage - The text content of the last assistant message.
+     * @throws {FlowError} If the message cannot be parsed as expected.
+     */
+    abstract parseResult(finalMessage: string): T;
+    private _lastTaskId?;
+    /**
+     * 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"`.
+     */
+    cancel(client?: OrchestratorAsync): Promise<void>;
+    /**
+     * Execute the flow end-to-end.
+     *
+     * @returns The parsed result.
+     * @throws {FlowError} If the task fails, times out, or cannot be parsed.
+     */
+    run(params?: FlowRunParams): Promise<T>;
+    private _waitForTerminal;
+    private _waitViaSocketIO;
+    private _waitViaPolling;
+    private _getFinalMessage;
+    private _sleep;
+}
+
 /**
  * Convert a snake_case string to camelCase.
  * Only converts single-underscore sequences followed by a lowercase letter.
@@ -1216,4 +1377,4 @@ declare function deepCamelCase<T>(obj: T): T;
  */
 declare const VERSION = "5.6.0";
 
-export { type ArchivedContent, type AttachmentMeta, type AttachmentUploadResponse, type AuthConfig, type CompactionEvent, type ComponentHealth, type ConfigurationStatus, type ConversationResult, EVENT_ERROR_EVENT_RECORDED, EVENT_MESSAGE_ADDED, EVENT_MESSAGE_STREAMING, EVENT_MESSAGE_SUMMARY_GENERATED, EVENT_MESSAGE_TRANSLATION_READY, EVENT_TASK_CREATED, EVENT_TASK_DELETED, EVENT_TASK_INSIGHT_UPDATED, EVENT_TASK_ITERATION_CHANGED, EVENT_TASK_RESULT_UPDATED, EVENT_TASK_STATUS_CHANGED, type ErrorCountResult, type ErrorEvent, type ErrorEventDetail, type ErrorEventListResult, type ErrorPurgeResult, type ErrorStatsResult, type EventHandler, type HealthDetail, type HealthStatus, type LLMBackendInfo, type LLMBackendStatus, type LLMModelContextInfo, type LLMModelVisionInfo, type LeaderStatus, type LockStatus, type MCPServerInfo, type MCPServerStatus, type MatrixConversationResult, type Message, type MessageDeleteMultipleResult, type MessageTranslation, type MessageTranslationReadyEvent, type MessageTranslationsResult, type MetricSnapshot, type MioContext, type MioMemoriesResult, type MioMemoryItem, Orchestrator, OrchestratorAPIError, OrchestratorAsync, OrchestratorAuthError, type OrchestratorClientOptions, type OrchestratorConfig, OrchestratorConfigError, OrchestratorConnectionError, OrchestratorError, OrchestratorNotFoundError, type Pagination$1 as Pagination, type ReadinessCheck, type ReadinessResult, RealtimeClient, type RealtimeClientOptions, type ReloadServicesResult, type ReloadStatus, type SlotInfo, type SlotsStatus, type SubagentsStatus, type SuccessResponse, type SummaryWorkerStatus, type SystemStatus, type SystemStatusSettings, type TaskCancelResponse, type TaskCreateResponse, type TaskDeleteResult, type TaskDetail, type TaskHandlerCluster, type TaskHandlerReplica, type TaskHandlerStatus, type TaskHandlerStatusLocal, type TaskJournal, type TaskListResult, type TaskOptions, type TaskSummary, type TokenWorkerStatus, type ToolCall, type ToolInfo, type ToolsListResult, VERSION, type VSATaskCreateResponse, type WebSocketClientInfo, type WebSocketStatus, type WorkflowStates, camelToSnake, createInsecureFetch, deepCamelCase, loadConfig, snakeToCamel };
+export { type ArchivedContent, type AttachmentMeta, type AttachmentUploadResponse, type AuthConfig, type CompactionEvent, type ComponentHealth, type ConfigurationStatus, type ConversationResult, DEFAULT_FLOW_TIMEOUT_MS, EVENT_ERROR_EVENT_RECORDED, EVENT_MESSAGE_ADDED, EVENT_MESSAGE_STREAMING, EVENT_MESSAGE_SUMMARY_GENERATED, EVENT_MESSAGE_TRANSLATION_READY, EVENT_TASK_CREATED, EVENT_TASK_DELETED, EVENT_TASK_INSIGHT_UPDATED, EVENT_TASK_ITERATION_CHANGED, EVENT_TASK_RESULT_UPDATED, EVENT_TASK_STATUS_CHANGED, type ErrorCountResult, type ErrorEvent, type ErrorEventDetail, type ErrorEventListResult, type ErrorPurgeResult, type ErrorStatsResult, type EventHandler, Flow, FlowCancelledError, FlowError, type FlowRunParams, FlowTimeoutError, type HealthDetail, type HealthStatus, type LLMBackendInfo, type LLMBackendStatus, type LLMModelContextInfo, type LLMModelVisionInfo, type LeaderStatus, type LockStatus, type MCPServerInfo, type MCPServerStatus, type MatrixConversationResult, type Message, type MessageDeleteMultipleResult, type MessageTranslation, type MessageTranslationReadyEvent, type MessageTranslationsResult, type MetricSnapshot, type MioContext, type MioMemoriesResult, type MioMemoryItem, Orchestrator, OrchestratorAPIError, OrchestratorAsync, OrchestratorAuthError, type OrchestratorClientOptions, type OrchestratorConfig, OrchestratorConfigError, OrchestratorConnectionError, OrchestratorError, OrchestratorNotFoundError, type Pagination$1 as Pagination, type ReadinessCheck, type ReadinessResult, RealtimeClient, type RealtimeClientOptions, type ReloadServicesResult, type ReloadStatus, type SlotInfo, type SlotsStatus, type SubagentsStatus, type SuccessResponse, type SummaryWorkerStatus, type SystemStatus, type SystemStatusSettings, type TaskCancelResponse, type TaskCreateResponse, type TaskDeleteResult, type TaskDetail, type TaskHandlerCluster, type TaskHandlerReplica, type TaskHandlerStatus, type TaskHandlerStatusLocal, type TaskJournal, type TaskListResult, type TaskOptions, type TaskSummary, type TokenWorkerStatus, type ToolCall, type ToolInfo, type ToolsListResult, VERSION, type VSATaskCreateResponse, type WebSocketClientInfo, type WebSocketStatus, type WorkflowStates, camelToSnake, createInsecureFetch, deepCamelCase, extractJsonFromMessage, loadConfig, setupDefaultClient, snakeToCamel };