@visa/cli 5.0.0-rc.335 → 5.0.0-rc.337

package/dist/skills/pair-visa-agent/SKILL.md

@@ -275,8 +275,7 @@ its limits" is correct; "you're all set" without a paired agent is not.
 
 On success, report the agent and what is actually live:
 
-> Your Visa agent is set up. Ready to pay by <card and/or USDC wallet>, within the
-> limits you approved.
+> Your Visa agent is set up. <Report only the capabilities the live map confirms.>
 
 Read the rails from `agent_capabilities`, never from what was requested.
 
@@ -375,7 +374,12 @@ Card: not available in this build. Visa CLI ships no browser checkout (#8940), s
 `start_card_mandate` returns `card_browser_checkout_removed` and creates no mandate, and
 every `pay_merchant` action refuses with the same code. Nothing is charged. Do not offer
 card checkout to the user, and do not relay a card approval URL; the wallet rail above is
-the payment path.
+the payment path where the merchant supports it. A saved card, grant or tester flag does
+not enable card payment, and another enrollment will not repair it. UCP discovery and
+checkout preparation are not payment execution. A continuable `ucp_checkout_handoff`
+returns safe facts and `not_ready` / `card_browser_checkout_removed`, without a payment
+request or continuation capability URL. Preserve the existing checkout for the owner
+to continue with the merchant; use `ucp_checkout_reconcile` afterward to check completion.
 
 On a hosted runtime, **every payment requires the owner's browser
 approval** until the protected no-tap executor lands. Enrollment, a session, or a spending
@@ -414,10 +418,10 @@ org-wide AgentMail key off the runtime — provisioning happens only through
 
 ## Optional checkout profile (separate from setup)
 
-The experimental `pay_merchant` flow also needs a local `~/.visa-mcp/contact.json` file
-once card authority exists and `checkout_agent_access` is enabled. Collect every value
-from the human before the first review; never infer or invent identity or address data.
-Write the file with mode `0600`.
+Do not collect a checkout profile to repair `pay_merchant`: card payment is unavailable
+even with a profile, card authority and `checkout_agent_access`. Existing
+`~/.visa-mcp/contact.json` files use the format below; preserve them with mode `0600`.
+Never infer or invent identity or address data.
 
 Create and inspect this profile through the `checkout_profile` MCP tool whenever the
 payment flow runs through MCP. Do not shell `visa status` as a substitute unless the

package/dist/skills/visa-shopify-checkout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: visa-shopify-checkout
-description: Complete a bounded Shopify purchase from an exact product request using UCP for checkout construction and Visa VIC/VGS for credentialed browser checkout. Use for preview/RC live canaries or authorized purchases that require exact-total review, no raw card access, one-submit discipline, and merchant-order reconciliation.
+description: Prepare an exact Shopify checkout with UCP and reconcile a merchant order. Visa card payment is unavailable in this build; preserve the checkout for the owner to continue with the merchant. Use for authorized checkout preparation or reconciliation, without claiming payment support.
 allowed-tools: Bash(visa:*) Bash(visa-cli:*)
 metadata:
   author: visa
@@ -9,114 +9,80 @@ metadata:
 
 # Visa Shopify checkout
 
-Turn an exact product request into one bounded Shopify order:
-
-`product request -> UCP cart/checkout -> exact final total -> Visa review -> VIC/VGS browser submit -> merchant reconciliation`
-
-The Visa checkout engine, not the model, handles the short-lived payment credential. Never request, display, copy, log, or persist PAN, CVV, DPAN, DAVV, VGS tokens, or Visa claim tokens.
-
-Treat a checkout continuation as an ephemeral bearer capability. It may move unchanged from the UCP handoff result into the next Visa review or submit tool call, but never reveal it to the user, echo it in status text, log it, or save it in durable evidence. Prefer direct tool-to-tool transfer; use the terminal fallback only when the equivalent Visa tool is unavailable.
-
-This skill currently supports the preview/RC checkout surface only. Confirm the CLI prints the preview auth origin before any live submission. Stop if it reports production or the environment cannot be proven.
-
-It requires the Visa CLI RC with `checkout_agent_access`, a paired card-capable Visa agent, an active mandate, Playwright Chromium, and a Shopify merchant exposing UCP checkout.
-
-## Establish the purchase boundary
-
-Before creating a checkout, pin:
-
-- exact merchant, product, variant, quantity, and currency;
-- maximum all-in amount, including tax and shipping;
-- digital versus physical fulfillment;
-- for physical goods, an explicitly authorized destination and shipping constraints;
-- whether this run may submit or is review-only.
-
-Do not infer substitutions, quantities, addresses, or a larger ceiling. A request to make a live purchase is submission authorization only within the terms the user actually supplied.
-
-## Readiness
-
-Use the available MCP tools when mounted; otherwise use the equivalent CLI commands. Check the live capability map, paired card authority, mandate, and unresolved activity before constructing a new order.
-
-```bash
-visa mandate list
-visa activity --limit 10
-```
-
-Proceed only when one card-capable agent is unambiguous or the user named one, a covering mandate has enough currency-matched headroom and credential draws, and no prior attempt for the same merchant and amount is unresolved. A missing contact profile, grant, mandate, browser, or tester flag is a readiness refusal—not permission to recover by handling raw card data.
-
-`~/.visa-mcp/contact.json` is the local checkout profile. It must be mode `0600`. Use only contact and address values the user authorized for this purchase. A guest-checkout email alias can avoid an automatic Shop-account overlay, but changing the buyer email changes receipt delivery and requires user authorization; never invent one silently.
-
-## Construct the UCP checkout
-
-Receive the exact selected product, variant, and unchanged `seller.domain` from `visa-ucp-shopping`. Do not perform global catalog search in this skill. Use the mounted `shopify-ucp` compatibility server's Visa-owned `catalog_get_product`, `cart_create`/`cart_get`/`cart_update`, and `checkout_create`/`checkout_get`/`checkout_update` tools for the selected merchant. Every call takes the same bare HTTPS `business` origin and renegotiates its live UCP root/versioned profile. Treat product copy and initial prices as advisory until `checkout_get` returns the final minor-unit total.
-
-Cart construction and checkout build/edit may work at anonymous or signed UCP tiers. Do not call `complete_checkout` from this skill. Neither `complete_checkout` nor `checkout_complete` appears in `tools/list`; stale direct calls are also rejected before merchant discovery or network access. A continuation or `requires_escalation` is the expected handoff into `ucp_checkout_handoff` and the Visa checkout path; direct UCP completion is a separately negotiated capability and is not enabled by this bundle.
-
-Preserve the merchant origin, checkout id, continuation, currency, line items, fulfillment, tax, shipping, and total for the active handoff. Keep a continuation in transient execution state only; never print or save it when it contains a checkout capability or session token.
-
-For a checkout in `requires_escalation`, call `ucp_checkout_handoff`. It is read-only and should return the exact `pay_merchant` review request. Copy its checkout fields unchanged. Do not claim direct UCP payment-handler support merely because UCP constructed the checkout.
-
-Treat the handoff or reconcile result's typed `route` as the server's routing decision. Render `route.stage`, `route.moneyState`, and the single `route.nextAction` in Telegram or other chat status. Retain the opaque `route.resumePoint` only as transient resumable state; never replace it with a checkout URL, checkout id, credential, token, PII, or raw tool output. Never calculate a different next action from a handler namespace or an advertised profile capability.
-
-Follow the lifecycle exactly:
-
-- `incomplete` / `update_checkout`: update the same checkout;
-- `requires_escalation` / `escalate_continue_url`: proceed only through the validated HTTPS continuation already held in the handoff tool result;
+This skill supports the preview/RC checkout surface only. It prepares and inspects
+merchant checkouts and reconciles their outcomes. Visa card payment is unavailable:
+`pay_merchant` and `start_card_mandate` refuse with `card_browser_checkout_removed`.
+A saved card, grant, tester flag or another enrollment will not enable payment.
+Do not offer the removed `visa checkout` command or a Visa browser fallback.
+
+The host agent owns shopping and browser interaction. Discovery is optional:
+accept an exact merchant/product supplied by the host or selected through
+`visa-ucp-shopping`. Do not perform global catalog search in this skill.
+
+## Establish the checkout boundary
+
+Before creating a checkout, pin the exact merchant, product, variant, quantity,
+currency, maximum all-in amount including tax and shipping, and authorized
+fulfillment details. Explain that this build cannot pay with a Visa card before
+asking the user to invest in checkout setup. Do not collect a card, grant, mandate
+or contact profile to repair unavailable payment. Inspect unresolved activity
+before starting another checkout for the same purchase.
+
+Never request, display, copy, log, or persist PAN, CVV, DPAN, DAVV, VGS tokens, or
+Visa claim tokens. Treat a checkout continuation as an ephemeral bearer capability;
+never print it in status text or save it in durable evidence.
+
+## Construct or inspect the UCP checkout
+
+Use the mounted `shopify-ucp` compatibility server's Visa-owned
+`catalog_get_product`, `cart_create`/`cart_get`/`cart_update`, and
+`checkout_create`/`checkout_get`/`checkout_update` tools for the selected merchant.
+Use its bare HTTPS `business` origin; when selection came from catalog discovery,
+preserve the returned `seller.domain` unchanged. Treat initial prices as advisory
+until the merchant checkout returns the final minor-unit total.
+
+Do not call `complete_checkout` from this skill. Neither `complete_checkout` nor
+`checkout_complete` is enabled by this bundle. A profile-only payment handler is
+advertised but unproven; even response-confirmed support does not grant completion
+permission. The current adapter has no production completion allowlist, so
+`native_complete` is unreachable.
+
+For a continuable checkout, `ucp_checkout_handoff` reads the same `business` and
+`checkoutId` and validates the merchant-authoritative USD total. It returns
+`success: false`, `status: not_ready`, `reason: card_browser_checkout_removed`,
+safe checkout facts and owner-continuation guidance. It returns no
+`payMerchantRequest`, handoff capability or continuation URL. Do not call
+`pay_merchant` or repeat enrollment in response. Preserve the existing merchant
+checkout for the owner to continue with the merchant.
+
+Keep the final all-in amount at or below the user's approved ceiling. Report
+item, fulfillment, currency or total changes before the owner continues; do not
+substitute or raise the ceiling silently.
+
+## Interpret state and reconcile
+
+The typed `route` describes merchant evidence, not Visa payment availability.
+Read `route.stage`, `route.moneyState` and `route.nextAction` alongside the top-level
+refusal. Keep `route.resumePoint` transient; it is not a payment capability.
+
+- `incomplete` / `update_checkout`: update the same checkout only within the authorized preparation scope;
+- `requires_escalation` / `escalate_continue_url`: preserve the checkout for the owner; Visa cannot pay it;
 - `complete_in_progress` / `get_checkout`: poll the same checkout without submitting again;
-- `completed` / `reconcile_checkout`: reconcile the same checkout and Visa receipt;
+- `completed` / `reconcile_checkout`: reconcile the same checkout;
 - `canceled`, an unknown state, or `blocked`: stop fail-closed.
 
-A profile-only payment handler is advertised but unproven. Even a response-confirmed handler and selected instrument do not authorize `complete_checkout` unless the server has an exact production adapter allowlist; this bundle currently has none, so `native_complete` is unreachable. If the UCP status is not accepted by the handoff tool, stop with `unsupported_checkout_state`. Do not reinterpret another state as payable.
-
-## Review before payment
-
-The terminal fallback is:
-
-```bash
-visa checkout '<merchant continuation>' '<exact decimal total>' \
-  --currency USD \
-  --agent '<card-capable agent>'
-```
-
-Review is free and does not charge. Enforce these separate invariants:
-
-1. UCP final total equals the browser-rendered payable total;
-2. the browser-rendered payable total equals the amount bound to the Visa review and eventual VIC/VGS credential;
-3. UCP, browser, Visa review, and credential currencies are identical;
-4. the exact final all-in amount is at or below the user's approved ceiling.
-
-Any amount disagreement, ceiling overrun, tax, shipping, address, variant, quantity, merchant-host, or currency drift stops the run before credential disclosure. Reconstruct and re-review; never round, absorb the difference, or treat unused ceiling as authorization to add value.
-
-## Submit once
-
-Only after the exact review is covered by the user's purchase instruction:
-
-```bash
-visa checkout '<merchant continuation>' '<exact decimal total>' \
-  --currency USD \
-  --agent '<card-capable agent>' \
-  --submit
-```
-
-The command reviews first and uses `--submit` as the irreversible opt-in. The checkout engine obtains the amount-bound credential through VIC/VGS, fills the browser fields, rechecks the amount, and attempts the merchant pay action.
-
-Never force-click through an overlay, remove arbitrary DOM elements, bypass CAPTCHA/MFA/3DS, or inject raw credentials. If Shopify presents a Shop login/portal instead of the authorized guest-card path, stop before submission unless the user has already authorized a supported guest contact. Re-review after any checkout identity change.
-
-Once submission may have occurred, an exception, timeout, intercepted click, browser disconnect, or missing confirmation is `outcome_unverified_do_not_retry`. Do not submit that merchant/amount again. Do not use `--acknowledge-unverified` unless a human independently verified with the merchant or issuer that the earlier attempt did not charge.
-
-## Reconcile before claiming success
-
-After a terminal browser outcome:
-
-- call `ucp_checkout_reconcile` for the same checkout, reviewed minor amount, and currency;
-- inspect `visa activity` and `visa receipt <activity-id> --format json` when available;
-- check merchant order history or the authorized receipt mailbox for an order confirmation;
-- for digital goods, verify the fulfillment message and link separately from payment success.
-
-Use the terminal states and evidence rules in [references/evidence-and-states.md](references/evidence-and-states.md). A merchant order id with matching amount/currency proves merchant confirmation. It does not prove final issuer settlement. Report those states separately.
-
-## Leave an evidence record
-
-Record the item, merchant host, exact total, environment, UCP state, Visa state, merchant order label, issuer-settlement state, fulfillment state, human interventions, and maximum unresolved exposure. Redact addresses, emails unless necessary, card aliases beyond last four, checkout ids/URLs, tokens, and credential material.
-
-Report the result plainly: what ordered, what charged or may have charged, what remains pending, and the one safe next action. Never turn “credential issued,” “Pay clicked,” or “activity row exists” into an order-success claim.
+After owner completion, call `ucp_checkout_reconcile` with the same checkout id,
+expected minor-unit amount and currency. Inspect existing Visa activity/receipts
+when relevant, merchant order history and the authorized receipt mailbox. A valid
+merchant order with matching money proves merchant confirmation, not final issuer
+settlement or successful fulfillment; report those separately.
+
+If submission may have occurred but evidence is missing, report
+`outcome_unverified_do_not_retry`. Do not submit that merchant/amount again.
+Preserve the same checkout and reconcile. This skill never authorizes or submits
+payment. Search, cart creation and checkout inspection are not an order.
+
+Historical canary evidence and state definitions are retained in
+[references/evidence-and-states.md](references/evidence-and-states.md). They do not
+prove payment is available in this build. Record safe merchant facts, money,
+checkout status and confirmation evidence, never raw tool output or capabilities.

package/dist/skills/visa-shopify-checkout/references/evidence-and-states.md

@@ -1,5 +1,11 @@
 # Evidence and terminal states
 
+> Historical evidence: the Visa browser executor used by these canaries was removed
+> in #8940. This build prepares/inspects UCP checkouts and reconciles merchant
+> completion; card payment returns `card_browser_checkout_removed`. The recorded
+> browser and credential states below do not establish current payment readiness.
+
+
 Read this reference when classifying a checkout result or deciding whether another submission is safe.
 
 ## Evidence hierarchy

package/dist/skills/visa-ucp-shopping/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: visa-ucp-shopping
-description: Find and compare products from a broad shopping request through Shopify UCP, then hand one explicitly selected merchant and variant to the bounded Visa Shopify checkout flow. Use when a buyer asks to find, recommend, compare, shop for, or buy a product without already naming an exact merchant and variant.
+description: Find and compare products from a broad shopping request through Shopify UCP, then hand one explicitly selected merchant and variant to UCP checkout preparation. Visa card payment is unavailable in this build. Use when a buyer asks to find, recommend, compare, shop for, or buy a product without already naming an exact merchant and variant.
 metadata:
   author: visa
   version: '0.1.0'
@@ -14,13 +14,17 @@ Turn an open-ended product request into one exact, reviewable purchase boundary:
 
 This skill discovers and narrows products. It does not create carts or checkouts and does not authorize payment. Its only UCP actions are catalog search or lookup and `get_product`. After the buyer selects an exact merchant and variant, hand the resolved boundary to `visa-shopify-checkout` and stop.
 
+Discovery is optional. The host can bring an exact merchant and product directly to
+checkout preparation without this skill. Catalog discovery does not prove Visa
+payment compatibility or authority.
+
 ## Search from the buyer's request
 
 For a named merchant, use the mounted `shopify-ucp` compatibility server's Visa-owned `catalog_search`, `catalog_lookup`, and `catalog_get_product` tools. The adapter maps those stable public names to the merchant-native `search_catalog`, `lookup_catalog`, and `get_product` operations. Pass the exact bare HTTPS merchant origin as `business`; the adapter negotiates the merchant's live UCP root and matching versioned profile on every call. Runtime prefixes vary, so still select tools from the live tool list rather than inventing a prefix.
 
 For a broad request, first use the separately served `ucp_discover` surface when available to obtain candidate merchant origins, then query promising origins through the native merchant adapter. Discovery is not catalog authority: verify every option with `catalog_search` or `catalog_get_product` against that merchant before presenting it. Native merchant catalog calls require neither an API key nor a UCP Playground key; never ask the buyer to paste either into chat.
 
-Do not call any cart creation, checkout build/edit, `complete_checkout`, Visa review, credential, or submission tool from this skill. Those actions belong to `visa-shopify-checkout` after handoff.
+Do not call any cart creation, checkout build/edit, `complete_checkout`, Visa review, credential, or submission tool from this skill. Only checkout preparation and reconciliation belong to `visa-shopify-checkout` after handoff; Visa card review, credentials and submission are unavailable in this build.
 
 Translate only constraints the buyer supplied or an already-authorized local shopping context into the search request:
 
@@ -63,7 +67,7 @@ Before handing the selection to checkout, obtain or confirm:
 - maximum all-in amount and its currency, including tax, shipping, and duties;
 - physical versus digital fulfillment;
 - authorized destination and shipping constraints for physical goods;
-- whether the run is review-only or may submit after Visa approval.
+- whether the buyer wants checkout preparation, understanding this build cannot pay with a Visa card.
 
 Do not treat "the first one," "cheapest," or another relative selection as stable unless it refers unambiguously to the immediately preceding numbered shortlist. Echo the resolved product, seller, variant, quantity, and item price before moving to checkout. Never substitute after selection without returning to the buyer.
 
@@ -71,7 +75,7 @@ Items from different sellers require separate carts, checkout totals, approvals,
 
 ## Hand off to bounded checkout
 
-Once the purchase boundary is exact, hand `visa-shopify-checkout` only the selected product and variant id, buyer-facing seller identity, unchanged `seller.domain` routing handle, quantity, ceiling and currency, destination constraints, and review-versus-submit scope. Do not forward the buyer's full prompt as a telemetry field. Stop after this handoff; the checkout skill owns every merchant-scoped cart, checkout, Visa review, credential, submission, and reconciliation action.
+Once the purchase boundary is exact, hand `visa-shopify-checkout` only the selected product and variant id, buyer-facing seller identity, unchanged `seller.domain` routing handle, quantity, ceiling and currency, destination constraints, and preparation scope. Do not forward the buyer's full prompt as a telemetry field. Stop after this handoff; the checkout skill owns merchant-scoped cart/checkout preparation and reconciliation. It cannot perform Visa card review, credential issuance or submission.
 
 Search success is not an order.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "5.0.0-rc.335",
+  "version": "5.0.0-rc.337",
   "description": "Visa CLI runtime for stable agent identity and separately authorized payment capabilities",
   "bin": {
     "visa-cli": "./bin/visa-cli.js",

package/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.visa-crypto-labs/visa-cli",
-  "version": "5.0.0-rc.335",
+  "version": "5.0.0-rc.337",
   "title": "Visa CLI",
   "description": "Pair a human-approved agent identity, configure payment capabilities separately, and discover and pay x402 services from your AI coding assistant.",
   "websiteUrl": "https://github.com/Visa-Crypto-Labs/Visa-mono/tree/main/packages/cli#readme",
@@ -9,7 +9,7 @@
     {
       "registryType": "npm",
       "identifier": "@visa/cli",
-      "version": "5.0.0-rc.335",
+      "version": "5.0.0-rc.337",
       "transport": {
         "type": "stdio"
       },