@azeth/mcp-server 0.2.0

package/dist/tools/guardian.js

@@ -0,0 +1,267 @@
+import { z } from 'zod';
+import { formatUnits } from 'viem';
+import { AZETH_CONTRACTS, TOKENS } from '@azeth/common';
+import { GuardianModuleAbi } from '@azeth/common/abis';
+import { createClient, resolveChain, validateAddress } from '../utils/client.js';
+import { resolveSmartAccount } from '../utils/resolve.js';
+import { success, error, handleError, guardianRequiredError } from '../utils/response.js';
+/** Register guardian MCP tools: azeth_get_guardrails, azeth_whitelist_protocol */
+export function registerGuardianTools(server) {
+    // ──────────────────────────────────────────────
+    // azeth_get_guardrails
+    // ──────────────────────────────────────────────
+    server.registerTool('azeth_get_guardrails', {
+        description: [
+            'View the guardian security configuration for a smart account.',
+            '',
+            'Use this when: You want to check spending limits, token/protocol whitelists,',
+            'daily spend tracking, emergency withdrawal status, or pending guardrail changes.',
+            '',
+            'Returns: Full guardian state including spending limits (USD), whitelisted tokens',
+            'and protocols, daily spend progress, and any pending timelock changes.',
+            '',
+            'This is read-only and safe to call at any time.',
+            '',
+            'Example: { "smartAccount": "me" }',
+        ].join('\n'),
+        inputSchema: z.object({
+            chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
+            smartAccount: z.string().optional().describe('Smart account to inspect. Accepts address, "me", "#N", or account name. Defaults to first account.'),
+        }),
+    }, async (args) => {
+        let client;
+        try {
+            client = await createClient(args.chain);
+            // Resolve smart account (defaults to first)
+            let account;
+            if (args.smartAccount) {
+                try {
+                    account = (await resolveSmartAccount(args.smartAccount, client));
+                }
+                catch (resolveErr) {
+                    return handleError(resolveErr);
+                }
+            }
+            else {
+                account = await client.resolveSmartAccount();
+            }
+            const chain = resolveChain(args.chain);
+            const guardianAddr = AZETH_CONTRACTS[chain].guardianModule;
+            // Parallel reads for efficiency: guardrails, daily spend, pending changes
+            const [guardrails, dailySpentUSD, pendingChange, pendingEmergency] = await Promise.all([
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'getGuardrails',
+                    args: [account],
+                }),
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'getDailySpentUSD',
+                    args: [account],
+                }),
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'getPendingChange',
+                    args: [account],
+                }),
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'getPendingEmergency',
+                    args: [account],
+                }),
+            ]);
+            // Check common token whitelists (ETH, USDC, WETH)
+            const ETH = '0x0000000000000000000000000000000000000000';
+            const usdc = TOKENS[chain].USDC;
+            const weth = TOKENS[chain].WETH;
+            // Check common protocol whitelists (Azeth modules)
+            const paymentAgreementModule = AZETH_CONTRACTS[chain].paymentAgreementModule;
+            const reputationModule = AZETH_CONTRACTS[chain].reputationModule;
+            const [ethWhitelisted, usdcWhitelisted, wethWhitelisted, paymentAgreementWhitelisted, reputationWhitelisted,] = await Promise.all([
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'isTokenWhitelisted',
+                    args: [account, ETH],
+                }),
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'isTokenWhitelisted',
+                    args: [account, usdc],
+                }),
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'isTokenWhitelisted',
+                    args: [account, weth],
+                }),
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'isProtocolWhitelisted',
+                    args: [account, paymentAgreementModule],
+                }),
+                client.publicClient.readContract({
+                    address: guardianAddr,
+                    abi: GuardianModuleAbi,
+                    functionName: 'isProtocolWhitelisted',
+                    args: [account, reputationModule],
+                }),
+            ]);
+            // Format the Guardrails struct (6 fields from ABI)
+            const g = guardrails;
+            const dailySpent = dailySpentUSD;
+            const dailyLimit = g.dailySpendLimitUSD;
+            const dailyRemaining = dailyLimit > dailySpent ? dailyLimit - dailySpent : 0n;
+            const dailyPercentUsed = dailyLimit > 0n
+                ? Number((dailySpent * 10000n) / dailyLimit) / 100
+                : 0;
+            // Format pending change
+            const pc = pendingChange;
+            const pe = pendingEmergency;
+            const now = BigInt(Math.floor(Date.now() / 1000));
+            return success({
+                account,
+                spendingLimits: {
+                    maxTransactionUSD: `$${formatUnits(g.maxTxAmountUSD, 18)}`,
+                    dailySpendLimitUSD: `$${formatUnits(dailyLimit, 18)}`,
+                    dailySpentUSD: `$${formatUnits(dailySpent, 18)}`,
+                    dailyRemainingUSD: `$${formatUnits(dailyRemaining, 18)}`,
+                    dailyPercentUsed: `${dailyPercentUsed.toFixed(1)}%`,
+                },
+                guardianLimits: {
+                    guardianMaxTransactionUSD: `$${formatUnits(g.guardianMaxTxAmountUSD, 18)}`,
+                    guardianDailySpendLimitUSD: `$${formatUnits(g.guardianDailySpendLimitUSD, 18)}`,
+                },
+                guardian: g.guardian,
+                emergencyWithdrawTo: g.emergencyWithdrawTo,
+                tokenWhitelist: {
+                    ETH: ethWhitelisted,
+                    USDC: usdcWhitelisted,
+                    WETH: wethWhitelisted,
+                },
+                protocolWhitelist: {
+                    PaymentAgreementModule: paymentAgreementWhitelisted,
+                    ReputationModule: reputationWhitelisted,
+                },
+                pendingGuardrailChange: pc.exists ? {
+                    changeHash: pc.changeHash,
+                    executeAfter: new Date(Number(pc.executeAfter) * 1000).toISOString(),
+                    readyIn: pc.executeAfter > now
+                        ? `${Math.ceil(Number(pc.executeAfter - now) / 60)} minutes`
+                        : 'READY to execute',
+                } : null,
+                pendingEmergencyWithdrawal: pe.exists ? {
+                    token: pe.token,
+                    executeAfter: new Date(Number(pe.executeAfter) * 1000).toISOString(),
+                    readyIn: pe.executeAfter > now
+                        ? `${Math.ceil(Number(pe.executeAfter - now) / 60)} minutes`
+                        : 'READY to execute',
+                } : null,
+            });
+        }
+        catch (err) {
+            return handleError(err);
+        }
+        finally {
+            try {
+                await client?.destroy();
+            }
+            catch (e) {
+                process.stderr.write(`[azeth-mcp] destroy error: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
+        }
+    });
+    // ──────────────────────────────────────────────
+    // azeth_whitelist_protocol
+    // ──────────────────────────────────────────────
+    server.registerTool('azeth_whitelist_protocol', {
+        description: [
+            'Add or remove a protocol (contract address) from your smart account\'s guardian whitelist.',
+            '',
+            'Use this when: You need to interact with a new DeFi protocol or contract through',
+            'executor modules (like PaymentAgreementModule). Protocols must be whitelisted for',
+            'automated operations to succeed.',
+            '',
+            'The "protocol" field must be a valid Ethereum address of the contract to whitelist.',
+            '',
+            'Returns: Confirmation of the whitelist update with transaction hash.',
+            '',
+            'Note: This requires a UserOperation (gas). Only the account owner can modify whitelists.',
+            'Whitelisting a protocol allows executor modules to interact with it on your behalf.',
+            'Whitelist additions require guardian co-signature for security.',
+            '',
+            'Example: { "protocol": "0x71D52798e3D0f5766f6f0AFEd6710EB5D1FF4DF9", "allowed": true }',
+        ].join('\n'),
+        inputSchema: z.object({
+            chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
+            protocol: z.string().describe('Protocol/contract address to whitelist or delist (0x...).'),
+            allowed: z.boolean().describe('true to whitelist, false to remove from whitelist.'),
+            smartAccount: z.string().optional().describe('Smart account address, name, or "#N". Defaults to first smart account.'),
+        }),
+    }, async (args) => {
+        if (!validateAddress(args.protocol)) {
+            return error('INVALID_INPUT', `Invalid protocol address: "${args.protocol}".`, 'Must be 0x-prefixed followed by 40 hex characters.');
+        }
+        let client;
+        try {
+            client = await createClient(args.chain);
+            let account;
+            if (args.smartAccount) {
+                try {
+                    account = (await resolveSmartAccount(args.smartAccount, client));
+                }
+                catch (resolveErr) {
+                    return handleError(resolveErr);
+                }
+            }
+            else {
+                account = await client.resolveSmartAccount();
+            }
+            const txHash = await client.setProtocolWhitelist(args.protocol, args.allowed, account);
+            const action = args.allowed ? 'whitelisted' : 'removed from whitelist';
+            // Resolve protocol name for known Azeth contracts
+            const chain = resolveChain(args.chain);
+            const contracts = AZETH_CONTRACTS[chain];
+            const protocolLower = args.protocol.toLowerCase();
+            let protocolName = args.protocol.slice(0, 6) + '...' + args.protocol.slice(-4);
+            if (protocolLower === contracts.paymentAgreementModule.toLowerCase())
+                protocolName = 'PaymentAgreementModule';
+            else if (protocolLower === contracts.reputationModule.toLowerCase())
+                protocolName = 'ReputationModule';
+            else if (protocolLower === contracts.trustRegistryModule.toLowerCase())
+                protocolName = 'TrustRegistryModule';
+            else if (protocolLower === contracts.guardianModule.toLowerCase())
+                protocolName = 'GuardianModule';
+            else if (protocolLower === contracts.factory.toLowerCase())
+                protocolName = 'AzethFactory';
+            return success({
+                protocol: args.protocol,
+                protocolName,
+                allowed: args.allowed,
+                message: `${protocolName} (${args.protocol}) ${action} on account ${account}.`,
+            }, { txHash });
+        }
+        catch (err) {
+            // Detect AA24 signature validation failure — common for guardian-gated operations
+            if (err instanceof Error && /AA24/.test(err.message)) {
+                return guardianRequiredError('Protocol whitelisting requires guardian co-signature (guardrail-loosening change).', { operation: 'whitelist_protocol' });
+            }
+            return handleError(err);
+        }
+        finally {
+            try {
+                await client?.destroy();
+            }
+            catch (e) {
+                process.stderr.write(`[azeth-mcp] destroy error: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
+        }
+    });
+}
+//# sourceMappingURL=guardian.js.map

package/dist/tools/guardian.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardian.js","sourceRoot":"","sources":["../../src/tools/guardian.ts"],"names":[],"mappings":"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"}

package/dist/tools/messaging.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Register XMTP messaging MCP tools: azeth_send_message, azeth_check_reachability, azeth_receive_messages, azeth_list_conversations, azeth_discover_agent_capabilities */
+export declare function registerMessagingTools(server: McpServer): void;
+//# sourceMappingURL=messaging.d.ts.map

package/dist/tools/messaging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../src/tools/messaging.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,2KAA2K;AAC3K,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0W9D"}

package/dist/tools/messaging.js

@@ -0,0 +1,353 @@
+import { z } from 'zod';
+import { createClient } from '../utils/client.js';
+import { resolveAddress } from '../utils/resolve.js';
+import { success, error, handleError } from '../utils/response.js';
+/** Register XMTP messaging MCP tools: azeth_send_message, azeth_check_reachability, azeth_receive_messages, azeth_list_conversations, azeth_discover_agent_capabilities */
+export function registerMessagingTools(server) {
+    // ──────────────────────────────────────────────
+    // azeth_send_message
+    // ──────────────────────────────────────────────
+    server.registerTool('azeth_send_message', {
+        description: [
+            'Send an encrypted message to another participant via the XMTP messaging network.',
+            '',
+            'Use this when: You need to communicate with another agent or service using end-to-end encrypted messaging.',
+            'The recipient must be reachable on the XMTP network (use azeth_check_reachability first if unsure).',
+            '',
+            'The "to" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).',
+            '',
+            'Returns: The conversation ID and recipient address confirming delivery.',
+            '',
+            'Note: This is NOT idempotent — each call sends a new message. The sender account is determined',
+            'by the AZETH_PRIVATE_KEY environment variable. Messages are limited to 10,000 characters.',
+            '',
+            'Example: { "to": "Alice", "content": "Hello, I would like to use your price-feed service." }',
+        ].join('\n'),
+        inputSchema: z.object({
+            chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
+            to: z.string().describe('Recipient: Ethereum address, participant name, "me", or "#N" (account index).'),
+            content: z.string().min(1).max(10_000).describe('Message text content (1-10,000 characters).'),
+            contentType: z.string().max(100).optional().describe('Content type hint. Defaults to "text/plain".'),
+        }),
+    }, async (args) => {
+        let client;
+        try {
+            client = await createClient(args.chain);
+            // Resolve "to": address, name, "me", "#N"
+            let toResolved;
+            try {
+                toResolved = await resolveAddress(args.to, client);
+            }
+            catch (resolveErr) {
+                return handleError(resolveErr);
+            }
+            const conversationId = await client.sendMessage({
+                to: toResolved.address,
+                content: args.content,
+                contentType: args.contentType,
+            });
+            return success({
+                conversationId,
+                to: toResolved.address,
+                ...(toResolved.resolvedFrom ? { resolvedTo: `"${toResolved.resolvedFrom}" → ${toResolved.address}` } : {}),
+                sent: true,
+            });
+        }
+        catch (err) {
+            return handleError(err);
+        }
+        finally {
+            try {
+                await client?.destroy();
+            }
+            catch { /* M-10: prevent destroy from masking the original error */ }
+        }
+    });
+    // ──────────────────────────────────────────────
+    // azeth_check_reachability
+    // ──────────────────────────────────────────────
+    server.registerTool('azeth_check_reachability', {
+        description: [
+            'Check if an Ethereum address is reachable on the XMTP messaging network.',
+            '',
+            'Use this when: You want to verify a participant can receive XMTP messages before sending.',
+            'This is a read-like operation and safe to retry.',
+            '',
+            'The "address" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).',
+            '',
+            'Returns: The address and whether it is reachable (boolean).',
+            '',
+            'Note: Reachability is cached for 5 minutes. An address is reachable if it has an active XMTP identity.',
+            'The checking account is determined by the AZETH_PRIVATE_KEY environment variable.',
+            '',
+            'Example: { "address": "Alice" } or { "address": "0x1234567890abcdef1234567890abcdef12345678" }',
+        ].join('\n'),
+        inputSchema: z.object({
+            chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
+            address: z.string().describe('Address to check: Ethereum address, participant name, "me", or "#N".'),
+        }),
+    }, async (args) => {
+        let client;
+        try {
+            client = await createClient(args.chain);
+            // Resolve address: address, name, "me", "#N"
+            let resolved;
+            try {
+                resolved = await resolveAddress(args.address, client);
+            }
+            catch (resolveErr) {
+                return handleError(resolveErr);
+            }
+            const reachable = await client.canReach(resolved.address);
+            return success({
+                address: resolved.address,
+                ...(resolved.resolvedFrom ? { resolvedFrom: `"${resolved.resolvedFrom}" → ${resolved.address}` } : {}),
+                reachable,
+            });
+        }
+        catch (err) {
+            return handleError(err);
+        }
+        finally {
+            try {
+                await client?.destroy();
+            }
+            catch { /* M-10: prevent destroy from masking the original error */ }
+        }
+    });
+    // ──────────────────────────────────────────────
+    // azeth_receive_messages
+    // ──────────────────────────────────────────────
+    server.registerTool('azeth_receive_messages', {
+        description: [
+            'Read incoming encrypted messages from the XMTP messaging network.',
+            '',
+            'Use this when: You want to check for messages from other agents or services.',
+            'This is the "inbox" view — it lets you read what others have sent you.',
+            '',
+            'Two modes:',
+            '  1. With "from": Read messages from a specific sender (up to "limit" messages)',
+            '  2. Without "from": Read the latest message from each conversation (inbox overview)',
+            '',
+            'The "from" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).',
+            '',
+            'Returns: Array of messages with sender address, content, timestamp, and conversation ID.',
+            '',
+            'Note: XMTP messages are end-to-end encrypted. The account reading messages is determined',
+            'by the AZETH_PRIVATE_KEY environment variable. First call may be slow due to XMTP initialization.',
+            '',
+            'Example: { "from": "Alice", "limit": 10 } or { } (all conversations)',
+        ].join('\n'),
+        inputSchema: z.object({
+            chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
+            from: z.string().optional().describe('Read messages from a specific sender. Accepts: address, name, "me", "#N". Omit for inbox overview.'),
+            limit: z.coerce.number().int().min(1).max(100).optional().describe('Maximum messages to return. Defaults to 20. Max 100.'),
+        }),
+    }, async (args) => {
+        let client;
+        try {
+            client = await createClient(args.chain);
+            const limit = args.limit ?? 20;
+            if (args.from) {
+                // Mode 1: Messages from specific sender
+                let fromResolved;
+                try {
+                    fromResolved = await resolveAddress(args.from, client);
+                }
+                catch (resolveErr) {
+                    return handleError(resolveErr);
+                }
+                const messages = await client.getMessages(fromResolved.address, limit);
+                return success({
+                    from: fromResolved.address,
+                    ...(fromResolved.resolvedFrom ? { resolvedFrom: `"${fromResolved.resolvedFrom}" → ${fromResolved.address}` } : {}),
+                    messageCount: messages.length,
+                    messages: messages.map(msg => ({
+                        sender: msg.sender,
+                        content: msg.content,
+                        timestamp: new Date(msg.timestamp).toISOString(),
+                        conversationId: msg.conversationId,
+                    })),
+                });
+            }
+            else {
+                // Mode 2: Inbox overview — latest message per conversation
+                const conversations = await client.getConversations();
+                // For each conversation, get the latest message
+                const inbox = [];
+                for (const conv of conversations.slice(0, limit)) {
+                    try {
+                        const messages = await client.getMessages(conv.peerAddress, 1);
+                        inbox.push({
+                            conversationId: conv.id,
+                            peerAddress: conv.peerAddress,
+                            createdAt: new Date(conv.createdAt).toISOString(),
+                            latestMessage: messages.length > 0 ? {
+                                content: messages[0].content,
+                                sender: messages[0].sender,
+                                timestamp: new Date(messages[0].timestamp).toISOString(),
+                            } : null,
+                        });
+                    }
+                    catch {
+                        // Skip conversations that fail to load
+                        inbox.push({
+                            conversationId: conv.id,
+                            peerAddress: conv.peerAddress,
+                            createdAt: new Date(conv.createdAt).toISOString(),
+                            latestMessage: null,
+                        });
+                    }
+                }
+                return success({
+                    conversationCount: conversations.length,
+                    showing: inbox.length,
+                    inbox,
+                });
+            }
+        }
+        catch (err) {
+            return handleError(err);
+        }
+        finally {
+            try {
+                await client?.destroy();
+            }
+            catch { /* M-10: prevent destroy from masking the original error */ }
+        }
+    });
+    // ──────────────────────────────────────────────
+    // azeth_list_conversations
+    // ──────────────────────────────────────────────
+    server.registerTool('azeth_list_conversations', {
+        description: [
+            'List all active XMTP messaging conversations.',
+            '',
+            'Use this when: You want to see who you have been communicating with,',
+            'or check if a conversation exists with a specific peer.',
+            '',
+            'Returns: Array of conversations with peer address and creation time.',
+            '',
+            'Note: First call may be slow due to XMTP initialization.',
+            '',
+            'Example: { }',
+        ].join('\n'),
+        inputSchema: z.object({
+            chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
+        }),
+    }, async (args) => {
+        let client;
+        try {
+            client = await createClient(args.chain);
+            const conversations = await client.getConversations();
+            return success({
+                conversationCount: conversations.length,
+                conversations: conversations.map(conv => ({
+                    id: conv.id,
+                    peerAddress: conv.peerAddress,
+                    createdAt: new Date(conv.createdAt).toISOString(),
+                })),
+            });
+        }
+        catch (err) {
+            return handleError(err);
+        }
+        finally {
+            try {
+                await client?.destroy();
+            }
+            catch { /* M-10: prevent destroy from masking the original error */ }
+        }
+    });
+    // ──────────────────────────────────────────────
+    // azeth_discover_agent_capabilities
+    // ──────────────────────────────────────────────
+    server.registerTool('azeth_discover_agent_capabilities', {
+        description: [
+            'Discover what services an agent offers by sending them a capabilities request over XMTP.',
+            '',
+            'Use this when: You want to find out what services another agent provides, their pricing,',
+            'and how to use them — before making a service request or payment.',
+            '',
+            'Sends a JSON capabilities request to the target agent and waits for their response.',
+            'The target agent must be online and have a MessageRouter configured to respond.',
+            '',
+            'The "agentAddress" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).',
+            '',
+            'Returns: The agent\'s capabilities including services, pricing, and usage instructions.',
+            'If no response within the timeout, returns an error indicating the agent may be offline.',
+            '',
+            'Example: { "agentAddress": "0x1234567890abcdef1234567890abcdef12345678" }',
+        ].join('\n'),
+        inputSchema: z.object({
+            chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
+            agentAddress: z.string().describe('Target agent: Ethereum address, participant name, "me", or "#N" (account index).'),
+            timeoutMs: z.coerce.number().int().min(1000).max(60_000).optional().describe('Timeout in milliseconds to wait for response. Defaults to 15000 (15 seconds). Max 60000.'),
+        }),
+    }, async (args) => {
+        let client;
+        try {
+            client = await createClient(args.chain);
+            const timeoutMs = args.timeoutMs ?? 15_000;
+            // Resolve target address
+            let resolved;
+            try {
+                resolved = await resolveAddress(args.agentAddress, client);
+            }
+            catch (resolveErr) {
+                return handleError(resolveErr);
+            }
+            // Send capabilities request
+            const capabilitiesRequest = JSON.stringify({ type: 'capabilities' });
+            await client.sendMessage({
+                to: resolved.address,
+                content: capabilitiesRequest,
+            });
+            // Poll for response within timeout
+            const startTime = Date.now();
+            const pollIntervalMs = 2_000;
+            while (Date.now() - startTime < timeoutMs) {
+                // Wait before polling
+                await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                const messages = await client.getMessages(resolved.address, 5);
+                if (messages.length > 0) {
+                    // Look for a capabilities response among recent messages
+                    for (const msg of messages) {
+                        // Skip messages older than our request
+                        if (msg.timestamp < startTime)
+                            continue;
+                        try {
+                            const parsed = JSON.parse(msg.content);
+                            if (typeof parsed === 'object' &&
+                                parsed !== null &&
+                                'type' in parsed &&
+                                parsed.type === 'capabilities') {
+                                return success({
+                                    agentAddress: resolved.address,
+                                    ...(resolved.resolvedFrom ? { resolvedFrom: `"${resolved.resolvedFrom}" → ${resolved.address}` } : {}),
+                                    capabilities: parsed,
+                                });
+                            }
+                        }
+                        catch {
+                            // Not valid JSON — skip
+                        }
+                    }
+                }
+            }
+            // Timeout — no response received
+            return error('NETWORK_ERROR', `No capabilities response received from ${resolved.address} within ${timeoutMs}ms. ` +
+                'The agent may be offline or does not have a MessageRouter configured.');
+        }
+        catch (err) {
+            return handleError(err);
+        }
+        finally {
+            try {
+                await client?.destroy();
+            }
+            catch { /* M-10: prevent destroy from masking the original error */ }
+        }
+    });
+}
+//# sourceMappingURL=messaging.js.map