feat(payments): Add LangGraph integration for payment handling

[ragsu43]

Description of changes:

Added LangGraph middleware and config files for developer integration with ACP.

[aidandaly24]

Nice work on this. The overall flow (detect, sign, inject, retry, across sync and async, plus the recovery callback and auto-session) reads well and the unit coverage is thorough. Requesting changes on a couple of correctness issues before this goes in, plus some cleanup.

Blocking:

• Sync path silently drops async on_payment_error callbacks (middleware.py:555).
• _check_post_recovery_rejection surfaces the wrong error detail because it never swaps in the fallback handler (middleware.py:373).

Should fix:

• Detection ignores the name-based handler registry, so legacy text-format 402s get missed (middleware.py:267).
• The exported MCPRequestPaymentHandler can't actually be used as a custom_handlers entry because of a shape mismatch (middleware.py:269).

Cleanup:

• The sync/async and the two rejection-check methods are near-duplicates and have already drifted, worth collapsing (middleware.py:353).
• Move the inline imports up to the top of the file per our style (middleware.py, several spots).

One process note: the header on test_functional.py says any change to this middleware has to be validated against a live Base Sepolia testnet before merge. Please confirm that run has happened.

[aidandaly24]

This drops async on_payment_error callbacks on the sync path. The async version at line 727 checks inspect.iscoroutinefunction before awaiting, but here we call the callback directly.

If someone registers an async def callback and runs the agent with agent.invoke(), this returns an un-awaited coroutine. It isn't a str and it isn't ErrorResolution.RETRY, so line 568 returns None and we fall through to PROPAGATE. The callback body never runs, the retry/fix is silently discarded, the LLM gets the default error message, and you leak a coroutine was never awaited RuntimeWarning.

Either run it to completion here (e.g. via an event loop), or detect a coroutine function up front and raise a clear error so it fails loudly instead of silently.

[aidandaly24]

Copy-paste drift from _check_post_payment_rejection. When the fallback detects the 402 (lines 369-371) this never reassigns _rh to _FallbackHandler(fallback), unlike the sibling method at line 343.

So _rh stays the GenericPaymentHandler, extract_body here looks for the PAYMENT_REQUIRED: marker, doesn't find it in raw JSON, and returns None which becomes {}. For a raw-JSON or MCP tool that returns {"statusCode":402,"body":{"error":"budget exceeded"}} on the recovery retry, the LLM sees rejected after recovery (unknown) instead of the real budget exceeded.

Reassign _rh = _FallbackHandler(fallback) inside the fallback branch, matching _check_post_payment_rejection.

[aidandaly24]

Detection only ever uses GenericPaymentHandler on the non-custom path (marker only), plus the JSON-only _fallback_detect_402. The name-based registry (http_request maps to HttpRequestPaymentHandler) is only consulted on the injection side through _get_handler.

That means a tool returning 402 in the legacy Status Code: / Headers: / Body: text-block format, which is exactly what HttpRequestPaymentHandler.extract_status_code was written to parse (handlers.py:479), never gets detected here. Generic finds no marker and returns None, and _fallback_detect_402 can't json.loads Status Code: 402. The 402 passes through as a normal result and payment never fires. This bites anyone who brings their own http_request-style tool with provide_http_request=False.

Consider routing detection through get_payment_handler(tool_name, tool_args) as well, not just injection.

[aidandaly24]

Shape-contract gotcha for custom handlers. We hand the detection handler the _prepare_for_handler output, which is {"content": [{"text": ...}]}. That works for GenericPaymentHandler, but the exported MCPRequestPaymentHandler expects the raw result with top-level structuredContent/httpStatus.

Since config accepts any PaymentResponseHandler, custom_handlers={"my_mcp_tool": MCPRequestPaymentHandler()} silently never detects a 402: extract_status_code reads keys that aren't in the prepared shape and returns None, and because has_custom_handler is True the lenient fallback at line 272 is skipped.

Either feed custom handlers the raw content, or document and enforce that a custom handler must consume the prepared shape.

[aidandaly24]

Three chunks of near-duplicated logic in this file, and the drift called out at line 373 is a direct result. _check_post_recovery_rejection is basically _check_post_payment_rejection, _ainvoke_error_handler mirrors _invoke_error_handler (~90 lines each, and their inner retry block re-implements _inject_payment_header), and the GenericPaymentHandler plus _fallback_detect_402 detect ladder shows up in three methods.

A single _resolve_402(content) helper plus a shared retry/inject body (the async version just wraps it with to_thread) would collapse all of this and stop the two rejection checks from diverging again.

[aidandaly24]

Imports belong at the top of the file, not inside methods. This one (from ...handlers import GenericPaymentHandler) is repeated inside _detect_402, _check_post_payment_rejection (335), and _check_post_recovery_rejection (364). Same story for import json as _json (187), from .errors import ... (537, 709), import asyncio (635, 706), and import inspect (707).

None of these have a cycle risk (.errors doesn't import middleware), so hoist them to the module top. The repeated handler import is also part of what let the two rejection checks drift.