@visa/cli 5.0.0-rc.408 → 5.0.0-rc.409

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

@@ -24,8 +24,9 @@ Markdown skill, CLI, and MCP protocol instead.
 Both supported surfaces run the same protected enrollment and share the same local
 pending record:
 
-1. Visa MCP server: `agent_enroll`, then `agent_enroll` with `wait: true` once the
-   owner has the page open.
+1. Visa MCP server: `agent_enroll` once; after the owner approves, this computer
+   finishes in the background (`get_status` shows `pairing.setup.state` go
+   `finishing` → `connected`; do not call `agent_enroll` while it is `finishing`).
 2. Terminal: `visa connect` (add `--format json` for machine output).
 
 Each returns one link and a short code for the human. The browser receives only that

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

@@ -37,9 +37,11 @@ It has two entrances to the exact same protected enrollment implementation: the
 native signer, Authority routes, owner browser approval, and limits. Never invent or mix
 in a second ceremony.
 
-- **You have the Visa MCP server mounted:** call `agent_enroll` and hand the owner the one
-  link and short code it returns. Call it again with `wait: true` once they have the page
-  open; it finishes activation only after they approve.
+- **You have the Visa MCP server mounted:** call `agent_enroll` once and give the owner
+  `browserUrl` and `confirmCode` exactly as returned. After their one approval this computer
+  finishes in the background. Poll `get_status`: `pairing.setup.state` goes `finishing` →
+  `connected`, and `pairing.setup.owed` names any owner step still left (call `agent_enroll`
+  once to hand it over). Do not call `agent_enroll` while it is `finishing`.
 - **The owner is at a terminal:** they run the command below.
 
 ```
@@ -56,7 +58,10 @@ The installed CLI selects its own service origins from its release channel. Neve
 for, guess, or construct a Visa URL.
 
 Running the same command again resumes an interrupted enrolment; `--restart` replaces an
-unclaimed request with a fresh code. `--ceiling <usd>` and `--per-transaction <usd>`
+unclaimed request with a fresh code. The local finisher can time out after about 15 minutes; this does not prove server expiry: when `pairing.setup.state` reads `expired`, call `agent_enroll` once without
+`restart` (terminal: `visa connect`): it resumes the original request if the server still
+accepts it, or answers `enrollment_expired` for an already-bound request the server no longer accepts. Only then call it with `restart: true` (terminal:
+`visa connect --restart`) and relay the new link and code. `--ceiling <usd>` and `--per-transaction <usd>`
 propose limits the owner confirms on the approval page.
 
 ## The tools the Visa MCP server serves
@@ -226,6 +231,9 @@ starts the enrolment.
       code into the sign-in page** — into the browser, never back to you in chat.
 - [ ] Call `agent_enroll` again once they have (the CLI command polls on its own). It
       picks up the approved sign-in on this device and moves on to the enrolment link.
+      This second call belongs to the sign-in leg only: nothing in the background picks
+      up a sign-in. The background finish starts after the enrolment link, so once the
+      owner approves that, do not call while `pairing.setup.state` is `finishing`.
 
 Signing in establishes the OWNER's session on this device. It creates no agent and grants
 no spending authority — those come from the enrolment and the approval the owner gives in
@@ -358,38 +366,79 @@ What to do instead:
       without minting a new agent — it renews the device lease and skips every step that
       is already done.
 - [ ] **If the OWNER never approved that authority**, only they can add it. Say so, name
-      what is missing, and stop. Enrolling again mints a NEW agent — it does not upgrade
-      this one, and doing it silently leaves the owner with two agents and one funded
-      wallet.
+      what is missing, and stop. Follow the returned Payments or limits action for this agent. Do not use
+      enrollment or restart to work around a payment refusal.
 
-A policy refusal or timeout means **nothing was signed**: report it and stop; do not retry
-with a different command or a reconstructed URL. Never raise a human-approved limit
-yourself.
+A policy refusal is a stop: follow its returned remedy. Never raise a human-approved limit yourself. A timeout leaves the payment outcome unknown; use the recovery table below.
+
+## Talking to the owner
+
+<!-- recovery-guidance: replyStyle -->
+
+Keep each owner message to a line or two, result first. Amounts in dollars; for an approval, the price and the link. Skip preamble, announcing next steps, recaps, how Visa works and waiting. No ids or hashes unless something failed; then one id. End with the result and one total, no per-call costs.
+<!-- /recovery-guidance -->
 
 ## Spending, once a rail is live
 
-Wallet: `discover` finds what to buy (a query, or a listing id to read one without
-paying), `pay` pays it with a mandatory `max` ceiling, and `history` reads this agent's
+Wallet: `discover` searches with `query`, or probes a URL/listing id with `target`
+without paying (target probes require wallet setup), `pay` pays it with a mandatory `max` ceiling, and `history` reads this agent's
 payments. The limits are the ones the owner approved; the owner changes them in the Visa
 Console, never you. Funding is the owner's, in the Console.
 
 Card: Visa-operated browser checkout is retired; another enrollment will not repair it.
-The retired browser-checkout tools refuse with `card_browser_checkout_removed`.
+`pay` is the wallet door: it refuses a merchant checkout URL with `card_checkout_not_on_pay`.
 On local builds that list `purchase_create`,
 `purchase_retrieve` and `purchase_cancel`, the protected card preview uses the
 host's checkout tools and the existing eligible card and agent identity. Follow
 `next`: relay the single owner setup or limits URL, let the owner act, then repeat
-the same purchase call. Never ask for funding-card secrets in chat. Explicit
+the same purchase call. Never ask for funding-card secrets in chat. Use an already returned `purchase.card` under the owner’s disclosure consent; otherwise follow the explicit retrieval action. Explicit
 `include:"card"` may put the issued purchase credential in model/chat history,
 under the owner's disclosure consent. A saved card or tester flag alone does
 not establish eligibility or merchant credential compatibility. UCP discovery
 and preparation remain separate from payment execution; a `not_ready` handoff
 is not permission to pay or to revive the retired browser flow.
 
-On a hosted runtime, **every payment requires the owner's browser
-approval** until the protected no-tap executor lands. Enrollment, a session, or a spending
-grant does not approve a later hosted payment. Relay the hosted approval URL and wait for
-the owner's decision before reporting success or retrying.
+## Payment outcomes and recovery
+
+<!-- recovery-guidance: ownerAction, timeout, identity -->
+
+Follow the returned code, stage, remedy and owner action. The specific nextAction takes precedence over kind. Platform needs human action or diagnosis. Show the exact approval link once; continue the same payment only when nextAction says so. On denial or expiry, follow its stop or recovery action. Escalate unclassified errors. A timeout does not prove nothing was signed or paid. Keep the same agent and purchase identity: wallet `economicIntentId` and exact arguments, card `resumeId`/`purchaseId`, or an app’s `idempotencyKey`/`draftId`. Never retry uncertainty under a new identity.
+<!-- /recovery-guidance -->
+
+<!-- recovery-guidance: localOutcomes -->
+
+| Returned code or outcome                                                              | Action                                                                                                                        |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `pending_activation`                                                                  | Owner finishes the existing connection in the Console.                                                                        |
+| `spending_limit_required`, `grant_expired`                                            | Owner sets or renews this agent’s limits; no re-pair.                                                                         |
+| `agent_paused`, `agent_revoked`                                                       | Owner resumes the paused agent; a revoked agent cannot pay again. Do not bypass the refusal; reconnecting does not bypass it. |
+| `device_key_replaced`                                                                 | Follow the returned connection action for this computer.                                                                      |
+| `owner_approval_required`, `wallet_owner_approval_required`                           | Show the exact returned approval link, then continue the same purchase after approval.                                        |
+| `owner_declined`                                                                      | Stop; never retry automatically.                                                                                              |
+| `owner_signature_unconfirmed`, `outcome_unknown`, `unreachable`, `malformed_response` | Read/reconcile the original request. Preserve its identity and token; do not create a replacement.                            |
+| `cancellation_pending`                                                                | Retrieve the same purchase; liability is unresolved, not released.                                                            |
+| `delivered` or `reconciling`                                                          | Check the recorded financial outcome; delivery is not settlement proof. Never pay the item again.                             |
+
+<!-- /recovery-guidance -->
+
+<!-- recovery-guidance: approval -->
+
+Read the actual approval mode. In an app, `authority: owner_autonomy` can pay within the owner’s limits. `owner_approval_required` needs the returned owner link. A connected app does not need local `agent_enroll` or `visa connect`.
+<!-- /recovery-guidance -->
+
+For agents on the owner’s computer:
+
+<!-- recovery-guidance: localOutput -->
+
+Save output in an owner-controlled local file; re-read the local saved result.
+<!-- /recovery-guidance -->
+
+For apps:
+
+<!-- recovery-guidance: missingOutput, noRefetch -->
+
+If payment is confirmed but the result is missing (“Paid; result not received. Do not pay again”), tell the owner in one line that it was paid and nothing came back, with the original purchase id. Never ask the merchant again for a purchased result, even for GET requests.
+<!-- /recovery-guidance -->
 
 ## Retired mesh integration
 
@@ -462,3 +511,7 @@ mailbox, key proof, recovery factor, or permission to spend.
 - `RUNTIMES.md` — OpenClaw, Hermes, and raw CLI setup.
 - `docs/agents/ARCHITECTURE.md` — where enrolment sits in the v4 request paths.
 - `visacli.sh/agents` — product-facing agent documentation.
+
+### Resuming after a local setup timeout
+
+A local timeout is not proof of server expiry. After a plain resume, relay any new `browserUrl` and `confirmCode` returned: an unbound request the server has definitively refused can be replaced automatically. `enrollment_expired` means an already-bound request needs an explicit restart. A transient or ambiguous failure preserves the same request; do not use `restart: true` merely because a request timed out.

package/dist/skills/pair-visa-agent/scripts/__tests__/setup.test.mjs

@@ -1,9 +1,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { tmpdir } from 'node:os'
-import { randomUUID } from 'node:crypto'
 
 import {
   parseSemver,
@@ -20,8 +19,7 @@ describe('setup.mjs portable provisioner', () => {
   let tempDir
 
   beforeEach(() => {
-    tempDir = join(tmpdir(), `setup-test-${randomUUID()}`)
-    mkdirSync(tempDir, { recursive: true })
+    tempDir = mkdtempSync(join(tmpdir(), 'setup-test-'))
   })
 
   afterEach(() => {
@@ -129,7 +127,7 @@ describe('setup.mjs portable provisioner', () => {
       writeFileSync(
         bundlePath,
         `
-        const tools = ['get_status', 'agent_enroll', 'discover', 'pay', 'history', 'feedback'];
+        const tools = ['get_status', 'agent_enroll'];
         `
       )
       const probe = probeMcpTools(bundlePath, REQUIRED_MCP_TOOLS)
@@ -165,6 +163,7 @@ describe('setup.mjs portable provisioner', () => {
     })
 
     it('requires only served tools: every required tool is a served general tool', () => {
+      expect(Object.isFrozen(REQUIRED_MCP_TOOLS)).toBe(true)
       const served = readFileSync(
         join(
           dirname(fileURLToPath(import.meta.url)),
@@ -276,10 +275,7 @@ describe('setup.mjs portable provisioner', () => {
       const mockNpmRoot = vi.fn(() => tempDir)
 
       const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
-      const result = await runSetup(
-        { VISA_RELEASE_CHANNEL: 'rc' },
-        { execFileSync: mockExec, npmRootFn: mockNpmRoot }
-      )
+      const result = await runSetup({}, { execFileSync: mockExec, npmRootFn: mockNpmRoot })
       logSpy.mockRestore()
 
       expect(mockExec).toHaveBeenCalledWith(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "5.0.0-rc.408",
+  "version": "5.0.0-rc.409",
   "description": "Visa CLI runtime for stable agent identity and separately authorized payment capabilities",
   "bin": {
     "visa-cli": "./bin/visa-cli.js",
@@ -11,21 +11,24 @@
     "sync:server-json": "node scripts/sync-server-json.mjs",
     "check:server-json": "node scripts/sync-server-json.mjs --check",
     "prebuild": "node scripts/sync-server-json.mjs",
-    "build": "tsc --noEmit && node esbuild.config.js",
+    "build": "pnpm test:types && node esbuild.config.js",
     "prepack": "node scripts/sync-server-json.mjs --check",
     "dev": "tsc --watch",
     "pretest": "pnpm build",
     "start": "node dist/mcp-server/index.js",
     "test": "jest --config jest.config.js",
+    "test:types": "tsc -p tsconfig.test.json",
+    "pretest:unit": "pnpm test:types",
     "test:unit": "jest --config jest.config.js",
+    "pretest:unit:watch": "pnpm test:types",
     "test:unit:watch": "jest --config jest.config.js --watch",
+    "pretest:unit:coverage": "pnpm test:types",
     "test:unit:coverage": "jest --config jest.config.js --coverage",
     "test:smoke": "VISA_AUTH_URL=https://auth.visacli.sh jest --config jest.smoke.config.js",
     "test:packed": "node scripts/packed-cli-smoke.mjs",
-    "test:integration": "jest --config jest.integration.config.js",
     "test:e2e": "jest --config jest.e2e.config.js",
     "coinbase:onramp": "pnpm exec tsx tests/e2e/coinbase-onramp-harness/run.ts",
-    "test:all": "npm run test:unit && npm run test:integration && npm run test:e2e",
+    "test:all": "npm run test:unit && npm run test:e2e",
     "prepublishOnly": "npm run build && npm test",
     "lint": "eslint src/**/*.ts",
     "format": "prettier --write \"src/**/*.ts\"",
@@ -44,9 +47,7 @@
   "author": "Visa Crypto Labs",
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@modelcontextprotocol/ext-apps": "1.7.5",
     "@modelcontextprotocol/server": "2.0.0",
-    "@ucp-js/sdk": "0.4.4",
     "commander": "^12.1.0",
     "punycode": "^2.3.1",
     "zod": "^3.25.76"
@@ -54,14 +55,13 @@
   "devDependencies": {
     "@types/express": "^5.0.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.1.0",
+    "@types/node": "^22.20.5",
     "@typescript-eslint/eslint-plugin": "^8.68.0",
     "@typescript-eslint/parser": "^8.68.0",
-    "@visa-cli/tools": "workspace:*",
     "@visa/crypto": "workspace:*",
     "@visa/financial-core": "workspace:*",
     "@visa/identity": "workspace:*",
-    "@visa/money": "workspace:*",
+    "@visa/contracts": "workspace:*",
     "@visa/observability": "workspace:*",
     "@visa/shared": "workspace:*",
     "@visa/wallet": "workspace:*",

package/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.visa-crypto-labs/visa-cli",
-  "version": "5.0.0-rc.408",
+  "version": "5.0.0-rc.409",
   "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": "5.0.0-rc.408",
+      "version": "5.0.0-rc.409",
       "transport": {
         "type": "stdio"
       },