@bnbagent/studio-cli 0.0.13-alpha.6 → 0.0.13-alpha.8

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

@@ -40,6 +40,7 @@
 import { ERC8183JobOps } from "@bnbagent/sdk/erc8183";
 import { SubmitPermanentlyUnsupportedError } from "@bnbagent/studio-runtime/erc8183";
 import { getWallet } from "@bnbagent/studio-runtime/wallet";
+import { limitCommerceOperation } from "./requestLimits.js";
 import * as defaultSigning from "./signing.js";
 
 const log = {
@@ -227,6 +228,7 @@ export class SellerCore {
     data: Record<string, unknown>,
   ): Promise<Record<string, unknown>> {
     this.requireCommerceRail();
+    await limitCommerceOperation("negotiate");
     let request = data.request;
     if (request === null || typeof request !== "object" || Array.isArray(request)) {
       const picked: Record<string, unknown> = {};
@@ -262,6 +264,7 @@ export class SellerCore {
     data: Record<string, unknown>,
   ): Promise<Record<string, unknown>> {
     this.requireCommerceRail();
+    await limitCommerceOperation("notify_funded");
     const raw = data.job_id;
     if (raw === undefined || raw === null || String(raw) === "") {
       this.spawn(() => this.sweep()); // bare notify → just scan stragglers

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

@@ -95,6 +95,7 @@ import express from "express";
 import { buildAgentCard } from "./agentCard.js";
 import { SellerAgentExecutor } from "./executor.js";
 import { buildModel } from "./model.js";
+import { requestLimitContext } from "./requestLimits.js";
 import type { RunWork } from "./sellerCore.js";
 import { LLM_READ_TOOLS } from "./tools.js";
 
@@ -500,6 +501,7 @@ async function main(): Promise<void> {
   );
 
   const app = express();
+  app.use(requestLimitContext);
 
   // GET /ping status fed to AgentCore: HEALTHY_BUSY while a background
   // delivery is in flight, else HEALTHY.

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.3",
+    "@bnbagent/sdk@0.5.5",
     # 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}}/executor.ts.tmpl

@@ -43,6 +43,7 @@ import {
   type ExecutionEventBus,
   type RequestContext,
 } from "@a2a-js/sdk/server";
+import { isCommerceRateLimitError } from "./requestLimits.js";
 import { SellerCore } from "./sellerCore.js";
 
 const log = {
@@ -94,9 +95,10 @@ export class SellerAgentExecutor extends SellerCore implements AgentExecutor {
     } catch (e) {
       // a skill failure must still ACK the buyer
       log.error(`skill ${JSON.stringify(skill)} failed`, e);
-      const name = e instanceof Error ? e.constructor.name : "Error";
-      const msg = e instanceof Error ? e.message : String(e);
-      return { error: `${name}: ${msg}`, skill };
+      if (isCommerceRateLimitError(e)) {
+        return { status: "retry", error: "seller rate limit exceeded", skill };
+      }
+      return { error: "seller operation failed; retry later", skill };
     }
   }
 
@@ -135,9 +137,15 @@ export class SellerAgentExecutor extends SellerCore implements AgentExecutor {
       // returned as a result above (peer of the MCP runtime: faults →
       // isError, business outcomes → result).
       log.error(`skill ${JSON.stringify(skill)} failed`, e);
-      const name = e instanceof Error ? e.constructor.name : "Error";
-      const msg = e instanceof Error ? e.message : String(e);
-      throw A2AError.internalError(`${name}: ${msg}`);
+      if (isCommerceRateLimitError(e)) {
+        result = {
+          status: "retry",
+          error: "seller rate limit exceeded",
+          skill,
+        };
+      } else {
+        throw A2AError.internalError("seller operation failed; retry later");
+      }
     }
     reply(eventBus, context, result);
   };

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

@@ -79,6 +79,11 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { generateText, stepCountIs } from "ai";
 import express from "express";
 import { z } from "zod";
+import {
+  isCommerceRateLimitError,
+  limitCommerceOperation,
+  requestLimitContext,
+} from "./requestLimits.js";
 import * as signing from "./signing.js";
 
 const APP_NAME = "agent";
@@ -88,6 +93,11 @@ const log = {
     console.error(`[seller-agent.mcp] ERROR ${msg}`, e ?? ""),
 };
 
+function protocolFailure(scope: string, error: unknown): never {
+  log.error(scope, error);
+  throw new Error("seller operation failed; retry later");
+}
+
 // ── Runtime secrets ───────────────────────────────────────────────────────────
 // Keep plaintext secrets OUT of agentcore.json. When BNBAGENT_RUNTIME_SECRET_ID
 // is set (deployed runtime), pull a JSON {ENV_NAME: value} blob from AWS
@@ -296,16 +306,24 @@ export function buildMcpServer(
       annotations: COMMERCE_ANNOTATIONS,
     },
     // Error contract (unified with the A2A executor): an unexpected fault
-    // here (wallet/signing failure) is left to PROPAGATE — the MCP SDK turns
-    // it into a tool result with `isError: true` (MCP's tool-execution-error
-    // channel), the peer of the A2A executor throwing
-    // `A2AError.internalError` → JSON-RPC -32603. Only CLASSIFIED business
-    // outcomes are returned as a normal result. So do NOT wrap this in a
-    // try/catch that masks a fault as a successful quote.
+    // becomes an MCP `isError` result with a generic public message; its full
+    // detail is logged server-side. Classified quota exhaustion is returned
+    // as a normal retry result and never as a fake quote.
     async ({ task_description, terms }) => {
-      const request = { task_description, terms: terms ?? {} };
-      const clamped = signing.clampPrice(signing.listPrice());
-      return toolResult(await signing.signQuote(request, clamped));
+      try {
+        await limitCommerceOperation("negotiate");
+        const request = { task_description, terms: terms ?? {} };
+        const clamped = signing.clampPrice(signing.listPrice());
+        return toolResult(await signing.signQuote(request, clamped));
+      } catch (e) {
+        if (isCommerceRateLimitError(e)) {
+          return toolResult({
+            status: "retry",
+            reason: "seller rate limit exceeded",
+          });
+        }
+        return protocolFailure("negotiate failed", e);
+      }
     },
     );
 
@@ -327,6 +345,17 @@ export function buildMcpServer(
       annotations: COMMERCE_ANNOTATIONS,
     },
     async ({ job_id }, extra) => {
+      try {
+        await limitCommerceOperation("notify_funded");
+      } catch (e) {
+        if (isCommerceRateLimitError(e)) {
+          return toolResult({
+            status: "retry",
+            reason: "seller rate limit exceeded",
+          });
+        }
+        return protocolFailure("notify_funded limiter failed", e);
+      }
       let jid: number;
       try {
         jid = parseJobId(job_id);
@@ -348,40 +377,43 @@ export function buildMcpServer(
       } catch (e) {
         // a failed verify is transient; tell the buyer to retry
         log.error(`verify of job ${jid} failed`, e);
-        const name = e instanceof Error ? e.constructor.name : "Error";
-        const msg = e instanceof Error ? e.message : String(e);
         return toolResult({
           status: "retry",
           job_id: jid,
-          reason: `${name}: ${msg}`,
+          reason: "chain verification temporarily unavailable",
         });
       }
       if (!verdict.ok) {
         return toolResult({
           status: verdict.permanent ? "rejected" : "retry",
           job_id: jid,
-          reason: verdict.reason,
+          reason: verdict.permanent
+            ? verdict.reason
+            : "chain verification temporarily unavailable",
         });
       }
 
       // 2/4 — produce the deliverable (THE ONLY LLM CALL; specialise the
       // prompt here)
       await reportProgress(extra, 2, 4);
-      const spec = await signing.jobSpec(jid);
-      const task =
-        spec !== null
-          ? JSON.stringify({ task: spec.task, terms: spec.terms })
-          : `job ${jid}`;
-      const prompt =
-        "You accepted and were paid for the following job. Produce the deliverable " +
-        `now. Be complete and self-contained.\n\nJOB CONTEXT:\n${task}`;
-      // An unexpected fault below (LLM unavailable, RPC/submit hiccup) is
-      // left to PROPAGATE — the MCP SDK returns it as an isError tool result
-      // (the peer of the A2A executor's internalError/-32603). Only the
-      // deterministic, classified outcome SubmitPermanentlyUnsupportedError
-      // is a "rejected" business result.
-      const work = await runLlm(prompt);
-
+      let work: string;
+      try {
+        const spec = await signing.jobSpec(jid);
+        const task =
+          spec !== null
+            ? JSON.stringify({ task: spec.task, terms: spec.terms })
+            : `job ${jid}`;
+        const prompt =
+          "You accepted and were paid for the following job. Produce the deliverable " +
+          `now. Be complete and self-contained.\n\nJOB CONTEXT:\n${task}`;
+        work = await runLlm(prompt);
+      } catch (e) {
+        return protocolFailure(`delivery preparation for job ${jid} failed`, e);
+      }
+      // Unexpected LLM/RPC faults are logged in full, then surfaced through
+      // MCP's isError channel with a generic public message. Only the
+      // deterministic SubmitPermanentlyUnsupportedError is a classified
+      // "rejected" business result.
       // 3/4 — sign + broadcast the on-chain submit (re-verifies FUNDED inside)
       await reportProgress(extra, 3, 4);
       let res: { submitTx: string; deliverableUrl: string | null };
@@ -401,10 +433,10 @@ export function buildMcpServer(
             status: "rejected",
             job_id: jid,
             skip: true,
-            reason: e.message,
+            reason: "seller wallet does not support result submission",
           });
         }
-        throw e;
+        return protocolFailure(`submit of job ${jid} failed`, e);
       }
 
       // 4/4 — done
@@ -606,6 +638,7 @@ async function main(): Promise<void> {
   });
 
   const app = express();
+  app.use(requestLimitContext);
 
   if (seller.state !== "disabled") {
     app.all(

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

@@ -0,0 +1,178 @@
+/**
+ * Application-level quotas for the two public seller operations.
+ *
+ * A process-wide bucket is always enforced, including when the hosting
+ * platform exposes no trustworthy caller identity. A second per-caller
+ * bucket is enabled only when the operator names a header that its trusted
+ * edge sets after stripping caller-supplied values. Request payload fields
+ * and forwarded IP headers are deliberately never treated as identities.
+ * The defaults are process-local; multi-replica owners can inject async
+ * shared limiters without making that infrastructure mandatory.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { RateLimitExceeded, SlidingWindowLimiter } from "@bnbagent/sdk/utils";
+import type { NextFunction, Request, Response } from "express";
+
+type CommerceOperation = "negotiate" | "notify_funded";
+
+const DEFAULT_GLOBAL_MAX = 120;
+const DEFAULT_CALLER_MAX = 20;
+const DEFAULT_WINDOW_SECONDS = 60;
+const DEFAULT_MAX_CALLERS = 10_000;
+const SHARED_LIMITER_TIMEOUT_MS = 5_000;
+
+export interface CommerceRateLimiter {
+  /** Consume one request; honor cancellation and reject denied requests. */
+  check(key: string, signal?: AbortSignal): void | Promise<void>;
+}
+
+export interface CommerceRateLimiters {
+  readonly global: CommerceRateLimiter;
+  readonly caller: CommerceRateLimiter;
+}
+
+interface CachedLimiters extends CommerceRateLimiters {
+  readonly configKey: string;
+}
+
+const callerContext = new AsyncLocalStorage<string | undefined>();
+let cached: CachedLimiters | undefined;
+let injected: CommerceRateLimiters | undefined;
+let warnedProcessLocal = false;
+
+/** Replace process-local counters with application-owned shared limiters. */
+export function setCommerceRateLimiters(
+  value: CommerceRateLimiters | null,
+): void {
+  injected = value ?? undefined;
+}
+
+function positiveEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || !/^\d+$/u.test(raw)) return fallback;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+function limiters(): CommerceRateLimiters {
+  if (injected) return injected;
+  const environment = (
+    process.env.ENV ||
+    process.env.ENVIRONMENT ||
+    process.env.NODE_ENV ||
+    ""
+  )
+    .trim()
+    .toLowerCase();
+  if (
+    !warnedProcessLocal &&
+    !["dev", "development", "test"].includes(environment)
+  ) {
+    warnedProcessLocal = true;
+    console.warn(
+      "[seller-agent] this process is using process-local rate limits; " +
+        "inject shared limiters or enforce equivalent limits at a trusted edge before scaling out.",
+    );
+  }
+  const names = [
+    "SELLER_RATE_LIMIT_GLOBAL_MAX_REQUESTS",
+    "SELLER_RATE_LIMIT_CALLER_MAX_REQUESTS",
+    "SELLER_RATE_LIMIT_WINDOW_SECONDS",
+    "SELLER_RATE_LIMIT_MAX_CALLERS",
+  ] as const;
+  const configKey = names.map((name) => process.env[name] ?? "").join("\0");
+  if (cached?.configKey === configKey) return cached;
+
+  const windowSeconds = positiveEnv(
+    "SELLER_RATE_LIMIT_WINDOW_SECONDS",
+    DEFAULT_WINDOW_SECONDS,
+  );
+  cached = {
+    configKey,
+    global: new SlidingWindowLimiter(
+      positiveEnv("SELLER_RATE_LIMIT_GLOBAL_MAX_REQUESTS", DEFAULT_GLOBAL_MAX),
+      windowSeconds,
+      2,
+    ),
+    caller: new SlidingWindowLimiter(
+      positiveEnv("SELLER_RATE_LIMIT_CALLER_MAX_REQUESTS", DEFAULT_CALLER_MAX),
+      windowSeconds,
+      positiveEnv("SELLER_RATE_LIMIT_MAX_CALLERS", DEFAULT_MAX_CALLERS),
+    ),
+  };
+  return cached;
+}
+
+async function checkLimiter(
+  limiter: CommerceRateLimiter,
+  key: string,
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const controller = new AbortController();
+  try {
+    await Promise.race([
+      Promise.resolve(limiter.check(key, controller.signal)),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () => {
+            controller.abort();
+            reject(new RateLimitExceeded("Seller rate limiter unavailable"));
+          },
+          SHARED_LIMITER_TIMEOUT_MS,
+        );
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+function trustedCaller(headers: Request["headers"]): string | undefined {
+  const header = (process.env.SELLER_TRUSTED_CALLER_HEADER ?? "")
+    .trim()
+    .toLowerCase();
+  if (!/^[a-z0-9-]+$/u.test(header)) return undefined;
+
+  const raw = headers[header];
+  if (typeof raw !== "string") return undefined;
+  const value = raw.trim();
+  if (value.length === 0 || value.length > 256 || /[\r\n]/u.test(value)) {
+    return undefined;
+  }
+  return value;
+}
+
+/** Carry only an operator-configured, edge-authenticated identity. */
+export function withTrustedCaller<T>(
+  headers: Request["headers"],
+  work: () => T,
+): T {
+  return callerContext.run(trustedCaller(headers), work);
+}
+
+/** Express middleware that makes the trusted identity available to handlers. */
+export function requestLimitContext(
+  req: Request,
+  _res: Response,
+  next: NextFunction,
+): void {
+  withTrustedCaller(req.headers, next);
+}
+
+/** Consume both the mandatory process bucket and optional caller bucket. */
+export async function limitCommerceOperation(
+  operation: CommerceOperation,
+): Promise<void> {
+  const active = limiters();
+  await checkLimiter(active.global, operation);
+  const caller = callerContext.getStore();
+  if (caller !== undefined) {
+    await checkLimiter(active.caller, `${operation}:${caller}`);
+  }
+}
+
+export function isCommerceRateLimitError(error: unknown): boolean {
+  return error instanceof RateLimitExceeded;
+}

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

@@ -40,6 +40,7 @@
 import { ERC8183JobOps } from "@bnbagent/sdk/erc8183";
 import { SubmitPermanentlyUnsupportedError } from "@bnbagent/studio-runtime/erc8183";
 import { getWallet } from "@bnbagent/studio-runtime/wallet";
+import { limitCommerceOperation } from "./requestLimits.js";
 import * as defaultSigning from "./signing.js";
 
 const log = {
@@ -227,6 +228,7 @@ export class SellerCore {
     data: Record<string, unknown>,
   ): Promise<Record<string, unknown>> {
     this.requireCommerceRail();
+    await limitCommerceOperation("negotiate");
     let request = data.request;
     if (request === null || typeof request !== "object" || Array.isArray(request)) {
       const picked: Record<string, unknown> = {};
@@ -262,6 +264,7 @@ export class SellerCore {
     data: Record<string, unknown>,
   ): Promise<Record<string, unknown>> {
     this.requireCommerceRail();
+    await limitCommerceOperation("notify_funded");
     const raw = data.job_id;
     if (raw === undefined || raw === null || String(raw) === "") {
       this.spawn(() => this.sweep()); // bare notify → just scan stragglers

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

@@ -95,6 +95,7 @@ import express from "express";
 import { buildAgentCard } from "./agentCard.js";
 import { SellerAgentExecutor } from "./executor.js";
 import { buildModel } from "./model.js";
+import { requestLimitContext } from "./requestLimits.js";
 import type { RunWork } from "./sellerCore.js";
 import { LLM_READ_TOOLS } from "./tools.js";
 
@@ -500,6 +501,7 @@ async function main(): Promise<void> {
   );
 
   const app = express();
+  app.use(requestLimitContext);
 
   // GET /ping status fed to AgentCore: HEALTHY_BUSY while a background
   // delivery is in flight, else HEALTHY.

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.3",
+    "@bnbagent/sdk@0.5.5",
     # 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/wallet/recipe.toml

@@ -7,7 +7,6 @@ node = ["@bnbagent/studio-runtime"]
 
 [dependencies.altana]
 node = ["@altananetwork/sdk@0.7.1"]
-
 [dependencies.turnkey]
 node = ["@turnkey/sdk-server@8.1.0", "@turnkey/viem@0.14.34"]
 

package/recipes/x402-buyer/recipe.toml

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

package/skills/references/bnbagent-studio-adding-to-project.md

@@ -74,7 +74,7 @@ Tune the price in `app/agent/studio.toml` (`[payments.erc8183]` `min_price`/ `ma
 
 Use `bag config set payments.erc8183.price 0` only for an explicit FREE product decision. Studio stores ERC-8183 amounts as decimal strings and reports FREE in `bag doctor`; the canonical stack supports zero funding. If a custom deployment is selected, set all three `ERC8183_*_ADDRESS` overrides from that same stack. The buyer still runs `setBudget(0)` and `fund(0)`, but no ERC-20 approval or token escrow occurs. Require `bag doctor` and `bag deploy prepare` to pass.
 
-For an X402 face, choose its request price independently. Use `bag config set payments.x402_seller.price_usd 0` only when the existing agent is intentionally becoming an unrestricted anonymous FREE API. This path bypasses B402 verify/settle, payment, and settlement audit; it needs no merchant credentials and Studio will not synchronize any configured B402 secrets. Positive prices retain the paid B402 onboarding and settle-before-work flow. Verify the choice with `bag x402 sell status`, `bag doctor`, and `bag deploy prepare`.
+For an X402 face, choose its request price independently. Use `bag config set payments.b402_seller.price_usd 0` only when the existing agent is intentionally becoming an unrestricted anonymous FREE API. This path bypasses B402 verify/settle, payment, and settlement audit; it needs no merchant credentials and Studio will not synchronize any configured B402 secrets. Positive prices retain the paid B402 onboarding and settle-before-work flow. Verify the choice with `bag x402 sell status`, `bag doctor`, and `bag deploy prepare`.
 
 ## Step 4c - LLM credit continuity (automatic, NOT an LLM tool)
 

package/skills/references/bnbagent-studio-operating.md

@@ -164,7 +164,7 @@ JobStatus enum: `OPEN` (0) → `FUNDED` (1) → `SUBMITTED` (2) → `COMPLETED`
 | Job stays `FUNDED`, never reaches `SUBMITTED` after an `accepted` ack | Background delivery failed (`runWork` / `submitResult` raised) - **not** visible in the A2A reply | The ack only confirms verify passed; delivery runs in the background. Observe the failure via the chain (job never leaves `FUNDED`) + CloudWatch logs; a later `notify_funded` re-attempts it via the sweep |
 | `ERC8183JobOps` has no such export from `@bnbagent/sdk` | package.json pinned an old `@bnbagent/sdk` (missing class) | Bump the dependency and reinstall |
 | ERC-8183 contract override is incomplete | Only one or two of commerce/router/policy were selected | Set or remove all three together; never mix stacks |
-| `/x402` is public without a 402 challenge | `payments.x402_seller.price_usd = "0"` selected anonymous FREE passthrough | If payment is intended, set a positive decimal price, configure the complete B402 credential set, rerun `bag doctor`, and redeploy |
+| `/x402` is public without a 402 challenge | `payments.b402_seller.price_usd = "0"` selected anonymous FREE passthrough | If payment is intended, set a positive decimal price, configure the complete B402 credential set, rerun `bag doctor`, and redeploy |
 | B402 credentials are missing but x402 reports FREE | Expected: FREE bypasses B402 and does not synchronize its secrets | No credential fix is needed; change to a positive price only when the route should charge |
 | `OPENROUTER_API_KEY env var is required` | Loading the entrypoint triggers the emitted `buildModel()` factory | Set the env var even for `bag dev --help` smoke |
 | RPC `limit exceeded` | Public RPC throttle | Retry, or set `STUDIO_BSC_TESTNET_RPC=<private rpc>` |

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

@@ -14,7 +14,7 @@ Use this playbook to activate the x402 seller rail for one agent. First choose P
 - 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: 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`.
+- `[payments.b402_seller]` exists. If not, run `bag x402 sell init`.
 
 The PAID application uses the **agent wallet address**, not a developer treasury, buyer wallet, or platform wallet.
 
@@ -25,7 +25,7 @@ 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
+bag config set payments.b402_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.
@@ -161,7 +161,7 @@ On the managed platform the deploy summary must say `x402 rail is ACTIVE` (or `A
 - Never log or print any B402 value or private key.
 - Never put a B402 value in `studio.toml` or a deploy descriptor.
 - 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.
+- 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 with `@bnb-chain/b402@0.2.1` does not yet perform that poll; it classifies pending as unknown. Version 0.2.1 separately guards credential replays through an atomic store. Do not claim current mainnet readiness until polling is implemented.
 - Settlement happens before work. A later work failure retains the payment and does not trigger an automatic refund.
 - The rail activates on AgentCore and Azure Foundry targets (managed platform or self-hosted); self-hosted targets have no anonymous URL and need an operator-run envelope-v1 front.
 - Every supported `wallet.kind` can be the PAID B402 payout wallet: `evm-local`, `twak`, `turnkey`, and `altana`. The payout lands at the configured `pay_to` or, by default, `[wallet].address`; for altana that address is the admin EOA (EIP-7702 — the smart account address equals the admin address), so the locally-held admin keystore can always move the revenue. Register the B402 merchant credentials for that exact address. FREE x402 bypasses B402 and has no payout.

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

@@ -11,6 +11,7 @@ Altana separates trusted administration from runtime authority:
 - `.studio/wallets/altana-session.json` is the one bounded, expiring runtime session and must stay mode `0600`.
 - `WALLET_PASSWORD` is admin-only. The Agent gets `ALTANA_SESSION`, never the password or admin keystore.
 - Generic signing is refused. ERC-8183 uses `sessionQuoteSigner()` and the approved quote checker.
+- The generated project pins `@bnbagent/sdk@0.5.5` and `@altananetwork/sdk@0.7.1`; doctor, readiness, and runtime loading reject version drift. SDK 0.5.4 introduced selector-bound calls, removed session-key token approvals, and requires an admin-provisioned bounded Commerce allowance. Projects upgrading from an older SDK must update it, re-grant with `bag wallet session grant --force`, and redeploy.
 - Deployment ships ONLY the serialized session as the `ALTANA_SESSION` runtime secret; the admin keystore and `WALLET_PASSWORD` never leave the operator machine. Renewal after expiry: `bag wallet session grant --force`, then re-run `bag deploy`. Readiness fails on a missing/expired/address-mismatched session, a group/world-readable session file, a session inside the artifact root, or an unresolvable project-local `@altananetwork/sdk`; it warns under 7 days remaining. `bag deploy verify` needs `--skip-register` (no generic signing for the ERC-8004 register).
 - Altana refuses generic message signing, so Pieverse SIWE cannot authenticate `bag llm activate` or runtime credit renewal. `bag init --wallet-kind altana --llm-provider pieverse-llm` is rejected outright; use OpenRouter, OpenAI, or Anthropic (API-key providers). `bag llm activate` and `bag doctor` also flag the combination on projects edited by hand.
 
@@ -34,13 +35,13 @@ bag dev
 
 Interactive grant recommendations are 10 U/day, 30 days, register=yes. In a non-TTY, pass `--budget-u`, `--expiry-days`, optional `--no-register`, and `--yes`. Stdout from a successful grant is only the session public key.
 
-If quote-checker approval fails after the paid grant, the owner-only session file is preserved. Repair it with:
+The grant persists the owner-only session, provisions a Commerce allowance no higher than its U-token cap, and approves the quote checker. Every relay-backed management write must return `CONFIRMED`; `PENDING` fails closed and preserves the session file. If either setup step fails after the paid grant, repair both with:
 
 ```bash
 bag wallet session grant --approve-only
 ```
 
-Replace with `grant --force`; the old on-chain revoke must succeed before the new grant begins. Revoke with `bag wallet session revoke --yes`; the file is deleted only after chain success.
+`--approve-only`, runtime loading, and deploy readiness reject pre-0.5.4 target-wide sessions. Replace one with `grant --force`; Studio zeros the old Commerce allowance before revoking, and both operations must be confirmed before the new grant begins. Revoke with `bag wallet session revoke --yes`; the file is deleted only after both confirmations.
 
 x402 buying remains separate and exact-bounded: