fix(payments): address langgraph middleware review follow-ups

[aidandaly24]

Description of changes

Follow-up fixes to the LangGraph payments middleware merged in #546. These came out of a post-merge review of middleware.py. All are scoped to the LangGraph integration; no public API changes.

Correctness

1. Async on_payment_error callback on the sync path now fails loudly.
   The guard that detects an async callback used with sync .invoke() previously raised a TypeError inside the callback try, whose except Exception immediately caught it, logged it, and returned None (PROPAGATE). The developer's misconfiguration was swallowed into a log line and an error message indistinguishable from a real payment failure. The check now runs before the try and propagates, matching the "fail loudly" intent stated in the original commit and class docstring.

2. Async callable objects (async def __call__) are now detected.
   inspect.iscoroutinefunction returns False for a callable instance whose __call__ is async, so such a callback slipped past the guard on the sync path (leaked an un-awaited coroutine, then degraded to PROPAGATE) and was never awaited on the async path. Detection now inspects the bound __call__; the sync path raises and the async path awaits it.

3. Post-payment retry-rejection honors custom handlers.
   _check_retry_rejection hardcoded GenericPaymentHandler + JSON fallback, so when a tool with a registered custom handler returned a bespoke-format 402 after payment (server rejected the signed payment), the still-402 went undetected and was handed back to the LLM as a normal result. It now routes through the custom handler (raw content), mirroring _detect_402, and surfaces the real error detail.

4. Payment header injection preserved when a tool call omits args.
   _detect_402 used request.tool_call.get("args", {}), which returns a throwaway dict when there is no args key, so header injection mutated a dict the retried handler never read. Switched to setdefault("args", {}) so the header reaches the retried call.

Docs

5. Documented the custom-handler input contract.
   Custom handlers receive the raw ToolMessage.content (str or list of blocks), not the middleware's internal wrapped shape. The built-in handlers expect the normalized shape, so passing one of them directly as a custom_handlers value silently fails to detect 402s. Clarified this in the config docstring and README. This is docs-only on purpose: a type-based config guard would wrongly reject legitimate PaymentResponseHandler/GenericPaymentHandler subclasses (the existing TrackingHandler functional test is exactly that).

Behavior change to flag for reviewers

Fix #1 changes async-callback-on-sync from "log + PROPAGATE" to "raise TypeError", and updates the two tests that asserted the swallowed behavior. If the graceful fallthrough was intentional, the alternative is to keep it and only correct the misleading "fail loudly" wording instead. Happy to switch.

Deferred (noted, not addressed here)

Non-correctness cleanups left for a separate change: the "PROPAGATE" magic-string sentinel in _handle_callback_resolution, the remaining near-duplication between _inject_payment_header and _inject_for_error_retry, the redundant name-based detection fallback for generic tools, and _FallbackHandler not subclassing PaymentResponseHandler.

Testing

• Added regression tests for all four correctness fixes; each was verified to fail against the merged middleware.py and pass with these changes (temporarily swapped the merged file back in and ran the new tests: 6 failed / 1 guard-passed, then all pass once restored).
• Full LangGraph unit suite green: 146 passed (up from 141).
• Full payments suite green: 648 passed.
• ruff check and ruff format --check clean on all changed files.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

✅ No Breaking Changes Detected

No public API breaking changes found in this PR.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[jariy17]

Just need to catch all types of async calls.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)