@bnbagent/studio-cli 0.0.12 → 0.0.13-alpha.1

package/dist/{chunk-RNWAADXU.js → chunk-RSM3RMDD.js}

@@ -21,8 +21,15 @@ import { stringify as tomlStringify } from "smol-toml";
 import { createHash } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
+import {
+  TURNKEY_SDK_SERVER_PACKAGE,
+  TURNKEY_VIEM_PACKAGE
+} from "@bnbagent/sdk/wallets";
 import { loadStudioToml } from "@bnbagent/studio-runtime/config";
-import { resolveProjectAltanaSdkEntry } from "@bnbagent/studio-runtime/wallet";
+import {
+  resolveProjectAltanaSdkEntry,
+  resolveProjectTurnkeySdkEntry
+} from "@bnbagent/studio-runtime/wallet";
 import { build as esbuildBuild } from "esbuild";
 
 // src/cli/utils/protocol.ts
@@ -141,6 +148,7 @@ async function buildZip(agentDir, outZip, opts = {}) {
     stageManifest(agentDir, buildRoot, entrypoint);
     stageStudioToml(agentDir, buildRoot);
     await stageAltanaSdk(agentDir, buildRoot, opts.bundle ?? bundleEntry);
+    await stageTurnkeySdk(agentDir, buildRoot, opts.bundle ?? bundleEntry);
     assertWithinUncompressedCap(
       buildRoot,
       opts.maxUncompressedBytes ?? MAX_UNCOMPRESSED_BYTES
@@ -277,7 +285,7 @@ async function stageAltanaSdk(agentDir, buildRoot, bundle) {
   }
   if (entry === null) {
     throw new Error(
-      "wallet.kind='altana' but @altananetwork/sdk is not resolvable from the agent project \u2014 the zip runtime could never load the Altana session wallet. Run `pnpm add @altananetwork/sdk@0.5.1` in app/agent, or deploy as a container."
+      "wallet.kind='altana' but @altananetwork/sdk is not resolvable from the agent project \u2014 the zip runtime could never load the Altana session wallet. Run `pnpm add @altananetwork/sdk@0.7.1` in app/agent, or deploy as a container."
     );
   }
   const pkgDir = path.join(buildRoot, "node_modules", "@altananetwork", "sdk");
@@ -288,7 +296,7 @@ async function stageAltanaSdk(agentDir, buildRoot, bundle) {
     `${JSON.stringify(
       {
         name: "@altananetwork/sdk",
-        version: altanaSdkVersionOf(entry),
+        version: packageVersionOf(entry, "@altananetwork/sdk"),
         private: true,
         type: "module",
         main: "index.js"
@@ -299,14 +307,76 @@ async function stageAltanaSdk(agentDir, buildRoot, bundle) {
 `
   );
 }
-function altanaSdkVersionOf(entry) {
+async function stageTurnkeySdk(agentDir, buildRoot, bundle) {
+  let kind = "evm-local";
+  try {
+    const cfg = loadStudioToml(path.join(agentDir, "studio.toml"));
+    const wallet = cfg.wallet;
+    if (wallet !== null && typeof wallet === "object" && !Array.isArray(wallet)) {
+      kind = String(wallet.kind ?? "evm-local");
+    }
+  } catch {
+  }
+  if (kind !== "turnkey") {
+    return;
+  }
+  const packageNames = [
+    TURNKEY_SDK_SERVER_PACKAGE,
+    TURNKEY_VIEM_PACKAGE
+  ];
+  const entries = /* @__PURE__ */ new Map();
+  try {
+    for (const packageName of packageNames) {
+      const entry = resolveProjectTurnkeySdkEntry(agentDir, packageName);
+      if (entry !== null) {
+        entries.set(packageName, entry);
+      }
+    }
+  } catch (exc) {
+    throw new Error(
+      `wallet.kind='turnkey' zip build: ${exc instanceof Error ? exc.message : exc}`
+    );
+  }
+  if (entries.size !== packageNames.length) {
+    const missing = packageNames.filter((name) => !entries.has(name));
+    throw new Error(
+      `wallet.kind='turnkey' zip build: missing ${missing.join(", ")}; install both Turnkey packages in app/agent: pnpm add ${TURNKEY_SDK_SERVER_PACKAGE} ${TURNKEY_VIEM_PACKAGE}, or deploy as a container.`
+    );
+  }
+  for (const packageName of packageNames) {
+    const entry = entries.get(packageName);
+    const packageDir = path.join(
+      buildRoot,
+      "node_modules",
+      ...packageName.split("/")
+    );
+    fs.mkdirSync(packageDir, { recursive: true });
+    await bundle(entry, path.join(packageDir, "index.js"));
+    fs.writeFileSync(
+      path.join(packageDir, "package.json"),
+      `${JSON.stringify(
+        {
+          name: packageName,
+          version: packageVersionOf(entry, packageName),
+          private: true,
+          type: "module",
+          main: "index.js"
+        },
+        null,
+        2
+      )}
+`
+    );
+  }
+}
+function packageVersionOf(entry, packageName) {
   let cursor = path.dirname(entry);
   for (let i = 0; i < 4; i += 1) {
     const manifest = path.join(cursor, "package.json");
     if (isFile(manifest)) {
       try {
         const pkg = JSON.parse(fs.readFileSync(manifest, "utf-8"));
-        if (pkg.name === "@altananetwork/sdk") {
+        if (pkg.name === packageName) {
           return typeof pkg.version === "string" ? pkg.version : "0.0.0";
         }
       } catch {
@@ -686,8 +756,8 @@ function packageRoot() {
   }
 }
 function studioCliVersion() {
-  if ("0.0.12") {
-    return "0.0.12";
+  if ("0.0.13-alpha.1") {
+    return "0.0.13-alpha.1";
   }
   const file = path3.join(packageRoot(), "package.json");
   const pkg = JSON.parse(fs3.readFileSync(file, "utf-8"));

package/dist/{deployCli-RWRR6XWO.js → deployCli-BY3ILBEP.js}

@@ -18,7 +18,7 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-RNWAADXU.js";
+} from "./chunk-RSM3RMDD.js";
 import "./chunk-RO726HJG.js";
 export {
   BNB_PLATFORM_API_URL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bnbagent/studio-cli",
-  "version": "0.0.12",
+  "version": "0.0.13-alpha.1",
   "description": "Skills-first toolkit and bag CLI for BNB Chain seller agents: ERC-8004 identity, ERC-8183 escrowed commerce, and x402 payments.",
   "keywords": [
     "bnb-chain",
@@ -25,7 +25,6 @@
     "directory": "packages/studio-cli"
   },
   "type": "module",
-  "packageManager": "pnpm@10.24.0",
   "engines": {
     "node": ">=22"
   },
@@ -42,16 +41,8 @@
   "bin": {
     "bag": "./dist/bag.js"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "lint": "biome check src tests",
-    "typecheck": "tsc --noEmit",
-    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
-  },
   "dependencies": {
-    "@bnbagent/sdk": "0.5.0",
-    "@bnbagent/studio-runtime": "0.0.12",
+    "@bnbagent/sdk": "0.5.2-alpha.1",
     "ai": "^7.0.29",
     "archiver": "^8.0.0",
     "commander": "^15.0.0",
@@ -62,7 +53,8 @@
     "smol-toml": "^1.3.0",
     "tar": "^7.4.0",
     "viem": "^2.54.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "@bnbagent/studio-runtime": "0.0.13-alpha.1"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",
@@ -78,5 +70,12 @@
     "typescript": "^5.5.0",
     "vitest": "^2.0.0",
     "zod": "^3.25.76"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "biome check src tests",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
   }
-}
+}

package/recipes/agent/recipe.toml

@@ -11,7 +11,7 @@ node = [
     # neutral. The agent project's serving deps (@a2a-js/sdk / MCP SDK / ai)
     # come from the runtimes/<R>/ recipe selected at `bag init` time.
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.0",
+    "@bnbagent/sdk@0.5.2-alpha.1",
 ]
 
 [env]

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.0",
+    "@bnbagent/sdk@0.5.2-alpha.1",
     # 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/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.0",
+    "@bnbagent/sdk@0.5.2-alpha.1",
     # 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

@@ -1,17 +1,22 @@
 [recipe]
 name = "wallet"
-description = "Configures the agent's wallet: 'evm-local' (default encrypted keystore), 'twak' (Trust Wallet Agent Kit CLI), or 'altana' (encrypted admin keystore plus one bounded runtime session)."
+description = "Configures the agent's wallet: 'evm-local' (default encrypted keystore), 'twak' (Trust Wallet Agent Kit CLI), 'altana' (encrypted admin keystore plus one bounded runtime session), or 'turnkey' (remote signer; the key lives in Turnkey's AWS Nitro enclave)."
 
 [dependencies]
 node = ["@bnbagent/studio-runtime"]
 
 [dependencies.altana]
-node = ["@altananetwork/sdk@0.5.1"]
+node = ["@altananetwork/sdk@0.7.1"]
+
+[dependencies.turnkey]
+node = ["@turnkey/sdk-server@8.1.0", "@turnkey/viem@0.14.34"]
 
 [env]
 # kind='twak': the twak CLI reads the unlock password from the environment —
 # it never goes on a command line.
 TWAK_WALLET_PASSWORD = "unlocks ~/.twak/wallet.json (twak kind); set in .studio/.env.local"
+# kind='turnkey': P-256 API credential; the signing key never leaves Turnkey's enclave.
+TURNKEY_API_PRIVATE_KEY = "Turnkey P-256 API private key (turnkey kind); set in .studio/.env.local"
 # kind='evm-local' (the `bag init` default) or kind='altana' admin operations:
 WALLET_PASSWORD = "set to a strong password (>= 12 chars); encrypts .studio/wallets/<addr>.json (runtime never receives it for altana)"
 

package/recipes/x402-buyer/recipe.toml

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

package/skills/bnbagent-studio.md

@@ -5,7 +5,7 @@ description: The single entry point for bnbagent-studio - a TypeScript CLI (`bag
 
 # bnbagent-studio (the single entry point)
 
-`bnbagent-studio` (CLI: `bag`) wires the `@bnbagent/sdk` protocol layer (wallet / ERC-8004 / ERC-8183 / Pieverse LLM) into a TypeScript agent project, then deploys it as a **single blockchain seller runtime**. A2A, MCP, and X402 are composable public faces selected with `--protocols`; the default evm-local/twak scaffold serves A2A + X402 with both ERC-8183 and B402 rails, while Altana defaults to A2A + ERC-8183 because paid B402 is unsupported. `bag deploy` uses **scheme C**: every new deploy or redeploy explicitly selects BNB, AWS, or Azure; a recorded deployment is used only to offer an explicit update action, never as a silent default. BNB is a 48h testnet trial and is disabled after expiry. AWS and Azure self-deploy into the user's own account. All cloud lifecycle mutations go through the pinned `@bnbagent/deploy-cli`; the optional AWS CLI is used only by the fail-open, read-only AgentCore quota check in `bag deploy prepare`. AgentCore and Azure Foundry share the unified A2A/X402 entrypoint; Azure rejects MCP. Treat an incompatible provider row as unavailable-do not force through it or mutate the scaffold during deploy.
+`bnbagent-studio` (CLI: `bag`) wires the `@bnbagent/sdk` protocol layer (wallet / ERC-8004 / ERC-8183 / Pieverse LLM) into a TypeScript agent project, then deploys it as a **single blockchain seller runtime**. A2A, MCP, and X402 are composable public faces selected with `--protocols`; every wallet kind scaffolds A2A + X402 with both ERC-8183 and B402 rails by default (for altana the paid B402 payout lands at the admin address). `bag deploy` uses **scheme C**: every new deploy or redeploy explicitly selects BNB, AWS, or Azure; a recorded deployment is used only to offer an explicit update action, never as a silent default. BNB is a 48h testnet trial and is disabled after expiry. AWS and Azure self-deploy into the user's own account. All cloud lifecycle mutations go through the pinned `@bnbagent/deploy-cli`; the optional AWS CLI is used only by the fail-open, read-only AgentCore quota check in `bag deploy prepare`. AgentCore and Azure Foundry share the unified A2A/X402 entrypoint; Azure rejects MCP. Treat an incompatible provider row as unavailable-do not force through it or mutate the scaffold during deploy.
 
 Invoked as `/bnbagent-studio <ask>`? Treat `<ask>` as the user's intent and route it through the decision tree below, exactly like a natural-language ask.
 

package/skills/references/bnbagent-studio-buying-from-bazaar.md

@@ -51,6 +51,8 @@ verified = true                                         # studio-reviewed shelf
 
 Hard-stop cases: a reviewed merchant whose live payTo drifts from the studio pin (address rotation or tampering - upgrade studio or verify out-of-band and pass `--pay-to`), and `--cap` below the live per-call price.
 
+Wallet kinds and rails: `evm-local` signs EIP-3009 locally; `twak` and `altana` route through a delegated payer that prefers the merchant's permit2 route. Altana smart-account payments are verified by the B402 facilitator on its permit2 rails (live since 2026-08, CMC field-verified) and need the one-time `bag wallet session x402-setup` arming (checker approval + bounded U→Permit2 allowance) - `bag doctor` shows the arming state as `[wallet] Altana x402 buying`.
+
 ## Step 2 - wire the buyer tools into the agent
 
 ```bash
@@ -99,7 +101,8 @@ bag dev        # then ask the agent something that needs the paid data
 | `X402RecipientRequiredError` | No pinned recipient for that host → same fix |
 | `X402RecipientMismatchError` | Live payTo drifted from the pin - do NOT override casually; re-verify the merchant |
 | `X402BudgetExhaustedError` | Per-call cap or daily budget hit - raise `per_call_cap_usd` / `[budget].max_per_day_usd` deliberately |
-| `x402 402 has no EIP-3009-payable option` | Merchant offers only permit2/other methods for $U on this network - not payable by this buyer today |
+| `x402 402 has no EIP-3009-payable option` | Merchant offers only permit2/other methods for $U on this network - a local-signing (`evm-local`) buyer cannot sign those. Delegated wallets pay permit2 routes through their own client: `twak` (mainnet), or `altana` sessions (ERC-1271; B402 verifies them on the permit2 rails - arm once with `bag wallet session x402-setup`) |
+| `U→Permit2 allowance … cannot cover max_usd` | Altana only: the bounded Permit2 allowance is spent/too small - re-run `bag wallet session x402-setup --allowance-u <amount>` (admin key) |
 | `X402PolicyError` / `PolicyViolation` | Signing allowlist - see `bnbagent-studio-extending-signing.md` |
 
 **Different from**:

package/skills/references/bnbagent-studio-extending-signing.md

@@ -61,7 +61,7 @@ The user wants the agent to pay e.g. `api.example.com` via x402.
 2. The service uses **EIP-3009 `TransferWithAuthorization`** (or `ReceiveWithAuthorization`). If it uses Permit2 or a custom primary type → goes to Section B.
 3. The token contract address on BSC is known and the user can confirm it. Don't guess from a token symbol - look up the deployed address.
 
-If any of (1)-(3) fail, **stop and tell the user**. The current release cannot integrate cross-chain services or non-EIP-3009 payment rails. Do not work around it; the SigningPolicy will refuse the request.
+If any of (1)-(3) fail, **stop and tell the user**. The current release cannot integrate cross-chain services or non-EIP-3009 payment rails into the LOCAL signer. Do not work around it; the SigningPolicy will refuse the request. (Merchants that only offer permit2 are still payable without touching SigningPolicy - through a delegated wallet kind: `twak`, or `altana` sessions, whose ERC-1271 signatures B402 verifies on its permit2 rails. That is a wallet-kind choice, not a signing extension.)
 
 **Steps when (1)-(3) all pass:**
 

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

@@ -136,7 +136,7 @@ The `--all` form is the right move when `app/agent/studio.toml`'s `[network].def
 
 `bag doctor` prints ERC-8183 pricing as `PAID` or `FREE`. FREE works on the canonical contract stack. If a custom deployment is selected, set `ERC8183_COMMERCE_ADDRESS`, `ERC8183_ROUTER_ADDRESS`, and `ERC8183_POLICY_ADDRESS` together; a partial set fails because it can mix incompatible commerce, router, and policy deployments.
 
-For the inbound x402 seller rail, `bag doctor` also prints `PAID` or `FREE`. PAID requires the complete B402 merchant credential set and an `evm-local` or `twak` payout wallet. Explicit zero is anonymous FREE passthrough: it does not read B402 credentials, call the facilitator, settle a payment, or apply the paid-mode payout-wallet allowlist. Confirm the same state with `bag x402 sell status`.
+For the inbound x402 seller rail, `bag doctor` also prints `PAID` or `FREE`. PAID requires the complete B402 merchant credential set; any supported wallet kind can be the payout wallet (for altana the payout lands at the admin address anchored as `[wallet].address`). Explicit zero is anonymous FREE passthrough: it does not read B402 credentials, call the facilitator, settle a payment, or apply the paid-mode payout-wallet allowlist. Confirm the same state with `bag x402 sell status`.
 
 > The current CLI has no `bag wallet transfer`, `bag erc20 approve/allowance` group, or `bag wallet balance --address` / `--token` flag. Running them returns an invalid-command or unknown-option error. Use an external wallet to move funds or set allowances; ERC-8183 funding auto-approves U as part of the buy flow.
 

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

@@ -138,14 +138,14 @@ 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; Altana instead defaults to A2A + ERC-8183 because paid B402 is unsupported. 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`.)
+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`.)
 > **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:
    ```bash
    pnpm install        # npm install works too - tooling is the user's choice
    ```
-   The sub-project's `package.json` carries its deps: `@bnbagent/studio-runtime` (the runtime lib, pinned to the scaffolding CLI's version range - NOT the CLI itself) + `@bnbagent/sdk` + `ai` (the AI SDK) plus the **protocol-specific** group - A2A adds `@a2a-js/sdk` + `express`, MCP adds `@modelcontextprotocol/sdk` instead (an A2A-only deploy never ships the MCP SDK, and an MCP-only deploy never ships the A2A one). For local dev against unreleased libs, `bag init` vendors local `.tgz` tarballs and points the manifest at them automatically.
+   The sub-project's `package.json` carries its deps: `@bnbagent/studio-runtime` (the runtime lib, pinned to the scaffolding CLI's exact version - NOT the CLI itself) + `@bnbagent/sdk` + `ai` (the AI SDK) plus the **protocol-specific** group - A2A adds `@a2a-js/sdk` + `express`, MCP adds `@modelcontextprotocol/sdk` instead (an A2A-only deploy never ships the MCP SDK, and an MCP-only deploy never ships the A2A one). For local dev against unreleased libs, `bag init` vendors local `.tgz` tarballs and points the manifest at them automatically.
 3. **Set the wallet password** - the USER does this, NOT you.
 
    🔒 **SECURITY - never route the wallet password through the chat.** It encrypts the key material that is the Agent's sole signing key. Do **NOT** ask the user to type it into the chat, and do **NOT** run any command with the password on the command line (`bag env set <PW_VAR> <literal>`, `twak wallet create --password <literal>`, …) - it would land in the session transcript, be sent to the model API, and hit shell history / `ps`.

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

@@ -144,7 +144,7 @@ When the credentials, IP allowlist, and facilitator environment are ready, run t
 bag x402 sell status
 ```
 
-For a sandbox/trial agent, it must find exact/eip3009 U on `eip155:97`. For production it must find the mainnet environment expected by the project. A network mismatch is not safe to ignore.
+For a sandbox/trial agent, it must find an exact U kind on `eip155:97` (the probe lists the offered rails, e.g. `(eip3009, permit2-exact)`). For production it must find the mainnet environment expected by the project. A network mismatch is not safe to ignore.
 
 Run the deployment gate, then redeploy to activate the selected mode:
 
@@ -164,5 +164,6 @@ On the managed platform the deploy summary must say `x402 rail is ACTIVE` (or `A
 - 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 and Azure Foundry targets (managed platform or self-hosted); self-hosted targets have no anonymous URL and need an operator-run envelope-v1 front.
-- 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.
+- 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.
+- Buyer compatibility: the 402 challenge advertises both `exact` rails - `eip3009` (EOA buyers, no pre-authorization) and `permit2-exact` (B402 verifies ERC-1271 smart-account signatures on this rail, so Altana sessions and ERC-4337 wallets can pay; the buyer needs a bounded U→Permit2 allowance first - see `bnbagent-studio-using-altana-wallet.md`). Rails are filtered against the facilitator's live `/supported`; `bag x402 sell status` prints which rails it actually offers, e.g. `(eip3009, permit2-exact)`. The seller never verifies signatures locally on either rail.
 - Never describe FREE as a zero-value B402 settlement. It bypasses B402.

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

@@ -48,6 +48,8 @@ x402 buying remains separate and exact-bounded:
 bag wallet session x402-setup --allowance-u <U> --yes
 ```
 
-Altana cannot be the b402 **seller** payout wallet for a positive price (paid mode allows `evm-local` and `twak` only); init, `bag x402 sell init`, and deploy readiness reject that paid combination. Explicit `price_usd = "0"` is allowed because FREE passthrough performs no payout and bypasses B402. The outbound buying authority above remains a separate feature.
+Once armed, `bag x402 buy` pays b402-facilitated merchants (e.g. CoinMarketCap) end to end: B402 verifies the session's ERC-1271 signature on its **permit2 rails** (live since 2026-08). Studio's own b402 sellers advertise `permit2-exact` alongside `eip3009`, so Altana wallets can pay studio-hosted merchants too; eip3009-only merchants still need a 65-byte EOA signature and cannot be paid by a smart account. The buy preflight checks the U→Permit2 allowance against the spend cap, and `bag doctor` reports `[wallet] Altana x402 buying`. Use `@altananetwork/sdk` 0.7.1 in the project.
+
+Altana can also be the b402 **seller** payout wallet for a positive price: the payout lands at `[wallet].address`, which for an EIP-7702 altana account is the admin EOA, so the locally-held admin keystore can always move the revenue. Issue the B402 merchant credentials for that exact address. Explicit `price_usd = "0"` stays FREE passthrough (no payout, bypasses B402). The outbound buying authority above remains a separate feature.
 
 For troubleshooting, run `bag doctor` and `bag wallet session status`. Do not print, parse, or copy the `signer` portion of the serialized session, and never move `.studio/wallets/` under `app/agent/`.