wauldo 0.10.0 → 0.12.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,4 +919,112 @@ declare class AgentsClient {
     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, supportScore };
+/**
+ * History API client — Wauldo Funnel #1 audit log.
+ *
+ * Read-only access to a tenant's task history (every completed task is
+ * persisted to a tenant-scoped DynamoDB audit log on the server side,
+ * exposed via /v1/history). Mirrors {@link MemoryClient} shape so a
+ * caller already familiar with the Memory API has zero ramp-up.
+ *
+ * Three formats:
+ *
+ * - {@link HistoryClient.list} — paginated JSON, suitable for dashboards.
+ * - {@link HistoryClient.export} with `format="csv"` — single CSV blob
+ *   (compliance evidence, header + footer metadata).
+ * - {@link HistoryClient.export} with `format="jsonl"` — newline-
+ *   delimited JSON for log pipelines.
+ *
+ * Right To Be Forgotten (GDPR Art. 17) is supported via
+ * {@link HistoryClient.deleteTask}, which removes every audit row for a
+ * specific task id within the caller's tenant.
+ *
+ * @example
+ * ```ts
+ * import { HistoryClient } from "wauldo/history";
+ * const hist = new HistoryClient({
+ *   baseUrl: "https://api.wauldo.com",
+ *   apiKey: "tig_live_...",
+ *   tenant: "my-org",
+ * });
+ * const page = await hist.list({ verdict: "CONFLICT", limit: 20 });
+ * for (const item of page.items) console.log(item.task_id, item.verdict);
+ * const blob = await hist.export({ format: "csv" });
+ * await hist.deleteTask("a69b8612-0c47-43f3-93f2-c00c8a4ac1f8");
+ * ```
+ */
+interface HistoryClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    tenant?: string;
+    timeoutMs?: number;
+}
+interface TaskHistoryEntry {
+    task_id: string;
+    tenant_id: string;
+    agent_id?: string | null;
+    verdict: string;
+    support_score: number;
+    halluc_rate: number;
+    latency_ms: number;
+    cost_micro_usd: number;
+    claims_count: number;
+    model?: string | null;
+    created_at: number;
+}
+interface HistoryListResponse {
+    items: TaskHistoryEntry[];
+    next_cursor: string | null;
+    /**
+     * `false` when the server hasn't wired its DynamoDB store (self-host
+     * without IAM perm). UI should show "audit log not enabled" rather
+     * than "no events yet" in that case.
+     */
+    enabled: boolean;
+}
+interface ListOptions {
+    verdict?: string;
+    agentId?: string;
+    fromMs?: number;
+    toMs?: number;
+    limit?: number;
+    cursor?: string;
+}
+interface ExportOptions extends Omit<ListOptions, "limit" | "cursor"> {
+    format: "csv" | "jsonl" | "json";
+}
+declare class HistoryClient {
+    private readonly config;
+    constructor(config: HistoryClientConfig);
+    private headers;
+    private buildQs;
+    private fetchRaw;
+    /**
+     * GET /v1/history — paginated audit log page. Pass `cursor` from a
+     * previous response's `next_cursor` to paginate. Filters compose
+     * with AND.
+     */
+    list(opts?: ListOptions): Promise<HistoryListResponse>;
+    /**
+     * Async generator over all pages within a window, yielding each page
+     * as the server returns it. Stops when `next_cursor` is null.
+     */
+    iterPages(opts?: ListOptions): AsyncIterableIterator<HistoryListResponse>;
+    /**
+     * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+     * the body as a string (`format=csv|jsonl`) or a parsed object
+     * (`format=json`). Server auto-paginates up to 10000 rows; the body
+     * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+     * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+     * a non-2xx response throws.
+     */
+    export(opts: ExportOptions): Promise<string | HistoryListResponse>;
+    /**
+     * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+     * audit row for `taskId` within the caller's tenant. Idempotent.
+     * Returns the number of rows deleted.
+     */
+    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 };

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,4 +919,112 @@ declare class AgentsClient {
     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, supportScore };
+/**
+ * History API client — Wauldo Funnel #1 audit log.
+ *
+ * Read-only access to a tenant's task history (every completed task is
+ * persisted to a tenant-scoped DynamoDB audit log on the server side,
+ * exposed via /v1/history). Mirrors {@link MemoryClient} shape so a
+ * caller already familiar with the Memory API has zero ramp-up.
+ *
+ * Three formats:
+ *
+ * - {@link HistoryClient.list} — paginated JSON, suitable for dashboards.
+ * - {@link HistoryClient.export} with `format="csv"` — single CSV blob
+ *   (compliance evidence, header + footer metadata).
+ * - {@link HistoryClient.export} with `format="jsonl"` — newline-
+ *   delimited JSON for log pipelines.
+ *
+ * Right To Be Forgotten (GDPR Art. 17) is supported via
+ * {@link HistoryClient.deleteTask}, which removes every audit row for a
+ * specific task id within the caller's tenant.
+ *
+ * @example
+ * ```ts
+ * import { HistoryClient } from "wauldo/history";
+ * const hist = new HistoryClient({
+ *   baseUrl: "https://api.wauldo.com",
+ *   apiKey: "tig_live_...",
+ *   tenant: "my-org",
+ * });
+ * const page = await hist.list({ verdict: "CONFLICT", limit: 20 });
+ * for (const item of page.items) console.log(item.task_id, item.verdict);
+ * const blob = await hist.export({ format: "csv" });
+ * await hist.deleteTask("a69b8612-0c47-43f3-93f2-c00c8a4ac1f8");
+ * ```
+ */
+interface HistoryClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    tenant?: string;
+    timeoutMs?: number;
+}
+interface TaskHistoryEntry {
+    task_id: string;
+    tenant_id: string;
+    agent_id?: string | null;
+    verdict: string;
+    support_score: number;
+    halluc_rate: number;
+    latency_ms: number;
+    cost_micro_usd: number;
+    claims_count: number;
+    model?: string | null;
+    created_at: number;
+}
+interface HistoryListResponse {
+    items: TaskHistoryEntry[];
+    next_cursor: string | null;
+    /**
+     * `false` when the server hasn't wired its DynamoDB store (self-host
+     * without IAM perm). UI should show "audit log not enabled" rather
+     * than "no events yet" in that case.
+     */
+    enabled: boolean;
+}
+interface ListOptions {
+    verdict?: string;
+    agentId?: string;
+    fromMs?: number;
+    toMs?: number;
+    limit?: number;
+    cursor?: string;
+}
+interface ExportOptions extends Omit<ListOptions, "limit" | "cursor"> {
+    format: "csv" | "jsonl" | "json";
+}
+declare class HistoryClient {
+    private readonly config;
+    constructor(config: HistoryClientConfig);
+    private headers;
+    private buildQs;
+    private fetchRaw;
+    /**
+     * GET /v1/history — paginated audit log page. Pass `cursor` from a
+     * previous response's `next_cursor` to paginate. Filters compose
+     * with AND.
+     */
+    list(opts?: ListOptions): Promise<HistoryListResponse>;
+    /**
+     * Async generator over all pages within a window, yielding each page
+     * as the server returns it. Stops when `next_cursor` is null.
+     */
+    iterPages(opts?: ListOptions): AsyncIterableIterator<HistoryListResponse>;
+    /**
+     * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+     * the body as a string (`format=csv|jsonl`) or a parsed object
+     * (`format=json`). Server auto-paginates up to 10000 rows; the body
+     * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+     * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+     * a non-2xx response throws.
+     */
+    export(opts: ExportOptions): Promise<string | HistoryListResponse>;
+    /**
+     * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+     * audit row for `taskId` within the caller's tenant. Idempotent.
+     * Returns the number of rows deleted.
+     */
+    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 };

package/dist/index.js

@@ -24,6 +24,7 @@ __export(index_exports, {
   AgentsClient: () => AgentsClient,
   ConnectionError: () => ConnectionError,
   Conversation: () => Conversation,
+  HistoryClient: () => HistoryClient,
   HttpClient: () => HttpClient,
   HttpError: () => HttpError,
   MockHttpClient: () => MockHttpClient,
@@ -1406,6 +1407,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");
@@ -1441,6 +1491,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
@@ -1518,12 +1598,122 @@ var AgentsClient = class {
     }
   }
 };
+
+// src/history.ts
+var HistoryClient = 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;
+  }
+  buildQs(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0 && v !== null);
+    if (entries.length === 0) return "";
+    const usp = new URLSearchParams();
+    for (const [k, v] of entries) usp.set(k, String(v));
+    return "?" + usp.toString();
+  }
+  async fetchRaw(method, path) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + path;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 6e4);
+    try {
+      const resp = await fetch(url, {
+        method,
+        headers: this.headers(),
+        signal: controller.signal
+      });
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new Error(`HTTP ${resp.status} ${resp.statusText}: ${body.slice(0, 200)}`);
+      }
+      return resp;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * GET /v1/history — paginated audit log page. Pass `cursor` from a
+   * previous response's `next_cursor` to paginate. Filters compose
+   * with AND.
+   */
+  async list(opts = {}) {
+    const qs = this.buildQs({
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs,
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    return await resp.json();
+  }
+  /**
+   * Async generator over all pages within a window, yielding each page
+   * as the server returns it. Stops when `next_cursor` is null.
+   */
+  async *iterPages(opts = {}) {
+    let cursor = opts.cursor;
+    const pageSize = opts.limit ?? 50;
+    while (true) {
+      const next = { ...opts, limit: pageSize };
+      if (cursor !== void 0) next.cursor = cursor;
+      const page = await this.list(next);
+      yield page;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+  }
+  /**
+   * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+   * the body as a string (`format=csv|jsonl`) or a parsed object
+   * (`format=json`). Server auto-paginates up to 10000 rows; the body
+   * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+   * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+   * a non-2xx response throws.
+   */
+  async export(opts) {
+    if (!["csv", "jsonl", "json"].includes(opts.format)) {
+      throw new Error(`unsupported format '${opts.format}' \u2014 use csv|jsonl|json`);
+    }
+    const qs = this.buildQs({
+      format: opts.format,
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    if (opts.format === "json") {
+      return await resp.json();
+    }
+    return await resp.text();
+  }
+  /**
+   * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+   * audit row for `taskId` within the caller's tenant. Idempotent.
+   * Returns the number of rows deleted.
+   */
+  async deleteTask(taskId) {
+    if (!taskId) throw new Error("taskId required");
+    const resp = await this.fetchRaw("DELETE", `/v1/history/${encodeURIComponent(taskId)}`);
+    const body = await resp.json();
+    return Number(body?.deleted ?? 0);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentClient,
   AgentsClient,
   ConnectionError,
   Conversation,
+  HistoryClient,
   HttpClient,
   HttpError,
   MockHttpClient,

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
@@ -1476,11 +1555,121 @@ var AgentsClient = class {
     }
   }
 };
+
+// src/history.ts
+var HistoryClient = 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;
+  }
+  buildQs(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0 && v !== null);
+    if (entries.length === 0) return "";
+    const usp = new URLSearchParams();
+    for (const [k, v] of entries) usp.set(k, String(v));
+    return "?" + usp.toString();
+  }
+  async fetchRaw(method, path) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + path;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 6e4);
+    try {
+      const resp = await fetch(url, {
+        method,
+        headers: this.headers(),
+        signal: controller.signal
+      });
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new Error(`HTTP ${resp.status} ${resp.statusText}: ${body.slice(0, 200)}`);
+      }
+      return resp;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * GET /v1/history — paginated audit log page. Pass `cursor` from a
+   * previous response's `next_cursor` to paginate. Filters compose
+   * with AND.
+   */
+  async list(opts = {}) {
+    const qs = this.buildQs({
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs,
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    return await resp.json();
+  }
+  /**
+   * Async generator over all pages within a window, yielding each page
+   * as the server returns it. Stops when `next_cursor` is null.
+   */
+  async *iterPages(opts = {}) {
+    let cursor = opts.cursor;
+    const pageSize = opts.limit ?? 50;
+    while (true) {
+      const next = { ...opts, limit: pageSize };
+      if (cursor !== void 0) next.cursor = cursor;
+      const page = await this.list(next);
+      yield page;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+  }
+  /**
+   * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+   * the body as a string (`format=csv|jsonl`) or a parsed object
+   * (`format=json`). Server auto-paginates up to 10000 rows; the body
+   * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+   * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+   * a non-2xx response throws.
+   */
+  async export(opts) {
+    if (!["csv", "jsonl", "json"].includes(opts.format)) {
+      throw new Error(`unsupported format '${opts.format}' \u2014 use csv|jsonl|json`);
+    }
+    const qs = this.buildQs({
+      format: opts.format,
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    if (opts.format === "json") {
+      return await resp.json();
+    }
+    return await resp.text();
+  }
+  /**
+   * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+   * audit row for `taskId` within the caller's tenant. Idempotent.
+   * Returns the number of rows deleted.
+   */
+  async deleteTask(taskId) {
+    if (!taskId) throw new Error("taskId required");
+    const resp = await this.fetchRaw("DELETE", `/v1/history/${encodeURIComponent(taskId)}`);
+    const body = await resp.json();
+    return Number(body?.deleted ?? 0);
+  }
+};
 export {
   AgentClient,
   AgentsClient,
   ConnectionError,
   Conversation,
+  HistoryClient,
   HttpClient,
   HttpError,
   MockHttpClient,

package/package.json

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