@bnbagent/studio-cli 0.0.6-alpha.4 → 0.0.6-alpha.6

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

@@ -3,7 +3,7 @@ name: bnbagent-studio-selling-via-b402
 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
+> **Reference file** of the `bnbagent-studio` router skill, installed at
 > `bnbagent-studio/references/` and loaded on demand (not a standalone skill).
 > Route here via the router's decision tree.
 
@@ -19,10 +19,9 @@ agent wallets, or mix sandbox and production values.
 - 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).
-- 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`.
+- PAID managed platform only: an interactive GitHub-login session from
+  `bag platform login` is available for reading the platform Relay egress
+  IPs. A `bnbk_…` CI token does not satisfy this endpoint's GitHub-user check.
 - `[payments.x402_seller]` exists. If not, run
   `bag x402 sell init`.
 
@@ -59,66 +58,86 @@ call under the
 the runtime signs each request automatically once the credentials are stored.
 
 Work from the workspace root. Keep private material under `.studio/`, which is
-excluded from source and deploy artifacts:
+excluded from source and deploy artifacts. Generate a separate key pair for
+each environment:
 
 ```bash
 umask 077
-mkdir -p .studio/b402
-openssl genrsa -out .studio/b402/private.pem 2048
-openssl pkey -in .studio/b402/private.pem -pubout \
-  -out .studio/b402/public.pem
-openssl pkey -in .studio/b402/private.pem -pubout -outform DER |
-  openssl base64 -A > .studio/b402/public.der.b64
-openssl pkcs8 -topk8 -nocrypt -in .studio/b402/private.pem -outform DER |
-  openssl base64 -A > .studio/b402/private.der.b64
-chmod 600 .studio/b402/private.pem .studio/b402/private.der.b64
+b402_env=sandbox
+mkdir -p ".studio/b402/$b402_env"
+openssl genpkey -algorithm RSA \
+  -out ".studio/b402/$b402_env/private.pem" \
+  -pkeyopt rsa_keygen_bits:1024
+openssl pkey -in ".studio/b402/$b402_env/private.pem" -pubout \
+  -out ".studio/b402/$b402_env/public.pem"
+openssl pkey -in ".studio/b402/$b402_env/private.pem" -pubout -outform DER |
+  openssl base64 -A > ".studio/b402/$b402_env/public.der.b64"
+openssl pkcs8 -topk8 -nocrypt \
+  -in ".studio/b402/$b402_env/private.pem" -outform DER |
+  openssl base64 -A > ".studio/b402/$b402_env/private.der.b64"
+chmod 600 ".studio/b402/$b402_env/private.pem" \
+  ".studio/b402/$b402_env/private.der.b64"
 ```
 
 Do not print the private key or its base64 form. Submit only the public key
 material to B402.
 
-Studio generates a 2048-bit RSA key. The current B402 application form text
-mentions 1024 bits, while 2048-bit acceptance still requires confirmation from
-the B402 operator. Confirm that field with the operator; do not silently
-downgrade the key.
+The current B402 request-signing contract explicitly requires a 1024-bit RSA
+key and RSA-SHA256. Follow that protocol requirement even if a larger RSA key
+would normally be preferred elsewhere. Repeat with `b402_env=production`
+instead of reusing the sandbox pair.
 
 ## Collect the IP allowlist
 
-B402 allowlists the merchant's **outbound** (egress) IPs — the addresses the
+B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the
 agent's facilitator calls come FROM. Submit every part that applies to your
 deployment target:
 
-1. **Platform egress IPs (managed-platform deploys)** — the addresses
-   deployed-agent requests reach B402 from. Authenticated read (bearer from
-   the Preconditions):
+1. **Platform Relay egress IPs (managed-platform deploys)**: the addresses
+   that the platform B402 Relay uses to reach the facilitator. The managed
+   deployment worker points only the AgentCore runtime copy of
+   `B402_BASE_URL` at this Relay. Refresh and read the interactive session
+   without printing its bearer:
 
    ```bash
-   curl -H "Authorization: Bearer $BNBAGENT_API_TOKEN" \
-     "https://bnbagent-api.bnbchain.world/v1/b402/whitelist-ips"
+   bag platform whoami >/dev/null
+   platform_session="$HOME/.bnbagent-deploy/bnb/session.json"
+   platform_access_token="$(jq -er '.access_token' "$platform_session")"
+   platform_api_url="$(jq -er '.apiUrl' "$platform_session")"
+   curl -H "Authorization: Bearer $platform_access_token" \
+     "$platform_api_url/v1/b402/whitelist-ips"
+   unset platform_access_token
    # → {"whitelist_ips": ["13.115.15.190", …], "cache_ttl_seconds": 300}
    ```
 
    Submit every address in `whitelist_ips`. The list is served with a short
-   cache TTL and can rotate — re-read it right before submitting the form.
-   Set `BAG_PLATFORM_API_BASE` to target a non-production platform
-   environment.
+   cache TTL and can rotate, so re-read it right before submitting the form.
+   The login session is stored mode `0600`. Do not echo, log, or paste its
+   access or refresh token. `bnbk_` tokens from `bag platform token` are
+   deliberately rejected by this GitHub-login-only endpoint.
 
-2. **Your local public IP** — required so a local `bag dev` run can reach
+2. **Your local public IP**: required so a local `bag dev` run can reach
    B402:
 
    ```bash
    curl ipinfo.io/ip
    ```
 
-3. **Self-hosted AgentCore egress (self-deploys)** — AgentCore gives the
-   container no fixed egress IP, so there is no address to submit directly.
-   Route the facilitator egress through a fixed-IP forward proxy you control
-   and submit THAT IP: set `HTTPS_PROXY` on the runtime and enable proxy
-   support for Node's fetch, which ignores proxy env vars by default —
-   install an undici `EnvHttpProxyAgent` global dispatcher in the agent
-   entrypoint, or run the container on Node 24+ with `--use-env-proxy`.
-   Without this, every verify/settle call is rejected as an unallowlisted
-   IP even though the deploy summary reports the rail ACTIVE.
+3. **Self-hosted AgentCore egress (self-deploys)**: operate a restricted B402
+   Relay on a host with a fixed public egress IP, such as a user-managed VPS,
+   and submit that IP. Set the runtime `B402_BASE_URL` to the Relay base URL.
+   The Relay exposes only
+   `supported`, `verify`, and `settle`, fixes the upstream facilitator, and
+   forwards the signed body and Tesla header allowlist without holding the
+   merchant private key or automatically retrying a settlement transport
+   failure. See the
+   [self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md)
+   for a TypeScript example.
+
+   As an alternative, use AWS-supported AgentCore VPC mode with a private subnet, NAT
+   Gateway, and Elastic IP. Submit the Elastic IP and keep
+   `B402_BASE_URL` pointed at the facilitator. Studio does not deploy or
+   manage that AWS network.
 
 Do not add the public inbound gateway IP, a transient build-runner IP, or
 guessed addresses. If the whitelist endpoint is unreachable, stop onboarding
@@ -134,10 +153,11 @@ production. Fill the form as follows:
 | Field | Value |
 |---|---|
 | Business Name | Your agent or business display name |
-| Website | Your project or service URL |
-| Wallet | The agent wallet address |
-| RSA Public Key | The contents of `.studio/b402/public.der.b64` in the format the operator confirms |
-| IP allowlist | Every platform egress IP from `/v1/b402/whitelist-ips` plus your local public IP (see "Collect the IP allowlist") |
+| Email | Primary contact email address |
+| Wallet address | The agent wallet for that environment |
+| Public key | The contents of `.studio/b402/<environment>/public.der.b64` |
+| IP allowlist | For managed deploys, every platform Relay IP from `/v1/b402/whitelist-ips`; for self-hosted deploys, the user's Relay or NAT Elastic IP; add the local public IP when `bag dev` must reach B402 directly |
+| Webhook callback URL | Supply only when the integration uses callbacks |
 
 Keep the two environments isolated:
 
@@ -152,20 +172,28 @@ Open the workspace `.studio/.env.local` in an editor and fill exactly four
 values:
 
 ```dotenv
-B402_BASE_URL=https://qacb.sdtaop.com
+B402_BASE_URL=
 B402_CLIENT_ID=
 B402_ACCESS_TOKEN=
 B402_PRIVATE_KEY_B64=
 ```
 
 Copy the single-line DER value from
-`.studio/b402/private.der.b64` into `B402_PRIVATE_KEY_B64`. Do not include the
-value in shell history, terminal output, source files, TOML, screenshots, or
-support tickets.
+`.studio/b402/<environment>/private.der.b64` into `B402_PRIVATE_KEY_B64`.
+`B402_BASE_URL`, `B402_CLIENT_ID`, and `B402_ACCESS_TOKEN` are the values
+issued together for that environment. Do not include any value in shell
+history, terminal output, source files, TOML, screenshots, or support tickets.
 
 `B402_PRIVATE_KEY` accepts the PEM representation as an alternative. Keep
 exactly one private-key form; do not set both.
 
+For the current managed BSC Testnet path, the platform-supported upstream is
+`https://qacb.sdtaop.com`; the worker projects only the AgentCore runtime copy
+to its Relay. For a generic self-hosted environment, use the authenticated
+base URL issued during onboarding. With your own Relay, set the runtime
+`B402_BASE_URL` to that Relay base URL and configure the Relay's fixed upstream
+to the issued URL.
+
 ## Verify and activate
 
 For PAID mode, check names and presence without exposing values:
@@ -197,22 +225,34 @@ 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.
+there is no anonymous URL. Operate your own HTTP front that relays envelope-v1
+JSON through an authenticated AgentCore invocation. The default Bag
+self-deploy uses Cognito OAuth over raw HTTPS; AWS SDK/SigV4 is only for a
+runtime deliberately configured with IAM authorization. PAID also needs your
+own fixed-egress B402 Relay or equivalent network path. The complete gateway
+wrapper, response parser, Relay example, and direct-invocation fallback are in
+the
+[self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md).
+A dormant or forced-dormant summary means the rail was not activated; fix the
+named credential, runtime, network, or tunnel condition and redeploy.
 
 ## Hard rules
 
 - Never log or print any B402 value or private key.
 - Never put a B402 value in `studio.toml` or a deploy descriptor.
-- Never retry a settlement whose outcome is unknown. Follow
+- Never replay a paid HTTP request whose outcome is unknown. Follow
   `docs/guides/x402-selling.md` and reconcile `(nonce, network, payer)` first.
+- Binance `/settle` is asynchronous. A parseable `success: false` response
+  with a transaction is pending and requires an idempotent poll with the same
+  settlement payload. Studio v0.0.6 and the latest
+  `@bnb-chain/b402@0.1.0` do not yet perform that poll; they classify pending
+  as unknown. Do not claim current mainnet readiness until this is updated.
 - Settlement happens before work. A later work failure retains the payment and
   does not trigger an automatic refund.
 - The rail activates on AgentCore targets only (managed platform or
   self-hosted); azure-foundry stays forced dormant.
-- PAID payout wallets must use `wallet.kind` `evm-local` or `twak`; FREE has
-  no payout and does not apply this B402-specific allowlist.
+- PAID B402 payout wallets must use `wallet.kind` `evm-local` (private-key
+  wallet stored as an encrypted keystore) or `twak`. Altana is unsupported.
+  FREE x402 bypasses B402, has no payout, and must not be described as Altana
+  B402 support.
 - Never describe FREE as a zero-value B402 settlement. It bypasses B402.

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

@@ -199,8 +199,11 @@ bag deploy destroy --provider aws --execute # delegated teardown (add --purge)
 - b402/x402 selling on self-hosted AgentCore: the rail activates in-process
   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`.
+  relays envelope-v1 through the runtime's configured authorizer. The default
+  Bag deploy uses Cognito OAuth over HTTPS, not SDK/SigV4. PAID also needs a
+  fixed-egress B402 Relay or VPC/NAT/Elastic-IP path. See
+  `bnbagent-studio-selling-via-b402` and
+  `docs/guides/self-hosted-x402-gateway.md`.
 - `bag deploy --help` / `bag deploy <command> --help` (authoritative for commands + flags)
 - `agentcore/agentcore.json` — name (resource naming continuity), protocol, authorizer, envVars
 - `agentcore/aws-targets.json` — AWS account + region

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

@@ -27,8 +27,8 @@ bag init <name> --wallet-kind altana --destination self --no-onboard
 # Non-TTY defaults to OpenRouter. In a TTY, choose OpenRouter, OpenAI, or
 # Anthropic from the provider menu; a flag remains available when desired:
 # bag init <name> --wallet-kind altana --llm-provider anthropic --destination self
+# Edit <name>/.studio/.env.local and set WALLET_PASSWORD first.
 cd <name>/app/agent
-export WALLET_PASSWORD='<strong password>'
 bag wallet new
 # fund the printed admin address with gas + U
 bag wallet session grant

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

@@ -31,8 +31,9 @@ with "unknown option"); `bag doctor` and `bag deploy prepare` verify the floor.
 
 ## 2. Create the wallet — one time, in YOUR terminal
 
-studio can't create it for you (the twak CLI takes the password on argv, upstream
-S-8, and studio never puts secrets on argv). Do these steps yourself.
+`bag wallet twak-init` drives creation for you (step 3) so you never type the
+password on a command line; the NaaS setup wizard below still has to be run by
+hand once, because it is interactive.
 
 **Every twak command is prefixed with the dedicated home.** Without `HOME=$DH`,
 twak uses your real `~/.twak` (your MAIN wallet) and macOS pops a login-keychain
@@ -64,20 +65,22 @@ DH=<workspace>/.studio/twak     # e.g. ~/proj/.studio/twak
      your main/real wallet).
 
 **3. Create the wallet** (password UPPER + lower + digit, e.g. `Mypasswd01`;
-   `mypasswd01` is rejected). **RECOMMENDED — let studio drive it with the
-   password OFF argv** (it resolves the project home from studio.toml, so no
-   `HOME=` juggling):
+   `mypasswd01` is rejected). **RECOMMENDED — let studio drive it so you never
+   type the password on a command line** (it resolves the project home from
+   studio.toml, so no `HOME=` juggling):
    ```bash
    bag wallet twak-init                                       # interactive hidden prompt
    printf %s "$PW" | bag wallet twak-init --password-stdin    # CI / scripts
    bag wallet twak-init --password-file pw.txt                # file must be chmod 600
    ```
-   It wraps `twak wallet create --no-keychain` (password reaches twak via env +
-   piped stdin only), tightens `wallet.json` to mode 600, and adopts the
-   address into studio.toml in one go — so steps 5's `bag wallet new` is
-   already done.
-
-   Manual alternative (password lands on argv → `ps` / shell history;
+   It seeds this home's `credentials.json` from `~/.twak` when step 2 was run
+   there, wraps `twak wallet create --password … --no-keychain` (twak requires
+   the flag on its own argv, so the value reaches that short-lived child — it
+   never lands in YOUR shell history), tightens `wallet.json` to mode 600, and
+   adopts the address into studio.toml in one go — so step 5's `bag wallet new`
+   is already done.
+
+   Manual alternative (you type the password on argv → `ps` / shell history;
    acceptable only for a throwaway hot wallet):
    ```bash
    HOME="$DH" twak wallet create --password '<StrongPw>' --no-keychain
@@ -249,8 +252,11 @@ registers a `Container` runtime and `app/agent/Dockerfile` builds the image
 | 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. |
+| Programmatic wallet creation forces password onto argv | S-8 | Bridged by `bag wallet twak-init` (you supply it via stdin / 0600 file / hidden prompt; studio forwards it on the child's argv because twak requires the flag); the manual twak commands remain a fallback. |
 | CLI has no daily/monthly caps | — | Studio's policy layer (`[budget].max_per_day_usd`, host allowlist, per-request caps) is the spend authority for both wallet kinds. |
+| `twak wallet balance --chain bsctestnet` rejects the chain | BUG-031 | Fails with `CHAIN_UNSUPPORTED` even though `wallet address` and `erc8183` accept `bsctestnet`. Use `bag wallet balance` (RPC-based, works on testnet), or raw RPC: `eth_getBalance` for tBNB and an `eth_call` of `balanceOf(address)` on the U token for token balance. |
+| `twak tx <hash> --chain bsctestnet` rejects the chain | BUG-032 | Same chain-registry gap on the readback path: transactions twak itself just mined on `bsctestnet` cannot be inspected with `twak tx`. Use public RPC (`eth_getTransactionByHash` / `eth_getTransactionReceipt`) or BscScan testnet instead. |
+| Raw `twak erc8183 create-job` has no expiry preflight | BUG-030 | An `--expires-at` inside the policy's dispute window is accepted, all four funding steps succeed, and only the final `submit` reverts `SubmissionTooLate()` (`0x15e5dd74`). Prefer the SDK path (`ERC8183Client` preflights this); if you must use the raw CLI, set `expires_at ≥ now + deadline + dispute_window` — on testnet's 24h window, `now + 172800` (48h) is a safe floor. |
 
 ## 7. Quick health checks