@visa/cli 4.1.0-rc.37 → 4.1.0-rc.38

package/README.md

@@ -1,21 +1,19 @@
 # @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 silently create a wallet,
+card credential, budget, mailbox, `.visa` name, or TAP listing.
+
+The product flow has three explicit parts:
+
+1. **Identity** — `enroll_agent` (or `visa agent enroll`) opens one browser
+   review for the exact runtime and public-key fingerprint. The private key
+   stays on the runtime device.
+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
 
@@ -65,27 +63,59 @@ 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
+## Pair an agent identity
+
+From MCP, call **`enroll_agent`** with `{"action":"start"}`. It creates the
+runtime's Ed25519 key locally, verifies the terminal/browser channel, and opens
+the identity-only review. After the human approves, call `enroll_agent` with
+`{"action":"claim"}` to activate and durably store the identity.
+
+```bash
+visa agent enroll          # opens the one human review page
+visa agent enroll-claim    # resumes delivery/activation after approval
+visa agent list
+visa agent show <agent-id>
+```
 
-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.
+The advanced `create` → `claim` → `verify` → `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.
 
-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.
+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.
+
+## Existing wallet capability: caps, then funding
 
-## Caps, then funding — strict order
+These commands apply only to a pre-cutover/test runtime that already has a
+valid, separately provisioned wallet credential. Pairing again cannot create or
+repair that payment capability.
 
 ```bash
 visa wallet limits --per-transaction 0.25 --daily 2.00   # BEFORE any funds arrive
@@ -120,8 +150,8 @@ command.
 
 | 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 |
+| `enroll_agent` | Two-step identity-only pairing: start opens the exact runtime/key review; `{"action":"claim"}` activates and stores the agent identity |
+| `wallet_status` | Separately provisioned 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 |
@@ -163,7 +193,15 @@ visa pay <listing-id> --max <usd>
 visa activity
 visa receipt <receipt-id>
 
-# Human-approved agent runtime pairing
+# Primary same-machine v2 identity pairing
+visa agent enroll
+visa agent enroll-claim
+
+# Existing-account session recovery (separate from identity pairing)
+visa agent login
+visa agent login-claim
+
+# Advanced split-device form of the same v2 ceremony
 visa agent create
 visa agent claim <pairing-id> --runtime <name> --context "<purpose>"
 visa agent verify <pairing-id> <code>
@@ -200,14 +238,18 @@ 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-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-mcp/agent-credential.json` | Legacy checkout-credential compatibility record (mode 0600) |
 | `~/.visa-v4/policy.json` | Wallet spend policy — never edit by hand; use `visa wallet limits` |
 
 ## 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.
@@ -216,7 +258,8 @@ A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet
 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.
+The ceremony timed out — restart with `visa agent enroll`, then run
+`visa agent enroll-claim` after approving the new browser review.
 
 **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.