@ouro.bot/cli 0.1.0-alpha.653 → 0.1.0-alpha.655

package/dist/repertoire/tools-commerce.js

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commerceToolDefinitions = void 0;
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const store_1 = require("../commerce/store");
+function requireFamilyContext(ctx) {
+    if (!ctx?.context?.friend?.id)
+        return "no friend context — cannot use commerce tools.";
+    if (ctx.context.friend.trustLevel !== "family")
+        return "commerce tools require family trust level.";
+    /* v8 ignore next -- no-agentRoot fallback depends on process argv; normal tool calls inject agentRoot @preserve */
+    if (ctx.agentRoot)
+        return { friendId: ctx.context.friend.id, agentRoot: ctx.agentRoot };
+    return { friendId: ctx.context.friend.id, agentRoot: (0, identity_1.getAgentRoot)() };
+}
+function parseItems(raw) {
+    if (!raw?.trim())
+        return undefined;
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed))
+        throw new Error("items_json must be a JSON array");
+    return parsed.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            throw new Error("each item must be an object");
+        const record = item;
+        if (typeof record.name !== "string" || !record.name.trim())
+            throw new Error("each item needs a name");
+        return {
+            name: record.name,
+            ...(typeof record.quantity === "number" ? { quantity: record.quantity } : {}),
+            ...(typeof record.amount === "number" ? { amount: record.amount } : {}),
+        };
+    });
+}
+function parseExpiryMinutes(raw) {
+    if (!raw?.trim())
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isInteger(value) || value <= 0)
+        throw new Error("expires_minutes must be a positive integer");
+    return value;
+}
+function parseExactAmount(raw) {
+    const value = raw?.trim();
+    if (!value || !/^\d+(?:\.\d{1,2})?$/.test(value))
+        throw new Error("amount must be an exact decimal with at most two places");
+    return Number(value);
+}
+function parseToolName(raw) {
+    const toolName = raw?.trim();
+    if (!toolName)
+        throw new Error("tool_name is required");
+    return toolName;
+}
+function parseConstraints(raw) {
+    if (!raw?.trim())
+        return undefined;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("constraints_json must be a JSON object");
+    return Object.fromEntries(Object.entries(parsed).map(([key, value]) => [key, String(value)]));
+}
+function validateToolConstraints(toolName, constraints) {
+    if (toolName !== "stripe_create_card")
+        return;
+    if (!constraints?.type)
+        throw new Error("constraints_json.type is required for stripe_create_card");
+    if (!constraints.merchant_categories)
+        throw new Error("constraints_json.merchant_categories is required for stripe_create_card");
+}
+exports.commerceToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "commerce_checkout_preview",
+                description: "Create an AP2-compatible local checkout preview before any payment or booking action. Requires family trust.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        merchant: { type: "string", description: "Merchant, provider, or counterparty name." },
+                        amount: { type: "string", description: "Exact total amount." },
+                        currency: { type: "string", description: "Currency code, e.g. usd." },
+                        tool_name: { type: "string", description: "Exact tool this authority may be used with, e.g. stripe_create_card, flight_hold, or flight_book." },
+                        constraints_json: { type: "string", description: "JSON object of exact tool-argument constraints; required for stripe_create_card type and merchant_categories, and recommended for flight offer_id." },
+                        reason: { type: "string", description: "Why this purchase/booking is being made." },
+                        items_json: { type: "string", description: "Optional JSON array of {name, quantity, amount} items." },
+                        expires_minutes: { type: "string", description: "Optional expiry window in minutes; defaults to 30." },
+                    },
+                    required: ["merchant", "amount", "currency", "tool_name", "reason"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_commerce_checkout_preview",
+                message: "commerce_checkout_preview invoked",
+                meta: { tool: "commerce_checkout_preview", merchant: args.merchant },
+            });
+            const guard = requireFamilyContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            try {
+                const expiresInMinutes = parseExpiryMinutes(args.expires_minutes);
+                const toolName = parseToolName(args.tool_name);
+                const constraints = parseConstraints(args.constraints_json);
+                const items = parseItems(args.items_json);
+                validateToolConstraints(toolName, constraints);
+                const record = (0, store_1.createCommercePreview)({
+                    agentRoot: guard.agentRoot,
+                    friendId: guard.friendId,
+                    merchant: args.merchant,
+                    amount: parseExactAmount(args.amount),
+                    currency: args.currency,
+                    allowedTools: [toolName],
+                    constraints,
+                    reason: args.reason,
+                    items,
+                    ...(expiresInMinutes ? { expiresInMinutes } : {}),
+                });
+                const confirmationMessage = (0, store_1.commerceConfirmationMessage)(record);
+                return JSON.stringify({
+                    checkoutId: record.id,
+                    merchant: record.merchant,
+                    amount: record.amount,
+                    currency: record.currency,
+                    allowedTools: record.allowedTools,
+                    constraints: record.constraints,
+                    expiresAt: record.expiresAt,
+                    digest: record.digest,
+                    confirmationMessage,
+                    next: `Ask the family user to send the confirmationMessage exactly in a new turn after reviewing merchant, amount, currency, tool, and constraints; then call commerce_checkout_commit from that same turn.`,
+                }, null, 2);
+            }
+            catch (error) {
+                return `commerce preview error: ${error instanceof Error ? error.message : /* v8 ignore next -- defensive non-Error parser failures */ String(error)}`;
+            }
+        },
+        summaryKeys: ["merchant", "amount", "currency"],
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "creates a purchase mandate preview" },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "commerce_checkout_commit",
+                description: "Confirm an exact checkout preview for the next matching payment/booking tool call. Requires family trust and confirmation=CONFIRM_PURCHASE.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        checkout_id: { type: "string", description: "Checkout preview ID." },
+                        digest: { type: "string", description: "Digest returned by commerce_checkout_preview." },
+                        confirmation: { type: "string", description: "Must be CONFIRM_PURCHASE." },
+                    },
+                    required: ["checkout_id", "digest", "confirmation"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_commerce_checkout_commit",
+                message: "commerce_checkout_commit invoked",
+                meta: { tool: "commerce_checkout_commit", checkoutId: args.checkout_id },
+            });
+            const guard = requireFamilyContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            try {
+                const record = (0, store_1.confirmCommercePreview)({
+                    agentRoot: guard.agentRoot,
+                    checkoutId: args.checkout_id,
+                    digest: args.digest,
+                    confirmation: args.confirmation,
+                    friendId: guard.friendId,
+                    currentUserMessage: ctx?.currentUserMessage,
+                });
+                return JSON.stringify({
+                    checkoutId: record.id,
+                    status: record.status,
+                    expiresAt: record.expiresAt,
+                    use: "Call the approved payment or booking tool with the exact merchant/tool/amount/currency/constraint arguments; Ouro will consume the matching authority without exposing a bearer token.",
+                }, null, 2);
+            }
+            catch (error) {
+                return `commerce commit error: ${error instanceof Error ? error.message : /* v8 ignore next -- defensive non-Error store failures */ String(error)}`;
+            }
+        },
+        summaryKeys: ["checkout_id"],
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "confirms a purchase mandate" },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "commerce_receipt_get",
+                description: "Read a local commerce checkout/mandate receipt. Requires family trust.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        checkout_id: { type: "string", description: "Checkout ID." },
+                    },
+                    required: ["checkout_id"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_commerce_receipt_get",
+                message: "commerce_receipt_get invoked",
+                meta: { tool: "commerce_receipt_get", checkoutId: args.checkout_id },
+            });
+            const guard = requireFamilyContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            const record = (0, store_1.readCommerceRecord)(guard.agentRoot, args.checkout_id);
+            return record ? JSON.stringify(record, null, 2) : `commerce checkout not found: ${args.checkout_id}`;
+        },
+        summaryKeys: ["checkout_id"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "commerce_access_log",
+                description: "Read the commerce authority access log. Requires family trust.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        limit: { type: "string", description: "Number of recent entries to return; defaults to 20." },
+                    },
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_commerce_access_log",
+                message: "commerce_access_log invoked",
+                meta: { tool: "commerce_access_log" },
+            });
+            const guard = requireFamilyContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            const limit = args.limit ? Number.parseInt(args.limit, 10) : 20;
+            return JSON.stringify((0, store_1.readCommerceAccessLog)(guard.agentRoot, Number.isInteger(limit) ? limit : 20), null, 2);
+        },
+        summaryKeys: ["limit"],
+    },
+];

package/dist/repertoire/tools-flight.js

@@ -6,6 +6,7 @@ const duffel_client_1 = require("./duffel-client");
 const user_profile_1 = require("./user-profile");
 const credential_access_1 = require("./credential-access");
 const runtime_1 = require("../nerves/runtime");
+const store_1 = require("../commerce/store");
 // Lazy-initialized Duffel client singleton
 let _duffelClient = null;
 async function getDuffelClient() {
@@ -29,6 +30,43 @@ function requireFriendContext(ctx) {
     }
     return { friendId: ctx.context.friend.id };
 }
+function parseExactAmount(raw) {
+    const value = raw.trim();
+    if (!/^\d+(?:\.\d{1,2})?$/.test(value))
+        throw new Error("amount must be an exact decimal with at most two places");
+    return Number(value);
+}
+function consumeReservedCommerce(ctx, toolName) {
+    if (!ctx?.commerceAuthority || !ctx.agentRoot)
+        return null;
+    const result = (0, store_1.consumeReservedCommerceAuthority)({
+        agentRoot: ctx.agentRoot,
+        checkoutId: ctx.commerceAuthority.checkoutId,
+        reservationToken: ctx.commerceAuthority.reservationToken,
+        toolName,
+        friendId: ctx.context?.friend?.id,
+    });
+    return result.ok ? null : `commerce authority consume error: ${result.reason}`;
+}
+function markCommerceAttempted(ctx, toolName) {
+    if (!ctx?.commerceAuthority || !ctx.agentRoot)
+        return null;
+    const result = (0, store_1.markReservedCommerceAuthorityAttempted)({
+        agentRoot: ctx.agentRoot,
+        checkoutId: ctx.commerceAuthority.checkoutId,
+        reservationToken: ctx.commerceAuthority.reservationToken,
+        toolName,
+        friendId: ctx.context?.friend?.id,
+    });
+    return result.ok ? null : `commerce authority attempt error: ${result.reason}`;
+}
+function normalizeCurrency(raw) {
+    return raw.trim().toLowerCase();
+}
+function orderMatchesApprovedTotal(input, amount, currency) {
+    const orderAmount = parseExactAmount(input.totalAmount);
+    return orderAmount === amount && normalizeCurrency(input.totalCurrency) === normalizeCurrency(currency);
+}
 exports.flightToolDefinitions = [
     {
         tool: {
@@ -89,13 +127,16 @@ exports.flightToolDefinitions = [
             type: "function",
             function: {
                 name: "flight_hold",
-                description: "Hold a flight offer for a short period before committing to book. Not all airlines support holds.",
+                description: "Hold a flight offer for a short period before committing to book. Not all airlines support holds. Requires a matching confirmed commerce checkout.",
                 parameters: {
                     type: "object",
                     properties: {
                         offer_id: { type: "string", description: "The Duffel offer ID to hold" },
+                        amount: { type: "string", description: "Exact hold amount from the approved commerce preview." },
+                        currency: { type: "string", description: "Currency code from the approved commerce preview, e.g. usd." },
+                        commerce_authority: { type: "string", description: "Optional explicit authority token for external/manual flows; normally omit so Ouro consumes the matching confirmed checkout." },
                     },
-                    required: ["offer_id"],
+                    required: ["offer_id", "amount", "currency"],
                 },
             },
         },
@@ -111,9 +152,19 @@ exports.flightToolDefinitions = [
                 return guard;
             // Hold functionality would call Duffel's offer hold API.
             // For pre-build, we return a structured acknowledgment.
+            const amount = parseExactAmount(args.amount);
+            const attemptError = markCommerceAttempted(ctx, "flight_hold");
+            if (attemptError)
+                return attemptError;
+            const consumeError = consumeReservedCommerce(ctx, "flight_hold");
+            /* v8 ignore next -- hold pre-build has no provider callback between attempt and consume; this branch is race-defense for file/process interference @preserve */
+            if (consumeError)
+                return consumeError;
             return JSON.stringify({
                 status: "hold_requested",
                 offerId: args.offer_id,
+                amount,
+                currency: args.currency,
                 message: "Hold requested. Confirm or cancel before the hold expires.",
             });
         },
@@ -125,13 +176,14 @@ exports.flightToolDefinitions = [
             type: "function",
             function: {
                 name: "flight_book",
-                description: "Book a flight. Pulls passenger name/DOB/passport from the user's profile. Creates a virtual card, books the flight, then deactivates the card. Requires family trust level.",
+                description: "Book a flight. Pulls passenger name/DOB/passport from the user's profile. Creates a virtual card, books the flight, then deactivates the card. Requires family trust level and a matching confirmed commerce checkout.",
                 parameters: {
                     type: "object",
                     properties: {
                         offer_id: { type: "string", description: "The Duffel offer ID to book" },
                         amount: { type: "string", description: "Expected total amount in dollars" },
                         currency: { type: "string", description: "Currency code (e.g. 'usd')" },
+                        commerce_authority: { type: "string", description: "Optional explicit authority token for external/manual flows; normally omit so Ouro consumes the matching confirmed checkout." },
                     },
                     required: ["offer_id", "amount", "currency"],
                 },
@@ -148,6 +200,8 @@ exports.flightToolDefinitions = [
             if (typeof guard === "string")
                 return guard;
             try {
+                const amount = parseExactAmount(args.amount);
+                const currency = normalizeCurrency(args.currency);
                 const store = (0, credential_access_1.getCredentialStore)();
                 // Get passenger data from profile
                 const legalName = await (0, user_profile_1.getUserProfileField)(guard.friendId, "legalName", store);
@@ -157,6 +211,9 @@ exports.flightToolDefinitions = [
                 const dateOfBirth = await (0, user_profile_1.getUserProfileField)(guard.friendId, "dateOfBirth", store);
                 const passport = await (0, user_profile_1.getUserProfileField)(guard.friendId, "passport", store);
                 const client = await getDuffelClient();
+                const attemptError = markCommerceAttempted(ctx, "flight_book");
+                if (attemptError)
+                    return attemptError;
                 const result = await client.createOrder({
                     offerId: args.offer_id,
                     passengers: [{
@@ -169,9 +226,15 @@ exports.flightToolDefinitions = [
                             passportCountry: passport?.country,
                             passportExpiry: passport?.expiry,
                         }],
-                    amount: parseFloat(args.amount),
-                    currency: args.currency,
+                    amount,
+                    currency,
                 });
+                if (!orderMatchesApprovedTotal(result, amount, currency)) {
+                    return `booking error: completed order total ${result.totalAmount} ${result.totalCurrency} does not match approved ${args.amount} ${args.currency}`;
+                }
+                const consumeError = consumeReservedCommerce(ctx, "flight_book");
+                if (consumeError)
+                    return consumeError;
                 return JSON.stringify(result, null, 2);
             }
             catch (err) {

package/dist/repertoire/tools-stripe.js

@@ -4,6 +4,7 @@ exports.stripeToolDefinitions = void 0;
 exports.resetStripeClient = resetStripeClient;
 const stripe_client_1 = require("./stripe-client");
 const runtime_1 = require("../nerves/runtime");
+const store_1 = require("../commerce/store");
 // Lazy-initialized Stripe client singleton
 let _stripeClient = null;
 async function getStripeClient() {
@@ -21,13 +22,43 @@ function requireFamilyContext(ctx) {
     }
     return { friendId: ctx.context.friend.id };
 }
+function parseExactSpendLimit(raw) {
+    const value = raw.trim();
+    if (!/^\d+(?:\.\d{1,2})?$/.test(value))
+        throw new Error("spend_limit must be an exact decimal with at most two places");
+    return Number(value);
+}
+function consumeReservedCommerce(ctx, toolName) {
+    if (!ctx?.commerceAuthority || !ctx.agentRoot)
+        return null;
+    const result = (0, store_1.consumeReservedCommerceAuthority)({
+        agentRoot: ctx.agentRoot,
+        checkoutId: ctx.commerceAuthority.checkoutId,
+        reservationToken: ctx.commerceAuthority.reservationToken,
+        toolName,
+        friendId: ctx.context?.friend?.id,
+    });
+    return result.ok ? null : `commerce authority consume error: ${result.reason}`;
+}
+function markCommerceAttempted(ctx, toolName) {
+    if (!ctx?.commerceAuthority || !ctx.agentRoot)
+        return null;
+    const result = (0, store_1.markReservedCommerceAuthorityAttempted)({
+        agentRoot: ctx.agentRoot,
+        checkoutId: ctx.commerceAuthority.checkoutId,
+        reservationToken: ctx.commerceAuthority.reservationToken,
+        toolName,
+        friendId: ctx.context?.friend?.id,
+    });
+    return result.ok ? null : `commerce authority attempt error: ${result.reason}`;
+}
 exports.stripeToolDefinitions = [
     {
         tool: {
             type: "function",
             function: {
                 name: "stripe_create_card",
-                description: "Create a virtual card for a transaction. Returns card ID and last 4 digits (never the full card number). Requires family trust level.",
+                description: "Create a virtual card for an approved transaction. Returns card ID and last 4 digits (never the full card number). Requires family trust level and a matching confirmed commerce checkout.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -46,10 +77,14 @@ exports.stripeToolDefinitions = [
                         },
                         merchant_categories: {
                             type: "string",
-                            description: "Comma-separated allowed merchant categories (optional)",
+                            description: "Comma-separated allowed merchant categories from the confirmed commerce constraints.",
+                        },
+                        commerce_authority: {
+                            type: "string",
+                            description: "Optional explicit authority token for external/manual flows; normally omit so Ouro consumes the matching confirmed checkout without exposing a bearer token.",
                         },
                     },
-                    required: ["type", "spend_limit", "currency"],
+                    required: ["type", "spend_limit", "currency", "merchant_categories"],
                 },
             },
         },
@@ -64,16 +99,23 @@ exports.stripeToolDefinitions = [
             if (typeof guard === "string")
                 return guard;
             try {
+                const categories = args.merchant_categories.split(",").map((c) => c.trim()).filter(Boolean);
+                if (categories.length === 0)
+                    throw new Error("merchant_categories is required");
+                const spendLimit = parseExactSpendLimit(args.spend_limit);
+                const attemptError = markCommerceAttempted(ctx, "stripe_create_card");
+                if (attemptError)
+                    return attemptError;
                 const client = await getStripeClient();
-                const categories = args.merchant_categories
-                    ? args.merchant_categories.split(",").map((c) => c.trim())
-                    : undefined;
                 const card = await client.createVirtualCard({
                     type: args.type,
-                    spendLimit: parseFloat(args.spend_limit),
+                    spendLimit,
                     currency: args.currency,
                     merchantCategories: categories,
                 });
+                const consumeError = consumeReservedCommerce(ctx, "stripe_create_card");
+                if (consumeError)
+                    return consumeError;
                 return JSON.stringify({
                     cardId: card.cardId,
                     last4: card.last4,

package/dist/repertoire/tools.js

@@ -15,6 +15,7 @@ const tools_bundle_1 = require("./tools-bundle");
 const runtime_1 = require("../nerves/runtime");
 const guardrails_1 = require("./guardrails");
 const identity_1 = require("../heart/identity");
+const store_1 = require("../commerce/store");
 const tools_surface_1 = require("./tools-surface");
 const mcp_tools_1 = require("./mcp-tools");
 const tools_voice_1 = require("./tools-voice");
@@ -40,6 +41,7 @@ var tools_surface_2 = require("./tools-surface");
 Object.defineProperty(exports, "surfaceToolDef", { enumerable: true, get: function () { return tools_surface_2.surfaceToolDef; } });
 // All tool definitions in a single registry
 const allDefinitions = [...tools_base_1.baseToolDefinitions, ...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, ...tools_voice_1.voiceToolDefinitions, tools_surface_1.surfaceToolDefinition];
+const COMMERCE_AUTHORITY_TOOLS = new Set(["stripe_create_card", "flight_hold", "flight_book"]);
 // MCP tool definitions — populated each time getToolsForChannel() is called with an mcpManager.
 // Kept separate from allDefinitions so execTool can find them.
 let mcpDefinitions = [];
@@ -251,7 +253,8 @@ async function execTool(name, args, ctx) {
     const guardContext = {
         readPaths: tools_base_1.editFileReadTracker,
         trustLevel: ctx?.context?.friend?.trustLevel,
-        agentRoot: safeGetAgentRoot(),
+        agentRoot: ctx?.agentRoot ?? safeGetAgentRoot(),
+        friendId: ctx?.context?.friend?.id,
         ...(mcpDef?.mcpServer ? { mcpServerName: mcpDef.mcpServer } : {}),
         ...(ctx?.context?.isGroupChat !== undefined ? { isGroupChat: (ctx?.context).isGroupChat } : {}),
     };
@@ -267,8 +270,37 @@ async function execTool(name, args, ctx) {
         });
         return guardResult.reason;
     }
+    const commerceReservation = COMMERCE_AUTHORITY_TOOLS.has(name) && guardContext.agentRoot
+        ? (0, store_1.reserveCommerceAuthority)({
+            agentRoot: guardContext.agentRoot,
+            token: guardArgs.commerce_authority,
+            toolName: name,
+            args: guardArgs,
+            friendId: guardContext.friendId,
+        })
+        : null;
+    if (commerceReservation && !commerceReservation.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            event: "tool.guardrail_block",
+            component: "tools",
+            message: "guardrail blocked tool execution",
+            meta: { name, reason: commerceReservation.reason },
+        });
+        return `commerce authority required: ${commerceReservation.reason}`;
+    }
+    const toolContext = commerceReservation?.ok
+        ? {
+            ...ctx,
+            agentRoot: guardContext.agentRoot,
+            commerceAuthority: {
+                checkoutId: commerceReservation.checkoutId,
+                reservationToken: commerceReservation.reservationToken,
+            },
+        }
+        : ctx;
     try {
-        const result = await def.handler(args, ctx);
+        const result = await def.handler(args, toolContext);
         (0, runtime_1.emitNervesEvent)({
             event: "tool.end",
             component: "tools",
@@ -287,6 +319,22 @@ async function execTool(name, args, ctx) {
         });
         throw error;
     }
+    finally {
+        if (commerceReservation?.ok && guardContext.agentRoot) {
+            try {
+                (0, store_1.releaseReservedCommerceAuthority)({
+                    agentRoot: guardContext.agentRoot,
+                    checkoutId: commerceReservation.checkoutId,
+                    reservationToken: commerceReservation.reservationToken,
+                    toolName: name,
+                    friendId: guardContext.friendId,
+                });
+            }
+            catch {
+                /* v8 ignore next -- external tool result/error should not be masked by best-effort reservation cleanup @preserve */
+            }
+        }
+    }
 }
 function summarizeKeyValues(args, keys, maxValueLength = 60) {
     const parts = [];

package/dist/senses/a2a-entry.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const agentArgIndex = process.argv.indexOf("--agent");
+const agentName = agentArgIndex >= 0 ? process.argv[agentArgIndex + 1] : undefined;
+if (!agentName) {
+    // eslint-disable-next-line no-console -- pre-boot guard: --agent check before imports
+    console.error("Missing required --agent <name> argument.\nUsage: node dist/senses/a2a-entry.js --agent ouroboros [--port 18920] [--base-url https://agent.example]");
+    process.exit(1);
+}
+function argValue(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+const runtime_logging_1 = require("../heart/daemon/runtime-logging");
+const runtime_1 = require("../nerves/runtime");
+(0, runtime_logging_1.configureDaemonRuntimeLogger)("a2a");
+(0, runtime_1.emitNervesEvent)({
+    component: "senses",
+    event: "senses.entry_boot",
+    message: "booting A2A entrypoint",
+    meta: { entry: "a2a", agentName },
+});
+Promise.resolve().then(() => __importStar(require("../a2a/server"))).then(async ({ startA2AServer }) => {
+    const rawPort = argValue("--port");
+    const port = rawPort ? Number.parseInt(rawPort, 10) : undefined;
+    await startA2AServer({
+        agentName,
+        ...(argValue("--host") ? { host: argValue("--host") } : {}),
+        ...(Number.isInteger(port) ? { port } : {}),
+        ...(argValue("--base-url") ? { baseUrl: argValue("--base-url") } : {}),
+        ...(argValue("--path") ? { path: argValue("--path") } : {}),
+    });
+})
+    .catch((error) => {
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "senses",
+        event: "senses.entry_error",
+        message: "A2A entrypoint failed",
+        meta: { entry: "a2a", agentName, error: error instanceof Error ? error.message : String(error) },
+    });
+    // eslint-disable-next-line no-console -- fatal startup guard for sense process
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});