@bnbagent/studio-cli 0.0.13-alpha.2 → 0.0.13-alpha.4

package/recipes/runtimes/agentcore/code/{{PKG}}/mcpMain.ts.tmpl

@@ -69,10 +69,10 @@ import {
 } from "@bnbagent/studio-runtime/wallet";
 import {
   createEnvelopeMiddleware,
-  X402_SELL_PATH,
-  type X402HttpRequest,
-  X402Seller,
-} from "@bnbagent/studio-runtime/x402";
+  b402SellPath,
+  type B402HttpRequest,
+  B402Seller,
+} from "@bnbagent/studio-runtime/b402";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
@@ -185,7 +185,7 @@ function flatQuery(query: Record<string, unknown>): Record<string, string> {
 }
 
 // ── LLM work hook (lazy: built on first authorized task) ─────────────────────
-// Deferred construction keeps negotiate and unpaid x402 quote paths from
+// Deferred construction keeps negotiate and unpaid payment challenge paths from
 // building the model, and keeps this module importable without the provider
 // env until a deliverable is actually produced.
 type RunLlm = (prompt: string) => Promise<string>;
@@ -593,25 +593,26 @@ async function main(): Promise<void> {
 
   const cfg = loadStudioToml();
   const rails = { erc8183: hasErc8183Rail(cfg) };
+  const sellPath = b402SellPath(cfg);
   const host = process.env.AGENT_BIND_HOST || "0.0.0.0";
   const port = Number(process.env.AGENT_PORT || "8000");
-  const seller = await X402Seller.create({
+  const seller = await B402Seller.create({
     cfg,
     runWork: ({ prompt }) => runLlm(prompt),
     walletAddress: getWallet().address,
     resourceUrl: `${
       process.env.AGENTCORE_RUNTIME_URL ?? `http://localhost:${port}`
-    }${X402_SELL_PATH}`,
+    }${sellPath}`,
   });
 
   const app = express();
 
   if (seller.state !== "disabled") {
     app.all(
-      X402_SELL_PATH,
+      sellPath,
       express.text({ type: "*/*", limit: "1mb" }),
       async (req, res) => {
-        const request: X402HttpRequest = {
+        const request: B402HttpRequest = {
           method: req.method,
           path: req.path,
           query: flatQuery(req.query),

package/recipes/runtimes/agentcore/code/{{PKG}}/unifiedMain.ts.tmpl

@@ -33,14 +33,14 @@
  * because Foundry's incoming A2A is text-modality only — {@link SkillRouter}
  * parses it and dispatches through the SAME `SellerAgentExecutor.dispatch`.
  *
- * ## How x402 buyers reach /x402 on either runtime
+ * ## How payment buyers reach the selected B402 seller route
  *
  * Neither hosted-agent gateway allows anonymous ingress, and both strip or
  * gate the buyer's half of the HTTP exchange — so the anonymous buyer talks
  * to an external gateway that wraps each request in `http-envelope-v1`
  * (outer HTTP always 200) and forwards it with the runtime's own auth.
  * {@link createEnvelopeMiddleware} unwraps the tunnel onto the in-process
- * {@link X402Seller} below. See docs/guides/self-hosted-x402-gateway.md
+ * {@link B402Seller} below. See docs/guides/self-hosted-x402-gateway.md
  * (AWS) and self-hosted-x402-gateway-azure.md (Azure).
  *
  * Secrets: on AgentCore, `loadRuntimeSecrets()` pulls the Secrets Manager
@@ -85,11 +85,11 @@ import {
 } from "@bnbagent/studio-runtime/wallet";
 import {
   createEnvelopeMiddleware,
-  X402_SELL_PATH,
-  type X402HttpRequest,
-  type X402RunWork,
-  X402Seller,
-} from "@bnbagent/studio-runtime/x402";
+  b402SellPath,
+  type B402HttpRequest,
+  type B402RunWork,
+  B402Seller,
+} from "@bnbagent/studio-runtime/b402";
 import { generateText, stepCountIs } from "ai";
 import express from "express";
 import { buildAgentCard } from "./agentCard.js";
@@ -252,8 +252,8 @@ function flatQuery(query: Record<string, unknown>): Record<string, string> {
   return out;
 }
 
-function x402Work(runWork: RunWork): X402RunWork {
-  return ({ prompt }) => runWork(prompt, { sessionId: "x402" });
+function b402Work(runWork: RunWork): B402RunWork {
+  return ({ prompt }) => runWork(prompt, { sessionId: "b402" });
 }
 
 // ── Foundry text-carrier adapters ────────────────────────────────────────────
@@ -447,6 +447,7 @@ async function main(): Promise<void> {
 
   const cfg = loadStudioToml();
   const rails = { erc8183: hasErc8183Rail(cfg) };
+  const sellPath = b402SellPath(cfg);
   const host = process.env.AGENT_BIND_HOST || "0.0.0.0";
   // Both hosted-agent contract ports are always bound (AgentCore A2A: 9000,
   // Foundry invocations: 8088) so one image serves either cloud. AGENT_PORT
@@ -473,9 +474,9 @@ async function main(): Promise<void> {
     commerceSkills: rails.erc8183,
   });
   const agentCard = buildAgentCard({ commerceSkills: rails.erc8183 });
-  const seller = await X402Seller.create({
+  const seller = await B402Seller.create({
     cfg,
-    runWork: x402Work(runWork),
+    runWork: b402Work(runWork),
     walletAddress: getWallet().address,
     // The 402 challenge's resource URL must be the BUYER-facing address:
     // BNBAGENT_PUBLIC_URL (the operator's gateway base URL, no /x402 suffix —
@@ -488,7 +489,7 @@ async function main(): Promise<void> {
       process.env.AGENT_PUBLIC_URL ??
       process.env.AGENTCORE_RUNTIME_URL ??
       `http://localhost:${port}`
-    }${X402_SELL_PATH}`,
+    }${sellPath}`,
   });
   const router = new SkillRouter(executor, { name: generatorTag() });
 
@@ -518,10 +519,10 @@ async function main(): Promise<void> {
 
   if (seller.state !== "disabled") {
     app.all(
-      X402_SELL_PATH,
+      sellPath,
       express.text({ type: "*/*", limit: "1mb" }),
       async (req, res) => {
-        const request: X402HttpRequest = {
+        const request: B402HttpRequest = {
           method: req.method,
           path: req.path,
           query: flatQuery(req.query),
@@ -583,7 +584,7 @@ async function main(): Promise<void> {
   const servers = ports.map((p, i) => {
     const server = app.listen(p, host, () => {
       console.log(
-        `[seller-agent] serving on ${host}:${p}${i === 0 ? "" : " (secondary contract port)"} (x402: ${seller.state})`,
+        `[seller-agent] serving on ${host}:${p}${i === 0 ? "" : " (secondary contract port)"} (${seller.protocol}: ${seller.state})`,
       );
     });
     if (i > 0) {

package/recipes/runtimes/agentcore/recipe.toml

@@ -32,7 +32,7 @@ node = [
     # BNBAGENT_RUNTIME_SECRET_ID is set (default secretsmanager mode + platform).
     "@aws-sdk/client-secrets-manager@^3.600.0",
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.2-alpha.1",
+    "@bnbagent/sdk@0.5.3",
     # The LLM work hook (generateText + tools) and the model factory.
     "ai@^7.0.29",
     # Tool input schemas (AI SDK tools + MCP registerTool).

package/recipes/runtimes/azure-foundry/code/{{PKG}}/mcpMain.ts.tmpl

@@ -69,10 +69,10 @@ import {
 } from "@bnbagent/studio-runtime/wallet";
 import {
   createEnvelopeMiddleware,
-  X402_SELL_PATH,
-  type X402HttpRequest,
-  X402Seller,
-} from "@bnbagent/studio-runtime/x402";
+  b402SellPath,
+  type B402HttpRequest,
+  B402Seller,
+} from "@bnbagent/studio-runtime/b402";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
@@ -185,7 +185,7 @@ function flatQuery(query: Record<string, unknown>): Record<string, string> {
 }
 
 // ── LLM work hook (lazy: built on first authorized task) ─────────────────────
-// Deferred construction keeps negotiate and unpaid x402 quote paths from
+// Deferred construction keeps negotiate and unpaid payment challenge paths from
 // building the model, and keeps this module importable without the provider
 // env until a deliverable is actually produced.
 type RunLlm = (prompt: string) => Promise<string>;
@@ -593,25 +593,26 @@ async function main(): Promise<void> {
 
   const cfg = loadStudioToml();
   const rails = { erc8183: hasErc8183Rail(cfg) };
+  const sellPath = b402SellPath(cfg);
   const host = process.env.AGENT_BIND_HOST || "0.0.0.0";
   const port = Number(process.env.AGENT_PORT || "8000");
-  const seller = await X402Seller.create({
+  const seller = await B402Seller.create({
     cfg,
     runWork: ({ prompt }) => runLlm(prompt),
     walletAddress: getWallet().address,
     resourceUrl: `${
       process.env.AGENTCORE_RUNTIME_URL ?? `http://localhost:${port}`
-    }${X402_SELL_PATH}`,
+    }${sellPath}`,
   });
 
   const app = express();
 
   if (seller.state !== "disabled") {
     app.all(
-      X402_SELL_PATH,
+      sellPath,
       express.text({ type: "*/*", limit: "1mb" }),
       async (req, res) => {
-        const request: X402HttpRequest = {
+        const request: B402HttpRequest = {
           method: req.method,
           path: req.path,
           query: flatQuery(req.query),

package/recipes/runtimes/azure-foundry/code/{{PKG}}/unifiedMain.ts.tmpl

@@ -33,14 +33,14 @@
  * because Foundry's incoming A2A is text-modality only — {@link SkillRouter}
  * parses it and dispatches through the SAME `SellerAgentExecutor.dispatch`.
  *
- * ## How x402 buyers reach /x402 on either runtime
+ * ## How payment buyers reach the selected B402 seller route
  *
  * Neither hosted-agent gateway allows anonymous ingress, and both strip or
  * gate the buyer's half of the HTTP exchange — so the anonymous buyer talks
  * to an external gateway that wraps each request in `http-envelope-v1`
  * (outer HTTP always 200) and forwards it with the runtime's own auth.
  * {@link createEnvelopeMiddleware} unwraps the tunnel onto the in-process
- * {@link X402Seller} below. See docs/guides/self-hosted-x402-gateway.md
+ * {@link B402Seller} below. See docs/guides/self-hosted-x402-gateway.md
  * (AWS) and self-hosted-x402-gateway-azure.md (Azure).
  *
  * Secrets: on AgentCore, `loadRuntimeSecrets()` pulls the Secrets Manager
@@ -85,11 +85,11 @@ import {
 } from "@bnbagent/studio-runtime/wallet";
 import {
   createEnvelopeMiddleware,
-  X402_SELL_PATH,
-  type X402HttpRequest,
-  type X402RunWork,
-  X402Seller,
-} from "@bnbagent/studio-runtime/x402";
+  b402SellPath,
+  type B402HttpRequest,
+  type B402RunWork,
+  B402Seller,
+} from "@bnbagent/studio-runtime/b402";
 import { generateText, stepCountIs } from "ai";
 import express from "express";
 import { buildAgentCard } from "./agentCard.js";
@@ -252,8 +252,8 @@ function flatQuery(query: Record<string, unknown>): Record<string, string> {
   return out;
 }
 
-function x402Work(runWork: RunWork): X402RunWork {
-  return ({ prompt }) => runWork(prompt, { sessionId: "x402" });
+function b402Work(runWork: RunWork): B402RunWork {
+  return ({ prompt }) => runWork(prompt, { sessionId: "b402" });
 }
 
 // ── Foundry text-carrier adapters ────────────────────────────────────────────
@@ -447,6 +447,7 @@ async function main(): Promise<void> {
 
   const cfg = loadStudioToml();
   const rails = { erc8183: hasErc8183Rail(cfg) };
+  const sellPath = b402SellPath(cfg);
   const host = process.env.AGENT_BIND_HOST || "0.0.0.0";
   // Both hosted-agent contract ports are always bound (AgentCore A2A: 9000,
   // Foundry invocations: 8088) so one image serves either cloud. AGENT_PORT
@@ -473,9 +474,9 @@ async function main(): Promise<void> {
     commerceSkills: rails.erc8183,
   });
   const agentCard = buildAgentCard({ commerceSkills: rails.erc8183 });
-  const seller = await X402Seller.create({
+  const seller = await B402Seller.create({
     cfg,
-    runWork: x402Work(runWork),
+    runWork: b402Work(runWork),
     walletAddress: getWallet().address,
     // The 402 challenge's resource URL must be the BUYER-facing address:
     // BNBAGENT_PUBLIC_URL (the operator's gateway base URL, no /x402 suffix —
@@ -488,7 +489,7 @@ async function main(): Promise<void> {
       process.env.AGENT_PUBLIC_URL ??
       process.env.AGENTCORE_RUNTIME_URL ??
       `http://localhost:${port}`
-    }${X402_SELL_PATH}`,
+    }${sellPath}`,
   });
   const router = new SkillRouter(executor, { name: generatorTag() });
 
@@ -518,10 +519,10 @@ async function main(): Promise<void> {
 
   if (seller.state !== "disabled") {
     app.all(
-      X402_SELL_PATH,
+      sellPath,
       express.text({ type: "*/*", limit: "1mb" }),
       async (req, res) => {
-        const request: X402HttpRequest = {
+        const request: B402HttpRequest = {
           method: req.method,
           path: req.path,
           query: flatQuery(req.query),
@@ -583,7 +584,7 @@ async function main(): Promise<void> {
   const servers = ports.map((p, i) => {
     const server = app.listen(p, host, () => {
       console.log(
-        `[seller-agent] serving on ${host}:${p}${i === 0 ? "" : " (secondary contract port)"} (x402: ${seller.state})`,
+        `[seller-agent] serving on ${host}:${p}${i === 0 ? "" : " (secondary contract port)"} (${seller.protocol}: ${seller.state})`,
       );
     });
     if (i > 0) {

package/recipes/runtimes/azure-foundry/recipe.toml

@@ -29,7 +29,7 @@ node = [
     # on either cloud.
     "@aws-sdk/client-secrets-manager@^3.600.0",
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.2-alpha.1",
+    "@bnbagent/sdk@0.5.3",
     # The LLM work hook (generateText + tools) and the model factory
     # (model.ts buildModel — studio.toml [llm] + the provider key env).
     "ai@^7.0.29",

package/recipes/x402-buyer/recipe.toml

@@ -6,7 +6,7 @@ status = "v0.0.x"
 [dependencies]
 node = [
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.2-alpha.1",
+    "@bnbagent/sdk@0.5.3",
     "ai@^7.0.29",   # AI SDK `tool` wrappers around the buyer functions
     "zod@^3.25.0",  # tool input schemas
 ]

package/skills/bnbagent-studio.md

@@ -1,6 +1,6 @@
 ---
 name: bnbagent-studio
-description: The single entry point for bnbagent-studio - a TypeScript CLI (`bag`) for building a blockchain SELLER agent that earns $U on BNB Chain via ERC-8004 + ERC-8183 + x402 (Pieverse LLM inside). Load this skill whenever the user works in a bnbagent-studio / `bag` project, or wants to create/scaffold, deploy, run, debug, operate, or monetize such a seller agent (composable A2A, MCP, and X402 faces; BNB Chain trial, AWS AgentCore, or Azure Foundry). All detailed playbooks ship as references/ files inside this skill - route via the decision tree in the body. When invoked with arguments, treat them as the user's intent and route the same way.
+description: The single entry point for bnbagent-studio - a TypeScript CLI (`bag`) for building a blockchain SELLER agent that earns $U on BNB Chain via ERC-8004 + ERC-8183 + an x402 or MPP B402 payment face (Pieverse LLM inside). Load this skill whenever the user works in a bnbagent-studio / `bag` project, or wants to create/scaffold, deploy, run, debug, operate, or monetize such a seller agent (composable A2A, MCP, and alternative X402/MPP faces; BNB Chain trial, AWS AgentCore, or Azure Foundry). All detailed playbooks ship as references/ files inside this skill - route via the decision tree in the body. When invoked with arguments, treat them as the user's intent and route the same way.
 ---
 
 # bnbagent-studio (the single entry point)
@@ -23,11 +23,12 @@ One deployed runtime, one signer: a single valuable Agent serves the selected fa
 | Add wallet / the single seller runtime to an existing TypeScript agent | `references/bnbagent-studio-adding-to-project.md` |
 | Run / debug / dev / doctor / RPC / balance / incident triage | `references/bnbagent-studio-operating.md` |
 | Implement what the Agent sells, tune pricing, publish over A2A and/or MCP, defend disputes (seller flow) | `references/bnbagent-studio-selling-via-8183.md` |
-| Sell one paid or FREE HTTP request through the B402-backed x402 rail (pricing choice; paid merchant application, RSA key, credentials, IP allowlist, activation) | `references/bnbagent-studio-selling-via-b402.md` |
+| Sell one paid or FREE HTTP request through the selected B402-backed x402 or MPP rail (pricing choice; paid merchant application, RSA key, credentials, IP allowlist, activation) | `references/bnbagent-studio-selling-via-b402.md` |
 | Deploy / redeploy / status / logs / destroy | Run `bag deploy` and explicitly choose a provider. Non-interactive deploy requires `--provider bnb\|aws\|azure --yes` (and `--allow-multiple` when keeping another provider active). Read `references/bnbagent-studio-use-bnb-trial.md`, `references/bnbagent-studio-use-aws-agentcore.md`, or `references/bnbagent-studio-use-azure-foundry.md` for the selected provider. `bag deploy status` lists every recorded provider; multi-deployment logs/verify/destroy require `--provider`. |
 | Wire chain-read tools into the Agent's LLM (AI SDK `tool()` wrappers, or any TS agent framework) | `references/bnbagent-studio-wiring-llm-tools.md` |
 | Buy a service from another ERC-8183 seller via CLI - incl. testing your own seller from the buyer side (v2/internal - NOT the v1 seller product flow) | `references/bnbagent-studio-buying-via-8183.md` |
 | Give the agent a PAID x402 capability - CMC market data / Binance Bazaar (B402) merchants / any pay-per-call API (`bag x402 trust`, x402-buyer recipe, 402 buyer errors) | `references/bnbagent-studio-buying-from-bazaar.md` |
+| Give the agent a native MPP+B402 buyer capability (`bag mpp trust/quote/buy`, mpp-buyer recipe, recipient/realm pins, unknown outcomes) | `references/bnbagent-studio-buying-via-mpp.md` |
 | Extend the EIP-712 signing allowlist (custom contract / new x402 service / diagnose `PolicyViolation` / `X402PolicyError`) | `references/bnbagent-studio-extending-signing.md` |
 | Project uses `[wallet].kind = "twak"` (create / fund / SIWE-bind / container deploy / known limitations) | `references/bnbagent-studio-using-twak-wallet.md` |
 | Project uses `[wallet].kind = "altana"` (admin keystore / bounded session / quote checker / x402 allowance / local dev / session-only deploy + renewal) | `references/bnbagent-studio-using-altana-wallet.md` |
@@ -53,11 +54,11 @@ Treat ERC-8183 amounts as decimal strings at CLI/config boundaries and `bigint`
 
 ## CLI groups at a glance
 
-`init`, `scan`, `recipe`, `skills`, `wallet`, `erc8004`, `erc8183`, `x402`, `agents`, `config`, `env`, `dev`, `doctor`, `audit`, `deploy`, `platform`, `llm`, `bundle`, `budget` - see `bag --help` for details. `bag deploy [--provider bnb\|aws\|azure] [--backend aws\|azure]` is the primary deploy command; `--backend` is valid only for provider `bnb` and confirms the recipe-derived managed backend. `prepare`, `verify`, `status`, `info`, `destroy`, `logs`, and `fix-gitignore` remain lifecycle subcommands (`deploy agent` is a deprecated compatibility alias). Provider deploy/status/logs/destroy and deploy-time credential validation are delegated to pinned `@bnbagent/deploy-cli@0.5.13`.
+`init`, `scan`, `recipe`, `skills`, `wallet`, `erc8004`, `erc8183`, `x402`, `mpp`, `agents`, `config`, `env`, `dev`, `doctor`, `audit`, `deploy`, `platform`, `llm`, `bundle`, `budget` - see `bag --help` for details. `bag deploy [--provider bnb\|aws\|azure] [--backend aws\|azure]` is the primary deploy command; `--backend` is valid only for provider `bnb` and confirms the recipe-derived managed backend. `prepare`, `verify`, `status`, `info`, `destroy`, `logs`, and `fix-gitignore` remain lifecycle subcommands (`deploy agent` is a deprecated compatibility alias). Provider deploy/status/logs/destroy and deploy-time credential validation are delegated to pinned `@bnbagent/deploy-cli@0.5.15`.
 
 ## Tool surface
 
-- **CLI** - write-side (wallet ops, on-chain register, x402 buy, deploy)
+- **CLI** - write-side (wallet ops, on-chain register, x402/MPP buy, deploy)
 - **MCP** - an external seller face (`bag init --protocols MCP`), composable with A2A; dual mode is A2A-native so `HEALTHY_BUSY` preserves background work
 - **`@bnbagent/studio-runtime/tools`** - 15 pure read-only functions, wrapped into LLM tools by the chain-tools recipe (read `references/bnbagent-studio-wiring-llm-tools.md`)
 

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

@@ -114,13 +114,13 @@ Delivery is no longer instant: because the seller works in the background, the w
 
 ## Stage 5 - Fetch the deliverable
 
-The single seller runtime serves **no** job-query endpoint - the deliverable is read back from the on-chain submission (the `submit` tx carries the `deliverable_url`, typically `ipfs://...`) and the IPFS object. Get the URL via CLI:
+The single seller runtime serves **no** job-query endpoint - the deliverable is read back from the on-chain submission (the `submit` tx carries the stable `deliverable_url`). This may be IPFS for self-hosting or a content-addressed HTTPS URL for S3, Azure Blob, or managed-platform storage. Get the URL via CLI:
 
 ```bash
 bag erc8183 fetch <job_id>
 ```
 
-Prints the `deliverable_url`. Fetch it yourself (e.g. via an IPFS gateway) to read the `DeliverableManifest`: `{"chain_id", "contracts", "job_id", "response": {"content": ..., "content_type": ...}, "metadata": {...}}`.
+Prints the `deliverable_url`. Fetch it directly (using a gateway when the scheme is `ipfs://`) to read the `DeliverableManifest`: `{"chain_id", "contracts", "job_id", "response": {"content": ..., "content_type": ...}, "metadata": {...}}`.
 
 ## Stage 6 - Settle
 

package/skills/references/bnbagent-studio-buying-via-mpp.md

@@ -0,0 +1,44 @@
+---
+name: bnbagent-studio-buying-via-mpp
+description: When the user wants an agent to buy from a native MPP+B402 endpoint. Covers trust, quote, buy, recipe wiring, wallet limits, and unknown payment outcomes.
+---
+
+> **Reference file** of the `bnbagent-studio` router skill, installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill).
+
+# Buy via native MPP+B402
+
+MPP and x402 are parallel alternatives. Use this flow only when the server returns a native `WWW-Authenticate: Payment` challenge with method `b402` and intent `charge`. Never route an x402 402 body into this buyer and never add automatic protocol fallback.
+
+## Trust, inspect, then buy
+
+```bash
+bag mpp trust https://seller.example/mpp --yes
+bag mpp quote https://seller.example/mpp
+bag mpp buy https://seller.example/mpp --max-usd 0.10
+```
+
+`trust` is an unpaid probe. Review the live domain, realm, recipient, CAIP-2 network, token address, EIP-3009 method, price, and cap. For an unreviewed endpoint, verify the realm and recipient out-of-band. The resulting `[payments.mpp.merchants.*]` entry pins all of them before any typed data is signed.
+
+P0 supports only:
+
+- `wallet.kind = "evm-local"` or an equivalent wallet exposing `sign.typed_data`;
+- native MPP `b402.charge`;
+- B402's pinned BSC mainnet/testnet U facts;
+- EIP-3009;
+- one paid dispatch per call.
+
+TWAK's delegated `x402.pay` permission is not generic EIP-712 signing, and Altana's current session interface does not expose the required signing surface. Both must fail before payment.
+
+## Wire the agent tools
+
+```bash
+bag recipe code mpp-buyer
+```
+
+This emits `mppBuyer.ts` with `quote_mpp` and `buy_with_mpp`. Spread `MPP_BUYER_TOOLS` into the generated AgentCore or Azure Foundry AI SDK tool map. Runtime enforcement remains in `@bnbagent/studio-runtime/mpp`; the LLM can tighten `max_usd` but cannot widen configured merchant or daily caps or choose another recipient.
+
+## Unknown means stop
+
+After `Authorization: Payment` crosses the fetch boundary, a timeout, connection loss, or paid response without a successful `Payment-Receipt` is an `unknown` outcome. Studio records `mpp_buy` with status `unknown`. Do not retry automatically or tell the user to rerun blindly. Reconcile the wallet/facilitator/seller state first; another request can create another payment.
+
+Use `--local-dev` only for an operator-owned loopback endpoint. It permits plain HTTP and pins recipient plus realm from the live challenge for that invocation; it is not a production trust mechanism.

package/skills/references/bnbagent-studio-scaffolding-agent.md

@@ -70,7 +70,7 @@ The fields (give the user all of them at once):
 | 2 | **Network** | `bsc-testnet` / `bsc-mainnet` | `bsc-testnet` |
 | 3 | **LLM provider** | `pieverse-llm` / `openrouter` / `openai` / `anthropic` / `bedrock` | `pieverse-llm` |
 | 4 | **Wallet kind** (`--wallet-kind`) | `evm-local` (encrypted local keystore at the workspace root; `bag wallet new` creates it, `--private-key` imports an existing key; CodeZip deploy) / `twak` (**fully supported, opt in with `--wallet-kind twak`** - Trust Wallet Agent Kit CLI ≥0.20.0, self-custody encrypted mnemonic in a **project-dedicated** home `.studio/twak`, isolated from your main `~/.twak`; created manually with `HOME=<ws>/.studio/twak twak wallet create`, then `bag wallet new` adopts; container deploy. Reuse an existing wallet across agents with `--twak-home <path>`) / `altana` (bounded-session custody - admin keystore stays local, deploys ship ONLY the `ALTANA_SESSION` secret; zip deploy; not compatible with `pieverse-llm` or a paid b402 rail; flow: `references/bnbagent-studio-using-altana-wallet.md`) | `evm-local` |
-| 5 | **Storage** | `local` (file:// on disk, offline dev only, does **NOT** survive deploy) / `ipfs` (durable, public, deploy-ready; needs your pinning service's upload endpoint + write key as `STORAGE_API_URL` / `STORAGE_API_KEY` in `.studio/.env.local` **before the first real delivery** - see Step 6b) | `local` |
+| 5 | **Storage** | `local` (offline only) / `ipfs` / `s3` / `azure-blob`. Self-hosted deploys use BYOS credentials; managed-platform deploys receive an operator-owned storage endpoint and scoped token through the sealed runtime-secret channel. | `local` |
 | 6 | **Protocol faces** (`--protocols`) | any non-empty subset of `A2A`, `MCP`, `X402` | `A2A,X402` (`A2A` for Altana) |
 | 7 | **LLM model** | provider catalogue; for `pieverse-llm` the default `auto/free` runs at $0/token | `auto/free` |
 | 8 | **Auto-topup** | `enable` / `disable` - lets the Agent auto-pay $U from the wallet when LLM credits run low | deferred (non-interactive `bag init` records no `[budget]`; enable later with `bag budget enable`) |
@@ -126,7 +126,7 @@ Then execute Stage 2 **without further prompts** until you hit a step that genui
 
 ## Stage 2 - Generate a todo list (visible to the user)
 
-Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-step layout (evm-local default, Pieverse default LLM; plus a conditional Step 6b when `storage=ipfs`):
+Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-step layout (evm-local default, Pieverse default LLM; plus a conditional Step 6b for self-hosted durable storage):
 
 > **Step 0 - Pre-flight (informational; do NOT block `bag init` on it).** `bag init` self-renders the `agentcore/` deploy descriptor, and deploys delegate to the pinned `@bnbagent/deploy-cli` run via `bunx`, so Bun is only needed later, at `bag deploy` time. Do **not** re-check Node or `bag` (both are necessarily present - running the CLI required Node, and this skill only loads because `bag` is installed).
 >
@@ -139,6 +139,8 @@ Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-
 > **Onboarding note.** On a human TTY, `bag init` runs steps 3, 4 and 6 automatically (it prompts once for the wallet password, runs `bag wallet new`, zero-deposit-activates Pieverse, and prints faucet URLs). **You (Claude Code) drive `bag init` non-interactively**, so that auto-flow does NOT fire - keep steps 3/4/6 below. Pass `--no-onboard` to `bag init` to make this explicit and deterministic regardless of how the shell wires stdin.
 
 1. `bag init <name> --llm-provider <p> --network <n> --storage-provider <s> --wallet-kind <k> [--protocols <comma-list>] [--rails <8183|b402|both>] [--erc8183-price <base-units>] [--b402-price <usd>] --no-onboard` - scaffold the current workspace. **`<name>` must start with a letter, use ASCII letters and digits only, and be at most 23 characters.** `bag init` rejects `-`, `_`, `.`, and overlong names instead of renaming them. Pass `--wallet-kind evm-local` (default) or `--wallet-kind twak` (twak is fully supported - pass the flag to opt in), and `--storage-provider local` (default) or `ipfs`, per the Stage-1 choices; for twak, add `--twak-home <path>` ONLY if the user wants to reuse an existing wallet (otherwise omit - a project-dedicated `.studio/twak` is the safe default). Omit `--protocols` and `--rails` for the default A2A + X402 faces with both ERC-8183 and B402 rails (all wallet kinds, altana included — its paid B402 payout lands at the admin address). Pass either flag when the user chose another face/rail combination (`--protocol <one>` is only a legacy alias), add `--model <m>` only if the user overrode the provider default, and `--enable-auto-topup` / `--no-auto-topup` only if they made an explicit choice (otherwise omit - consent stays deferred). Pass `--erc8183-price 0` only when the user explicitly chose FREE; omitting the flag preserves the paid 0.1 U default. The canonical stack supports FREE; if a custom deployment is selected, set all three `ERC8183_COMMERCE_ADDRESS`, `ERC8183_ROUTER_ADDRESS`, and `ERC8183_POLICY_ADDRESS` values from that same stack. For B402, pass `--b402-price 0` only after the user explicitly accepts an unrestricted anonymous FREE `/x402` endpoint. FREE bypasses B402 verify/settle and needs no merchant credentials; a positive price keeps the `$0.01` default and requires the paid onboarding playbook. **Destination:** while the trial campaign runs, bare `bag init` (no `--destination`) defaults to `platform` - so pass `--destination self` **explicitly** whenever the user chose their own AWS, otherwise studio.toml silently records `platform` and the confirmation block you echoed no longer matches what was written. Omit `--destination` only when the user actually wants the `platform` 48h testnet trial (the campaign default) - do NOT treat that default as a mistake or re-confirm it; it is the intended behavior while the campaign is open. (Bare init also resolves to `self` once the campaign ends, or when `--network bsc-mainnet` / a non-agentcore `--runtime` is passed.) On the `platform` path `bag init` hard-forces `bsc-testnet`, pins `--runtime agentcore` + packages an artifact (a zip for the default evm-local and altana wallets, a container for twak). For evm-local a wallet key will later leave your machine, so pair it with a throwaway `bag wallet new`; for altana only the bounded session ships - do NOT create a new wallet (full flow: `docs/guides/platform-deploy.md`). Defaults `--runtime agentcore` (the only advertised runtime; the Preview `azure-foundry` runtime remains explicitly selectable but is outside this playbook; there is no `--framework` flag because the AI SDK model/tools story is part of the runtime templates). Creates `<name>/` workspace root + `<name>/app/agent/` (the single sub-project: A2A emits `src/unifiedMain.ts` (the express + A2A entrypoint, one code set for both deploy clouds) + `src/sellerCore.ts` (the protocol-neutral core; executor inherits it) + `src/executor.ts` + `src/agentCard.ts`; MCP emits `src/mcpMain.ts`; both include `src/signing.ts` + `src/tools.ts` + `src/model.ts` + their own `studio.toml` + `package.json` + `tsconfig.json`) + `<name>/agentcore/` (`agentcore.json` + `aws-targets.json`, self-rendered - no agentcore CLI needed at init). The workspace root holds the `agentcore/` deploy descriptor, the `.studio/wallets/` keystore, a thin `package.json` + `pnpm-workspace.yaml`, README, and `.gitignore`. (v1 is seller-only - no `--role`.)
+> **Current storage choices:** `--storage-provider` accepts `local`, `ipfs`, `s3`, and `azure-blob`. The latter three are BYOS only for self-hosted deployment; a managed-platform deployment replaces the writer with its injected API endpoint/token.
+>
 > **Altana + custom contracts:** Altana sessions remain bound to the canonical ERC-8183 targets. Use `evm-local` for a custom Commerce/Router/Policy stack; doctor and deploy readiness reject this unsupported combination when the ERC-8183 rail is active.
 
 2. `cd <name>`, then make sure the dependencies are installed. `bag init` already runs the install by default (skip only if it was scaffolded with `--no-install`); the manual equivalent from the workspace root is:
@@ -194,7 +196,7 @@ Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-
 
 6. **Activate Pieverse LLM** (only if `llm=pieverse-llm`, default): `bag llm activate` - **zero-deposit by default** (`--initial-usd` defaults to 0). SIWE-logs in with the agent wallet (an off-chain EIP-191 signature - no gas, no U), creates an `sk-pv-...` key with a $0 allocation, and writes `PIEVERSE_LLM_API_KEY` to `.env.local` + `key_hash` to studio.toml. The default model `auto/free` runs at $0/token, so **no funding is required to start**. Only when you switch to a paid model do you fund the wallet and run `bag llm topup --amount N` (then `[llm.auto_renew]` auto-**allocates** from your Pieverse Account Balance to the key below the floor; wallet U is spent only when `[budget]` has been explicitly enabled). For non-Pieverse providers, manually set the API key env var instead.
 
-   **Step 6b - Set the IPFS pinning credentials** (only when the user chose `storage=ipfs`; `bag init` defaults to `local`). With `--storage-provider ipfs` the Agent pins each deliverable to IPFS at delivery and publishes `ipfs://CID` on-chain (durable, public, deploy-ready). Works with **any** IPFS pinning service or a self-hosted node:
+   **Step 6b - Set self-hosted deliverable-storage credentials** (skip this for managed-platform deploys; the platform injects its own scoped upload token). With `--storage-provider ipfs` the self-hosted Agent pins each deliverable to IPFS at delivery and publishes `ipfs://CID` on-chain. Works with any IPFS pinning service or a self-hosted node:
 
    > Pick a pinning service and create a write key/JWT in its console (or run your own IPFS node - its `/api/v0/add` endpoint usually needs no key), then:
    >
@@ -203,7 +205,9 @@ Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-
    > bag env set STORAGE_API_KEY <your-write-key>
    > ```
    >
-   > Written to `.studio/.env.local`. **OPTIONAL to start** (scaffold, `bag dev`, and deploy all work without them) but **required before the first real delivery submits on-chain** - without them the Agent can't pin to IPFS and delivery fails. You can also pass `--ipfs-key <key>` to `bag init` upfront. `bag doctor` WARNs (never blocks) while they're unset. For pure offline dev with no IPFS, scaffold with `--storage-provider local` instead (writes `STORAGE_LOCAL_PATH`, no key - but does NOT survive deploy: the deployed agent and your dev box don't share a filesystem).
+   > Written to `.studio/.env.local`. They are required before deploy and the first real delivery. You can also pass `--ipfs-key <key>` to `bag init` upfront.
+
+   For self-hosted `s3`, fill `bucket`/`region` and set `DELIVERABLE_S3_ACCESS_KEY_ID` plus `DELIVERABLE_S3_SECRET_ACCESS_KEY`. For self-hosted `azure-blob`, fill `account_url`/`container` and set a write SAS or the complete namespaced service-principal variables scaffolded in `.studio/.env.local`. A `public_base_url` may point at the user's CloudFront/Azure Front Door/CDN; otherwise the bucket/container must itself allow anonymous reads. Never use a presigned/SAS URL for the public base. Canonical JSON deliverables are capped at 10 MiB before upload and are re-read/hash-verified through the public URL before on-chain submit. `credential_mode = "ambient"` is a runtime option, not an IAM/RBAC provisioner: the operator must grant the runtime identity write access. Managed-platform deploys ignore this BYOS writer configuration and use the API-injected storage endpoint/token. For pure offline dev, keep `local`.
 
 7. **Recipe code is already emitted by `bag init`** - the `app/agent/` sub-project plus its `studio.toml` is written by step 1, so **skip manual recipe emission**. To re-emit or inspect a recipe later, `bag recipe code agent` / `bag recipe code runtimes/agentcore` (emits under `{{PKG}}` = the agent's `src/` dir; pass `--pkg <name>` to override). The real work is editing the Agent's `runWork` hook in `app/agent/src/sellerCore.ts` (A2A) / `app/agent/src/mcpMain.ts` (MCP) (see `bnbagent-studio-selling-via-8183.md` in this same directory).
 8. **Verify**: `bag doctor` - confirms the scaffold + Pieverse key activation (if applicable) + config. Zero BNB / U are **WARN only** (not failures) - funding is optional (see step 5), so do NOT refuse to continue on a balance warning. Only refuse on real FAILs (missing keystore, unparseable config, etc.).
@@ -230,7 +234,7 @@ For each todo item:
 - Step 3 (password): the USER sets it **themselves, in their own terminal** - never through the chat or on a command line (see Step 3's security note). They edit `.studio/.env.local` and set `TWAK_WALLET_PASSWORD` (twak) or `WALLET_PASSWORD` (evm-local). `bag` auto-loads that file, so once it's set `bag wallet new` / `bag llm activate` pick it up - no `source`/`cd` needed. Wait for the user to confirm before continuing.
 - Step 5 (funding): OPTIONAL - only stop here if the user explicitly wants a paid LLM model, on-chain settle, or to pay ERC-8183 buys now. Otherwise skip; the `auto/free` default needs no funds.
 - Step 6 (Pieverse activation): zero-deposit, so it just works - no funding precheck needed. If `bag llm activate` fails on connectivity, retry once.
-- Step 6b (IPFS credentials): only when `storage=ipfs`. OPTIONAL now - do NOT block; the user picks a pinning service and runs `bag env set STORAGE_API_URL <url>` + `bag env set STORAGE_API_KEY <key>` themselves. Remind them they're required before the first real delivery (and `bag doctor` will keep WARNing until set). Skip entirely if they chose `local` storage.
+- Step 6b (deliverable storage): skip for `local` and for every managed-platform deploy. Self-hosted IPFS needs its write endpoint, S3 needs namespaced keys unless ambient identity is deliberately configured, and Azure Blob needs a write SAS/service principal unless ambient identity is deliberately configured. Do not ask for secret values in chat; have the user set them with `bag env set`. Self-hosted deploy readiness blocks incomplete storage configuration.
 - Business-logic step: ask the user what the Agent should produce when it delivers a job - the `runWork` hook in `app/agent/src/sellerCore.ts` (A2A) / `app/agent/src/mcpMain.ts` (MCP) is the developer hook. Leave the generic LLM passthrough stub if they don't know yet
 
 **Never** ask the user to `echo "KEY=VALUE" >> .env.local`. Always call `bag env set KEY VALUE` - it replaces the existing line if present, otherwise appends, so it's safe to run repeatedly.

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

@@ -175,7 +175,7 @@ Older contracts may have required a manual `withdraw` - confirm against the depl
 
 ## How a buyer reads the deliverable
 
-The agent serves **no** job-query endpoint. The buyer reads the deliverable back from the on-chain submission (the `submit` tx carries the deterministic `deliverable_url`) / the IPFS object. This is by design - the chain is the shared source of truth, and the agent stays a thin A2A surface.
+The agent serves **no** job-query endpoint. The buyer reads the stable `deliverable_url` from the on-chain submission, then fetches the content-addressed object from IPFS, self-hosted S3/Blob, or the managed API proxy. This is by design - the chain is the shared source of truth, and the agent stays a thin A2A surface.
 
 ## Common errors + remediation
 

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

@@ -89,7 +89,7 @@ B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the agen
 
    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.
 
-4. **Self-hosted Azure Foundry egress (self-deploys)**: Foundry hosted-agent containers have floating egress just like AgentCore, so the agent must NOT call the facilitator directly. Run the envelope gateway on a Container Apps workload-profiles environment whose subnet has a NAT Gateway with a Standard static public IP, co-host a restricted B402 forwarder there (the AWS guide's Relay example works verbatim — the NAT Gateway replaces its fixed-IP host requirement), point the runtime `B402_BASE_URL` at that forwarder, and submit the NAT Gateway IP. The environment type and VNet cannot be changed after creation; see the [Azure external-gateway reference](bnbagent-studio-use-azure-foundry.md#x402-external-gateway). Studio does not deploy or manage that Azure network.
+4. **Self-hosted Azure Foundry egress (self-deploys)**: Foundry hosted-agent containers have floating egress just like AgentCore, so the agent must NOT call the facilitator directly. Run the envelope gateway on a Container Apps workload-profiles environment whose subnet has a NAT Gateway with a Standard static public IP, co-host a restricted B402 forwarder there (the AWS guide's Relay example works verbatim — the NAT Gateway replaces its fixed-IP host requirement), point the runtime `B402_BASE_URL` at that forwarder, and submit the NAT Gateway IP. The environment type and VNet cannot be changed after creation; the full recipe (subnet sizing, ingress caveats, minReplicas) is in the [Azure self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway-azure.md). Studio does not deploy or manage that Azure 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 and confirm the platform environment with the operator.
 

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

@@ -1,6 +1,6 @@
 ---
 name: bnbagent-studio-use-aws-agentcore
-description: When the user wants to deploy or operate a bnbagent-studio project on AWS Bedrock AgentCore - deploy with `bag deploy --provider aws` (all cloud lifecycle mutations are delegated to pinned `@bnbagent/deploy-cli@0.5.13`), inspect with `bag deploy status` / `logs --provider aws` / `verify --provider aws`, and tear down with `bag deploy destroy --provider aws --execute [--purge]`. Also covers AWS credential prerequisites, the optional read-only quota probe, and the runtime-secret channel.
+description: When the user wants to deploy or operate a bnbagent-studio project on AWS Bedrock AgentCore - deploy with `bag deploy --provider aws` (all cloud lifecycle mutations are delegated to pinned `@bnbagent/deploy-cli@0.5.15`), inspect with `bag deploy status` / `logs --provider aws` / `verify --provider aws`, and tear down with `bag deploy destroy --provider aws --execute [--purge]`. Also covers AWS credential prerequisites, the optional read-only quota probe, and the runtime-secret channel.
 ---
 
 > **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.