@oobe-protocol-labs/sap-mcp-server 0.9.2 → 0.9.3

package/dist/tools/x402-paid-call-tool.js

@@ -5,7 +5,10 @@
 import { registerTool } from '../adapters/mcp/sdk-compat.js';
 import { createTextResponse } from '../adapters/mcp/tool-response.js';
 import { getActiveProfile, getProfileConfigPath } from '../config/profiles.js';
-import { executeX402PaidCall, getX402PaymentReadiness, inspectX402Receipt, probeX402PaymentChallenge, signX402PaymentChallenge, } from '../payments/x402-paid-call.js';
+import { executeX402PaidCall, executeExternalX402Call, getX402PaymentReadiness, inspectX402Receipt, probeX402PaymentChallenge, signX402PaymentChallenge, } from '../payments/x402-paid-call.js';
+import { finalizeTransactionWithLocalSigner } from './transaction-tools.js';
+import { SAP_AGENT_REGISTER_INPUT_SCHEMA, SAP_AGENT_UPDATE_INPUT_SCHEMA, parseRegisterAgentArgs, parseUpdateAgentArgs, } from './sap-sdk-tools.js';
+import { SAP_PROTOCOL_TREASURY, SAP_REGISTRATION_FEE_LAMPORTS } from '../core/constants.js';
 const paidCallInputSchema = {
     endpoint: {
         type: 'string',
@@ -29,7 +32,7 @@ const paidCallInputSchema = {
     },
     maxPriceUsd: {
         type: 'number',
-        description: 'Maximum accepted x402 payment amount in USD. The call aborts if the challenge exceeds this cap.',
+        description: 'Per-call safety cap in USD for the x402 payment. The call aborts before signing if the challenge exceeds this cap. Estimate first with sap_estimate_tool_cost.',
     },
     maxAttempts: {
         type: 'number',
@@ -93,12 +96,588 @@ export function registerX402PaidCallTool(server, _context) {
     registerPaymentsProfileCurrentTool(server, _context);
     registerPaymentsReadinessTool(server);
     registerPaymentsCallPaidTool(server, 'sap_payments_call_paid_tool');
+    registerPaymentsCallExternalX402Tool(server);
+    registerPaymentsRegisterAgentTool(server, _context);
+    registerPaymentsUpdateAgentTool(server, _context);
+    registerPaymentsFinalizeTransactionTool(server, _context);
     registerPaymentsPrepareChallengeTool(server);
     registerPaymentsSignChallengeTool(server);
     registerPaymentsVerifyReceiptTool(server);
     // Backward-compatible alias used by existing Codex/Hermes/Claude client snippets.
     registerPaymentsCallPaidTool(server, 'sap_x402_paid_call');
 }
+function registerPaymentsRegisterAgentTool(server, context) {
+    registerTool(server, 'sap_payments_register_agent', {
+        title: 'Register SAP Agent With Local Signer',
+        description: 'Canonical local non-custodial SAP registry write for hosted and local users. Use this after hosted sap_register_agent returns hosted_local_signer_required, or directly instead of raw sap_register_agent. It registers the active local SAP MCP profile wallet as an on-chain SAP agent with the local signer; OOBE never receives keypair bytes. This tool does not pay a hosted x402 fee because it runs locally through sap_payments. After confirmation it enforces the source-level expected 0.1 SOL SAP protocol registration fee against the protocol treasury. success is true only when the agent account exists and the protocol fee invariant is verified. Requires confirm: true.',
+        inputSchema: {
+            ...SAP_AGENT_REGISTER_INPUT_SCHEMA,
+            confirmationTimeoutMs: {
+                type: 'number',
+                description: 'Optional local confirmation wait in milliseconds. Defaults to 90000 so the tool can distinguish confirmed registration from an expired/not-landed transaction.',
+            },
+            confirm: { type: 'boolean', description: 'Must be true. Confirms the user wants the local signer to submit this SAP registry transaction.' },
+        },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                success: { type: 'boolean', description: 'Whether the full SAP registration lifecycle completed: agent account confirmed and protocol fee invariant verified.' },
+                signature: { type: 'string', description: 'Solana transaction signature returned by the SAP SDK.' },
+                confirmationStatus: { type: 'string', description: 'Final local confirmation result: confirmed, finalized, processed, expired, missing, or failed.' },
+                signerPublicKey: { type: 'string', description: 'Public key of the local SAP MCP signer that registered the agent.' },
+                profile: { type: 'string', description: 'Active local SAP MCP profile used for registration when available.' },
+                agentRegistered: { type: 'boolean', description: 'Whether the SAP agent account was found on-chain, even if protocolComplete is false.' },
+                agent: { type: 'object', description: 'Agent registration fields submitted on-chain.' },
+                protocolFee: { type: 'object', description: 'Verification of the SAP protocol registration fee credited to the protocol treasury in the landed transaction.' },
+                protocolComplete: { type: 'boolean', description: 'True only when the agent account is confirmed and the expected protocol fee invariant is verified from transaction metadata.' },
+                audit: { type: 'object', description: 'Agent-readable proof that the write was local, non-custodial, and did not use hosted x402.' },
+            },
+            required: ['success', 'signature', 'confirmationStatus', 'signerPublicKey', 'agentRegistered', 'agent', 'protocolFee', 'protocolComplete', 'audit'],
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        try {
+            const parsed = parseRegisterAgentInput(input);
+            const activeProfile = getActiveProfile();
+            const signerPublicKey = context.signer?.publicKey.toBase58();
+            if (!signerPublicKey) {
+                throw new Error('No local signer configured. Run the SAP MCP wizard full setup or repair the local sap_payments bridge, then restart the agent runtime.');
+            }
+            const args = parseRegisterAgentArgs(parsed);
+            const signature = await context.sapClient.agent.register(args);
+            const confirmation = await waitForLocalAgentRegistration(context, signature, parsed.confirmationTimeoutMs);
+            if (!confirmation.confirmed) {
+                return createTextResponse(JSON.stringify({
+                    success: false,
+                    signature,
+                    confirmationStatus: confirmation.status,
+                    signerPublicKey,
+                    profile: activeProfile,
+                    agentPda: confirmation.agentPda,
+                    agentRegistered: false,
+                    agent: {
+                        name: args.name,
+                        description: args.description,
+                        agentId: args.agentId,
+                        agentUri: args.agentUri,
+                        x402Endpoint: args.x402Endpoint,
+                        protocols: args.protocols,
+                        capabilityCount: args.capabilities.length,
+                        pricingTierCount: args.pricing.length,
+                    },
+                    protocolFee: buildUnconfirmedProtocolFeeStatus(signature),
+                    protocolComplete: false,
+                    audit: {
+                        action: 'sap_payments_register_agent',
+                        registeredLocally: true,
+                        hostedX402Charged: false,
+                        signerBoundary: 'local-sap-payments-bridge',
+                        secretMaterial: 'keypair-bytes-never-returned',
+                        transactionLanded: false,
+                        retrySafe: confirmation.retrySafe,
+                        rule: 'The local signer submitted the SAP registry transaction, but the transaction did not confirm or the agent account was not found inside the local confirmation window.',
+                        nextAction: confirmation.retrySafe
+                            ? 'Ask the user for confirmation, then retry sap_payments_register_agent once with the same fields and confirm: true. Do not call hosted sap_register_agent.'
+                            : 'Do not retry automatically. Inspect the signature and local RPC health first.',
+                    },
+                }, null, 2), { isError: true });
+            }
+            const protocolFee = await verifyProtocolRegistrationFee(context, signature);
+            if (protocolFee.status === 'missing_or_underpaid') {
+                return createTextResponse(JSON.stringify({
+                    success: false,
+                    signature,
+                    confirmationStatus: confirmation.status,
+                    signerPublicKey,
+                    profile: activeProfile,
+                    agentPda: confirmation.agentPda,
+                    agentRegistered: true,
+                    protocolComplete: false,
+                    agent: {
+                        name: args.name,
+                        description: args.description,
+                        agentId: args.agentId,
+                        agentUri: args.agentUri,
+                        x402Endpoint: args.x402Endpoint,
+                        protocols: args.protocols,
+                        capabilityCount: args.capabilities.length,
+                        pricingTierCount: args.pricing.length,
+                    },
+                    protocolFee,
+                    audit: {
+                        action: 'sap_payments_register_agent',
+                        registeredLocally: true,
+                        hostedX402Charged: false,
+                        signerBoundary: 'local-sap-payments-bridge',
+                        secretMaterial: 'keypair-bytes-never-returned',
+                        transactionLanded: true,
+                        protocolIntegrity: 'failed',
+                        rule: 'The SAP agent account was found after registration, but the source-level expected protocol treasury registration fee was not visible in the landed transaction. The account exists, but the SAP registration lifecycle is not complete and must not be marketed as protocol-complete.',
+                        nextAction: 'Do not retry registration automatically. Inspect the signature, deployed SAP program version, and treasury account balance delta before changing fee policy or redeploying the program.',
+                    },
+                }, null, 2), { isError: true });
+            }
+            if (protocolFee.status !== 'verified') {
+                return createTextResponse(JSON.stringify({
+                    success: false,
+                    signature,
+                    confirmationStatus: confirmation.status,
+                    signerPublicKey,
+                    profile: activeProfile,
+                    agentPda: confirmation.agentPda,
+                    agentRegistered: true,
+                    protocolComplete: false,
+                    agent: {
+                        name: args.name,
+                        description: args.description,
+                        agentId: args.agentId,
+                        agentUri: args.agentUri,
+                        x402Endpoint: args.x402Endpoint,
+                        protocols: args.protocols,
+                        capabilityCount: args.capabilities.length,
+                        pricingTierCount: args.pricing.length,
+                    },
+                    protocolFee,
+                    audit: {
+                        action: 'sap_payments_register_agent',
+                        registeredLocally: true,
+                        hostedX402Charged: false,
+                        signerBoundary: 'local-sap-payments-bridge',
+                        secretMaterial: 'keypair-bytes-never-returned',
+                        transactionLanded: true,
+                        protocolIntegrity: 'fee-verification-unavailable',
+                        rule: 'The SAP agent account was found, but transaction metadata did not prove the protocol treasury fee. The lifecycle is intentionally failed closed until another RPC or explorer verifies the fee delta.',
+                        nextAction: 'Fetch transaction metadata from a reliable RPC or explorer. Do not announce registration complete until protocolFee.status is verified.',
+                    },
+                }, null, 2), { isError: true });
+            }
+            return createTextResponse(JSON.stringify({
+                success: true,
+                signature,
+                confirmationStatus: confirmation.status,
+                signerPublicKey,
+                profile: activeProfile,
+                agentPda: confirmation.agentPda,
+                agentRegistered: true,
+                agent: {
+                    name: args.name,
+                    description: args.description,
+                    agentId: args.agentId,
+                    agentUri: args.agentUri,
+                    x402Endpoint: args.x402Endpoint,
+                    protocols: args.protocols,
+                    capabilityCount: args.capabilities.length,
+                    pricingTierCount: args.pricing.length,
+                },
+                protocolFee,
+                protocolComplete: protocolFee.status === 'verified',
+                audit: {
+                    action: 'sap_payments_register_agent',
+                    registeredLocally: true,
+                    hostedX402Charged: false,
+                    signerBoundary: 'local-sap-payments-bridge',
+                    secretMaterial: 'keypair-bytes-never-returned',
+                    transactionLanded: true,
+                    protocolIntegrity: 'verified',
+                    rule: 'Hosted sap_register_agent is accountless and cannot sign user-owned registry writes. This local bridge submitted the SAP registry transaction with the user-controlled profile signer.',
+                    nextAction: 'Registration is complete. Fetch the agent by owner wallet and continue with optional Metaplex or SNS identity links.',
+                },
+            }, null, 2));
+        }
+        catch (error) {
+            return createTextResponse(formatLocalRegistryError(error), { isError: true });
+        }
+    });
+}
+function buildUnconfirmedProtocolFeeStatus(signature) {
+    return {
+        status: 'not_checked',
+        signature,
+        expectedTreasury: SAP_PROTOCOL_TREASURY,
+        expectedLamports: SAP_REGISTRATION_FEE_LAMPORTS.toString(10),
+        reason: 'Registration transaction was not confirmed, so protocol fee verification was skipped.',
+    };
+}
+async function verifyProtocolRegistrationFee(context, signature) {
+    try {
+        const tx = await context.connection.getParsedTransaction(signature, {
+            commitment: 'confirmed',
+            maxSupportedTransactionVersion: 0,
+        });
+        if (!tx?.meta) {
+            return {
+                status: 'unavailable',
+                signature,
+                expectedTreasury: SAP_PROTOCOL_TREASURY,
+                expectedLamports: SAP_REGISTRATION_FEE_LAMPORTS.toString(10),
+                reason: 'Transaction metadata was unavailable from the configured RPC.',
+            };
+        }
+        const accountKeys = tx.transaction.message.accountKeys.map((account) => account.pubkey.toBase58());
+        const treasuryIndex = accountKeys.indexOf(SAP_PROTOCOL_TREASURY);
+        if (treasuryIndex < 0) {
+            return {
+                status: 'missing_or_underpaid',
+                signature,
+                expectedTreasury: SAP_PROTOCOL_TREASURY,
+                expectedLamports: SAP_REGISTRATION_FEE_LAMPORTS.toString(10),
+                observedLamportsDelta: '0',
+                reason: 'Protocol treasury account was not present in the transaction account list.',
+            };
+        }
+        const preBalance = BigInt(tx.meta.preBalances[treasuryIndex] ?? 0);
+        const postBalance = BigInt(tx.meta.postBalances[treasuryIndex] ?? 0);
+        const delta = postBalance - preBalance;
+        const verified = delta >= SAP_REGISTRATION_FEE_LAMPORTS;
+        return {
+            status: verified ? 'verified' : 'missing_or_underpaid',
+            signature,
+            expectedTreasury: SAP_PROTOCOL_TREASURY,
+            expectedLamports: SAP_REGISTRATION_FEE_LAMPORTS.toString(10),
+            observedLamportsDelta: delta.toString(10),
+            reason: verified
+                ? 'Protocol treasury balance delta satisfies the expected SAP registration fee.'
+                : 'Protocol treasury balance delta is below the expected SAP registration fee.',
+        };
+    }
+    catch (error) {
+        return {
+            status: 'unavailable',
+            signature,
+            expectedTreasury: SAP_PROTOCOL_TREASURY,
+            expectedLamports: SAP_REGISTRATION_FEE_LAMPORTS.toString(10),
+            reason: error instanceof Error ? error.message : 'Unable to fetch transaction metadata from RPC.',
+        };
+    }
+}
+function registerPaymentsUpdateAgentTool(server, context) {
+    registerTool(server, 'sap_payments_update_agent', {
+        title: 'Update SAP Agent With Local Signer',
+        description: 'Local non-custodial SAP registry update for hosted users. Use this when hosted sap_update_agent returns hosted_local_signer_required. It updates the active local SAP MCP profile wallet agent with the local signer, including name, description, capabilities, protocols, pricing, agentUri/metadataUri, or x402Endpoint. Use it for agent picture/profile metadata updates after uploading image or metadata to a public URL such as IPFS, Arweave, Kommodo, or a HTTPS metadata endpoint. OOBE never receives keypair bytes and no hosted x402 fee is charged. Requires confirm: true.',
+        inputSchema: {
+            ...SAP_AGENT_UPDATE_INPUT_SCHEMA,
+            confirmationTimeoutMs: {
+                type: 'number',
+                description: 'Optional local confirmation wait in milliseconds. Defaults to 90000 so the tool can distinguish confirmed update from an expired/not-landed transaction.',
+            },
+            confirm: { type: 'boolean', description: 'Must be true. Confirms the user wants the local signer to submit this SAP registry update transaction.' },
+        },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                success: { type: 'boolean', description: 'Whether the local SAP agent update transaction was confirmed on-chain.' },
+                signature: { type: 'string', description: 'Solana transaction signature returned by the SAP SDK.' },
+                confirmationStatus: { type: 'string', description: 'Final local confirmation result: confirmed, finalized, processed, expired, missing, or failed.' },
+                signerPublicKey: { type: 'string', description: 'Public key of the local SAP MCP signer that updated the agent.' },
+                profile: { type: 'string', description: 'Active local SAP MCP profile used for update when available.' },
+                agentPda: { type: 'string', description: 'SAP agent PDA derived from the active local signer wallet.' },
+                update: { type: 'object', description: 'Update fields submitted on-chain. Omitted fields were intentionally left unchanged.' },
+                audit: { type: 'object', description: 'Agent-readable proof that the write was local, non-custodial, and did not use hosted x402.' },
+            },
+            required: ['success', 'signature', 'confirmationStatus', 'signerPublicKey', 'agentPda', 'update', 'audit'],
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        try {
+            const parsed = parseUpdateAgentInput(input);
+            const activeProfile = getActiveProfile();
+            const signerPublicKey = context.signer?.publicKey.toBase58();
+            if (!signerPublicKey) {
+                throw new Error('No local signer configured. Run the SAP MCP wizard full setup or repair the local sap_payments bridge, then restart the agent runtime.');
+            }
+            const args = parseUpdateAgentArgs(parsed);
+            const signature = await context.sapClient.agent.update(args);
+            const confirmation = await waitForLocalAgentUpdate(context, signature, parsed.confirmationTimeoutMs);
+            const update = summarizeAgentUpdate(args);
+            if (!confirmation.confirmed) {
+                return createTextResponse(JSON.stringify({
+                    success: false,
+                    signature,
+                    confirmationStatus: confirmation.status,
+                    signerPublicKey,
+                    profile: activeProfile,
+                    agentPda: confirmation.agentPda,
+                    update,
+                    audit: {
+                        action: 'sap_payments_update_agent',
+                        updatedLocally: true,
+                        hostedX402Charged: false,
+                        signerBoundary: 'local-sap-payments-bridge',
+                        secretMaterial: 'keypair-bytes-never-returned',
+                        transactionLanded: false,
+                        retrySafe: confirmation.retrySafe,
+                        rule: 'The local signer submitted the SAP registry update transaction, but the transaction did not confirm or the agent account was not found inside the local confirmation window.',
+                        nextAction: confirmation.retrySafe
+                            ? 'Ask the user for confirmation, then retry sap_payments_update_agent once with the same fields and confirm: true. Do not call hosted sap_update_agent.'
+                            : 'Do not retry automatically. Inspect the signature and local RPC health first.',
+                    },
+                }, null, 2), { isError: true });
+            }
+            return createTextResponse(JSON.stringify({
+                success: true,
+                signature,
+                confirmationStatus: confirmation.status,
+                signerPublicKey,
+                profile: activeProfile,
+                agentPda: confirmation.agentPda,
+                update,
+                audit: {
+                    action: 'sap_payments_update_agent',
+                    updatedLocally: true,
+                    hostedX402Charged: false,
+                    signerBoundary: 'local-sap-payments-bridge',
+                    secretMaterial: 'keypair-bytes-never-returned',
+                    transactionLanded: true,
+                    rule: 'Hosted sap_update_agent is accountless and cannot sign user-owned registry writes. This local bridge submitted the SAP registry update with the user-controlled profile signer.',
+                },
+            }, null, 2));
+        }
+        catch (error) {
+            return createTextResponse(formatLocalRegistryError(error), { isError: true });
+        }
+    });
+}
+async function waitForLocalAgentRegistration(context, signature, timeoutMs = 90_000) {
+    return waitForLocalAgentWrite(context, signature, timeoutMs);
+}
+async function waitForLocalAgentWrite(context, signature, timeoutMs = 90_000) {
+    const boundedTimeoutMs = Math.max(15_000, Math.min(timeoutMs, 180_000));
+    const startedAt = Date.now();
+    const [agentPda] = context.sapClient.agent.deriveAgent();
+    let lastStatus = 'missing';
+    while (Date.now() - startedAt < boundedTimeoutMs) {
+        const statuses = await context.connection.getSignatureStatuses([signature], { searchTransactionHistory: true });
+        const status = statuses.value[0];
+        if (status?.err) {
+            return {
+                confirmed: false,
+                retrySafe: true,
+                status: 'failed',
+                agentPda: agentPda.toBase58(),
+            };
+        }
+        lastStatus = status?.confirmationStatus ?? lastStatus;
+        const agent = await context.sapClient.agent.fetchNullable();
+        if (agent) {
+            return {
+                confirmed: true,
+                retrySafe: false,
+                status: status?.confirmationStatus ?? 'confirmed',
+                agentPda: agentPda.toBase58(),
+            };
+        }
+        await sleep(2_000);
+    }
+    return {
+        confirmed: false,
+        retrySafe: lastStatus === 'missing',
+        status: lastStatus === 'missing' ? 'expired_or_not_landed' : lastStatus,
+        agentPda: agentPda.toBase58(),
+    };
+}
+async function waitForLocalAgentUpdate(context, signature, timeoutMs = 90_000) {
+    const boundedTimeoutMs = Math.max(15_000, Math.min(timeoutMs, 180_000));
+    const startedAt = Date.now();
+    const [agentPda] = context.sapClient.agent.deriveAgent();
+    let lastStatus = 'missing';
+    while (Date.now() - startedAt < boundedTimeoutMs) {
+        const statuses = await context.connection.getSignatureStatuses([signature], { searchTransactionHistory: true });
+        const status = statuses.value[0];
+        if (status?.err) {
+            return {
+                confirmed: false,
+                retrySafe: true,
+                status: 'failed',
+                agentPda: agentPda.toBase58(),
+            };
+        }
+        lastStatus = status?.confirmationStatus ?? lastStatus;
+        if (lastStatus === 'processed' || lastStatus === 'confirmed' || lastStatus === 'finalized') {
+            return {
+                confirmed: true,
+                retrySafe: false,
+                status: lastStatus,
+                agentPda: agentPda.toBase58(),
+            };
+        }
+        await sleep(2_000);
+    }
+    return {
+        confirmed: false,
+        retrySafe: lastStatus === 'missing',
+        status: lastStatus === 'missing' ? 'expired_or_not_landed' : lastStatus,
+        agentPda: agentPda.toBase58(),
+    };
+}
+async function sleep(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}
+function registerPaymentsCallExternalX402Tool(server) {
+    registerTool(server, 'sap_payments_call_external_x402', {
+        title: 'Pay And Call External x402 Endpoint',
+        description: 'High-level local payment bridge for generic HTTP x402 endpoints outside hosted SAP MCP, such as another SAP agent endpoint discovered from the registry. It sends the request once to obtain the 402 payment challenge, signs with the user-controlled local SAP MCP profile wallet, retries the same HTTP request with PAYMENT-SIGNATURE, and returns the response plus receipt. Use sap_payments_call_paid_tool for hosted SAP MCP tools; use this only for external HTTP x402 providers. Requires confirm: true and maxPriceUsd.',
+        inputSchema: {
+            url: {
+                type: 'string',
+                description: 'External HTTP or HTTPS x402 endpoint URL to call, for example an agent endpoint discovered from SAP registry metadata.',
+            },
+            method: {
+                type: 'string',
+                enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+                description: 'HTTP method for the external request. Defaults to POST.',
+            },
+            headers: {
+                type: 'object',
+                description: 'Optional non-sensitive headers for the external request. Do not include PAYMENT-SIGNATURE, X-PAYMENT, Authorization, or cookies.',
+            },
+            body: {
+                type: 'object',
+                description: 'Optional JSON request body for POST, PUT, PATCH, or DELETE calls. Strings are sent as-is; objects are JSON-encoded.',
+            },
+            profileName: paidCallInputSchema.profileName,
+            maxPriceUsd: paidCallInputSchema.maxPriceUsd,
+            maxAttempts: paidCallInputSchema.maxAttempts,
+            confirm: paidCallInputSchema.confirm,
+        },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                success: { type: 'boolean', description: 'Whether the external x402 call completed successfully.' },
+                url: { type: 'string', description: 'External endpoint URL called.' },
+                method: { type: 'string', description: 'HTTP method used.' },
+                signerAddress: { type: 'string', description: 'Public address of the local SAP MCP signer. Secret bytes are never returned.' },
+                payment: { type: 'object', description: 'Selected payment requirements, including amountUsd, network, asset, and payTo, when a 402 challenge was paid.' },
+                settlement: { type: 'object', description: 'x402 settlement response returned by the provider/facilitator when available.' },
+                response: { type: 'object', description: 'External HTTP response status, safe headers, and parsed body.' },
+                attempts: { type: 'number', description: 'Number of attempts used.' },
+                transientRetries: { type: 'array', items: { type: 'string' }, description: 'Retryable errors encountered before success.' },
+                audit: { type: 'object', description: 'Agent-readable proof object with intent id, profile, payment receipt, attempts, and secret-material guarantee.' },
+            },
+            required: ['success', 'url', 'method', 'signerAddress', 'response', 'attempts', 'transientRetries', 'audit'],
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (input) => {
+        try {
+            const parsed = parseExternalInput(input);
+            const result = await executeExternalX402Call(parsed);
+            return createTextResponse(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return createTextResponse(formatPaidCallError(error), { isError: true });
+        }
+    });
+}
+function registerPaymentsFinalizeTransactionTool(server, context) {
+    registerTool(server, 'sap_payments_finalize_transaction', {
+        title: 'Finalize Transaction With Local Signer',
+        description: 'Local non-custodial transaction finalizer for hosted SAP MCP builders. Use this when a hosted tool returns transactionBase64, transaction, or an unsigned Solana transaction. It previews, signs with the active local SAP MCP profile signer, and optionally submits through the OOBE hosted submit relay for reliable confirmation. The relay only broadcasts already-signed bytes and never receives keypair material. Never create temporary signing scripts, read keypair JSON, or call hosted sap_sign_transaction for user-owned signatures. Requires confirm: true.',
+        inputSchema: {
+            transaction: {
+                type: 'string',
+                description: 'Serialized unsigned or partially signed Solana transaction. Accepts base64 by default.',
+            },
+            transactionBase64: {
+                type: 'string',
+                description: 'Alias for transaction when the builder returns transactionBase64.',
+            },
+            encoding: {
+                type: 'string',
+                enum: ['base64', 'base58'],
+                description: 'Encoding for transaction or transactionBase64. Defaults to base64.',
+            },
+            submit: {
+                type: 'boolean',
+                description: 'When true, submit the signed transaction after preview and signing. When false or omitted, return the signed transaction for inspection.',
+            },
+            skipPreflight: {
+                type: 'boolean',
+                description: 'Optional Solana RPC sendRawTransaction skipPreflight flag, used only when submit is true.',
+            },
+            maxRetries: {
+                type: 'number',
+                description: 'Optional Solana RPC sendRawTransaction maxRetries value, used only when submit is true.',
+            },
+            confirmationTimeoutMs: {
+                type: 'number',
+                description: 'Optional bounded confirmation wait in milliseconds. Defaults to 90000; maximum 180000.',
+            },
+            commitment: {
+                type: 'string',
+                enum: ['processed', 'confirmed', 'finalized'],
+                description: 'Desired confirmation status before returning success. Defaults to confirmed.',
+            },
+            submitViaRelay: {
+                type: 'boolean',
+                description: 'When submit is true, defaults to true. Set false only when the user explicitly wants local RPC submission instead of the OOBE hosted submit relay.',
+            },
+            submitRelayUrl: {
+                type: 'string',
+                description: 'Optional submit relay URL. Must be HTTPS, localhost, or 127.0.0.1. Defaults to https://mcp.sap.oobeprotocol.ai/tx/submit.',
+            },
+            confirm: {
+                type: 'boolean',
+                description: 'Must be true. Confirms the user allows the local SAP MCP signer to sign this transaction.',
+            },
+            signerProfile: {
+                type: 'string',
+                description: 'Optional profile name to use for signing instead of the global active profile. When provided, the bridge loads config-<signerProfile>.json and uses its keypair. This eliminates the need to switch .active-profile manually — multiple profiles can coexist in the same session. Falls back to the active profile if omitted.',
+            },
+            intentId: {
+                type: 'string',
+                description: 'Optional caller-provided id used to bind preview, signature, submission, and audit output.',
+            },
+        },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                success: { type: 'boolean', description: 'Whether finalization succeeded.' },
+                action: { type: 'string', description: 'preview-sign or preview-sign-submit.' },
+                submitted: { type: 'boolean', description: 'Whether the signed transaction was submitted to RPC.' },
+                signature: { type: 'string', description: 'Solana transaction signature when submit is true.' },
+                confirmationStatus: { type: 'string', description: 'Confirmed/finalized/failed/expired_or_not_landed status when submit is true.' },
+                retrySafe: { type: 'boolean', description: 'Whether the agent may ask the user to retry without risking a known landed duplicate.' },
+                explorerUrl: { type: 'string', description: 'Solana explorer URL for the submitted signature.' },
+                signerPublicKey: { type: 'string', description: 'Public key of the local signer that signed the transaction.' },
+                nativeTransferSol: { type: 'number', description: 'Estimated native SOL transferred by the transaction.' },
+                preview: { type: 'object', description: 'Decoded transaction preview and policy result.' },
+                signedTransaction: { type: 'string', description: 'Base64 signed transaction when submit is false or for audit.' },
+                encoding: { type: 'string', description: 'Encoding of signedTransaction.' },
+                audit: { type: 'object', description: 'Proof object binding intent, local signer, preview, signing, submission, and secret-material guarantee.' },
+            },
+            required: ['success', 'action', 'submitted', 'signerPublicKey', 'nativeTransferSol', 'preview', 'audit'],
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        try {
+            const parsed = parseFinalizeTransactionInput(input);
+            const result = await finalizeTransactionWithLocalSigner(context, parsed);
+            return createTextResponse(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return createTextResponse(formatFinalizeTransactionError(error), { isError: true });
+        }
+    });
+}
 function registerPaymentsProfileCurrentTool(server, context) {
     registerTool(server, 'sap_payments_profile_current', {
         title: 'Show Local SAP Payments Profile',
@@ -129,26 +708,55 @@ function registerPaymentsProfileCurrentTool(server, context) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async () => createTextResponse(JSON.stringify({
-        serverRole: 'local-sap-payments-bridge',
-        activeProfile: getActiveProfile(),
-        configPath: getProfileConfigPath(getActiveProfile()),
-        mode: context.config.mode,
-        network: networkFromRpcUrl(context.config.rpcUrl),
-        rpcUrl: redactUrl(context.config.rpcUrl),
-        programId: context.config.programId,
-        agentPubkey: context.config.agentPubkey,
-        walletPath: context.config.walletPath,
-        walletPathConfigured: Boolean(context.config.walletPath),
-        signerConfigured: Boolean(context.signer),
-        signerPublicKey: context.signer?.publicKey.toBase58(),
-        localProfileVisibility: 'visible-to-local-sap-payments-bridge',
-        hostedRemoteVisibility: 'not-visible-to-hosted-accountless-server',
-        secretMaterial: 'keypair-bytes-never-returned',
-        recommendedPaidTool: 'sap_payments_call_paid_tool',
-        recommendedReadinessTool: 'sap_payments_readiness',
-        agentInstruction: 'For wallet/profile questions, trust this local sap_payments profile result over the remote hosted sap_profile_current result. For paid/write workflows call sap_payments_readiness first. The hosted SAP MCP server is intentionally accountless.',
-    }, null, 2)));
+    }, async () => {
+        // Re-read the active profile on every call to avoid stale cache.
+        // The context.signer was resolved at startup from the then-active profile;
+        // if the user switched .active-profile manually, the cached signer is stale.
+        // We re-read .active-profile and resolve the current signer on demand.
+        const currentProfile = getActiveProfile();
+        const currentConfigPath = getProfileConfigPath(currentProfile);
+        let currentSignerPubkey = context.signer?.publicKey.toBase58();
+        let currentWalletPath = context.config.walletPath;
+        // Always try to re-resolve the signer from the active profile to avoid
+        // stale cache. If .active-profile was switched manually after startup,
+        // the context.signer reflects the OLD profile. We re-read and re-resolve.
+        try {
+            const { loadProfileConfig } = await import('../config/profiles.js');
+            const { resolveSigner } = await import('../signer/signer-resolver.js');
+            const profileConfig = loadProfileConfig(currentProfile);
+            if (profileConfig) {
+                const signerResult = await resolveSigner({ ...context.config, ...profileConfig });
+                if (signerResult.signer) {
+                    currentSignerPubkey = signerResult.signer.publicKey.toBase58();
+                }
+                currentWalletPath = profileConfig.walletPath;
+            }
+        }
+        catch {
+            // If we can't resolve the signer for the current profile, fall back
+            // to the cached signer — better than crashing.
+        }
+        return createTextResponse(JSON.stringify({
+            serverRole: 'local-sap-payments-bridge',
+            activeProfile: currentProfile,
+            configPath: currentConfigPath,
+            mode: context.config.mode,
+            network: networkFromRpcUrl(context.config.rpcUrl),
+            rpcUrl: redactUrl(context.config.rpcUrl),
+            programId: context.config.programId,
+            agentPubkey: context.config.agentPubkey,
+            walletPath: currentWalletPath,
+            walletPathConfigured: Boolean(currentWalletPath),
+            signerConfigured: Boolean(currentSignerPubkey),
+            signerPublicKey: currentSignerPubkey,
+            localProfileVisibility: 'visible-to-local-sap-payments-bridge',
+            hostedRemoteVisibility: 'not-visible-to-hosted-accountless-server',
+            secretMaterial: 'keypair-bytes-never-returned',
+            recommendedPaidTool: 'sap_payments_call_paid_tool',
+            recommendedReadinessTool: 'sap_payments_readiness',
+            agentInstruction: 'For wallet/profile questions, trust this local sap_payments profile result over the remote hosted sap_profile_current result. For paid/write workflows call sap_payments_readiness first. The hosted SAP MCP server is intentionally accountless. If you need to sign with a specific profile, use signerProfile param on sap_payments_finalize_transaction instead of switching .active-profile.',
+        }, null, 2));
+    });
 }
 function registerPaymentsReadinessTool(server) {
     registerTool(server, 'sap_payments_readiness', {
@@ -227,7 +835,7 @@ function registerPaymentsPrepareChallengeTool(server) {
             body: paidCallInputSchema.body,
             maxPriceUsd: {
                 type: 'number',
-                description: 'Optional maximum acceptable USD price used only to reject oversized challenges during inspection.',
+                description: 'Maximum accepted x402 payment amount in USD. The call aborts if the challenge exceeds this cap. Common tool costs: read-premium ~$0.001, builder ~$0.008, standard value-action ~$0.09, heavy value-action ~$0.05. Set to at least the expected tier price — e.g. maxPriceUsd: 0.12 for standard swaps, 0.06 for heavy private execution, 0.01 for reads. If omitted, defaults to a very low cap that may abort value-action calls silently.',
             },
         },
         outputSchema: {
@@ -365,6 +973,74 @@ function parseInput(input) {
         confirm: record.confirm === true,
     };
 }
+function parseExternalInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('sap_payments_call_external_x402 requires an input object.');
+    }
+    const record = input;
+    if (!record.url) {
+        throw new Error('url is required.');
+    }
+    if (record.maxPriceUsd === undefined) {
+        throw new Error('maxPriceUsd is required.');
+    }
+    return {
+        url: record.url,
+        method: record.method,
+        headers: record.headers,
+        body: record.body,
+        profileName: record.profileName,
+        maxPriceUsd: record.maxPriceUsd,
+        maxAttempts: record.maxAttempts,
+        confirm: record.confirm === true,
+    };
+}
+function parseRegisterAgentInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('sap_payments_register_agent requires an input object.');
+    }
+    const record = input;
+    if (record.confirm !== true) {
+        throw new Error('confirm: true is required to submit a local SAP registry transaction.');
+    }
+    return record;
+}
+function parseUpdateAgentInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('sap_payments_update_agent requires an input object.');
+    }
+    const record = input;
+    if (record.confirm !== true) {
+        throw new Error('confirm: true is required to submit a local SAP registry update transaction.');
+    }
+    const hasUpdate = [
+        'name',
+        'description',
+        'capabilities',
+        'pricing',
+        'protocols',
+        'agentId',
+        'agentUri',
+        'metadataUri',
+        'x402Endpoint',
+    ].some((key) => Object.prototype.hasOwnProperty.call(record, key));
+    if (!hasUpdate) {
+        throw new Error('At least one update field is required: name, description, capabilities, pricing, protocols, agentId, agentUri/metadataUri, or x402Endpoint.');
+    }
+    return record;
+}
+function summarizeAgentUpdate(args) {
+    return {
+        name: args.name,
+        description: args.description,
+        agentId: args.agentId,
+        agentUri: args.agentUri,
+        x402Endpoint: args.x402Endpoint,
+        protocols: args.protocols,
+        capabilityCount: args.capabilities?.length ?? null,
+        pricingTierCount: args.pricing?.length ?? null,
+    };
+}
 function parseProbeInput(input) {
     if (!input || typeof input !== 'object' || Array.isArray(input)) {
         throw new Error('sap_payments_prepare_challenge requires an input object.');
@@ -409,6 +1085,30 @@ function parseReceiptInput(input) {
     }
     return header;
 }
+function parseFinalizeTransactionInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('sap_payments_finalize_transaction requires an input object.');
+    }
+    const record = input;
+    if (!record.transaction && !record.transactionBase64) {
+        throw new Error('transaction or transactionBase64 is required.');
+    }
+    return {
+        transaction: record.transaction,
+        transactionBase64: record.transactionBase64,
+        encoding: record.encoding,
+        submit: record.submit === true,
+        skipPreflight: record.skipPreflight,
+        maxRetries: record.maxRetries,
+        confirmationTimeoutMs: record.confirmationTimeoutMs,
+        commitment: record.commitment,
+        submitViaRelay: record.submitViaRelay !== false,
+        submitRelayUrl: record.submitRelayUrl,
+        confirm: record.confirm === true,
+        signerProfile: typeof record.signerProfile === 'string' ? record.signerProfile : undefined,
+        intentId: record.intentId,
+    };
+}
 function formatPaidCallError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const retryable = isRetryablePaymentError(message);
@@ -426,6 +1126,39 @@ function formatPaidCallError(error) {
     };
     return JSON.stringify(payload, null, 2);
 }
+function formatLocalRegistryError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = message.toLowerCase();
+    const signerMissing = normalized.includes('no local signer') || normalized.includes('no signer configured');
+    const retryable = isRetryablePaymentError(message);
+    const category = signerMissing
+        ? 'local_signer_missing'
+        : 'local_registry_write_failed';
+    return JSON.stringify({
+        success: false,
+        error: message,
+        retryable,
+        category,
+        hostedX402Charged: false,
+        agentInstruction: 'For SAP agent registration or profile updates from hosted-user setups, call sap_payments_register_agent or sap_payments_update_agent from the local sap_payments bridge. Do not retry hosted sap_register_agent/sap_update_agent after hosted_local_signer_required, and do not create temporary signing scripts or read keypair JSON.',
+        nextAction: signerMissing
+            ? 'Call sap_payments_readiness. If signerConfigured is false, run the SAP MCP wizard full setup or repair flow and restart the agent runtime.'
+            : 'Check the registry fields, local profile, SOL fee balance, and SAP program/RPC status. Retry the matching sap_payments registry tool only after explicit user confirmation.',
+    }, null, 2);
+}
+function formatFinalizeTransactionError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return JSON.stringify({
+        success: false,
+        error: message,
+        retryable: isRetryablePaymentError(message),
+        category: message.toLowerCase().includes('no local signer') || message.toLowerCase().includes('no signer')
+            ? 'local_signer_missing'
+            : 'local_transaction_finalization_failed',
+        agentInstruction: 'Do not create temporary signing scripts, do not read keypair JSON, and do not call hosted sap_sign_transaction for user-owned signatures. Use sap_payments_finalize_transaction from the local sap_payments bridge. For submit:true, prefer the default hosted submit relay unless the user explicitly requests local RPC submission.',
+        nextAction: 'Call sap_payments_readiness. If the local signer is ready, retry sap_payments_finalize_transaction with confirm: true, submit: true, and the same transaction only when retrySafe is true or the prior attempt never submitted. If readiness says missing bridge or signer, run the wizard repair flow.',
+    }, null, 2);
+}
 function isRetryablePaymentError(message) {
     const normalized = message.toLowerCase();
     const retryablePatterns = [