wauldo 0.7.2 → 0.8.0

package/README.md

@@ -116,6 +116,39 @@ console.log(result.action);           // "block"
 console.log(result.claims[0].reason); // "numerical_mismatch"
 ```
 
+### Deployed Agents — create, run, stream
+
+```typescript
+import { AgentsClient } from 'wauldo';
+
+const agents = new AgentsClient({
+  baseUrl: 'https://api.wauldo.com',
+  apiKey: 'YOUR_API_KEY',
+  tenant: 'my-tenant',
+});
+
+const agent = await agents.create({
+  name: 'support-bot',
+  description: 'Answers refund questions',
+  wauldoToml: `[agent]\nname = "support-bot"\n[model]\nprovider = "openrouter"\nname = "auto"`,
+  preset: 'general_task', // or 'rust_backend_architect', 'rag_data_engineer', ...
+});
+
+const run = await agents.run(agent.id, 'Can I return a shirt 30 days after purchase?');
+
+// Stream reasoning live as each workflow state completes
+for await (const event of agents.streamTask(run.task_id)) {
+  console.log(`  ${event.state_name}: ${event.duration_ms}ms  (${event.completion_tokens} tok)`);
+}
+
+// Or poll for the final verified result
+const task = await agents.waitForTask(run.task_id, { timeoutMs: 120_000 });
+console.log(task.result);                     // The answer
+console.log(task.verification?.verdict);      // SAFE | UNVERIFIED | BLOCK | …
+console.log(task.verification?.trust_score);  // 0.0 – 1.0
+console.log(task.verification?.message);      // Human-readable context when non-SAFE
+```
+
 ### Chat (OpenAI-compatible)
 
 ```typescript

package/dist/index.d.mts

@@ -644,4 +644,175 @@ declare class ToolNotFoundError extends WauldoError {
     constructor(toolName: string);
 }
 
-export { AgentClient, 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 DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HttpClient, type HttpClientConfig, 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, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, ValidationError, WauldoError, chatContent, guardIsBlocked, guardIsSafe };
+interface AgentsClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    /** Tenant identifier forwarded via x-rapidapi-user header. */
+    tenant?: string;
+    /** Per-request timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+interface DeployedAgent {
+    id: string;
+    tenant_id: string;
+    name: string;
+    description: string;
+    wauldo_toml: string;
+    agents_md?: string;
+    mcp_json?: string;
+    model_provider: string;
+    model_name: string;
+    preset?: string;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateAgentInput {
+    name: string;
+    wauldoToml: string;
+    description?: string;
+    agentsMd?: string;
+    mcpJson?: string;
+    preset?: string;
+}
+interface UpdateAgentPatch {
+    description?: string;
+    wauldoToml?: string;
+    agentsMd?: string;
+    mcpJson?: string;
+    preset?: string;
+}
+interface AgentListResponse {
+    agents: DeployedAgent[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+interface AgentRunResponse {
+    task_id: string;
+    agent_id: string;
+    status: string;
+    created_at: number;
+}
+interface A2aResponse {
+    task_id: string;
+    agent_id: string;
+    trace: string[];
+    depth: number;
+    status: string;
+}
+/** Verification verdict returned on completed tasks. */
+type Verdict = "SAFE" | "UNCERTAIN" | "PARTIAL" | "BLOCK" | "CONFLICT" | "UNVERIFIED";
+/** Task lifecycle status. */
+type TaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+/** A single verified claim from an agent output. */
+interface TaskClaim {
+    text: string;
+    supported: boolean;
+    confidence: number;
+}
+/**
+ * Verification block attached to completed tasks. When
+ * `verification_source === "prompt_only"` the `confidence` and
+ * `hallucination_rate` fields reflect self-consistency only; rely on
+ * `verdict` + `trust_score` + `message` as authoritative.
+ */
+interface TaskVerification {
+    verdict: Verdict;
+    hallucination_rate: number;
+    confidence: number;
+    trust_score: number;
+    verification_source: string;
+    claims: TaskClaim[];
+    verification_retries: number;
+    /** Human-readable context for non-SAFE verdicts. */
+    message?: string | null;
+    sources_cited?: number[];
+    stripped_claims?: string[];
+}
+/** Full task record returned by `GET /v1/tasks/:id`. */
+interface Task {
+    task_id: string;
+    tenant_id: string;
+    status: TaskStatus;
+    prompt: string;
+    created_at: number;
+    updated_at: number;
+    preset?: string | null;
+    result?: string | null;
+    error?: string | null;
+    partial_result?: string | null;
+    verification?: TaskVerification | null;
+    journal?: Record<string, unknown> | null;
+}
+/**
+ * Single event yielded by `GET /v1/tasks/:id/stream`. Each SSE `data:`
+ * line is a JSON-serialised StateTransition emitted when a workflow
+ * state completes.
+ */
+interface StateTransition {
+    state_name: string;
+    to_state?: string | null;
+    condition: string;
+    raw_output: string;
+    validation_notes: string[];
+    timestamp: number;
+    success: boolean;
+    retry_count: number;
+    duration_ms: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    repair_count: number;
+    cache_hit: boolean;
+}
+declare function isTerminalStatus(s: TaskStatus | string): boolean;
+declare class HttpError extends Error {
+    status: number;
+    statusText: string;
+    body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+declare class AgentsClient {
+    private readonly config;
+    constructor(config: AgentsClientConfig);
+    private headers;
+    private request;
+    create(input: CreateAgentInput): Promise<DeployedAgent>;
+    list(limit?: number, offset?: number): Promise<AgentListResponse>;
+    get(agentId: string): Promise<DeployedAgent>;
+    update(agentId: string, patch: UpdateAgentPatch): Promise<DeployedAgent>;
+    delete(agentId: string): Promise<void>;
+    run(agentId: string, input: string, verificationMode?: "strict" | "balanced" | "permissive"): Promise<AgentRunResponse>;
+    a2aInvoke(agentId: string, input: string, trace?: string[], verificationMode?: "strict" | "balanced" | "permissive"): 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>;
+    /**
+     * Poll `getTask` until the task reaches a terminal status. Resolves
+     * with the final Task snapshot. Rejects with `Error("timeout")` if
+     * the task is still running after `timeoutMs`. Use `streamTask` when
+     * you need event-by-event progress instead of a single final state.
+     */
+    waitForTask(taskId: string, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<Task>;
+    /**
+     * Subscribe to `GET /v1/tasks/:id/stream` and yield typed
+     * StateTransition events as each workflow state completes. The
+     * generator closes when the upstream stream closes (task reached
+     * terminal status) or on connection error.
+     *
+     * @example
+     * ```ts
+     * for await (const event of agents.streamTask(run.task_id)) {
+     *   console.log(event.state_name, event.duration_ms);
+     * }
+     * ```
+     */
+    streamTask(taskId: string): AsyncGenerator<StateTransition>;
+}
+
+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, 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 TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus };

package/dist/index.d.ts

@@ -644,4 +644,175 @@ declare class ToolNotFoundError extends WauldoError {
     constructor(toolName: string);
 }
 
-export { AgentClient, 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 DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HttpClient, type HttpClientConfig, 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, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, ValidationError, WauldoError, chatContent, guardIsBlocked, guardIsSafe };
+interface AgentsClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    /** Tenant identifier forwarded via x-rapidapi-user header. */
+    tenant?: string;
+    /** Per-request timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+interface DeployedAgent {
+    id: string;
+    tenant_id: string;
+    name: string;
+    description: string;
+    wauldo_toml: string;
+    agents_md?: string;
+    mcp_json?: string;
+    model_provider: string;
+    model_name: string;
+    preset?: string;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateAgentInput {
+    name: string;
+    wauldoToml: string;
+    description?: string;
+    agentsMd?: string;
+    mcpJson?: string;
+    preset?: string;
+}
+interface UpdateAgentPatch {
+    description?: string;
+    wauldoToml?: string;
+    agentsMd?: string;
+    mcpJson?: string;
+    preset?: string;
+}
+interface AgentListResponse {
+    agents: DeployedAgent[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+interface AgentRunResponse {
+    task_id: string;
+    agent_id: string;
+    status: string;
+    created_at: number;
+}
+interface A2aResponse {
+    task_id: string;
+    agent_id: string;
+    trace: string[];
+    depth: number;
+    status: string;
+}
+/** Verification verdict returned on completed tasks. */
+type Verdict = "SAFE" | "UNCERTAIN" | "PARTIAL" | "BLOCK" | "CONFLICT" | "UNVERIFIED";
+/** Task lifecycle status. */
+type TaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+/** A single verified claim from an agent output. */
+interface TaskClaim {
+    text: string;
+    supported: boolean;
+    confidence: number;
+}
+/**
+ * Verification block attached to completed tasks. When
+ * `verification_source === "prompt_only"` the `confidence` and
+ * `hallucination_rate` fields reflect self-consistency only; rely on
+ * `verdict` + `trust_score` + `message` as authoritative.
+ */
+interface TaskVerification {
+    verdict: Verdict;
+    hallucination_rate: number;
+    confidence: number;
+    trust_score: number;
+    verification_source: string;
+    claims: TaskClaim[];
+    verification_retries: number;
+    /** Human-readable context for non-SAFE verdicts. */
+    message?: string | null;
+    sources_cited?: number[];
+    stripped_claims?: string[];
+}
+/** Full task record returned by `GET /v1/tasks/:id`. */
+interface Task {
+    task_id: string;
+    tenant_id: string;
+    status: TaskStatus;
+    prompt: string;
+    created_at: number;
+    updated_at: number;
+    preset?: string | null;
+    result?: string | null;
+    error?: string | null;
+    partial_result?: string | null;
+    verification?: TaskVerification | null;
+    journal?: Record<string, unknown> | null;
+}
+/**
+ * Single event yielded by `GET /v1/tasks/:id/stream`. Each SSE `data:`
+ * line is a JSON-serialised StateTransition emitted when a workflow
+ * state completes.
+ */
+interface StateTransition {
+    state_name: string;
+    to_state?: string | null;
+    condition: string;
+    raw_output: string;
+    validation_notes: string[];
+    timestamp: number;
+    success: boolean;
+    retry_count: number;
+    duration_ms: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    repair_count: number;
+    cache_hit: boolean;
+}
+declare function isTerminalStatus(s: TaskStatus | string): boolean;
+declare class HttpError extends Error {
+    status: number;
+    statusText: string;
+    body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+declare class AgentsClient {
+    private readonly config;
+    constructor(config: AgentsClientConfig);
+    private headers;
+    private request;
+    create(input: CreateAgentInput): Promise<DeployedAgent>;
+    list(limit?: number, offset?: number): Promise<AgentListResponse>;
+    get(agentId: string): Promise<DeployedAgent>;
+    update(agentId: string, patch: UpdateAgentPatch): Promise<DeployedAgent>;
+    delete(agentId: string): Promise<void>;
+    run(agentId: string, input: string, verificationMode?: "strict" | "balanced" | "permissive"): Promise<AgentRunResponse>;
+    a2aInvoke(agentId: string, input: string, trace?: string[], verificationMode?: "strict" | "balanced" | "permissive"): 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>;
+    /**
+     * Poll `getTask` until the task reaches a terminal status. Resolves
+     * with the final Task snapshot. Rejects with `Error("timeout")` if
+     * the task is still running after `timeoutMs`. Use `streamTask` when
+     * you need event-by-event progress instead of a single final state.
+     */
+    waitForTask(taskId: string, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<Task>;
+    /**
+     * Subscribe to `GET /v1/tasks/:id/stream` and yield typed
+     * StateTransition events as each workflow state completes. The
+     * generator closes when the upstream stream closes (task reached
+     * terminal status) or on connection error.
+     *
+     * @example
+     * ```ts
+     * for await (const event of agents.streamTask(run.task_id)) {
+     *   console.log(event.state_name, event.duration_ms);
+     * }
+     * ```
+     */
+    streamTask(taskId: string): AsyncGenerator<StateTransition>;
+}
+
+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, 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 TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus };

package/dist/index.js

@@ -21,9 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AgentClient: () => AgentClient,
+  AgentsClient: () => AgentsClient,
   ConnectionError: () => ConnectionError,
   Conversation: () => Conversation,
   HttpClient: () => HttpClient,
+  HttpError: () => HttpError,
   MockHttpClient: () => MockHttpClient,
   ServerError: () => ServerError,
   TimeoutError: () => TimeoutError,
@@ -32,7 +34,8 @@ __export(index_exports, {
   WauldoError: () => WauldoError,
   chatContent: () => chatContent,
   guardIsBlocked: () => guardIsBlocked,
-  guardIsSafe: () => guardIsSafe
+  guardIsSafe: () => guardIsSafe,
+  isTerminalStatus: () => isTerminalStatus
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1284,12 +1287,239 @@ function guardIsSafe(response) {
 function guardIsBlocked(response) {
   return response.action === "block";
 }
+
+// src/agents.ts
+var MAX_RESPONSE_SIZE = 10 * 1024 * 1024;
+function isTerminalStatus(s) {
+  return s === "completed" || s === "failed" || s === "cancelled";
+}
+async function _boundedRead(resp, limit = MAX_RESPONSE_SIZE) {
+  if (!resp.body) return new Uint8Array(0);
+  const reader = resp.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      total += value.byteLength;
+      if (total > limit) {
+        try {
+          await reader.cancel();
+        } catch {
+        }
+        throw new Error(
+          `response body too large: >${limit} bytes`
+        );
+      }
+      chunks.push(value);
+    }
+  }
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    merged.set(c, offset);
+    offset += c.byteLength;
+  }
+  return merged;
+}
+var HttpError = class extends Error {
+  constructor(status, statusText, body) {
+    super(`HTTP ${status} ${statusText}: ${body}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+    this.name = "HttpError";
+  }
+};
+var AgentsClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+  }
+  headers(extra) {
+    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, ...extra ?? {} };
+  }
+  async request(method, path, body, headerOverride) {
+    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(headerOverride),
+        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);
+      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 ────────────────────────────────────────────────────────
+  async create(input) {
+    const body = {
+      name: input.name,
+      wauldo_toml: input.wauldoToml,
+      description: input.description ?? ""
+    };
+    if (input.agentsMd !== void 0) body.agents_md = input.agentsMd;
+    if (input.mcpJson !== void 0) body.mcp_json = input.mcpJson;
+    if (input.preset !== void 0) body.preset = input.preset;
+    return await this.request("POST", "/v1/agents", body);
+  }
+  async list(limit = 20, offset = 0) {
+    return await this.request(
+      "GET",
+      `/v1/agents?limit=${limit}&offset=${offset}`
+    );
+  }
+  async get(agentId) {
+    return await this.request("GET", `/v1/agents/${agentId}`);
+  }
+  async update(agentId, patch) {
+    const body = {};
+    if (patch.description !== void 0) body.description = patch.description;
+    if (patch.wauldoToml !== void 0) body.wauldo_toml = patch.wauldoToml;
+    if (patch.agentsMd !== void 0) body.agents_md = patch.agentsMd;
+    if (patch.mcpJson !== void 0) body.mcp_json = patch.mcpJson;
+    if (patch.preset !== void 0) body.preset = patch.preset;
+    return await this.request("PATCH", `/v1/agents/${agentId}`, body);
+  }
+  async delete(agentId) {
+    await this.request("DELETE", `/v1/agents/${agentId}`);
+  }
+  // ── Runs ────────────────────────────────────────────────────────
+  async run(agentId, input, verificationMode) {
+    if (!input) throw new Error("input is required");
+    const body = { input };
+    if (verificationMode) body.verification_mode = verificationMode;
+    return await this.request(
+      "POST",
+      `/v1/agents/${agentId}/runs`,
+      body
+    );
+  }
+  async a2aInvoke(agentId, input, trace, verificationMode) {
+    if (!input) throw new Error("input is required");
+    const body = { input };
+    if (verificationMode) body.verification_mode = verificationMode;
+    const extraHeaders = {};
+    if (trace && trace.length > 0) extraHeaders["x-a2a-trace"] = trace.join(",");
+    return await this.request(
+      "POST",
+      `/v1/a2a/${agentId}`,
+      body,
+      extraHeaders
+    );
+  }
+  // ── Tasks (poll + stream) ───────────────────────────────────────
+  /** `GET /v1/tasks/:id` — fetch the current state of a task. */
+  async getTask(taskId) {
+    return await this.request("GET", `/v1/tasks/${taskId}`);
+  }
+  /** `DELETE /v1/tasks/:id` — cancel a queued or running task. */
+  async cancelTask(taskId) {
+    await this.request("DELETE", `/v1/tasks/${taskId}`);
+  }
+  /**
+   * Poll `getTask` until the task reaches a terminal status. Resolves
+   * with the final Task snapshot. Rejects with `Error("timeout")` if
+   * the task is still running after `timeoutMs`. Use `streamTask` when
+   * you need event-by-event progress instead of a single final state.
+   */
+  async waitForTask(taskId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 18e4;
+    const pollIntervalMs = opts.pollIntervalMs ?? 2e3;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const task = await this.getTask(taskId);
+      if (isTerminalStatus(task.status)) return task;
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `task ${taskId} still in status '${task.status}' after ${timeoutMs}ms`
+        );
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+  /**
+   * Subscribe to `GET /v1/tasks/:id/stream` and yield typed
+   * StateTransition events as each workflow state completes. The
+   * generator closes when the upstream stream closes (task reached
+   * terminal status) or on connection error.
+   *
+   * @example
+   * ```ts
+   * for await (const event of agents.streamTask(run.task_id)) {
+   *   console.log(event.state_name, event.duration_ms);
+   * }
+   * ```
+   */
+  async *streamTask(taskId) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + `/v1/tasks/${taskId}/stream`;
+    const controller = new AbortController();
+    const resp = await fetch(url, {
+      method: "GET",
+      headers: this.headers({ Accept: "text/event-stream" }),
+      signal: controller.signal
+    });
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => "");
+      throw new HttpError(resp.status, resp.statusText, text);
+    }
+    if (!resp.body) return;
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trimEnd().replace(/\r$/, "");
+          if (!trimmed.startsWith("data:")) continue;
+          const payload = trimmed.slice(5).trim();
+          if (!payload) continue;
+          try {
+            const obj = JSON.parse(payload);
+            yield obj;
+          } catch {
+          }
+        }
+      }
+    } finally {
+      try {
+        controller.abort();
+      } catch {
+      }
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentClient,
+  AgentsClient,
   ConnectionError,
   Conversation,
   HttpClient,
+  HttpError,
   MockHttpClient,
   ServerError,
   TimeoutError,
@@ -1298,5 +1528,6 @@ function guardIsBlocked(response) {
   WauldoError,
   chatContent,
   guardIsBlocked,
-  guardIsSafe
+  guardIsSafe,
+  isTerminalStatus
 });

package/dist/index.mjs

@@ -1246,11 +1246,238 @@ function guardIsSafe(response) {
 function guardIsBlocked(response) {
   return response.action === "block";
 }
+
+// src/agents.ts
+var MAX_RESPONSE_SIZE = 10 * 1024 * 1024;
+function isTerminalStatus(s) {
+  return s === "completed" || s === "failed" || s === "cancelled";
+}
+async function _boundedRead(resp, limit = MAX_RESPONSE_SIZE) {
+  if (!resp.body) return new Uint8Array(0);
+  const reader = resp.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      total += value.byteLength;
+      if (total > limit) {
+        try {
+          await reader.cancel();
+        } catch {
+        }
+        throw new Error(
+          `response body too large: >${limit} bytes`
+        );
+      }
+      chunks.push(value);
+    }
+  }
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    merged.set(c, offset);
+    offset += c.byteLength;
+  }
+  return merged;
+}
+var HttpError = class extends Error {
+  constructor(status, statusText, body) {
+    super(`HTTP ${status} ${statusText}: ${body}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+    this.name = "HttpError";
+  }
+};
+var AgentsClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+  }
+  headers(extra) {
+    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, ...extra ?? {} };
+  }
+  async request(method, path, body, headerOverride) {
+    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(headerOverride),
+        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);
+      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 ────────────────────────────────────────────────────────
+  async create(input) {
+    const body = {
+      name: input.name,
+      wauldo_toml: input.wauldoToml,
+      description: input.description ?? ""
+    };
+    if (input.agentsMd !== void 0) body.agents_md = input.agentsMd;
+    if (input.mcpJson !== void 0) body.mcp_json = input.mcpJson;
+    if (input.preset !== void 0) body.preset = input.preset;
+    return await this.request("POST", "/v1/agents", body);
+  }
+  async list(limit = 20, offset = 0) {
+    return await this.request(
+      "GET",
+      `/v1/agents?limit=${limit}&offset=${offset}`
+    );
+  }
+  async get(agentId) {
+    return await this.request("GET", `/v1/agents/${agentId}`);
+  }
+  async update(agentId, patch) {
+    const body = {};
+    if (patch.description !== void 0) body.description = patch.description;
+    if (patch.wauldoToml !== void 0) body.wauldo_toml = patch.wauldoToml;
+    if (patch.agentsMd !== void 0) body.agents_md = patch.agentsMd;
+    if (patch.mcpJson !== void 0) body.mcp_json = patch.mcpJson;
+    if (patch.preset !== void 0) body.preset = patch.preset;
+    return await this.request("PATCH", `/v1/agents/${agentId}`, body);
+  }
+  async delete(agentId) {
+    await this.request("DELETE", `/v1/agents/${agentId}`);
+  }
+  // ── Runs ────────────────────────────────────────────────────────
+  async run(agentId, input, verificationMode) {
+    if (!input) throw new Error("input is required");
+    const body = { input };
+    if (verificationMode) body.verification_mode = verificationMode;
+    return await this.request(
+      "POST",
+      `/v1/agents/${agentId}/runs`,
+      body
+    );
+  }
+  async a2aInvoke(agentId, input, trace, verificationMode) {
+    if (!input) throw new Error("input is required");
+    const body = { input };
+    if (verificationMode) body.verification_mode = verificationMode;
+    const extraHeaders = {};
+    if (trace && trace.length > 0) extraHeaders["x-a2a-trace"] = trace.join(",");
+    return await this.request(
+      "POST",
+      `/v1/a2a/${agentId}`,
+      body,
+      extraHeaders
+    );
+  }
+  // ── Tasks (poll + stream) ───────────────────────────────────────
+  /** `GET /v1/tasks/:id` — fetch the current state of a task. */
+  async getTask(taskId) {
+    return await this.request("GET", `/v1/tasks/${taskId}`);
+  }
+  /** `DELETE /v1/tasks/:id` — cancel a queued or running task. */
+  async cancelTask(taskId) {
+    await this.request("DELETE", `/v1/tasks/${taskId}`);
+  }
+  /**
+   * Poll `getTask` until the task reaches a terminal status. Resolves
+   * with the final Task snapshot. Rejects with `Error("timeout")` if
+   * the task is still running after `timeoutMs`. Use `streamTask` when
+   * you need event-by-event progress instead of a single final state.
+   */
+  async waitForTask(taskId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 18e4;
+    const pollIntervalMs = opts.pollIntervalMs ?? 2e3;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const task = await this.getTask(taskId);
+      if (isTerminalStatus(task.status)) return task;
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `task ${taskId} still in status '${task.status}' after ${timeoutMs}ms`
+        );
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+  /**
+   * Subscribe to `GET /v1/tasks/:id/stream` and yield typed
+   * StateTransition events as each workflow state completes. The
+   * generator closes when the upstream stream closes (task reached
+   * terminal status) or on connection error.
+   *
+   * @example
+   * ```ts
+   * for await (const event of agents.streamTask(run.task_id)) {
+   *   console.log(event.state_name, event.duration_ms);
+   * }
+   * ```
+   */
+  async *streamTask(taskId) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + `/v1/tasks/${taskId}/stream`;
+    const controller = new AbortController();
+    const resp = await fetch(url, {
+      method: "GET",
+      headers: this.headers({ Accept: "text/event-stream" }),
+      signal: controller.signal
+    });
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => "");
+      throw new HttpError(resp.status, resp.statusText, text);
+    }
+    if (!resp.body) return;
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trimEnd().replace(/\r$/, "");
+          if (!trimmed.startsWith("data:")) continue;
+          const payload = trimmed.slice(5).trim();
+          if (!payload) continue;
+          try {
+            const obj = JSON.parse(payload);
+            yield obj;
+          } catch {
+          }
+        }
+      }
+    } finally {
+      try {
+        controller.abort();
+      } catch {
+      }
+    }
+  }
+};
 export {
   AgentClient,
+  AgentsClient,
   ConnectionError,
   Conversation,
   HttpClient,
+  HttpError,
   MockHttpClient,
   ServerError,
   TimeoutError,
@@ -1259,5 +1486,6 @@ export {
   WauldoError,
   chatContent,
   guardIsBlocked,
-  guardIsSafe
+  guardIsSafe,
+  isTerminalStatus
 };

package/package.json

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