agentpay-mcp 1.2.0 → 4.0.0

package/dist/tools/session.js

@@ -0,0 +1,678 @@
+"use strict";
+/**
+ * session.ts — x402 V2 session payment tools.
+ *
+ * Implements the x402 V2 "wallet-based access & reusable sessions" pattern:
+ *   1. x402_session_start  — pay once, receive a signed session token
+ *   2. x402_session_fetch  — make N calls within the session (no new payments)
+ *   3. x402_session_status — inspect active sessions and TTL remaining
+ *   4. x402_session_end    — explicitly close a session
+ *
+ * Non-custodial design:
+ *   Agents sign session tokens locally with their private key.
+ *   No third party holds or validates keys at any point.
+ *   Session tokens are self-contained ECDSA-signed claims that any server
+ *   implementing x402 V2 can independently verify.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSessionHeaders = exports.findSessionForUrl = exports.x402SessionEndTool = exports.X402SessionEndSchema = exports.x402SessionStatusTool = exports.X402SessionStatusSchema = exports.x402SessionFetchTool = exports.X402SessionFetchSchema = exports.x402SessionStartTool = exports.X402SessionStartSchema = void 0;
+exports.handleX402SessionStart = handleX402SessionStart;
+exports.handleX402SessionFetch = handleX402SessionFetch;
+exports.handleX402SessionStatus = handleX402SessionStatus;
+exports.handleX402SessionEnd = handleX402SessionEnd;
+const zod_1 = require("zod");
+const agentwallet_sdk_1 = require("agentwallet-sdk");
+const client_js_1 = require("../utils/client.js");
+const format_js_1 = require("../utils/format.js");
+const manager_js_1 = require("../session/manager.js");
+Object.defineProperty(exports, "findSessionForUrl", { enumerable: true, get: function () { return manager_js_1.findSessionForUrl; } });
+Object.defineProperty(exports, "buildSessionHeaders", { enumerable: true, get: function () { return manager_js_1.buildSessionHeaders; } });
+// ─── x402_session_start ────────────────────────────────────────────────────
+exports.X402SessionStartSchema = zod_1.z.object({
+    endpoint: zod_1.z
+        .string()
+        .url()
+        .describe('The base URL or endpoint to establish a session for. ' +
+        'The agent pays once and the session covers all subsequent requests to this endpoint.'),
+    scope: zod_1.z
+        .enum(['prefix', 'exact'])
+        .optional()
+        .default('prefix')
+        .describe('"prefix" (default): session covers all paths under the endpoint URL. ' +
+        '"exact": session only covers this exact URL.'),
+    ttl_seconds: zod_1.z
+        .number()
+        .int()
+        .min(60)
+        .max(86400 * 30)
+        .optional()
+        .describe('Session lifetime in seconds (default: SESSION_TTL_SECONDS env var or 3600). ' +
+        'Min: 60 seconds. Max: 30 days.'),
+    label: zod_1.z
+        .string()
+        .max(100)
+        .optional()
+        .describe('Optional human-readable label for this session (e.g. "Premium API session")'),
+    max_payment_eth: zod_1.z
+        .string()
+        .optional()
+        .describe('Maximum ETH to pay for session establishment. Rejects if exceeded.'),
+    method: zod_1.z
+        .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+        .optional()
+        .default('GET')
+        .describe('HTTP method for the initial payment request (default: GET)'),
+    headers: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .describe('Additional headers for the session-start request'),
+    body: zod_1.z
+        .string()
+        .optional()
+        .describe('Request body for the initial session-start request (if POST/PUT/PATCH)'),
+    timeout_ms: zod_1.z
+        .number()
+        .int()
+        .min(1000)
+        .max(60000)
+        .optional()
+        .default(30000)
+        .describe('Request timeout in milliseconds (default: 30000)'),
+});
+exports.x402SessionStartTool = {
+    name: 'x402_session_start',
+    description: 'Establish an x402 V2 payment session: make a SINGLE on-chain payment and receive ' +
+        'a cryptographically signed session token. All subsequent calls to the same endpoint ' +
+        'within the session lifetime use x402_session_fetch — no additional payments required. ' +
+        'Agents pay once per session rather than once per API call. ' +
+        'Session tokens are signed locally by your wallet key (non-custodial). ' +
+        'Returns a session_id you pass to x402_session_fetch for all future calls.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            endpoint: {
+                type: 'string',
+                description: 'Base URL to establish a session for (e.g., "https://api.example.com/v1")',
+            },
+            scope: {
+                type: 'string',
+                enum: ['prefix', 'exact'],
+                description: '"prefix": covers all paths under this URL (default). "exact": single URL only.',
+                default: 'prefix',
+            },
+            ttl_seconds: {
+                type: 'number',
+                description: 'Session TTL in seconds (default: 3600 / 1 hour). Max: 30 days.',
+            },
+            label: {
+                type: 'string',
+                description: 'Optional label for this session (e.g., "Premium API session")',
+            },
+            max_payment_eth: {
+                type: 'string',
+                description: 'Maximum ETH to pay for this session. Rejects if price exceeds this.',
+            },
+            method: {
+                type: 'string',
+                enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+                description: 'HTTP method for the initial request (default: GET)',
+                default: 'GET',
+            },
+            headers: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                description: 'Additional request headers',
+            },
+            body: {
+                type: 'string',
+                description: 'Request body for POST/PUT/PATCH session-start requests',
+            },
+            timeout_ms: {
+                type: 'number',
+                description: 'Request timeout in milliseconds (default: 30000)',
+                default: 30000,
+            },
+        },
+        required: ['endpoint'],
+    },
+};
+async function handleX402SessionStart(input) {
+    try {
+        const wallet = (0, client_js_1.getWallet)();
+        const config = (0, client_js_1.getConfig)();
+        const timeoutMs = input.timeout_ms ?? 30000;
+        // Parse optional payment cap
+        let maxPaymentWei;
+        if (input.max_payment_eth) {
+            const cap = parseFloat(input.max_payment_eth);
+            if (isNaN(cap) || cap <= 0) {
+                throw new Error(`Invalid max_payment_eth: "${input.max_payment_eth}"`);
+            }
+            maxPaymentWei = BigInt(Math.round(cap * 1e18));
+        }
+        // Track payment
+        let paymentMade = false;
+        let paymentAmount = 0n;
+        let paymentTxHash = '';
+        let paymentRecipient = '';
+        let paymentToken = '0x0000000000000000000000000000000000000000';
+        // x402 client to handle the one-time session payment
+        const x402Client = (0, agentwallet_sdk_1.createX402Client)(wallet, {
+            autoPay: true,
+            maxRetries: 1,
+            globalPerRequestMax: maxPaymentWei,
+            onBeforePayment: (req) => {
+                const amount = BigInt(req.amount);
+                if (maxPaymentWei && amount > maxPaymentWei) {
+                    throw new Error(`Session payment (${amount} wei) exceeds max_payment_eth cap ` +
+                        `(${maxPaymentWei} wei = ${input.max_payment_eth} ETH). ` +
+                        `Set a higher max_payment_eth to proceed.`);
+                }
+                return true;
+            },
+            onPaymentComplete: (log) => {
+                paymentMade = true;
+                paymentAmount = log.amount;
+                paymentTxHash = log.txHash;
+                paymentRecipient = log.recipient;
+                paymentToken = log.token ?? '0x0000000000000000000000000000000000000000';
+            },
+        });
+        const method = input.method ?? 'GET';
+        const reqHeaders = {
+            'Accept': 'application/json, text/plain, */*',
+            ...(input.headers ?? {}),
+        };
+        if (input.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            if (!reqHeaders['Content-Type']) {
+                reqHeaders['Content-Type'] = 'application/json';
+            }
+        }
+        const requestInit = {
+            method,
+            headers: reqHeaders,
+            ...(input.body ? { body: input.body } : {}),
+            signal: AbortSignal.timeout(timeoutMs),
+        };
+        // Make the payment request
+        const response = await x402Client.fetch(input.endpoint, requestInit);
+        const responseText = await response.text();
+        if (!paymentMade) {
+            // Endpoint didn't require payment — still create a session if response was OK
+            // This allows agents to pre-establish sessions for endpoints that may start
+            // requiring payment, or to track usage even for free endpoints.
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`ℹ️ **No Payment Required**\n\n` +
+                        `  Endpoint: ${input.endpoint}\n` +
+                        `  Status:   ${response.status} ${response.statusText}\n\n` +
+                        `No x402 payment was needed. The endpoint responded without requiring payment.\n` +
+                        `You do not need a session token — use x402_pay directly for free endpoints.\n\n` +
+                        `📄 **Response Body**\n` +
+                        '```\n' + responseText.slice(0, 4000) + (responseText.length > 4000 ? '\n... [truncated]' : '') + '\n```'),
+                ],
+            };
+        }
+        // Create signed session record
+        // The signMessage function uses viem's wallet client, signing locally with the agent's key
+        const signMessage = async (message) => {
+            // Access the walletClient from the wallet instance for local signing
+            const wc = wallet.walletClient;
+            return wc.signMessage({ message });
+        };
+        const session = await (0, manager_js_1.createSession)({
+            endpoint: input.endpoint,
+            scope: input.scope ?? 'prefix',
+            ttlSeconds: input.ttl_seconds,
+            label: input.label,
+            paymentTxHash,
+            paymentAmount,
+            paymentToken,
+            paymentRecipient,
+            walletAddress: config.walletAddress,
+            signMessage,
+        });
+        const ttlRemaining = session.expiresAt - Math.floor(Date.now() / 1000);
+        const expiresAt = new Date(session.expiresAt * 1000).toISOString();
+        let out = `🔐 **x402 Session Established**\n\n`;
+        out += `  Session ID:    ${session.sessionId}\n`;
+        out += `  Endpoint:      ${session.endpoint}\n`;
+        out += `  Scope:         ${session.scope}\n`;
+        if (session.label)
+            out += `  Label:         ${session.label}\n`;
+        out += `  Network:       ${(0, format_js_1.chainName)(config.chainId)}\n`;
+        out += `  TTL:           ${Math.ceil(ttlRemaining / 60)}m (expires ${expiresAt})\n\n`;
+        out += `💳 **Session Payment**\n`;
+        out += `  Amount:    ${paymentAmount.toString()} (base units)\n`;
+        out += `  Recipient: ${paymentRecipient}\n`;
+        out += `  TX Hash:   ${paymentTxHash}\n\n`;
+        out += `✅ **Next Steps**\n`;
+        out += `  Use \`x402_session_fetch\` with session_id="${session.sessionId}" for all subsequent\n`;
+        out += `  requests to ${input.endpoint} — no further payments will be made during this session.\n`;
+        out += `  Check session status with \`x402_session_status\`.\n\n`;
+        out += `📄 **Initial Response** (${response.status})\n`;
+        const truncated = responseText.length > 4000;
+        out += '```\n' + responseText.slice(0, 4000) + (truncated ? '\n... [truncated]' : '') + '\n```';
+        return { content: [(0, format_js_1.textContent)(out)] };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            return {
+                content: [(0, format_js_1.textContent)(`❌ x402_session_start failed: Request timed out after ${input.timeout_ms ?? 30000}ms`)],
+                isError: true,
+            };
+        }
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'x402_session_start'))],
+            isError: true,
+        };
+    }
+}
+// ─── x402_session_fetch ────────────────────────────────────────────────────
+exports.X402SessionFetchSchema = zod_1.z.object({
+    session_id: zod_1.z
+        .string()
+        .uuid()
+        .describe('Session ID returned by x402_session_start.'),
+    url: zod_1.z
+        .string()
+        .url()
+        .describe('URL to fetch within the session. Must be covered by the session endpoint/scope.'),
+    method: zod_1.z
+        .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+        .optional()
+        .default('GET')
+        .describe('HTTP method (default: GET)'),
+    headers: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .describe('Additional HTTP headers (session token is injected automatically)'),
+    body: zod_1.z
+        .string()
+        .optional()
+        .describe('Request body for POST/PUT/PATCH requests'),
+    timeout_ms: zod_1.z
+        .number()
+        .int()
+        .min(1000)
+        .max(60000)
+        .optional()
+        .default(30000)
+        .describe('Request timeout in milliseconds (default: 30000)'),
+});
+exports.x402SessionFetchTool = {
+    name: 'x402_session_fetch',
+    description: 'Make an HTTP request within an established x402 V2 session — NO payment required. ' +
+        'The session token (signed by your wallet) is automatically attached to the request. ' +
+        'The server recognises your session and grants access without a new on-chain payment. ' +
+        'Requires a session_id from x402_session_start. ' +
+        'Returns an error if the session has expired (call x402_session_start again to renew).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: {
+                type: 'string',
+                description: 'Session ID from x402_session_start',
+            },
+            url: {
+                type: 'string',
+                description: 'URL to fetch (must be covered by the session)',
+            },
+            method: {
+                type: 'string',
+                enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+                description: 'HTTP method (default: GET)',
+                default: 'GET',
+            },
+            headers: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                description: 'Additional headers (session token is injected automatically)',
+            },
+            body: {
+                type: 'string',
+                description: 'Request body for POST/PUT/PATCH',
+            },
+            timeout_ms: {
+                type: 'number',
+                description: 'Timeout in milliseconds (default: 30000)',
+                default: 30000,
+            },
+        },
+        required: ['session_id', 'url'],
+    },
+};
+async function handleX402SessionFetch(input) {
+    try {
+        const timeoutMs = input.timeout_ms ?? 30000;
+        // Look up session
+        const lookup = (0, manager_js_1.lookupSession)(input.session_id);
+        if (!lookup.found) {
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`❌ Session not found: "${input.session_id}"\n\n` +
+                        `Create a new session with x402_session_start first.`),
+                ],
+                isError: true,
+            };
+        }
+        if (lookup.expired) {
+            const expiredAt = new Date(lookup.session.expiresAt * 1000).toISOString();
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`⏰ **Session Expired**\n\n` +
+                        `  Session ID: ${input.session_id}\n` +
+                        `  Endpoint:   ${lookup.session.endpoint}\n` +
+                        `  Expired at: ${expiredAt}\n\n` +
+                        `Call x402_session_start to establish a new session for this endpoint.`),
+                ],
+                isError: true,
+            };
+        }
+        const { session } = lookup;
+        // Validate URL is covered by the session scope
+        const urlCovered = isUrlCoveredBySession(input.url, session);
+        if (!urlCovered) {
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`❌ URL not covered by this session.\n\n` +
+                        `  Session endpoint: ${session.endpoint}\n` +
+                        `  Session scope:    ${session.scope}\n` +
+                        `  Requested URL:    ${input.url}\n\n` +
+                        `This URL is outside the session's ${session.scope === 'exact' ? 'exact match' : 'prefix match'} scope.\n` +
+                        `Create a new session for this URL with x402_session_start, or use x402_pay for a one-time request.`),
+                ],
+                isError: true,
+            };
+        }
+        // Build request headers — inject session token automatically
+        const sessionHeaders = (0, manager_js_1.buildSessionHeaders)(session);
+        const method = input.method ?? 'GET';
+        const mergedHeaders = {
+            'Accept': 'application/json, text/plain, */*',
+            ...sessionHeaders,
+            ...(input.headers ?? {}),
+        };
+        if (input.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            if (!mergedHeaders['Content-Type']) {
+                mergedHeaders['Content-Type'] = 'application/json';
+            }
+        }
+        const requestInit = {
+            method,
+            headers: mergedHeaders,
+            ...(input.body ? { body: input.body } : {}),
+            signal: AbortSignal.timeout(timeoutMs),
+        };
+        // Make request — plain fetch, NO x402 payment client
+        // The session token headers tell the server to bypass the payment flow
+        const response = await fetch(input.url, requestInit);
+        const responseText = await response.text();
+        // Record the call in the session
+        (0, manager_js_1.recordSessionCall)(input.session_id);
+        // Handle edge case: server still returned 402 (session not recognised)
+        if (response.status === 402) {
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`⚠️ **Server returned 402 — Session Not Recognised**\n\n` +
+                        `  URL:        ${input.url}\n` +
+                        `  Session ID: ${input.session_id}\n\n` +
+                        `The server returned HTTP 402 despite session headers being sent.\n` +
+                        `This means the server does not support x402 V2 session tokens yet,\n` +
+                        `or the session has been invalidated server-side.\n\n` +
+                        `Options:\n` +
+                        `  • Use x402_pay for a one-time payment to this URL\n` +
+                        `  • Contact the API provider about x402 V2 session support\n\n` +
+                        `📄 **Response Body**\n` +
+                        '```\n' + responseText.slice(0, 2000) + '\n```'),
+                ],
+                isError: true,
+            };
+        }
+        // Truncate very large responses
+        const MAX_LEN = 8000;
+        const truncated = responseText.length > MAX_LEN;
+        const displayText = truncated
+            ? responseText.slice(0, MAX_LEN) + '\n\n... [response truncated]'
+            : responseText;
+        const ttlRemaining = session.expiresAt - Math.floor(Date.now() / 1000);
+        const callNumber = session.callCount; // after recordSessionCall incremented it
+        let out = `⚡ **x402 Session Fetch** (call #${callNumber})\n\n`;
+        out += `  Session ID:  ${session.sessionId}\n`;
+        if (session.label)
+            out += `  Label:       ${session.label}\n`;
+        out += `  URL:         ${input.url}\n`;
+        out += `  Method:      ${method}\n`;
+        out += `  Status:      ${response.status} ${response.statusText}\n`;
+        out += `  Session TTL: ${Math.ceil(ttlRemaining / 60)}m remaining\n`;
+        out += `  💰 No payment — session token used\n\n`;
+        out += `📄 **Response Body**\n`;
+        out += '```\n' + displayText + '\n```';
+        return { content: [(0, format_js_1.textContent)(out)] };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            return {
+                content: [(0, format_js_1.textContent)(`❌ x402_session_fetch failed: Request timed out after ${input.timeout_ms ?? 30000}ms`)],
+                isError: true,
+            };
+        }
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'x402_session_fetch'))],
+            isError: true,
+        };
+    }
+}
+// ─── x402_session_status ──────────────────────────────────────────────────
+exports.X402SessionStatusSchema = zod_1.z.object({
+    session_id: zod_1.z
+        .string()
+        .optional()
+        .describe('Specific session ID to inspect. ' +
+        'Omit to list all active sessions.'),
+});
+exports.x402SessionStatusTool = {
+    name: 'x402_session_status',
+    description: 'Check the status of x402 V2 payment sessions. ' +
+        'Without arguments, lists all active sessions with TTL remaining. ' +
+        'With a session_id, shows full details for that session including ' +
+        'call count, payment info, and the signed session token.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: {
+                type: 'string',
+                description: 'Specific session ID to inspect. Omit to list all active sessions.',
+            },
+        },
+        required: [],
+    },
+};
+async function handleX402SessionStatus(input) {
+    try {
+        const now = Math.floor(Date.now() / 1000);
+        if (input.session_id) {
+            // Detailed view for a specific session
+            const lookup = (0, manager_js_1.lookupSession)(input.session_id);
+            if (!lookup.found) {
+                return {
+                    content: [
+                        (0, format_js_1.textContent)(`❌ Session not found: "${input.session_id}"\n\n` +
+                            `Use x402_session_status (no arguments) to list active sessions.`),
+                    ],
+                    isError: true,
+                };
+            }
+            const { session, expired } = lookup;
+            const ttlRemaining = Math.max(0, session.expiresAt - now);
+            const decoded = (0, manager_js_1.decodeSessionToken)(session.sessionToken);
+            let out = expired
+                ? `⏰ **Session Expired**\n\n`
+                : `🔐 **Session Details**\n\n`;
+            out += `  Session ID:    ${session.sessionId}\n`;
+            if (session.label)
+                out += `  Label:         ${session.label}\n`;
+            out += `  Status:        ${expired ? '❌ Expired' : '✅ Active'}\n`;
+            out += `  Endpoint:      ${session.endpoint}\n`;
+            out += `  Scope:         ${session.scope}\n`;
+            out += `  Wallet:        ${session.walletAddress}\n\n`;
+            out += `⏱️  **Timing**\n`;
+            out += `  Created:       ${new Date(session.createdAt * 1000).toISOString()}\n`;
+            out += `  Expires:       ${new Date(session.expiresAt * 1000).toISOString()}\n`;
+            if (!expired)
+                out += `  TTL Remaining: ${formatTtl(ttlRemaining)}\n`;
+            out += `  Last Used:     ${session.lastUsedAt > 0 ? new Date(session.lastUsedAt * 1000).toISOString() : 'Never'}\n`;
+            out += `  Call Count:    ${session.callCount}\n\n`;
+            out += `💳 **Session Payment**\n`;
+            out += `  TX Hash:       ${session.paymentTxHash}\n`;
+            out += `  Amount:        ${session.paymentAmount} (base units)\n`;
+            out += `  Recipient:     ${session.paymentRecipient}\n`;
+            out += `  Token:         ${session.paymentToken === '0x0000000000000000000000000000000000000000' ? 'ETH (native)' : session.paymentToken}\n\n`;
+            if (decoded) {
+                out += `🔏 **Token Info**\n`;
+                out += `  Protocol:      ${decoded.payload.version}\n`;
+                out += `  Signature:     ${decoded.signature.slice(0, 20)}...${decoded.signature.slice(-8)}\n`;
+            }
+            return { content: [(0, format_js_1.textContent)(out)] };
+        }
+        // List all active sessions
+        const active = (0, manager_js_1.listActiveSessions)();
+        if (active.length === 0) {
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`📋 **Active Sessions**\n\n` +
+                        `No active sessions. Use x402_session_start to establish a session.\n\n` +
+                        `ℹ️  Sessions are stored in-process and survive for their configured TTL.\n` +
+                        `   Default TTL: 3600 seconds (1 hour). Set SESSION_TTL_SECONDS to override.`),
+                ],
+            };
+        }
+        let out = `📋 **Active x402 Sessions** (${active.length})\n\n`;
+        for (const session of active) {
+            const ttlRemaining = Math.max(0, session.expiresAt - now);
+            const ttlBar = ttlProgressBar(ttlRemaining, session.expiresAt - session.createdAt);
+            out += `─────────────────────────────────────\n`;
+            out += `  ID:       ${session.sessionId}\n`;
+            if (session.label)
+                out += `  Label:    ${session.label}\n`;
+            out += `  Endpoint: ${session.endpoint}\n`;
+            out += `  Scope:    ${session.scope}\n`;
+            out += `  TTL:      ${formatTtl(ttlRemaining)} ${ttlBar}\n`;
+            out += `  Calls:    ${session.callCount}\n`;
+            out += `  Payment:  ${session.paymentAmount} base units → TX ${session.paymentTxHash.slice(0, 18)}...\n`;
+            out += '\n';
+        }
+        out += `\nUse x402_session_fetch with a session_id to make free calls within a session.\n`;
+        out += `Use x402_session_status with session_id="..." for full session details.`;
+        return { content: [(0, format_js_1.textContent)(out)] };
+    }
+    catch (error) {
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'x402_session_status'))],
+            isError: true,
+        };
+    }
+}
+// ─── x402_session_end ─────────────────────────────────────────────────────
+exports.X402SessionEndSchema = zod_1.z.object({
+    session_id: zod_1.z
+        .string()
+        .uuid()
+        .describe('Session ID to close.'),
+});
+exports.x402SessionEndTool = {
+    name: 'x402_session_end',
+    description: 'Explicitly close an x402 V2 session before it expires naturally. ' +
+        'After calling this, x402_session_fetch will return an error for the closed session. ' +
+        'Useful for security hygiene or when you know a session is no longer needed.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: {
+                type: 'string',
+                description: 'Session ID to close (from x402_session_start)',
+            },
+        },
+        required: ['session_id'],
+    },
+};
+async function handleX402SessionEnd(input) {
+    try {
+        const lookup = (0, manager_js_1.lookupSession)(input.session_id);
+        if (!lookup.found) {
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`❌ Session not found: "${input.session_id}"`),
+                ],
+                isError: true,
+            };
+        }
+        if (lookup.expired) {
+            return {
+                content: [
+                    (0, format_js_1.textContent)(`ℹ️ Session "${input.session_id}" was already expired.\n` +
+                        `Endpoint: ${lookup.session.endpoint}`),
+                ],
+            };
+        }
+        const { session } = lookup;
+        (0, manager_js_1.endSession)(input.session_id);
+        return {
+            content: [
+                (0, format_js_1.textContent)(`✅ **Session Closed**\n\n` +
+                    `  Session ID: ${session.sessionId}\n` +
+                    `  Endpoint:   ${session.endpoint}\n` +
+                    `  Calls made: ${session.callCount}\n\n` +
+                    `The session has been closed and can no longer be used.\n` +
+                    `Use x402_session_start to establish a new session when needed.`),
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'x402_session_end'))],
+            isError: true,
+        };
+    }
+}
+// ─── Internal helpers ──────────────────────────────────────────────────────
+/**
+ * Check if a URL is covered by a session's endpoint + scope.
+ */
+function isUrlCoveredBySession(url, session) {
+    if (session.scope === 'exact') {
+        return url === session.endpoint;
+    }
+    // Prefix: URL must start with endpoint
+    // Normalise: ensure endpoint doesn't end in slash for prefix matching
+    const base = session.endpoint.endsWith('/') ? session.endpoint : session.endpoint + '/';
+    return url === session.endpoint || url.startsWith(base) || url.startsWith(session.endpoint + '?');
+}
+/**
+ * Format TTL seconds as a human-readable string.
+ */
+function formatTtl(seconds) {
+    if (seconds <= 0)
+        return 'Expired';
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}
+/**
+ * Generate a simple ASCII progress bar for TTL remaining.
+ */
+function ttlProgressBar(remaining, total) {
+    if (total <= 0)
+        return '';
+    const pct = Math.max(0, Math.min(1, remaining / total));
+    const filled = Math.round(pct * 10);
+    const empty = 10 - filled;
+    const bar = '█'.repeat(filled) + '░'.repeat(empty);
+    const emoji = pct > 0.5 ? '🟢' : pct > 0.2 ? '🟡' : '🔴';
+    return `${emoji} [${bar}]`;
+}
+//# sourceMappingURL=session.js.map