@visa/cli 4.1.0-rc.65 → 4.1.0-rc.67

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.6'
+  version: '0.6.7'
   # 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
@@ -165,15 +165,20 @@ possible (re-pairing an existing identity silently dead-ends). Do this instead:
    Read the name from the response. Do **not** start another hand-off. `--new` /
    `force:true` exists only if they explicitly want a _second, separate_ agent.
 2. **Report status honestly — "connected" is five separate things**, not one. Never
-   imply the agent can spend just because it's connected:
+   imply the agent can spend just because it's connected. Don't guess from prose —
+   read it live from tools: `agent_capabilities` returns the DERIVED capability map
+   (the identity + wallet + mail base plus card/tap/subway availability),
+   `get_status` reports enrollment / account / version, and `agent_login` establishes
+   or confirms the account session that spending grants require.
    - **Identity** — connected (`.visa` name bound to _this user's_ account). ✓ once `already_connected`.
-   - **Spending** — a _separate human approval_, and there are two rails. For the
-     Turnkey **wallet** (x402 stablecoin), the owner approves a wallet grant in
-     **account settings → agent wallet → Spend** (see "What you can do once paired"
-     below). For **card** checkout, the owner approves in **account settings → agent
-     card → Spend**. You **cannot** self-grant either; never tell the user to run
-     `visa agent add-rail` (it refuses identity-only agents), and never self-mint a
-     wallet with `wallet_init` on mainnet — it throws until the owner's delegation lands.
+   - **Spending** — a _separate human approval_, and there are two rails, each
+     approved on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`) — not any
+     account-settings page (that legacy surface is retired). The Turnkey
+     **wallet:x402** rail (stablecoin) is approved with the owner's **sign-in session**
+     (the Google/email auth-proxy) — **no passkey**. The **card:vic** rail is approved
+     with a **passkey**. You **cannot** self-grant either; there is no
+     `visa agent add-rail` command, and never self-mint a wallet with `wallet_init` on
+     mainnet — it throws until the owner's delegation lands.
    - **Mesh (`.visa` messaging)** — with `SUBWAY_MESH=visa`, a returning device now
      registers on `pair`; if `meshRegistered` is false, `visa register <name>` joins it.
    - **Trusted (TAP)** — follows spend/provisioning; don't promise it before then.
@@ -193,24 +198,40 @@ never self-mints it. On mainnet (production) `wallet_init` throws
 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.
 - [ ] **Resolve the next step** with `setup_agent` (`{"rail":"wallet"}`), or drive the
-      raw `visa agent grant-wallet <agentId>` ceremony. `setup_agent` reports
-      `needs_wallet` and points at the owner-approval grant — it does not tell you to
-      self-mint.
-- [ ] **Owner approves the wallet.** The human runs / confirms the wallet grant and
-      approves it in the account UI (**account settings → agent wallet → Spend**),
-      confirming caps and passkey. That approval registers the delegated signer + caps
-      and writes the delegated Turnkey credential (`turnkey.json`) to this runtime.
-      You cannot approve on their behalf.
+      raw `visa agent grant-wallet <agentId>` ceremony. `setup_agent` sequences
+      identity → wallet → policy → ready and points at the owner-approval grant — it
+      does not tell you to self-mint.
+- [ ] **Owner approves the wallet.** The human 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. That approval registers the
+      delegated Turnkey signer + caps and writes the delegated Turnkey credential
+      (`turnkey.json`) to this runtime. You cannot approve on their behalf.
 - [ ] **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.
 
-Card checkout is a separate upgrade on top of this Turnkey-only base — approve a card
-in **account settings → agent card → Spend**, then `start_card_mandate` / `pay_merchant`
-draw against it. Neither rail is enabled by pairing.
+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.
 
 ## Core flow
 
@@ -300,6 +321,31 @@ a reachable `SUBWAY_RELAY_MULTIADDR`. If those tools or the relay are unavailabl
 that clearly and stop. Do not imply that identity pairing alone granted directory or
 messaging authority, and do not improvise another transport.
 
+## Optional agent mailbox (separate from pairing)
+
+Pairing does not provision an email address or inbox. If the agent needs a
+mailbox — e.g. to receive a merchant's account-signup or one-time-code email —
+connect one explicitly, from the paired runtime, with the raw CLI:
+
+```
+visa agent mail-connect <agentId>
+```
+
+This is CLI-only; no pairing step or MCP tool connects a mailbox. It requires an
+already-paired stable-agent identity on this runtime — it reads the local agent
+record and proves the Ed25519 identity to the service. It issues the stable
+agent mailbox if one does not exist, then stores an inbox-scoped credential in an
+owner-only `0600` runtime file so this runtime can read that one inbox.
+
+Be honest about scope. A mailbox grants an email address and the ability to read
+that inbox — nothing more. It is **not** identity, a wallet, spend authority, a
+card, or a `.visa` name, and it never authorizes a payment. Do not claim pairing
+set up mail. Once connected, the MCP `wallet_mail_status`, `wallet_mail_read`,
+and `wallet_mail_await_otp` tools read the inbox (e.g. to await a sender-checked
+one-time code); without the scoped credential those reads fail closed. Keep the
+org-wide AgentMail key off the runtime — provisioning happens only through
+`mail-connect` under operator control.
+
 ## Optional checkout profile (separate from pairing)
 
 Pairing does not enable card checkout. If the operator has separately provisioned card

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "4.1.0-rc.65",
+  "version": "4.1.0-rc.67",
   "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.65",
+  "version": "4.1.0-rc.67",
   "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.65",
+      "version": "4.1.0-rc.67",
       "transport": {
         "type": "stdio"
       },