aira-sdk 0.4.0 → 2.1.0

package/dist/extras/vercel-ai.d.ts

@@ -1,48 +1,85 @@
 /**
- * Vercel AI SDK integration — middleware that notarizes tool calls and completions.
+ * Vercel AI SDK integration — pre-execution gate via tool wrapping.
  *
  * Requires: ai (Vercel AI SDK, peer dependency)
  *
- * Usage:
- *   import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
- *   const middleware = new AiraVercelMiddleware(aira, "my-agent");
- *   // Use as wrap around tool calls or stream callbacks
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * Vercel AI SDK exposes two integration points:
+ *
+ *   1. `onStepFinish` / `onFinish` callbacks on `generateText` / `streamText`
+ *      — these fire AFTER each step or after the whole generation completes.
+ *      They are post-hoc only; they cannot block a tool from running.
+ *
+ *   2. The per-tool `execute` function (user code) — this runs BEFORE the
+ *      model sees the tool result. Wrapping it is the only place where we
+ *      can synchronously gate execution.
+ *
+ * Therefore the `wrapTool()` method is the real authorization gate: it calls
+ * `aira.authorize()` before invoking the underlying tool and `aira.notarize()`
+ * after. If authorize returns `pending_approval` we throw so the tool does
+ * NOT run; the model will see the tool result as an error and react
+ * accordingly (typically by stopping or asking the user).
+ *
+ * The `onStepFinish` / `onFinish` helpers below are AUDIT-ONLY: they cannot
+ * gate execution (Vercel AI has no pre-step hook), and they run after the
+ * tool has already executed. They produce receipts for the overall
+ * generation as an audit trail, not as an authorization boundary.
  */
 import type { Aira } from "../client";
 import type { TrustPolicy, TrustContext } from "./trust";
 export type { TrustPolicy, TrustContext } from "./trust";
+export interface AiraVercelMiddlewareOptions {
+    modelId?: string;
+    trustPolicy?: TrustPolicy;
+    /** Fail closed if authorize() fails (network, 5xx). Default: false. */
+    strict?: boolean;
+}
 export declare class AiraVercelMiddleware {
     private client;
     private agentId;
     private modelId?;
     private trustPolicy?;
-    constructor(client: Aira, agentId: string, options?: {
-        modelId?: string;
-        trustPolicy?: TrustPolicy;
-    });
+    private strict;
+    constructor(client: Aira, agentId: string, options?: AiraVercelMiddlewareOptions);
     /**
      * Check trust for a counterparty agent before interacting.
      * Advisory by default — only blocks on revoked VC or unregistered agent if configured.
      */
     checkTrust(counterpartyId: string): Promise<TrustContext>;
-    private notarize;
-    /** Call after a tool execution to notarize it. */
-    onToolCall(toolName: string, argKeys?: string[]): void;
-    /** Call after a tool returns to notarize the result. */
-    onToolResult(toolName: string, resultLength: number): void;
-    /** Call when a text generation step completes. */
+    /**
+     * AUDIT-ONLY: log a post-hoc receipt for a generation step.
+     * Vercel AI has no pre-step hook; this cannot gate execution.
+     */
+    private auditFinish;
+    /**
+     * AUDIT-ONLY: called after a step finishes.
+     * Cannot block the step — it has already run.
+     */
     onStepFinish(stepType: string, tokenCount?: number): void;
-    /** Call when the full generation completes. */
+    /**
+     * AUDIT-ONLY: called after full generation finishes.
+     */
     onFinish(finishReason: string, totalTokens?: number): void;
     /**
      * Returns a Vercel AI SDK-compatible callbacks object for streamText/generateText.
+     * These callbacks are AUDIT-ONLY and cannot gate execution.
      *
      * Usage:
      *   const result = await streamText({ ...opts, ...middleware.asCallbacks() });
      */
     asCallbacks(): Record<string, (...args: unknown[]) => void>;
     /**
-     * Wraps a tool's execute function to auto-notarize calls and results.
+     * REAL GATE: wraps a tool's execute function so that:
+     *   1. `aira.authorize()` runs BEFORE the tool — throws on POLICY_DENIED
+     *      or pending_approval, which prevents the tool from executing.
+     *   2. If authorized, the tool runs.
+     *   3. `aira.notarize()` runs AFTER, with outcome "completed" or "failed".
+     *
+     * This is the recommended integration point for Vercel AI because it's
+     * the only place where pre-execution gating is possible.
      */
     wrapTool<T extends (...args: unknown[]) => unknown>(toolFn: T, toolName: string): T;
 }

package/dist/extras/vercel-ai.js

@@ -1,13 +1,33 @@
 "use strict";
 /**
- * Vercel AI SDK integration — middleware that notarizes tool calls and completions.
+ * Vercel AI SDK integration — pre-execution gate via tool wrapping.
  *
  * Requires: ai (Vercel AI SDK, peer dependency)
  *
- * Usage:
- *   import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
- *   const middleware = new AiraVercelMiddleware(aira, "my-agent");
- *   // Use as wrap around tool calls or stream callbacks
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * Vercel AI SDK exposes two integration points:
+ *
+ *   1. `onStepFinish` / `onFinish` callbacks on `generateText` / `streamText`
+ *      — these fire AFTER each step or after the whole generation completes.
+ *      They are post-hoc only; they cannot block a tool from running.
+ *
+ *   2. The per-tool `execute` function (user code) — this runs BEFORE the
+ *      model sees the tool result. Wrapping it is the only place where we
+ *      can synchronously gate execution.
+ *
+ * Therefore the `wrapTool()` method is the real authorization gate: it calls
+ * `aira.authorize()` before invoking the underlying tool and `aira.notarize()`
+ * after. If authorize returns `pending_approval` we throw so the tool does
+ * NOT run; the model will see the tool result as an error and react
+ * accordingly (typically by stopping or asking the user).
+ *
+ * The `onStepFinish` / `onFinish` helpers below are AUDIT-ONLY: they cannot
+ * gate execution (Vercel AI has no pre-step hook), and they run after the
+ * tool has already executed. They produce receipts for the overall
+ * generation as an audit trail, not as an authorization boundary.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiraVercelMiddleware = void 0;
@@ -18,11 +38,13 @@ class AiraVercelMiddleware {
     agentId;
     modelId;
     trustPolicy;
+    strict;
     constructor(client, agentId, options) {
         this.client = client;
         this.agentId = agentId;
         this.modelId = options?.modelId;
         this.trustPolicy = options?.trustPolicy;
+        this.strict = options?.strict ?? false;
     }
     /**
      * Check trust for a counterparty agent before interacting.
@@ -34,41 +56,43 @@ class AiraVercelMiddleware {
         }
         return (0, trust_1.checkTrust)(this.client, this.trustPolicy, counterpartyId);
     }
-    notarize(actionType, details) {
+    /**
+     * AUDIT-ONLY: log a post-hoc receipt for a generation step.
+     * Vercel AI has no pre-step hook; this cannot gate execution.
+     */
+    async auditFinish(actionType, details) {
         try {
-            const params = {
+            const auth = await this.client.authorize({
                 actionType,
                 details: details.slice(0, MAX_DETAILS),
                 agentId: this.agentId,
-            };
-            if (this.modelId)
-                params.modelId = this.modelId;
-            this.client.notarize(params).catch((e) => {
-                console.warn("Aira notarize failed (non-blocking):", e);
+                modelId: this.modelId,
             });
+            if (auth.status === "authorized") {
+                await this.client.notarize({ actionId: auth.action_id, outcome: "completed" });
+            }
+            // If pending_approval — just leave it; nothing to execute for audit-only.
         }
         catch (e) {
-            console.warn("Aira notarize failed (non-blocking):", e);
+            console.warn("Aira audit failed (non-blocking):", e);
         }
     }
-    /** Call after a tool execution to notarize it. */
-    onToolCall(toolName, argKeys = []) {
-        this.notarize("tool_call", `Tool '${toolName}' called. Arg keys: [${argKeys.join(", ")}]`);
-    }
-    /** Call after a tool returns to notarize the result. */
-    onToolResult(toolName, resultLength) {
-        this.notarize("tool_completed", `Tool '${toolName}' completed. Result length: ${resultLength} chars`);
-    }
-    /** Call when a text generation step completes. */
+    /**
+     * AUDIT-ONLY: called after a step finishes.
+     * Cannot block the step — it has already run.
+     */
     onStepFinish(stepType, tokenCount) {
-        this.notarize("step_completed", `Step '${stepType}' completed.${tokenCount != null ? ` Tokens: ${tokenCount}` : ""}`);
+        void this.auditFinish("step_completed", `Step '${stepType}' completed.${tokenCount != null ? ` Tokens: ${tokenCount}` : ""}`);
     }
-    /** Call when the full generation completes. */
+    /**
+     * AUDIT-ONLY: called after full generation finishes.
+     */
     onFinish(finishReason, totalTokens) {
-        this.notarize("generation_completed", `Generation completed. Reason: ${finishReason}.${totalTokens != null ? ` Total tokens: ${totalTokens}` : ""}`);
+        void this.auditFinish("generation_completed", `Generation completed. Reason: ${finishReason}.${totalTokens != null ? ` Total tokens: ${totalTokens}` : ""}`);
     }
     /**
      * Returns a Vercel AI SDK-compatible callbacks object for streamText/generateText.
+     * These callbacks are AUDIT-ONLY and cannot gate execution.
      *
      * Usage:
      *   const result = await streamText({ ...opts, ...middleware.asCallbacks() });
@@ -86,15 +110,65 @@ class AiraVercelMiddleware {
         };
     }
     /**
-     * Wraps a tool's execute function to auto-notarize calls and results.
+     * REAL GATE: wraps a tool's execute function so that:
+     *   1. `aira.authorize()` runs BEFORE the tool — throws on POLICY_DENIED
+     *      or pending_approval, which prevents the tool from executing.
+     *   2. If authorized, the tool runs.
+     *   3. `aira.notarize()` runs AFTER, with outcome "completed" or "failed".
+     *
+     * This is the recommended integration point for Vercel AI because it's
+     * the only place where pre-execution gating is possible.
      */
     wrapTool(toolFn, toolName) {
         const self = this;
         const wrapped = async function (...args) {
-            self.onToolCall(toolName, args.length > 0 && typeof args[0] === "object" && args[0] ? Object.keys(args[0]) : []);
-            const result = await toolFn.apply(this, args);
-            self.onToolResult(toolName, String(result).length);
-            return result;
+            const argKeys = args.length > 0 && typeof args[0] === "object" && args[0]
+                ? Object.keys(args[0])
+                : [];
+            let actionId = null;
+            try {
+                const auth = await self.client.authorize({
+                    actionType: "tool_call",
+                    details: `Tool '${toolName}' called. Arg keys: [${argKeys.join(", ")}]`.slice(0, MAX_DETAILS),
+                    agentId: self.agentId,
+                    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.`);
+                    err.code = "PENDING_APPROVAL";
+                    throw err;
+                }
+                actionId = auth.action_id;
+            }
+            catch (e) {
+                const err = e;
+                if (err.code === "POLICY_DENIED" || err.code === "PENDING_APPROVAL")
+                    throw e;
+                if (self.strict)
+                    throw e;
+                console.warn("Aira authorize failed (fail-open):", err);
+            }
+            try {
+                const result = await toolFn.apply(this, args);
+                if (actionId) {
+                    await self.client.notarize({
+                        actionId,
+                        outcome: "completed",
+                        outcomeDetails: `Tool '${toolName}' completed. Result length: ${String(result).length} chars`.slice(0, MAX_DETAILS),
+                    }).catch((e) => console.warn("Aira notarize failed (non-blocking):", e));
+                }
+                return result;
+            }
+            catch (err) {
+                if (actionId) {
+                    await self.client.notarize({
+                        actionId,
+                        outcome: "failed",
+                        outcomeDetails: `Tool '${toolName}' failed: ${err?.message ?? String(err)}`.slice(0, MAX_DETAILS),
+                    }).catch((e) => console.warn("Aira notarize failed (non-blocking):", e));
+                }
+                throw err;
+            }
         };
         return wrapped;
     }

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 ActionReceipt, type ActionDetail, type AgentDetail, type AgentVersion, type EvidencePackage, type ComplianceSnapshot, type EscrowAccount, type EscrowTransaction, type VerifyResult, type PaginatedList, } from "./types";
+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";

package/dist/session.d.ts

@@ -1,22 +1,33 @@
 /**
- * AiraSession — scoped session with pre-filled defaults.
+ * 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
+ * merges defaults on `authorize()` only and provides a thin passthrough
+ * for `notarize()` so callers can use a single object end-to-end.
  */
 import type { Aira } from "./client";
-import type { ActionReceipt } from "./types";
+import type { Authorization, ActionReceipt } from "./types";
 export declare class AiraSession {
     private client;
     private defaults;
     constructor(client: Aira, agentId: string, defaults?: Record<string, unknown>);
-    notarize(params: {
+    authorize(params: {
         actionType: string;
         details: string;
+        instructionHash?: string;
         modelId?: string;
         modelVersion?: string;
-        instructionHash?: string;
         parentActionId?: string;
+        endpointUrl?: string;
         storeDetails?: boolean;
         idempotencyKey?: string;
         requireApproval?: boolean;
         approvers?: string[];
+    }): Promise<Authorization>;
+    notarize(params: {
+        actionId: string;
+        outcome?: "completed" | "failed";
+        outcomeDetails?: string;
     }): Promise<ActionReceipt>;
 }

package/dist/session.js

@@ -1,6 +1,11 @@
 "use strict";
 /**
- * AiraSession — scoped session with pre-filled defaults.
+ * 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
+ * merges defaults on `authorize()` only and provides a thin passthrough
+ * for `notarize()` so callers can use a single object end-to-end.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiraSession = void 0;
@@ -11,14 +16,17 @@ class AiraSession {
         this.client = client;
         this.defaults = { agentId, ...(defaults ?? {}) };
     }
-    async notarize(params) {
+    async authorize(params) {
         const merged = {
             agentId: this.defaults.agentId,
             ...(this.defaults.modelId ? { modelId: this.defaults.modelId } : {}),
             ...(this.defaults.agentVersion ? { agentVersion: this.defaults.agentVersion } : {}),
             ...params,
         };
-        return this.client.notarize(merged);
+        return this.client.authorize(merged);
+    }
+    async notarize(params) {
+        return this.client.notarize(params);
     }
 }
 exports.AiraSession = AiraSession;

package/dist/types.d.ts

@@ -1,23 +1,35 @@
-/** Cryptographic receipt from notarizing an action. */
+/**
+ * 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
+ *
+ * POLICY_DENIED is raised as an `AiraError` — not returned as a status.
+ */
+export interface Authorization {
+    action_id: string;
+    status: "authorized" | "pending_approval";
+    created_at: string;
+    request_id: string;
+    warnings: string[] | null;
+}
+/**
+ * Cryptographic receipt from notarizing an action — Step 2 of the two-step flow.
+ *
+ * Only populated when `status === "notarized"`. For "failed" outcomes,
+ * the receipt fields stay null — only the audit trail is recorded.
+ */
 export interface ActionReceipt {
     action_id: string;
-    receipt_id: string;
-    payload_hash: string;
-    signature: string;
-    timestamp_token: string | null;
+    status: "notarized" | "failed";
     created_at: string;
     request_id: string;
-    status?: string;
-    action_type?: string;
-    agent_id?: string | null;
-    warnings?: string[] | null;
-    policy_evaluation?: {
-        policy_id: string;
-        policy_name: string;
-        decision: string;
-        reasoning: string | null;
-        confidence: number | null;
-    } | null;
+    receipt_id: string | null;
+    payload_hash: string | null;
+    signature: string | null;
+    timestamp_token: string | null;
+    warnings: string[] | null;
 }
 /** Full action details including receipt and authorizations. */
 export interface ActionDetail {
@@ -71,6 +83,7 @@ export interface AgentVersion {
     changelog: string | null;
     status: string;
     published_at: string | null;
+    created_at: string;
 }
 /** Sealed evidence package. */
 export interface EvidencePackage {
@@ -124,7 +137,18 @@ export interface EscrowTransaction {
     description?: string | null;
     reference_action_id?: string | null;
 }
-/** Public verification result. */
+/**
+ * Result of a public action receipt verification.
+ *
+ * The endpoint actually recomputes the SHA-256 hash and verifies the
+ * Ed25519 signature against the published public key — `valid` is the
+ * result of that real cryptographic check, not just an existence check.
+ *
+ * On a successful (or tamper-detected) verification the result includes
+ * the full evidence — `signature`, `public_key`, `signed_payload`,
+ * `timestamp_token` — so an external auditor can re-run the same check
+ * with OpenSSL or any Ed25519 library without trusting Aira's verdict.
+ */
 export interface VerifyResult {
     valid: boolean;
     public_key_id: string;
@@ -133,6 +157,12 @@ export interface VerifyResult {
     request_id: string;
     receipt_id?: string | null;
     action_id?: 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;
 }
 /** Paginated list response. */
 export interface PaginatedList<T = Record<string, unknown>> {
@@ -142,9 +172,33 @@ export interface PaginatedList<T = Record<string, unknown>> {
     per_page: number;
     has_more: boolean;
 }
-/** Aira API error. */
+/**
+ * Human co-signature on an action.
+ *
+ * Returned by `Aira.cosign()`. Records that a specific human has
+ * acknowledged or signed off on an action that was already authorized
+ * (and optionally already notarized).
+ */
+export interface CosignResult {
+    cosignature_id: string;
+    action_id: string;
+    cosigner_email: string;
+    cosigned_at: string;
+    request_id: string;
+}
+/**
+ * Aira API error.
+ *
+ * There is a single error type — catch `AiraError` and branch on
+ * `e.code` (`"POLICY_DENIED"`, `"INVALID_STATE"`, `"NOT_FOUND"`, ...).
+ * There are no subclasses per error code.
+ */
 export declare class AiraError extends Error {
-    status: number;
+    /** HTTP status code from the backend response. */
+    statusCode: number;
+    /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code: string;
-    constructor(status: number, code: string, message: string);
+    /** Optional backend-supplied context (policy_id, action_id, etc.). */
+    details: Record<string, unknown>;
+    constructor(statusCode: number, code: string, message: string, details?: Record<string, unknown>);
 }

package/dist/types.js

@@ -1,15 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiraError = void 0;
-/** Aira API error. */
+/**
+ * Aira API error.
+ *
+ * There is a single error type — catch `AiraError` and branch on
+ * `e.code` (`"POLICY_DENIED"`, `"INVALID_STATE"`, `"NOT_FOUND"`, ...).
+ * There are no subclasses per error code.
+ */
 class AiraError extends Error {
-    status;
+    /** HTTP status code from the backend response. */
+    statusCode;
+    /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code;
-    constructor(status, code, message) {
+    /** Optional backend-supplied context (policy_id, action_id, etc.). */
+    details;
+    constructor(statusCode, code, message, details = {}) {
         super(`[${code}] ${message}`);
         this.name = "AiraError";
-        this.status = status;
+        this.statusCode = statusCode;
         this.code = code;
+        this.details = details;
     }
 }
 exports.AiraError = AiraError;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aira-sdk",
-  "version": "0.4.0",
-  "description": "TypeScript SDK for Aira — AI governance infrastructure",
+  "version": "2.1.0",
+  "description": "The authorization and audit layer for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {