wauldo 0.11.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
@@ -941,4 +1027,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 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
@@ -941,4 +1027,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 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

@@ -1407,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");
@@ -1442,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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wauldo",
-  "version": "0.11.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",