feat(mcp): cumulative spend cap and durable payment audit ledger (closes #405, closes #406)

[sparkysolutions10-pixel]

Summary

Addresses and resolves issues #405 and #406 by introducing a cumulative spend ceiling and a durable payment audit ledger for the Bazaar MCP server.

Key Changes

1. Cumulative Spend Ceiling (The spend cap is per call, so it is not a cap #405):

   • Configurable cumulative budget ceiling (maxCumulativeSpend, environment variable MCP_MAX_CUMULATIVE_SPEND or MCP_MAX_SESSION_SPEND, defaulting to $10.00).
   • Added distinct error code ERR_SPEND_LIMIT_EXCEEDED to MCP_ERROR_CODES in src/mcp/codes.ts. When the cumulative budget ceiling is reached, subsequent payment requests are refused with ERR_SPEND_LIMIT_EXCEEDED and a descriptive message detailing the exhausted budget.
   • Proves in tests that N calls under the per-call limit are refused once their sum exceeds the cumulative ceiling.

2. Budget Discoverability (The spend cap is per call, so it is not a cap #405):

   • Dynamic paid_call tool description updated on ListToolsRequestSchema to disclose the per-call cap, cumulative cap, current spent total, and remaining budget to the agent before calling.
   • Added new �azaar_spend_budget MCP query tool allowing agents to inspect spending breakdown, limits, and recent audit records.

3. Restart Behavior (The spend cap is per call, so it is not a cap #405):

   • Deliberate and documented restart handling:
     • When spendLedgerPath (MCP_SPEND_LEDGER_PATH) is configured, previous payment records and cumulative spend totals are restored from disk on startup, preventing agents or operators from bypassing the spend cap via process restarts.
     • When spendLedgerPath is omitted (default), spending is tracked in-memory for the duration of the MCP server session, suitable for stateless or serverless environments.

4. Durable Payment Audit Ledger (Nothing records what the agent spent #406):

   • Implemented SpendLedger in src/mcp/ledger.ts.
   • Records every payment attempt (timestamp, URL, host, method, amount, network, transaction hash, outcome, and reason), whether successful or failed.
   • Extracts transaction hash from payment-response / x-payment-response headers or x-transaction-hash where present.
   • Zero secret material: Strictly never records secret keys, seeds, signatures, or raw transaction envelopes.

5. Prometheus Metrics with Bounded Labels (Nothing records what the agent spent #406):

   • Implemented McpMetrics in src/mcp/metrics.ts.
   • mcp_payment_attempts_total: Counter tracking payment attempts labelled by bounded host,
     etwork, and outcome.
   • mcp_spend_total: Counter tracking total amount spent in USD labelled by bounded host and
     etwork.
   • host label is bounded against an allowlisted host set (�llowedHosts); any unlisted target host is mapped to 'other' to prevent Prometheus time series cardinality explosion.

6. Changeset & Tests:

   • Added .changeset/mcp-spend-cap-and-ledger.md.
   • Expanded Vitest test suite in ests/mcp.test.ts to 10 comprehensive tests.

Closes #405
Closes #406

[Miracle656]

Changes requested: one issue per PR, and only issues assigned to you

This is a process requirement, applied to all 23 of your open PRs in this repo. It is not a judgement about the code, which I have not been able to review — and that is the first half of the problem.

The bundling

Across your open PRs, 150 distinct issues are claimed. This one claims several. #483 claims 22, #481 claims 20, #477 claims 20, #474 claims 20.

A PR that closes twenty issues cannot be reviewed. Each of those issues has its own acceptance criteria — typically five — so twenty issues is a hundred separate things to verify in one diff, and if any one of them is wrong the whole PR is blocked while it is fixed. Every batch I published says the issues are deliberately independent so they can be worked in parallel, by different people, without colliding. Bundling them removes exactly that property.

The assignments

135 of the 150 issues claimed are assigned to other contributors — 67 different people.

This PR is an example: it names issues currently assigned to other contributors who are working on them now. Several have open PRs of their own. If this merged as it stands, those people would have done the work and received nothing for it, and I would have no way to tell the two efforts apart.

I am not assuming anything about why. Assignments change, Drips and GitHub can disagree, and a wide-ranging branch picks up issue numbers easily. But the effect on the people holding those assignments is the same regardless of intent, which is why I have to act on it.

What I need

• One issue per PR. The issue number in the title, its acceptance criteria met, and nothing else in the diff.
• Only issues assigned to you, or unassigned ones you have claimed through Drips. If an issue is assigned to someone else, it is theirs.
• Re-open the work that meets both conditions as individual PRs. I will review them in the order they arrive and at the same pace as everyone else's.

Nothing is being closed. These stay open and are yours to re-cut, withdraw or split as you choose.

Two things worth knowing before you re-cut

Some of this has already landed. #488 (SSRF guard for bazaar_search) and #487 (the paid_call host allow-list) cover the same ground as your #449; #486 covers the MCP README. Check current main before rebuilding something that is already there.

main has moved a long way today — #306, #309, #252, #256, #355, #381, #390, #402, #476, #488 and more. Cut from current main, not from where these branches started.

If you believe an issue named here is genuinely yours, say which and I will check the assignment myself — I would rather be corrected than have someone lose work.