@visa/cli 5.0.0-rc.415 → 5.0.0-rc.416

package/README.md

@@ -1,9 +1,9 @@
 # @visa/cli
 
-Visa CLI connects a computer to Visa as an **agent**: one durable agent whose
-installation key never leaves this machine, approved once by its owner in the
-Visa Console. Agents act through the MCP tools this package serves; owners act
-in the Console. The terminal only connects.
+Visa CLI connects each app to Visa as its own **agent**. Its installation
+key stays on this machine. The owner approves the agent once in the Visa
+Console. Agents act through the MCP tools this package serves; owners act in
+the Console. The terminal only connects.
 
 It speaks the Visa agent API, `/agent/v1`, and nothing else.
 
@@ -31,8 +31,8 @@ Managed updates certify the installed MCP bundle with `node dist/mcp-server/inde
 visa connect claude     # or cursor, codex, zed, ... (any client id the CLI knows)
 ```
 
-`connect` mounts the Visa MCP server in the AI client, then sets this computer
-up as an agent:
+`connect` mounts the Visa MCP server in the AI client, then sets up that app’s
+agent:
 
 1. It makes an Ed25519 installation key in this machine's key store (macOS
    Keychain, Windows DPAPI, Linux Secret Service, or a 0600 file on a headless
@@ -46,6 +46,17 @@ up as an agent:
    need a second `connect` call. `status` reports pickup progress and fresh
    Authority truth; connecting does not mean payments or TAP are ready.
 
+Connection is separate from spending:
+
+```text
+Connected.
+Next: add funds and set a limit.
+```
+
+A funded wallet needs only a limit. Status exposes the current connection and spending step in `connection`.
+
+New spending limits start on **Ask me each time**. On a connected computer, the owner can choose **Pay within my budget**, with suggested limits of $25 per payment and $100 in total. App connections ask before each payment.
+
 Before presenting a saved approval link, connect and status read the setup's current server state, including while another process owns pickup. Ended or already approved setups expose no approval URL. Status never claims a setup; unknown server state stays recoverable.
 
 Pickup stays bound to this setup and key. Its bound covers the setup's initial
@@ -59,6 +70,22 @@ store refuses without a fallback or extra prompt. The original setup remains ava
 for recovery on the next invocation. A missing pickup bundle or failed launch
 is reported as interrupted, rather than promising automatic completion.
 
+Reconnecting the same app keeps its agent. Connecting a different app starts
+a separate setup, with its own name, mark, key and limits. Older connections
+first recover their app from authenticated status. If that identity is unavailable,
+retry connect later or select the existing agent explicitly; no new setup is started.
+If Visa confirms that no app was recorded, connect asks you to select the existing
+agent explicitly instead of retrying or inferring its app from the caller.
+MCP tools default to the calling app’s agent when exactly one matches. An explicit
+agent selector overrides that default. Without a matching app, the usual agent
+selection applies.
+
+This computer remembers the wallet first returned by connect or status. Signing
+refuses a different wallet, owner or organisation; payments also check the saved
+wallet account. Agents connected before this update save it on their next
+successful connect or status read. Until then they keep the previous behaviour.
+Replacing the same agent on this computer keeps its saved wallet identity.
+
 Every step resumes. Pickup continues after the terminal closes; if it is interrupted,
 run `visa connect` again to recover the same setup.
 `--wait 0` starts the setup and returns; `--no-open` prints the link instead.
@@ -79,6 +106,12 @@ run `visa connect` again to recover the same setup.
   `--all` also cancels unfinished local setups and automatic pickup. If an
   unsettled purchase keeps a connected key, its pending replacement is still cancelled.
 - **Update**: `visa update` (RC stays on `@visa/cli@rc`).
+  Updates check a separate release before switching all entry points; interrupted
+  downloads keep the previous release usable. Activation rechecks the current release,
+  so an overlapping update keeps the active CLI, shell tools and MCP available.
+  Releases that cannot start through the installed MCP launcher are refused
+  before activation, including incompatible older releases selected by the channel.
+  Supervisor-managed runtimes continue to use `visa-runtime-converge`.
 
 | Command                    | What it does                                                                          |
 | -------------------------- | ------------------------------------------------------------------------------------- |
@@ -110,6 +143,8 @@ higher `skill_version`, the app asks its owner for the new text. Muse will not
 save a program's output as a skill, so its owner pastes the same text from the
 Console's Muse message.
 
+A delivered answer stays available from `payment_status` during a temporary read outage. Settlement stays unconfirmed until Visa can read the original purchase again.
+
 ## MCP tools
 
 Concurrent calls stay bound to their selected agent for every payment phase;
@@ -122,18 +157,48 @@ stable launcher) serves the laptop column of the one Visa tool catalogue:
 | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | `status`         | Who this agent is, what is ready, and who takes the next step. Call first.                                                         |
 | `connect`        | Connect this computer (or replace its key). Returns the owner link; picks up approval automatically.                               |
-| `discover`       | Search paid services or probe one URL. Answers `unavailable` until the discovery source is live.                                   |
-| `pay`            | Pay a URL that answers HTTP 402 with a Tempo charge (OUSD). Needs `max` and a new `request_id` per purchase. **Moves real money.** |
+| `discover`       | Search paid services or probe one URL with GET and no body. Answers `unavailable` until the discovery source is live.                                   |
+| `pay`            | Pay a URL that answers HTTP 402 with a Tempo charge (OUSD). Needs `max` including the network fee and a new `request_id` per purchase. Optional `userRequest`: the person's words, kept by Visa for product analysis. **Moves real money.** |
+| `task_post`      | Post a claim task with a reward in USD and a `request_id`; uses the existing payment limits and approval. |
+| `task_action`    | Claim, submit, accept or release a task. Claim and submit need the owner's approval of the signature, then the same call again; submit and accept pay and need `max`. Every action first needs Visa's clearance of that task. **Moves real money.** |
+| `task_list`      | List open screened tasks (or one named task with `task_id`) and short-lived clearances for task actions. Never pays. |
+| `task_status`    | Read a task’s status, reward and available claimant or submission. Never pays. |
 | `payment_status` | Read one purchase by its `request_id`, optionally waiting for it to change.                                                        |
-| `payment_cancel` | Cancel a purchase that has not executed.                                                                                           |
+| `payment_cancel` | Cancel a purchase awaiting owner approval.                                                                                           |
 | `history`        | This agent's purchases, newest first.                                                                                              |
 
+`task_action` is optional; use only tools advertised by this connection.
+
+Each tool advertises an extensible object `outputSchema`. Local and hosted MCP
+return that object in `structuredContent`, with a two-line summary first in
+`content` and the complete serialized JSON in a second text block. Text-only
+clients should read the JSON block; display clients should show the summary.
+Existing payload fields and refusal references remain available in the object.
+The shell adapter, `visa-tool`, prints the object as JSON and appends a
+`Reference: <id>` line on refusals; it does not print the MCP display summary.
+
+When a `discover` query finds no services, its `next` hint offers `task_post` with
+the query as the suggested description. Posting requires an explicit `reward`
+(USD decimal), `request_id`, optional `duration_seconds` (default 3600) and an
+optional documented `terms_preset` (`standard`, `fast` or `flexible`; a staked task
+names one). Unknown fields are refused. Local rules give fast feedback; the edge must allow the exact draft before paying.
+Tasks needing review are not posted. The CLI obtains fresh clearance before each
+task action; callers do not supply it to `task_action`. Submit needs `text` and
+`max`; accept needs `max`. A missing or invalid `max` is corrected on the same task action with the same `request_id`. Reuse the same arguments and request ID to resume; a task response
+does not prove payment settlement. Listed tasks show `net_reward` and any stake;
+a task that pays the worker nothing is never listed. A task outage or malformed task answer is named in
+`task_screening`, while successful service results remain available. `task_status` reads `/api/tasks/:id` without paying.
+Taskmarket defaults to its testnet on Tempo Moderato and to `api.taskmarket.dev`
+on mainnet; `VISA_TASKMARKET_URL=off` turns tasks off. The live testnet currently refuses access-key signatures;
+the harness models requested support separately.
+
 How `pay` works: the CLI builds the exact Tempo charge from the merchant's 402,
 asks Visa to admit it with this installation's proof, and, when the wallet
 provider needs this laptop's own approval, reads the signing activity from the
 provider itself, checks it against its own charge and votes. The paid request
 carries the agent's TAP signature; with no TAP key the CLI refuses before
-anything is signed. Reusing a `request_id` never pays twice: Visa's record
+anything is signed. Each paying merchant request and its paid retry send `Idempotency-Key` with the same
+`request_id`. Unpaid price previews send no idempotency header. Reusing a `request_id` never pays twice: Visa's record
 answers. When Visa verifies that the old execution was unpaid and explicitly
 returns the agent's `resume_payment` continuation, `payment_status` directs this
 computer to call `pay` with the same arguments and `request_id`. It prepares a
@@ -150,15 +215,22 @@ An authorized purchase without a signing continuation remains unknown and read-o
 
 When Visa reconciles a merchant-wallet hold, the settled purchase remains paid and cannot be retried. `pay` preserves Visa's guidance, and `payment_status` exposes its existing owner support continuation. Recovery depends on the merchant's settings; this continuation does not authorize a claim. A missing receipt, unavailable answer or client delivery report does not establish a merchant hold.
 
+A native payment awaiting approval resumes with `pay`, the same `request_id` and arguments after the owner approves.
+
 Only Visa’s canonical settled state is reported as paid; a merchant answer does not prove settlement. An unknown outcome is never reported as "nothing was paid". Free merchant answers are returned as a preview up to 1 MiB without payment or a kept file; the cap ends the read without waiting for EOF. If a paid answer file or its final journal cannot be saved, the original call still returns its bounded preview and canonical payment result; retries never pay again. A preview with no file does not promise local retention. If a payment read fails through a network interruption or a body interruption after a successful HTTP response, or returns retryable `503 unavailable`, a verified delivered answer remains available locally with settlement unknown; prepared, sending and incomplete receiving attempts still require the original read to succeed. Explicit HTTP refusals and complete malformed Visa responses remain errors. Kept paid answers are checked against the digest recorded as they arrived. A missing, changed, or previously undigested answer is unavailable; its purchase history remains and the paid request is never resent.
 
 Refusals are JSON with a `code` from the Visa error families (for example
 `setup_required`, `limit_reached`, `not_enabled`), a `message` and a `fix`.
-When the merchant's charge exceeds `pay.max`, the local `limit_reached` refusal
+For an OUSD charge, allow up to $0.01 above the quoted price for the network fee; a USDC.e swap also needs its funding ceiling.
+When the charge plus network fee ceiling exceeds `pay.max`, the local `limit_reached` refusal
 names the price above max; budget and cap refusals keep their own diagnostics.
 A saved merchant challenge that differs from its prepared payment is refused
 with a charge-mismatch diagnostic before signing or sending the paid request.
 
+The known Muse shell connection leaves other apps’ MCP settings and status lines untouched.
+
+Live status refreshes a renamed agent’s name on this computer. Owner steps for limits and paused apps link to that app in the Console. Unavailable tools direct the agent to the available tools; the owner handles withdrawals and conversions in Wallet.
+
 ## Status line
 
 `connect` installs a Claude Code status line (`visa-cli config statusline`).
@@ -190,6 +262,7 @@ and honours `NO_COLOR`.
 | `VISA_CLI_HOME`                | Where this CLI keeps its state (default `~/.visa-cli`).                                         |
 | `VISA_RUNTIME_CUSTODY_PROFILE` | `os` (default) or `headless` (a 0600 file key store).                                           |
 | `VISA_SUPPRESS_BROWSER=1`      | Print links instead of opening a browser.                                                       |
+| `VISA_TASKMARKET_URL` | Task service base URL; defaults to the Taskmarket testnet on Moderato and `https://api.taskmarket.dev` on mainnet. `off` disables tasks. |
 | `VISA_TEMPO_RPC_URL`           | A Tempo RPC for building charges (https, or this machine).                                      |
 | `VISA_RC_CODE`                 | The access code a release-candidate build asks for.                                             |
 | `VISA_CLI_HUD_THEME`           | `light` or `dark` status line colours, when the terminal does not say (`COLORFGBG`).            |
@@ -201,7 +274,7 @@ and honours `NO_COLOR`.
 | OS key store, or `~/.visa-cli/agent-keys/` (headless) | The installation key.                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `~/.visa-cli/agent.json`                              | This computer's agent (ids, name) and, while a setup is open, its one-time setup secret (0600).                                                                                                                                                                                                                                                                                                                                         |
 | `~/.visa-cli/hud-facts.json`                          | The status line's cache: the agent's last read state, never keys or tokens.                                                                                                                                                                                                                                                                                                                                                             |
-| `~/.visa-cli/purchases/`                              | Server- and agent-scoped records needed to finish after interruption, and merchant answers up to 50 MiB (0600 in a 0700 directory). Canonical settlement or a final unpaid outcome removes the prepared charge and unsigned transaction. Purchase records and already-kept answers are not automatically deleted, including on `visa disconnect --all`. Credential/security lifetimes and terminal preparation cleanup remain separate. |
+| `~/.visa-cli/purchases/`                              | Server- and agent-scoped records needed to finish after interruption, and merchant answers up to 50 MiB (0600 in a 0700 directory). When local storage can be updated, canonical settlement or a final unpaid outcome removes the prepared charge and unsigned transaction. Purchase records and already-kept answers are not automatically deleted, including on `visa disconnect --all`. Credential/security lifetimes and terminal preparation cleanup remain separate. |
 
 ### Managed runtime convergence
 
@@ -212,7 +285,7 @@ OpenClaw/Hermes deployments. See
 ### Cutover B hosted approval context
 
 The target hosted REST and MCP `pay` input accepts optional `original`, using the
-same canonical v1 terms and transient public replay request as payment prepare.
+same canonical v1 terms and transient confidential replay request as payment prepare.
 Supply the actual original signing intent; a description or commitment hash
 cannot reconstruct it. Reuse the existing `request_id` to resume the purchase.
 
@@ -225,3 +298,101 @@ or telemetry. The owner and original payment/approval/deadline bindings remain
 required. Hosted Tempo payments ask the owner each time and resume the same
 approved purchase. Internal admission and current spending checks still apply.
 This source contract does not establish deployed availability.
+
+### Protected message signing
+
+Status separates deployment `message_signing.configured` from this agent's
+`message_signing.readiness`. Follow an incomplete readiness continuation.
+`ready` means prerequisites are present, not that a message is authorized;
+service admission and separate owner consent still apply. Older status answers
+without readiness do not establish it from connection or configuration alone.
+
+`visa-tool sign_action` and the local/hosted MCP tool accept `request_id`,
+`scheme: "personal_sign"`, the original UTF-8 `message` and an HTTPS-origin
+`audience`. Use the same request ID and original inputs to resume. The selected
+agent determines the wallet and Tempo access key. The signature is an
+account-bound Tempo keychain V2 envelope; a service must support that envelope.
+Audience and network metadata constrain issuance. The external signature binds
+them only when the service includes them in its signed message.
+
+Message permission is separate from payment limits. The owner can approve the
+exact message or, on a device, an explicit literal prefix using
+`permission_scope`. Matching device requests name that `permission_id`.
+Permissions currently last at most five minutes and the current key expiry;
+renewal needs new owner consent. Hosted signatures require exact owner consent
+and an independent owner vote each time. Signing may authorize escrow or other
+financial effects at a service even though no new payment occurs.
+
+`GET /agent/v1/signatures/:request_id` reports metadata only. Repeating the
+original `sign_action` recovers a known provider activity and verifies the
+signature again before delivery. A dispatch with a lost activity locator stays
+unknown and is never replaced. The private owner page can revoke consent and
+dispose of its message context; commitments and dispatch fences remain.
+
+The production signer refuses unconfigured, unknown or ambiguous message
+namespaces. Trusted policy configuration and protected-provider qualification
+are activation requirements. No marketplace commands, EIP-712, root-wallet
+signing, ERC-8004 registration or automatic legal acceptance are added.
+
+### HTTP identity
+
+Protected signer preparation retains an assigned directory Key ID, registered
+agent domain and known public directory origin when the registry supplies them.
+The current signing profile still uses the cryptographic key thumbprint in its
+signed headers. Directory UUIDs require a protected signing-contract upgrade.
+HTTP identity v5 can cover a caller-supplied `Signature-Agent` header, but this
+metadata is not automatically sent. Retaining metadata alone does not establish
+merchant interoperability.
+
+`visa-tool attest_http_request` and local/hosted MCP accept a canonical HTTPS
+`url`, `method` (`GET`, `HEAD`, `POST`), application `headers` as pairs and
+`body_sha256` as a base64url SHA-256 digest. They return the exact normalized
+request and short-lived TAP identity headers. The agent sends them with its own
+HTTP client. Nothing is sent or paid by this tool; a 402 still needs `pay`.
+
+This uses the TAP identity key and standing owner TAP consent. `sign_action`
+continues to govern wallet-key messages. Requests can authorize service actions,
+so use the identity deliberately. Requires gate v5; older deployments refuse.
+See [the protocol, SDK and merchant contract](../../docs/design/target/http-attestation.md).
+
+### Merchant headers for Tempo MPP
+
+`pay` accepts `headers` as a string map or name/value pairs. Supply the merchant's
+required receipt and stable operation key, such as `Idempotency-Key`, unchanged
+on recovery. They are independent of Visa's purchase UUID. Permitted names are
+case-insensitive, values stay exact, and request commitments detect changes.
+Reserved transport, wallet/payment authorization and Visa headers are refused.
+Raw values stay transient and do not enter logs or public history. Redirects are
+not followed with these headers. Native ATUM currently refuses caller-supplied
+headers before funding because its closed plan does not bind them.
+
+Registry documentation follows the package release channel: prerelease builds use preview docs; stable builds use production docs.
+
+`status` accepts only the optional `agent` selector. Unknown arguments are refused;
+correct them on the same tool.
+
+Correct a malformed request_id on the same tool that refused it. Resuming an existing operation keeps its original request_id.
+
+Hosted discover searches by query. To price a URL, use discover with target in Visa CLI on a connected computer.
+
+A validation refusal describes the rejected input. It does not establish an earlier purchase’s outcome; read that purchase with payment_status and its original reference.
+
+A refused or unavailable task directs the agent to another permitted task. A task needing review directs it to Visa support; these refusals do not direct purchase-status reads.
+
+For a signing input conflict, repeat sign_action with its original inputs and request_id. The repeat_original_sign_action continuation refers to signing; payment_status retrieves purchases.
+
+An account-wide daily limit offers a smaller payment, a later attempt or Visa
+support. Raising an agent's spending limit cannot change that account limit.
+
+`history` accepts the previous answer's `page.next_cursor` as `cursor`, unchanged,
+to read the next page on local and hosted tools.
+
+`discover` accepts `limit` from 1 to 50. A search returns the matching services
+available, which can be fewer than the requested limit.
+
+A final `payment_status` or `payment_cancel` read updates this computer's purchase
+record. Disconnect releases a key once its purchases are final; an uncertain or
+in-flight purchase keeps its key and any saved merchant answer.
+
+HTTP identity requests for a paused agent retain the owner's resume step,
+including when its public identity entry is no longer available.

package/bin/active-package.cjs

@@ -0,0 +1,15 @@
+// The bootstrap package stays installed while a replacement is downloaded.
+const fs = require('node:fs')
+const path = require('node:path')
+module.exports = function activePackage(bootstrap) {
+  const root = path.join(bootstrap, '.self-update')
+  let version
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(root, 'active.json'), 'utf8')).version
+  } catch (error) {
+    if (error.code === 'ENOENT') return bootstrap
+    throw error
+  }
+  if (!/^\d+\.\d+\.\d+(?:-rc\.\d+)?$/.test(version)) throw new Error('Invalid CLI release')
+  return path.join(root, 'releases', version, 'node_modules', '@visa', 'cli')
+}

package/bin/update.cjs

@@ -0,0 +1,92 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const { pathToFileURL } = require('node:url')
+const { execFileSync } = require('node:child_process')
+const { randomUUID } = require('node:crypto')
+
+module.exports = async function update(bootstrap, tag, logger) {
+  const activePackage = require('./active-package.cjs')
+  const root = path.join(bootstrap, '.self-update')
+  const helpers = await import(
+    pathToFileURL(path.join(__dirname, '..', 'dist', 'managed-runtime', 'update-and-restart.mjs'))
+      .href
+  )
+  if (process.env.VISA_MANAGED_RUNTIME_DIR) {
+    const managed = await import(
+      pathToFileURL(path.join(__dirname, '..', 'dist', 'managed-runtime', 'resolve-and-update.mjs'))
+        .href
+    )
+    await managed.runManagedRuntimeConvergence(process.env, {
+      logger: { log: (message) => logger.info('update:managed', { message }) },
+    })
+    return
+  }
+  const id = randomUUID()
+  const options = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 300_000 }
+  // Four registry/install commands and two probes must finish before this lease can expire.
+  const unlock = helpers.acquireUpdateLock(root, id, { leaseMs: options.timeout * 6 + 60_000 })
+  const npm = (command, args, opts) => {
+    const output = execFileSync(command, args, opts)
+    logger.info('update:package_manager', { command: args[0], output: String(output ?? '') })
+    return output
+  }
+  try {
+    // A preceding updater may have activated a release while this one loaded.
+    const active = activePackage(bootstrap)
+    const version = JSON.parse(
+      npm('npm', ['view', `@visa/cli@${tag}`, 'version', '--json'], options)
+    )
+    if (
+      typeof version !== 'string' ||
+      !/^\d+\.\d+\.\d+(?:-rc\.\d+)?$/.test(version) ||
+      version.includes('-rc.') !== (tag === 'rc')
+    )
+      throw new Error('Registry did not return an exact release on this channel')
+    if (JSON.parse(fs.readFileSync(path.join(active, 'package.json'), 'utf8')).version === version)
+      return
+    const release = helpers.stageExactRelease(
+      {
+        managedDir: root,
+        exactVersion: version,
+        commandTimeoutMs: options.timeout,
+        correlationId: id,
+      },
+      {
+        execFileSync: npm,
+        logger: { log: (message) => logger.info('update:stage', { message }) },
+      }
+    )
+    const installed = path.join(release, 'node_modules', '@visa', 'cli')
+    const reported = execFileSync(
+      process.execPath,
+      [path.join(installed, 'bin', 'visa-cli.js'), '--version'],
+      options
+    ).trim()
+    if (reported !== version) throw new Error('Staged CLI version did not match')
+    const checked = JSON.parse(
+      execFileSync(
+        process.execPath,
+        [
+          '-e',
+          `const server = require(process.argv[1]);
+if (typeof server.startMcpServer !== 'function') throw new Error('Incompatible MCP launcher');
+server.startMcpServer();`,
+          path.join(installed, 'dist', 'mcp-server', 'index.js'),
+          '--self-check',
+        ],
+        options
+      )
+    )
+    if (checked.ok !== true || checked.build?.version !== version)
+      throw new Error('Staged MCP server did not load')
+    fs.accessSync(path.join(installed, 'dist', 'cli.js'))
+    fs.accessSync(path.join(installed, 'dist', 'tool-call.js'))
+    // Readers see the complete old release or the complete new release. The
+    // old package and every previous release remain usable after interruption.
+    const next = path.join(root, `.active-${id}.json`)
+    fs.writeFileSync(next, JSON.stringify({ version }), { mode: 0o600, flag: 'wx' })
+    fs.renameSync(next, path.join(root, 'active.json'))
+  } finally {
+    unlock()
+  }
+}

package/bin/visa-cli.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-require('../dist/cli.js');
+const path = require('node:path')
+const active = require('./active-package.cjs')(path.dirname(__dirname))
+require(path.join(active, 'dist', 'cli.js'))

package/bin/visa-tool.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-require('../dist/tool-call.js')
+const path = require('node:path')
+const active = require('./active-package.cjs')(path.dirname(__dirname))
+require(path.join(active, 'dist', 'tool-call.js'))
   .main(process.argv.slice(2))
   .then((code) => {
     process.exitCode = code