aira-sdk 2.1.0 → 3.0.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { Authorization, ActionReceipt, ActionDetail, AgentDetail, AgentVersion, CosignResult, EvidencePackage, ComplianceSnapshot, EscrowAccount, EscrowTransaction, VerifyResult, PaginatedList } from "./types";
+import { Authorization, ActionReceipt, ActionDetail, AgentDetail, AgentVersion, CosignResult, EvidencePackage, ComplianceSnapshot, EscrowAccount, EscrowTransaction, VerifyResult, PaginatedList, ComplianceReport, ComplianceReportListResponse, ComplianceReportVerification, ActionExplanation, ExplanationVerification, OutputPolicy, OutputPolicyUpdate } from "./types";
 import { AiraSession } from "./session";
 export interface AiraOptions {
     apiKey: string;
@@ -16,6 +16,7 @@ export declare class Aira {
     private get;
     private post;
     private put;
+    private patch;
     private del;
     private paginated;
     /**
@@ -23,7 +24,7 @@ export declare class Aira {
      *
      * Returns an `Authorization` with a status:
      *  - "authorized"       → safe to execute the action, then call `notarize()`
-     *  - "pending_approval" → enqueue `action_id` and wait for human approval
+     *  - "pending_approval" → enqueue `action_uuid` and wait for human approval
      *
      * If a policy denies the action, this throws `AiraError` with code
      * `POLICY_DENIED` (HTTP 403). Duplicate idempotent requests throw
@@ -271,6 +272,88 @@ export declare class Aira {
     getSettlement(settlementId: string): Promise<Record<string, unknown>>;
     /** Get the Merkle inclusion proof for one receipt in its settlement. */
     getSettlementInclusionProof(receiptId: string): Promise<Record<string, unknown>>;
+    /**
+     * Generate a regulatory PDF report.
+     *
+     * Frameworks:
+     * - `eu_ai_act_art12` — Annex VII technical file. Requires period.
+     * - `eu_ai_act_art9` — risk management register. Requires period.
+     * - `eu_ai_act_art6` — single-action explanation. Requires actionId.
+     * - `eu_ai_act_annex_iv` — full Annex IV technical documentation
+     *   (§§1..9). Requires period. Typical use: annual file for the
+     *   high-risk AI system provider obligations in Article 11.
+     */
+    createComplianceReport(params: {
+        framework: string;
+        periodStart?: string;
+        periodEnd?: string;
+        actionId?: string;
+        agentFilter?: string[];
+    }): Promise<ComplianceReport>;
+    /** Get the metadata for a compliance report (no PDF bytes). */
+    getComplianceReport(reportId: string): Promise<ComplianceReport>;
+    /** List compliance reports with optional filters. */
+    listComplianceReports(params?: {
+        framework?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ComplianceReportListResponse>;
+    /**
+     * Download the generated PDF as raw bytes (Uint8Array).
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    downloadComplianceReport(reportId: string): Promise<Uint8Array>;
+    /** Verify a compliance report's signature and content hash. */
+    verifyComplianceReport(reportId: string): Promise<ComplianceReportVerification>;
+    /**
+     * Return the org's output content-scan policy.
+     *
+     * Scans apply to the `outcomeDetails` passed to `notarize()`. Mode
+     * controls behaviour:
+     *  - `flag` — hits are recorded on the receipt, nothing blocked
+     *  - `deny` — a hit at or above `deny_severity_threshold` makes
+     *    notarize return 422 with code `OUTPUT_SCAN_VIOLATION`
+     *  - `redact` — matched spans are replaced with `[REDACTED]` and
+     *    the receipt signs over the cleaned bytes
+     */
+    getOutputPolicy(): Promise<OutputPolicy>;
+    /**
+     * Merge the supplied fields into the org's output content-scan
+     * policy. Omitted fields stay at their current values. Admin role
+     * required server-side.
+     */
+    updateOutputPolicy(updates: OutputPolicyUpdate): Promise<OutputPolicy>;
+    /**
+     * Article 6 right-to-explanation for a single action.
+     *
+     * The response includes a cryptographic ``_envelope`` — verify it
+     * later with {@link verifyActionExplanation} (the verify endpoint
+     * is public, so anyone holding the JSON can re-check it).
+     */
+    getActionExplanation(actionId: string): Promise<ActionExplanation>;
+    /**
+     * Public verify — recompute an explanation envelope's signature.
+     *
+     * POSTs the full explanation JSON to the unauthenticated
+     * ``/verify/explanation`` endpoint. The server looks up the public
+     * key by ``_envelope.signing_key_id`` and re-derives the canonical
+     * content hash + Ed25519 signature.
+     *
+     * ``request_id`` is stripped before sending, so a saved JSON
+     * explanation verifies the same way regardless of whether the
+     * caller round-tripped it through their own logs.
+     */
+    verifyActionExplanation(explanation: ActionExplanation | Record<string, unknown>): Promise<ExplanationVerification>;
+    /**
+     * Download the Article 6 explanation as a PDF.
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    downloadActionExplanationPdf(actionId: string): Promise<Uint8Array>;
     /** Create a scoped session with pre-filled defaults. */
     session(agentId: string, defaults?: Record<string, unknown>): AiraSession;
     /** Number of queued offline requests. */

package/dist/client.js

@@ -7,6 +7,44 @@ const session_1 = require("./session");
 const DEFAULT_BASE_URL = "https://api.airaproof.com";
 const DEFAULT_TIMEOUT = 30_000;
 const MAX_DETAILS_LENGTH = 50_000;
+// Binary download endpoints retry on transient 5xx (server hiccups,
+// brief gateway issues). 3 attempts with exponential backoff
+// (250ms -> 500ms -> 1000ms) keeps the worst case under 2s while
+// absorbing the most common flakes. 4xx errors are NOT retried —
+// those indicate a real problem the caller needs to see.
+const DOWNLOAD_MAX_ATTEMPTS = 3;
+const DOWNLOAD_BACKOFF_BASE_MS = 250;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Run a fetch with retries on transient 5xx and network errors.
+ * Returns the final Response (which may itself be a 5xx after all
+ * attempts are exhausted — caller decides whether to throw).
+ */
+async function fetchWithRetry(doFetch) {
+    let lastErr;
+    for (let attempt = 0; attempt < DOWNLOAD_MAX_ATTEMPTS; attempt++) {
+        try {
+            const res = await doFetch();
+            if (res.status >= 500 && attempt < DOWNLOAD_MAX_ATTEMPTS - 1) {
+                await sleep(DOWNLOAD_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            return res;
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt < DOWNLOAD_MAX_ATTEMPTS - 1) {
+                await sleep(DOWNLOAD_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            throw err;
+        }
+    }
+    // Unreachable in practice — the loop either returns or throws.
+    throw lastErr ?? new Error("download retry loop exited without a response");
+}
 function buildBody(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null));
 }
@@ -76,6 +114,13 @@ class Aira {
         }
         return this.request("PUT", path, body);
     }
+    patch(path, body) {
+        if (this.queue) {
+            const qid = this.queue.enqueue("PATCH", path, body);
+            return Promise.resolve({ _offline: true, _queue_id: qid });
+        }
+        return this.request("PATCH", path, body);
+    }
     del(path) {
         if (this.queue) {
             const qid = this.queue.enqueue("DELETE", path, {});
@@ -93,7 +138,7 @@ class Aira {
      *
      * Returns an `Authorization` with a status:
      *  - "authorized"       → safe to execute the action, then call `notarize()`
-     *  - "pending_approval" → enqueue `action_id` and wait for human approval
+     *  - "pending_approval" → enqueue `action_uuid` and wait for human approval
      *
      * If a policy denies the action, this throws `AiraError` with code
      * `POLICY_DENIED` (HTTP 403). Duplicate idempotent requests throw
@@ -108,7 +153,7 @@ class Aira {
             instruction_hash: params.instructionHash,
             model_id: params.modelId,
             model_version: params.modelVersion,
-            parent_action_id: params.parentActionId,
+            parent_action_uuid: params.parentActionId,
             endpoint_url: params.endpointUrl,
             store_details: params.storeDetails || undefined,
             idempotency_key: params.idempotencyKey,
@@ -202,7 +247,7 @@ class Aira {
         return this.post(`/agents/${slug}/decommission`, {});
     }
     async transferAgent(slug, toOrgId, reason) {
-        return this.post(`/agents/${slug}/transfer`, buildBody({ to_org_id: toOrgId, reason }));
+        return this.post(`/agents/${slug}/transfer`, buildBody({ to_org_uuid: toOrgId, reason }));
     }
     async getAgentActions(slug, page = 1) {
         const data = await this.get(`/agents/${slug}/actions`, { page });
@@ -232,7 +277,7 @@ class Aira {
     // ==================== Evidence ====================
     async createEvidencePackage(params) {
         return this.post("/evidence/packages", buildBody({
-            title: params.title, action_ids: params.actionIds, description: params.description, agent_slugs: params.agentSlugs,
+            title: params.title, action_uuids: params.actionIds, description: params.description, agent_slugs: params.agentSlugs,
         }));
     }
     async listEvidencePackages(page = 1) {
@@ -282,7 +327,7 @@ class Aira {
     async createEscrowAccount(params) {
         return this.post("/escrow/accounts", buildBody({
             purpose: params?.purpose, currency: params?.currency ?? "EUR",
-            agent_id: params?.agentId, counterparty_org_id: params?.counterpartyOrgId,
+            agent_id: params?.agentId, counterparty_org_uuid: params?.counterpartyOrgId,
         }));
     }
     async listEscrowAccounts(page = 1) {
@@ -294,17 +339,17 @@ class Aira {
     }
     async escrowDeposit(accountId, amount, description, referenceActionId) {
         return this.post(`/escrow/accounts/${accountId}/deposit`, buildBody({
-            amount, description, reference_action_id: referenceActionId,
+            amount, description, reference_action_uuid: referenceActionId,
         }));
     }
     async escrowRelease(accountId, amount, description, referenceActionId) {
         return this.post(`/escrow/accounts/${accountId}/release`, buildBody({
-            amount, description, reference_action_id: referenceActionId,
+            amount, description, reference_action_uuid: referenceActionId,
         }));
     }
     async escrowDispute(accountId, amount, description, referenceActionId) {
         return this.post(`/escrow/accounts/${accountId}/dispute`, buildBody({
-            amount, description, reference_action_id: referenceActionId,
+            amount, description, reference_action_uuid: referenceActionId,
         }));
     }
     // ==================== Chat ====================
@@ -374,7 +419,7 @@ class Aira {
     /** Submit a signed attestation of a successful interaction. */
     async attestReputation(slug, counterpartyDid, actionId, attestation, signature) {
         return this.post(`/agents/${slug}/reputation/attest`, {
-            counterparty_did: counterpartyDid, action_id: actionId, attestation, signature,
+            counterparty_did: counterpartyDid, action_uuid: actionId, attestation, signature,
         });
     }
     /** Verify a reputation score by returning inputs and score_hash. */
@@ -487,6 +532,156 @@ class Aira {
     async getSettlementInclusionProof(receiptId) {
         return this.get(`/settlements/inclusion-proof/${receiptId}`);
     }
+    // ==================== Compliance reports (Phase 1) ====================
+    /**
+     * Generate a regulatory PDF report.
+     *
+     * Frameworks:
+     * - `eu_ai_act_art12` — Annex VII technical file. Requires period.
+     * - `eu_ai_act_art9` — risk management register. Requires period.
+     * - `eu_ai_act_art6` — single-action explanation. Requires actionId.
+     * - `eu_ai_act_annex_iv` — full Annex IV technical documentation
+     *   (§§1..9). Requires period. Typical use: annual file for the
+     *   high-risk AI system provider obligations in Article 11.
+     */
+    async createComplianceReport(params) {
+        const body = buildBody({
+            framework: params.framework,
+            period_start: params.periodStart,
+            period_end: params.periodEnd,
+            action_uuid: params.actionId,
+            agent_filter: params.agentFilter,
+        });
+        return this.post("/compliance/reports", body);
+    }
+    /** Get the metadata for a compliance report (no PDF bytes). */
+    async getComplianceReport(reportId) {
+        return this.get(`/compliance/reports/${reportId}`);
+    }
+    /** List compliance reports with optional filters. */
+    async listComplianceReports(params) {
+        return this.get("/compliance/reports", buildBody({ ...params }));
+    }
+    /**
+     * Download the generated PDF as raw bytes (Uint8Array).
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    async downloadComplianceReport(reportId) {
+        if (this.queue) {
+            throw new types_1.AiraError(0, "OFFLINE", "Downloads are not available in offline mode");
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetchWithRetry(() => fetch(`${this.baseUrl}/compliance/reports/${reportId}/download`, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                signal: controller.signal,
+            }));
+            if (!res.ok) {
+                throw new types_1.AiraError(res.status, "DOWNLOAD_FAILED", res.statusText);
+            }
+            const buf = await res.arrayBuffer();
+            return new Uint8Array(buf);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Verify a compliance report's signature and content hash. */
+    async verifyComplianceReport(reportId) {
+        return this.get(`/compliance/reports/${reportId}/verify`);
+    }
+    // ==================== Output content-scan policy ====================
+    /**
+     * Return the org's output content-scan policy.
+     *
+     * Scans apply to the `outcomeDetails` passed to `notarize()`. Mode
+     * controls behaviour:
+     *  - `flag` — hits are recorded on the receipt, nothing blocked
+     *  - `deny` — a hit at or above `deny_severity_threshold` makes
+     *    notarize return 422 with code `OUTPUT_SCAN_VIOLATION`
+     *  - `redact` — matched spans are replaced with `[REDACTED]` and
+     *    the receipt signs over the cleaned bytes
+     */
+    async getOutputPolicy() {
+        return this.get("/output-policies");
+    }
+    /**
+     * Merge the supplied fields into the org's output content-scan
+     * policy. Omitted fields stay at their current values. Admin role
+     * required server-side.
+     */
+    async updateOutputPolicy(updates) {
+        // Strip undefined so they don't travel as `null` and accidentally
+        // reset server-side values.
+        const body = {};
+        for (const [k, v] of Object.entries(updates)) {
+            if (v !== undefined)
+                body[k] = v;
+        }
+        return this.patch("/output-policies", body);
+    }
+    /**
+     * Article 6 right-to-explanation for a single action.
+     *
+     * The response includes a cryptographic ``_envelope`` — verify it
+     * later with {@link verifyActionExplanation} (the verify endpoint
+     * is public, so anyone holding the JSON can re-check it).
+     */
+    async getActionExplanation(actionId) {
+        return this.get(`/actions/${actionId}/explanation`);
+    }
+    /**
+     * Public verify — recompute an explanation envelope's signature.
+     *
+     * POSTs the full explanation JSON to the unauthenticated
+     * ``/verify/explanation`` endpoint. The server looks up the public
+     * key by ``_envelope.signing_key_id`` and re-derives the canonical
+     * content hash + Ed25519 signature.
+     *
+     * ``request_id`` is stripped before sending, so a saved JSON
+     * explanation verifies the same way regardless of whether the
+     * caller round-tripped it through their own logs.
+     */
+    async verifyActionExplanation(explanation) {
+        const payload = {};
+        for (const [k, v] of Object.entries(explanation)) {
+            if (k === "request_id")
+                continue;
+            payload[k] = v;
+        }
+        return this.request("POST", "/verify/explanation", { explanation: payload }, false);
+    }
+    /**
+     * Download the Article 6 explanation as a PDF.
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    async downloadActionExplanationPdf(actionId) {
+        if (this.queue) {
+            throw new types_1.AiraError(0, "OFFLINE", "Downloads are not available in offline mode");
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetchWithRetry(() => fetch(`${this.baseUrl}/actions/${actionId}/explanation/pdf`, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                signal: controller.signal,
+            }));
+            if (!res.ok) {
+                throw new types_1.AiraError(res.status, "DOWNLOAD_FAILED", res.statusText);
+            }
+            return new Uint8Array(await res.arrayBuffer());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     // ==================== Session ====================
     /** Create a scoped session with pre-filled defaults. */
     session(agentId, defaults) {

package/dist/extras/langchain.d.ts

@@ -16,7 +16,7 @@
  * This handler implements the two-step flow as follows:
  *
  *   1. handleToolStart  → aira.authorize()
- *       - If the backend returns "authorized" we cache the action_id
+ *       - If the backend returns "authorized" we cache the action_uuid
  *         keyed by LangChain's `runId`, then return so the tool executes.
  *       - If the backend throws POLICY_DENIED we propagate the error,
  *         which prevents the tool from running at all (real gate).
@@ -51,7 +51,7 @@ export declare class AiraCallbackHandler {
     private actionTypes;
     private trustPolicy?;
     private strict;
-    /** runId → action_id cache so handleEnd can notarize the right action. */
+    /** runId → action_uuid cache so handleEnd can notarize the right action. */
     private inFlight;
     constructor(client: Aira, agentId: string, options?: AiraCallbackHandlerOptions);
     /**

package/dist/extras/langchain.js

@@ -17,7 +17,7 @@
  * This handler implements the two-step flow as follows:
  *
  *   1. handleToolStart  → aira.authorize()
- *       - If the backend returns "authorized" we cache the action_id
+ *       - If the backend returns "authorized" we cache the action_uuid
  *         keyed by LangChain's `runId`, then return so the tool executes.
  *       - If the backend throws POLICY_DENIED we propagate the error,
  *         which prevents the tool from running at all (real gate).
@@ -46,7 +46,7 @@ class AiraCallbackHandler {
     actionTypes;
     trustPolicy;
     strict;
-    /** runId → action_id cache so handleEnd can notarize the right action. */
+    /** runId → action_uuid cache so handleEnd can notarize the right action. */
     inFlight = new Map();
     constructor(client, agentId, options) {
         this.client = client;
@@ -81,11 +81,11 @@ class AiraCallbackHandler {
             });
             if (auth.status === "pending_approval") {
                 // Real gate — block the tool from running until a human approves.
-                const err = new Error(`Aira: action '${actionType}' is pending human approval (action_id=${auth.action_id}). Tool execution blocked.`);
+                const err = new Error(`Aira: action '${actionType}' is pending human approval (action_uuid=${auth.action_uuid}). Tool execution blocked.`);
                 err.code = "PENDING_APPROVAL";
                 throw err;
             }
-            this.inFlight.set(runId, auth.action_id);
+            this.inFlight.set(runId, auth.action_uuid);
         }
         catch (e) {
             const err = e;

package/dist/extras/mcp.js

@@ -39,7 +39,7 @@ function getTools() {
     return [
         {
             name: "authorize_action",
-            description: "Step 1 of the Aira two-step flow. Authorize an action BEFORE it executes. Returns an action_id with status 'authorized' or 'pending_approval'. Throws POLICY_DENIED if a policy blocks the action.",
+            description: "Step 1 of the Aira two-step flow. Authorize an action BEFORE it executes. Returns an action_uuid with status 'authorized' or 'pending_approval'. Throws POLICY_DENIED if a policy blocks the action.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -59,11 +59,11 @@ function getTools() {
             inputSchema: {
                 type: "object",
                 properties: {
-                    action_id: { type: "string", description: "action_id returned from authorize_action" },
+                    action_uuid: { type: "string", description: "action_uuid returned from authorize_action" },
                     outcome: { type: "string", enum: ["completed", "failed"], description: "Did the action succeed?" },
                     outcome_details: { type: "string", description: "Optional description of the outcome" },
                 },
-                required: ["action_id"],
+                required: ["action_uuid"],
             },
         },
         {
@@ -72,9 +72,9 @@ function getTools() {
             inputSchema: {
                 type: "object",
                 properties: {
-                    action_id: { type: "string", description: "Action UUID" },
+                    action_uuid: { type: "string", description: "Action UUID" },
                 },
-                required: ["action_id"],
+                required: ["action_uuid"],
             },
         },
         {
@@ -83,9 +83,9 @@ function getTools() {
             inputSchema: {
                 type: "object",
                 properties: {
-                    action_id: { type: "string", description: "Action UUID" },
+                    action_uuid: { type: "string", description: "Action UUID" },
                 },
-                required: ["action_id"],
+                required: ["action_uuid"],
             },
         },
         {
@@ -94,9 +94,9 @@ function getTools() {
             inputSchema: {
                 type: "object",
                 properties: {
-                    receipt_id: { type: "string", description: "Receipt UUID" },
+                    receipt_uuid: { type: "string", description: "Receipt UUID" },
                 },
-                required: ["receipt_id"],
+                required: ["receipt_uuid"],
             },
         },
         {
@@ -138,10 +138,10 @@ function getTools() {
             inputSchema: {
                 type: "object",
                 properties: {
-                    action_id: { type: "string", description: "Action UUID to co-sign" },
+                    action_uuid: { type: "string", description: "Action UUID to co-sign" },
                     counterparty_did: { type: "string", description: "DID of the counterparty agent" },
                 },
-                required: ["action_id", "counterparty_did"],
+                required: ["action_uuid", "counterparty_did"],
             },
         },
     ];
@@ -162,22 +162,22 @@ async function handleToolCall(client, name, args) {
         }
         if (name === "notarize_action") {
             const result = await client.notarize({
-                actionId: args.action_id,
+                actionId: args.action_uuid,
                 outcome: args.outcome ?? "completed",
                 outcomeDetails: args.outcome_details,
             });
             return [{ type: "text", text: JSON.stringify(result) }];
         }
         if (name === "get_action") {
-            const result = await client.getAction(args.action_id);
+            const result = await client.getAction(args.action_uuid);
             return [{ type: "text", text: JSON.stringify(result) }];
         }
         if (name === "verify_action") {
-            const result = await client.verifyAction(args.action_id);
+            const result = await client.verifyAction(args.action_uuid);
             return [{ type: "text", text: JSON.stringify(result) }];
         }
         if (name === "get_receipt") {
-            const result = await client.getReceipt(args.receipt_id);
+            const result = await client.getReceipt(args.receipt_uuid);
             return [{ type: "text", text: JSON.stringify(result) }];
         }
         if (name === "resolve_did") {
@@ -194,7 +194,7 @@ async function handleToolCall(client, name, args) {
             return [{ type: "text", text: JSON.stringify(result) }];
         }
         if (name === "request_mutual_sign") {
-            const result = await client.requestMutualSign(args.action_id, args.counterparty_did);
+            const result = await client.requestMutualSign(args.action_uuid, args.counterparty_did);
             return [{ type: "text", text: JSON.stringify(result) }];
         }
         return [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }];

package/dist/extras/openai-agents.d.ts

@@ -49,7 +49,7 @@ export declare class AiraGuardrail {
     /**
      * REAL GATE: call `authorize()` for a tool invocation.
      *
-     * Returns the action_id on success, throws on POLICY_DENIED or
+     * Returns the action_uuid on success, throws on POLICY_DENIED or
      * pending_approval. Arg keys are logged (not values) to avoid leaking
      * sensitive user input into audit trails.
      */

package/dist/extras/openai-agents.js

@@ -56,7 +56,7 @@ class AiraGuardrail {
     /**
      * REAL GATE: call `authorize()` for a tool invocation.
      *
-     * Returns the action_id on success, throws on POLICY_DENIED or
+     * Returns the action_uuid on success, throws on POLICY_DENIED or
      * pending_approval. Arg keys are logged (not values) to avoid leaking
      * sensitive user input into audit trails.
      */
@@ -70,11 +70,11 @@ class AiraGuardrail {
                 modelId: this.modelId,
             });
             if (auth.status === "pending_approval") {
-                const err = new Error(`Aira: tool '${toolName}' is pending human approval (action_id=${auth.action_id}). Tool execution blocked.`);
+                const err = new Error(`Aira: tool '${toolName}' is pending human approval (action_uuid=${auth.action_uuid}). Tool execution blocked.`);
                 err.code = "PENDING_APPROVAL";
                 throw err;
             }
-            return auth.action_id;
+            return auth.action_uuid;
         }
         catch (e) {
             const err = e;

package/dist/extras/vercel-ai.js

@@ -69,7 +69,7 @@ class AiraVercelMiddleware {
                 modelId: this.modelId,
             });
             if (auth.status === "authorized") {
-                await this.client.notarize({ actionId: auth.action_id, outcome: "completed" });
+                await this.client.notarize({ actionId: auth.action_uuid, outcome: "completed" });
             }
             // If pending_approval — just leave it; nothing to execute for audit-only.
         }
@@ -134,11 +134,11 @@ class AiraVercelMiddleware {
                     modelId: self.modelId,
                 });
                 if (auth.status === "pending_approval") {
-                    const err = new Error(`Aira: tool '${toolName}' is pending human approval (action_id=${auth.action_id}). Tool execution blocked.`);
+                    const err = new Error(`Aira: tool '${toolName}' is pending human approval (action_uuid=${auth.action_uuid}). Tool execution blocked.`);
                     err.code = "PENDING_APPROVAL";
                     throw err;
                 }
-                actionId = auth.action_id;
+                actionId = auth.action_uuid;
             }
             catch (e) {
                 const err = e;

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export type { AiraOptions } from "./client";
 export { AiraSession } from "./session";
 export { OfflineQueue } from "./offline";
 export type { QueuedRequest } from "./offline";
-export { AiraError, type Authorization, type ActionReceipt, type ActionDetail, type AgentDetail, type AgentVersion, type CosignResult, type EvidencePackage, type ComplianceSnapshot, type EscrowAccount, type EscrowTransaction, type VerifyResult, type PaginatedList, } from "./types";
+export { AiraError, FRAMEWORK_ANNEX_IV, FRAMEWORK_ART12, FRAMEWORK_ART9, FRAMEWORK_ART6, type Authorization, type ActionReceipt, type ActionDetail, type AgentDetail, type AgentVersion, type CosignResult, type EvidencePackage, type ComplianceSnapshot, type EscrowAccount, type EscrowTransaction, type VerifyResult, type PaginatedList, type ComplianceReport, type ComplianceReportListResponse, type ComplianceReportVerification, type ActionExplanation, type ExplanationEnvelope, type ExplanationVerification, type OutputPolicy, type OutputPolicyUpdate, type OutputScanFlags, type OutputScanHit, } from "./types";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiraError = exports.OfflineQueue = exports.AiraSession = exports.Aira = void 0;
+exports.FRAMEWORK_ART6 = exports.FRAMEWORK_ART9 = exports.FRAMEWORK_ART12 = exports.FRAMEWORK_ANNEX_IV = exports.AiraError = exports.OfflineQueue = exports.AiraSession = exports.Aira = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "Aira", { enumerable: true, get: function () { return client_1.Aira; } });
 var session_1 = require("./session");
@@ -9,3 +9,7 @@ var offline_1 = require("./offline");
 Object.defineProperty(exports, "OfflineQueue", { enumerable: true, get: function () { return offline_1.OfflineQueue; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "AiraError", { enumerable: true, get: function () { return types_1.AiraError; } });
+Object.defineProperty(exports, "FRAMEWORK_ANNEX_IV", { enumerable: true, get: function () { return types_1.FRAMEWORK_ANNEX_IV; } });
+Object.defineProperty(exports, "FRAMEWORK_ART12", { enumerable: true, get: function () { return types_1.FRAMEWORK_ART12; } });
+Object.defineProperty(exports, "FRAMEWORK_ART9", { enumerable: true, get: function () { return types_1.FRAMEWORK_ART9; } });
+Object.defineProperty(exports, "FRAMEWORK_ART6", { enumerable: true, get: function () { return types_1.FRAMEWORK_ART6; } });

package/dist/session.d.ts

@@ -2,7 +2,7 @@
  * AiraSession — scoped session with pre-filled defaults for `authorize()`.
  *
  * Under the two-step flow, only `authorize()` takes agent/model metadata;
- * `notarize()` operates on an existing action_id. This session therefore
+ * `notarize()` operates on an existing action_uuid. This session therefore
  * merges defaults on `authorize()` only and provides a thin passthrough
  * for `notarize()` so callers can use a single object end-to-end.
  */

package/dist/session.js

@@ -3,7 +3,7 @@
  * AiraSession — scoped session with pre-filled defaults for `authorize()`.
  *
  * Under the two-step flow, only `authorize()` takes agent/model metadata;
- * `notarize()` operates on an existing action_id. This session therefore
+ * `notarize()` operates on an existing action_uuid. This session therefore
  * merges defaults on `authorize()` only and provides a thin passthrough
  * for `notarize()` so callers can use a single object end-to-end.
  */

package/dist/types.d.ts

@@ -1,14 +1,24 @@
+/**
+ * Compliance framework identifiers — string values accepted by
+ * `Aira.createComplianceReport()` and returned on `ComplianceReport.framework`.
+ * Import these constants rather than hard-coding the wire strings so
+ * callers stay in lockstep with the backend if a name ever changes.
+ */
+export declare const FRAMEWORK_ART12: "eu_ai_act_art12";
+export declare const FRAMEWORK_ART9: "eu_ai_act_art9";
+export declare const FRAMEWORK_ART6: "eu_ai_act_art6";
+export declare const FRAMEWORK_ANNEX_IV: "eu_ai_act_annex_iv";
 /**
  * Authorization result from `authorize()` — Step 1 of the two-step flow.
  *
  * Status tells you what to do next:
  *  - "authorized"       → execute the action, then call `notarize()`
- *  - "pending_approval" → enqueue the action_id and wait for human approval
+ *  - "pending_approval" → enqueue the action_uuid and wait for human approval
  *
  * POLICY_DENIED is raised as an `AiraError` — not returned as a status.
  */
 export interface Authorization {
-    action_id: string;
+    action_uuid: string;
     status: "authorized" | "pending_approval";
     created_at: string;
     request_id: string;
@@ -21,36 +31,76 @@ export interface Authorization {
  * the receipt fields stay null — only the audit trail is recorded.
  */
 export interface ActionReceipt {
-    action_id: string;
+    action_uuid: string;
     status: "notarized" | "failed";
     created_at: string;
     request_id: string;
-    receipt_id: string | null;
+    receipt_uuid: string | null;
     payload_hash: string | null;
     signature: string | null;
     timestamp_token: string | null;
+    /**
+     * Output content-scan result attached at notarize time when the
+     * org has an output policy enabled. ``null`` when output filtering
+     * is off (global flag or per-org).
+     */
+    output_scan_flags?: OutputScanFlags | null;
     warnings: string[] | null;
 }
+export interface OutputScanHit {
+    name: string;
+    library: string;
+    severity: "info" | "warning" | "critical";
+    description: string;
+    matches: number;
+    /** Always `"[REDACTED]"` — the matched fragment never travels. */
+    sample: string;
+}
+export interface OutputScanFlags {
+    scanned_at: string;
+    libraries: string[];
+    mode: "flag" | "deny" | "redact";
+    decision: "allow" | "require_approval" | "deny";
+    worst_severity: "info" | "warning" | "critical" | null;
+    hits: OutputScanHit[];
+}
+export interface OutputPolicy {
+    enabled: boolean;
+    mode: "flag" | "deny" | "redact";
+    libraries: string[];
+    deny_severity_threshold: "info" | "warning" | "critical";
+    redact_severity_threshold: "info" | "warning" | "critical";
+    request_id: string;
+}
+export interface OutputPolicyUpdate {
+    enabled?: boolean;
+    mode?: "flag" | "deny" | "redact";
+    libraries?: string[];
+    deny_severity_threshold?: "info" | "warning" | "critical";
+    redact_severity_threshold?: "info" | "warning" | "critical";
+}
 /** Full action details including receipt and authorizations. */
 export interface ActionDetail {
-    action_id: string;
+    action_uuid: string;
+    org_uuid: string;
     action_type: string;
     action_details_hash: string;
     agent_id: string | null;
     model_id: string | null;
     instruction_hash: string | null;
-    parent_action_id: string | null;
+    parent_action_uuid: string | null;
     status: string;
     legal_hold: boolean;
     created_at: string;
     receipt: {
-        receipt_id: string;
+        receipt_uuid: string;
         payload_hash: string;
         signature: string;
         public_key_id: string;
         timestamp_token: string | null;
         receipt_version: string;
         verify_url: string;
+        created_at: string | null;
     } | null;
     authorizations: {
         id: string;
@@ -58,6 +108,10 @@ export interface ActionDetail {
         authorized_at: string | null;
     }[];
     request_id: string;
+    system_prompt_hash?: string | null;
+    tool_inputs_hash?: string | null;
+    model_params?: Record<string, unknown> | null;
+    execution_env?: Record<string, unknown> | null;
 }
 /** Registered agent identity. */
 export interface AgentDetail {
@@ -90,7 +144,7 @@ export interface EvidencePackage {
     id: string;
     title: string;
     description: string | null;
-    action_ids: string[];
+    action_uuids: string[];
     package_hash: string;
     signature: string;
     status: string;
@@ -120,7 +174,7 @@ export interface EscrowAccount {
     created_at: string;
     request_id: string;
     agent_id?: string | null;
-    counterparty_org_id?: string | null;
+    counterparty_org_uuid?: string | null;
     purpose?: string | null;
     transactions?: EscrowTransaction[];
 }
@@ -135,7 +189,7 @@ export interface EscrowTransaction {
     status: string;
     created_at: string;
     description?: string | null;
-    reference_action_id?: string | null;
+    reference_action_uuid?: string | null;
 }
 /**
  * Result of a public action receipt verification.
@@ -155,14 +209,19 @@ export interface VerifyResult {
     message: string;
     verified_at: string;
     request_id: string;
-    receipt_id?: string | null;
-    action_id?: string | null;
+    receipt_uuid?: string | null;
+    action_uuid?: string | null;
     payload_hash?: string | null;
     signature?: string | null;
     public_key?: string | null;
     algorithm?: string | null;
     timestamp_token?: string | null;
     signed_payload?: Record<string, unknown> | null;
+    policy_evaluator_attestation?: {
+        evaluator_key_id: string;
+        signature: string;
+        payload_hash: string;
+    } | null;
 }
 /** Paginated list response. */
 export interface PaginatedList<T = Record<string, unknown>> {
@@ -180,8 +239,8 @@ export interface PaginatedList<T = Record<string, unknown>> {
  * (and optionally already notarized).
  */
 export interface CosignResult {
-    cosignature_id: string;
-    action_id: string;
+    cosignature_uuid: string;
+    action_uuid: string;
     cosigner_email: string;
     cosigned_at: string;
     request_id: string;
@@ -198,7 +257,72 @@ export declare class AiraError extends Error {
     statusCode: number;
     /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code: string;
-    /** Optional backend-supplied context (policy_id, action_id, etc.). */
+    /** Optional backend-supplied context (policy_uuid, action_uuid, etc.). */
     details: Record<string, unknown>;
     constructor(statusCode: number, code: string, message: string, details?: Record<string, unknown>);
 }
+export interface ComplianceReport {
+    id: string;
+    framework: string;
+    status: "pending" | "generating" | "ready" | "failed";
+    created_at: string;
+    request_id?: string;
+    org_uuid?: string;
+    period_start?: string | null;
+    period_end?: string | null;
+    action_uuid?: string | null;
+    agent_filter?: string[] | null;
+    receipt_count?: number | null;
+    pdf_size_bytes?: number | null;
+    content_hash?: string | null;
+    signature?: string | null;
+    signing_key_id?: string | null;
+    timestamp_token?: string | null;
+    timestamp_token_present?: boolean;
+    report_metadata?: Record<string, unknown> | null;
+    error_message?: string | null;
+    generated_at?: string | null;
+}
+export interface ComplianceReportListResponse {
+    items: ComplianceReport[];
+    total: number;
+    limit: number;
+    offset: number;
+    request_id: string;
+}
+export interface ComplianceReportVerification {
+    report_uuid: string;
+    valid: boolean;
+    checks: Record<string, unknown>;
+    descriptor?: Record<string, unknown> | null;
+    request_id: string;
+}
+export interface ExplanationEnvelope {
+    alg: string;
+    signing_key_id: string;
+    content_hash: string;
+    signature: string;
+    generated_at: string;
+}
+export interface ActionExplanation {
+    action: Record<string, unknown>;
+    policy_chain: Array<Record<string, unknown>>;
+    approval_chain: Array<Record<string, unknown>>;
+    receipt?: Record<string, unknown> | null;
+    regulation: Record<string, unknown>;
+    /**
+     * Ed25519 signature over the canonical JSON of every field above
+     * (except ``_envelope`` itself and ``request_id``). The on-wire key
+     * is ``_envelope`` — the SDK exposes it under the same name so a
+     * saved ``JSON.stringify(explanation)`` round-trips through
+     * :meth:`Aira.verifyActionExplanation` untouched.
+     */
+    _envelope?: ExplanationEnvelope;
+    request_id: string;
+}
+export interface ExplanationVerification {
+    valid: boolean;
+    checks: Record<string, unknown>;
+    signing_key_id?: string | null;
+    request_id: string;
+}

package/dist/types.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiraError = void 0;
+exports.AiraError = exports.FRAMEWORK_ANNEX_IV = exports.FRAMEWORK_ART6 = exports.FRAMEWORK_ART9 = exports.FRAMEWORK_ART12 = void 0;
+/**
+ * Compliance framework identifiers — string values accepted by
+ * `Aira.createComplianceReport()` and returned on `ComplianceReport.framework`.
+ * Import these constants rather than hard-coding the wire strings so
+ * callers stay in lockstep with the backend if a name ever changes.
+ */
+exports.FRAMEWORK_ART12 = "eu_ai_act_art12";
+exports.FRAMEWORK_ART9 = "eu_ai_act_art9";
+exports.FRAMEWORK_ART6 = "eu_ai_act_art6";
+exports.FRAMEWORK_ANNEX_IV = "eu_ai_act_annex_iv";
 /**
  * Aira API error.
  *
@@ -13,7 +23,7 @@ class AiraError extends Error {
     statusCode;
     /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code;
-    /** Optional backend-supplied context (policy_id, action_id, etc.). */
+    /** Optional backend-supplied context (policy_uuid, action_uuid, etc.). */
     details;
     constructor(statusCode, code, message, details = {}) {
         super(`[${code}] ${message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aira-sdk",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "The authorization and audit layer for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",