@visa/cli 5.0.0-rc.401 → 5.0.0-rc.403

package/README.md

@@ -66,6 +66,11 @@ not shell source; execute it as argv without concatenating it into a command.
 Ordinary reads contain no card credential. **`--include card` / `include:"card"`
 explicitly returns issued purchase credentials to stdout or the MCP tool result,
 which may enter agent/chat history.** The owner must consent to that disclosure.
+Under that same `agent_history` consent, `purchase_create` itself returns
+`purchase.card` (network token, expiry and network cryptogram) when issuance
+completes within its wait. Treat either result as a secret for this one checkout:
+enter it once at the same merchant, and never log, store, echo or pass it to
+another tool, request or person.
 Original funding-card details and native signing keys are never returned. A
 cryptogram is not a generic CVC; the host must establish actual merchant support.
 
@@ -171,8 +176,7 @@ 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 retrieving, updating, and cancelling existing durable tasks. New `pay` calls use the same search, pricing, and wallet-payment routing regardless of Tasks support; they do not create card tasks.
-- Recovery of existing approval continuations through multi-round-trip `input_required` URL elicitation with HMAC-protected, client-bound request state. New wallet `pay` calls do not start card approval work.
+- No `io.modelcontextprotocol/tasks` extension: it only ever carried the retired card checkout, so `tasks/*` requests answer JSON-RPC `-32601` and a replayed `requestState` continuation answers `-32602`. A wallet `pay` that needs the owner's approval is resumed by calling `pay` again with the same `economicIntentId`.
 - 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`.
@@ -212,7 +216,14 @@ their Tempo wallet (it asks for USDC.e first if the wallet is empty, and keeps
 trying on its own while it is open). `visa connect` waits up to two minutes
 for it and says "Connected. Nothing is owed." only once the key is set up;
 until then the device line is pending with `wallet_key_setup_pending` and the
-next step. `get_status` reports the same in `walletKey.tempoKey`. Reopening
+next step. `get_status` reports the same in `walletKey.tempoKey`, and Visa's
+live verdict on the key in `walletKey.authority`: `live`; `expired` or
+`absent` (the owner renews the approval in the Console); `revoked` (the agent
+was revoked and cannot pay again; connect a new agent); `replaced` (another
+computer replaced this one's keys; connect this one as a new agent); `refused`
+(Visa answered with a refusal, so retrying will not help); or `unreachable`
+(Visa did not answer: offline, timed out or a server error, so nothing is
+known). A revoked agent is also `revoked` in `pairing.agents[].state`. Reopening
 the approval link, in the same tab or a new one, lands on the same approval;
 it never asks again for a code the terminal has already used.
 
@@ -233,7 +244,11 @@ machine's wallet key still needs the owner; an agent with no wallet renews it.
 `visa connect --restart` starts a fresh approval for this machine: choose
 **Replacing** on the approval page to give the same agent new keys (its budget
 and history stay; the old keys are retired and this machine's old local records
-are kept as `*.replaced-<time>` backups). `--restart` never touches the
+are kept as `*.replaced-<time>` backups). If that run stops before the owner
+approves, a plain `visa connect` (or `agent_enroll`) picks the same setup up,
+whether the owner chose a new agent or **Replacing**, and hands back its link
+while it is still waiting; once its keys are installed, or its window lapses,
+the held agent answers again. `--restart` never touches the
 installed `pair-visa-agent` skill; `--force-skill` replaces it, moving a locally
 edited copy to `.visa-cli-managed/backups/` first.
 
@@ -306,8 +321,7 @@ The rail comes from the target. You never name it:
 discover { "query": "current weather by city" }                  # nothing is spent
 pay      { "target": "<listing-id>", "max": "0.05", ... }        # probe, policy check, sign, settle
 pay      { "target": "https://provider.example/paid", "max": "0.05" }
-history  {}                                                       # this agent's payments
-history  { "id": "<activity-id>" }                                # one receipt, with its proof
+history  {}                                                       # this agent's payments, with their proof
 ```
 
 Owners read spend across every rail in the Console's Activity feed.
@@ -344,7 +358,7 @@ a name that was ever real has to stay readable here.
 | Tool | Description |
 |------|-------------|
 | `get_status` | Everything about this machine in one answer: the owner signed in, the agent this machine holds, its limits, its capabilities, and what is owed next. Its `tap` block reports this computer's TAP key (`key`) and the public directory listing (`directory`) separately |
-| `agent_enroll` | The one door. Idempotent, and runs whichever leg is owed: signs the owner in when the session lapsed, answers `already_connected` when this machine already holds a usable agent (so an agent that exists is never answered by minting a second one), and enrolls when none is held. One Approve certifies this machine's wallet, card and TAP keys. On a new computer, the owner can choose "replacing" on the approval page to move an existing agent there; the old computer's keys stop. Pass `restart: true` to force a fresh enrollment, or `setup: "<key>"` to pick up the agent the owner started on the Visa website (this is never answered `already_connected`, even when this machine holds another agent). Without `wait: true` it takes one step and says where the setup is: `awaiting_owner_device_approval` (the owner still has to approve; `browserUrl` is included), `finishing_device_setup` (the owner approved and their page is finishing; call again, nothing for the owner to do) or `connected`. It also returns `tapStatus: { key, directory }`, which is two separate facts: this computer's TAP key (`live`, `renew_due`, `expired`, `missing`) and the agent's public directory listing (`registered`, `pending`, `unavailable`, `unknown` and so on). An unreadable listing never changes `key`. For a machine that already holds its agent it returns `cardKey` (`live`, `renew_due`, `renewing`, `expired`, `none`) and renews a due card key through the same owner link a card purchase opens: `awaiting_owner_card_approval` with `browserUrl` and `requiresOwnerBrowserApproval: true` when the owner must approve, and `cardKeyError` when the renewal could not finish (call again) |
+| `agent_enroll` | The one door. Idempotent, and runs whichever leg is owed: signs the owner in when the session lapsed, answers `already_connected` when this machine already holds a usable agent (so an agent that exists is never answered by minting a second one), and enrolls when none is held. One Approve certifies this machine's wallet, card and TAP keys. On a new computer, the owner can choose "replacing" on the approval page to move an existing agent there; the old computer's keys stop. Pass `restart: true` to force a fresh enrollment (until it is installed or lapses, a later plain call picks that setup up instead of answering `already_connected`), or `setup: "<key>"` to pick up the agent the owner started on the Visa website (this is never answered `already_connected`, even when this machine holds another agent). Without `wait: true` it takes one step and says where the setup is: `awaiting_owner_device_approval` (the owner still has to approve; `browserUrl` is included), `finishing_device_setup` (the owner approved and their page is finishing; call again, nothing for the owner to do) or `connected`. It also returns `tapStatus: { key, directory }`, which is two separate facts: this computer's TAP key (`live`, `renew_due`, `expired`, `missing`) and the agent's public directory listing (`registered`, `pending`, `unavailable`, `unknown` and so on). An unreadable listing never changes `key`. For a machine that already holds its agent it returns `cardKey` (`live`, `renew_due`, `renewing`, `expired`, `none`) and renews a due card key through the same owner link a card purchase opens: `awaiting_owner_card_approval` with `browserUrl` and `requiresOwnerBrowserApproval: true` when the owner must approve, and `cardKeyError` when the renewal could not finish (call again) |
 | `discover` | Find something to pay for. Takes search text (by default it searches paid services the wallet pays on Tempo), or one URL to read its live charge without paying |
 | `pay` | Pay **from the agent wallet**: MPP on Tempo, in USDC.e. Search text searches; a URL whose 402 offers a Tempo charge pays (without `max` it returns the price and what the agent can spend now). A merchant with no Tempo charge, or a directory listing id, is refused with `merchant_not_supported`. A merchant checkout URL is refused by name — that is `purchase_create` |
 | `history` | Receipts, across every rail, with reconciliation when a payment's outcome is unresolved. Tempo payments are listed under `tempoPayments` |
@@ -369,7 +383,7 @@ a name that was ever real has to stay readable here.
 | `wallet_directory_pay` | **Removed.** Use `pay` |
 | `wallet_history` | **Removed.** Use `history` |
 | `wallet_fund` | **Removed.** The funding address is in `get_status` |
-| `checkout_merchants` | **Removed.** Use `history` with `merchants: true` |
+| `checkout_merchants` | **Removed.** Card purchases are read with `purchase_retrieve` |
 | `reset` | **Removed.** Use `visa disconnect --all` |
 
 Ground rules the tooling enforces — work with them, not around them:
@@ -527,8 +541,10 @@ Deterministic preconditions always resolve to a specific code:
 | Managed wallet limits are owner-set (`limits` with caps) | `managed_limits_owner_controlled` | `platform` |
 | The owner's spending approval for this agent has run out (`pay`, card purchases); nothing was charged, and the owner renews it at the `remedyUrl` limits page with the same limits | `grant_expired` | `platform` |
 | The owner pressed Decline on this exact "Ask me each time" payment (wallet or card); nothing was charged and it is never paid | `owner_declined` | `caller` |
+| The owner pressed Decline on this device setup's approval page (`visa connect`, `agent_enroll`); nothing was connected, and only a new setup (`--restart`) asks them again | `setup_declined` | `caller` |
 | Listing is not x402 (`pay`) | `invalid_argument` | `caller` |
-| Activity id not found or not attributable (`history {id}`) | `activity_entry_not_found` | `caller` |
+| Activity id not found or not attributable (`visa://receipt/{id}`) | `activity_entry_not_found` | `caller` |
+| A retired parameter was sent (`history` with `id` or `merchants`) | `invalid_argument` | `caller` |
 | The bundled signer is missing from this install (`agent_enroll`, `pay`) | `native_runtime_signer_not_installed` | `platform` |
 | The bundled signer is present but cannot be made executable | `native_runtime_signer_not_executable` | `platform` |
 | No signer is built for this OS/CPU | `native_runtime_platform_unsupported` | `platform` |