@visa/cli 4.1.0-rc.26 → 4.1.0-rc.260

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

@@ -1,79 +1,122 @@
-# Running the Visa pairing skill in OpenClaw **and** Hermes
-
-`@visa/visa-cli-openclaw` is packaged for OpenClaw, but the v4 **pairing** capability
-(`skills/pair-visa-agent/`) is deliberately runtime-agnostic: one skill works in OpenClaw,
-[Hermes](https://github.com/NousResearch/hermes-agent), or any runtime that can run the
-`visa` CLI or mount its MCP server. This doc is the map of how the two runtimes differ and
-why a single skill suffices.
-
-## The blunt fact: plugins are NOT portable
-
-| Axis            | OpenClaw                                                  | Hermes (NousResearch)                                                                                                                     |
-| --------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Language        | **JavaScript/TypeScript**                                 | **Python**                                                                                                                                |
-| Plugin manifest | `openclaw.plugin.json` + `definePluginEntry` (`index.ts`) | `~/.hermes/plugins/<name>/plugin.yaml` + `__init__.py`, `ctx.register_tool(...)`                                                          |
-| Config file     | `~/.openclaw/openclaw.json`                               | `~/.hermes/config.yaml`                                                                                                                   |
-| Skills          | markdown `SKILL.md` (+ optional UV scripts)               | markdown `~/.hermes/skills/<name>/` (agent-authored + curated Skills Hub)                                                                 |
-| MCP             | `openclaw.json` → `mcp.servers.*`                         | `config.yaml` → `mcp_servers.*`                                                                                                           |
-| Persona         | `SOUL.md`                                                 | `SOUL.md`                                                                                                                                 |
-| Migration       | —                                                         | `hermes claw migrate` (v0.3.0+): imports SOUL, memory, **skills → `~/.hermes/skills/openclaw-imports/`**, allowlists, and **MCP servers** |
-
-You cannot ship one plugin binary for both — the OpenClaw JS `pair_agent_*` tools in this
-package do not load in Hermes. **Do not try.**
-
-## What IS portable: markdown skills + MCP
-
-Both runtimes (a) read markdown skills natively and (b) mount MCP servers via an
-equivalent config block (`mcp.servers.*` ↔ `mcp_servers.*`, same `command`/`args`/`env`,
-same tool include/exclude). So the cross-runtime bridge is:
-
-1. **The `visa` CLI** — `visa agent enroll|enroll-claim --format json` (piped, load-bearing
-   exit codes). Any runtime that can execute a command can pair.
-2. **The `visa` MCP server** — the bundled `dist/mcp-server/index.js` entrypoint (there is
-   **no `visa mcp` subcommand**; `visa-cli connect <client>` registers it, or configure it
-   by hand). Mount it identically in either runtime:
-
-   **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']
-   ```
-
-3. **One `pair-visa-agent/SKILL.md`** — runtime-agnostic. It tells the agent to use
-   whichever pairing surface is present (`pair_agent_*` OpenClaw tools → `enroll_agent`
-   MCP tool → raw `visa agent …` CLI), all wrapping the same on-device hand-off.
-
-## So: how each runtime gets the capability
-
-| Runtime           | How it pairs                                                                                                                                                                                                                                 |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **OpenClaw**      | Install this package → the JS `pair_agent_start`/`pair_agent_poll` tools + the skill. (Or just the `visa` MCP server + the skill, no plugin.)                                                                                                |
-| **Hermes**        | Mount the `visa` MCP server in `config.yaml` (→ `enroll_agent`) and drop `pair-visa-agent/SKILL.md` into `~/.hermes/skills/`. `hermes claw migrate` will also import the skill from an existing OpenClaw install. No Python plugin required. |
-| **Anything else** | `visa` on PATH + the skill. The skill's raw-CLI path is the universal fallback.                                                                                                                                                              |
-
-## Optional: a symmetric Hermes plugin
-
-Not required — Hermes users get the full capability via the MCP server + skill above. If
-you want the _same named tools_ (`pair_agent_start`/`pair_agent_poll`) in Hermes, a thin
-`~/.hermes/plugins/visa-cli/` Python plugin (`plugin.yaml` + `__init__.py`) that shells out
-to `visa agent enroll|enroll-claim --format json` and registers the tools via
-`ctx.register_tool(...)` would mirror the OpenClaw plugin. Tracked as a fast-follow; the
-CLI + MCP + skill already make pairing "just work" in Hermes.
+# Running Visa agent setup in OpenClaw and Hermes
+
+`@visa/visa-cli-openclaw` is packaged for OpenClaw, but the skill is runtime-agnostic.
+OpenClaw, Hermes, and any runtime that can execute the `visa` CLI or mount its MCP server
+all drive the same setup operation: identity plus every requested rail, behind one owner
+approval.
+
+## Plugins are runtime-specific
+
+| Axis            | OpenClaw                                                  | Hermes                                                                                          |
+| --------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Language        | JavaScript/TypeScript                                     | Python                                                                                          |
+| Plugin manifest | `openclaw.plugin.json` + `definePluginEntry` (`index.ts`) | `~/.hermes/plugins/<name>/plugin.yaml` + `__init__.py`, `ctx.register_tool(...)`                |
+| Config file     | `~/.openclaw/openclaw.json`                               | `~/.hermes/config.yaml`                                                                         |
+| Skills          | Markdown `SKILL.md`                                       | Markdown under `~/.hermes/skills/<name>/`                                                       |
+| MCP             | `mcp.servers.*`                                           | `mcp_servers.*`                                                                                 |
+| Migration       | —                                                         | `hermes claw migrate` imports skills, allowlists, compatible MCP servers, memory, and `SOUL.md` |
+
+The OpenClaw JavaScript tools do not load as a Hermes plugin. Portability comes from the
+Markdown skill, CLI, and MCP protocol instead.
+
+## One ceremony, two surfaces
+
+Both supported surfaces share the same local pending record and the same server-owned
+setup operation:
+
+1. Visa MCP server: `setup_start`, then `setup_status` until it reports done
+   (`setup_resume` / `setup_cancel` for the interrupted and abandoned cases).
+2. Raw CLI: `visa setup start "<name>" --rails card,wallet --format json`, then
+   `visa setup status --format json`.
+
+The start operation returns a review URL for the human. The browser receives only that
+URL. The runtime retains its private Ed25519 key and local claim material. Polling both
+resumes the same pending identity after an interruption and performs the runtime's own
+steps — a setup nothing polls is a setup that never finishes.
+
+Use `agentId` as the stable identity. `identityKeyJkt` identifies the currently bound
+Ed25519 public key and can change after key rotation. Only the rails named in the
+operation are configured; email, `.visa` names, and tap bindings remain separate
+follow-up configuration.
+
+The older `pair_agent_start` / `pair_agent_poll` and `enroll_agent` surfaces still exist
+for published clients, but they pair identity ALONE and cost the owner one further
+approval per rail. Do not use them to connect a new agent.
+
+## Install and mount
+
+Install the prerelease CLI, which provides both command names and the MCP server:
+
+```sh
+npm install -g @visa/cli@rc
+```
+
+There is no `visa mcp` subcommand. Run `visa-cli connect <runtime>` when supported, or
+configure `@visa/cli/dist/mcp-server/index.js` directly. Replace `<npm root -g>` below
+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`). Hermes passes a filtered platform-safe baseline
+(`PATH`, `HOME`, platform variables, and `XDG_*`) plus this server's `env:` map.
+Arbitrary gateway variables are excluded, so map `VISA_RC_CODE` explicitly. The
+placeholder keeps its value in `~/.hermes/.env` instead of `config.yaml`:
+
+```yaml
+mcp_servers:
+  visa-cli:
+    command: node
+    args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
+    env:
+      VISA_RC_CODE: ${VISA_RC_CODE}
+      # Optional overrides for a different state directory or toolchain:
+      # HOME: /home/<user>
+      # PATH: /usr/local/bin:/usr/bin:/bin
+```
+
+### Keep one local-state namespace
+
+The gateway shell and the Visa MCP subprocess must resolve the same `HOME` and
+`VISA_CLI_HOME`. Set that boundary before pairing and keep it stable. Changing
+`VISA_CLI_HOME` later also changes where paired identity and grant records are
+read; it is not a safe way to make an old contact file visible.
+
+For example, with `HOME=/opt/data/home` and no `VISA_CLI_HOME`, identity lives
+under `/opt/data/home/.visa-cli` and checkout contact under
+`/opt/data/home/.visa-mcp`. A profile at `/opt/data/.visa-mcp` belongs to a
+different state namespace. Do not scan, copy, or auto-adopt it: contact files
+contain owner PII. Save the profile explicitly through `checkout_profile` in
+the running MCP process, or run the CLI command with the exact same environment.
+`visa agent preflight --format json` reports the non-secret path and source it
+checked.
+
+## Runtime setup map
+
+| Runtime       | Setup surface                                                                                                                                                                                                    |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenClaw      | Install `@visa/visa-cli-openclaw` for the bundled skill. The plugin auto-mounts the Visa MCP server, which serves `setup_start` / `setup_status`.                                                                |
+| Hermes        | Run `visa-cli connect hermes`, install the skill with `visa agent skill --runtime hermes` (it resolves the per-profile dir), and use `setup_start`. `hermes claw migrate` can import an existing OpenClaw setup. |
+| Codex         | Run `visa agent skill --runtime codex`. It plants the skill under `~/.codex/skills/` and mounts the Visa MCP server into `~/.codex/config.toml` in the same step.                                                |
+| Other runtime | Put `visa` on `PATH`, mount the same MCP server if supported, or use the raw `visa setup start` and `visa setup status` commands as the universal fallback.                                                      |
+
+The skill itself can be installed with `visa agent skill`. Pass `--runtime <name>` or
+`--dir <path>` when auto-detection is not appropriate, then reload the runtime.
+
+## Optional Hermes wrapper
+
+A Hermes Python plugin may wrap the canonical raw CLI commands and register tools with
+`ctx.register_tool(...)`. It is optional: the MCP server and skill already expose the
+same operation and persisted local state without a second implementation.