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

package/dist/bag.js

@@ -52,7 +52,7 @@ import {
   x402SellerIsFree,
   x402SellerPricingState,
   x402SellerUsesB402
-} from "./chunk-AT2UYK5U.js";
+} from "./chunk-APRWJKEA.js";
 import {
   TWAK_CLI_MIN_VERSION,
   TWAK_CLI_VERSION,
@@ -230,7 +230,7 @@ import {
 var CAMPAIGN_DOC_URL = "https://www.bnbchain.org/en/blog/bnb-agent-studio-is-live-on-bnb-chain-ai-agents-from-one-prompt";
 var CAMPAIGN_CHECK_TIMEOUT_MS = 6e3;
 async function fetchCampaignActive() {
-  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-LBDK2B4U.js");
+  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-HCI42S6E.js");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), CAMPAIGN_CHECK_TIMEOUT_MS);
   try {
@@ -2823,6 +2823,19 @@ var ERC20_BALANCE_ABI = [
     outputs: [{ name: "", type: "uint256" }]
   }
 ];
+var ERC20_ALLOWANCE_ABI = [
+  {
+    type: "function",
+    name: "allowance",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" }
+    ],
+    outputs: [{ name: "", type: "uint256" }]
+  }
+];
+var PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
 function client(networkName) {
   const net2 = getNetwork(networkName);
   return createPublicClient({ transport: http(net2.rpcUrl) });
@@ -2851,6 +2864,20 @@ async function readUBalanceRaw(address, networkName) {
   });
   return raw;
 }
+async function readUAllowanceRaw(owner, spender, networkName) {
+  const net2 = getNetwork(networkName);
+  const uToken = net2.tokens.U;
+  if (uToken === void 0) {
+    return null;
+  }
+  const raw = await client(networkName).readContract({
+    address: getAddress(uToken.address),
+    abi: ERC20_ALLOWANCE_ABI,
+    functionName: "allowance",
+    args: [getAddress(owner), getAddress(spender)]
+  });
+  return raw;
+}
 async function readTransactionSeen(txHash, networkName) {
   try {
     await client(networkName).getTransaction({
@@ -3729,7 +3756,7 @@ function checkAltanaSdkResolvable(root, _target) {
       level: Level.CRITICAL,
       name: "altana_sdk_resolvable",
       message: `@altananetwork/sdk is not resolvable from the agent project${failure ? ` (${failure})` : ""} \u2014 the deployed runtime cannot build the Altana session wallet at cold start.`,
-      fixCmd: "pnpm add @altananetwork/sdk@0.5.1",
+      fixCmd: "pnpm add @altananetwork/sdk@0.7.1",
       details: failure ? { error: failure } : {}
     }
   ];
@@ -4708,6 +4735,28 @@ var managedAzureFoundryChecks = [
   checkAltanaSessionNotInsideAgent
 ];
 
+// src/cli/_turnkeyGuidance.ts
+function turnkeySetupGuidance() {
+  return `
+Turnkey setup (official CLI: https://docs.turnkey.com/sdks/cli):
+  1. In the dashboard's top-right user menu, copy the Organization ID into
+     TURNKEY_ORG_ID.
+  2. Generate a P-256 API key locally, then register its public key under
+     User Details -> Create API keys:
+       turnkey generate api-key --organization "$TURNKEY_ORG_ID" --key-name bnbagent-studio
+     Set TURNKEY_API_PUBLIC_KEY to the generated public key and
+     TURNKEY_API_PRIVATE_KEY to its locally generated private key. Keep the
+     private key out of argv, logs, and source control.
+  3. Create a wallet and an Ethereum account:
+       turnkey wallets create --name bnbagent-studio --key-name bnbagent-studio
+       turnkey wallets accounts create --wallet bnbagent-studio --address-format ADDRESS_FORMAT_ETHEREUM --key-name bnbagent-studio
+  4. Set TURNKEY_SIGN_WITH to the returned 0x Ethereum account address. It is
+     not a Turnkey wallet id (UUID).
+  5. Store all four TURNKEY_* values in the owner-only .studio/.env.local,
+     then run \`(cd app/agent && bag wallet new)\` to validate and anchor the
+     address. No signing key is created or downloaded by bag.`;
+}
+
 // src/cli/llm.ts
 import * as fs18 from "fs";
 import * as path17 from "path";
@@ -7389,7 +7438,8 @@ function cmdNewTurnkey(projectRoot) {
   const signWith = String(process.env.TURNKEY_SIGN_WITH ?? "").trim();
   if (signWith === "") {
     printErr(
-      "error: TURNKEY_SIGN_WITH is not set (wallet.kind = 'turnkey').\nCreate a wallet account in the Turnkey dashboard, set the TURNKEY_* credentials in .studio/.env.local (bag auto-loads it), then re-run `bag wallet new` to adopt + anchor the address."
+      `error: TURNKEY_SIGN_WITH is not set (wallet.kind = 'turnkey').
+${turnkeySetupGuidance()}`
     );
     return 1;
   }
@@ -10091,8 +10141,8 @@ function printTurnkeyNotice() {
     `
 NOTE \u2014 wallet.kind = "turnkey" (remote signer, keys in Turnkey's AWS Nitro enclave):
  \xB7 WALLET: no key material exists locally \u2014 the Agent signs via the TURNKEY_*
-   API credentials in .studio/.env.local (dashboard \u2192 API keys). Set them,
-   then run \`(cd app/agent && bag wallet new)\` to adopt + anchor the address.
+   API credentials in .studio/.env.local.
+${turnkeySetupGuidance()}
  \xB7 BILLING: every successful signature is billed (free tier: 25/month at
    1 request/second; pay-as-you-go $0.10 each) \u2014 budget accordingly.
  \xB7 PRODUCTION: use a NON-ROOT API user restricted by an explicit ALLOW policy;
@@ -11626,6 +11676,9 @@ async function checkLocalKeystoreExists(root, _target) {
   if (walletCfg.kind === "altana") {
     return [];
   }
+  if (walletCfg.kind === "turnkey") {
+    return [];
+  }
   const signer = walletCfg.signer ?? "local";
   if (signer !== "local") {
     return [];
@@ -11651,6 +11704,9 @@ async function checkWalletPasswordEnvSet(root, _target) {
   if (kind === "altana") {
     return [];
   }
+  if (kind === "turnkey") {
+    return [];
+  }
   if (process.env.WALLET_PASSWORD) {
     return [];
   }
@@ -12274,6 +12330,46 @@ function awsJson(stdout) {
     return null;
   }
 }
+async function checkAwsAccountMatchesTarget(root, target) {
+  if (target !== "agentcore") {
+    return [];
+  }
+  const [targetAccount, region] = readAwsTarget(root);
+  if (!targetAccount || !region || !await whichBin("aws")) {
+    return [];
+  }
+  const identity = await runCapture("aws", [
+    "sts",
+    "get-caller-identity",
+    "--region",
+    region,
+    "--output",
+    "json"
+  ]);
+  if (identity.code !== 0) {
+    return [];
+  }
+  const rawAccount = awsJson(identity.stdout)?.Account;
+  const credentialAccount = typeof rawAccount === "string" && /^\d{12}$/.test(rawAccount.trim()) ? rawAccount.trim() : null;
+  if (credentialAccount === null || credentialAccount === targetAccount) {
+    return [];
+  }
+  const targetPath = path24.join(root, "agentcore", "aws-targets.json");
+  return [
+    {
+      level: Level.CRITICAL,
+      name: "aws_account_mismatch",
+      message: `active AWS credentials resolve to account ${credentialAccount}, but agentcore/aws-targets.json pins account ${targetAccount}. The delegated deploy rejects this mismatch before provisioning. Switch credentials, or update the local target file after confirming which account should own the deployment.`,
+      details: {
+        credential_account: credentialAccount,
+        target_account: targetAccount,
+        region,
+        path: targetPath
+      },
+      fixCmd: `# edit agentcore/aws-targets.json and set the default account to ${credentialAccount}, or switch the active AWS credentials`
+    }
+  ];
+}
 async function checkAgentcoreQuotaHeadroom(root, target) {
   if (target !== "agentcore") {
     return [];
@@ -12379,6 +12475,7 @@ var allChecks = [
   checkDeployCliRunnable,
   checkRuntimeSecretsInjected,
   checkAwsTargetsPopulated,
+  checkAwsAccountMatchesTarget,
   checkAgentcoreQuotaHeadroom
 ];
 
@@ -15190,6 +15287,15 @@ function printAgentClientPrompt(root, invokeUrl, status) {
     );
   }
   const endpointBlock = endpoints.join("\n");
+  const commerceShapeLines = hasA2aFace(faces) ? [
+    "MESSAGE SHAPES (complete A2A JSON-RPC requests)",
+    '- negotiate: {"jsonrpc":"2.0","id":"request-1","method":"message/send","params":{"message":{"messageId":"message-1","role":"user","parts":[{"kind":"data","data":{"skill":"negotiate","task_description":"<what you want done>","terms":{"deliverables":"...","quality_standards":"..."}}}]}}}',
+    '- notify_funded: {"jsonrpc":"2.0","id":"request-2","method":"message/send","params":{"message":{"messageId":"message-2","role":"user","parts":[{"kind":"data","data":{"skill":"notify_funded","job_id":123}}]}}}'
+  ] : [
+    "MCP TOOL ARGUMENTS",
+    '- negotiate: {"task_description":"<what you want done>","terms":{"deliverables":"...","quality_standards":"..."}}',
+    '- notify_funded: {"job_id":123}'
+  ];
   const lines = [
     "",
     CLIENT_PROMPT_RULE,
@@ -15222,9 +15328,7 @@ function printAgentClientPrompt(root, invokeUrl, status) {
       "- Remote ERC-8183 callers need an OAuth2 access token:",
       tokenSteps,
       "",
-      "MESSAGE SHAPES",
-      '- negotiate: {"skill":"negotiate","task_description":"<what you want done>","terms":{"deliverables":"...","quality_standards":"..."}}',
-      '- notify_funded: {"skill":"notify_funded","job_id":<int>}'
+      ...commerceShapeLines
     ] : [
       "- The anonymous x402 route does not use the OAuth2 token flow shown for ERC-8183."
     ],
@@ -16671,6 +16775,28 @@ async function printAgentClientPrompt2(root, destination, opts = {}) {
         The invoke URL carries a querystring (?qualifier=...): never
         string-concatenate extra path segments onto it \u2014 that produces
         an invalid URL and an HTTP 405.`;
+  const commerceShapeLines = hasA2aFace(faces) ? [
+    "MESSAGE SHAPES (complete A2A JSON-RPC requests)",
+    '- negotiate: {"jsonrpc":"2.0","id":"request-1","method":"message/send","params":{"message":{"messageId":"message-1","role":"user","parts":[{"kind":"data","data":{"skill":"negotiate","task_description":"<what you want done>","terms":{"deliverables":"...","quality_standards":"..."}}}]}}}',
+    '- notify_funded: {"jsonrpc":"2.0","id":"request-2","method":"message/send","params":{"message":{"messageId":"message-2","role":"user","parts":[{"kind":"data","data":{"skill":"notify_funded","job_id":123}}]}}}'
+  ] : [
+    "MCP TOOL ARGUMENTS",
+    '- negotiate: {"task_description":"<what you want done>","terms":{"deliverables":"...","quality_standards":"..."}}',
+    '- notify_funded: {"job_id":123}'
+  ];
+  const mcpSessionLines = hasA2aFace(faces) && hasMcpFace(faces) ? [
+    "",
+    "MCP SESSION FLOW (A2A+MCP through envelope-v1)",
+    "  1) Keep X-Amzn-Bedrock-AgentCore-Runtime-Session-Id on every outer InvokeAgentRuntime request; this is the outer AgentCore runtime session.",
+    "  2) Send an envelope-v1 POST /mcp whose decoded body is the MCP initialize request, with no inner mcp-session-id header.",
+    '  3) Decode the envelope response and read headers["mcp-session-id"]; this is the inner MCP session, separate from the outer header.',
+    "  4) Send notifications/initialized, then tools/list or tools/call in new envelopes whose inner headers carry that same mcp-session-id."
+  ] : hasMcpFace(faces) ? [
+    "",
+    "MCP SESSION FLOW",
+    "  1) Send initialize without mcp-session-id and capture the response mcp-session-id header.",
+    "  2) Send notifications/initialized, then tools/list or tools/call with that header."
+  ] : [];
   const lines = [
     "",
     CLIENT_PROMPT_RULE2,
@@ -16700,9 +16826,8 @@ async function printAgentClientPrompt2(root, destination, opts = {}) {
       "- Remote ERC-8183 callers need an OAuth2 access token:",
       tokenSteps,
       "",
-      "MESSAGE SHAPES",
-      '- negotiate: {"skill":"negotiate","task_description":"<what you want done>","terms":{"deliverables":"...","quality_standards":"..."}}',
-      '- notify_funded: {"skill":"notify_funded","job_id":<int>}'
+      ...commerceShapeLines,
+      ...mcpSessionLines
     ] : [
       "- The anonymous x402 route does not use the OAuth2 token flow shown for ERC-8183."
     ],
@@ -17955,7 +18080,7 @@ function checkWalletTurnkey(walletCfg) {
   }
   return out;
 }
-function checkWalletAltana(walletCfg, projectRoot, data) {
+async function checkWalletAltana(walletCfg, projectRoot, data) {
   const out = [];
   const contracts = erc8183ContractOverrideState(
     erc8183ContractEnvForProject(projectRoot)
@@ -18041,13 +18166,41 @@ function checkWalletAltana(walletCfg, projectRoot, data) {
     out.push({
       name: "[wallet] Altana SDK",
       status: entry === null ? FAIL : PASS,
-      detail: entry === null ? "@altananetwork/sdk is not resolvable from this project \u2014 run `pnpm add @altananetwork/sdk@0.5.1`" : entry
+      detail: entry === null ? "@altananetwork/sdk is not resolvable from this project \u2014 run `pnpm add @altananetwork/sdk@0.7.1`" : entry
     });
   } catch (error) {
     out.push({
       name: "[wallet] Altana SDK",
       status: FAIL,
-      detail: `${error instanceof Error ? error.message : String(error)} \u2014 run \`pnpm add @altananetwork/sdk@0.5.1\``
+      detail: `${error instanceof Error ? error.message : String(error)} \u2014 run \`pnpm add @altananetwork/sdk@0.7.1\``
+    });
+  }
+  const networkName = String(tableOf14(data, "network").default ?? "bsc-mainnet");
+  try {
+    const allowanceRaw = await readUAllowanceRaw(
+      address,
+      PERMIT2_ADDRESS,
+      networkName
+    );
+    if (allowanceRaw !== null) {
+      const uToken = getNetwork9(networkName).token("U");
+      out.push(
+        allowanceRaw > 0n ? {
+          name: "[wallet] Altana x402 buying",
+          status: PASS,
+          detail: `U\u2192Permit2 allowance ${fromRaw3(allowanceRaw, uToken.decimals)} U on ${networkName} (b402 permit2 rail armed)`
+        } : {
+          name: "[wallet] Altana x402 buying",
+          status: WARN,
+          detail: `no U\u2192Permit2 allowance on ${networkName} \u2014 outbound x402 buying is not armed; run \`bag wallet session x402-setup --allowance-u <amount>\` (admin key) if this agent should pay b402 merchants`
+        }
+      );
+    }
+  } catch (error) {
+    out.push({
+      name: "[wallet] Altana x402 buying",
+      status: WARN,
+      detail: `could not read the U\u2192Permit2 allowance on ${networkName}: ${error instanceof Error ? error.message : String(error)}`
     });
   }
   return out;
@@ -21461,16 +21614,21 @@ async function cmdSellStatus(probe) {
   }
   try {
     const supported = await _probeB402Supported(process.env);
-    const methodKind = supported?.kinds.find(
-      (kind) => kind.x402Version === 2 && kind.scheme === "exact" && kind.network === network && kind.extra.assetTransferMethod === "eip3009"
+    const matching = (method) => supported?.kinds.find(
+      (kind) => kind.x402Version === 2 && kind.scheme === "exact" && kind.network === network && kind.extra.assetTransferMethod === method && kind.extra.name === token.eip712Name && kind.extra.version === token.eip712Version
     );
-    if (methodKind && methodKind.extra.name === token.eip712Name && methodKind.extra.version === token.eip712Version) {
-      printOut(`B402 probe: exact/eip3009 U available for ${network}`);
+    const available = token.methods.filter(
+      (method) => matching(method) !== void 0
+    );
+    if (available.length > 0) {
+      const missing = token.methods.filter((m) => !available.includes(m));
+      printOut(
+        `B402 probe: exact U available for ${network} (${available.join(", ")})${missing.length > 0 ? ` \u2014 advertised but not offered by the facilitator: ${missing.join(", ")}` : ""}`
+      );
       return 0;
     }
-    const observed = methodKind ? `observed name=${String(methodKind.extra.name ?? "(missing)")} version=${String(methodKind.extra.version ?? "(missing)")}` : "no exact/eip3009 kind was returned";
     printOut(
-      `B402 probe: mismatch for ${network}; expected name=${token.eip712Name} version=${token.eip712Version}; ${observed}. Check that the credentials belong to the matching B402 environment.`
+      `B402 probe: mismatch for ${network}; expected an exact kind (${token.methods.join(" or ")}) with name=${token.eip712Name} version=${token.eip712Version}; none was returned. Check that the credentials belong to the matching B402 environment.`
     );
   } catch {
     printOut(
@@ -21599,6 +21757,30 @@ async function cmdBuy2(url, opts) {
     );
     return 1;
   }
+  const buyWalletKind = String(tableOf16(cfg, "wallet").kind ?? "evm-local");
+  if (buyWalletKind === "altana") {
+    let allowanceRaw;
+    try {
+      allowanceRaw = await readUAllowanceRaw(
+        wallet.address,
+        PERMIT2_ADDRESS,
+        networkName
+      );
+    } catch (exc) {
+      printErr(`error: permit2 allowance check failed: ${errMsg6(exc)}`);
+      return 1;
+    }
+    if (allowanceRaw !== null && allowanceRaw < neededRaw) {
+      const uToken = getNetwork11(networkName).token("U");
+      printErr(
+        `error: U\u2192Permit2 allowance ${fromRaw5(allowanceRaw, uToken.decimals)} U cannot cover max_usd $${opts.maxUsd.toFixed(2)}: b402 settles Altana payments by pulling through Permit2 (${PERMIT2_ADDRESS}).`
+      );
+      printErr(
+        "fix: bag wallet session x402-setup --allowance-u <amount>   (admin key; approves the x402 signature checker and sets the bounded Permit2 allowance)"
+      );
+      return 1;
+    }
+  }
   let result;
   try {
     result = await auditedOp4(
@@ -21638,7 +21820,7 @@ async function cmdBuy2(url, opts) {
   }
   const paidUsd = result.paidUsd ?? 0;
   const envelope = result.txPaymentEnvelope ?? "";
-  const envelopePreview = envelope ? `${envelope.slice(0, 40)}...` : "(no payment \u2014 server did not 402)";
+  const envelopePreview = envelope ? `${envelope.slice(0, 40)}...` : result.paidUsd !== null ? "(delegated x402 client \u2014 the envelope never leaves the wallet client)" : "(no payment \u2014 server did not 402)";
   const ok = result.statusCode >= 200 && result.statusCode < 300;
   if (result.paidUsd === null) {
     if (ok) {

package/dist/{chunk-AT2UYK5U.js → chunk-APRWJKEA.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-alpha.1") {
-    return "0.0.12-alpha.1";
+  if ("0.0.12-alpha.3") {
+    return "0.0.12-alpha.3";
   }
   const file = path3.join(packageRoot(), "package.json");
   const pkg = JSON.parse(fs3.readFileSync(file, "utf-8"));

package/dist/{deployCli-LBDK2B4U.js → deployCli-HCI42S6E.js}

@@ -18,7 +18,7 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-AT2UYK5U.js";
+} from "./chunk-APRWJKEA.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-alpha.1",
+  "version": "0.0.12-alpha.3",
   "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",
@@ -42,7 +42,7 @@
     "bag": "./dist/bag.js"
   },
   "dependencies": {
-    "@bnbagent/sdk": "0.5.1-alpha.2",
+    "@bnbagent/sdk": "0.5.1-alpha.3",
     "ai": "^7.0.29",
     "archiver": "^8.0.0",
     "commander": "^15.0.0",
@@ -54,7 +54,7 @@
     "tar": "^7.4.0",
     "viem": "^2.54.0",
     "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.12-alpha.1"
+    "@bnbagent/studio-runtime": "0.0.12-alpha.3"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",

package/recipes/wallet/recipe.toml

@@ -6,7 +6,7 @@ description = "Configures the agent's wallet: 'evm-local' (default encrypted key
 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"]

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-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:
 
@@ -165,4 +165,5 @@ On the managed platform the deploy summary must say `x402 rail is ACTIVE` (or `A
 - 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.
+- 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
 ```
 
+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 cannot be the b402 **seller** payout wallet for a positive price (paid mode allows `evm-local` and `twak` only); init, `bag x402 sell init`, and deploy readiness reject that paid combination. Explicit `price_usd = "0"` is allowed because FREE passthrough performs no payout and bypasses B402. The outbound buying authority above remains a separate feature.
 
 For troubleshooting, run `bag doctor` and `bag wallet session status`. Do not print, parse, or copy the `signer` portion of the serialized session, and never move `.studio/wallets/` under `app/agent/`.