web3-tools-mcp 2.0.1 → 3.0.0

package/src/tools/sign/transactions.ts

@@ -0,0 +1,428 @@
+import { randomBytes } from 'node:crypto'
+import { type AbiFunction, type Address, encodeFunctionData, isAddress, parseAbiItem, parseUnits, toHex } from 'viem'
+import { z } from 'zod'
+import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import { log } from '../../log.js'
+import { buildTxPreview, type RawTx, type TxPreview } from '../../preview.js'
+import { type SigningProgress, type SigningRequest, signingCall } from '../../signing-requests.js'
+import type { ChainName } from '../../types.js'
+import { createTool, formatResponse } from '../../utils.js'
+import { getWalletClient } from '../../wallet-client.js'
+import { getPhoneSigner } from '../../walletconnect.js'
+import { failure } from './errors.js'
+
+function generateRequestId(): string {
+  return randomBytes(16).toString('hex')
+}
+
+function requireAddress(label: string, address: string): Address {
+  if (!isAddress(address)) throw new Error(`Invalid ${label}: ${address}`)
+  return address
+}
+
+function explorerTxUrl(chain: ChainName, txHash: unknown): string | undefined {
+  return getClientManager().explorerUrl(chain, `/tx/${txHash}`)
+}
+
+/**
+ * Which wallet to send the request to. Deliberately required on every signing tool: both
+ * signers can be live at once, and only the person holding the devices knows which one is
+ * actually to hand. Guessing strands the request in front of a screen nobody is looking at.
+ *
+ * Either way the transaction is decoded and simulated first — the wallet shows its own
+ * summary, so the preview is returned to the caller too, to be read before approving.
+ */
+const SignWithSchema = z
+  .enum(['phone', 'browser'])
+  .describe(
+    'Where to approve this: "phone" for a paired WalletConnect wallet, "browser" for the wallet signing page. Ask the user which they want — do not assume, even when only one is connected. Call wallet_status first: it says which signers are ready, and when no signing page is open it returns walletUrl. In that case give the user that link, ask them to open it and connect a wallet, and only call this once they confirm — a signing request cannot reach a page nobody has open.'
+  )
+
+type SignWith = z.infer<typeof SignWithSchema>
+
+/** Only meaningful with several wallets paired; wallet_status lists them. */
+const AccountSchema = z
+  .string()
+  .optional()
+  .describe(
+    'Which paired wallet to ask, by address. Only needed when wallet_status reports more than one — omit it and the most recently paired one is used.'
+  )
+
+/** This identity's phone wallet and the address to sign from, or an error saying what to do. */
+async function requirePhoneSession(identity: string, account?: string) {
+  const phone = getPhoneSigner()
+  if (!phone) {
+    throw new Error(
+      'Phone signing is not configured on this server. Set WALLETCONNECT_PROJECT_ID, or sign in the browser instead.'
+    )
+  }
+
+  const session = await phone.session(identity, account)
+  if (!session) {
+    const paired = await phone.sessions(identity)
+    throw new Error(
+      account
+        ? `No paired wallet holds ${account}. Paired: ${paired.flatMap((s) => s.accounts).join(', ') || 'none'}.`
+        : 'No phone wallet is paired. Run pair_phone_wallet and scan the QR, or sign in the browser instead.'
+    )
+  }
+
+  // A session can expose several addresses; the one asked for, spelled as the wallet
+  // reported it, or its first when the caller did not choose.
+  const wanted = account?.toLowerCase()
+  const from = session.accounts.find((a) => a.toLowerCase() === wanted) ?? session.accounts[0]
+  return { phone, session, from }
+}
+
+/** Long enough for a congested chain, short enough that a stuck one is reported rather than hung on. */
+const RECEIPT_TIMEOUT = 180_000
+
+/**
+ * Wait for the transaction to actually be mined.
+ *
+ * A hash means broadcast, nothing more. Reporting that as success is how a reverted
+ * transaction — gas spent, nothing done — gets read back as if it had worked.
+ */
+async function confirm(chain: ChainName, txHash: unknown) {
+  try {
+    const receipt = await getClientManager()
+      .getClient(chain)
+      .waitForTransactionReceipt({ hash: txHash as `0x${string}`, timeout: RECEIPT_TIMEOUT })
+
+    return {
+      status: receipt.status === 'success' ? ('mined' as const) : ('reverted' as const),
+      blockNumber: receipt.blockNumber.toString(),
+      gasUsed: receipt.gasUsed.toString()
+    }
+  } catch (error) {
+    // Still out there — it simply has not been mined yet. Not a failure, and saying so beats
+    // claiming either outcome.
+    log('warning', 'Transaction', `No receipt for ${txHash} yet: ${(error as Error).message}`)
+    return { status: 'broadcast' as const }
+  }
+}
+
+async function signOnPhone(
+  chain: ChainName,
+  tx: RawTx & { data?: string },
+  identity: string,
+  account: string | undefined,
+  progress: SigningProgress
+) {
+  const { phone, from } = await requirePhoneSession(identity, account)
+  const preview = await buildTxPreview(chain, tx, from)
+
+  const txHash = await phone.request(
+    chain,
+    'eth_sendTransaction',
+    [{ from, to: tx.to, value: tx.value ?? '0x0', ...(tx.data && { data: tx.data }) }],
+    { identity, account, onWaiting: progress.waiting }
+  )
+
+  progress.mining(String(txHash))
+  return { txHash, preview, signedWith: 'phone' as const, receipt: await confirm(chain, txHash) }
+}
+
+/**
+ * `onWaiting` is what decides whether the tool call waits.
+ *
+ * The browser signer never calls it: the tab is opened and the title flashes, so somebody is
+ * looking within seconds and the grace period is worth spending. A phone is only as loud as
+ * the wallet, and the two people actually use push nothing at all — so that path hands back
+ * a request id as soon as the wallet has it, rather than spending the grace on silence.
+ */
+async function requestSignature(
+  chain: ChainName,
+  tx: RawTx & { data?: string },
+  signWith: SignWith,
+  identity: string,
+  account: string | undefined,
+  progress: SigningProgress
+) {
+  log('info', 'Transaction', `${chain} → ${tx.to}, signing with ${signWith}`)
+  if (signWith === 'phone') return signOnPhone(chain, tx, identity, account, progress)
+
+  const wallet = getWalletClient(identity)
+  await wallet.waitForSigner()
+
+  const preview = await buildTxPreview(chain, tx, wallet.getAddress())
+
+  const txHash = await wallet.request({
+    id: generateRequestId(),
+    type: 'send_transaction',
+    chain,
+    data: { to: tx.to, value: tx.value ?? '0x0', ...(tx.data && { data: tx.data }) },
+    preview
+  })
+
+  progress.mining(String(txHash))
+  return { txHash, preview, signedWith: 'browser' as const, receipt: await confirm(chain, txHash) }
+}
+
+/**
+ * What to tell the agent when nobody has approved yet.
+ *
+ * Emphatically not a failure: the request is in front of a wallet right now. Calling the
+ * signing tool again would put a second, separately approvable request there — so the way
+ * back is the id, and this says so plainly enough that an agent does not retry instead.
+ */
+function awaitingApproval(request: SigningRequest) {
+  return formatResponse({
+    success: true,
+    status: 'awaiting_approval',
+    requestId: request.id,
+    signedWith: request.signer,
+    what: request.summary,
+    nextStep: `Tell the user to approve it${request.signer === 'phone' ? ' in their phone wallet — some wallets do not notify, so they may need to open the app themselves' : ' in the signing page'}, then call check_signing_request with requestId "${request.id}". Do not call this tool again: that would ask for a second signature.`,
+    message: 'Sent to the wallet. Nothing has been signed or broadcast yet.'
+  })
+}
+
+/**
+ * Whether it worked, which is not the same question as whether it was sent.
+ *
+ * A reverted transaction is mined, costs gas and does nothing. Reporting it as a success
+ * because a hash came back is how an agent goes on to build on a state change that never
+ * happened.
+ */
+function minedOutcome(receipt: { status: 'mined' | 'reverted' | 'broadcast'; blockNumber?: string; gasUsed?: string }) {
+  if (receipt.status === 'reverted') {
+    return {
+      success: false,
+      status: 'reverted',
+      blockNumber: receipt.blockNumber,
+      gasUsed: receipt.gasUsed,
+      message: 'Mined, but it reverted. The gas was spent and nothing else changed.'
+    }
+  }
+
+  if (receipt.status === 'broadcast') {
+    return {
+      success: true,
+      status: 'broadcast',
+      message: 'Signed and broadcast, but not mined yet. Check the explorer link before treating it as done.'
+    }
+  }
+
+  return { success: true, status: 'mined', blockNumber: receipt.blockNumber, gasUsed: receipt.gasUsed }
+}
+
+/** What the caller should see about a transaction before it is approved. */
+function previewSummary(preview: TxPreview) {
+  return {
+    action: preview.decoded?.intent ?? preview.decoded?.functionName,
+    protocol: preview.decoded?.protocol ?? preview.toLabel,
+    details: preview.decoded?.fields.map((f) => `${f.name}: ${f.value}${f.warning ? ` (${f.warning})` : ''}`),
+    simulation: preview.simulation
+  }
+}
+
+export default {
+  send_native_token: createTool(
+    'Send Native Token',
+    'Send native tokens (ETH, MATIC, BNB, etc.) to an address. Simulates the transaction, then sends it to the signer you choose for approval.',
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network'),
+      to: z.string().describe('Recipient address'),
+      amount: z.string().describe('Amount in native token (e.g., "0.1" for 0.1 ETH)'),
+      data: z.string().optional().describe('Optional hex-encoded data to include with transaction'),
+      signWith: SignWithSchema,
+      account: AccountSchema
+    }),
+    async (args, identity) => {
+      try {
+        const to = requireAddress('recipient address', args.to)
+        const value = `0x${parseUnits(args.amount, 18).toString(16)}`
+
+        const outcome = await signingCall(
+          { identity, signer: args.signWith, summary: `Send ${args.amount} on ${args.chain} to ${to}` },
+          (progress) =>
+            requestSignature(
+              args.chain as ChainName,
+              { to, value, data: args.data },
+              args.signWith,
+              identity,
+              args.account,
+              progress
+            )
+        )
+        if (!outcome.done) return awaitingApproval(outcome.request)
+        const { txHash, preview, signedWith, receipt } = outcome.result
+
+        return formatResponse({
+          ...minedOutcome(receipt),
+          chain: args.chain,
+          transactionHash: txHash,
+          to,
+          amount: args.amount,
+          signedWith,
+          preview: previewSummary(preview),
+          explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
+        })
+      } catch (error) {
+        return failure(error, 'Transaction failed or was rejected')
+      }
+    }
+  ),
+
+  send_erc20_token: createTool(
+    'Send ERC20 Token',
+    'Send ERC20 tokens to an address. Simulates the transfer, then sends it to the signer you choose for approval.',
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network'),
+      tokenAddress: z.string().describe('ERC20 token contract address'),
+      to: z.string().describe('Recipient address'),
+      amount: z.string().describe('Amount in token units (e.g., "100" for 100 USDC)'),
+      decimals: z.number().optional().default(18).describe('Token decimals (default: 18)'),
+      signWith: SignWithSchema,
+      account: AccountSchema
+    }),
+    async (args, identity) => {
+      try {
+        const tokenAddress = requireAddress('token address', args.tokenAddress)
+        const to = requireAddress('recipient address', args.to)
+
+        const data = encodeFunctionData({
+          abi: [parseAbiItem('function transfer(address to, uint256 amount)')],
+          args: [to, parseUnits(args.amount, args.decimals ?? 18)]
+        })
+
+        const outcome = await signingCall(
+          { identity, signer: args.signWith, summary: `Send ${args.amount} of ${tokenAddress} on ${args.chain} to ${to}` },
+          (progress) =>
+            requestSignature(
+              args.chain as ChainName,
+              { to: tokenAddress, data, value: '0x0' },
+              args.signWith,
+              identity,
+              args.account,
+              progress
+            )
+        )
+        if (!outcome.done) return awaitingApproval(outcome.request)
+        const { txHash, preview, signedWith, receipt } = outcome.result
+
+        return formatResponse({
+          ...minedOutcome(receipt),
+          chain: args.chain,
+          transactionHash: txHash,
+          tokenAddress,
+          to,
+          amount: args.amount,
+          signedWith,
+          preview: previewSummary(preview),
+          explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
+        })
+      } catch (error) {
+        return failure(error, 'Token transfer failed or was rejected')
+      }
+    }
+  ),
+
+  write_contract: createTool(
+    'Write Contract',
+    'Send a transaction that calls a state-changing contract function. Simulates it first, then asks your wallet to approve. Costs gas.',
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network'),
+      contractAddress: z.string().describe('Contract address'),
+      functionAbi: z.string().describe('Function ABI definition (e.g., "function transfer(address to, uint256 amount)")'),
+      args: z
+        .array(z.union([z.string(), z.number(), z.boolean()]))
+        .optional()
+        .describe('Function arguments in order matching the ABI signature'),
+      value: z.string().optional().describe('Optional native value to send with transaction (in ETH units, e.g., "0.1")'),
+      signWith: SignWithSchema,
+      account: AccountSchema
+    }),
+    async (args, identity) => {
+      try {
+        const contractAddress = requireAddress('contract address', args.contractAddress)
+        const abiItem = parseAbiItem(args.functionAbi) as AbiFunction
+
+        const data = encodeFunctionData({
+          abi: [abiItem],
+          functionName: abiItem.name,
+          args: (args.args || []) as readonly unknown[]
+        })
+        const value = args.value ? `0x${parseUnits(args.value, 18).toString(16)}` : '0x0'
+
+        const outcome = await signingCall(
+          { identity, signer: args.signWith, summary: `${abiItem.name}() on ${contractAddress} (${args.chain})` },
+          (progress) =>
+            requestSignature(
+              args.chain as ChainName,
+              { to: contractAddress, data, value },
+              args.signWith,
+              identity,
+              args.account,
+              progress
+            )
+        )
+        if (!outcome.done) return awaitingApproval(outcome.request)
+        const { txHash, preview, signedWith, receipt } = outcome.result
+
+        return formatResponse({
+          ...minedOutcome(receipt),
+          chain: args.chain,
+          transactionHash: txHash,
+          contractAddress,
+          functionName: abiItem.name,
+          signedWith,
+          preview: previewSummary(preview),
+          explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
+        })
+      } catch (error) {
+        return failure(error, 'Contract call failed or was rejected')
+      }
+    }
+  ),
+
+  sign_message: createTool(
+    'Sign Message',
+    'Sign a message with your wallet, on whichever signer you choose.',
+    z.object({
+      message: z.string().describe('Message to sign'),
+      signWith: SignWithSchema,
+      account: AccountSchema
+    }),
+    async (args, identity) => {
+      try {
+        const sign = async (progress: SigningProgress) => {
+          if (args.signWith === 'phone') {
+            const { phone, from } = await requirePhoneSession(identity, args.account)
+            return phone.request('mainnet', 'personal_sign', [toHex(args.message), from], {
+              identity,
+              account: args.account,
+              onWaiting: progress.waiting
+            })
+          }
+
+          const wallet = getWalletClient(identity)
+          await wallet.waitForSigner()
+          return wallet.request({
+            id: generateRequestId(),
+            type: 'sign_message',
+            chain: 'any',
+            data: { message: args.message }
+          })
+        }
+
+        const outcome = await signingCall(
+          { identity, signer: args.signWith, summary: `Sign the message "${args.message.slice(0, 60)}"` },
+          sign
+        )
+        if (!outcome.done) return awaitingApproval(outcome.request)
+
+        return formatResponse({
+          success: true,
+          message: args.message,
+          signature: outcome.result,
+          signedWith: args.signWith,
+          signatureType: 'personal_sign'
+        })
+      } catch (error) {
+        return failure(error, 'Message signing failed or was rejected')
+      }
+    }
+  )
+}

package/src/tools/sign/wallet.ts

@@ -0,0 +1,216 @@
+import qrcode from 'qrcode-terminal'
+import { z } from 'zod'
+import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import { pendingSigningRequests } from '../../signing-requests.js'
+import type { ChainName } from '../../types.js'
+import { createTool, formatResponse } from '../../utils.js'
+import { getWalletClient } from '../../wallet-client.js'
+import { getPhoneSigner, pairingLinks } from '../../walletconnect.js'
+import { describeError, failure } from './errors.js'
+
+/**
+ * Connecting a wallet and reporting what is connected — separate from the tools that ask
+ * one to sign, because this is the part a user does once and that has nothing to do with
+ * any particular transaction.
+ */
+
+/** Render a pairing URI as an ASCII QR, so it can be scanned straight from the chat. */
+function qrFor(uri: string): Promise<string> {
+  return new Promise((resolve) => qrcode.generate(uri, { small: true }, resolve))
+}
+
+export default {
+  pair_phone_wallet: createTool(
+    'Pair Phone Wallet',
+    'Pair a phone wallet over WalletConnect, so transactions are signed on the phone instead of in a browser. ' +
+      'Returns a QR to scan plus links that open a wallet directly — show those to the user as clickable links. ' +
+      'Always pairs: call it when the user wants a wallet connected, and call wallet_status instead to find out ' +
+      'whether one already is. Pairing again adds a wallet rather than replacing one, and signing tools then take ' +
+      '"account" to choose between them. Requires a WalletConnect project id.',
+    z.object({
+      chains: z
+        .array(z.enum(SUPPORTED_CHAINS))
+        .optional()
+        .describe('Chains to request access to (defaults to every supported network)'),
+      wallet: z.string().optional().describe('Name of the wallet to open, e.g. "rabby" — omit to list the common ones'),
+      agent: z
+        .string()
+        .optional()
+        .describe(
+          'Who is asking, shown in the wallet approval dialog, e.g. "Claude Code". Say who you actually are — ' +
+            'the user reads this when deciding whether to grant signing access.'
+        )
+    }),
+    async (args, identity) => {
+      const phone = getPhoneSigner()
+      if (!phone) {
+        return formatResponse({
+          success: false,
+          message:
+            'No WalletConnect project id configured. Get a free one at https://dashboard.walletconnect.com and pass --walletconnect-project-id or set WALLETCONNECT_PROJECT_ID.'
+        })
+      }
+
+      try {
+        // Before anything starts the client: its name is fixed the moment it does.
+        phone.nameAgent(args.agent)
+        const paired = await phone.sessions(identity)
+
+        const chains = (args.chains ?? SUPPORTED_CHAINS.filter((c) => c !== 'localhost')) as ChainName[]
+        const uri = await phone.pair(chains, identity)
+        const projectId = getClientManager().getConfig().walletConnectProjectId as string
+
+        return formatResponse({
+          qr: await qrFor(uri),
+          uri,
+          // Pairing adds rather than replaces, so say what is already there — scanning this
+          // leaves the user with both, and signing tools take `account` to pick.
+          ...(paired.length > 0 && {
+            alreadyPaired: paired.map((session) => ({ address: session.accounts[0], wallet: session.peer })),
+            // Whether both survive is the wallet's call, not this server's, and some keep
+            // only one session per site.
+            keepingBoth:
+              `Approving this in a wallet app already listed above (${[...new Set(paired.map((s) => s.peer).filter(Boolean))].join(', ')}) ` +
+              'may end its existing session — some wallets keep one per site. To hold both at once, approve this in a different wallet app.'
+          }),
+          // For an agent running on the phone itself there is nothing to scan, so hand over
+          // links that open the wallet directly. `wallet` narrows the list to one.
+          openOnThisDevice: await pairingLinks(projectId, uri, args.wallet),
+          // Approving grants an agent standing permission to request signatures, so the
+          // wallet dialog names the agent rather than implying a website is connecting.
+          shownInWallet: args.agent ? `${args.agent} via web3-tools-mcp` : 'web3-tools-mcp (AI agent)',
+          howToPresent:
+            'Render each openOnThisDevice entry as a clickable link labelled with the wallet name, and show the ' +
+            'uri as copyable text. On a phone that tap is the whole flow. Show the QR only when the user is on a ' +
+            'different device from their wallet — it is unreadable inline on the phone that holds the wallet. ' +
+            'If a link does nothing, some clients drop custom schemes like rabby://, so tell them to paste the uri.',
+          message:
+            'On another device: scan the QR with your wallet. On this device: tap one of the openOnThisDevice ' +
+            'links, or copy the uri and paste it into your wallet under WalletConnect — every wallet supports ' +
+            'that, and it is the one that always works. Then run wallet_status to confirm.'
+        })
+      } catch (error) {
+        return failure(error, 'Could not start WalletConnect pairing')
+      }
+    }
+  ),
+
+  disconnect_phone_wallet: createTool(
+    'Disconnect Phone Wallet',
+    'End WalletConnect sessions and drop the pairings underneath them. Without "account" this disconnects every paired wallet, so name one when the user only wants that wallet gone — wallet_status lists them.',
+    z.object({
+      account: z
+        .string()
+        .optional()
+        .describe('Address of the one wallet to disconnect. Omit to disconnect every wallet paired here.')
+    }),
+    async (args, identity) => {
+      const phone = getPhoneSigner()
+      if (!phone) {
+        return formatResponse({ success: false, message: 'No WalletConnect project id configured — nothing to disconnect.' })
+      }
+
+      try {
+        const before = await phone.sessions(identity)
+        const removed = await phone.disconnect(identity, args.account)
+        const left = await phone.sessions(identity)
+
+        return formatResponse({
+          success: true,
+          disconnectedSessions: removed.sessions,
+          droppedPairings: removed.pairings,
+          wallets: before.map((session) => `${session.peer ?? 'unknown wallet'} (${session.accounts.join(', ')})`),
+          stillPaired: left.map((session) => ({ address: session.accounts[0], wallet: session.peer })),
+          message:
+            removed.sessions || removed.pairings
+              ? left.length > 0
+                ? `Disconnected. ${left.length} wallet(s) still paired — pass "account" to a signing tool to choose between them.`
+                : 'Disconnected. Transactions fall back to the browser wallet until a phone is paired again.'
+              : 'Nothing was connected.'
+        })
+      } catch (error) {
+        return failure(error, 'Could not disconnect the phone wallet')
+      }
+    }
+  ),
+
+  wallet_status: createTool(
+    'Wallet Status',
+    'Report every signer and whether it is ready, so a signing tool can be given the right signWith.',
+    z.object({}),
+    async (_args, identity) => {
+      // Both signers are reported, never just the first one found: signWith makes this a
+      // choice the user owns, so the agent has to see everything available.
+      const phone = getPhoneSigner()
+      const phonesPaired = (await phone?.sessions(identity).catch(() => undefined)) ?? []
+      const phoneSession = phonesPaired[phonesPaired.length - 1]
+
+      const wallet = getWalletClient(identity)
+      const relayError = await wallet
+        .connect()
+        .then(() => undefined)
+        .catch((error) => describeError(error))
+
+      const browserReady = !relayError && wallet.isConnected()
+      // Only raise a tab when there is no other way to sign — a status check should not
+      // open a window at someone who is about to use their phone.
+      if (!browserReady && !phoneSession && !relayError) wallet.openBrowser()
+
+      const signers = {
+        phone: phoneSession
+          ? {
+              ready: true,
+              address: phoneSession.accounts[0],
+              // One wallet can expose several addresses; `account` on a signing tool picks.
+              ...(phoneSession.accounts.length > 1 && { accounts: phoneSession.accounts }),
+              wallet: phoneSession.peer,
+              chains: phoneSession.chains,
+              // Only when there is a choice to make: pass one of these as `account`.
+              ...(phonesPaired.length > 1 && {
+                alsoPaired: phonesPaired.slice(0, -1).map((s) => ({ address: s.accounts[0], wallet: s.peer, chains: s.chains }))
+              })
+            }
+          : {
+              ready: false,
+              reason: phone
+                ? 'No phone paired. Run pair_phone_wallet and scan the QR.'
+                : 'Phone signing is not configured — set WALLETCONNECT_PROJECT_ID.'
+            },
+        browser: browserReady
+          ? { ready: true, address: wallet.getAddress(), openTab: wallet.getPageUrl() }
+          : {
+              ready: false,
+              reason: relayError ?? 'No signing page is open.',
+              walletUrl: relayError ? undefined : wallet.getUrl()
+            }
+      }
+
+      const ready = [phoneSession ? 'phone' : undefined, browserReady ? 'browser' : undefined].filter(Boolean)
+      const message =
+        ready.length === 2
+          ? 'Both signers are ready. Ask the user which one to use, then pass it as signWith.'
+          : ready.length === 1
+            ? `Only ${ready[0]} is ready. Confirm with the user before signing there, or set the other one up.`
+            : `No signer is ready. For a browser, give the user this link and ask them to open it and connect a wallet: ${signers.browser.walletUrl ?? '(relay unavailable)'}. For a phone, run pair_phone_wallet.`
+
+      // Handed back by a signing tool that outlasted its call, and collectable by id —
+      // otherwise a signature waiting on somebody's phone is invisible from here.
+      const waiting = pendingSigningRequests(identity)
+
+      return formatResponse({
+        ready,
+        signers,
+        ...(waiting.length > 0 && {
+          awaitingApproval: waiting.map((request) => ({
+            requestId: request.id,
+            what: request.summary,
+            signedWith: request.signer,
+            waitingFor: `${Math.round((Date.now() - request.startedAt) / 1000)}s`
+          })),
+          nextStep: 'Collect each of these with check_signing_request rather than asking for the signature again.'
+        }),
+        message
+      })
+    }
+  )
+}

package/src/utils.ts

@@ -7,13 +7,16 @@ export function createTool<T extends z.ZodType>(
   title: string,
   description: string,
   schema: T,
-  handler: (args: z.infer<T>) => Promise<ToolResult>
+  handler: (args: z.infer<T>, identity: string) => Promise<ToolResult>,
+  /** Whether this server can serve the tool at all; one it cannot is never offered. */
+  available?: () => boolean
 ) {
   return {
     title,
     description,
     schema,
-    handler
+    handler,
+    available
   }
 }