aira-sdk 1.0.0 → 2.4.0

package/dist/extras/index.d.ts

@@ -1,14 +1,30 @@
 /**
  * Aira SDK extras — framework integrations.
  *
- * Each integration is in its own file to avoid importing unnecessary dependencies.
- * Import directly from the subpath:
+ * Each integration is in its own file to avoid importing unnecessary
+ * dependencies. Import directly from the subpath:
  *
  *   import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
  *   import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
  *   import { AiraGuardrail } from "aira-sdk/extras/openai-agents";
  *   import { createServer } from "aira-sdk/extras/mcp";
  *   import { verifySignature, parseEvent } from "aira-sdk/extras/webhooks";
+ *
+ * Every integration is honestly labeled as one of three kinds:
+ *
+ *   "gate"    — intercepts before execution and can deny. authorize()
+ *               runs first; if the policy engine denies, the wrapped
+ *               call never runs.
+ *   "audit"   — runs after execution because the host framework does not
+ *               expose a pre-execution hook that can abort. Aira still
+ *               records a signed receipt; it just cannot prevent the
+ *               action.
+ *   "adapter" — exposes Aira's own API as a tool the host framework can
+ *               call. Neither a gate nor an audit hook over other tools.
+ *
+ * The INTEGRATIONS registry below is the single source of truth — the
+ * README integration matrix is generated from it so the docs cannot
+ * drift from the code.
  */
 export { AiraCallbackHandler } from "./langchain";
 export { AiraVercelMiddleware } from "./vercel-ai";
@@ -19,3 +35,34 @@ export { verifySignature, parseEvent, WebhookEventType } from "./webhooks";
 export type { WebhookEvent, WebhookEventTypeName } from "./webhooks";
 export { checkTrust } from "./trust";
 export type { TrustPolicy, TrustContext } from "./trust";
+export type IntegrationKind = "gate" | "audit" | "adapter";
+export interface IntegrationSpec {
+    /** Human display name. */
+    name: string;
+    /** SDK subpath: aira-sdk/extras/{module}. */
+    module: string;
+    /** Primary exported symbol. */
+    symbol: string;
+    /** Honest classification. */
+    kind: IntegrationKind;
+    /**
+     * True if Aira can intercept and deny BEFORE the underlying call runs.
+     * Must be true for kind=="gate" and false otherwise.
+     */
+    preExecutionGate: boolean;
+    /** What the integration wraps. */
+    surface: string;
+    /** Why this is gate / audit / adapter — surface in docs and tests. */
+    notes: string;
+}
+/**
+ * The single source of truth for the integration matrix. Tests pin this
+ * registry; the README is generated from it. To add a new integration:
+ *
+ *   1. Implement the file under src/extras/
+ *   2. Add an IntegrationSpec entry here
+ *   3. Run `npm test` — failing tests will tell you what to update
+ */
+export declare const INTEGRATIONS: readonly IntegrationSpec[];
+/** Render INTEGRATIONS as a Markdown table for the README. */
+export declare function integrationMatrixMarkdown(): string;

package/dist/extras/index.js

@@ -2,17 +2,34 @@
 /**
  * Aira SDK extras — framework integrations.
  *
- * Each integration is in its own file to avoid importing unnecessary dependencies.
- * Import directly from the subpath:
+ * Each integration is in its own file to avoid importing unnecessary
+ * dependencies. Import directly from the subpath:
  *
  *   import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
  *   import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
  *   import { AiraGuardrail } from "aira-sdk/extras/openai-agents";
  *   import { createServer } from "aira-sdk/extras/mcp";
  *   import { verifySignature, parseEvent } from "aira-sdk/extras/webhooks";
+ *
+ * Every integration is honestly labeled as one of three kinds:
+ *
+ *   "gate"    — intercepts before execution and can deny. authorize()
+ *               runs first; if the policy engine denies, the wrapped
+ *               call never runs.
+ *   "audit"   — runs after execution because the host framework does not
+ *               expose a pre-execution hook that can abort. Aira still
+ *               records a signed receipt; it just cannot prevent the
+ *               action.
+ *   "adapter" — exposes Aira's own API as a tool the host framework can
+ *               call. Neither a gate nor an audit hook over other tools.
+ *
+ * The INTEGRATIONS registry below is the single source of truth — the
+ * README integration matrix is generated from it so the docs cannot
+ * drift from the code.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkTrust = exports.WebhookEventType = exports.parseEvent = exports.verifySignature = exports.handleToolCall = exports.getTools = exports.createServer = exports.AiraGuardrail = exports.AiraVercelMiddleware = exports.AiraCallbackHandler = void 0;
+exports.INTEGRATIONS = exports.checkTrust = exports.WebhookEventType = exports.parseEvent = exports.verifySignature = exports.handleToolCall = exports.getTools = exports.createServer = exports.AiraGuardrail = exports.AiraVercelMiddleware = exports.AiraCallbackHandler = void 0;
+exports.integrationMatrixMarkdown = integrationMatrixMarkdown;
 var langchain_1 = require("./langchain");
 Object.defineProperty(exports, "AiraCallbackHandler", { enumerable: true, get: function () { return langchain_1.AiraCallbackHandler; } });
 var vercel_ai_1 = require("./vercel-ai");
@@ -29,3 +46,73 @@ Object.defineProperty(exports, "parseEvent", { enumerable: true, get: function (
 Object.defineProperty(exports, "WebhookEventType", { enumerable: true, get: function () { return webhooks_1.WebhookEventType; } });
 var trust_1 = require("./trust");
 Object.defineProperty(exports, "checkTrust", { enumerable: true, get: function () { return trust_1.checkTrust; } });
+/**
+ * The single source of truth for the integration matrix. Tests pin this
+ * registry; the README is generated from it. To add a new integration:
+ *
+ *   1. Implement the file under src/extras/
+ *   2. Add an IntegrationSpec entry here
+ *   3. Run `npm test` — failing tests will tell you what to update
+ */
+exports.INTEGRATIONS = [
+    {
+        name: "LangChain.js",
+        module: "langchain",
+        symbol: "AiraCallbackHandler",
+        kind: "gate",
+        preExecutionGate: true,
+        surface: "Tools (gate). Chains and LLM completions are audit-only.",
+        notes: "handleToolStart calls authorize() and throws on POLICY_DENIED so the " +
+            "tool never runs. Chain/LLM hooks are post-hoc because LangChain has " +
+            "no pre-execution chain hook that can abort.",
+    },
+    {
+        name: "Vercel AI SDK",
+        module: "vercel-ai",
+        symbol: "AiraVercelMiddleware",
+        kind: "gate",
+        preExecutionGate: true,
+        surface: "Tools via wrapTool() (gate). onFinish helpers are audit-only.",
+        notes: "wrapTool() wraps a tool's execute function so authorize() runs " +
+            "before the tool body. onStepFinish / onFinish callbacks fire after " +
+            "execution and are explicitly labeled audit-only — Vercel AI has no " +
+            "pre-step hook.",
+    },
+    {
+        name: "OpenAI Agents",
+        module: "openai-agents",
+        symbol: "AiraGuardrail",
+        kind: "gate",
+        preExecutionGate: true,
+        surface: "Tools via wrapTool()",
+        notes: "Wraps each tool function: authorize() runs before the tool body. " +
+            "Denied calls throw; failed calls notarize with outcome=failed.",
+    },
+    {
+        name: "MCP",
+        module: "mcp",
+        symbol: "createServer",
+        kind: "adapter",
+        preExecutionGate: false,
+        surface: "Server adapter (exposes Aira as MCP tools)",
+        notes: "MCP is bidirectional: the agent CHOOSES to call authorize_action / " +
+            "notarize_action. This is not a wrapper over other MCP tools — it is " +
+            "a protocol adapter that lets MCP-aware agents reach Aira.",
+    },
+    {
+        name: "Webhooks",
+        module: "webhooks",
+        symbol: "verifySignature",
+        kind: "adapter",
+        preExecutionGate: false,
+        surface: "HMAC-SHA256 webhook signature verifier",
+        notes: "Standalone HMAC verification helper. Not an agent integration.",
+    },
+];
+/** Render INTEGRATIONS as a Markdown table for the README. */
+function integrationMatrixMarkdown() {
+    const header = "| Integration | Type | Pre-execution gate? | Surface | Notes |\n" +
+        "|---|---|---|---|---|";
+    const rows = exports.INTEGRATIONS.map((i) => `| **${i.name}** | ${i.kind} | ${i.preExecutionGate ? "Yes" : "No"} | ${i.surface} | ${i.notes} |`);
+    return [header, ...rows].join("\n");
+}

package/dist/extras/langchain.d.ts

@@ -1,42 +1,93 @@
 /**
- * LangChain.js integration — auto-notarize tool and chain completions.
+ * LangChain.js integration — pre-execution gate + post-execution notarize.
  *
  * Requires: @langchain/core (peer dependency)
  *
- * Usage:
- *   import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
- *   const handler = new AiraCallbackHandler(aira, "my-agent");
- *   const chain = someChain.withConfig({ callbacks: [handler] });
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * LangChain fires callbacks BEFORE and AFTER each tool/chain/LLM step. The
+ * `handleToolStart` / `handleChainStart` / `handleLLMStart` callbacks are
+ * genuine pre-execution hooks: if one throws, LangChain propagates the error
+ * and the tool is never executed. That means `handleToolStart` can serve as
+ * a real authorization gate — not merely an audit hook.
+ *
+ * This handler implements the two-step flow as follows:
+ *
+ *   1. handleToolStart  → aira.authorize()
+ *       - If the backend returns "authorized" we cache the action_id
+ *         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).
+ *       - If the backend returns "pending_approval" we throw an error
+ *         so the tool does NOT execute until a human approves.
+ *
+ *   2. handleToolEnd / handleToolError → aira.notarize()
+ *       - Notarize the outcome as "completed" or "failed". This closes
+ *         the two-step flow and produces a cryptographic receipt.
+ *
+ * The same pattern applies to chains and LLM calls. For chains and LLMs we
+ * use "chain_run" / "llm_run" as action types so you can filter by them.
+ *
+ * If the integration cannot reach Aira at authorize time, it fails open with
+ * a console warning — your agent keeps running, but no receipt is produced.
+ * To make it fail closed, set `strict: true` in the options.
  */
 import type { Aira } from "../client";
 import type { TrustPolicy, TrustContext } from "./trust";
 export type { TrustPolicy, TrustContext } from "./trust";
+export interface AiraCallbackHandlerOptions {
+    modelId?: string;
+    actionTypes?: Record<string, string>;
+    trustPolicy?: TrustPolicy;
+    /** Fail closed if authorize() fails (network, 5xx). Default: false. */
+    strict?: boolean;
+}
 export declare class AiraCallbackHandler {
     private client;
     private agentId;
     private modelId?;
     private actionTypes;
     private trustPolicy?;
-    constructor(client: Aira, agentId: string, options?: {
-        modelId?: string;
-        actionTypes?: Record<string, string>;
-        trustPolicy?: TrustPolicy;
-    });
+    private strict;
+    /** runId → action_id cache so handleEnd can notarize the right action. */
+    private inFlight;
+    constructor(client: Aira, agentId: string, options?: AiraCallbackHandlerOptions);
     /**
      * 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;
-    /** Called when a tool finishes. */
-    handleToolEnd(output: string, name?: string): void;
-    /** Called when a chain finishes. */
-    handleChainEnd(outputs: Record<string, unknown>): void;
-    /** Called when an LLM finishes. */
-    handleLLMEnd(generationCount: number): void;
+    private doAuthorize;
+    private doNotarize;
+    /** Called BEFORE a tool runs — authorization gate. */
+    handleToolStart(tool: {
+        name?: string;
+    } | string | unknown, input: string, runId: string): Promise<void>;
+    /** Called AFTER a tool completes successfully. */
+    handleToolEnd(output: string, runId: string, name?: string): Promise<void>;
+    /** Called if a tool throws. */
+    handleToolError(err: Error, runId: string, name?: string): Promise<void>;
+    /** Called BEFORE a chain runs. */
+    handleChainStart(chain: {
+        name?: string;
+    } | unknown, inputs: Record<string, unknown>, runId: string): Promise<void>;
+    /** Called AFTER a chain completes. */
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
+    /** Called if a chain throws. */
+    handleChainError(err: Error, runId: string): Promise<void>;
+    /** Called BEFORE an LLM runs. */
+    handleLLMStart(llm: unknown, prompts: string[], runId: string): Promise<void>;
+    /** Called AFTER an LLM completes. */
+    handleLLMEnd(response: {
+        generations?: unknown[];
+    } | number, runId: string): Promise<void>;
+    /** Called if an LLM throws. */
+    handleLLMError(err: Error, runId: string): Promise<void>;
     /**
      * Returns a LangChain-compatible callbacks object.
      * Use with: chain.invoke(input, { callbacks: [handler.asCallbacks()] })
      */
-    asCallbacks(): Record<string, (...args: unknown[]) => void>;
+    asCallbacks(): Record<string, (...args: unknown[]) => Promise<void> | void>;
 }

package/dist/extras/langchain.js

@@ -1,13 +1,39 @@
 "use strict";
 /**
- * LangChain.js integration — auto-notarize tool and chain completions.
+ * LangChain.js integration — pre-execution gate + post-execution notarize.
  *
  * Requires: @langchain/core (peer dependency)
  *
- * Usage:
- *   import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
- *   const handler = new AiraCallbackHandler(aira, "my-agent");
- *   const chain = someChain.withConfig({ callbacks: [handler] });
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * LangChain fires callbacks BEFORE and AFTER each tool/chain/LLM step. The
+ * `handleToolStart` / `handleChainStart` / `handleLLMStart` callbacks are
+ * genuine pre-execution hooks: if one throws, LangChain propagates the error
+ * and the tool is never executed. That means `handleToolStart` can serve as
+ * a real authorization gate — not merely an audit hook.
+ *
+ * This handler implements the two-step flow as follows:
+ *
+ *   1. handleToolStart  → aira.authorize()
+ *       - If the backend returns "authorized" we cache the action_id
+ *         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).
+ *       - If the backend returns "pending_approval" we throw an error
+ *         so the tool does NOT execute until a human approves.
+ *
+ *   2. handleToolEnd / handleToolError → aira.notarize()
+ *       - Notarize the outcome as "completed" or "failed". This closes
+ *         the two-step flow and produces a cryptographic receipt.
+ *
+ * The same pattern applies to chains and LLM calls. For chains and LLMs we
+ * use "chain_run" / "llm_run" as action types so you can filter by them.
+ *
+ * If the integration cannot reach Aira at authorize time, it fails open with
+ * a console warning — your agent keeps running, but no receipt is produced.
+ * To make it fail closed, set `strict: true` in the options.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiraCallbackHandler = void 0;
@@ -19,15 +45,19 @@ class AiraCallbackHandler {
     modelId;
     actionTypes;
     trustPolicy;
+    strict;
+    /** runId → action_id cache so handleEnd can notarize the right action. */
+    inFlight = new Map();
     constructor(client, agentId, options) {
         this.client = client;
         this.agentId = agentId;
         this.modelId = options?.modelId;
         this.trustPolicy = options?.trustPolicy;
+        this.strict = options?.strict ?? false;
         this.actionTypes = {
-            tool_end: "tool_call",
-            chain_end: "chain_completed",
-            llm_end: "llm_completion",
+            tool: "tool_call",
+            chain: "chain_run",
+            llm: "llm_run",
             ...(options?.actionTypes ?? {}),
         };
     }
@@ -41,35 +71,88 @@ class AiraCallbackHandler {
         }
         return (0, trust_1.checkTrust)(this.client, this.trustPolicy, counterpartyId);
     }
-    notarize(actionType, details) {
+    async doAuthorize(actionType, details, runId) {
         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 === "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.`);
+                err.code = "PENDING_APPROVAL";
+                throw err;
+            }
+            this.inFlight.set(runId, auth.action_id);
+        }
+        catch (e) {
+            const err = e;
+            // Always propagate authorization-layer rejections.
+            if (err.code === "POLICY_DENIED" || err.code === "PENDING_APPROVAL")
+                throw e;
+            if (this.strict)
+                throw e;
+            console.warn("Aira authorize failed (fail-open):", err);
+        }
+    }
+    async doNotarize(runId, outcome, details) {
+        const actionId = this.inFlight.get(runId);
+        if (!actionId)
+            return;
+        this.inFlight.delete(runId);
+        try {
+            await this.client.notarize({
+                actionId,
+                outcome,
+                outcomeDetails: details.slice(0, MAX_DETAILS),
             });
         }
         catch (e) {
             console.warn("Aira notarize failed (non-blocking):", e);
         }
     }
-    /** Called when a tool finishes. */
-    handleToolEnd(output, name = "unknown") {
-        this.notarize(this.actionTypes.tool_end, `Tool '${name}' completed. Output length: ${String(output).length} chars`);
+    /** Called BEFORE a tool runs — authorization gate. */
+    async handleToolStart(tool, input, runId) {
+        const name = typeof tool === "string" ? tool : tool?.name ?? "unknown";
+        await this.doAuthorize(this.actionTypes.tool, `Tool '${name}' invoked. Input length: ${String(input).length} chars`, runId);
+    }
+    /** Called AFTER a tool completes successfully. */
+    async handleToolEnd(output, runId, name = "unknown") {
+        await this.doNotarize(runId, "completed", `Tool '${name}' completed. Output length: ${String(output).length} chars`);
+    }
+    /** Called if a tool throws. */
+    async handleToolError(err, runId, name = "unknown") {
+        await this.doNotarize(runId, "failed", `Tool '${name}' failed: ${err?.message ?? String(err)}`);
+    }
+    /** Called BEFORE a chain runs. */
+    async handleChainStart(chain, inputs, runId) {
+        const name = chain?.name ?? "chain";
+        const keys = typeof inputs === "object" && inputs ? Object.keys(inputs) : [];
+        await this.doAuthorize(this.actionTypes.chain, `Chain '${name}' started. Input keys: [${keys.join(", ")}]`, runId);
     }
-    /** Called when a chain finishes. */
-    handleChainEnd(outputs) {
+    /** Called AFTER a chain completes. */
+    async handleChainEnd(outputs, runId) {
         const keys = typeof outputs === "object" && outputs ? Object.keys(outputs) : [];
-        this.notarize(this.actionTypes.chain_end, `Chain completed. Output keys: [${keys.join(", ")}]`);
+        await this.doNotarize(runId, "completed", `Chain completed. Output keys: [${keys.join(", ")}]`);
     }
-    /** Called when an LLM finishes. */
-    handleLLMEnd(generationCount) {
-        this.notarize(this.actionTypes.llm_end, `LLM completed. Generations: ${generationCount}`);
+    /** Called if a chain throws. */
+    async handleChainError(err, runId) {
+        await this.doNotarize(runId, "failed", `Chain failed: ${err?.message ?? String(err)}`);
+    }
+    /** Called BEFORE an LLM runs. */
+    async handleLLMStart(llm, prompts, runId) {
+        await this.doAuthorize(this.actionTypes.llm, `LLM called with ${prompts?.length ?? 0} prompt(s)`, runId);
+    }
+    /** Called AFTER an LLM completes. */
+    async handleLLMEnd(response, runId) {
+        const count = typeof response === "number" ? response : response?.generations?.length ?? 0;
+        await this.doNotarize(runId, "completed", `LLM completed. Generations: ${count}`);
+    }
+    /** Called if an LLM throws. */
+    async handleLLMError(err, runId) {
+        await this.doNotarize(runId, "failed", `LLM failed: ${err?.message ?? String(err)}`);
     }
     /**
      * Returns a LangChain-compatible callbacks object.
@@ -77,18 +160,18 @@ class AiraCallbackHandler {
      */
     asCallbacks() {
         return {
-            handleToolEnd: (output, ...args) => {
-                const runId = args[1];
-                const name = args[2]?.name ?? "unknown";
-                this.handleToolEnd(String(output), name);
-            },
-            handleChainEnd: (outputs) => {
-                this.handleChainEnd((outputs ?? {}));
-            },
-            handleLLMEnd: (response) => {
-                const resp = response;
-                this.handleLLMEnd(resp?.generations?.length ?? 0);
+            handleToolStart: (tool, input, runId) => this.handleToolStart(tool, String(input ?? ""), String(runId ?? "")),
+            handleToolEnd: (output, runId, ...rest) => {
+                const meta = rest[1];
+                return this.handleToolEnd(String(output), String(runId ?? ""), meta?.name ?? "unknown");
             },
+            handleToolError: (err, runId) => this.handleToolError(err, String(runId ?? "")),
+            handleChainStart: (chain, inputs, runId) => this.handleChainStart(chain, (inputs ?? {}), String(runId ?? "")),
+            handleChainEnd: (outputs, runId) => this.handleChainEnd((outputs ?? {}), String(runId ?? "")),
+            handleChainError: (err, runId) => this.handleChainError(err, String(runId ?? "")),
+            handleLLMStart: (llm, prompts, runId) => this.handleLLMStart(llm, prompts ?? [], String(runId ?? "")),
+            handleLLMEnd: (response, runId) => this.handleLLMEnd(response, String(runId ?? "")),
+            handleLLMError: (err, runId) => this.handleLLMError(err, String(runId ?? "")),
         };
     }
 }

package/dist/extras/mcp.d.ts

@@ -3,9 +3,30 @@
  *
  * Requires: @modelcontextprotocol/sdk (peer dependency)
  *
- * Usage:
- *   import { createServer } from "aira-sdk/extras/mcp";
- *   const server = createServer({ apiKey: "aira_live_xxx" });
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * MCP is a bidirectional protocol: the host (an AI agent) connects to this
+ * server and calls the tools explicitly. There is no "wrap" moment — the
+ * agent *chooses* to invoke `authorize_action` before performing the side
+ * effect and `notarize_action` after. There is no hidden hook point.
+ *
+ * That makes this integration AUDIT-ONLY in the sense that we don't own the
+ * execution boundary: we can only do what the caller asks us to do. But the
+ * exposed tools faithfully implement the two-step flow, so an MCP client
+ * that follows the contract gets the full authorization gate.
+ *
+ * Exposed tools:
+ *   - authorize_action   → POST /api/v1/actions
+ *   - notarize_action    → POST /api/v1/actions/{id}/notarize
+ *   - get_action         → GET  /api/v1/actions/{id}
+ *   - verify_action      → GET  /api/v1/verify/action/{id}
+ *   - get_receipt        → GET  /api/v1/receipts/{id}
+ *   - resolve_did        → POST /api/v1/dids/resolve
+ *   - verify_credential  → POST /api/v1/credentials/verify (via agent slug)
+ *   - get_reputation     → GET  /api/v1/agents/{slug}/reputation
+ *   - request_mutual_sign → POST /api/v1/actions/{id}/mutual-sign/request
  */
 import type { Aira } from "../client";
 /** Tool definition for MCP list_tools response. */

package/dist/extras/mcp.js

@@ -4,9 +4,30 @@
  *
  * Requires: @modelcontextprotocol/sdk (peer dependency)
  *
- * Usage:
- *   import { createServer } from "aira-sdk/extras/mcp";
- *   const server = createServer({ apiKey: "aira_live_xxx" });
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * MCP is a bidirectional protocol: the host (an AI agent) connects to this
+ * server and calls the tools explicitly. There is no "wrap" moment — the
+ * agent *chooses* to invoke `authorize_action` before performing the side
+ * effect and `notarize_action` after. There is no hidden hook point.
+ *
+ * That makes this integration AUDIT-ONLY in the sense that we don't own the
+ * execution boundary: we can only do what the caller asks us to do. But the
+ * exposed tools faithfully implement the two-step flow, so an MCP client
+ * that follows the contract gets the full authorization gate.
+ *
+ * Exposed tools:
+ *   - authorize_action   → POST /api/v1/actions
+ *   - notarize_action    → POST /api/v1/actions/{id}/notarize
+ *   - get_action         → GET  /api/v1/actions/{id}
+ *   - verify_action      → GET  /api/v1/verify/action/{id}
+ *   - get_receipt        → GET  /api/v1/receipts/{id}
+ *   - resolve_did        → POST /api/v1/dids/resolve
+ *   - verify_credential  → POST /api/v1/credentials/verify (via agent slug)
+ *   - get_reputation     → GET  /api/v1/agents/{slug}/reputation
+ *   - request_mutual_sign → POST /api/v1/actions/{id}/mutual-sign/request
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getTools = getTools;
@@ -17,19 +38,45 @@ const types_1 = require("../types");
 function getTools() {
     return [
         {
-            name: "notarize_action",
-            description: "Notarize an AI agent action with a cryptographic receipt",
+            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.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    action_type: { type: "string", description: "e.g. email_sent, loan_approved, claim_processed" },
-                    details: { type: "string", description: "What happened" },
+                    action_type: { type: "string", description: "e.g. email_sent, loan_approved, wire_transfer" },
+                    details: { type: "string", description: "What the agent is about to do" },
                     agent_id: { type: "string", description: "Agent slug" },
                     model_id: { type: "string", description: "Model used (optional)" },
+                    require_approval: { type: "boolean", description: "Force human approval (optional)" },
+                    approvers: { type: "array", items: { type: "string" }, description: "Approver emails (optional)" },
                 },
                 required: ["action_type", "details"],
             },
         },
+        {
+            name: "notarize_action",
+            description: "Step 2 of the Aira two-step flow. Notarize the outcome of an already-authorized action. Call this AFTER the action has been executed. Returns a cryptographic receipt when outcome is 'completed'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    action_id: { type: "string", description: "action_id 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"],
+            },
+        },
+        {
+            name: "get_action",
+            description: "Retrieve full details of an action including its receipt and authorizations",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    action_id: { type: "string", description: "Action UUID" },
+                },
+                required: ["action_id"],
+            },
+        },
         {
             name: "verify_action",
             description: "Verify a notarized action's cryptographic receipt",
@@ -102,15 +149,29 @@ function getTools() {
 /** Handle an MCP tool call and return text content. */
 async function handleToolCall(client, name, args) {
     try {
-        if (name === "notarize_action") {
-            const result = await client.notarize({
+        if (name === "authorize_action") {
+            const result = await client.authorize({
                 actionType: args.action_type,
                 details: args.details,
                 agentId: args.agent_id,
                 modelId: args.model_id,
+                requireApproval: args.require_approval,
+                approvers: args.approvers,
+            });
+            return [{ type: "text", text: JSON.stringify(result) }];
+        }
+        if (name === "notarize_action") {
+            const result = await client.notarize({
+                actionId: args.action_id,
+                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);
+            return [{ type: "text", text: JSON.stringify(result) }];
+        }
         if (name === "verify_action") {
             const result = await client.verifyAction(args.action_id);
             return [{ type: "text", text: JSON.stringify(result) }];