@visa/cli 4.1.0-rc.72 → 4.1.0-rc.74

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

@@ -6,7 +6,7 @@ allowed-tools: Bash(visa:*) Bash(visa-cli:*) Bash(node:*) Bash(npm:*) Bash(npx:*
 metadata:
   author: visa
   homepage: https://visacli.sh/agents
-  version: '0.6.7'
+  version: '0.6.8'
   # OpenClaw-namespaced extension (agentskills.io keeps `metadata` free-form, so
   # non-standard runtime config lives here — `user-invocable` is not a standard
   # top-level field). OpenClaw auto-installs `install[]` when `requires.bins` are
@@ -189,59 +189,76 @@ possible (re-pairing an existing identity silently dead-ends). Do this instead:
 Missing **spend** blocks _checkout mandates_, not a delegated x402 wallet — but that
 wallet must first be acquired by owner approval (below); it is never self-minted.
 
-## What you can do once paired — acquiring a wallet to spend
-
-Pairing binds **identity only**. To let this agent pay via the Turnkey x402
-(stablecoin) wallet, the wallet must be **delegated by the human owner** — the runtime
-never self-mints it. On mainnet (production) `wallet_init` throws
-`WalletCredentialRequiredError` until that delegation lands, so do NOT call it as a
-setup step. Follow this sequence:
-
-- [ ] **Pair** the identity (the flow above). Identity only — no wallet yet.
-- [ ] **Sign in the account session FIRST.** Wallet delegation is an account
-      operation, so this runtime needs a live owner session before `grant-wallet`:
-      `agent_login` (MCP) or `visa agent login` (CLI). Without a session the grant has
-      no account to delegate from.
-- [ ] **Initiate the wallet grant from MCP — no shelling.** Call `agent_connect`
-      (`{"rail":"wallet","ceiling":"<usd>","perTransaction":"<usd>"}`); omit `agentId`
-      to target the most recently paired agent. It creates the delegation request and
-      returns `{ url, code, attachId, willGrant, expiresAt }`. Present the bare `url`
-      and `code` to the human exactly as returned — the crypto approval happens in the
-      browser and **cannot** run inline in chat. Prefer this over the raw
-      `visa agent grant-wallet <agentId>` CLI ceremony; `setup_agent` (`{"rail":"wallet"}`)
-      still sequences identity → wallet → policy → ready if you need the next-step map.
-      If `agent_connect` returns `{"code":"session_required"}`, run `agent_login` first.
-- [ ] **Owner approves the wallet.** The human opens the `url` and confirms the wallet
-      grant on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`), approving with
-      their **sign-in session — no passkey** — and confirming the caps. You cannot approve
-      on their behalf.
-- [ ] **Finish from MCP with `agent_connect_poll`.** Call `agent_connect_poll`
-      (`{"attachId":"<from agent_connect>"}`; or resume by `agentId`) — each call runs one
-      bounded poll. It returns `{"ok":false,"state":"...","blockedByKind":"awaiting_human_approval"}`
-      while pending; call again until it returns `{"ok":true,"state":"grant_activated","fundAddress":...,"caps":...}`.
-      Activation registers the delegated Turnkey signer + caps and writes the delegated
-      Turnkey credential (`turnkey.json`) to this runtime. It never spends.
-- [ ] **Confirm the real wallet** with `wallet_status` (or `visa wallet show`). Only a
-      provisioned/delegated credential — not the served tool list — means the wallet is
-      usable; `agent_capabilities.wallet.available` reflects this.
-- [ ] **Set the spend policy** with `wallet_policy_set` — per-transaction / daily /
-      session USD caps (plus optional network and merchant allow/deny lists) that refuse
-      any x402 payment BEFORE it is signed. This is the `policy` step in the
-      `setup_agent` chain, between a delegated wallet and spending.
-- [ ] **Spend** with `wallet_pay` (x402), enforced by the owner-approved local policy
-      caps. Never raise a human-approved limit yourself.
-
-Once the wallet is delegated and a policy is set, these are the served wallet tools this
-agent can actually call: `wallet_discover` (search the public x402 Bazaar),
-`wallet_probe` (read a challenge without paying), `wallet_pay` / `wallet_directory_pay`
-(pay, policy-enforced), `wallet_history` / `wallet_reconcile` (local ledger + resolve
-`reconciling` holds), `wallet_fund` (funding address + faucet), and `wallet_export`
-(export key material — dangerous). All spending is gated by the owner-approved local
-policy caps.
-
-Card checkout is a separate upgrade on top of this Turnkey-only base — approve a card on
-the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`) with a **passkey**, then
-`start_card_mandate` / `pay_merchant` draw against it. Neither rail is enabled by pairing.
+## What you can do once paired — granting spend authority (card or wallet)
+
+Pairing binds **identity only**. To let this agent pay, the human owner must **delegate**
+a spend rail — the runtime never self-mints one. There are two rails, and **one** ceremony
+drives both:
+
+- **`wallet:x402`** (Turnkey stablecoin) — owner approves with their **sign-in session, no
+  passkey**. On mainnet `wallet_init` throws `WalletCredentialRequiredError` until this
+  delegation lands, so never call it as a setup step.
+- **`card:vic`** (Visa card checkout) — owner approves with a **passkey**.
+
+The contract is identical for both rails, and it is **one command from you, one approval
+from the owner**. You never hand a command, code, or URL back to the human after they
+approve — you poll to completion yourself:
+
+1. **You run one command** naming the rail and caps.
+2. **The owner opens the returned link and approves once** (they may adjust the amount).
+3. **You poll to activation** — the owner does nothing further.
+
+- [ ] **Pair** the identity (the flow above). Identity only — no rail yet.
+- [ ] **Establish the owner session once.** Grant creation is an account operation, so this
+      runtime needs a live owner session: `agent_login` (MCP) or `visa agent login` (CLI).
+      This is a short-lived session established once for the grant — **not** a re-pair, and
+      **not** something the owner repeats per payment. If `agent_connect` later returns
+      `{"code":"session_required"}`, the session lapsed — run `agent_login` again.
+- [ ] **Initiate the grant from MCP — no shelling, no invented URLs.** Call `agent_connect`
+      with the rail and caps: `{"rail":"card","ceiling":"<usd>","perTransaction":"<usd>"}`
+      (or `"rail":"wallet"`); omit `agentId` to target the most recently paired agent. It
+      returns `{ url, code, attachId, willGrant, expiresAt }`. Present the **bare `url` and
+      `code` exactly as returned** — never construct, shorten, or guess a Visa URL, and never
+      open it yourself. The crypto approval happens in the owner's browser and cannot run
+      inline in chat. (`setup_agent {"rail":"card"|"wallet"}` returns the same next-step map
+      if you need it.)
+- [ ] **Owner approves once** on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`),
+      confirming the caps — **card with a passkey, wallet with their sign-in session**. You
+      cannot approve on their behalf.
+- [ ] **Poll to activation from MCP.** Call `agent_connect_poll` (`{"attachId":"<from
+      agent_connect>"}`; or resume by `agentId`) — one bounded poll per call. It returns
+      `{"ok":false,"state":"...","blockedByKind":"awaiting_human_approval"}` while pending;
+      call again until `{"ok":true,"state":"grant_activated","caps":...}` (wallet also
+      returns `fundAddress`). Activation registers the delegated signer + caps: wallet writes
+      the Turnkey credential (`turnkey.json`); card writes the card pointer. It never spends.
+- [ ] **Confirm the rail is live.** Wallet: `wallet_status` / `visa wallet show`
+      (`agent_capabilities.wallet.available`). Card: `agent_capabilities.card.available`.
+      Only a delegated credential — not the served tool list — means the rail is usable.
+- [ ] **Then spend against the owner-approved caps.** Wallet: set the policy with
+      `wallet_policy_set` (per-transaction / daily / session USD caps + optional network and
+      merchant allow/deny lists that refuse an x402 payment BEFORE it is signed), then
+      `wallet_pay`. Card: `start_card_mandate` then `pay_merchant`. Never raise a
+      human-approved limit yourself.
+
+**Raw CLI equivalent (one shot).** If you cannot drive MCP, the same ceremony runs from the
+CLI and `--wait` polls to activation in a single call. Present the URL it prints — don't
+invent one:
+
+```
+visa agent grant-card   <agentId> --ceiling <usd> --per-transaction <usd> --wait
+visa agent grant-wallet <agentId> --ceiling <usd> --per-transaction <usd> --wait
+```
+
+Use the stable `agentId` from pairing or `visa agent list` — never invent or alter the id.
+A policy refusal or timeout means **nothing was signed**: report it and stop; do not retry
+with a different command or a reconstructed URL.
+
+Once a wallet is delegated and a policy is set, these are the served wallet tools this agent
+can actually call: `wallet_discover` (search the public x402 Bazaar), `wallet_probe` (read a
+challenge without paying), `wallet_pay` / `wallet_directory_pay` (pay, policy-enforced),
+`wallet_history` / `wallet_reconcile` (local ledger + resolve `reconciling` holds),
+`wallet_fund` (funding address + faucet), and `wallet_export` (export key material —
+dangerous). All spending is gated by the owner-approved local policy caps.
 
 ## Core flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "4.1.0-rc.72",
+  "version": "4.1.0-rc.74",
   "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-10-17/server.schema.json",
   "name": "io.github.visa-crypto-labs/visa-cli",
-  "version": "4.1.0-rc.72",
+  "version": "4.1.0-rc.74",
   "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": "4.1.0-rc.72",
+      "version": "4.1.0-rc.74",
       "transport": {
         "type": "stdio"
       },