@paybox-sh/sdk 0.8.5 → 2.0.0

package/README.md

@@ -3,11 +3,10 @@
 Typed Node SDK and `paybox` CLI for the PayBox agent API. It mirrors the MCP tool
 surface — `list_credentials`, `request_payment`, `claim_payment_credentials`,
 `request_wallet_sign`, `request_secret`, `request_swap`, `discover_services`,
-`pay_x402`, `use_service`, `get_portfolio`, `get_buy_link`,
-`request_account_change`, `get_request`, and read-only plugin tools (`world_*`,
-`hyperliquid_*`) — but talks to the REST API directly, with no MCP host and no
-signing iframe.
-Geofenced World money tools are MCP-only.
+`pay_x402`, `use_service`, `get_portfolio`, `get_buy_link`, `get_deposit_link`,
+`request_account_change`, `get_request`, and the generic plugin discovery,
+contract, and invocation flow. Core operations use the REST API; plugins use
+the same MCP tools as connector hosts, with no hardcoded per-plugin paths.
 
 Wallet signing is **non-custodial and runs in-process**: the SDK reuses the exact
 signing core from the wallet-sign iframe (`@paybox/mcp-app`), builds the chain
@@ -23,22 +22,22 @@ npx @paybox-sh/sdk login     # or use the CLI directly
 
 Driving this CLI from an agent? [`SKILL.md`](SKILL.md) ships in the package and
 describes the install and login flow as an agent skill: what the human has to do
-(approve wallets, paste one signing key), and what the agent should not do
-around it. Use the CLI on **Grok Bot**, **Grok Computer**, and any agent on a
+(approve wallets, confirm one code), and what the agent should not do
+around it. Use the CLI on **Muse**, **Grok Bot**, **Grok Computer**, and any agent on a
 computer with no connector screen — not the grok.com MCP connector path.
 
 ## CLI
 
 ```bash
-# Authenticate: OAuth in the browser (approve with a passkey), or store a key.
-# `paybox login` is a guided two-step: OAuth, then it opens the app to provision
-# a wallet signing key and prompts you to paste the `pbxk1.` token back.
-# The OAuth step is a device-code grant, so the browser that approves does not
-# have to be on the machine running the CLI.
-paybox login                              # device-code OAuth, then provision a key
-paybox login --no-provision               # OAuth only, skip the key step
+# Setup is two commands. `login` authenticates; `connect` pairs a signing key.
+# Pairing prints eight emoji and a link; you open the link and pick that same
+# code in PayBox. The key is generated locally and never leaves this machine,
+# so there is nothing to copy. Neither command needs a browser on the machine
+# running the CLI — approve both from a phone if you like.
+paybox login                              # device-code OAuth (browser + passkey)
 paybox login --key pbx_live_…             # personal API key instead (no OAuth)
-PAYBOX_SIGNING_KEY=pbxk1.… paybox login   # supply the signing key non-interactively
+paybox connect                            # pair a signing key
+PAYBOX_SIGNING_KEY=pbxk1.… paybox …       # headless: reuse an already-paired key
 
 paybox credentials                        # list usable credentials
 # `--credential <id>` below is the `credential.id` from that list, not the wallet name.
@@ -60,8 +59,9 @@ paybox account-change --note "need a wallet grant"  # manage_url for the user to
 paybox request <request_id> --wait        # poll a pending request
 
 # Plugins (enable them in the paybox app first)
-paybox world markets --status active      # browse prediction markets
-paybox hyperliquid markets                # spot discovery
+paybox plugins list --status enabled
+paybox plugins contract paybox://plugins/world
+paybox plugins use world world_get_events --input '{"status":"active"}'
 
 paybox version                            # installed version (+ update check)
 paybox update                             # update the global install to latest
@@ -77,7 +77,7 @@ its own binary). For project installs use `pnpm up`/`pnpm rm`, or `npx
 @paybox-sh/sdk@latest` to always run the latest without installing.
 
 `sign`, `swap`, `pay-x402`, and `use-service` can complete in-process with a
-configured `pbxk1.` key. World buy/sell/redeem are MCP-only.
+configured `pbxk1.` key. Plugin calls return the raw MCP tool result.
 
 For a Solana `swap` the SDK re-pins a fresh recent blockhash immediately before
 signing (parity with the signing window — the quote-time blockhash expires
@@ -85,7 +85,7 @@ within ~60–90s, often before signing), so a swap that dwells for approval no
 longer broadcasts as `BlockhashNotFound`. EVM swaps are unaffected.
 
 `pay-x402` is header mode — on success `output.value.x_payment` is the `X-PAYMENT`
-header to replay on the original request. `use-service` is gateway mode — paybox
+header to replay on the original request. `use-service` is gateway mode — PayBox
 makes the paid call for you and returns the resource's reply on
 `output.value.response`. Pass `--accepts` from the resource's own 402 (start from
 the curated Bazaar set with `paybox discover`).
@@ -122,6 +122,15 @@ const services = await paybox.discoverServices("weather api");
 const rawServices = await paybox.discoverServices("weather api", { raw: true }); // debug only
 const paid = await paybox.useService({ credentialId: walletId, url: services[0].resource });
 // paid.response.output.value.response holds the resource's reply
+
+const plugins = await paybox.discoverPlugins({ status: "enabled" });
+const selected = plugins.plugins.find((plugin) => plugin.id === "aave");
+const contract = await paybox.getPluginContract(selected!.contract_uri!);
+const result = await paybox.usePlugin({
+  pluginId: contract.contract.id,
+  toolId: contract.contract.tools[0].id,
+  input: {},
+});
 ```
 
 ## Configuration
@@ -141,6 +150,37 @@ macOS/Linux). On Windows the POSIX mode bits don't restrict access — the file
 is not access-protected there, so prefer `PAYBOX_API_KEY` / `PAYBOX_SIGNING_KEY`
 env vars on shared Windows machines.
 
+## Headless and CI
+
+Pairing needs a human to confirm the code, so CI cannot pair at run time. Pair
+once ahead of time **as the identity CI will use**, then carry both secrets:
+
+```bash
+# On a laptop. The pbx_live_ key comes from the PayBox app (Agents → create an
+# agent, pick its wallets); it is shown once.
+paybox login --key pbx_live_…      # authenticate as the client CI will use
+paybox connect                     # pick the code; approve on any device
+grep signingKey ~/.config/paybox/config.json
+```
+
+```yaml
+env:
+  PAYBOX_API_KEY: ${{ secrets.PAYBOX_API_KEY }}          # pbx_live_…
+  PAYBOX_SIGNING_KEY: ${{ secrets.PAYBOX_SIGNING_KEY }}  # pbxk1.…
+```
+
+`PayboxClient.fromConfig()` reads both from the environment, so the runner needs
+no config file, no browser, and no TTY.
+
+Those two secrets are a **matched pair**: a signer is bound to the client that
+paired it. Present a `pbxk1.` to a different client — including the throwaway
+client that a plain `paybox login` registers — and signing fails with `agent
+signer belongs to another client`. It reads like a revocation but means you
+paired under a different identity. Rotating the API key mints a new client, so
+re-pair after rotation — `paybox login` drops the stored key when it does this
+and tells you to run `paybox connect`, rather than leaving one that cannot
+sign.
+
 ## Develop
 
 `pnpm-lock.yaml` also contains the `../mcp-app` importer because this SDK

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: PayBox CLI setup
-version: 0.8.8
+version: 0.8.13
 description: >-
   Install and log in to the PayBox CLI (@paybox-sh/sdk) so an agent can pay,
   sign, and hold wallet, card, and secret credentials on the user's behalf. Use
@@ -12,11 +12,11 @@ description: >-
 
 The human and agent guide is `https://docs.paybox.sh` (start at
 getting-started and connect/mcp). This file is only the CLI film. Grok
-(grok.com) and Grok Bots are different hosts; do not treat one as the other.
+(grok.com), Grok Bots, and Muse are different hosts; do not treat one as another.
 
 ## Which host
 
-- **Grok Bot, Grok Computer, or any agent on a computer or VM with no connector
+- **Muse, Grok Bot, Grok Computer, or any agent on a computer or VM with no connector
   screen:** this skill is the path. Install and run `paybox login` on that
   machine. Do not send the user to grok.com/connectors and do not paste the MCP
   URL as setup.
@@ -24,12 +24,67 @@ getting-started and connect/mcp). This file is only the CLI film. Grok
   grok.com/connectors. Do not run this CLI install flow unless they explicitly
   want the CLI on a separate machine.
 
-When the user says "install PayBox" and you are Grok Bot or running on a
+When the user says "install PayBox" and you are Muse, Grok Bot, or running on a
 computer, start here immediately.
 
 The user asks to install PayBox. Two things need them: they approve wallet
-access with a passkey, and they paste one signing key. Everything else is yours,
-and they should not see it happen.
+access with a passkey, and they confirm one emoji code. Everything else is
+yours, and they should not see it happen.
+
+No secret ever passes through chat. The signing key is generated on the machine
+running the CLI and stays there; what you show the user is an eight-emoji code
+derived from its public half, which is safe to put in a transcript.
+
+## Muse
+
+On Muse this section wins over the Grok Bot phone-app rules below.
+Prod is `https://api.paybox.sh` / `https://app.paybox.sh`. Stay quiet until they
+say install PayBox / install paybox / Install Paybox. English. Few words. No
+secret dumps. No invented click paths.
+
+Do not send them to Settings → Connectors → Add custom, or to paste an MCP URL.
+Muse **Manage Connectors** (OpenAI, Anthropic, and the rest) is not where
+PayBox is added. Do not run passkey inside Muse. Muse is a chat host, not a
+Grok Bot computer VM. Do not ask for done, listo, or a screenshot. Do not
+fake ready.
+Never wipe `~/.config/paybox`.
+
+Two chat controls, then Welcome. Muse does **not** open those links the way
+Grok Bot does. Every link you send must tell them to tap it. A bare
+markdown pill with no "tap this" line is a failed take.
+
+1. Run device-code login (`paybox login`, or the PayBox capability Authorize
+   flow if this host already has it). The moment you have
+   `verification_uri_complete` and `user_code`, send **one** message:
+   **Tap [Authorize wallets](verification_uri_complete) on your phone
+   browser.** plus `Code: XXXX-XXXX`. One short extra line only if the
+   PayBox **Capability** screen shows **Authorize**: "Or tap Authorize on
+   Paybox under Capabilities." Never mention Add custom. Phone browser
+   (Safari or Chrome), not the native PayBox app and not inside Muse.
+   You do not open the URL. Poll until OAuth is live. Do not end the
+   turn while polling.
+2. When OAuth is live and the signing key is missing, run `paybox connect`
+   and send **one** message: **Tap [Connect signing key](url) on your phone
+   browser and pick this code**, plus the eight emoji the CLI printed. Use
+   the URL and the code exactly as `connect` printed them — do not build
+   the URL yourself. Then poll; `connect` returns once they pick it. Do not
+   ask for the key, and do not ask them to come back to chat.
+
+Ready only when OAuth or an API key is live **and** `canSign` is true. Then
+Welcome to PayBox with two buttons: **Swap 20 USDC to SOL**, **Pay a Solana
+briefing**. Do the one they tap. Stop when that job is done.
+
+If token exchange fails (`refresh_rejected` / egress): one stop line, "Host
+blocks PayBox token exchange. Install NOT complete." Do not offer Settings →
+Add custom as a workaround. If a PayBox capability with **Authorize** is
+visible, point only there. If MCP is already Connected under Manage your MCP
+servers, use that grant — still no Add custom story.
+
+Install the CLI only when this host still needs device-code:
+`npm install -g @paybox-sh/sdk@latest`, then `paybox --json version` (2.0.0+;
+older builds pair no signing key and ask for a paste instead).
+Fresh `PAYBOX_CONFIG_DIR`. Unset `PAYBOX_API_URL` `PAYBOX_API_KEY`
+`PAYBOX_SIGNING_KEY` `PAYBOX_ACCESS_TOKEN`.
 
 ## Install
 
@@ -90,9 +145,9 @@ Send that link even though the CLI also tries to open a browser. When the CLI
 is not on the user's machine, that local open is useless or invisible, and your
 message is the only way they reach the page.
 
-On a phone, Authorize wallets should open the PayBox app. That is the
-correct path. After they tap Connect CLI, the app opens Generate a signing
-key by itself. Do not tell them to come back to chat first.
+On Grok Bot, Authorize wallets should open the PayBox app. That is the
+correct path there. Do not tell them to come back to chat first. On Muse
+use the Muse section: phone browser, not the native app, not inside Muse.
 
 Then wait. The poll is the continue signal. Do not ask the user to type `done`,
 confirm, or send a screenshot, and do not end your turn while login is running.
@@ -101,43 +156,47 @@ one rather than reusing the old link.
 
 A `clientId` already on disk when this `paybox login` starts is the previous
 client. Ignore it. `login` registers a new client and only writes `oauth` after
-the poll succeeds. If you restart login for a fresh code, drop any signing-key
-link you already sent.
-
-After **this** login writes `oauth` (or prints `/agent-key?client_id=`), send
-the signing-key controls. Prefer that printed URL. If stderr never printed it
-but this run did save `oauth`, build
-`https://app.paybox.sh/agent-key?client_id=<cid>` from the `cid` claim on the
-access token this login just wrote. Never use `oauth.clientId`, a `pbx-oauth-`
-id, or a `clientId` that was already in `config.json` when the command started.
-Those are the OAuth registration, not the vault agent. `/agent-key` will say
-the agent was not found. Do not wait for a dropped Windows executor to
-reconnect before they see the box. Merge the key when the machine is back;
-showing the box does not need that machine.
-
-### Step 2 — Paste the signing key
-
-The moment **this** login has an agent-key URL (stderr, or `cid` from the oauth
-it just saved), put **Generate Signing Key** in chat as that link plus a
-**masked input** for the `pbxk1.` value, in the same turn. Seconds after they
-finish Authorize wallets, not minutes. That chat link must use the JWT `cid`
-and must open the PayBox app on the first tap, the same way Authorize wallets
-does. Do not `Start-Process`, `open`, `rundll32`, or `xdg-open` the authorize,
-connect, or agent-key URL yourself. Write what they give you to login's
-prompt stdin when that prompt is alive. If login is wedged after this oauth
-write, keep the box on screen and merge `signingKey` when the host can write
-files again.
-
-Pass it through the prompt, or set `PAYBOX_SIGNING_KEY` before running `login`
-when nothing is attached to stdin. Never pass it as `login --signing-key <value>`
-on the command line: an argument lands in shell history and is visible to anyone
-who can list processes.
-
-Do not ask the user to click a signing-key URL that never arrived. Do not open
-the page twice. Do not hold the box until login narrates success.
-
-Wallet signing is non-custodial: the key stays on the user's machine and PayBox
-never holds it. Never print, log, or echo it.
+the poll succeeds. If you restart login for a fresh code, drop any pairing link
+and code you already sent — a pairing is bound to the client that started it.
+
+### Step 2 — Confirm the pairing code
+
+Run `paybox connect` as soon as `login` returns — it does not pair for you.
+Run it again any time the key is missing later. The CLI prints eight emoji and
+a link to stderr:
+
+```
+  🍕 🎸 🦊 🚀 🌵 🥁 🐙 🪐
+Open this on any device and pick that code to connect this machine:
+  https://app.paybox.sh/agent-key?client_id=…&pairing_id=…
+```
+
+Relay both in one message, seconds after they finish Authorize wallets, not
+minutes: the link plus that exact code. PayBox shows three codes and they pick
+yours. Use the printed URL verbatim — it carries the `pairing_id`, and the
+`client_id` comes from the server, so there is no id for you to choose. On Grok
+Bot the link must open the PayBox app on the first tap, the same way Authorize
+wallets does. On Muse tell them to tap it in the phone browser.
+
+Do not `Start-Process`, `open`, `rundll32`, or `xdg-open` the authorize,
+connect, or agent-key URL yourself. Then wait — `connect` polls and returns on
+its own. Do not ask the user to type `done`, do not send the link twice, and do
+not re-run `connect` while one is still polling; a second pairing invalidates
+the code they are looking at.
+
+Never ask the user for the key itself, and never accept one if they offer it —
+there is no step in this flow that needs it. The emoji code is safe to send;
+a `pbxk1.` value is not. Wallet signing is non-custodial: the key is generated
+on the user's machine and stays there, and PayBox never holds it.
+
+`PAYBOX_SIGNING_KEY` exists for headless runs that reuse a key paired earlier
+on another machine. It is not part of this flow, and there is no flag that
+takes a key on the command line — an argument would land in shell history and
+be visible to anyone who can list processes.
+
+`login` clears any stored signing key, because it registers a new client and a
+key paired to the previous one cannot sign. That is why pairing follows login
+rather than preceding it.
 
 ### Step 3 — Confirm
 
@@ -145,17 +204,22 @@ never holds it. Never print, log, or echo it.
 paybox --json whoami
 ```
 
-`canSign` must be `true`. If it is `false` the key did not save; redo step 2
-rather than continuing, because signing and swaps will fail without it.
+`canSign` must be `true`. If it is `false` the pairing did not complete; run
+`paybox connect` again for a fresh code rather than continuing, because signing
+and swaps will fail without it.
 
 ## What the user sees
 
 From the install request until `canSign` is `true`, exactly two messages, in
 this order:
 
-1. The **Authorize wallets** link plus the code.
-2. **Generate Signing Key** plus the masked `pbxk1.` field, as soon as
-   **this** login prints `/agent-key?client_id=` or writes a new `oauth`.
+1. The **Authorize wallets** link plus the code. On Muse, the line says
+   to tap that link on the phone browser. Grok Bot can omit that; it
+   opens the link itself.
+2. **Connect signing key** — the link `connect` printed, plus the eight
+   emoji, as soon as it prints them. Same on both hosts; there is no
+   input field and nothing for them to send back. Grok Bot opens the
+   link itself; on Muse tell them to tap it in the phone browser.
 
 Nothing else. No "Installing…", "Opening…", "Got it", no CLI version, package
 manager, config path, or request id, and no narration of a retry or fallback. If
@@ -232,24 +296,30 @@ catalog index. There may be tens or thousands.
    app, not a host Settings → Plugins screen. Ask them to turn on what
    they want to use, then say when they are back.
 
-2. Then call `discover_plugins` with `status` `enabled`, no `query`, and
-   a small `limit`. That page is what they have on, not the store. From
+2. Then run `paybox --json plugins list --status enabled --limit 10`. That page
+   is what they have on, not the store. From
    those plugins plus the portfolio, suggest a few concrete next moves
    (about six, not one row per plugin). Use each result's `name` and
    contract. Be specific: amounts, which wallet UUID, which market or
    vault from the contract. Mix two enabled plugins in one suggestion
    when that serves the same goal (for example fund or swap, then put
-   the result to work). If nothing is enabled, skip the suggestion list
-   and stay on the Plugins link.
-
-When they name a plugin or a job, search: `discover_plugins` with `query`
-set to what they asked, `status` `enabled` if they already turned it on,
-then page with `next_cursor` only while the current page has no match.
-Official plugin money uses MCP: `get_contract` with `contract_uri`
-unchanged → `use_plugin` with that contract's `plugin_id`, `tool_id`,
-and `input`. Do not invent a `paybox <plugin>` command; only use CLI
-groups that `paybox --help` already lists. Enabled plugin tools may also
-appear on `tools/list`. Plugin money always pauses for passkey.
+   the result to work). On Muse, Welcome is those two buttons first:
+   **Swap 20 USDC to SOL** on the granted Solana wallet, then **Pay a
+   Solana briefing**. Do not offer 0.001 SOL to USDC. If nothing is
+   enabled, skip the extra plugin list and stay on the Plugins link.
+
+When they name a plugin or a job, search with `paybox --json plugins list
+<query> --status enabled`, then page with `--cursor <next_cursor>` only while
+the current page has no match. For an official plugin, run `paybox --json
+plugins contract <contract_uri>` with the URI unchanged, then `paybox --json
+plugins use <plugin_id> <tool_id> --input <json>` with input matching that
+contract. Unofficial discovery results already contain their tool schemas;
+reuse `--invocation-id` only to retrieve the exact same ambiguous call. Plugin
+money always pauses for passkey.
+
+There are no per-plugin commands. `paybox world …` and `paybox hyperliquid …`
+were removed in 1.0.0; reach World and Hyperliquid through `paybox plugins`
+like every other plugin.
 
 If prod MCP (`https://api.paybox.sh/mcp`) is `unreachable` or `needsAuth` while
 `paybox --json whoami` still works, say that. Do not send the human to Settings.
@@ -258,10 +328,11 @@ Do not switch to staging. Do not report the dollar as sent.
 ## A setup that went wrong
 
 - The user had to prompt you after approving wallet access.
-- The key field waited minutes after they finished Authorize wallets.
-- The signing-key URL used `oauth.clientId`, a `pbx-oauth-` id, or a
-  `clientId` that was already on disk before this `paybox login` started.
-- The first Generate Signing Key tap said the agent was not in the vault.
+- The pairing code waited minutes after they finished Authorize wallets.
+- You rebuilt the pairing URL instead of relaying the one `connect` printed.
+- You sent a code from an earlier `connect` run, so none of the three
+  codes in PayBox matched.
+- You asked the user for the signing key, or accepted one they offered.
 - You asked the user to type `done`.
 - You opened either page twice.
 - You launched authorize, connect, or agent-key with `Start-Process` or an
@@ -272,3 +343,9 @@ Do not switch to staging. Do not report the dollar as sent.
   got its own window).
 - Setup chat contained anything besides those two messages.
 - A token, API key, or `pbxk1.` value reached the transcript.
+- On Muse you sent Settings → Connectors → Add custom, or Manage Connectors.
+- On Muse you opened passkey inside Muse.
+- On Muse Authorize wallets opened in the PayBox app or inside Muse.
+- On Muse you sent a link without telling them to tap it.
+- On Muse you faked ready before `canSign` was true.
+- On Muse token exchange failed and you invented an MCP Add custom path.