@bnbagent/studio-cli 0.0.6-alpha.1 → 0.0.6-alpha.3

package/skills/references/bnbagent-studio-selling-via-8183.md

@@ -106,6 +106,26 @@ quote_ttl_seconds = 300
 default_estimated_completion_seconds = 600
 ```
 
+An explicit `price = "0"` opts into free jobs when the selected ERC-8183
+contract supports zero-price funding. Keep `currency` configured because it
+remains part of the signed quote.
+
+Prefer the CLI so the zero-price choice is visible and remains a decimal
+string:
+
+```bash
+bag config set payments.erc8183.price 0
+bag env set ERC8183_COMMERCE_ADDRESS <commerce-address>
+bag env set ERC8183_ROUTER_ADDRESS <router-address>
+bag env set ERC8183_POLICY_ADDRESS <policy-address>
+bag doctor
+bag deploy prepare
+```
+
+Take all three addresses from the same compatible custom deployment.
+Doctor/prepare reject canonical or partial contract selection for FREE and
+announce `zero token escrow` only when the complete custom stack is selected.
+
 ## Stage 3 — LLM credit continuity (Pieverse projects only)
 
 If `[llm].provider = "pieverse-llm"`, the Agent's emitted

package/skills/references/bnbagent-studio-selling-via-b402.md

@@ -1,6 +1,6 @@
 ---
 name: bnbagent-studio-selling-via-b402
-description: When the user wants a bnbagent-studio agent to sell paid HTTP requests through the B402-backed x402 rail. Owns per-agent merchant onboarding, RSA key preparation, egress-IP allowlisting, sandbox/production separation, B402 environment setup, seller status checks, and activation by redeploy (managed platform or self-hosted AgentCore).
+description: When the user wants a bnbagent-studio agent to sell paid or FREE HTTP requests through the B402-backed x402 rail. Owns the explicit pricing choice and, for PAID mode, per-agent merchant onboarding, RSA key preparation, egress-IP allowlisting, sandbox/production separation, B402 environment setup, seller status checks, and activation by redeploy (managed platform or self-hosted AgentCore).
 ---
 
 > **Reference file** of the `bnbagent-studio` router skill — installed at
@@ -9,24 +9,46 @@ description: When the user wants a bnbagent-studio agent to sell paid HTTP reque
 
 # Sell via B402
 
-Use this playbook to activate the x402 seller rail for one agent. B402 merchant
-credentials are per agent and per environment. Never reuse a merchant record
-across agent wallets, or mix sandbox and production values.
+Use this playbook to activate the x402 seller rail for one agent. First choose
+PAID or FREE explicitly. B402 merchant credentials are per agent and per
+environment and are needed only for PAID. Never reuse a merchant record across
+agent wallets, or mix sandbox and production values.
 
 ## Preconditions
 
-- The agent wallet already exists. Its address will receive the U payments.
+- The agent wallet already exists. In PAID mode its address receives U.
 - The project targets the managed platform or self-hosted AgentCore
   (azure-foundry cannot activate the rail).
-- Managed platform only: a platform bearer token is available for reading the
+- PAID managed platform only: a platform bearer token is available for reading the
   platform egress IPs — the GitHub-login access token from
   `bag platform login`, or a `bnbk_…` API token minted once by
   `bag platform token`.
 - `[payments.x402_seller]` exists. If not, run
   `bag x402 sell init`.
 
-The application uses the **agent wallet address**, not a developer treasury,
-buyer wallet, or platform wallet.
+The PAID application uses the **agent wallet address**, not a developer
+treasury, buyer wallet, or platform wallet.
+
+## Choose PAID or FREE
+
+Use one of these explicit boundaries:
+
+```bash
+bag init <name> --rails b402 --b402-price 0
+bag x402 sell init --price-usd 0
+bag config set payments.x402_seller.price_usd 0
+```
+
+`"0"` means anonymous FREE passthrough. The runtime returns work directly and
+does not issue a 402 challenge, call B402 `/supported`/verify/settle, transfer
+U, or write an `x402_sell` settlement audit. B402 credentials are ignored and
+not synchronized. Run `bag x402 sell status`, `bag doctor`, and
+`bag deploy prepare`; all must label the route FREE.
+
+This is unrestricted public access. Confirm that intent before continuing.
+Managed platform still publishes the route through its gateway; self-hosted
+AgentCore still needs an envelope-v1 front; Azure Foundry remains unsupported.
+If FREE is the selected product, skip the merchant/RSA/IP sections below.
 
 ## Generate the agent's RSA material
 
@@ -130,7 +152,7 @@ Open the workspace `.studio/.env.local` in an editor and fill exactly four
 values:
 
 ```dotenv
-B402_BASE_URL=
+B402_BASE_URL=https://qacb.sdtaop.com
 B402_CLIENT_ID=
 B402_ACCESS_TOKEN=
 B402_PRIVATE_KEY_B64=
@@ -146,7 +168,7 @@ exactly one private-key form; do not set both.
 
 ## Verify and activate
 
-Check names and presence without exposing values:
+For PAID mode, check names and presence without exposing values:
 
 ```bash
 bag x402 sell status --no-probe
@@ -163,7 +185,7 @@ For a sandbox/trial agent, it must find exact/eip3009 U on `eip155:97`. For
 production it must find the mainnet environment expected by the project. A
 network mismatch is not safe to ignore.
 
-Run the deployment gate, then redeploy to activate the paid route:
+Run the deployment gate, then redeploy to activate the selected mode:
 
 ```bash
 bag deploy prepare
@@ -171,11 +193,12 @@ bag deploy --provider bnb   # managed platform
 bag deploy --provider aws   # self-hosted AgentCore
 ```
 
-On the managed platform the deploy summary must say `x402 rail is ACTIVE` and
-print the anonymous `/x402` URL. On a self-hosted AgentCore deploy it says
-`x402 rail is ACTIVE (self-hosted AgentCore)`: the rail runs in-process, but
-there is no anonymous URL — operate your own HTTP front that relays
-envelope-v1 JSON over SigV4-signed `InvokeAgentRuntime` calls (see
+On the managed platform the deploy summary must say `x402 rail is ACTIVE` (or
+`ACTIVE in FREE mode`) and print the anonymous `/x402` URL. On a self-hosted
+AgentCore deploy it says `x402 rail is ACTIVE (self-hosted AgentCore)` or
+`ACTIVE in FREE mode (self-hosted AgentCore)`: the rail runs in-process, but
+there is no anonymous URL — operate your own HTTP front that relays envelope-v1
+JSON over SigV4-signed `InvokeAgentRuntime` calls (see
 `docs/guides/x402-selling.md`, "Self-hosted AgentCore access"). A dormant or
 forced-dormant summary means the rail was not activated; fix the named
 credential, runtime, network, or tunnel condition and redeploy.
@@ -190,5 +213,6 @@ credential, runtime, network, or tunnel condition and redeploy.
   does not trigger an automatic refund.
 - The rail activates on AgentCore targets only (managed platform or
   self-hosted); azure-foundry stays forced dormant.
-- The payout wallet must be `wallet.kind` `evm-local` or `twak`; other kinds
-  (including Altana) are rejected at init, `sell init`, and readiness.
+- PAID payout wallets must use `wallet.kind` `evm-local` or `twak`; FREE has
+  no payout and does not apply this B402-specific allowlist.
+- Never describe FREE as a zero-value B402 settlement. It bypasses B402.

package/skills/references/bnbagent-studio-use-aws-agentcore.md

@@ -197,8 +197,9 @@ bag deploy destroy --provider aws --execute # delegated teardown (add --purge)
 ## Reference
 
 - b402/x402 selling on self-hosted AgentCore: the rail activates in-process
-  when the B402 credentials are set, but there is no anonymous URL — operate
-  your own HTTP front that relays envelope-v1 over `InvokeAgentRuntime`. See
+  with complete B402 credentials for PAID, or without them when explicit zero
+  selects FREE. There is no anonymous URL — operate your own HTTP front that
+  relays envelope-v1 over `InvokeAgentRuntime`. See
   `bnbagent-studio-selling-via-b402` and `docs/guides/x402-selling.md`.
 - `bag deploy --help` / `bag deploy <command> --help` (authoritative for commands + flags)
 - `agentcore/agentcore.json` — name (resource naming continuity), protocol, authorizer, envVars

package/skills/references/bnbagent-studio-use-azure-foundry.md

@@ -7,7 +7,7 @@ description: When the user wants to deploy or operate an A2A bnbagent-studio pro
 
 # bnbagent-studio-use-azure-foundry
 
-> **Preview.** Azure Foundry support is fully wired and listed in the `--runtime` menu. The most recent end-to-end live verification predates the TypeScript rewrite — treat your first deploy as a verification run.
+> **Preview — not advertised in this release.** Azure Foundry support is fully wired but hidden from the `--runtime` menu and the deploy provider menu; these steps still work if you select `azure-foundry` / `--provider azure` explicitly. The most recent end-to-end live verification predates the TypeScript rewrite — treat your first deploy as a verification run.
 
 Procedure for deploying and operating the seller Agent on **Azure AI
 Foundry Hosted Agents** (`[stack].runtime = "azure-foundry"`). ALL cloud

package/skills/references/bnbagent-studio-use-bnb-trial.md

@@ -13,7 +13,7 @@ keep `bsc-testnet`, and explain that the runtime signing material is transmitted
 to the operator's managed secret store for the trial. Never use a mainnet key.
 
 All auth and cloud lifecycle work must cross the pinned
-`@bnbagent/deploy-cli@0.4.14` boundary. Do not call AWS/Azure CLIs or platform
+`@bnbagent/deploy-cli@0.4.14` boundary. Do not call the AWS CLI or platform
 REST routes directly.
 
 ## Select and authenticate
@@ -35,7 +35,7 @@ Before offering BNB, inspect the trial result:
 - `available`: selectable; explain that the 48h clock starts on first success.
 - `active`: selectable; show remaining time and expiry immediately.
 - `expired`: show the row and expiry, but mark it unavailable and do not select
-  it. AWS/Azure remain independently available when compatible with the
+  it. AWS remains independently available when compatible with the
   project scaffold.
 - unknown/auth required: explain that eligibility cannot be confirmed until
   login; the delegated deploy rechecks before building.

package/skills/references/bnbagent-studio-using-altana-wallet.md

@@ -58,10 +58,11 @@ x402 buying remains separate and exact-bounded:
 bag wallet session x402-setup --allowance-u <U> --yes
 ```
 
-Altana cannot be the b402 **seller** payout wallet (the rail allows
-`evm-local` and `twak` only); init, `bag x402 sell init`, and deploy
-readiness reject the combination. Only the outbound buying authority above
-is available.
+Altana cannot be the b402 **seller** payout wallet for a positive price (paid
+mode allows `evm-local` and `twak` only); init, `bag x402 sell init`, and
+deploy readiness reject that paid combination. Explicit
+`price_usd = "0"` is allowed because FREE passthrough performs no payout and
+bypasses B402. The outbound buying authority above remains a separate feature.
 
 For troubleshooting, run `bag doctor` and `bag wallet session status`. Do not
 print, parse, or copy the `signer` portion of the serialized session, and never

package/skills/references/bnbagent-studio-using-twak-wallet.md

@@ -173,11 +173,11 @@ Two assets, two different rules:
   settles), so topping up burns no BNB. A twak wallet is also a supported
   b402 **seller** payout wallet (`bag init --wallet-kind twak --rails b402`);
   receiving needs no signature or gas either.
-- **BNB (gas)** — **testnet: none needed; mainnet: a little for ERC-8183.**
-  Testnet: the SDK forwards MegaFuel's testnet paymaster (`--paymaster-url`,
-  twak >= 0.20.0), so x402 topups (already gasless) plus **all** 8004/8183
-  writes are sponsored — a little tBNB (~0.007) is only a fallback in case
-  sponsorship declines a tx. Mainnet: x402 stays gasless and `bag 8004
+- **BNB (gas)** — **testnet canonical contracts normally use sponsorship;
+  mainnet needs a little for ERC-8183.** Testnet: the SDK forwards MegaFuel's
+  testnet paymaster (`--paymaster-url`, twak >= 0.20.0). Sponsorship still
+  depends on the paymaster policy covering the target contract and method;
+  keep a little tBNB (~0.007) as fallback. Mainnet: x402 stays gasless and `bag 8004
   register` is gas-sponsored by twak internally (Trust gateway — studio
   passes no paymaster flag), but **`8183 settle` / `fund` self-pay gas**, so
   keep ~0.007 BNB on the wallet for them.
@@ -203,8 +203,8 @@ spending limit nothing can bypass. Studio's daily caps
 (persisted to `.studio/spend-ledger.json`), best-effort in the deployed
 runtime (in-memory, resets on cold start).
 
-Testnet faucet: https://www.bnbchain.org/en/testnet-faucet (tBNB, fallback only).
-Mainnet: U via PancakeSwap (BNB not needed — gas is sponsored).
+Testnet faucet: https://www.bnbchain.org/en/testnet-faucet (tBNB fallback).
+Mainnet: U via PancakeSwap; keep BNB for ERC-8183 fund/settle.
 
 ## 4. SIWE binding (Pieverse) — ALWAYS bind before paying
 
@@ -244,7 +244,9 @@ registers a `Container` runtime and `app/agent/Dockerfile` builds the image
 |---|---|---|
 | ~~Seller `submit` unavailable~~ | ~~REQ-1~~ RESOLVED in v0.19.0 | `submit --opt-params` works — verified on-chain. |
 | ~~Seller `quote` signing broken~~ | ~~S-11 regression in v0.19.0~~ RESOLVED in v0.19.1 | v0.19.0 hex-decoded `0x…` messages and signed the bytes, so provider_sig never verified (testnet also rejected `sign-message --chain bsctestnet`). v0.19.1 signs the literal text (EIP-191): `sign_quote` works on both wallet kinds. |
-| ~~Testnet intent writes self-pay gas~~ | ~~REQ-2~~ RESOLVED in v0.20.0 | twak accepts `--paymaster-url`; the SDK forwards MegaFuel's testnet endpoint on every sponsored write, so testnet 8004/8183 writes are gasless too (the relay itself is flaky — see the BUG-029 warning in §3). Mainnet stays twak-internal (no flag passed). The CLI floor is now **0.20.0** — `bag doctor` / `bag deploy prepare` reject older. |
+| ~~No testnet paymaster URL~~ | ~~REQ-2~~ RESOLVED in v0.20.0 | twak accepts `--paymaster-url`; the SDK forwards MegaFuel's testnet endpoint on eligible writes. Actual sponsorship depends on the paymaster policy covering the target and method (the relay itself is flaky — see the BUG-029 warning in §3). The CLI floor is **0.20.0**. |
+| Custom ERC-8004 registry | supported | Set `ERC8004_REGISTRY_ADDRESS`; the SDK requires the intent target and env override to match before invoking twak. Sponsorship still depends on paymaster policy coverage, so keep fallback tBNB. |
+| Custom ERC-8183 targets unavailable | upstream feature request | twak v0.20.0 has no Commerce/Router/Policy address option. Studio doctor/prepare and the SDK fail closed instead of silently executing on canonical contracts; use `evm-local` for a custom ERC-8183 deployment. |
 | No generic EIP-712 signing | P0 (won't fix) | `[wallet.signing]` is ignored; payments go through the delegated payer's own prechecks + `--max-payment`. Endpoints needing an `Authorization` header *and* x402 are unavailable (e.g. `bag llm key new --initial-usd > 0` — use `--initial-usd 0` + topup + allocate instead, same end state). |
 | No wallet import | S-6 | Switching wallet kinds changes your address → re-run `bag 8004 register` (new on-chain identity). |
 | Programmatic wallet creation forces password onto argv | S-8 | Bridged by `bag wallet twak-init` (password via stdin / 0600 file / hidden prompt — never argv); the manual twak commands remain a fallback. |