@visa/cli 4.1.0-rc.19 → 4.1.0-rc.2

package/dist/checkout-engine/vgs-live-instrument.js

@@ -1,252 +0,0 @@
-/**
- * Our fail-closed freshness bound, matching the runner's 15-minute checkout
- * review window — NOT a claim about VGS's actual assurance TTL (unpublished).
- * The only proven-working configuration mints the intent right after the
- * ceremony; anything older is refused before an intent is created.
- */
-export const PURCHASE_ASSURANCE_MAX_AGE_MS = 15 * 60 * 1000;
-/** Tolerated forward clock skew on `mintedAt` before it is treated as invalid. */
-const PURCHASE_ASSURANCE_MAX_SKEW_MS = 2 * 60 * 1000;
-export function decimalToMinor(value) {
-    // JSON files routinely carry a number where the contract says decimal string
-    // ("transactionAmount": 5): refuse non-strings HERE so every caller surfaces
-    // its scoped invalid/mismatch remedy instead of a raw TypeError crash.
-    if (typeof value !== 'string')
-        return null;
-    if (!/^\d+(\.\d{1,2})?$/.test(value))
-        return null;
-    const [whole, fraction = ''] = value.split('.');
-    const minor = Number(whole) * 100 + Number(fraction.padEnd(2, '0'));
-    return Number.isSafeInteger(minor) ? minor : null;
-}
-function validateTarget(reference, ctx) {
-    if (typeof reference.merchantName !== 'string' ||
-        typeof reference.merchantCountryCode !== 'string' ||
-        !reference.merchantName.trim() ||
-        !/^[A-Z]{2}$/.test(reference.merchantCountryCode)) {
-        throw new Error('VGS checkout reference merchant name/country is invalid');
-    }
-    let referenceHost;
-    try {
-        referenceHost = new URL(reference.merchantUrl).hostname;
-    }
-    catch {
-        throw new Error('VGS checkout reference merchant URL is invalid');
-    }
-    if (referenceHost !== ctx.merchantHost) {
-        throw new Error(`VGS credential merchant mismatch: ${referenceHost} vs ${ctx.merchantHost}`);
-    }
-    const amountMinor = decimalToMinor(reference.transactionAmount);
-    if (amountMinor === null)
-        throw new Error('VGS checkout reference amount is invalid');
-    if (amountMinor !== ctx.amountMinor) {
-        throw new Error(`VGS credential amount mismatch: ${amountMinor} vs ${ctx.amountMinor} minor units`);
-    }
-    // String() so a JSON-number currency (840) mismatches with a readable
-    // message instead of crashing on .toUpperCase().
-    const currency = String(reference.transactionCurrencyCode).toUpperCase();
-    if (currency !== ctx.currency) {
-        throw new Error(`VGS credential currency mismatch: ${currency} vs ${ctx.currency}`);
-    }
-}
-function validateCliCredential(value) {
-    if (typeof value.tokenId !== 'string' || !value.tokenId.trim()) {
-        throw new Error('CLI agent credential requires tokenId');
-    }
-    // Deliberately no assuranceData requirement: the artifact's enrollment-time
-    // assurance is identity/enrollment material and is never read here (#5709).
-}
-/**
- * Refuse to mint an intent unless the assurance is fresh and its declared
- * scope matches the checkout target exactly. `now` is injectable so the
- * freshness rules are testable with a pinned clock (same pattern as
- * validateCredential).
- */
-export function validatePurchaseAssurance(value, target, now = new Date()) {
-    const remedy = 'run a fresh device-binding ceremony scoped to this exact merchant, amount, and ' +
-        'currency, and pass its output via --purchase-assurance-file (#5709)';
-    if (value == null || typeof value !== 'object') {
-        throw new Error(`purchase assurance is missing — ${remedy}`);
-    }
-    if (value.assuranceData == null) {
-        throw new Error(`purchase assurance requires assuranceData — ${remedy}`);
-    }
-    const mintedAtMs = typeof value.mintedAt === 'string' ? Date.parse(value.mintedAt) : NaN;
-    if (!Number.isFinite(mintedAtMs)) {
-        throw new Error(`purchase assurance requires an ISO 8601 mintedAt — ${remedy}`);
-    }
-    const age = now.getTime() - mintedAtMs;
-    if (age < -PURCHASE_ASSURANCE_MAX_SKEW_MS) {
-        throw new Error(`purchase assurance mintedAt is in the future — ${remedy}`);
-    }
-    if (age > PURCHASE_ASSURANCE_MAX_AGE_MS) {
-        throw new Error(`purchase assurance is stale (minted ${value.mintedAt}, limit ` +
-            `${PURCHASE_ASSURANCE_MAX_AGE_MS / 60000} minutes) — ${remedy}`);
-    }
-    let targetHost;
-    try {
-        targetHost = new URL(target.merchantUrl).hostname;
-    }
-    catch {
-        throw new Error('VGS checkout reference merchant URL is invalid');
-    }
-    if (value.merchantHost !== targetHost) {
-        throw new Error(`purchase assurance merchant mismatch: ${value.merchantHost} vs ${targetHost} — ${remedy}`);
-    }
-    const assuranceMinor = decimalToMinor(value.transactionAmount);
-    const targetMinor = decimalToMinor(target.transactionAmount);
-    if (assuranceMinor === null || assuranceMinor !== targetMinor) {
-        throw new Error(`purchase assurance amount mismatch: ${value.transactionAmount} vs ` +
-            `${target.transactionAmount} — ${remedy}`);
-    }
-    if (typeof value.transactionCurrencyCode !== 'string' ||
-        value.transactionCurrencyCode.toUpperCase() !==
-            String(target.transactionCurrencyCode).toUpperCase()) {
-        throw new Error(`purchase assurance currency mismatch: ${value.transactionCurrencyCode} vs ` +
-            `${target.transactionCurrencyCode} — ${remedy}`);
-    }
-}
-// `now` is injectable so expiry rules are testable with a pinned clock.
-export function validateCredential(value, now = new Date()) {
-    if (!/^\d{12,19}$/.test(value.networkToken)) {
-        throw new Error('VGS credential network token must contain 12-19 digits');
-    }
-    if (!/^\d{3,4}$/.test(value.cryptogramValue)) {
-        throw new Error('VGS credential short DAVV must contain 3-4 digits');
-    }
-    if (typeof value.cryptogramType !== 'string' || value.cryptogramType.toUpperCase() !== 'DAVV') {
-        throw new Error(`VGS credential type ${value.cryptogramType || '<missing>'} is not DAVV`);
-    }
-    if (!Number.isInteger(value.expMonth) || value.expMonth < 1 || value.expMonth > 12) {
-        throw new Error('VGS credential expiration month is invalid');
-    }
-    if (!Number.isInteger(value.expYear) ||
-        value.expYear < now.getFullYear() ||
-        (value.expYear === now.getFullYear() && value.expMonth < now.getMonth() + 1)) {
-        throw new Error('VGS credential is expired');
-    }
-    if (value.cryptogramExpiresAt !== undefined) {
-        const expiresAtMs = Date.parse(value.cryptogramExpiresAt);
-        if (!Number.isFinite(expiresAtMs))
-            throw new Error('VGS credential expiry is invalid');
-        if (expiresAtMs - now.getTime() < 60_000) {
-            throw new Error('VGS credential has less than 60 seconds of validity remaining');
-        }
-    }
-}
-/**
- * Mints the full DPAN + short DAVV only after the executor revalidates the
- * reviewed merchant, amount, and currency. The payment credential remains in
- * memory, is never returned to the caller, and can be requested only once.
- */
-export class VgsLiveInstrument {
-    reference;
-    cardholderName;
-    fetchCredential;
-    kind = 'agentic-token';
-    used = false;
-    minted = null;
-    constructor(reference, cardholderName, fetchCredential) {
-        this.reference = reference;
-        this.cardholderName = cardholderName;
-        this.fetchCredential = fetchCredential;
-    }
-    /**
-     * Non-null once VGS has actually issued a credential (the intent is consumed
-     * from that moment, even if local validation later rejects the credential) —
-     * exactly the population a VIC confirmation can be owed for.
-     */
-    confirmationTarget() {
-        return this.minted;
-    }
-    async getCredential(ctx) {
-        if (this.used)
-            throw new Error('VGS live credential instrument is single-use');
-        this.used = true;
-        validateTarget(this.reference, ctx);
-        if (!this.reference.tokenId || !this.reference.intentId) {
-            throw new Error('VGS checkout reference requires tokenId and intentId');
-        }
-        if (!this.cardholderName.trim())
-            throw new Error('cardholder name is required');
-        const { tokenId, intentId, ...transaction } = this.reference;
-        const value = await this.fetchCredential({ tokenId, intentId, transaction });
-        this.minted = { tokenId, intentId };
-        try {
-            validateCredential(value);
-        }
-        catch (err) {
-            // VGS already issued a cryptogram for this intent even though we refuse
-            // to fill it; "correct inputs and retry" would silently reuse a consumed
-            // intent, so steer the operator to a fresh one.
-            throw new Error(`${err.message} — a credential was issued by VGS but rejected locally; obtain a fresh intent before retrying`);
-        }
-        return {
-            pan: value.networkToken,
-            expMonth: value.expMonth,
-            expYear: value.expYear,
-            cvc: value.cryptogramValue,
-            cardholderName: this.cardholderName.trim(),
-            ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
-        };
-    }
-}
-/**
- * Consumes #5614's claimed CLI enrollment artifact (for the tokenId) plus a
- * FRESH purchase-scoped assurance, and creates a fresh, transaction-scoped VIC
- * intent + credential after checkout approval. This is the production-shaped
- * bridge; unlike VgsLiveInstrument it never needs a pre-created intent ID.
- *
- * The enrollment artifact's stored assuranceData is deliberately never sent:
- * replaying it makes intent creation succeed (HTTP 201) while the cryptogram
- * deterministically never completes — the #5709 dead end. Purchase
- * authorization is the fresh, merchant+amount+currency-scoped assurance,
- * validated against the checkout target BEFORE any intent is minted so a
- * doomed intent is never created.
- */
-export class VgsAssuranceInstrument {
-    enrollment;
-    purchase;
-    target;
-    cardholderName;
-    mintCredential;
-    kind = 'agentic-token';
-    used = false;
-    minted = null;
-    constructor(enrollment, purchase, target, cardholderName, mintCredential) {
-        this.enrollment = enrollment;
-        this.purchase = purchase;
-        this.target = target;
-        this.cardholderName = cardholderName;
-        this.mintCredential = mintCredential;
-    }
-    /** See VgsLiveInstrument.confirmationTarget — same contract. */
-    confirmationTarget() {
-        return this.minted;
-    }
-    async getCredential(ctx) {
-        if (this.used)
-            throw new Error('VGS assurance instrument is single-use');
-        this.used = true;
-        validateCliCredential(this.enrollment);
-        validateTarget(this.target, ctx);
-        validatePurchaseAssurance(this.purchase, this.target);
-        if (!this.cardholderName.trim())
-            throw new Error('cardholder name is required');
-        const { payment: value, intentId } = await this.mintCredential({
-            tokenId: this.enrollment.tokenId,
-            assuranceData: this.purchase.assuranceData,
-            transaction: this.target,
-        });
-        this.minted = { tokenId: this.enrollment.tokenId, intentId };
-        validateCredential(value);
-        return {
-            pan: value.networkToken,
-            expMonth: value.expMonth,
-            expYear: value.expYear,
-            cvc: value.cryptogramValue,
-            cardholderName: this.cardholderName.trim(),
-            ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
-        };
-    }
-}

package/dist/checkout-engine/vic-confirmation.d.ts

@@ -1,34 +0,0 @@
-import type { CheckoutOutcome } from './executor.js';
-import type { VicConfirmationTarget } from './vgs-live-instrument.js';
-export type VicTransactionStatus = 'APPROVED' | 'DECLINED';
-export type PostVicConfirmation = (input: {
-    tokenId: string;
-    intentId: string;
-    transactionStatus: VicTransactionStatus;
-    transactionType: 'PURCHASE';
-    transactionTimestamp: string;
-    transaction: {
-        transactionAmount: string;
-        transactionCurrencyCode: string;
-    };
-}) => Promise<unknown>;
-export type VicConfirmationReport = {
-    posted: true;
-    transactionStatus: VicTransactionStatus;
-} | {
-    posted: false;
-    reason: string;
-};
-/** Definitive merchant answers map to a status; everything else maps to none. */
-export declare function outcomeToTransactionStatus(outcome: CheckoutOutcome): VicTransactionStatus | null;
-export declare function reportVicOutcome(input: {
-    target: VicConfirmationTarget | null;
-    outcome: CheckoutOutcome;
-    transaction: {
-        transactionAmount: string;
-        transactionCurrencyCode: string;
-    };
-    post: PostVicConfirmation;
-    /** Injectable for tests; defaults to now. */
-    timestamp?: Date;
-}): Promise<VicConfirmationReport>;

package/dist/checkout-engine/vic-confirmation.js

@@ -1,39 +0,0 @@
-/** Definitive merchant answers map to a status; everything else maps to none. */
-export function outcomeToTransactionStatus(outcome) {
-    if (outcome === 'confirmed')
-        return 'APPROVED';
-    if (outcome === 'declined')
-        return 'DECLINED';
-    return null;
-}
-export async function reportVicOutcome(input) {
-    const transactionStatus = outcomeToTransactionStatus(input.outcome);
-    if (!transactionStatus) {
-        return {
-            posted: false,
-            reason: `outcome '${input.outcome}' is not a definitive merchant answer — ` +
-                'resolve it with the merchant, then post the confirmation manually',
-        };
-    }
-    if (!input.target) {
-        return { posted: false, reason: 'no VIC credential was minted in this run' };
-    }
-    try {
-        await input.post({
-            tokenId: input.target.tokenId,
-            intentId: input.target.intentId,
-            transactionStatus,
-            transactionType: 'PURCHASE',
-            transactionTimestamp: (input.timestamp ?? new Date()).toISOString(),
-            transaction: input.transaction,
-        });
-        return { posted: true, transactionStatus };
-    }
-    catch (err) {
-        return {
-            posted: false,
-            reason: `confirmation POST failed: ${err.message} — the merchant outcome stands; ` +
-                'retry the confirmation for this intent out-of-band',
-        };
-    }
-}

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

@@ -1,299 +0,0 @@
----
-name: pair-visa-agent
-description: Pair a Visa CLI v4 agent identity to this device so the agent can pay on the user's behalf. You paste a link, the user enrolls on mobile web, and the credential auto-pairs back to this device — no code is ever typed back. Use when the user says "pair my agent", "enroll my Visa CLI", "connect my Visa wallet", "set up my agent identity", "get me set up to pay", "log in to Visa", or asks to connect/sign up their .visa account.
-compatibility: Needs the `visa` CLI (`npm i -g @visa/cli@rc`) — run `node scripts/setup.mjs` to auto-install it if missing — plus network access to the Visa verify-web origin. 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.5.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
-  # missing; other runtimes (Hermes, Claude Code, …) self-provision via the
-  # bundled `scripts/setup.mjs` (see compatibility + Getting set up). @rc pinned
-  # until 4.1.0 is promoted to latest.
-  openclaw:
-    user-invocable: true
-    emoji: '💳'
-    requires:
-      bins:
-        - visa
-    install:
-      - kind: node
-        package: '@visa/cli@rc'
-        bins:
-          - visa
-          - visa-cli
----
-
-# Pair a Visa CLI v4 Agent Identity
-
-Connects a Visa v4 identity (`.visa` name + delegated wallet + card) to THIS device
-through a mobile-web enrollment link. This is the device-link flow: the credential
-pairs back **automatically** to the terminal that started it. **No confirmation code is
-ever typed back into you** — the code is an out-of-band check the human reads to confirm
-the page they are on is the flow you started.
-
-Driven through the local `visa` binary. **This skill is runtime-agnostic** — it works in
-OpenClaw, Hermes, or any agent runtime that can run the `visa` CLI or mount its MCP
-server (see Runtimes). Use whichever pairing surface your runtime exposes; they all wrap
-the same two `visa` commands:
-
-- **`pair_agent_start` / `pair_agent_poll`** — the OpenClaw plugin tools (parse JSON for you). Use these if present.
-- **`enroll_agent`** — the `visa` MCP server tool, if the runtime has the server mounted.
-- **`visa agent enroll` / `visa agent enroll-claim`** — the raw CLI, always available if `visa` is on PATH. The universal fallback.
-
-Pick the first one available; if unsure, shell out to the raw CLI commands — every path
-hits the same hand-off on this device.
-
-## Getting this skill
-
-The skill ships **inside the public `@visa/cli` npm package** — no git clone of the
-(private) monorepo is required, so any agent box that can reach npm can install it:
-
-```
-npm install -g @visa/cli@rc      # public npm — puts `visa` on PATH
-visa agent skill                 # plants this skill into your runtime's skills dir
-```
-
-`visa agent skill` auto-detects OpenClaw / Hermes / Claude Code (falling back to the
-project-local `./.agents/skills`); pass `--runtime <name>` or `--dir <path>` to target
-one explicitly, `--force` to overwrite, or `--print` to read it without writing. After
-it lands, **reload/restart your agent** so the runtime registers the skill, then prompt
-the agent — "set up my Visa agent to pay" — to run the pairing flow below. (Installing a
-skill does not run it; the agent activates it on a matching prompt.)
-
-Access is gated server-side by the employee allowlist + Turnkey, so shipping the playbook
-over public npm exposes no capability — only allowlisted accounts can actually pair.
-
-(OpenClaw users also get it auto-bundled with the `@visa/visa-cli-openclaw` plugin. The
-`npx skills add` open-standard path applies once the skill is published to a public repo.)
-
-## Getting set up (install → mount → pair → transact)
-
-The whole flow, top to bottom:
-
-1. **Install the CLI (prerelease)** — `npm install -g @visa/cli@rc`, **or** run the bundled
-   provisioner `node scripts/setup.mjs` (idempotent — installs `@visa/cli@rc` only if `visa`
-   is missing; this is how **Hermes / Claude Code / any runtime** self-provisions, and what
-   OpenClaw runs automatically via the manifest). You **must** use the `@rc` tag: the
-   `@latest` tag (4.0.x) predates the `visa agent` commands and reports "does not expose
-   agent enroll". This puts both `visa` and `visa-cli` on PATH and ships the bundled MCP
-   server (`@visa/cli/dist/mcp-server/index.js`). (Once 4.1.0 is promoted to `latest`, bare
-   `@visa/cli` will work.)
-2. **Mount the MCP server** — one mount gives this agent the _entire_ v4 toolset:
-   - **OpenClaw:** installing the `@visa/visa-cli-openclaw` plugin **auto-mounts** the server
-     (its postinstall writes `mcp.servers["visa-cli"]` into `~/.openclaw/openclaw.json`).
-     Nothing to do by hand.
-   - **Hermes / anything else:** run `visa-cli install hermes` (or `visa-cli install <runtime>`).
-     This writes the server entry idempotently into the runtime's config (Hermes →
-     `~/.hermes/config.yaml` under `mcp_servers`). See Runtimes below for the exact shape.
-   - **No runtime integration?** The raw `visa agent …` CLI still works — the universal fallback.
-3. **Pair** — run the Core flow below. This binds a `.visa` identity + delegated wallet + card
-   to this device.
-4. **Transact** — once paired, use the mounted tools (see "What you can do once paired").
-
-## Runtimes
-
-One artifact, both runtimes. The `visa` CLI is the portable substrate; mount its MCP
-server so the runtime exposes the tools (both use the same server entrypoint — replace
-`<npm root -g>` with the output of `npm root -g`):
-
-**OpenClaw** (`~/.openclaw/openclaw.json`):
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "visa-cli": {
-        "command": "node",
-        "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
-      }
-    }
-  }
-}
-```
-
-**Hermes** (`~/.hermes/config.yaml`):
-
-```yaml
-mcp_servers:
-  visa-cli:
-    command: node
-    args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
-```
-
-No MCP server configured? The raw `visa agent …` CLI commands below work as long as `visa`
-is on PATH. (In Hermes, `hermes claw migrate` also imports this skill from an existing
-OpenClaw install into `~/.hermes/skills/`.) See `RUNTIMES.md` for the full plugin/config map.
-
-## Running commands
-
-- Every command supports `--format json`; the tools use it. On success JSON goes to
-  stdout; on failure a JSON object with `error` (and, for claim, a `status`) goes to
-  stdout with a non-zero exit code. **Always parse the JSON — never scrape prose.**
-- `enroll-claim` exit codes are load-bearing: `0` = claimed (done), `3` = not ready yet
-  (poll again), `1` = terminal failure (stop, recover).
-
-## Core flow
-
-Copy this checklist and track progress:
-
-- [ ] Step 1 — Start the hand-off (`pair_agent_start` / `enroll_agent` / `visa agent enroll --format json`)
-- [ ] Step 2 — Present the link AND the confirmation code to the user
-- [ ] Step 3 — Poll until paired (`pair_agent_poll` / `visa agent enroll-claim --format json`) — auto-pairs, no code entry
-- [ ] Step 4 — Confirm the identity is bound to this device
-
-Below, "start" and "poll" mean whichever surface your runtime exposes (see the top of
-this skill). The returned fields and the poll semantics are identical across all of them.
-
-### Step 1 — Start the hand-off
-
-**CRITICAL:** Only ONE hand-off can be in flight per device; starting a new one replaces
-any prior. If the user says they already started enrolling, go to Step 3 first.
-
-Start the hand-off (`pair_agent_start`, or `visa agent enroll --format json`). It returns
-`browserUrl`, `confirmCode`, `expiresAt`.
-
-If it returns an error containing `verify-web URL not available in stable builds`, this is
-a stable CLI build with the surface not yet public. **Do NOT proceed** — tell the user to
-set `VISA_VERIFY_WEB_URL` (or use a preview/RC build), then stop.
-
-If it returns an error containing `RC build requires access` (often suffixed `Run: visa-cli
-setup`), this is an **older RC build** whose employee gate still fires on the pairing
-bootstrap. **Do NOT run `visa-cli setup`** — that is the legacy v3 GitHub-OAuth path, it is
-NOT how v4 pairing authenticates, and it dead-ends on the same gate. Recover by either
-upgrading to a current RC (`npm install -g @visa/cli@rc` — recent RCs exempt `agent enroll`
-/ `agent enroll-claim` from this gate) or, if the operator has the code, setting the
-`VISA_RC_CODE` env var on the host. Then retry the hand-off. Never substitute `setup` for
-pairing.
-
-### Step 2 — Present the link AND the confirmation code
-
-Show BOTH clearly. The user opens the link on their phone.
-
-**Formatting rules — make it clean AND tappable in chat clients like Telegram:**
-
-- **Bare, tappable link.** Put `browserUrl` on its own line as a plain URL — no backticks, no
-  code span, and do **not** wrap it as a Markdown `[label](url)` link. Telegram auto-linkifies
-  a bare URL (one tap opens the phone's browser); a code span is unclickable, and the long
-  pairing query string (`?cli=…&cliPk=…`, with underscores) breaks Telegram MarkdownV2 link
-  parsing. Add a short "👉 Tap to open on your phone" cue so it reads as an action.
-- **Emphasize the confirm code.** Show `confirmCode` in **bold** or `monospace` — both are
-  Telegram-safe (mono needs no escaping). It's read/compared, never clicked.
-- **Relative expiry.** "expires in about 15 minutes" — never the raw `expiresAt` ISO/UTC
-  timestamp (e.g. `2026-07-21T21:22:57Z`); a UTC time reads as noise.
-- **Scannable layout.** Short lines, a blank line between blocks, one leading emoji per block.
-- **Don't over-Markdown.** Telegram MarkdownV2 requires escaping `_ * [ ] ( ) ~ > # + - = | { } . !`,
-  so heavy formatting risks a broken render. A bold/mono code + a bare link + emojis is plenty —
-  keep the rest plain prose.
-
-Use this shape:
-
-> 💳 **Pair your Visa agent** — open this on your phone:
->
-> 👉 &lt;browserUrl — bare, on its own line&gt;
->
-> 🔐 Confirmation code: **&lt;confirmCode&gt;**
->
-> On the final screen, check the code matches before you finish — only finish if it does. Never
-> type this code back to me or share it with anyone; it pairs back here automatically once you
-> finish. Expires in about 15 minutes.
-
-**Do NOT** ask the user to read the code back. **Do NOT** accept a code as input. Pairing
-is proven by a secret held on this device, not by anything the user types.
-
-### Step 3 — Poll until paired (auto-pair)
-
-Poll (`pair_agent_poll`, or `visa agent enroll-claim --format json`). With the raw CLI,
-read the **exit code** (`0` claimed / `3` not-ready / `1` terminal); the plugin tool
-returns the same as a `done`/`status` object. Then, based on the result:
-
-- `done: true` / exit 0, `status: "claimed"` → paired. Go to Step 4.
-- `done: false` / exit 3, `status: "not_ready"` → the user hasn't finished. Tell them
-  you're still waiting, then poll again. **Do not loop forever** — each poll already
-  waits ~9s; after a handful of polls, ask the user whether they've finished on their phone.
-- `done: true`, `status: "not_ready"`, `likelyExpired: true` → the 15-minute window
-  expired. Go back to Step 1.
-- `done: true`, `status: "confirm_mismatch"` → **STOP.** See Errors.
-- `done: true`, `status: "no_pending"` → no hand-off in flight. Go back to Step 1.
-
-### Step 4 — Confirm the identity is bound
-
-On `claimed`, tell the user their `name` (e.g. `alec.visa`) is paired to this device. Read
-`keyBound`:
-
-- `keyBound: true` → the agent key was generated on THIS device; its private half never
-  left it. Highest assurance.
-- `keyBound: false` → an existing agent was connected from a returning sign-in; no agent
-  key is held locally. Normal and expected for returning users — the credential is fully
-  valid.
-
-## What you can do once paired
-
-Pairing is the on-ramp. v4 is **non-custodial** — a Turnkey-delegated wallet bounded by
-on-device keys and policies, **not** a stored credit line or a server-custodied card.
-Describe it that way to the user. The mounted MCP server exposes:
-
-- **x402 wallet spend (the core rail)** — `wallet_discover` (find payable x402 services by
-  outcome; free) → `wallet_probe` (preview a fresh x402 challenge; free) → `wallet_pay` /
-  `wallet_directory_pay` (a bounded payment settled directly from the delegated wallet over
-  x402, wallet→endpoint — never touching credits, cards, or server-side spend controls).
-  These `wallet_*` tools are **default-on in the supported build** (the v4 wallet runtime is
-  bundled); spend stays bounded by the on-device wallet policy. The same rail is on the CLI
-  as `visa find` / `inspect` / `pay`.
-- **Visa catalog (curated tools)** — `discover_tools` → `execute_tool` (or `visa tools` /
-  `visa run`): enumerate the curated catalog and run a tool; paid ones show a preview and
-  settle inline. Distinct from the open x402 directory above.
-- **Subway mesh** — `subway_*` route calls across the agent mesh. **Gated:** present but only
-  reach the mesh once the `.visa` relay is wired (`SUBWAY_MESH` / `SUBWAY_RELAY_MULTIADDR`);
-  until then they no-op against an unreachable relay.
-- **Real-merchant card checkout (experimental, opt-in)** — `pay_merchant` fills and pays an
-  ordinary merchant web checkout with a **Verified Agent card credential**: a one-shot
-  network-token cryptogram minted **on this device** (non-custodial) — not a stored card,
-  not x402, not server-side spend controls. Two steps: `review` (free; returns merchant +
-  exact amount as a `reviewId`) then `pay` (requires `confirm: "PAY <reviewId>"` + a passkey,
-  and CHARGES). **Tester-gated** (`checkout_agent_access`) and **RC/preview builds only** —
-  opt-in, never paired-and-go.
-
-If a tool you expect isn't visible, the MCP server isn't mounted (or the v4 wallet runtime
-isn't bundled in this build) — go back to "Getting set up".
-
-## Important
-
-- **The confirmation code is display-only.** Show it; never ask for it; never accept it as
-  input. It lets the human verify the page matches the flow you started.
-- **Never read, print, log, or echo** the credential file or the enrollment pending file,
-  or the `browserUrl` query values beyond the single presentation to the user. The link
-  carries only a hash + a public key — safe in history — but treat it as one-time.
-- Do not run API-key setup, card enrollment, or a balance top-up as a substitute for
-  pairing. Once paired, use the `visa-cli` skill's Rail 1 commands to pay.
-
-## Limits
-
-| Limit                          | Value                                                        |
-| ------------------------------ | ------------------------------------------------------------ |
-| Hand-off validity              | 15 minutes from `pair_agent_start`                           |
-| In-flight hand-offs per device | 1 (a new start replaces the prior)                           |
-| Claim                          | single-shot server-side; once claimed the entry is destroyed |
-| Confirmation code              | 6 chars, no ambiguous glyphs; display-only                   |
-
-## Errors
-
-All errors are JSON with a non-zero exit code; `enroll-claim` tags them with `status`.
-
-| status / symptom                                                  | Cause                                                             | Recovery                                                                                                                                                                                  |
-| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `error: verify-web URL not available in stable builds`            | Stable CLI build, surface not public                              | Set `VISA_VERIFY_WEB_URL` or use a preview build. Do not proceed otherwise.                                                                                                               |
-| `error: RC build requires access` (may say `Run: visa-cli setup`) | Older RC build whose employee gate still fires on the bootstrap   | **Do NOT run `visa-cli setup`** (legacy v3 GitHub-OAuth path; dead-ends on the same gate). Upgrade the RC (`npm install -g @visa/cli@rc`) or set `VISA_RC_CODE`, then retry the hand-off. |
-| `no_pending`                                                      | No hand-off in flight (never started, or already claimed/expired) | Start fresh with `pair_agent_start`.                                                                                                                                                      |
-| `not_ready`, `likelyExpired: false`                               | User hasn't finished the mobile flow                              | Wait, tell the user, poll again. Bounded polling only.                                                                                                                                    |
-| `not_ready`, `likelyExpired: true`                                | 15-minute window elapsed                                          | Start over with `pair_agent_start`.                                                                                                                                                       |
-| `confirm_mismatch`                                                | The claim didn't match THIS device's secret                       | STOP. Show the re-derived `confirmCode`. If the user did not just finish the flow, someone else may hold their link — start over. Never retry blindly.                                    |
-| `error` (network / malformed)                                     | Transport or server error                                         | Surface the message. Poll once more; if it persists, start over.                                                                                                                          |
-
-## Further docs
-
-- `docs/agents/ARCHITECTURE.md` — where the enroll hand-off sits in the v4 request paths.
-- `visacli.sh/agents` — product-facing agent docs.

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

@@ -1,48 +0,0 @@
-#!/usr/bin/env node
-// Portable provisioner for the pair-visa-agent skill.
-//
-// Ensures the `visa` CLI is installed so ANY Agent Skills runtime can pair —
-// not just OpenClaw (whose `metadata.openclaw.install` auto-runs). Hermes,
-// Claude Code, and any other agentskills.io-compatible runtime run this bundled
-// script per the standard's `scripts/` execution stage.
-//
-// Safe to run repeatedly: it no-ops when `visa` already resolves. Pinned to @rc
-// because the v4 agent surface is prerelease (the @latest tag predates the
-// `visa agent` commands); drop the tag once 4.1.0 is promoted to latest.
-
-import { execSync } from 'node:child_process'
-
-function resolves(cmd) {
-  try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' })
-    return true
-  } catch {
-    return false
-  }
-}
-
-if (resolves('visa') || resolves('visa-cli')) {
-  console.log('✓ visa CLI already installed — nothing to do. Run the pairing flow in SKILL.md.')
-  process.exit(0)
-}
-
-console.log('Installing @visa/cli@rc (the v4 agent surface is prerelease)…')
-try {
-  execSync('npm install -g @visa/cli@rc', { stdio: 'inherit' })
-} catch {
-  console.error(
-    'Global install failed. Try `npm install -g @visa/cli@rc` manually (may need sudo, or set a\n' +
-      'user-writable npm prefix: `npm config set prefix ~/.npm-global` and add its `bin` to PATH).'
-  )
-  process.exit(1)
-}
-
-if (!resolves('visa') && !resolves('visa-cli')) {
-  console.error(
-    'Installed, but `visa` is not on PATH. Ensure your npm global bin dir is on PATH\n' +
-      '(`npm bin -g` shows it), then re-run this script.'
-  )
-  process.exit(1)
-}
-
-console.log('✓ visa CLI ready. Now run the pairing flow in SKILL.md.')