@paybox-sh/sdk 2.1.0 → 2.3.0

package/README.md

@@ -30,11 +30,11 @@ computer with no connector screen — not the grok.com MCP connector path.
 
 ```bash
 # 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. Add --no-open to
-# either command to print the link without launching a browser.
+# Pairing prints a two-digit number and a link; you open the link and pick that
+# same number 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. Add --no-open
+# to either command to print the link without launching a browser.
 paybox login                              # device-code OAuth (browser + passkey)
 paybox login --key pbx_live_…             # personal API key instead (no OAuth)
 paybox connect                            # pair a signing key
@@ -146,6 +146,64 @@ const result = await paybox.usePlugin({
 });
 ```
 
+## Run and resume a plugin request
+
+`runPlugin` invokes a plugin once and drives its stored request. `resumeRequest`
+reads an existing request and does not invoke the plugin again. Signing follows
+validated Solana/EVM transaction capabilities and server-owned `refresh_before_sign`,
+not plugin names. `resumeRequest` also consumes stored `wallet_sign` transaction
+intents through the existing signer. Unknown formats, versioned plans and gasless
+prepared plans stop with `outcome: "unsupported"`. Public plugins also use
+`use_plugin`, with their installation ID as `plugin_id`; request completion does
+not by itself prove a purchase or broadcast. Use the plugin contract to select an
+enabled tool and construct its input.
+
+```ts
+import type { UsePluginArgs } from "@paybox-sh/sdk";
+
+async function runApprovedOperation(operation: UsePluginArgs) {
+  const execution = await paybox.runPlugin(operation, { timeoutMs: 60_000 });
+  if (execution.requestId) {
+    await saveRequestId(execution.requestId);
+  }
+  return execution;
+}
+
+const execution = await paybox.resumeRequest(savedRequestId, {
+  waitForApproval: true,
+  timeoutMs: 60_000,
+});
+```
+
+The example assumes application-owned storage through `saveRequestId` and
+`savedRequestId`. Keep the request ID so another process can resume after a pause.
+A paired signing key enables automatic signing. Set `autoSign: false` to stop
+before signing. The server still enforces wallet grants and approval requirements.
+
+| Outcome | Meaning |
+| --- | --- |
+| `terminal` | Check `response.status`: `success`, `denied`, or `error`. A signature alone is not success. |
+| `approval_required` | The user must approve through Paybox. Approval waiting is disabled by default. |
+| `signing_required` | Automatic signing is disabled or a signing key is unavailable. |
+| `unsupported` | The result or signing plan is outside the supported contract. |
+| `reconcile_required` | The client cannot confirm completion. Query the same request before further action. |
+| `deadline_exceeded` / `cancelled` | The client stopped. The server operation can still finish. |
+
+The default deadline is 300 seconds and includes network calls. Polling starts at
+2 seconds, doubles when the status is unchanged, and stops increasing at 30 seconds.
+A status change resets the interval. `intervalMs` sets the starting interval from
+1 to 30,000 milliseconds. `signal` accepts an `AbortSignal` for cancellation.
+
+Do not start concurrent drivers for the same request. After an uncertain result,
+use `getRequest` before an explicit resume. The driver does not automatically retry
+a signature submission or create a replacement request. If invocation stops before
+a request ID arrives, reconcile outside this driver before invoking the plugin again.
+
+`usePlugin` still returns the raw MCP result, including metadata. Use it for data
+tools and unsupported flows. The new methods do not change existing CLI commands.
+Funding requests stop with `outcome: "unsupported"`, `reason: "funding_required"`,
+and a non-signing `pending_funding` response. They never reopen or submit a plan.
+
 ## Configuration
 
 Resolution order: explicit constructor options → environment → stored config.
@@ -172,7 +230,7 @@ once ahead of time **as the identity CI will use**, then carry both secrets:
 # 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
+paybox connect                     # pick the number; approve on any device
 grep signingKey ~/.config/paybox/config.json
 ```
 
@@ -205,10 +263,13 @@ pnpm install
 pnpm typecheck
 pnpm build           # tsup → dist/ (ESM + types + paybox bin)
 
-# Refresh the generated tool types from a running server (the source of truth):
-PAYBOX_MCP_URL=http://127.0.0.1:8080/mcp PAYBOX_API_KEY=pbx_live_… pnpm gen
+# Refresh the generated tool types from the MCP tool contract:
+pnpm gen
 ```
 
-The argument and response types in `src/generated.ts` mirror the server's MCP
-tool schemas (`schemars`-derived) and `server/src/models.rs`. `pnpm gen` reads the
-live `list_tools` schemas so the client can't drift from the server contract.
+The argument types in `src/types.generated.ts` come from
+`artifacts/contracts/mcp-tools-v1.json`, the committed list of core MCP tools and
+their input schemas. CI fails when the tools change and the file does not, or
+when this file is not regenerated from it. Refresh it with
+`PAYBOX_UPDATE_CONTRACTS=1 cargo test --lib mcp_tool_contract_matches_core_tools`
+in `server/`. Response types in `src/types.ts` track `server/src/models.rs`.

package/SKILL.md

@@ -10,9 +10,8 @@ description: >-
 
 # PayBox CLI setup
 
-The human and agent guide is `https://docs.paybox.sh` (start at
-getting-started and connect/mcp). This skill covers CLI tasks and setup. Grok
-(grok.com), Grok Bots, and Muse are different hosts; do not treat one as another.
+This skill covers PayBox through the CLI. Grok (grok.com), Grok Bots, and Muse
+are different hosts; do not treat one as another.
 
 ## Start with the requested task
 
@@ -21,8 +20,8 @@ Keep the requested action, amount, asset, network, and recipient.
 Ask for missing details before a money operation.
 Selecting PayBox does not authorize spending, signing, funding, or changing grants.
 
-Use an existing PayBox connector when available. Otherwise follow **Which host**
-below. For CLI tasks, check the installed CLI and run `paybox --json whoami`.
+Follow **Which host** below first. For CLI tasks, check the installed CLI and
+run `paybox --json whoami`.
 This command reports local configuration. It does not verify remote access.
 The setup sections below apply only to the missing steps identified here.
 
@@ -48,22 +47,23 @@ incomplete and stop.
 ## Which host
 
 - **Muse, Grok Bot, Grok Computer, or any agent on a computer or VM with no connector
-  screen:** use the CLI on that machine. Check existing access before setup.
-  Do not send the user to grok.com/connectors and do not paste the MCP
-  URL as setup.
+  screen:** use only the CLI on that machine. Check existing access before
+  setup. Never use the MCP URL, a custom connector, a Client ID, or a host
+  secrets store, and never say PayBox is unavailable on this host.
 - **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.
+  want the CLI on a separate machine. Use an existing PayBox connector there
+  when available.
 
 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 on the PayBox page, and they confirm one emoji code. Everything else is
-yours.
+access on the PayBox page, and they confirm one two-digit number. Everything
+else is yours.
 
 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
+running the CLI and stays there; what you show the user is a two-digit number
 derived from its public half, which is safe to put in a transcript.
 
 ## Host capabilities
@@ -72,11 +72,11 @@ One setup flow applies on every host. A host changes only the capability values
 below. The flow never branches on a host name. Prod is `https://api.paybox.sh` /
 `https://app.paybox.sh`.
 
-| Host | `link_surface` | `renders_buttons` | `keeps_process` | `cli_allowed` |
-|---|---|---|---|---|
-| Muse | `phone_browser` | no | no | yes |
-| Grok Bot | `app` | yes | yes | yes |
-| Unknown host | `phone_browser` | no | no | yes until it refuses |
+| Host | `link_surface` | `renders_buttons` | `keeps_process` | `cli_allowed` | `group_login` |
+|---|---|---|---|---|---|
+| Muse | `phone_browser` | no | no | yes | yes until it refuses |
+| Grok Bot | `app` | yes | yes | yes | no |
+| Unknown host | `phone_browser` | no | no | yes until it refuses | yes until it refuses |
 
 For a host not listed, use the unknown-host row and correct a value only from
 observed behavior. A new host is one new row.
@@ -95,6 +95,9 @@ observed behavior. A new host is one new row.
 - `cli_allowed`: when the host refuses the CLI install, pairing, or signing,
   stop visibly. Say setup is not supported on this host. Do not retry, work
   around the host, or send the user to another path as a substitute.
+- `group_login`: when no and the request comes from a group chat, say in one
+  line to send "install PayBox" in the private chat with the bot. Do not start
+  login in the group.
 
 Every host: English unless the user writes otherwise. Few words. Never show a
 secret. Never wipe `~/.config/paybox`. Do not send the user to Settings →
@@ -169,23 +172,23 @@ If access works, skip login and complete only the missing setup step.
 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 to stderr as plain prose (not JSON), and polls until the user
-approves. Read the `Code:` line and the URL from that stderr. There is no
-`user_code` field to wait for. After the poll writes `oauth`, the CLI may print
-an `/agent-key?client_id=` URL. Do not wait for it if this run already saved
-`oauth`.
+approves. Read the URL from that stderr. The link already carries the code, so
+do not send the `Code:` line. There is no `user_code` field to wait for. After
+the poll writes `oauth`, the CLI may print an `/agent-key?client_id=` URL. Do
+not wait for it if this run already saved `oauth`.
 
 ### Step 1: Authorize wallets
 
-The moment login prints the verification URL and code, send **one** message:
+The moment login prints the verification URL, send **one** message:
 
 > **Welcome to PayBox.** Two quick steps:
-> 1. Tap [Connect CLI to PayBox](verification URL), choose the wallets to
->    share, and confirm. Code: `XXXX-XXXX`
-> 2. Next I will send a signing-key link to connect this machine.
+> 1. Tap [Connect CLI to PayBox](verification URL), choose your wallets, and
+>    tap **Connect with PayBox CLI**.
+> 2. Next I will send a link to connect your signing key.
 
 Use only the steps that are still missing. Say what the page asks the user to
-do: pick the wallets and use the connect button. Do not describe a passkey or
-code-entry step the page does not show. Apply `link_surface` from **Host
+do: pick the wallets and tap **Connect with PayBox CLI**. Do not describe a
+passkey or code-entry step the page does not show. Apply `link_surface` from **Host
 capabilities**. Then keep polling as `keeps_process` allows. Do not open the URL yourself.
 
 If the code expires before approval, run `paybox login --no-open` again for a
@@ -197,26 +200,27 @@ previous client. Ignore it.
 
 Skip this step for read-only tasks. For setup-only requests or tasks that need
 local signing, run `paybox connect --no-open` when `canSign` is false.
-Login does not pair for you. The CLI prints eight emoji and a link to stderr:
+Login does not pair for you. The CLI prints a two-digit number and a link to
+stderr:
 
 ```
-  🍕 🎸 🦊 🚀 🌵 🥁 🐙 🪐
-Open this on any device and pick that code to connect this machine:
+  47
+Open this on any device and pick that number to connect this machine:
   https://app.paybox.sh/agent-key?client_id=…&pairing_id=…
 ```
 
 Send **one** message seconds after Step 1 completes, titled **Connect your
-signing key**: the eight emoji exactly as printed, each with its name, and the
-printed link in the same message. Never reuse the sample emoji above. PayBox
-shows three codes and the user picks yours. Use the printed URL verbatim, since
-it carries the `pairing_id` and the `client_id` comes from the server.
+signing key**: the number exactly as printed and the printed link in the same
+message. Never reuse the sample number above. PayBox shows three numbers and the
+user picks yours. Use the printed URL verbatim, since it carries the
+`pairing_id` and the `client_id` comes from the server.
 
 Do not `Start-Process`, `open`, `rundll32`, or `xdg-open` any of these URLs
 yourself. `connect` polls and returns on its own. Do not send the link twice and
 do not re-run `connect` while one is polling: a second pairing invalidates the
-code on screen.
+number on screen.
 
-Never ask for the key itself and never accept one. The emoji code is safe to
+Never ask for the key itself and never accept one. The number is safe to
 send; a `pbxk1.` value is not. The key is generated on the machine running the
 CLI and PayBox never holds it. `PAYBOX_SIGNING_KEY` is only for headless runs
 that reuse a key paired elsewhere, and no flag takes a key, because an argument
@@ -243,11 +247,11 @@ host without evidence.
 
 When setup finishes:
 
-> **PayBox is connected.**
+> **PayBox is connected.** **$TOTAL** across N wallets.
 
-then a Token / Amount / USD table of the granted wallets (see **Once setup is
-done**), then the choices **Swap 20 USDC to SOL** and **Pay a Solana
-briefing**, as `renders_buttons` allows, plus a short "You can try" list.
+then the wallet table (see **Once setup is done**), then the choices **Swap 20
+USDC to SOL** and **Pay a Solana briefing**, as `renders_buttons` allows, plus
+a short "You can try" list.
 
 Secondary suggestions: Get a Solana briefing, Show my portfolio, See my enabled
 plugins. Check the granted wallets, funds, and enabled plugins before offering
@@ -258,13 +262,27 @@ fees, and keep the platform approval.
 ## Once setup is done
 
 For a setup-only request, show the granted wallets with `paybox --json credentials`.
-Then use `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 Token / Amount / USD
-table, never addresses or invented balances. The CLI cannot create wallets; it
-uses what the user granted during authorization. If the portfolio call fails
-after connection, report setup as complete and name that failure. Do not
-restart setup.
+Then run `paybox --json portfolio --address <wallet>` for every granted wallet.
+Every `--credential` takes the `credential.id` from that list; a wallet's name is
+not an id and the command will refuse it. Show one Wallet / Holdings / USD table
+with one row per wallet:
+
+| Wallet | Holdings | USD |
+|---|---|---|
+| main-solana | 1.30 SOL · 34.48 USDC | $175.53 |
+| main-evm (Base) | 28.47 USDC · 0.0008 ETH | $30.59 |
+
+- Sort by USD, highest first. `$TOTAL` is the sum of each `total_usd`.
+- Holdings: the top two tokens by USD, two decimals (four for SOL or ETH under 1).
+- Skip tokens with `dust: true` or no price. Never show addresses or invented
+  balances.
+- Merge wallets under $1 into one last row: "N small wallets".
+- If a portfolio call fails or `total_usd` is null, show "unavailable" in that
+  row.
+
+The CLI cannot create wallets; it uses what the user granted during
+authorization. If a portfolio call fails after connection, report setup as
+complete and name that failure. Do not restart setup.
 
 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
@@ -315,14 +333,32 @@ not treat Welcome as a catalog index.
    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.
+When they name a provider or a job that needs one (a Solana limit order,
+a liquidity-pool investment, or concert tickets), search both catalogs with
+`paybox --json plugins list <query>` and `paybox --json discover <query>`, even
+when the first catalog matches. Use concise task keywords; for "use Kamino",
+search both for Kamino. Keep only routes supporting the requested action and
+chain. Keep default source and status filters unless the user restricted them,
+so disabled official plugins remain visible. Follow available pagination before
+claiming a sole match; plugin pages use `--cursor <next_cursor>`.
+
+If multiple relevant routes remain, show provider names, plugin or service
+labels, supported actions, and enablement requirements, then ask which to use.
+If exactly one relevant route remains across both catalogs, state it and
+continue without another route-choice question: one matching Kamino plugin and
+no Kamino service means use the plugin. If neither matches, explain that and
+offer a useful next step. For a selected disabled plugin, share its `enable_url`,
+wait for enablement, and discover it again before invocation.
+
+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. For a service, follow its exact discovered contract through
+the supported service/payment flow. Continue the original task after selection;
+do not stop at a discovery summary. Ask for missing task details and keep all
+required approvals. Route selection does not authorize spending or signing.
+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`
@@ -337,9 +373,9 @@ Do not switch to staging. Do not report the dollar as sent.
 - The user had to prompt you after approving wallet access, and you did not
   resume the same attempt.
 - A browser opened before the user had the link.
-- The pairing code waited minutes after they finished Authorize wallets.
+- The pairing number 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, or sample emoji.
+- You sent a number from an earlier `connect` run, or the sample number.
 - You asked the user for the signing key, or accepted one they offered.
 - You sent a link twice, or re-ran `login` or `connect` while one was running.
 - You launched authorize, connect, or agent-key with a local open command.
@@ -349,6 +385,9 @@ Do not switch to staging. Do not report the dollar as sent.
 - You nudged a specialist after its last command was blocked.
 - You spawned more specialists than named jobs.
 - A token, API key, or `pbxk1.` value reached the transcript.
-- You sent Settings → Connectors → Add custom, or Manage Connectors.
+- You offered a custom connector, a Client ID, a host secrets store, Settings →
+  Connectors → Add custom, or Manage Connectors.
+- You told the user PayBox is unavailable on this host.
+- You started login in a group chat where `group_login` is no.
 - You claimed signing readiness before `canSign` was true.
 - A setup-only Welcome replaced or interrupted a task the user already asked for.