wauldo 0.11.0 → 0.13.0

package/dist/index.d.mts

@@ -695,6 +695,50 @@ interface AgentRunResponse {
     status: string;
     created_at: number;
 }
+/**
+ * Immutable snapshot of an agent's `AgentContractV2` payload, content-addressed
+ * via SHA-256 and identified by a monotone `rev` integer. Mirrors AWS ECS
+ * task-definition revisions: append-only, O(1) rollback via `setActiveRevision`.
+ */
+interface AgentRevision {
+    rev: number;
+    sha256: string;
+    contract_json: string;
+    created_at: number;
+    message?: string;
+    created_by?: string;
+}
+interface CreateRevisionInput {
+    /** Full `AgentContractV2` JSON payload (same shape as `custom_preset` on POST /v1/agents). */
+    customPreset: Record<string, unknown>;
+    /** Optional commit-message-style note (≤256 chars). */
+    message?: string;
+    /** When `true` (default) the new revision becomes active immediately. */
+    setActive?: boolean;
+}
+interface CreateRevisionResponse {
+    rev: number;
+    sha256: string;
+    active_rev: number;
+}
+interface ListRevisionsResponse {
+    revisions: AgentRevision[];
+    active_rev: number;
+    head_rev: number;
+    count: number;
+}
+/**
+ * Result of `shareTask` / `unshareTask`.
+ *
+ * `expiresAt` is epoch milliseconds, or `null` for paid tenants
+ * (no expiration). Free-tier shares default to a 30-day TTL ; once
+ * elapsed, the public `GET /v1/runs/<shareId>` returns 404.
+ */
+interface ShareResponse {
+    share_id: string;
+    url: string;
+    expires_at: number | null;
+}
 interface A2aResponse {
     task_id: string;
     agent_id: string;
@@ -801,12 +845,54 @@ declare class AgentsClient {
     get(agentId: string): Promise<DeployedAgent>;
     update(agentId: string, patch: UpdateAgentPatch): Promise<DeployedAgent>;
     delete(agentId: string): Promise<void>;
+    /**
+     * `POST /v1/agents/:id/revisions` — mint an immutable revision.
+     *
+     * The server validates `customPreset` (size, depth, states, cycle, tools,
+     * quota) and stores an immutable snapshot keyed by SHA-256. When
+     * `setActive` is `true` (default) the new revision becomes the agent's
+     * live revision; `false` stages it for review.
+     */
+    createRevision(agentId: string, input: CreateRevisionInput): Promise<CreateRevisionResponse>;
+    /** `GET /v1/agents/:id/revisions` — list revisions newest-first. */
+    listRevisions(agentId: string): Promise<ListRevisionsResponse>;
+    /** `GET /v1/agents/:id/revisions/:rev` — fetch one revision verbatim. */
+    getRevision(agentId: string, rev: number): Promise<AgentRevision>;
+    /**
+     * `PATCH /v1/agents/:id/active-revision` — O(1) rollback / promotion.
+     *
+     * No LLM cost — the revision is already validated and stored. Use this
+     * to roll back to a previous good revision when the current one breaks
+     * in production.
+     */
+    setActiveRevision(agentId: string, rev: number): Promise<DeployedAgent>;
     run(agentId: string, input: string, verificationMode?: "strict" | "balanced" | "permissive", factCheckMode?: "lexical" | "hybrid" | "semantic"): Promise<AgentRunResponse>;
     a2aInvoke(agentId: string, input: string, trace?: string[], verificationMode?: "strict" | "balanced" | "permissive", factCheckMode?: "lexical" | "hybrid" | "semantic"): Promise<A2aResponse>;
     /** `GET /v1/tasks/:id` — fetch the current state of a task. */
     getTask(taskId: string): Promise<Task>;
     /** `DELETE /v1/tasks/:id` — cancel a queued or running task. */
     cancelTask(taskId: string): Promise<void>;
+    /**
+     * `POST /v1/tasks/:id/share` — publish a run as a public URL.
+     *
+     * Idempotent : calling on an already-shared task returns the existing
+     * `ShareResponse` without bumping the per-tenant cap. The returned
+     * `url` (form `https://wauldo.com/r/<id>`) can be pasted anywhere —
+     * anyone with the link sees the verdict + claims + sources + timeline
+     * through a strict-whitelist projection (no `custom_preset` /
+     * `wauldo_toml` / system prompt / tool args ever leave the tenant).
+     *
+     * Free-tier tenants get a 30-day TTL ; paid tenants get
+     * `expires_at = null` (no expiration).
+     */
+    shareTask(taskId: string): Promise<ShareResponse>;
+    /**
+     * `DELETE /v1/tasks/:id/share` — make a published run private again.
+     *
+     * Idempotent : calling on a never-published task returns 204.
+     * Subsequent `GET /v1/runs/<shareId>` for the cleared id returns 404.
+     */
+    unshareTask(taskId: string): Promise<void>;
     /**
      * Poll `getTask` until the task reaches a terminal status. Resolves
      * with the final Task snapshot. Rejects with `Error("timeout")` if
@@ -833,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.
  *
@@ -941,4 +1146,4 @@ declare class HistoryClient {
     deleteTask(taskId: string): Promise<number>;
 }
 
-export { type A2aResponse, AgentClient, type AgentListResponse, 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 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 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

@@ -695,6 +695,50 @@ interface AgentRunResponse {
     status: string;
     created_at: number;
 }
+/**
+ * Immutable snapshot of an agent's `AgentContractV2` payload, content-addressed
+ * via SHA-256 and identified by a monotone `rev` integer. Mirrors AWS ECS
+ * task-definition revisions: append-only, O(1) rollback via `setActiveRevision`.
+ */
+interface AgentRevision {
+    rev: number;
+    sha256: string;
+    contract_json: string;
+    created_at: number;
+    message?: string;
+    created_by?: string;
+}
+interface CreateRevisionInput {
+    /** Full `AgentContractV2` JSON payload (same shape as `custom_preset` on POST /v1/agents). */
+    customPreset: Record<string, unknown>;
+    /** Optional commit-message-style note (≤256 chars). */
+    message?: string;
+    /** When `true` (default) the new revision becomes active immediately. */
+    setActive?: boolean;
+}
+interface CreateRevisionResponse {
+    rev: number;
+    sha256: string;
+    active_rev: number;
+}
+interface ListRevisionsResponse {
+    revisions: AgentRevision[];
+    active_rev: number;
+    head_rev: number;
+    count: number;
+}
+/**
+ * Result of `shareTask` / `unshareTask`.
+ *
+ * `expiresAt` is epoch milliseconds, or `null` for paid tenants
+ * (no expiration). Free-tier shares default to a 30-day TTL ; once
+ * elapsed, the public `GET /v1/runs/<shareId>` returns 404.
+ */
+interface ShareResponse {
+    share_id: string;
+    url: string;
+    expires_at: number | null;
+}
 interface A2aResponse {
     task_id: string;
     agent_id: string;
@@ -801,12 +845,54 @@ declare class AgentsClient {
     get(agentId: string): Promise<DeployedAgent>;
     update(agentId: string, patch: UpdateAgentPatch): Promise<DeployedAgent>;
     delete(agentId: string): Promise<void>;
+    /**
+     * `POST /v1/agents/:id/revisions` — mint an immutable revision.
+     *
+     * The server validates `customPreset` (size, depth, states, cycle, tools,
+     * quota) and stores an immutable snapshot keyed by SHA-256. When
+     * `setActive` is `true` (default) the new revision becomes the agent's
+     * live revision; `false` stages it for review.
+     */
+    createRevision(agentId: string, input: CreateRevisionInput): Promise<CreateRevisionResponse>;
+    /** `GET /v1/agents/:id/revisions` — list revisions newest-first. */
+    listRevisions(agentId: string): Promise<ListRevisionsResponse>;
+    /** `GET /v1/agents/:id/revisions/:rev` — fetch one revision verbatim. */
+    getRevision(agentId: string, rev: number): Promise<AgentRevision>;
+    /**
+     * `PATCH /v1/agents/:id/active-revision` — O(1) rollback / promotion.
+     *
+     * No LLM cost — the revision is already validated and stored. Use this
+     * to roll back to a previous good revision when the current one breaks
+     * in production.
+     */
+    setActiveRevision(agentId: string, rev: number): Promise<DeployedAgent>;
     run(agentId: string, input: string, verificationMode?: "strict" | "balanced" | "permissive", factCheckMode?: "lexical" | "hybrid" | "semantic"): Promise<AgentRunResponse>;
     a2aInvoke(agentId: string, input: string, trace?: string[], verificationMode?: "strict" | "balanced" | "permissive", factCheckMode?: "lexical" | "hybrid" | "semantic"): Promise<A2aResponse>;
     /** `GET /v1/tasks/:id` — fetch the current state of a task. */
     getTask(taskId: string): Promise<Task>;
     /** `DELETE /v1/tasks/:id` — cancel a queued or running task. */
     cancelTask(taskId: string): Promise<void>;
+    /**
+     * `POST /v1/tasks/:id/share` — publish a run as a public URL.
+     *
+     * Idempotent : calling on an already-shared task returns the existing
+     * `ShareResponse` without bumping the per-tenant cap. The returned
+     * `url` (form `https://wauldo.com/r/<id>`) can be pasted anywhere —
+     * anyone with the link sees the verdict + claims + sources + timeline
+     * through a strict-whitelist projection (no `custom_preset` /
+     * `wauldo_toml` / system prompt / tool args ever leave the tenant).
+     *
+     * Free-tier tenants get a 30-day TTL ; paid tenants get
+     * `expires_at = null` (no expiration).
+     */
+    shareTask(taskId: string): Promise<ShareResponse>;
+    /**
+     * `DELETE /v1/tasks/:id/share` — make a published run private again.
+     *
+     * Idempotent : calling on a never-published task returns 204.
+     * Subsequent `GET /v1/runs/<shareId>` for the cleared id returns 404.
+     */
+    unshareTask(taskId: string): Promise<void>;
     /**
      * Poll `getTask` until the task reaches a terminal status. Resolves
      * with the final Task snapshot. Rejects with `Error("timeout")` if
@@ -833,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.
  *
@@ -941,4 +1146,4 @@ declare class HistoryClient {
     deleteTask(taskId: string): Promise<number>;
 }
 
-export { type A2aResponse, AgentClient, type AgentListResponse, 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 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 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);
@@ -1407,6 +1410,55 @@ var AgentsClient = class {
   async delete(agentId) {
     await this.request("DELETE", `/v1/agents/${agentId}`);
   }
+  // ── Revisions (ECS-style versioning) ────────────────────────────
+  /**
+   * `POST /v1/agents/:id/revisions` — mint an immutable revision.
+   *
+   * The server validates `customPreset` (size, depth, states, cycle, tools,
+   * quota) and stores an immutable snapshot keyed by SHA-256. When
+   * `setActive` is `true` (default) the new revision becomes the agent's
+   * live revision; `false` stages it for review.
+   */
+  async createRevision(agentId, input) {
+    const body = {
+      custom_preset: input.customPreset,
+      set_active: input.setActive ?? true
+    };
+    if (input.message !== void 0) body.message = input.message;
+    return await this.request(
+      "POST",
+      `/v1/agents/${agentId}/revisions`,
+      body
+    );
+  }
+  /** `GET /v1/agents/:id/revisions` — list revisions newest-first. */
+  async listRevisions(agentId) {
+    return await this.request(
+      "GET",
+      `/v1/agents/${agentId}/revisions`
+    );
+  }
+  /** `GET /v1/agents/:id/revisions/:rev` — fetch one revision verbatim. */
+  async getRevision(agentId, rev) {
+    return await this.request(
+      "GET",
+      `/v1/agents/${agentId}/revisions/${rev}`
+    );
+  }
+  /**
+   * `PATCH /v1/agents/:id/active-revision` — O(1) rollback / promotion.
+   *
+   * No LLM cost — the revision is already validated and stored. Use this
+   * to roll back to a previous good revision when the current one breaks
+   * in production.
+   */
+  async setActiveRevision(agentId, rev) {
+    return await this.request(
+      "PATCH",
+      `/v1/agents/${agentId}/active-revision`,
+      { rev }
+    );
+  }
   // ── Runs ────────────────────────────────────────────────────────
   async run(agentId, input, verificationMode, factCheckMode) {
     if (!input) throw new Error("input is required");
@@ -1442,6 +1494,36 @@ var AgentsClient = class {
   async cancelTask(taskId) {
     await this.request("DELETE", `/v1/tasks/${taskId}`);
   }
+  // ── Shareable runs ──────────────────────────────────────────────
+  /**
+   * `POST /v1/tasks/:id/share` — publish a run as a public URL.
+   *
+   * Idempotent : calling on an already-shared task returns the existing
+   * `ShareResponse` without bumping the per-tenant cap. The returned
+   * `url` (form `https://wauldo.com/r/<id>`) can be pasted anywhere —
+   * anyone with the link sees the verdict + claims + sources + timeline
+   * through a strict-whitelist projection (no `custom_preset` /
+   * `wauldo_toml` / system prompt / tool args ever leave the tenant).
+   *
+   * Free-tier tenants get a 30-day TTL ; paid tenants get
+   * `expires_at = null` (no expiration).
+   */
+  async shareTask(taskId) {
+    return await this.request(
+      "POST",
+      `/v1/tasks/${taskId}/share`,
+      {}
+    );
+  }
+  /**
+   * `DELETE /v1/tasks/:id/share` — make a published run private again.
+   *
+   * Idempotent : calling on a never-published task returns 204.
+   * Subsequent `GET /v1/runs/<shareId>` for the cleared id returns 404.
+   */
+  async unshareTask(taskId) {
+    await this.request("DELETE", `/v1/tasks/${taskId}/share`);
+  }
   /**
    * Poll `getTask` until the task reaches a terminal status. Resolves
    * with the final Task snapshot. Rejects with `Error("timeout")` if
@@ -1520,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) {
@@ -1639,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

@@ -1364,6 +1364,55 @@ var AgentsClient = class {
   async delete(agentId) {
     await this.request("DELETE", `/v1/agents/${agentId}`);
   }
+  // ── Revisions (ECS-style versioning) ────────────────────────────
+  /**
+   * `POST /v1/agents/:id/revisions` — mint an immutable revision.
+   *
+   * The server validates `customPreset` (size, depth, states, cycle, tools,
+   * quota) and stores an immutable snapshot keyed by SHA-256. When
+   * `setActive` is `true` (default) the new revision becomes the agent's
+   * live revision; `false` stages it for review.
+   */
+  async createRevision(agentId, input) {
+    const body = {
+      custom_preset: input.customPreset,
+      set_active: input.setActive ?? true
+    };
+    if (input.message !== void 0) body.message = input.message;
+    return await this.request(
+      "POST",
+      `/v1/agents/${agentId}/revisions`,
+      body
+    );
+  }
+  /** `GET /v1/agents/:id/revisions` — list revisions newest-first. */
+  async listRevisions(agentId) {
+    return await this.request(
+      "GET",
+      `/v1/agents/${agentId}/revisions`
+    );
+  }
+  /** `GET /v1/agents/:id/revisions/:rev` — fetch one revision verbatim. */
+  async getRevision(agentId, rev) {
+    return await this.request(
+      "GET",
+      `/v1/agents/${agentId}/revisions/${rev}`
+    );
+  }
+  /**
+   * `PATCH /v1/agents/:id/active-revision` — O(1) rollback / promotion.
+   *
+   * No LLM cost — the revision is already validated and stored. Use this
+   * to roll back to a previous good revision when the current one breaks
+   * in production.
+   */
+  async setActiveRevision(agentId, rev) {
+    return await this.request(
+      "PATCH",
+      `/v1/agents/${agentId}/active-revision`,
+      { rev }
+    );
+  }
   // ── Runs ────────────────────────────────────────────────────────
   async run(agentId, input, verificationMode, factCheckMode) {
     if (!input) throw new Error("input is required");
@@ -1399,6 +1448,36 @@ var AgentsClient = class {
   async cancelTask(taskId) {
     await this.request("DELETE", `/v1/tasks/${taskId}`);
   }
+  // ── Shareable runs ──────────────────────────────────────────────
+  /**
+   * `POST /v1/tasks/:id/share` — publish a run as a public URL.
+   *
+   * Idempotent : calling on an already-shared task returns the existing
+   * `ShareResponse` without bumping the per-tenant cap. The returned
+   * `url` (form `https://wauldo.com/r/<id>`) can be pasted anywhere —
+   * anyone with the link sees the verdict + claims + sources + timeline
+   * through a strict-whitelist projection (no `custom_preset` /
+   * `wauldo_toml` / system prompt / tool args ever leave the tenant).
+   *
+   * Free-tier tenants get a 30-day TTL ; paid tenants get
+   * `expires_at = null` (no expiration).
+   */
+  async shareTask(taskId) {
+    return await this.request(
+      "POST",
+      `/v1/tasks/${taskId}/share`,
+      {}
+    );
+  }
+  /**
+   * `DELETE /v1/tasks/:id/share` — make a published run private again.
+   *
+   * Idempotent : calling on a never-published task returns 204.
+   * Subsequent `GET /v1/runs/<shareId>` for the cleared id returns 404.
+   */
+  async unshareTask(taskId) {
+    await this.request("DELETE", `/v1/tasks/${taskId}/share`);
+  }
   /**
    * Poll `getTask` until the task reaches a terminal status. Resolves
    * with the final Task snapshot. Rejects with `Error("timeout")` if
@@ -1477,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) {
@@ -1595,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.11.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",