@visa/cli 5.0.0-rc.402 → 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.
 
@@ -211,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.
 
@@ -232,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.
 
@@ -342,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` |
@@ -525,6 +541,7 @@ 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 (`visa://receipt/{id}`) | `activity_entry_not_found` | `caller` |
 | A retired parameter was sent (`history` with `id` or `merchants`) | `invalid_argument` | `caller` |