wauldo 0.12.0 → 0.13.0

package/dist/index.d.mts

@@ -919,6 +919,125 @@ declare class AgentsClient {
     streamTask(taskId: string): AsyncGenerator<StateTransition>;
 }
 
+/**
+ * Workflows API client — Wauldo Workflow Runtime (Step Functions style).
+ *
+ * State-machine workflows authored as `Task` / `Choice` / `Wait` / `Pass` /
+ * `Fail` / `Succeed` states. Runs are async: `startRun` returns an
+ * `execution_id`, then poll `getRun` (or use `waitForRun`) until a terminal
+ * status.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowsClient } from "wauldo/workflows";
+ * const wf = new WorkflowsClient({ baseUrl: "https://api.wauldo.com", apiKey: "..." });
+ * const created = await wf.create({
+ *   name: "triage",
+ *   startAt: "Compute",
+ *   states: {
+ *     Compute: { type: "Task", resource: "tool:calculator", next: "Done" },
+ *     Done: { type: "Succeed" },
+ *   },
+ * });
+ * const run = await wf.startRun(created.id, { operation: "add", a: 21, b: 21 });
+ * const final = await wf.waitForRun(created.id, run.execution_id);
+ * console.log(final.status, final.output);
+ * ```
+ */
+interface WorkflowsClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    /** Tenant identifier forwarded via x-rapidapi-user header. */
+    tenant?: string;
+    /** Per-request timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+/** A workflow definition. */
+interface Workflow {
+    id: string;
+    tenant_id: string;
+    name: string;
+    description?: string;
+    start_at: string;
+    states: Record<string, unknown>;
+    version: string;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateWorkflowInput {
+    name: string;
+    startAt: string;
+    states: Record<string, unknown>;
+    description?: string;
+}
+interface WorkflowListResponse {
+    workflows: Workflow[];
+}
+/** 202 response from `POST /v1/workflows/:id/runs`. */
+interface StartRunResponse {
+    execution_id: string;
+    workflow_id: string;
+    status: string;
+}
+/**
+ * A workflow execution record. `status` is one of `running`, `succeeded`,
+ * `failed`, `timed_out`. `output` is populated on success; `error` on
+ * terminal failure.
+ */
+interface WorkflowExecution {
+    id: string;
+    workflow_id: string;
+    tenant_id: string;
+    status: string;
+    current_state?: string | null;
+    input: unknown;
+    output?: unknown;
+    started_at: number;
+    ended_at?: number | null;
+    error?: string | null;
+}
+declare const TERMINAL_WORKFLOW_STATUSES: readonly ["succeeded", "failed", "timed_out"];
+declare function isWorkflowRunTerminal(status: string): boolean;
+declare class WorkflowsClient {
+    private readonly config;
+    constructor(config: WorkflowsClientConfig);
+    private headers;
+    private request;
+    /**
+     * `POST /v1/workflows` — create a workflow definition.
+     *
+     * The server validates cycles, transition targets, choice operators,
+     * and the per-tenant cap (100) before returning 201.
+     */
+    create(input: CreateWorkflowInput): Promise<Workflow>;
+    /** `GET /v1/workflows` — list workflows for the calling tenant. */
+    list(): Promise<WorkflowListResponse>;
+    /** `GET /v1/workflows/:id` */
+    get(workflowId: string): Promise<Workflow>;
+    /** `DELETE /v1/workflows/:id` */
+    delete(workflowId: string): Promise<void>;
+    /**
+     * `POST /v1/workflows/:id/runs` — start an async execution.
+     *
+     * Returns 202 with an `execution_id` immediately. Poll {@link getRun}
+     * or use {@link waitForRun} to await completion.
+     */
+    startRun(workflowId: string, input?: unknown): Promise<StartRunResponse>;
+    /** `GET /v1/workflows/:id/runs/:execution_id` — fetch one execution. */
+    getRun(workflowId: string, executionId: string): Promise<WorkflowExecution>;
+    /**
+     * Poll {@link getRun} until the run reaches a terminal status.
+     *
+     * Rejects with an error if the run hasn't terminated within
+     * `timeoutMs`. The server enforces its own 60s wall-clock cap per run,
+     * so a timeout larger than ~75_000 is just slack for polling overhead.
+     */
+    waitForRun(workflowId: string, executionId: string, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<WorkflowExecution>;
+}
+
 /**
  * History API client — Wauldo Funnel #1 audit log.
  *
@@ -1027,4 +1146,4 @@ declare class HistoryClient {
     deleteTask(taskId: string): Promise<number>;
 }
 
-export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRevision, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type CreateRevisionInput, type CreateRevisionResponse, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HistoryClient, type HistoryClientConfig, type ExportOptions as HistoryExportOptions, type ListOptions as HistoryListOptions, type HistoryListResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type ListRevisionsResponse, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StateTransition, type Task, type TaskClaim, type TaskHistoryEntry, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, supportScore };
+export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRevision, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type CreateRevisionInput, type CreateRevisionResponse, type CreateWorkflowInput, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HistoryClient, type HistoryClientConfig, type ExportOptions as HistoryExportOptions, type ListOptions as HistoryListOptions, type HistoryListResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type ListRevisionsResponse, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StartRunResponse, type StateTransition, TERMINAL_WORKFLOW_STATUSES, type Task, type TaskClaim, type TaskHistoryEntry, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, type Workflow, type WorkflowExecution, type WorkflowListResponse, WorkflowsClient, type WorkflowsClientConfig, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, isWorkflowRunTerminal, supportScore };

package/dist/index.d.ts

@@ -919,6 +919,125 @@ declare class AgentsClient {
     streamTask(taskId: string): AsyncGenerator<StateTransition>;
 }
 
+/**
+ * Workflows API client — Wauldo Workflow Runtime (Step Functions style).
+ *
+ * State-machine workflows authored as `Task` / `Choice` / `Wait` / `Pass` /
+ * `Fail` / `Succeed` states. Runs are async: `startRun` returns an
+ * `execution_id`, then poll `getRun` (or use `waitForRun`) until a terminal
+ * status.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowsClient } from "wauldo/workflows";
+ * const wf = new WorkflowsClient({ baseUrl: "https://api.wauldo.com", apiKey: "..." });
+ * const created = await wf.create({
+ *   name: "triage",
+ *   startAt: "Compute",
+ *   states: {
+ *     Compute: { type: "Task", resource: "tool:calculator", next: "Done" },
+ *     Done: { type: "Succeed" },
+ *   },
+ * });
+ * const run = await wf.startRun(created.id, { operation: "add", a: 21, b: 21 });
+ * const final = await wf.waitForRun(created.id, run.execution_id);
+ * console.log(final.status, final.output);
+ * ```
+ */
+interface WorkflowsClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    /** Tenant identifier forwarded via x-rapidapi-user header. */
+    tenant?: string;
+    /** Per-request timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+/** A workflow definition. */
+interface Workflow {
+    id: string;
+    tenant_id: string;
+    name: string;
+    description?: string;
+    start_at: string;
+    states: Record<string, unknown>;
+    version: string;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateWorkflowInput {
+    name: string;
+    startAt: string;
+    states: Record<string, unknown>;
+    description?: string;
+}
+interface WorkflowListResponse {
+    workflows: Workflow[];
+}
+/** 202 response from `POST /v1/workflows/:id/runs`. */
+interface StartRunResponse {
+    execution_id: string;
+    workflow_id: string;
+    status: string;
+}
+/**
+ * A workflow execution record. `status` is one of `running`, `succeeded`,
+ * `failed`, `timed_out`. `output` is populated on success; `error` on
+ * terminal failure.
+ */
+interface WorkflowExecution {
+    id: string;
+    workflow_id: string;
+    tenant_id: string;
+    status: string;
+    current_state?: string | null;
+    input: unknown;
+    output?: unknown;
+    started_at: number;
+    ended_at?: number | null;
+    error?: string | null;
+}
+declare const TERMINAL_WORKFLOW_STATUSES: readonly ["succeeded", "failed", "timed_out"];
+declare function isWorkflowRunTerminal(status: string): boolean;
+declare class WorkflowsClient {
+    private readonly config;
+    constructor(config: WorkflowsClientConfig);
+    private headers;
+    private request;
+    /**
+     * `POST /v1/workflows` — create a workflow definition.
+     *
+     * The server validates cycles, transition targets, choice operators,
+     * and the per-tenant cap (100) before returning 201.
+     */
+    create(input: CreateWorkflowInput): Promise<Workflow>;
+    /** `GET /v1/workflows` — list workflows for the calling tenant. */
+    list(): Promise<WorkflowListResponse>;
+    /** `GET /v1/workflows/:id` */
+    get(workflowId: string): Promise<Workflow>;
+    /** `DELETE /v1/workflows/:id` */
+    delete(workflowId: string): Promise<void>;
+    /**
+     * `POST /v1/workflows/:id/runs` — start an async execution.
+     *
+     * Returns 202 with an `execution_id` immediately. Poll {@link getRun}
+     * or use {@link waitForRun} to await completion.
+     */
+    startRun(workflowId: string, input?: unknown): Promise<StartRunResponse>;
+    /** `GET /v1/workflows/:id/runs/:execution_id` — fetch one execution. */
+    getRun(workflowId: string, executionId: string): Promise<WorkflowExecution>;
+    /**
+     * Poll {@link getRun} until the run reaches a terminal status.
+     *
+     * Rejects with an error if the run hasn't terminated within
+     * `timeoutMs`. The server enforces its own 60s wall-clock cap per run,
+     * so a timeout larger than ~75_000 is just slack for polling overhead.
+     */
+    waitForRun(workflowId: string, executionId: string, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<WorkflowExecution>;
+}
+
 /**
  * History API client — Wauldo Funnel #1 audit log.
  *
@@ -1027,4 +1146,4 @@ declare class HistoryClient {
     deleteTask(taskId: string): Promise<number>;
 }
 
-export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRevision, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type CreateRevisionInput, type CreateRevisionResponse, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HistoryClient, type HistoryClientConfig, type ExportOptions as HistoryExportOptions, type ListOptions as HistoryListOptions, type HistoryListResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type ListRevisionsResponse, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StateTransition, type Task, type TaskClaim, type TaskHistoryEntry, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, supportScore };
+export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRevision, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type CreateRevisionInput, type CreateRevisionResponse, type CreateWorkflowInput, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HistoryClient, type HistoryClientConfig, type ExportOptions as HistoryExportOptions, type ListOptions as HistoryListOptions, type HistoryListResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type ListRevisionsResponse, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StartRunResponse, type StateTransition, TERMINAL_WORKFLOW_STATUSES, type Task, type TaskClaim, type TaskHistoryEntry, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, type Workflow, type WorkflowExecution, type WorkflowListResponse, WorkflowsClient, type WorkflowsClientConfig, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, isWorkflowRunTerminal, supportScore };

package/dist/index.js

@@ -29,14 +29,17 @@ __export(index_exports, {
   HttpError: () => HttpError,
   MockHttpClient: () => MockHttpClient,
   ServerError: () => ServerError,
+  TERMINAL_WORKFLOW_STATUSES: () => TERMINAL_WORKFLOW_STATUSES,
   TimeoutError: () => TimeoutError,
   ToolNotFoundError: () => ToolNotFoundError,
   ValidationError: () => ValidationError,
   WauldoError: () => WauldoError,
+  WorkflowsClient: () => WorkflowsClient,
   chatContent: () => chatContent,
   guardIsBlocked: () => guardIsBlocked,
   guardIsSafe: () => guardIsSafe,
   isTerminalStatus: () => isTerminalStatus,
+  isWorkflowRunTerminal: () => isWorkflowRunTerminal,
   supportScore: () => supportScore
 });
 module.exports = __toCommonJS(index_exports);
@@ -1599,6 +1602,133 @@ var AgentsClient = class {
   }
 };
 
+// src/workflows.ts
+var TERMINAL_WORKFLOW_STATUSES = [
+  "succeeded",
+  "failed",
+  "timed_out"
+];
+function isWorkflowRunTerminal(status) {
+  return TERMINAL_WORKFLOW_STATUSES.includes(status);
+}
+var WorkflowsClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+  }
+  headers() {
+    const h = { "Content-Type": "application/json" };
+    if (this.config.apiKey) h["Authorization"] = `Bearer ${this.config.apiKey}`;
+    if (this.config.tenant) h["x-rapidapi-user"] = this.config.tenant;
+    return h;
+  }
+  async request(method, path, body) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + path;
+    const controller = new AbortController();
+    const timeout = setTimeout(
+      () => controller.abort(),
+      this.config.timeoutMs ?? 12e4
+    );
+    try {
+      const init = {
+        method,
+        headers: this.headers(),
+        signal: controller.signal
+      };
+      if (body !== void 0) init.body = JSON.stringify(body);
+      const resp = await fetch(url, init);
+      if (resp.status === 204) return null;
+      const bytes = await _boundedRead(resp, MAX_RESPONSE_SIZE);
+      const text = new TextDecoder().decode(bytes);
+      if (!resp.ok) {
+        throw new HttpError(resp.status, resp.statusText, text);
+      }
+      return text ? JSON.parse(text) : null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  // ── CRUD ──────────────────────────────────────────────────────────
+  /**
+   * `POST /v1/workflows` — create a workflow definition.
+   *
+   * The server validates cycles, transition targets, choice operators,
+   * and the per-tenant cap (100) before returning 201.
+   */
+  async create(input) {
+    const body = {
+      name: input.name,
+      start_at: input.startAt,
+      states: input.states
+    };
+    if (input.description !== void 0) body.description = input.description;
+    const env = await this.request("POST", "/v1/workflows", body);
+    return env.workflow;
+  }
+  /** `GET /v1/workflows` — list workflows for the calling tenant. */
+  async list() {
+    return await this.request("GET", "/v1/workflows");
+  }
+  /** `GET /v1/workflows/:id` */
+  async get(workflowId) {
+    const env = await this.request(
+      "GET",
+      `/v1/workflows/${workflowId}`
+    );
+    return env.workflow;
+  }
+  /** `DELETE /v1/workflows/:id` */
+  async delete(workflowId) {
+    await this.request("DELETE", `/v1/workflows/${workflowId}`);
+  }
+  // ── Runs ──────────────────────────────────────────────────────────
+  /**
+   * `POST /v1/workflows/:id/runs` — start an async execution.
+   *
+   * Returns 202 with an `execution_id` immediately. Poll {@link getRun}
+   * or use {@link waitForRun} to await completion.
+   */
+  async startRun(workflowId, input) {
+    const body = {};
+    if (input !== void 0) body.input = input;
+    return await this.request(
+      "POST",
+      `/v1/workflows/${workflowId}/runs`,
+      body
+    );
+  }
+  /** `GET /v1/workflows/:id/runs/:execution_id` — fetch one execution. */
+  async getRun(workflowId, executionId) {
+    const env = await this.request(
+      "GET",
+      `/v1/workflows/${workflowId}/runs/${executionId}`
+    );
+    return env.execution;
+  }
+  /**
+   * Poll {@link getRun} until the run reaches a terminal status.
+   *
+   * Rejects with an error if the run hasn't terminated within
+   * `timeoutMs`. The server enforces its own 60s wall-clock cap per run,
+   * so a timeout larger than ~75_000 is just slack for polling overhead.
+   */
+  async waitForRun(workflowId, executionId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 9e4;
+    const pollIntervalMs = opts.pollIntervalMs ?? 1e3;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const execution = await this.getRun(workflowId, executionId);
+      if (isWorkflowRunTerminal(execution.status)) return execution;
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `workflow run ${executionId} did not terminate within ${timeoutMs}ms (last status: ${execution.status})`
+        );
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+};
+
 // src/history.ts
 var HistoryClient = class {
   constructor(config) {
@@ -1718,13 +1848,16 @@ var HistoryClient = class {
   HttpError,
   MockHttpClient,
   ServerError,
+  TERMINAL_WORKFLOW_STATUSES,
   TimeoutError,
   ToolNotFoundError,
   ValidationError,
   WauldoError,
+  WorkflowsClient,
   chatContent,
   guardIsBlocked,
   guardIsSafe,
   isTerminalStatus,
+  isWorkflowRunTerminal,
   supportScore
 });

package/dist/index.mjs

@@ -1556,6 +1556,133 @@ var AgentsClient = class {
   }
 };
 
+// src/workflows.ts
+var TERMINAL_WORKFLOW_STATUSES = [
+  "succeeded",
+  "failed",
+  "timed_out"
+];
+function isWorkflowRunTerminal(status) {
+  return TERMINAL_WORKFLOW_STATUSES.includes(status);
+}
+var WorkflowsClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+  }
+  headers() {
+    const h = { "Content-Type": "application/json" };
+    if (this.config.apiKey) h["Authorization"] = `Bearer ${this.config.apiKey}`;
+    if (this.config.tenant) h["x-rapidapi-user"] = this.config.tenant;
+    return h;
+  }
+  async request(method, path, body) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + path;
+    const controller = new AbortController();
+    const timeout = setTimeout(
+      () => controller.abort(),
+      this.config.timeoutMs ?? 12e4
+    );
+    try {
+      const init = {
+        method,
+        headers: this.headers(),
+        signal: controller.signal
+      };
+      if (body !== void 0) init.body = JSON.stringify(body);
+      const resp = await fetch(url, init);
+      if (resp.status === 204) return null;
+      const bytes = await _boundedRead(resp, MAX_RESPONSE_SIZE);
+      const text = new TextDecoder().decode(bytes);
+      if (!resp.ok) {
+        throw new HttpError(resp.status, resp.statusText, text);
+      }
+      return text ? JSON.parse(text) : null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  // ── CRUD ──────────────────────────────────────────────────────────
+  /**
+   * `POST /v1/workflows` — create a workflow definition.
+   *
+   * The server validates cycles, transition targets, choice operators,
+   * and the per-tenant cap (100) before returning 201.
+   */
+  async create(input) {
+    const body = {
+      name: input.name,
+      start_at: input.startAt,
+      states: input.states
+    };
+    if (input.description !== void 0) body.description = input.description;
+    const env = await this.request("POST", "/v1/workflows", body);
+    return env.workflow;
+  }
+  /** `GET /v1/workflows` — list workflows for the calling tenant. */
+  async list() {
+    return await this.request("GET", "/v1/workflows");
+  }
+  /** `GET /v1/workflows/:id` */
+  async get(workflowId) {
+    const env = await this.request(
+      "GET",
+      `/v1/workflows/${workflowId}`
+    );
+    return env.workflow;
+  }
+  /** `DELETE /v1/workflows/:id` */
+  async delete(workflowId) {
+    await this.request("DELETE", `/v1/workflows/${workflowId}`);
+  }
+  // ── Runs ──────────────────────────────────────────────────────────
+  /**
+   * `POST /v1/workflows/:id/runs` — start an async execution.
+   *
+   * Returns 202 with an `execution_id` immediately. Poll {@link getRun}
+   * or use {@link waitForRun} to await completion.
+   */
+  async startRun(workflowId, input) {
+    const body = {};
+    if (input !== void 0) body.input = input;
+    return await this.request(
+      "POST",
+      `/v1/workflows/${workflowId}/runs`,
+      body
+    );
+  }
+  /** `GET /v1/workflows/:id/runs/:execution_id` — fetch one execution. */
+  async getRun(workflowId, executionId) {
+    const env = await this.request(
+      "GET",
+      `/v1/workflows/${workflowId}/runs/${executionId}`
+    );
+    return env.execution;
+  }
+  /**
+   * Poll {@link getRun} until the run reaches a terminal status.
+   *
+   * Rejects with an error if the run hasn't terminated within
+   * `timeoutMs`. The server enforces its own 60s wall-clock cap per run,
+   * so a timeout larger than ~75_000 is just slack for polling overhead.
+   */
+  async waitForRun(workflowId, executionId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 9e4;
+    const pollIntervalMs = opts.pollIntervalMs ?? 1e3;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const execution = await this.getRun(workflowId, executionId);
+      if (isWorkflowRunTerminal(execution.status)) return execution;
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `workflow run ${executionId} did not terminate within ${timeoutMs}ms (last status: ${execution.status})`
+        );
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+};
+
 // src/history.ts
 var HistoryClient = class {
   constructor(config) {
@@ -1674,13 +1801,16 @@ export {
   HttpError,
   MockHttpClient,
   ServerError,
+  TERMINAL_WORKFLOW_STATUSES,
   TimeoutError,
   ToolNotFoundError,
   ValidationError,
   WauldoError,
+  WorkflowsClient,
   chatContent,
   guardIsBlocked,
   guardIsSafe,
   isTerminalStatus,
+  isWorkflowRunTerminal,
   supportScore
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wauldo",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Official TypeScript SDK for Wauldo — Verified AI answers from your documents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",