@paybox-sh/sdk 0.8.2 → 0.8.5

package/README.md

@@ -24,7 +24,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 **Grok Bot**, **Grok Computer**, and any agent on a
+computer with no connector screen — not the grok.com MCP connector path.
 
 ## CLI
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: PayBox CLI setup
-version: 0.8.3
+version: 0.8.8
 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
@@ -14,6 +14,19 @@ 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.
 
+## Which host
+
+- **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 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.
@@ -60,8 +73,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 +90,51 @@ 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 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.
 
 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`
+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 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.
@@ -116,7 +154,8 @@ 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.
+2. **Generate Signing Key** plus the masked `pbxk1.` field, as soon as
+   **this** login prints `/agent-key?client_id=` or writes a new `oauth`.
 
 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 +171,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
@@ -175,8 +258,17 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybox-sh/sdk",
-  "version": "0.8.2",
+  "version": "0.8.5",
   "type": "module",
   "description": "Typed Node SDK + `paybox` CLI for the PayBox agent API. Mirrors the MCP tool surface (list_credentials, request_payment, request_wallet_sign, request_secret, request_swap, get_portfolio, verify_solana_balance, get_request) over REST, with in-process non-custodial wallet signing.",
   "license": "Apache-2.0",