@visa/cli 4.1.0-rc.156 → 4.1.0-rc.158

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

@@ -1,12 +1,12 @@
 ---
 name: pair-visa-agent
-description: Pair a Visa CLI v4 agent identity to this runtime. Present one authorization link, the returned public confirmation code, and the full public request-key fingerprint to the human, then poll until the runtime's local Ed25519 identity is activated. Use when the user says "pair my agent", "enroll my Visa CLI", "connect my Visa agent", or "set up my agent identity".
+description: Pair a Visa CLI v4 agent identity to this runtime. Sign the owner in first (agent_login), then present one authorization link, the returned public confirmation code, and the full public request-key fingerprint to the human, then poll until the runtime's local Ed25519 identity is activated. Use when the user says "pair my agent", "enroll my Visa CLI", "connect my Visa agent", or "set up my agent identity".
 compatibility: Needs the `visa` CLI (`npm i -g @visa/cli@rc`) — run `node scripts/setup.mjs` to install it if missing — plus network access to the Visa authorization service. Works in OpenClaw, Hermes, or any Agent Skills runtime.
 allowed-tools: Bash(visa:*) Bash(visa-cli:*) Bash(node:*) Bash(npm:*) Bash(npx:*)
 metadata:
   author: visa
   homepage: https://visacli.sh/agents
-  version: '0.6.9'
+  version: '0.7.0'
   # 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
@@ -90,7 +90,9 @@ OpenClaw users also receive the skill with the `@visa/visa-cli-openclaw` plugin.
      `visa-cli connect <runtime>`. For Hermes, the entry is written under `mcp_servers`
      in `~/.hermes/config.yaml`.
    - **No MCP integration:** use the raw `visa agent …` commands.
-3. **Pair.** Follow the core flow below.
+3. **Sign the owner in.** Pairing starts are owner-bound — see "Sign in first" below. On a
+   fresh runtime this step is required before any pairing command will succeed.
+4. **Pair.** Follow the core flow below.
 
 ## MCP mounting examples
 
@@ -112,15 +114,30 @@ OpenClaw (`~/.openclaw/openclaw.json`):
 }
 ```
 
-Hermes (`~/.hermes/config.yaml`):
+Hermes (`~/.hermes/config.yaml`). **Hermes passes ONLY this `env:` map to the MCP
+subprocess — it does NOT inherit the gateway environment.** Omitting a required variable
+(an RC access code, the right `HOME`, `PATH`) makes the server exit on every start while
+`agent_capabilities` — which reads on-disk grant state, not live tool registration — can
+still report rails as available. Always set the map explicitly:
 
 ```yaml
 mcp_servers:
   visa-cli:
     command: node
     args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
+    # Hermes does NOT inherit the gateway env. This map is the entire
+    # subprocess environment; omit VISA_RC_CODE and the server exits on boot.
+    env:
+      HOME: /home/<user> # the home that holds this runtime's .visa-cli state
+      VISA_RC_CODE: <access code>
+      PATH: /usr/local/bin:/usr/bin:/bin
 ```
 
+Hermes also loads skills **per profile** from `~/.hermes/profiles/<profile>/skills/`, not
+from `~/.hermes/skills/` — on a multi-profile box, install with an explicit target:
+`visa agent skill --dir ~/.hermes/profiles/<profile>/skills`. A flat-dir install exits 0
+and is silently never loaded.
+
 In Hermes, `hermes claw migrate` can also import this skill and MCP configuration from an
 existing OpenClaw installation. See `RUNTIMES.md` for the complete runtime map.
 
@@ -140,15 +157,45 @@ Present it when the field is present and skip it when it is absent; an older ser
 simply omits it, which is not an error. The activation result includes protocol version
 `2`, `pairingId`, stable `agentId`, the display name, and `identityKeyJkt`.
 
+## Sign in first — pairing is owner-bound
+
+Pairing starts are authenticated as the owner: the service pins the owner account at
+initiation, and the browser review page rejects any other signed-in account
+(`owner_profile_mismatch`). So on a fresh runtime the ceremony has a mandatory first leg —
+establish the owner session **before** any pairing command:
+
+- [ ] Call `agent_login` (MCP, default action `"start"`) or run
+      `visa agent login --format json` (CLI). The result carries a sign-in `browserUrl`
+      and a short 6-character confirmation code.
+- [ ] Relay **both** to the human in your reply — the bare URL on its own line, and the
+      code. You are very often not in a terminal they can see; the chat message is the
+      only place these values reach them.
+- [ ] The human opens the link, signs in (Google or email), and **types the confirmation
+      code into the sign-in page** — into the browser, never back to you in chat.
+- [ ] Claim the session: `agent_login {"action":"claim"}` (the CLI command polls on its
+      own). Once claimed, the session token is stored locally and pairing can start.
+
+If a pairing command returns "An owner profile is required before pairing" or
+`{"code":"session_required"}`, that is this ordering rule — not a fault. Run `agent_login`,
+drive the sign-in above to a claimed session, then retry the same pairing command once.
+
+The account that signs in here is the owner the pairing binds to. The same person must
+approve the pairing link in the next step from that same signed-in browser session;
+a different account on the review page fails closed.
+
 ## Fastest path — one shot (`visa agent pair`)
 
-If the `visa` CLI is on PATH, prefer the one-shot command — it does the whole flow
-from a single call, so the user types nothing after their initial request:
+If the `visa` CLI is on PATH, prefer the one-shot command — after the owner session above
+exists, it does the whole flow from a single call, so the user types nothing after their
+initial request:
 
 ```
 visa agent pair --format json
 ```
 
+On a runtime with no owner session it fails with "An owner profile is required before
+pairing" — run the sign-in leg above first, then re-run it.
+
 It returns `browserUrl`, `pairingId`, stable `agentId`, the full public
 `requestKeyFingerprint`, and — on newer builds — `confirmationCode` **immediately**. It
 starts a detached activation process only after the pending identity and private key are
@@ -216,9 +263,11 @@ approve — you poll to completion yourself:
 - [ ] **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.
+      If you just paired, the session from the sign-in-first leg is usually still live —
+      no re-login needed. This is a short-lived session established once — **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
@@ -254,6 +303,14 @@ visa agent grant-card   <agentId> --ceiling <usd> --per-transaction <usd> --wait
 visa agent grant-wallet <agentId> --ceiling <usd> --per-transaction <usd> --wait
 ```
 
+Rail selection is the owner's call — wallet only, card only, or both. Newer builds also
+accept one compound command that runs the same ceremony per rail in sequence
+(`both` = card, then wallet, under the same caps — expect one extra approval trip):
+
+```
+visa agent connect --authority <card|wallet|both> --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.
@@ -267,6 +324,8 @@ dangerous). All spending is gated by the owner-approved local policy caps.
 
 ## Core flow
 
+- [ ] Establish the owner session ("Sign in first" above) if this runtime does not have
+      one yet.
 - [ ] Start the pairing with `pair_agent_start`, `enroll_agent` action `start`, or
       `visa agent enroll --format json`.
 - [ ] Present the authorization URL, stable agent ID, full public fingerprint, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "4.1.0-rc.156",
+  "version": "4.1.0-rc.158",
   "description": "Visa CLI runtime for stable agent identity and separately authorized payment capabilities",
   "bin": {
     "visa-cli": "./bin/visa-cli.js",
@@ -100,7 +100,6 @@
     "native/build-win.bat",
     "native/bin/win32-x64/visa-keychain-win.exe",
     "server.json",
-    "README.md",
-    "LICENSE"
+    "README.md"
   ]
 }

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.156",
+  "version": "4.1.0-rc.158",
   "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.156",
+      "version": "4.1.0-rc.158",
       "transport": {
         "type": "stdio"
       },