aira-sdk 0.4.0 → 2.1.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { ActionReceipt, ActionDetail, AgentDetail, AgentVersion, EvidencePackage, ComplianceSnapshot, EscrowAccount, EscrowTransaction, VerifyResult, PaginatedList } from "./types";
+import { Authorization, ActionReceipt, ActionDetail, AgentDetail, AgentVersion, CosignResult, EvidencePackage, ComplianceSnapshot, EscrowAccount, EscrowTransaction, VerifyResult, PaginatedList } from "./types";
 import { AiraSession } from "./session";
 export interface AiraOptions {
     apiKey: string;
@@ -18,19 +18,48 @@ export declare class Aira {
     private put;
     private del;
     private paginated;
-    notarize(params: {
+    /**
+     * Step 1 — Authorize an action BEFORE it executes.
+     *
+     * 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
+     *
+     * If a policy denies the action, this throws `AiraError` with code
+     * `POLICY_DENIED` (HTTP 403). Duplicate idempotent requests throw
+     * `DUPLICATE_REQUEST` (HTTP 409).
+     */
+    authorize(params: {
         actionType: string;
         details: string;
         agentId?: string;
         agentVersion?: string;
+        instructionHash?: string;
         modelId?: string;
         modelVersion?: string;
-        instructionHash?: string;
         parentActionId?: string;
+        endpointUrl?: string;
         storeDetails?: boolean;
         idempotencyKey?: string;
         requireApproval?: boolean;
         approvers?: string[];
+        systemPromptHash?: string;
+        toolInputsHash?: string;
+        modelParams?: Record<string, unknown>;
+        executionEnv?: Record<string, unknown>;
+    }): Promise<Authorization>;
+    /**
+     * Step 2 — Notarize the outcome of an already-authorized action.
+     *
+     * Call this AFTER executing the action. Outcome is "completed" by default;
+     * pass "failed" if the action ran but failed so the audit trail captures
+     * the failure. The returned `ActionReceipt` carries the Ed25519 signature
+     * and RFC 3161 timestamp token when the status is "notarized".
+     */
+    notarize(params: {
+        actionId: string;
+        outcome?: "completed" | "failed";
+        outcomeDetails?: string;
     }): Promise<ActionReceipt>;
     getAction(actionId: string): Promise<ActionDetail>;
     listActions(params?: {
@@ -40,7 +69,17 @@ export declare class Aira {
         agentId?: string;
         status?: string;
     }): Promise<PaginatedList<ActionDetail>>;
-    authorizeAction(actionId: string): Promise<Record<string, unknown>>;
+    /**
+     * Add a human co-signature to an action that already exists.
+     *
+     * This is distinct from the authorization gate (it runs against `/cosign`,
+     * not `/authorize`). It records that a specific human has acknowledged or
+     * signed off on an action that was already authorized and notarized.
+     * Requires JWT auth (dashboard user, not an API key).
+     */
+    cosign(params: {
+        actionId: string;
+    }): Promise<CosignResult>;
     setLegalHold(actionId: string): Promise<Record<string, unknown>>;
     releaseLegalHold(actionId: string): Promise<Record<string, unknown>>;
     getActionChain(actionId: string): Promise<Record<string, unknown>[]>;
@@ -163,6 +202,75 @@ export declare class Aira {
     attestReputation(slug: string, counterpartyDid: string, actionId: string, attestation: string, signature: string): Promise<Record<string, unknown>>;
     /** Verify a reputation score by returning inputs and score_hash. */
     verifyReputation(slug: string): Promise<Record<string, unknown>>;
+    /**
+     * Get all reproducibility metadata stored for an action.
+     *
+     * Returns the system_prompt_hash, tool_inputs_hash, model_params,
+     * execution_env, and other knobs that an external replay tool
+     * needs to confirm it has the same inputs as the original run.
+     */
+    getReplayContext(actionId: string): Promise<Record<string, unknown>>;
+    /**
+     * Seal a regulator-ready evidence bundle for a date range.
+     *
+     * `framework` must be one of: `eu_ai_act_art12`, `iso_42001`,
+     * `aiuc_1`, `soc_2_cc7`, `raw`.
+     */
+    createComplianceBundle(params: {
+        framework: "eu_ai_act_art12" | "iso_42001" | "aiuc_1" | "soc_2_cc7" | "raw";
+        periodStart: string;
+        periodEnd: string;
+        title?: string;
+        agentFilter?: string[];
+        /**
+         * Client-supplied key (unique per org) — retrying with the same key
+         * returns the original bundle and does NOT charge a second operation.
+         * Use this if your job runner may replay the call on network flakes.
+         */
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    listComplianceBundles(page?: number, perPage?: number): Promise<PaginatedList<Record<string, unknown>>>;
+    getComplianceBundle(bundleId: string): Promise<Record<string, unknown>>;
+    /**
+     * Download the self-contained JSON document for the bundle. The
+     * exported document inlines every receipt's signed payload + signature
+     * and the JWKS URL so an auditor can re-verify offline.
+     */
+    exportComplianceBundle(bundleId: string): Promise<Record<string, unknown>>;
+    getBundleInclusionProof(bundleId: string, receiptId: string): Promise<Record<string, unknown>>;
+    /**
+     * Score the agent's recent behavior against its active baseline.
+     * Read-only — does NOT persist an alert. Use this for dashboards.
+     */
+    getDriftStatus(agentId: string, lookbackHours?: number): Promise<Record<string, unknown>>;
+    /** Compute a behavioral baseline from production action history. */
+    computeDriftBaseline(params: {
+        agentId: string;
+        windowStart: string;
+        windowEnd: string;
+        activate?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Seed a baseline from a config dict (for cold-start agents). */
+    seedSyntheticBaseline(params: {
+        agentId: string;
+        expectedDistribution: Record<string, number>;
+        expectedActionsPerDay: number;
+        activate?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Score the current window and persist an alert if it exceeds the threshold. */
+    runDriftCheck(agentId: string, lookbackHours?: number): Promise<Record<string, unknown> | null>;
+    listDriftAlerts(agentId: string, page?: number, acknowledged?: boolean): Promise<PaginatedList<Record<string, unknown>>>;
+    acknowledgeDriftAlert(agentId: string, alertId: string): Promise<Record<string, unknown>>;
+    /**
+     * Seal every unsettled receipt for the org into a new settlement.
+     * Admin-only. Returns the new settlement, or null if there were no
+     * unsettled receipts (no-op).
+     */
+    createSettlement(): Promise<Record<string, unknown> | null>;
+    listSettlements(page?: number, perPage?: number): Promise<PaginatedList<Record<string, unknown>>>;
+    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>>;
     /** 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

@@ -10,7 +10,7 @@ const MAX_DETAILS_LENGTH = 50_000;
 function buildBody(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null));
 }
-function sanitizeDetails(text) {
+function truncateDetails(text) {
     return text.length > MAX_DETAILS_LENGTH ? text.slice(0, MAX_DETAILS_LENGTH) + "...[truncated]" : text;
 }
 class Aira {
@@ -46,7 +46,8 @@ class Aira {
                 return {};
             const data = (await res.json().catch(() => ({ error: res.statusText, code: "UNKNOWN" })));
             if (!res.ok) {
-                throw new types_1.AiraError(res.status, data.code ?? "UNKNOWN", data.error ?? res.statusText);
+                const message = data.message ?? res.statusText;
+                throw new types_1.AiraError(res.status, data.code ?? "UNKNOWN", message, data.details ?? {});
             }
             return data;
         }
@@ -69,33 +70,72 @@ class Aira {
         return this.request("POST", path, body);
     }
     put(path, body) {
+        if (this.queue) {
+            const qid = this.queue.enqueue("PUT", path, body);
+            return Promise.resolve({ _offline: true, _queue_id: qid });
+        }
         return this.request("PUT", path, body);
     }
     del(path) {
+        if (this.queue) {
+            const qid = this.queue.enqueue("DELETE", path, {});
+            return Promise.resolve({ _offline: true, _queue_id: qid });
+        }
         return this.request("DELETE", path);
     }
     paginated(data) {
         const p = data.pagination;
         return { data: data.data, total: p.total, page: p.page, per_page: p.per_page, has_more: p.has_more };
     }
-    // ==================== Actions ====================
-    async notarize(params) {
+    // ==================== Actions (two-step: authorize → notarize) ====================
+    /**
+     * Step 1 — Authorize an action BEFORE it executes.
+     *
+     * 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
+     *
+     * If a policy denies the action, this throws `AiraError` with code
+     * `POLICY_DENIED` (HTTP 403). Duplicate idempotent requests throw
+     * `DUPLICATE_REQUEST` (HTTP 409).
+     */
+    async authorize(params) {
         const body = buildBody({
             action_type: params.actionType,
-            details: sanitizeDetails(params.details),
+            details: truncateDetails(params.details),
             agent_id: params.agentId,
             agent_version: params.agentVersion,
+            instruction_hash: params.instructionHash,
             model_id: params.modelId,
             model_version: params.modelVersion,
-            instruction_hash: params.instructionHash,
             parent_action_id: params.parentActionId,
+            endpoint_url: params.endpointUrl,
             store_details: params.storeDetails || undefined,
             idempotency_key: params.idempotencyKey,
             require_approval: params.requireApproval || undefined,
             approvers: params.approvers,
+            system_prompt_hash: params.systemPromptHash,
+            tool_inputs_hash: params.toolInputsHash,
+            model_params: params.modelParams,
+            execution_env: params.executionEnv,
         });
         return this.post("/actions", body);
     }
+    /**
+     * Step 2 — Notarize the outcome of an already-authorized action.
+     *
+     * Call this AFTER executing the action. Outcome is "completed" by default;
+     * pass "failed" if the action ran but failed so the audit trail captures
+     * the failure. The returned `ActionReceipt` carries the Ed25519 signature
+     * and RFC 3161 timestamp token when the status is "notarized".
+     */
+    async notarize(params) {
+        const body = buildBody({
+            outcome: params.outcome ?? "completed",
+            outcome_details: params.outcomeDetails,
+        });
+        return this.post(`/actions/${params.actionId}/notarize`, body);
+    }
     async getAction(actionId) {
         return this.get(`/actions/${actionId}`);
     }
@@ -105,8 +145,16 @@ class Aira {
         }));
         return this.paginated(data);
     }
-    async authorizeAction(actionId) {
-        return this.post(`/actions/${actionId}/authorize`, {});
+    /**
+     * Add a human co-signature to an action that already exists.
+     *
+     * This is distinct from the authorization gate (it runs against `/cosign`,
+     * not `/authorize`). It records that a specific human has acknowledged or
+     * signed off on an action that was already authorized and notarized.
+     * Requires JWT auth (dashboard user, not an API key).
+     */
+    async cosign(params) {
+        return this.post(`/actions/${params.actionId}/cosign`, {});
     }
     async setLegalHold(actionId) {
         return this.post(`/actions/${actionId}/hold`, {});
@@ -333,6 +381,112 @@ class Aira {
     async verifyReputation(slug) {
         return this.get(`/agents/${slug}/reputation/verify`);
     }
+    // ==================== Replay context (F10) ====================
+    /**
+     * Get all reproducibility metadata stored for an action.
+     *
+     * Returns the system_prompt_hash, tool_inputs_hash, model_params,
+     * execution_env, and other knobs that an external replay tool
+     * needs to confirm it has the same inputs as the original run.
+     */
+    async getReplayContext(actionId) {
+        return this.get(`/actions/${actionId}/replay-context`);
+    }
+    // ==================== Compliance bundles ====================
+    /**
+     * Seal a regulator-ready evidence bundle for a date range.
+     *
+     * `framework` must be one of: `eu_ai_act_art12`, `iso_42001`,
+     * `aiuc_1`, `soc_2_cc7`, `raw`.
+     */
+    async createComplianceBundle(params) {
+        const body = buildBody({
+            framework: params.framework,
+            period_start: params.periodStart,
+            period_end: params.periodEnd,
+            title: params.title,
+            agent_filter: params.agentFilter,
+            idempotency_key: params.idempotencyKey,
+        });
+        return this.post("/compliance/bundles", body);
+    }
+    async listComplianceBundles(page = 1, perPage = 20) {
+        const data = await this.get(`/compliance/bundles?page=${page}&per_page=${perPage}`);
+        return this.paginated(data);
+    }
+    async getComplianceBundle(bundleId) {
+        return this.get(`/compliance/bundles/${bundleId}`);
+    }
+    /**
+     * Download the self-contained JSON document for the bundle. The
+     * exported document inlines every receipt's signed payload + signature
+     * and the JWKS URL so an auditor can re-verify offline.
+     */
+    async exportComplianceBundle(bundleId) {
+        return this.get(`/compliance/bundles/${bundleId}/export`);
+    }
+    async getBundleInclusionProof(bundleId, receiptId) {
+        return this.get(`/compliance/bundles/${bundleId}/inclusion-proof/${receiptId}`);
+    }
+    // ==================== Drift detection ====================
+    /**
+     * Score the agent's recent behavior against its active baseline.
+     * Read-only — does NOT persist an alert. Use this for dashboards.
+     */
+    async getDriftStatus(agentId, lookbackHours = 24) {
+        return this.get(`/agents/${agentId}/drift?lookback_hours=${lookbackHours}`);
+    }
+    /** Compute a behavioral baseline from production action history. */
+    async computeDriftBaseline(params) {
+        return this.post(`/agents/${params.agentId}/drift/baseline`, buildBody({
+            window_start: params.windowStart,
+            window_end: params.windowEnd,
+            activate: params.activate ?? true,
+        }));
+    }
+    /** Seed a baseline from a config dict (for cold-start agents). */
+    async seedSyntheticBaseline(params) {
+        return this.post(`/agents/${params.agentId}/drift/baseline/synthetic`, buildBody({
+            expected_distribution: params.expectedDistribution,
+            expected_actions_per_day: params.expectedActionsPerDay,
+            activate: params.activate ?? true,
+        }));
+    }
+    /** Score the current window and persist an alert if it exceeds the threshold. */
+    async runDriftCheck(agentId, lookbackHours = 24) {
+        return this.post(`/agents/${agentId}/drift/check?lookback_hours=${lookbackHours}`, {});
+    }
+    async listDriftAlerts(agentId, page = 1, acknowledged) {
+        let params = `page=${page}&per_page=50`;
+        if (acknowledged !== undefined) {
+            params += `&acknowledged=${acknowledged}`;
+        }
+        const data = await this.get(`/agents/${agentId}/drift/alerts?${params}`);
+        return this.paginated(data);
+    }
+    async acknowledgeDriftAlert(agentId, alertId) {
+        return this.post(`/agents/${agentId}/drift/alerts/${alertId}/acknowledge`, {});
+    }
+    // ==================== Merkle settlement (F8) ====================
+    /**
+     * Seal every unsettled receipt for the org into a new settlement.
+     * Admin-only. Returns the new settlement, or null if there were no
+     * unsettled receipts (no-op).
+     */
+    async createSettlement() {
+        return this.post("/settlements", {});
+    }
+    async listSettlements(page = 1, perPage = 20) {
+        const data = await this.get(`/settlements?page=${page}&per_page=${perPage}`);
+        return this.paginated(data);
+    }
+    async getSettlement(settlementId) {
+        return this.get(`/settlements/${settlementId}`);
+    }
+    /** Get the Merkle inclusion proof for one receipt in its settlement. */
+    async getSettlementInclusionProof(receiptId) {
+        return this.get(`/settlements/inclusion-proof/${receiptId}`);
+    }
     // ==================== Session ====================
     /** Create a scoped session with pre-filled defaults. */
     session(agentId, defaults) {

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>;
 }