feat(payment): add read-only imperative commands

[aidandaly24]

Description

First layer of the AgentCore Payments command stack, targeting refactor.
Mutation follow-ups #2277 (identity providers), #2280 (managers/connectors), and
#2281 (sessions/instruments) are temporarily closed with their branches preserved.
The current focus is the read CLI, followed by a separate read-only TUI PR.

Updated against refactor at 4a235162. Payment read behavior, required-field/TUI
routing conventions, and fixture recordings are unchanged.

Read help now distinguishes application-user scope from optional observability labels,
orders required selectors before optional inputs, and uses the existing Gateway/Identity
pagination wording. README examples connect manager selection, instrument list/get, and
balance. Flag names, schemas, defaults, request handling, and JSON output are unchanged.

Adds 11 project-free, headless read commands:

• payment manager get|list
• payment connector get|list
• payment session get|list
• payment instrument get|list|balance
• identity payment-credential-provider get|list

Primary selectors use IDs. For session/instrument reads, Core resolves the manager with
GetPaymentManager in the configured region and supplies the returned ARN to the data plane.
Callers therefore need the manager-read permission as well as the requested data-plane action.
JWT-only managers are rejected before data-plane access.

Balance requires an explicit chain, defaults to USDC, preserves atomic amount strings/decimals,
and propagates service errors rather than converting them to zero.

The layer includes read-side Core contracts, injected client wiring, read-only tests, and recorded
Get/List fixtures. It adds no payment mutation handlers, IAM provisioning, credential-write input
handling, or dedicated TUI screens.

Related Issue

Part of #2272. The preserved mutation branches cover the remaining headless scope.

Documentation PR

N/A. README command tree, read examples, and permission requirements are updated here.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

• RECORD=0 bun test: 3,259 passed, 0 failed across 229 files.
• bun run typecheck
• bun run lint:check, bun run format:check, bun run secrets:check
• bun run build
• Existing focused read suite: 38 passed; help rendered for all 11 read commands without AWS clients.
• Focused review of consolidated tests and comparison with earlier Runtime/Gateway/Identity PRs.
• Previous baseline Linux, Windows, and macOS CI on 38c4d079: https://github.com/aws/agentcore-cli/actions/runs/34625569401

Test source was consolidated from 1,475 to 561 added lines, reducing the read-layer snapshot
from 3,448 to 2,233 additions at that cleanup. The subsequent help polish adds no tests or fixtures.
Each read command retains fixture-backed root/Core coverage, list pagination is checked at the
SDK boundary, shared manager-resolution failures are tested once in Core, and balance keeps its
chain/default-token/precision/zero/error checks. Unused test-client configuration and write-only
fixtures were removed from this layer.

Uses the refactor Bun scripts rather than the npm scripts from the repository's main template.
No AWS resources were changed while preparing this split.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

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

[agentcore-devx-automation]

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

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

This is a well-scoped read-only surface for AgentCore Payments. I reviewed the diff end-to-end and did not find issues that need to change before merging.

Highlights that made this easy to sign off on:

• Boundaries. PaymentClient sits cleanly on top of the shared control/data client factories. Data-plane methods route through a single sendData helper that (a) rejects ARN-shaped managerId before any client is configured, (b) fetches the manager fresh on every call, (c) refuses CUSTOM_JWT managers with a USER-sourced InputValidationError that explains the bearer-token limitation, and (d) surfaces a MalformedServiceResponseError when the service omits the ARN. Each of these branches is asserted in payment.read.test.ts.
• Handlers. Required-flag validation happens before Core is touched, and the tests confirm no SDK client is ever constructed on the failure path (both omitted and empty variants). ARN selectors and the removed --manager-arn flag are explicitly rejected.
• Big-number fidelity. GetPaymentInstrumentBalance responses are handed straight to the JSON renderer, and balance.test.tsx pins down that the atomic amount string beyond MAX_SAFE_INTEGER and its decimals survive round-tripping, including the "0" case. The handler correctly does not convert service errors to a zero balance.
• Region/endpoint propagation. Both control and data client factories receive the same { region, endpoint } derived from context; verified for the eu-west-1 + custom endpoint case.
• Test style. Mocks live at the SDK send boundary and everything else — router, CoreClient, JSON rendering, IO — runs for real. Fixture replay via fixtureFactories gives realistic wire shapes without over-mocking.
• Command tree. payment.read.test.tsx asserts the exact nine-leaf shape (manager get/list, connector get/list, session get/list, instrument get/list/balance) and that no leaf accepts --wait/--browser or exposes TUI, matching the "CLI only for now" stance in the README.
• Identity surface. Only get and list are wired for payment-credential-provider, consistent with the read-only scope; the create/update/delete methods added to CoreIdentityClient are unexposed but ready for a follow-up.
• Connector hints. connector get emits the AUTHENTICATION_EXPIRED / AUTHENTICATION_FAILED warning only in non-JSON mode and never suggests write commands that don't exist yet — tested for both --json and bare invocations.

Nothing blocking. Ship it.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.60441% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.08%. Comparing base (4a23516) to head (42f2b9a).

Files with missing lines	Patch %	Lines
src/handlers/payment/instrument/balance/index.tsx	88.88%	8 Missing ⚠️
src/core/identity.tsx	70.00%	3 Missing ⚠️
src/handlers/payment/instrument/get/index.tsx	96.07%	2 Missing ⚠️
src/handlers/payment/instrument/list/index.tsx	95.83%	2 Missing ⚠️
src/handlers/payment/session/get/index.tsx	95.34%	2 Missing ⚠️
src/handlers/payment/connector/get/index.tsx	97.43%	1 Missing ⚠️
src/handlers/payment/connector/list/index.tsx	96.55%	1 Missing ⚠️
src/handlers/payment/session/list/index.tsx	97.61%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2276      +/-   ##
============================================
+ Coverage     97.06%   97.08%   +0.02%     
============================================
  Files           569      587      +18     
  Lines         39322    39906     +584     
============================================
+ Hits          38167    38743     +576     
- Misses         1155     1163       +8     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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