aira-sdk 1.0.0 → 2.1.0

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

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

@@ -1,37 +1,69 @@
 /**
- * OpenAI Node SDK integration — guardrail that notarizes tool calls.
+ * OpenAI Agents SDK integration — pre-execution gate via tool wrapping.
  *
- * Requires: openai (peer dependency)
+ * Requires: @openai/agents (peer dependency)
  *
- * Usage:
- *   import { AiraGuardrail } from "aira-sdk/extras/openai-agents";
- *   const guardrail = new AiraGuardrail(aira, "my-agent");
- *   guardrail.onToolCall("search", { query: "test" });
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * The OpenAI Agents SDK supports guardrails that run BEFORE the model produces
+ * output (`inputGuardrails`) and BEFORE a tool executes (via wrapping the
+ * tool's `execute` / function). Either path can throw to abort the run, so
+ * both qualify as a REAL authorization gate.
+ *
+ * `AiraGuardrail.wrapTool()` is the cleanest integration: it calls
+ * `aira.authorize()` before the tool runs. If the backend responds with:
+ *
+ *   - "authorized"         → the tool runs; `aira.notarize()` is called
+ *                            with outcome="completed" (or "failed" on throw).
+ *   - "pending_approval"   → we throw. The agent never sees the tool result;
+ *                            it handles the error like any other tool failure.
+ *   - AiraError POLICY_DENIED → rethrown. Tool is blocked entirely.
+ *
+ * Behavior on authorize network/5xx errors is controlled by `strict`:
+ *   - strict=false (default) → fail open with a warning. Tool runs, no receipt.
+ *   - strict=true            → fail closed. Tool throws.
  */
 import type { Aira } from "../client";
 import type { TrustPolicy, TrustContext } from "./trust";
 export type { TrustPolicy, TrustContext } from "./trust";
+export interface AiraGuardrailOptions {
+    modelId?: string;
+    trustPolicy?: TrustPolicy;
+    /** Fail closed if authorize() fails (network, 5xx). Default: false. */
+    strict?: boolean;
+}
 export declare class AiraGuardrail {
     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?: AiraGuardrailOptions);
     /**
      * 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, args?: Record<string, unknown>): void;
-    /** Call after a tool returns to notarize the result. */
-    onToolResult(toolName: string, result?: unknown): void;
     /**
-     * Wraps a tool function to auto-notarize calls and results.
+     * REAL GATE: call `authorize()` for a tool invocation.
+     *
+     * Returns the action_id on success, throws on POLICY_DENIED or
+     * pending_approval. Arg keys are logged (not values) to avoid leaking
+     * sensitive user input into audit trails.
+     */
+    authorizeToolCall(toolName: string, args?: Record<string, unknown>): Promise<string | null>;
+    /** Notarize the outcome of a previously authorized tool call. */
+    notarizeToolResult(actionId: string, toolName: string, outcome: "completed" | "failed", detail: string): Promise<void>;
+    /**
+     * REAL GATE: wraps a tool function to gate + notarize.
+     *
+     * Flow:
+     *   1. Call `aira.authorize()` — throws POLICY_DENIED or pending_approval.
+     *   2. Run the tool.
+     *   3. Call `aira.notarize()` with outcome="completed" or "failed".
+     *
      * No raw user data is sent — only tool name, arg keys, and output length.
      */
     wrapTool<T extends (...args: unknown[]) => unknown>(toolFn: T, toolName?: string): T;

package/dist/extras/openai-agents.js

@@ -1,13 +1,30 @@
 "use strict";
 /**
- * OpenAI Node SDK integration — guardrail that notarizes tool calls.
+ * OpenAI Agents SDK integration — pre-execution gate via tool wrapping.
  *
- * Requires: openai (peer dependency)
+ * Requires: @openai/agents (peer dependency)
  *
- * Usage:
- *   import { AiraGuardrail } from "aira-sdk/extras/openai-agents";
- *   const guardrail = new AiraGuardrail(aira, "my-agent");
- *   guardrail.onToolCall("search", { query: "test" });
+ * ---------------------------------------------------------------------------
+ * LIFECYCLE & DESIGN NOTES
+ * ---------------------------------------------------------------------------
+ *
+ * The OpenAI Agents SDK supports guardrails that run BEFORE the model produces
+ * output (`inputGuardrails`) and BEFORE a tool executes (via wrapping the
+ * tool's `execute` / function). Either path can throw to abort the run, so
+ * both qualify as a REAL authorization gate.
+ *
+ * `AiraGuardrail.wrapTool()` is the cleanest integration: it calls
+ * `aira.authorize()` before the tool runs. If the backend responds with:
+ *
+ *   - "authorized"         → the tool runs; `aira.notarize()` is called
+ *                            with outcome="completed" (or "failed" on throw).
+ *   - "pending_approval"   → we throw. The agent never sees the tool result;
+ *                            it handles the error like any other tool failure.
+ *   - AiraError POLICY_DENIED → rethrown. Tool is blocked entirely.
+ *
+ * Behavior on authorize network/5xx errors is controlled by `strict`:
+ *   - strict=false (default) → fail open with a warning. Tool runs, no receipt.
+ *   - strict=true            → fail closed. Tool throws.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiraGuardrail = void 0;
@@ -18,11 +35,13 @@ class AiraGuardrail {
     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,34 +53,61 @@ class AiraGuardrail {
         }
         return (0, trust_1.checkTrust)(this.client, this.trustPolicy, counterpartyId);
     }
-    notarize(actionType, details) {
+    /**
+     * REAL GATE: call `authorize()` for a tool invocation.
+     *
+     * Returns the action_id on success, throws on POLICY_DENIED or
+     * pending_approval. Arg keys are logged (not values) to avoid leaking
+     * sensitive user input into audit trails.
+     */
+    async authorizeToolCall(toolName, args) {
+        const argKeys = Object.keys(args ?? {});
         try {
-            const params = {
-                actionType,
-                details: details.slice(0, MAX_DETAILS),
+            const auth = await this.client.authorize({
+                actionType: "tool_call",
+                details: `Tool '${toolName}' called. Arg keys: [${argKeys.join(", ")}]`.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") {
+                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;
+            }
+            return auth.action_id;
         }
         catch (e) {
-            console.warn("Aira notarize failed (non-blocking):", 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);
+            return null;
         }
     }
-    /** Call after a tool execution to notarize it. */
-    onToolCall(toolName, args) {
-        const argKeys = Object.keys(args ?? {});
-        this.notarize("tool_call", `Tool '${toolName}' called. Arg keys: [${argKeys.join(", ")}]`);
-    }
-    /** Call after a tool returns to notarize the result. */
-    onToolResult(toolName, result) {
-        this.notarize("tool_completed", `Tool '${toolName}' completed. Result length: ${String(result).length} chars`);
+    /** Notarize the outcome of a previously authorized tool call. */
+    async notarizeToolResult(actionId, toolName, outcome, detail) {
+        try {
+            await this.client.notarize({
+                actionId,
+                outcome,
+                outcomeDetails: `Tool '${toolName}' ${outcome}: ${detail}`.slice(0, MAX_DETAILS),
+            });
+        }
+        catch (e) {
+            console.warn("Aira notarize failed (non-blocking):", e);
+        }
     }
     /**
-     * Wraps a tool function to auto-notarize calls and results.
+     * REAL GATE: wraps a tool function to gate + notarize.
+     *
+     * Flow:
+     *   1. Call `aira.authorize()` — throws POLICY_DENIED or pending_approval.
+     *   2. Run the tool.
+     *   3. Call `aira.notarize()` with outcome="completed" or "failed".
+     *
      * No raw user data is sent — only tool name, arg keys, and output length.
      */
     wrapTool(toolFn, toolName) {
@@ -71,10 +117,20 @@ class AiraGuardrail {
             const kwargs = args.length > 0 && typeof args[0] === "object" && args[0]
                 ? args[0]
                 : undefined;
-            self.onToolCall(name, kwargs);
-            const result = await toolFn.apply(this, args);
-            self.onToolResult(name, result);
-            return result;
+            const actionId = await self.authorizeToolCall(name, kwargs);
+            try {
+                const result = await toolFn.apply(this, args);
+                if (actionId) {
+                    await self.notarizeToolResult(actionId, name, "completed", `result length ${String(result).length} chars`);
+                }
+                return result;
+            }
+            catch (err) {
+                if (actionId) {
+                    await self.notarizeToolResult(actionId, name, "failed", err?.message ?? String(err));
+                }
+                throw err;
+            }
         };
         return wrapped;
     }