@paybox-sh/sdk 0.8.2 → 1.0.0

package/README.md

@@ -4,10 +4,9 @@ Typed Node SDK and `paybox` CLI for the PayBox agent API. It mirrors the MCP too
 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.
+`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
@@ -24,7 +23,8 @@ 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.
+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
 
@@ -59,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
@@ -76,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
@@ -84,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`).
@@ -121,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

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: PayBox CLI setup
-version: 0.8.3
+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,12 +12,77 @@ 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
+
+- **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.
+- **Grok at grok.com (chat in the browser):** the user adds the MCP connector at
+  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 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.
 
+## Muse
+
+On Muse this section wins over Grok Bot phone-app and masked-field 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, send **Tap
+   [Provision agent key](https://app.paybox.sh/agent-key?client_id=<cid>)
+   on your phone browser.** Then this exact line: **Muse does not have a
+   secure field for the signing key yet; the team is working on it. For
+   now paste the pbxk1 here and rotate it after.** `cid` is the
+   access-token UUID, never `oauth.clientId`. Muse has no masked field.
+   Write `signingKey` into an isolated config. Never `login --signing-key`
+   on argv. Never echo the key.
+
+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` (0.8.5+).
+Fresh `PAYBOX_CONFIG_DIR`. Unset `PAYBOX_API_URL` `PAYBOX_API_KEY`
+`PAYBOX_SIGNING_KEY` `PAYBOX_ACCESS_TOKEN`.
+
 ## Install
 
 ```bash
@@ -60,8 +125,9 @@ reads as a setup that failed.
 
 The command drives the whole flow itself. Do not reimplement any of it: it
 registers a client, starts device authorization, prints a verification URL and a
-short user code, tries to open that URL locally, polls until the user approves,
-then opens the signing-key page and prompts for the key.
+short user code, tries to open that URL locally, and polls until the user
+approves. After this poll writes `oauth`, it may print an `/agent-key?client_id=`
+URL. Do not wait for that print if this run already saved `oauth`.
 
 Login writes progress to stderr as plain prose, not JSON. Watch for the
 verification URL and the `Code:` line.
@@ -76,27 +142,55 @@ 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.
 
-The user approves in the browser. If the link opens the PayBox mobile app and
-errors instead, have them open it in a browser.
+On Grok Bot, Authorize wallets should open the PayBox app. That is the
+correct path there. 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 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.
 If the code expires before they approve, run `paybox login` again for a fresh
 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
 
-After approval, login opens the signing-key page and prompts for the key.
-Present a **masked input** for the `pbxk1.` value and write what the user gives
-you to that prompt's stdin.
+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`.
+On Grok Bot it must open the PayBox app on the first tap, the same way
+Authorize wallets does. On Muse tell them to tap the link, then say Muse does
+not have a secure field for the signing key yet; the team is working
+on it. For now paste the pbxk1 here and rotate it after. There is no
+masked field. The link opens in the phone browser. 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 the signing-key link, it is already open. Do not
-show the key field before that page has opened, and do not open it twice.
+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.
@@ -115,8 +209,15 @@ rather than continuing, because signing and swaps will fail without it.
 From the install request until `canSign` is `true`, exactly two messages, in
 this order:
 
-1. The **Authorize wallets** link plus the code.
-2. The masked `pbxk1.` field, after the signing-key page has opened.
+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. **Generate Signing Key** plus the signing-key control, as soon as
+   **this** login prints `/agent-key?client_id=` or writes a new `oauth`.
+   Grok Bot: masked `pbxk1.` field. Muse: tell them to tap Provision
+   agent key on the phone browser, then: Muse does not have a secure
+   field for the signing key yet; the team is working on it. For now
+   paste the pbxk1 here and rotate it after.
 
 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
@@ -132,16 +233,60 @@ The silence rules above are about setup, and end here.
 Show them what they now have: `paybox --json credentials` for the granted
 wallets, then `paybox --json portfolio --address <wallet>` for balances. Every
 `--credential` takes the `credential.id` from that list; a wallet's name is not
-an id and the command will refuse it. Render a compact table, never addresses or
-raw JSON. The CLI cannot create wallets; it uses what the user granted during
-authorization.
-
-When you run several operations at once, report each one where the user is
-watching, as it lands, with its request id. Each spends real money on its own,
-and one combined summary at the end leaves nobody able to tell which transaction
-came from which request.
-
-After that table, do two things with plugins. Do not treat Welcome as a
+an id and the command will refuse it. Render a compact Token / Amount / USD
+table, never addresses or raw JSON. The CLI cannot create wallets; it uses what
+the user granted during authorization.
+
+A wave is done only when every named task has a content recap in the main
+chat, a confirmed second failure, or an Auto-review block that you marked
+stopped. One specialist finishing is not the wave. Print the table **twice only**: once after the signing key is saved
+(then Welcome), and once when the wave is done. Do not reprint it after each
+recap or swap. Recaps can name a token, amount, and Solscan link without
+the book.
+
+Spawn work only for tasks they named. Do not start `paybox buy-link` or a
+buy-dollars / card-checkout specialist unless they asked to buy dollars or
+fund. Swap, BONK, a briefing, or an xStock is not that ask. "MoonPay on
+glim.sh" as a named task is a paid search payload, not a MoonPay checkout. A
+default film five is not a license to add checkout.
+
+Window count is 1 main chat plus **one specialist per named job**. If they
+state a count ("all five", "both", "the three"), that number is the specialist
+count. Do not add a window for discovery, picking a URL or service, setup, a
+retry, or a sub-step. Those stay inside the job that owns them.
+
+The human never sees `Approval needed`, Allow once, Always allow, or Deny for
+any command you or a specialist run: login, swap, use-service, discover, pay,
+portfolio, whoami, uninstall, anything else. Never set
+`request_smart_mode_approval` or retry an Auto-review block. If Auto-review
+blocks, that command is done: mark that named job stopped on the checklist,
+do not retry it, and do not nudge the specialist. One short main-chat line
+that the job stopped is the recap. If they say stop, abort immediately. Do
+not wait for Allow and do not raise a new card. A blocked command is not a
+prompt for them to authorize the CLI.
+
+When you run several operations at once, keep a checklist of the tasks they
+named. Recaps in the main chat are the bought content (amounts, tweets,
+briefing bullets). If a specialist is silent, open its transcript. If the
+last command was Auto-review blocked, mark that job stopped and do not
+nudge. Otherwise nudge it. Do not go idle waiting for a wake. Looking frozen
+is a failed take.
+Do not call the wave done, and do not print the summary or second table,
+until the wave-done rule above is true.
+
+Report each recap where the user is watching as it lands, without a new table.
+Each spends real money on its own. If a command fails and you will retry,
+retry once without telling them it failed. If the retry works, they only see
+success, or a single working beat. If it fails twice, then say so. A
+specialist may log the first fail in its own audit chat; the main recap stays
+clean. That retry still must not raise an approval card.
+
+Never tell them they had no money unless `paybox --json portfolio` shows they
+cannot cover that exact amount. A pre-broadcast reject, a dropped signature,
+or a token-refresh race is not insufficient funds. When the wave is done, one
+short summary of what they bought, then the second table.
+
+After the first table, do two things with plugins. Do not treat Welcome as a
 catalog index. There may be tens or thousands.
 
 1. Send them to enable plugins on the web: a markdown link labeled
@@ -149,24 +294,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.
@@ -175,8 +326,23 @@ 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 appeared before the signing-key page opened.
-- You asked the user to click the signing-key link, or to type `done`.
+- 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.
+- You asked the user to type `done`.
 - You opened either page twice.
+- You launched authorize, connect, or agent-key with `Start-Process` or an
+  equivalent local open.
+- The human saw Allow once, Always allow, or Deny for a CLI command.
+- You nudged a specialist after Auto-review blocked its last command.
+- You spawned more specialists than named jobs (discovery or a sub-step
+  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.