Superstables client v1.0.0: Agent plugin, seller tools and safer payments

Testnet by default. The mainnet gate is controlled by SUPERSTABLES_ALLOW_MAINNET; leave it unset for now. No mainnet chain is payable in this release, even with the switch enabled.

Upgrade and recovery

• Custom approval sites and RPCs: SUPERSTABLES_ALLOW_SITE is no longer read. Use superstables owner settings in the owner's terminal to allow another approval site or configure trusted RPCs. Environment variables alone no longer authorize replacements for owner actions or an unpaid verdict. See owner settings.
• Spend policies: run superstables policy show. Invalid rules now stop payments; caps require plain decimals with at most six decimal places. Empty files and omitted caps use the defaults: 0.05 USDC per payment and 1 USDC per day. Your account's ~/.superstables/policy.yaml also applies when another policy or client home is selected. Policy remains a software check, editable by a process running as you.
• Seller terms: use HTTPS, except for HTTP on this machine, including for SUPERSTABLES_INDEX_URL, SUPERSTABLES_CATALOGUE_URL and SUPERSTABLES_DEMO_SERVICE_URL. Retake older EVM quotes. EVM budget purchases now accept authorization lifetimes of 30–600 seconds. Tempo budget purchases refuse malformed, reused or overly long challenges and unsupported payment routes; custom RPCs must answer for the expected testnet.
• Local wallet and approval links: new local-wallet keys are encrypted by default; unattended initialization needs an explicit wallet init --no-passphrase. wallet encrypt converts an existing key; version 0.4.0 cannot read encrypted keys. Restart wallet serve after upgrading or encrypting: agents now use a private socket by default. Over SSH, use wallet serve --tcp, its printed forwarding command and SUPERSTABLES_WALLET_URL on the agent's side. Browser-wallet approvals now choose a port per client home: replace fixed 4412 forwarding with the port printed by pay. Capture the approval link when printed; status and new records no longer repeat it. See local-wallet setup.
• Files: unsafe home, payment-record, wallet and budget folders are refused before writes. Inspect the named folder before applying the reported permission fix. The local wallet's agent token must be a private regular file. doctor reports unreadable record lines, which are skipped and do not count toward the daily cap.
• Scripts and recovery: owner actions can return landed, exit 0, with final: false; check finality before granting again. An empty EVM or Solana budget is not proof of revocation. Revoke and recovery may need an owner transaction and gas even when the allowance reads zero. Unclear cancellations, unreadable journals and inconclusive chain reads answer unknown (exit 5): check the original operation before paying again. For an existing EVM or Solana key with no recorded owner, run budget setup --hosted to link first, then grant separately. Older Tempo journals are not repaired by upgrading. A paid Single purchase on superstables.com holds the next purchase until chain finality unless the owner stops waiting. See results and owner recovery.
• Stopped budget approvals: budget wait can resume recorded EVM setup, grant, revoke and fund-agent requests on superstables.com after their worker stops. It reuses the request and preserves payment evidence. Unresolved approvals remain unknown and block other owner commands on that chain. Agents must stop and ask the owner. An owner can give up a background approval with budget wait --id ID --abandon in their terminal: this frees the chain but neither cancels the request on the site nor undoes a transaction. Tempo and Solana do not resume this way. See approval recovery and replacement limits.
• SDK callers: pass amountAtomic, decimals and spentTodayAtomic to evaluatePolicy; a missing daily total now refuses a capped payment. Decimal inputs are deprecated. Keep Money.amount and Money.atomic consistent, pass token decimals to toAtomic and fromAtomic, and stop reading runner from SDK attempts and attempts --json. Handle SellerUnreachableError from detect() instead of TypeError when a seller cannot be reached. See SDK migration details.

Added

• Mainnet switch: SUPERSTABLES_ALLOW_MAINNET is the operator's switch for mainnet, off unless set. 1 or true turns it on. Unset, empty, 0 or false keep it off. Any other value, such as yes or TRUE, is an error that names the variable and refuses every mainnet. Every refusal of a mainnet in quote, pay and superstables budget names it. Agents never set it. The switch alone signs nothing: the chain must also be enabled in your signed owner settings and meet the chain gate's prerequisites. No mainnet chain is payable in this release, so the switch unlocks none yet. See what mainnet still needs.
• Budget key protection: EVM and Solana agent keys use files unless you opt into the OS keychain on macOS or Linux with budget setup --key-store os-keychain. budget rotate --rail evm or --rail solana retires the old address locally, obtains final revocation, handles open purchases and returns recoverable funds before connecting a replacement. Start with --plan; grant the new key separately. Revocation ends the old key's spending permission, not its control of funds already withdrawn. Keychain storage does not protect against code running as you while it is unlocked. See key replacement.
• Agent plugin: the plugin package includes one Superstables skill for using the connector and CLI, including Budgets. It configures remote MCP tools at https://mcp.superstables.com for finding services, requesting single purchases and reading their status, plus the budget tools described below. An account member approves and signs single purchases on superstables.com. The plugin ships through GitHub, separately from npm.
• Budget requests signed on your machine, sent through the connector: on EVM chains with approvals on superstables.com, budget setup --hosted, grant, revoke and fund-agent now support --sign-only. The agent key signs the approval request for the connector to send unchanged within five minutes. budget wait --site-request checks the agent and signed terms before adopting the request and following its outcome. If the signature expires before adoption, the outcome remains unknown: the connector may already have sent it. See signed requests and recovery.
• Budget requests from the agent plugin: when the signed-in connector offers submit_budget_request, the skill routes EVM budget setup and grant requests for approval on superstables.com through it. The agent signs on your machine with --sign-only; the owner approves on superstables.com, and budget wait --site-request follows the outcome. For revocation, request_budget_revoke returns the owner's link to revoke on superstables.com. Without the required connector tool, the CLI uses the direct path.
• Signed settings: superstables owner settings sign records your wallet's signature over settings, policy and retired keys. For approvals using that wallet, a changed policy is refused until signed again. Approval pages show more of the seller, policy, chain and raw wallet amounts; the local wallet adds an explicit payment confirmation and wallet open to reopen its page.
• Seller referrals: eligible budget buy and pay requests carry referral headers tied to the signed payment. EVM EIP-3009 payments carry the referral in their nonce; Solana and Tempo use a memo. EVM Permit2 payments and seller-fixed Solana memos carry no referral token. Receipts record attribution, never the token. SUPERSTABLES_REFERRALS=off disables referrals for new payments and budget operations; retries under an existing --op keep their recorded attribution. See referral formats and limits.
• Seller integration: @superstables/client/seller reads referral headers and verifies tokens against the site's published keys. A valid token alone does not prove a purchase. demo-service can publish a listing claim challenge when SUPERSTABLES_CLAIM_CHALLENGE is set; it is off by default. See seller referrals.
• Seller credit: superstables seller credit shows prepaid credit, recent top-ups and credit entries. seller top-up <amount> adds 1–1000 USDC on Base Sepolia through the usual signer, spend policy and owner approval. It checks the top-up and payment terms before signing. Another top-up is blocked while an earlier one remains unresolved: check seller credit and status <attempt> before proceeding. The seller API key goes only to the trusted site, is not printed or saved, and responses echoing it are discarded. Other sites, including staging and this machine, need owner permission. See credit, top-up recovery and site settings.
• Budget auto recovery: with your recovery policy on superstables.com enabled, an eligible EVM or Solana budget purchase can read payment terms up to three times, then switch to the same seller on another chain. The client checks the allowance, --max and the site-supplied price and margin. It does not ask for approval of each switch or send the request to a different seller. Without recovery, terms are read once. Orders recorded by earlier development builds remain unknown; check their recorded transactions on chain before doing anything else.

Changed and fixed

• Budget recovery waits for final evidence before returning a price that could still settle. EVM purchases sharing an agent key and chain take turns on this machine: a second budget buy waits up to 10 minutes, then refuses with exit 3 and nothing signed if still blocked. Arc Testnet blocks new purchases while an earlier price remains unresolved. Tempo prechecks include owner-paid network fees when they can be estimated.
• Default RPCs for budget approvals and recovery on your machine now support finalized-state reads on Arbitrum Sepolia and Robinhood Chain Testnet. Base Sepolia budget setup and grants tolerate larger gaps between RPCs' finalized blocks. Missing or conflicting required evidence still blocks confirmation. See RPC rules and exceptions.
• Retrying a budget setup on superstables.com can now replace an expired link once the site confirms expiry and there is no evidence of a send. The existing agent key is kept.
• The chain check after a payment retries briefly when an endpoint lags, without paying again. A differing block hash is reported as removed only once finality reaches that block; inconclusive reads remain unchecked.
• Spend policies use exact integer comparisons, including in the local wallet, which rechecks policy when approving. Stopped unsigned payments release reservations only after the process is proven gone. Discovery explains hidden listings, owner handoffs include expiry and account guidance, and account refusals direct owners to a wallet linked to their account.
• Payment records are flushed before submission; approval pages, seller responses, journals and external text receive stricter checks. Zod is updated to 4.6.6, including x402's payment validation, in installs from npm and the skill zip; installs from git still use x402's zod 3. The npm package locks its production dependencies with npm-shrinkwrap.json. Builds include software bills of materials and a way to compare release artifacts with their source; npm provenance is not included. See build verification.
• Stopped or unreadable approvals: when budget wait restarts an approval, only the newest restart can record its result; an existing result is preserved. Refused flags for existing approvals and unreadable records return unknown (exit 5, not final). Records lost or damaged during budget wait, including --abandon, are left as found. Check superstables.com and wallet activity before retrying. Do not start another purchase for that request.