@visa/cli 4.1.0-rc.26 → 4.1.0-rc.261

package/README.md

@@ -1,21 +1,23 @@
 # @visa/cli
 
-Visa CLI v4 gives an AI agent a **Visa Verified Agent** identity and a scoped,
-human-capped signer for a Turnkey-managed wallet. Agents discover paid
-x402/MPP services and pay with USDC over MCP (Model Context Protocol); the
-human approves the limits and every payment is checked against on-device policy
-before anything is signed. Larger browser purchases use a separately approved
-VIC credential and card mandate.
-
-The v4 flow has three parts, always in this order:
-
-1. **Identity** — the human enrolls in the browser (email or Google sign-in, card on file, bank verification) and mints a `.visa` name bound to the agent.
-2. **Delegation** — a pairing ceremony gives the runtime a scoped, revocable
-   Turnkey signer with human-approved per-transaction and daily caps. The
-   runtime never receives the human wallet's root key.
-3. **Payment** — `find → inspect → pay` handles x402/MPP purchases with gasless
-   USDC and explicit maxima; `checkout` / `mandate` handles larger VIC browser
-   purchases.
+Visa CLI v4 pairs an AI runtime to a human-approved **Visa agent identity**.
+The pairing ceremony creates one stable agent ID and activates one
+runtime-custodied Ed25519 identity key. It does not create payment authority,
+a mailbox, or a `.visa` name. New paired agents request publication of their
+public key to the TAP directory by default; owners can durably remove it with
+`visa agent tap-opt-out <agent-id>`.
+
+The product flow has three explicit parts:
+
+1. **Identity** — `setup_start` (or `visa setup start`) opens ONE browser
+   review that covers the exact runtime, its public-key fingerprint, and every
+   requested rail in a single owner approval. The private key stays on the
+   runtime device. The older identity-only doors remain callable for an
+   already-started integration but are hidden from normal discovery.
+2. **Capabilities** — payment methods, spend grants, email and directory
+   bindings are configured separately, each with its own human-visible terms.
+3. **Use** — when a separately provisioned capability exists, the wallet and
+   VIC commands enforce that capability's own policy and approval boundary.
 
 ## Install
 
@@ -31,7 +33,7 @@ Windows PowerShell:
 iwr -useb https://app.visacli.sh/install.ps1 | iex
 ```
 
-Node.js 18+ is required. macOS, Windows, and Linux are supported for the v4 wallet flow.
+Node.js 20+ is required. macOS, Windows, and Linux are supported for the v4 wallet flow.
 
 ## MCP setup
 
@@ -65,44 +67,170 @@ args = ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
 
 There is no CLI subcommand for starting the MCP server directly — the MCP server is the bundled `dist/mcp-server/index.js` entrypoint, which `visa-cli connect <client>` registers for you.
 
-## Enroll a Verified Agent
+### UCP commerce bundle
 
-Enrollment starts from the agent, not the terminal: the agent calls the **`enroll_agent`** MCP tool, which opens the enrollment page in the browser and prints a 6-character confirmation code in the terminal. The human signs in with **email or Google**, chooses the agent's `.visa` name, adds a card, completes the bank's verification step, and types the confirmation code. When the browser reports the credential was sent to the CLI, the agent calls `enroll_agent` with `{"action":"claim"}` to park the credential on the device.
+Install the Visa pairing skill, discovery-first UCP shopping skill, bounded
+Shopify checkout skill, and both Visa and Shopify UCP MCP entries in one step:
 
-Only enter a confirmation code you watched your own terminal print. Enrollment
-must begin with `enroll_agent` and present Turnkey email or Google sign-in.
+```bash
+visa agent skill --commerce --runtime codex
+# runtimes with writable MCP config: codex, openclaw, hermes
+
+# Inspect the installed local bundle without changing skills or MCP config:
+visa agent skill --commerce --runtime codex --check
+```
+
+The shopping skill turns broad requests into a short seller/variant list and
+requires an exact selection plus an all-in ceiling before checkout. The pinned
+Shopify UCP server requires Node.js 22 or newer. A successful run
+reports both MCP entries as mounted or already mounted; restart or reload the
+agent before using the new tools. The installer never performs discovery or a
+checkout itself. The install-only command exits successfully after writing the
+bundle, but reports `commerceReady: false` / `ucp_check_required` until the
+explicit `--check` gate passes. `commerceReady` is a compatibility alias for
+local bundle readiness only; it never proves that a merchant purchase can be
+completed. The JSON result keeps `purchase.ready: false` until a separate live
+checkout preflight is performed.
+
+Checked readiness is read-only: missing or modified skills and missing,
+conflicting, or malformed MCP entries are reported without installing or
+rewriting anything. It parses the active local profile and its pinned Shopify
+profile contract directly from disk, without starting `npx`, and reports the
+exact profile initialization command if local state is missing or invalid. It
+also refuses to claim local natural-language shopping readiness when a
+top-level `ucp` or `shop` skill with a `SKILL.md` is present in the same runtime
+directory. The installer reports those paths but never deletes or disables
+user-owned skills.
+
+If the selected runtime already has a non-equivalent `shopify-ucp` entry, the
+command fails without changing that entry or its environment, authentication,
+timeout, or filtering fields. Rename or remove the existing entry explicitly
+before rerunning; the installer does not silently replace or downgrade it.
+
+### MCP 2026-07-28 compatibility
+
+This release speaks the modern, stateless MCP `2026-07-28` protocol over stdio and deliberately rejects the legacy `initialize` handshake. Your client must support per-request protocol envelopes and `server/discover`; update the client before upgrading Visa CLI if it still sends MCP `2025-*` traffic. `visa-cli connect` can write configuration for every listed client, but configuration support does not imply that an older installed client understands the new wire revision.
+
+The server now exposes:
+
+- JSON Schema 2020-12 tool inputs and outputs, `structuredContent`, namespaced result metadata, cache hints, and receipt `resource_link` blocks.
+- Resources for agent status, capabilities, recent activity, and canonical `visa://receipt/{transactionId}` receipts.
+- Prompts for pairing/funding, spend inspection, safe purchasing, and receipt reconciliation, with completion support.
+- The `io.modelcontextprotocol/tasks` extension for durable, pollable `pay_merchant` approval work. Task lifecycle is owner-scoped in the auth service; an MCP-process restart fails an in-flight checkout closed instead of replaying it.
+- Multi-round-trip `input_required` URL elicitation with HMAC-protected, client-bound request state when the client supports URL elicitation but not Tasks.
+- The `io.modelcontextprotocol/ui` Visa Control Center MCP App at `ui://visa/control-center`.
+
+Visa sidebands no longer pollute business JSON. Clients receive keys such as `io.visa/visa-receipt` and `io.visa/update-available` in result `_meta`.
+
+## Setup doors
+
+There is one blessed door for each transition. Recovery commands are kept
+discoverable only where a shipped flow prints them; legacy starts remain callable
+for compatibility but do not appear in normal CLI or MCP discovery.
+
+| Transition | Blessed door | Status |
+|---|---|---|
+| New agent from an AI runtime or terminal | `setup_start` / `visa setup start` | Canonical: identity and requested rails on one review page |
+| Agent already created in Console | `agent_handoff_claim` / `visa agent handoff-claim <code>` | Canonical Console handoff |
+| Existing owner account on this device | `agent_login` / `visa agent login` | Canonical sign-in |
+| Resume the canonical setup after restart | `setup_status`, then `setup_resume` / `visa setup status`, then `visa setup open` | Canonical recovery |
+| Finish an already-started legacy pairing | `enroll_agent` action `claim` / `visa agent enroll-claim`, `claim`, or `pairing-resume` as printed | Recovery compatibility only |
+| Resume a paused agent | `visa agent resume <agent-id>` | Live lifecycle control, not enrollment |
+| Start an identity-only legacy pairing | `enroll_agent` / `visa agent enroll`, `pair`, `create`, `verify` | Hidden compatibility; do not start here |
+
+## Pair an agent identity
+
+For a NEW agent, call **`setup_start`** with the name the human chooses: one
+resumable setup covers identity plus every requested rail in a single owner
+approval on one review page, and `setup_status` / `setup_resume` carry it
+across restarts. From a terminal, `visa setup start "<name>"` begins the same
+operation.
+
+For a wallet setup, `completed` on the server is necessary but not sufficient
+for the runtime to report ready. `setup_status` first verifies the exact-agent
+local signing path used by wallet preflight and payments; managed runtimes make
+one bounded recovery attempt. Until that evidence is readable, the result is
+`wallet_runtime_not_ready`, no payment is attempted, and the setup record stays
+available for a later resume.
+
+The identity-only legacy handler remains callable for an existing integration or
+an already-started ceremony, but it is deliberately absent from normal discovery.
+Do not start a new agent there.
+
+```bash
+visa setup start "Name"    # one review page, one approval, every rail
+visa agent list
+visa agent show <agent-id>
+```
+
+The advanced `create` → `claim` → `verify` → `pairing-resume` commands are the
+split-device choreography of this same v2 ceremony, not a second enrollment
+system. The review shows the runtime, context, stable agent ID, full public-key
+fingerprint, and expiry. It grants identity only; no spend limits or instruments
+are implied.
+
+On macOS and Linux, the private identity key is stored under
+`~/.visa-cli/agents` in an owner-only directory with file mode `0600`. It is
+currently an exportable local file: copying it transfers identity proof, and
+losing it blocks new proofs because same-agent key recovery is not yet
+available. Protocol-v2 identity pairing fails closed on Windows until the CLI
+can apply and verify an owner-only Windows ACL. The pairing link contains no
+credential or private key.
 
-## Connect an agent runtime (pairing)
+## Recover an existing account session
 
-Enrollment mints identity; **pairing is what lets a runtime sign payments.**
+`visa agent login` opens the Turnkey-first web sign-in for an existing v4
+account, then `visa agent login-claim` stores the returned account session in
+the OS keychain. `--wait` keeps the first command polling for the full
+15-minute browser window.
 
 ```bash
-visa agent create                                                # in the human's terminal — prints the pairing id
-visa agent claim <pairing-id> --runtime <name> --context "<one-line purpose>"
-visa agent verify <pairing-id> <code>                            # verifies the channel, opens the authorization page
-visa agent list                                                  # shows the activated runtime
+visa agent login          # sign in and display the terminal confirmation code
+visa agent login-claim    # resume pickup after returning from the browser
 ```
 
-The browser authorization is the human gate: it shows the runtime and context and sets the **per-transaction and daily spend caps**. If the runtime lost its network response, `visa agent resume <pairing-id>` reprints the code and resumes delivery; `visa agent cancel [pairing-id]` abandons an unapproved request. Pairing credentials are stored on the agent machine with mode `0600`; the pairing link contains no credential.
+This is account-session recovery, not agent pairing. It does not create or
+replace an identity key, delegate a wallet, select a card, set a budget, or
+grant spend authority. The pending PKCE verifier is kept under
+`~/.visa-cli/session-recovery/` in owner-only local state and is pinned to the
+exact web origin that started the flow.
+Session recovery currently fails closed on Windows until the CLI can apply and
+verify an owner-only ACL for this pending verifier.
 
-## Caps, then funding — strict order
+## Wallet capability: grant, caps, then funding
+
+Pairing never creates or repairs payment authority — the owner delegates it in
+a separate grant ceremony, and re-pairing is not a substitute:
+
+```bash
+visa agent login                                          # owner account session, once
+visa agent grant-wallet <agent-id> --ceiling 25 --per-transaction 1 --wait
+```
+
+The owner approves once in the browser; the runtime polls to activation and
+receives a delegated, capped, revocable signer (it can never mint one itself).
+`visa agent pause <agent-id>` temporarily blocks new Visa CLI card and wallet payments at the canonical authority service (mandates remain intact; resume with `visa agent resume <agent-id>`). `visa agent revoke <agent-id>` withdraws the current server grant without touching identity; provider-credential removal is a separate lifecycle.
+
+With a wallet delegated, set caps before funding:
 
 ```bash
-visa wallet limits --per-transaction 0.25 --daily 2.00   # BEFORE any funds arrive
-visa wallet show                                          # address, network, policy
-visa wallet fund                                          # funding instructions
+visa wallet limits --agent <agent-id> --per-transaction 0.25 --daily 2.00
+visa wallet show --agent <agent-id>                       # address, network, policy
+visa wallet fund --agent <agent-id>                       # funding instructions
 ```
 
 Fund the wallet with USDC only after limits are set. Payments are gasless — no ETH is ever needed. Mainnet (Base) is the production default; set `VISA_V4_NETWORK=base-sepolia` for testnet, where `visa wallet fund` points at the faucet.
 
+Updating wallet limits preserves the active session budget window and its spent exposure. Reapplying the same limits is a no-op; `wallet limits` does not provide an implicit session-spend reset.
+
 ## Discover and pay
 
 ```bash
 visa find "current weather by city" --max 0.10   # discovery; spends nothing
 visa inspect <listing-id>                        # fetches the live 402 challenge; spends nothing
-visa pay <listing-id> --max 0.05                 # policy check → sign → settle
-visa activity                                    # recent payments
-visa receipt <receipt-id>                        # journaled proof with on-chain tx
+visa pay <listing-id> --agent <agent-id> --max 0.05 # policy check → sign → settle
+visa activity --agent <agent-id>                    # recent payments
+visa receipt <receipt-id> --agent <agent-id>        # journaled proof with on-chain tx
 
 # Advanced direct-URL mode uses the same probe, policy, and receipt path.
 visa inspect --url https://provider.example/paid
@@ -116,12 +244,25 @@ owned by `apps/mpp`, and VIC uses the checkout/mandate surface. Unsupported
 rails are refused before signing. The wallet exposes no agent key-export
 command.
 
+Each wallet-enabled agent has an isolated Turnkey credential, policy, journal,
+receipts, and paid-response directory. `--agent` / the MCP `agent` field may be
+omitted while exactly one wallet authority exists; with multiple authorities it
+is required so the CLI never guesses which agent can spend.
+
 ## MCP tools (v4 surface)
 
 | Tool | Description |
 |------|-------------|
-| `enroll_agent` | Two-step Verified Agent enrollment: default opens the browser flow with a hand-off challenge; `{"action":"claim"}` stores the enrollment credential on this device |
-| `wallet_status` | Wallet address, network, policy, and pairing state |
+| `agent_capabilities` | Derived live capability map (identity, wallet, card, mail, tap, subway) with upgrade paths |
+| `setup_agent` | Next-step resolver for the wallet rail: `{state, nextAction, blockedBy, steps}`; never spends |
+| `agent_login` | Start/claim the owner's device account session (required before a grant) |
+| `setup_start` | Start ONE resumable setup (identity + rails) in a single human approval; returns the review link and this device's half of the compare code |
+| `setup_status` | Read the server's one `nextAction` and polling cadence; terminal wallet results additionally require exact-agent local signing evidence before reporting ready |
+| `setup_resume` | Put the review link and compare code back in front of the human after a restart or a closed tab |
+| `setup_cancel` | Abandon a setup still waiting on the human; never undoes an approval |
+| `agent_connect` | Initiate an owner-approved spending grant for a paired agent |
+| `agent_connect_poll` | Poll that grant ceremony to activation (returns caps, and the funding address for wallet) |
+| `wallet_status` | Delegated wallet address, network, and policy state |
 | `wallet_policy_set` | Set per-transaction / daily caps (with human approval) |
 | `wallet_discover` | Sweep x402 directories for services, with live re-probing |
 | `wallet_probe` | Fetch a service's live 402 challenge without paying |
@@ -129,6 +270,7 @@ command.
 | `wallet_directory_pay` | Directory find + pay in one call, same policy path |
 | `wallet_history` | Journaled payment receipts |
 | `wallet_fund` | Funding instructions for the wallet address |
+| `checkout_merchants` | Read-only: merchants where your card has completed real checkouts, from this device's receipts |
 | `get_status` | Account and wallet state summary |
 | `feedback` | Submit feedback on a tool result |
 | `reset` | Clear local auth state and credentials |
@@ -163,11 +305,19 @@ visa pay <listing-id> --max <usd>
 visa activity
 visa receipt <receipt-id>
 
-# Human-approved agent runtime pairing
+# Primary same-machine setup
+visa setup start "Name" --rails card,wallet
+visa setup status
+
+# Existing-account session recovery (separate from identity pairing)
+visa agent login
+visa agent login-claim
+
+# Recovery compatibility for a legacy split-device ceremony already in flight
 visa agent create
 visa agent claim <pairing-id> --runtime <name> --context "<purpose>"
 visa agent verify <pairing-id> <code>
-visa agent resume <pairing-id>
+visa agent pairing-resume <pairing-id>
 visa agent cancel [pairing-id]
 visa agent list
 
@@ -200,14 +350,19 @@ visa-cli feedback                   # submit feedback
 
 | Path | Contents |
 |------|----------|
-| `~/.visa-mcp/agent-credential.json` | Verified Agent enrollment credential (mode 0600) |
-| `~/.visa-cli/` | Pairing / delegated signer credentials (mode 0600) |
-| `~/.visa-v4/policy.json` | Wallet spend policy — never edit by hand; use `visa wallet limits` |
+| `~/.visa-cli/pairings/` | Pending ceremony verifier or runtime identity key (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/agents/` | Activated agent identity, runtime private key, and signed activation credentials (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/session-recovery/` | Pending login-only PKCE verifier and pinned web origin (owner-only mode 0600 on macOS/Linux) |
+| `~/.visa-cli/removed-agents/` | Records of agents deleted on the server, kept 30 days then dropped. Written automatically; nothing reads it |
+| `~/.visa-mcp/agent-credential.json` | Legacy checkout-credential compatibility record (mode 0600) |
+| `~/.visa-v4/agents/<agentId>/` | Per-agent Turnkey credential, spend policy, reservation journal, receipts, and paid responses — never edit by hand |
 
 ## Troubleshooting
 
-**Wallet commands report pairing is required**
-Payments on a production network require the paired delegated credential — complete enrollment and pairing first. There is no local fallback wallet on mainnet, by design.
+**Wallet commands report that payment setup is required**
+Identity pairing deliberately grants no payment authority. Complete the
+separate wallet/instrument and spend-policy setup when available; pairing again
+will not upgrade an identity into a signer.
 
 **`policy refused` from `pay`**
 A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet limits` with the human's approval.
@@ -215,8 +370,9 @@ A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet
 **`expected 402 from <url>`**
 That URL isn't payment-gated — probe the service's actual paid route (`wallet_probe` / `visa find`).
 
-**Pairing ended `expired` or `cancelled`**
-The ceremony timed out — re-run `visa agent create` and claim the new pairing id.
+**Setup ended `expired` or `cancelled`**
+The ceremony timed out — restart with `visa setup start "Name"`, then follow
+`visa setup status` until it reports the next action.
 
 **Tools don't appear in the AI client**
 Restart the client or reconnect the MCP server (`/mcp` → `visa-cli` → reconnect in Claude Code). Re-run `visa-cli connect <client>` to rewrite the config.

package/dist/checkout-engine/adapters/generic.d.ts

@@ -5,13 +5,82 @@ import type { Contact, FillResult, FilledField } from '../types.js';
 export interface CheckoutAdapter {
     name: string;
     matches(detected: DetectResult): boolean;
+    prepareContact?: (page: Page, contact: Contact) => Promise<FillResult>;
     fill(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact): Promise<FillResult>;
 }
 export declare function resolveLocator(page: Page, entry: FieldEntry): Locator;
 export declare function scrubFillErrorMessage(message: string, value: string): string;
+/**
+ * A fill failure in a few words, for a message a human reads.
+ *
+ * Playwright's error is a multi-line call log — useful in the evidence file,
+ * unreadable in a refusal message and in the receipt an operator opens a week
+ * later. The refusal names WHICH fields refused; without this it never says
+ * WHY, so diagnosing a merchant we cannot drive means either reproducing it or
+ * reading someone's evidence JSON. Each cause maps to a different fix:
+ *
+ *   not editable      — the input exists but is readonly/disabled at fill time
+ *                       (a custom widget owning the value, or a not-yet-ready
+ *                       form). Typing will not help; the field needs an adapter
+ *                       or a longer wait.
+ *   not a text field  — a non-input element pretending to be one. Needs an
+ *                       adapter that drives the widget.
+ *   not visible /
+ *   detached          — a re-render race. The reveal loop is the lever.
+ *
+ * Input is already scrubbed by scrubFillErrorMessage; this only ever shortens.
+ */
+export declare function summarizeFillFailure(error: string | undefined): string;
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export declare function contactNameShapes(contact: Contact, cardholderName?: string): {
+    fullName?: string;
+    first?: string;
+    last?: string;
+};
+export declare function fillContactFieldMap(page: Page, fields: FieldMap, contact: Contact, opts?: {
+    fillTimeoutMs?: number;
+    detect?: (page: Page) => Promise<DetectResult>;
+}): Promise<FilledField[]>;
 export declare function fillFieldMap(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact, opts?: {
     fillTimeoutMs?: number;
+    detect?: (page: Page) => Promise<DetectResult>;
 }): Promise<FilledField[]>;
+/**
+ * Re-detect and adopt fresh entries for every card field after the panel is
+ * unfolded. Injected for tests; the executor's own detector is used in
+ * production.
+ */
+export declare function refreshCardGroupFromPage(page: Page, fields: FieldMap, detect?: (page: Page) => Promise<DetectResult>): Promise<string[]>;
+/**
+ * Reveal card fields that a checkout keeps collapsed until a payment method is
+ * chosen.
+ *
+ * `fillFields` skips any entry with `visible === false`, so a card-number input
+ * sitting inside a folded panel is never even attempted — the generic adapter
+ * then reports `ok: false` ("fill incomplete") without having typed anything.
+ * That is the correct default: filling an invisible input is how a credential
+ * gets typed into the wrong place. But a payment-method `<select>` guarding the
+ * card panel is common enough to be worth handling, and the recovery is a
+ * single deterministic interaction rather than a guess.
+ *
+ * We only ever SELECT a card option — never a wallet, bank transfer, or
+ * anything else — and we only act when the card field is already detected but
+ * hidden. If nothing changes, the caller proceeds exactly as before and still
+ * fails closed.
+ *
+ * Mutates `fields.number.visible` on success so the subsequent fill attempts
+ * the field it just revealed.
+ */
+export declare function revealCollapsedCardSection(page: Page, fields: FieldMap, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    revealed: boolean;
+    via: string | null;
+}>;
 export declare class GenericAdapter implements CheckoutAdapter {
     name: string;
     matches(_detected: DetectResult): boolean;