web3-tools-mcp 2.0.2 → 3.0.0

package/src/index.ts

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { WalletRelay } from 'web3-wallet-relay'
 import packageJson from '../package.json' with { type: 'json' }
 import { initializeClientManager, SUPPORTED_CHAINS } from './client.js'
+import { DEFAULT_IDENTITY } from './context.js'
 import { startHttpServer } from './http-server.js'
 import { attachLogServer } from './log.js'
-import { registerAllTools } from './tools/index.js'
+import { createMcpServer } from './mcp-server.js'
 import { parseCommandLineArgs } from './utils.js'
-import { getWalletClient } from './wallet-client.js'
+import { allWalletClients, configureWalletRelay, getWalletClient } from './wallet-client.js'
 
 // Parse configuration
 const config = parseCommandLineArgs()
@@ -42,12 +42,15 @@ ENVIRONMENT VARIABLES:
   WALLETCONNECT_PROJECT_ID      Alternative to --walletconnect-project-id
   CUSTOM_RPC                    Alternative to --custom-rpc
   MCP_HTTP_PORT                 Serve MCP over HTTP on this port instead of stdio
+  MCP_HOSTED                    Apply the hosted guards without the CLI (library use)
   MCP_TOKEN                     Bearer token required by the HTTP transport
   MCP_PUBLIC_URL                Public URL of this server, advertised in OAuth metadata
   UPSTASH_REDIS_REST_URL        Keep WalletConnect sessions in Redis, not on disk
   UPSTASH_REDIS_REST_TOKEN
   WALLET_SERVER_URL             URL of a hosted wallet relay (omit to run one locally)
-  WALLET_TOKEN                  Shared pairing token for the wallet relay
+  WALLET_TOKEN                  Secret the wallet relay signs its room tokens with
+  ANVIL_RPC_URL                 Node exposing debug_traceCall (default: 127.0.0.1:8545)
+  ANVIL_ALLOW_RESET             Let tracing re-fork that node, clearing its state
 
 SUPPORTED CHAINS:
   ${SUPPORTED_CHAINS.join(', ')}
@@ -92,12 +95,6 @@ if (config.customRpcUrls) {
 // Initialize client manager
 initializeClientManager(config)
 
-function createMcpServer() {
-  const server = new McpServer({ name: 'web3-tools-mcp', version: packageJson.version }, { capabilities: { logging: {} } })
-  registerAllTools(server)
-  return server
-}
-
 const httpMode = Boolean(process.env.MCP_HTTP_PORT)
 const httpPort = Number(process.env.MCP_HTTP_PORT)
 
@@ -114,7 +111,13 @@ const hostedRelay = httpMode
   ? new WalletRelay({ token: process.env.WALLET_TOKEN, publicUrl: process.env.MCP_PUBLIC_URL })
   : undefined
 
-const wallet = getWalletClient(hostedRelay ? { port: httpPort, token: hostedRelay.token } : undefined)
+// Hosted, the relay is this process's own, on the platform's port. Set before any client
+// is made, so every identity's client reaches that one rather than starting its own.
+if (hostedRelay) configureWalletRelay({ port: httpPort, token: hostedRelay.token })
+
+// Outside any tool call, so this is the shared identity — the only one a self-hosted
+// server ever has, and the one a hosted server uses before anybody has authenticated.
+const wallet = getWalletClient(DEFAULT_IDENTITY)
 
 // Hosted, the relay is attached to the HTTP server, so connect only once that is listening.
 const walletReady = httpMode
@@ -131,7 +134,7 @@ async function shutdown(reason: string) {
   if (shuttingDown) return
   shuttingDown = true
   console.error(`[MCP] Shutting down (${reason})`)
-  await wallet.stop().catch(() => {})
+  await Promise.all(allWalletClients().map((client) => client.stop().catch(() => {})))
   process.exit(0)
 }
 

package/src/lib.ts

@@ -0,0 +1,24 @@
+/**
+ * What this package offers a host that serves it to other people.
+ *
+ * The CLI at `index.ts` is a program: importing it parses argv, starts a relay and runs a
+ * server. This is the library half — nothing here has an effect until it is called, so a
+ * deployment can assemble its own server with its own way of deciding who may do what.
+ *
+ * The split in what each side owns is deliberate. This package knows how to talk to chains
+ * and wallets and how to keep one person's signing away from another's; it holds no opinion
+ * about who anybody is, what they are allowed, or what it costs. Those are policy, and they
+ * belong to whatever is doing the serving.
+ */
+
+export { initializeClientManager, SUPPORTED_CHAINS } from './client.js'
+export { DEFAULT_IDENTITY, identityFrom } from './context.js'
+export { type HttpServerOptions, startHttpServer } from './http-server.js'
+export { attachLogServer, log } from './log.js'
+export { createMcpServer } from './mcp-server.js'
+export { type Login, OAuthProvider, SingleUserOAuthProvider, tokenLogin } from './oauth.js'
+export { registerAllTools, type ToolGroup, type ToolMiddleware, toolGroup } from './tools/index.js'
+export type { ChainName, Config, ToolResult } from './types.js'
+export { parseCommandLineArgs } from './utils.js'
+export { allWalletClients, configureWalletRelay, getWalletClient, WalletClient } from './wallet-client.js'
+export { getPhoneSigner, PhoneSigner, qrSvg } from './walletconnect.js'

package/src/mcp-server.ts

@@ -0,0 +1,47 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import packageJson from '../package.json' with { type: 'json' }
+import { registerAllTools, type ToolMiddleware } from './tools/index.js'
+
+/**
+ * A server with every tool registered, ready to be connected to a transport.
+ *
+ * Exists so a host does not have to construct one itself. Reaching for the MCP SDK from
+ * outside would mean a second copy of it, and two copies of the same class are two
+ * unrelated types as far as a compiler is concerned — the error arrives at the seam rather
+ * than where the mistake was made.
+ */
+/**
+ * What a client shows for this server, when it has somewhere to fetch it from.
+ *
+ * Only when a public URL is known: the icon has to be same-origin with the MCP endpoint and
+ * fetchable without credentials, which is true of the signing page's own static files and
+ * not true of anything a stdio server could offer. A client that cannot resolve it falls
+ * back to a letter, which is what it already does.
+ */
+function identity() {
+  const publicUrl = process.env.MCP_PUBLIC_URL?.replace(/\/$/, '')
+  if (!publicUrl) return {}
+
+  return {
+    websiteUrl: publicUrl,
+    icons: [
+      { src: `${publicUrl}/icon.png`, mimeType: 'image/png', sizes: ['512x512'] },
+      { src: `${publicUrl}/icon.svg`, mimeType: 'image/svg+xml', sizes: ['any'] }
+    ]
+  }
+}
+
+export function createMcpServer(middleware?: ToolMiddleware): McpServer {
+  const server = new McpServer(
+    {
+      name: 'web3-tools-mcp',
+      version: packageJson.version,
+      title: 'Web3 Tools',
+      description: packageJson.description,
+      ...identity()
+    },
+    { capabilities: { logging: {} } }
+  )
+  registerAllTools(server, middleware)
+  return server
+}

package/src/oauth.ts

@@ -29,12 +29,14 @@ interface StoredCode {
   redirectUri: string
   resource?: string
   scopes: string[]
+  address?: string
   expiresAt: number
 }
 
 interface StoredToken {
   clientId: string
   scopes: string[]
+  address?: string
   expiresAt: number
 }
 
@@ -92,18 +94,28 @@ function constantTimeEquals(a: string, b: string): boolean {
   return left.length === right.length && timingSafeEqual(left, right)
 }
 
-function loginPage(params: { error?: string; fields: Record<string, string> }): string {
-  // The SDK's authorize handler reads its parameters from the body on POST, so the form
-  // has to carry the whole authorization request back, not just the token.
-  const hidden = Object.entries(params.fields)
-    .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
-    .join('\n  ')
+/**
+ * How a deployment decides who is at the authorize screen.
+ *
+ * Deliberately free of any type from the MCP SDK, a chain library, or this package: an
+ * implementation renders a page and reads back a form, and everything about *how* somebody
+ * proves who they are — a shared token, a wallet signature, a company SSO — stays outside.
+ * Returning an address makes the issued token that person's; returning none authenticates
+ * the deployment rather than anybody in particular.
+ */
+export interface Login {
+  /** The page served at GET /authorize. `hidden` must be placed inside its form. */
+  page(hidden: string, error?: string): string | Promise<string>
+  /** Reads the posted form. An `error` re-renders the page; an `address` names the person. */
+  identify(form: Record<string, string>): Promise<{ address?: string; error?: string }>
+  /**
+   * Form fields this login owns. They are kept out of the hidden inputs replayed into the
+   * page, so a credential can never be echoed back into the HTML.
+   */
+  owns?: string[]
+}
 
-  return `<!doctype html>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Connect to web3-tools-mcp</title>
-<style>
+const PAGE_STYLE = `
   :root { color-scheme: light dark; }
   body { font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 26rem;
          margin: 12vh auto; padding: 0 1.25rem; }
@@ -113,22 +125,45 @@ function loginPage(params: { error?: string; fields: Record<string, string> }):
                   box-sizing: border-box; }
   input { border: 1px solid #ccd; font-family: ui-monospace, monospace; }
   button { margin-top: .75rem; border: 0; background: #3856d6; color: #fff; font-weight: 600; }
-  .error { color: #b3251d; font-weight: 600; }
+  .error { color: #b3251d; font-weight: 600; }`
+
+/** The default: one shared credential, so a self-hoster needs no identity provider. */
+export function tokenLogin(accessToken: string): Login {
+  return {
+    owns: ['token'],
+    page: (hidden, error) => `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect to web3-tools-mcp</title>
+<style>${PAGE_STYLE}
 </style>
 <h1>Connect to web3-tools-mcp</h1>
 <p>Paste this server's access token to authorise the client.</p>
-${params.error ? `<p class="error">${params.error}</p>` : ''}
+${error ? `<p class="error">${error}</p>` : ''}
 <form method="post">
   ${hidden}
   <input name="token" type="password" placeholder="MCP_TOKEN" autocomplete="off" autofocus>
   <button type="submit">Authorise</button>
-</form>`
+</form>`,
+    async identify(form) {
+      if (!constantTimeEquals(form.token ?? '', accessToken)) return { error: 'That token was not accepted.' }
+      // No address: this authenticates the deployment, not a person.
+      return {}
+    }
+  }
 }
 
-export class SingleUserOAuthProvider implements OAuthServerProvider {
+export class OAuthProvider implements OAuthServerProvider {
   private store = new Store()
 
-  constructor(private accessToken: string) {}
+  /**
+   * `staticToken` is accepted verbatim in an Authorization header, for clients that can send
+   * one and skip the flow entirely. It names no person, so it carries no identity.
+   */
+  constructor(
+    private login: Login,
+    private staticToken?: string
+  ) {}
 
   get clientsStore(): OAuthRegisteredClientsStore {
     const store = this.store
@@ -151,34 +186,35 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
   }
 
   /**
-   * GET renders the token prompt; POST checks it and redirects back with a code. Handling
-   * both here keeps the whole login inside the SDK's authorize route.
+   * GET renders the login; POST hands the form to it and, if it names somebody, redirects
+   * back with a code. Handling both here keeps the whole login inside the SDK's authorize
+   * route, which is the only place the client will follow a redirect from.
    */
   async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void> {
     const request = res.req
-    const submitted = (request.body as { token?: string } | undefined)?.token ?? ''
-
-    // Everything except the token itself is replayed into the form, so the handler sees a
-    // complete authorization request when the form posts back.
-    const fields = Object.fromEntries(
-      Object.entries({ ...(request.query as Record<string, string>), ...(request.body as Record<string, string>) }).filter(
-        ([name, value]) => name !== 'token' && typeof value === 'string'
-      )
-    ) as Record<string, string>
-
-    if (request.method !== 'POST') {
-      res.setHeader('content-type', 'text/html; charset=utf-8').send(loginPage({ fields }))
-      return
-    }
-
-    if (!constantTimeEquals(submitted, this.accessToken)) {
+    const form = { ...(request.query as Record<string, string>), ...(request.body as Record<string, string>) }
+
+    // The SDK's authorize handler reads its parameters from the body on POST, so the form
+    // has to carry the whole authorization request back — minus whatever the login owns,
+    // which would mean echoing a credential into the HTML.
+    const owned = new Set(this.login.owns ?? [])
+    const hidden = Object.entries(form)
+      .filter(([name, value]) => !owned.has(name) && typeof value === 'string')
+      .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
+      .join('\n  ')
+
+    const render = async (status: number, error?: string) => {
       res
-        .status(401)
+        .status(status)
         .setHeader('content-type', 'text/html; charset=utf-8')
-        .send(loginPage({ fields, error: 'That token was not accepted.' }))
-      return
+        .send(await this.login.page(hidden, error ? escapeHtml(error) : undefined))
     }
 
+    if (request.method !== 'POST') return render(200)
+
+    const identified = await this.login.identify(form)
+    if (identified.error) return render(401, identified.error)
+
     const code = randomBytes(24).toString('hex')
     await this.store.set<StoredCode>(`code:${code}`, {
       clientId: client.client_id,
@@ -186,6 +222,7 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
       redirectUri: params.redirectUri,
       resource: params.resource?.href,
       scopes: params.scopes ?? [],
+      address: identified.address,
       expiresAt: Date.now() + CODE_TTL
     })
 
@@ -208,7 +245,7 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
 
     // One use only: a replayed code must not mint a second token.
     await this.store.remove(`code:${authorizationCode}`)
-    return this.issue(client.client_id, stored.scopes)
+    return this.issue(client.client_id, stored.scopes, stored.address)
   }
 
   async exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[]): Promise<OAuthTokens> {
@@ -217,16 +254,17 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
     if (stored.clientId !== client.client_id) throw new Error('Refresh token was issued to a different client')
 
     await this.store.remove(`refresh:${refreshToken}`)
-    return this.issue(client.client_id, scopes ?? stored.scopes)
+    // The refreshed token stays the same person's: a refresh proves possession, not identity.
+    return this.issue(client.client_id, scopes ?? stored.scopes, stored.address)
   }
 
-  private async issue(clientId: string, scopes: string[]): Promise<OAuthTokens> {
+  private async issue(clientId: string, scopes: string[], address?: string): Promise<OAuthTokens> {
     const accessToken = randomBytes(32).toString('hex')
     const refreshToken = randomBytes(32).toString('hex')
     const expiresAt = Math.floor(Date.now() / 1000) + TOKEN_TTL
 
-    await this.store.set<StoredToken>(`token:${accessToken}`, { clientId, scopes, expiresAt })
-    await this.store.set<StoredToken>(`refresh:${refreshToken}`, { clientId, scopes, expiresAt })
+    await this.store.set<StoredToken>(`token:${accessToken}`, { clientId, scopes, address, expiresAt })
+    await this.store.set<StoredToken>(`refresh:${refreshToken}`, { clientId, scopes, address, expiresAt })
 
     return {
       access_token: accessToken,
@@ -237,9 +275,9 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
     }
   }
 
-  /** Accepts an issued token, or MCP_TOKEN itself so a client that can send a header still works. */
+  /** Accepts an issued token, or the static one so a client that can send a header still works. */
   async verifyAccessToken(token: string): Promise<AuthInfo> {
-    if (constantTimeEquals(token, this.accessToken)) {
+    if (this.staticToken && constantTimeEquals(token, this.staticToken)) {
       // requireBearerAuth refuses a token with no expiry, and this one never expires.
       return { token, clientId: 'static', scopes: [], expiresAt: Math.floor(Date.now() / 1000) + TOKEN_TTL }
     }
@@ -253,7 +291,15 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
       throw new InvalidTokenError('Access token has expired')
     }
 
-    return { token, clientId: stored.clientId, scopes: stored.scopes, expiresAt: stored.expiresAt }
+    // `extra.address` is where the tools read the caller's identity from; a token that names
+    // nobody leaves it unset, and everything falls back to the shared identity.
+    return {
+      token,
+      clientId: stored.clientId,
+      scopes: stored.scopes,
+      expiresAt: stored.expiresAt,
+      ...(stored.address ? { extra: { address: stored.address } } : {})
+    }
   }
 
   async revokeToken(_client: OAuthClientInformationFull, request: { token: string }): Promise<void> {
@@ -262,6 +308,13 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
   }
 }
 
+/** One shared credential, which is all a self-hosted server needs. */
+export class SingleUserOAuthProvider extends OAuthProvider {
+  constructor(accessToken: string) {
+    super(tokenLogin(accessToken), accessToken)
+  }
+}
+
 /** PKCE helper, used by the tests to drive the flow the way a real client would. */
 export function pkce(): { verifier: string; challenge: string } {
   const verifier = randomBytes(32).toString('base64url')

package/src/preview.ts

@@ -23,6 +23,8 @@ export interface AssetChange {
   to: string
   amount: string
   humanAmount?: string
+  /** Set for an ERC-721 transfer, which moves this one token rather than an amount. */
+  tokenId?: string
 }
 
 export interface TxPreview {
@@ -162,13 +164,30 @@ function topicToAddress(topic: string): string {
   return `0x${topic.slice(-40)}`
 }
 
-async function enrichTransfers(chain: ChainName, logs: readonly { address: string; topics: readonly string[]; data: string }[]) {
+export async function enrichTransfers(
+  chain: ChainName,
+  logs: readonly { address: string; topics: readonly string[]; data: string }[]
+) {
   const transfers = logs.filter((log) => log.topics[0]?.toLowerCase() === TRANSFER_TOPIC && log.topics.length >= 3)
 
   return Promise.all(
     transfers.map(async (log): Promise<AssetChange> => {
-      const amount = log.data && log.data !== '0x' ? BigInt(log.data).toString() : '0'
       const meta = await tokenMeta(chain, log.address).catch(() => ({ symbol: undefined, decimals: undefined }))
+
+      // ERC-721 shares ERC-20's Transfer topic but indexes the token id as a fourth topic,
+      // leaving the data empty — read as ERC-20, a mint looks like a transfer of nothing.
+      if (log.topics.length === 4) {
+        return {
+          token: log.address,
+          symbol: meta.symbol,
+          from: topicToAddress(log.topics[1]!),
+          to: topicToAddress(log.topics[2]!),
+          amount: '1',
+          tokenId: BigInt(log.topics[3]!).toString()
+        }
+      }
+
+      const amount = log.data && log.data !== '0x' ? BigInt(log.data).toString() : '0'
       return {
         token: log.address,
         symbol: meta.symbol,

package/src/signing-requests.ts

@@ -0,0 +1,198 @@
+import { randomBytes } from 'node:crypto'
+import { log } from './log.js'
+
+/**
+ * A signature that outlives the tool call that asked for it.
+ *
+ * Approving happens on a human's schedule. A browser signer is told to come — the tab opens
+ * and the badge flashes — but a phone wallet is only as loud as the wallet itself, and some
+ * send no notification at all. So the wait routinely outlives whatever timeout the MCP
+ * client applies, and the agent is left holding a tool call that never returns while the
+ * request is still perfectly alive in the wallet.
+ *
+ * Each request gets an id and outlives its call. Settling quickly still returns inline, so
+ * the common case — a browser tab that pops up and is approved in seconds — is unchanged.
+ * Past that the call hands back the id and the agent collects the result later.
+ *
+ * Held in memory on purpose: a request is only meaningful while the socket or WalletConnect
+ * session that carries it is alive, and both die with the process anyway.
+ */
+
+/**
+ * How long to wait on a signer that has been told to come — the browser page, whose tab
+ * opens and whose title flashes. Comfortably under any MCP client's tool timeout.
+ *
+ * A signer that cannot raise the alarm does not use this at all: it calls `waiting()` the
+ * moment the request is with the wallet, and the call returns then. Waiting on a phone that
+ * never buzzed is dead time either way.
+ */
+export const GRACE_MS = 25_000
+
+/** How long a finished result stays collectable. */
+const RESULT_TTL = 15 * 60_000
+
+export type SigningState = 'pending' | 'done' | 'failed'
+
+export interface SigningRequest {
+  id: string
+  identity: string
+  /** What is being asked for, in a line, so a later check can say what it was. */
+  summary: string
+  signer: 'browser' | 'phone'
+  /** Waiting on a person, or on the chain. They deserve different things said about them. */
+  stage: 'approval' | 'mining'
+  /** Known once approved, so a request can be followed on an explorer before it settles. */
+  txHash?: string
+  startedAt: number
+  state: SigningState
+  settledAt?: number
+  result?: unknown
+  error?: string
+}
+
+/** How a signing job says where it has got to. */
+export interface SigningProgress {
+  /**
+   * The request is with the wallet and only a human is left. Everything that fails quickly —
+   * no session, an unapproved chain, a reverted simulation — has already thrown.
+   */
+  waiting: () => void
+  /** Approved and broadcast. Nothing is settled until it is mined. */
+  mining: (txHash: string) => void
+}
+
+interface Tracked extends SigningRequest {
+  /** Already has a catch attached, so awaiting it again can never be unhandled. */
+  settled: Promise<void>
+}
+
+const requests = new Map<string, Tracked>()
+
+function sweep(): void {
+  const now = Date.now()
+  for (const [id, request] of requests) {
+    if (request.settledAt && now - request.settledAt > RESULT_TTL) requests.delete(id)
+  }
+}
+
+function view(request: Tracked): SigningRequest {
+  const { settled: _settled, ...rest } = request
+  return rest
+}
+
+/** Resolves when the request settles, or when the grace runs out — whichever comes first. */
+function race(request: Tracked, graceMs: number, handoff?: Promise<void>): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, graceMs)
+    // A request nobody is waiting for must not keep a stdio server alive after its client
+    // has gone; shutdown is what ends it.
+    timer.unref?.()
+
+    const done = () => {
+      clearTimeout(timer)
+      resolve()
+    }
+
+    request.settled.then(done)
+    handoff?.then(done)
+  })
+}
+
+/**
+ * Run a signing request, waiting only as long as a tool call reasonably can.
+ *
+ * The work starts here either way — returning `done: false` means nobody has approved yet,
+ * never that nothing was asked.
+ */
+export async function signingCall<T>(
+  context: { identity: string; summary: string; signer: 'browser' | 'phone'; graceMs?: number },
+  run: (progress: SigningProgress) => Promise<T>
+): Promise<{ done: true; result: T } | { done: false; request: SigningRequest }> {
+  sweep()
+
+  const id = randomBytes(16).toString('hex')
+
+  // Ends the wait: until it is called, a failure is a real error the caller should see
+  // rather than something to be collected later.
+  let handedOff: () => void
+  const handoff = new Promise<void>((resolve) => {
+    handedOff = resolve
+  })
+
+  // Built before `run` starts, because a signer is free to report progress synchronously.
+  const request: Tracked = {
+    id,
+    identity: context.identity,
+    summary: context.summary,
+    signer: context.signer,
+    stage: 'approval',
+    startedAt: Date.now(),
+    state: 'pending',
+    settled: Promise.resolve()
+  }
+
+  // Broadcasting does not end the wait. On a fast chain the receipt is seconds away, and a
+  // caller still inside its grace would rather have the mined result than a request id.
+  const started = run({
+    waiting: () => handedOff(),
+    mining: (txHash) => {
+      request.stage = 'mining'
+      request.txHash = txHash
+    }
+  })
+
+  request.settled = started.then(
+    (result) => {
+      request.state = 'done'
+      request.result = result
+      request.settledAt = Date.now()
+    },
+    (error: unknown) => {
+      request.state = 'failed'
+      request.error = error instanceof Error ? error.message : String(error)
+      request.settledAt = Date.now()
+    }
+  )
+
+  requests.set(id, request)
+  await race(request, context.graceMs ?? GRACE_MS, handoff)
+
+  if (request.state === 'done') {
+    requests.delete(id)
+    return { done: true, result: request.result as T }
+  }
+  if (request.state === 'failed') {
+    requests.delete(id)
+    throw new Error(request.error)
+  }
+
+  log('info', 'Signing', `${context.summary} is still waiting for approval — handed back as ${id.slice(0, 8)}`)
+  return { done: false, request: view(request) }
+}
+
+/**
+ * Collect a request handed back earlier, waiting out another grace period if it is still
+ * pending — so an agent that checks in a loop paces itself rather than spinning.
+ *
+ * Scoped to the caller: an id is unguessable, but on a server carrying several people that
+ * is not the reason one of them cannot read another's signature.
+ */
+export async function collectSigningRequest(id: string, identity: string, graceMs = GRACE_MS): Promise<SigningRequest> {
+  sweep()
+
+  const request = requests.get(id)
+  if (!request || request.identity !== identity) {
+    throw new Error(`No signing request ${id} is waiting. It may have been collected already, or it expired.`)
+  }
+
+  if (request.state === 'pending') await race(request, graceMs)
+  if (request.state !== 'pending') requests.delete(id)
+
+  return view(request)
+}
+
+/** Everything this identity still has in front of a wallet. */
+export function pendingSigningRequests(identity: string): SigningRequest[] {
+  sweep()
+  return [...requests.values()].filter((request) => request.identity === identity && request.state === 'pending').map(view)
+}