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

package/dist/bag.js

@@ -52,7 +52,7 @@ import {
   x402SellerIsFree,
   x402SellerPricingState,
   x402SellerUsesB402
-} from "./chunk-RNWAADXU.js";
+} from "./chunk-RSM3RMDD.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-RWRR6XWO.js");
+  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-BY3ILBEP.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({
@@ -2937,7 +2964,7 @@ function canBuildWallet(root, data) {
   const cfg = data ?? loadAgentToml(root);
   const walletCfg = tableOf2(cfg, "wallet");
   const kind = walletCfg.kind;
-  if (kind === "twak" || kind === "altana") {
+  if (kind === "twak" || kind === "altana" || kind === "turnkey") {
     return false;
   }
   if (!process.env.WALLET_PASSWORD) {
@@ -2955,7 +2982,7 @@ function canBuildWallet(root, data) {
 function walletAddressForChecks(root, data) {
   const cfg = data ?? loadAgentToml(root);
   const walletCfg = tableOf2(cfg, "wallet");
-  if (walletCfg.kind === "twak" || walletCfg.kind === "altana") {
+  if (walletCfg.kind === "twak" || walletCfg.kind === "altana" || walletCfg.kind === "turnkey") {
     const addr = String(walletCfg.address ?? "").trim();
     return addr || null;
   }
@@ -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";
@@ -5909,18 +5958,15 @@ async function cmdUsage(daysArg) {
 
 // src/cli/recipes/deps.ts
 var CORE_PKG = "@bnbagent/studio-runtime";
-var VERSION_RE = /^(\d+)\.(\d+)\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+var VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 function coreRequirement() {
   const version = cliVersion();
-  const m = VERSION_RE.exec(version);
-  if (m === null) {
+  if (!VERSION_RE.test(version)) {
     throw new Error(
       `cannot derive a core constraint from CLI version '${version}'; expected X.Y.Z or X.Y.Z-<prerelease>`
     );
   }
-  const major = Number.parseInt(m[1], 10);
-  const minor = Number.parseInt(m[2], 10);
-  return `${CORE_PKG}@>=${version} <${major}.${minor + 1}.0`;
+  return `${CORE_PKG}@${version}`;
 }
 function normalizeNodeDeps(deps) {
   return deps.map((d) => d.trim() === CORE_PKG ? coreRequirement() : d);
@@ -6587,6 +6633,7 @@ import {
 } from "@bnbagent/studio-runtime/config";
 import { tbnbFaucetHint as tbnbFaucetHint2 } from "@bnbagent/studio-runtime/networks";
 import { buildPolicy, buildWallet } from "@bnbagent/studio-runtime/wallet";
+import { getAddress as toChecksumAddress } from "viem";
 
 // src/cli/walletSession.ts
 import * as fs21 from "fs";
@@ -7318,6 +7365,9 @@ async function cmdNew(opts) {
   if (kind === "twak") {
     return cmdNewTwak(projectRoot, walletCfg);
   }
+  if (kind === "turnkey") {
+    return cmdNewTurnkey(projectRoot);
+  }
   const privateKey = await resolvePrivateKeyArg(opts.privateKey);
   const password = requireDurablePassword(projectRoot);
   const keystoreDir = resolveKeystoreDir2(
@@ -7381,6 +7431,28 @@ Install it (Node >=22):  npm install -g @trustwallet/cli@${TWAK_CLI_VERSION}`
   printNextAfterNew(projectRoot, address);
   return 0;
 }
+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').
+${turnkeySetupGuidance()}`
+    );
+    return 1;
+  }
+  let address;
+  try {
+    address = toChecksumAddress(signWith);
+  } catch {
+    printErr(
+      `error: TURNKEY_SIGN_WITH must be the wallet account's Ethereum address (0x + 40 hex chars), not a Turnkey wallet id \u2014 copy it from the dashboard wallet-account view. Got: '${signWith}'`
+    );
+    return 1;
+  }
+  printOut(address);
+  persistAddress(projectRoot, address);
+  return 0;
+}
 function ensureTwakCredentials(walletFile, homeDir) {
   const twakDir = path21.dirname(walletFile);
   const target = path21.join(twakDir, "credentials.json");
@@ -7558,6 +7630,33 @@ function cmdShow5(projectRootArg2) {
     );
     return 0;
   }
+  if (kind === "turnkey") {
+    const anchored = String(walletCfg.address ?? "").trim();
+    const signWith = String(process.env.TURNKEY_SIGN_WITH ?? "").trim();
+    const address2 = anchored || signWith;
+    if (!address2) {
+      throw new Error(
+        "cannot resolve the Turnkey wallet address: no [wallet].address is anchored in studio.toml and TURNKEY_SIGN_WITH is not set \u2014 fill .studio/.env.local, then run `bag wallet new`."
+      );
+    }
+    const requiredEnv = [
+      "TURNKEY_API_PUBLIC_KEY",
+      "TURNKEY_API_PRIVATE_KEY",
+      "TURNKEY_ORG_ID",
+      "TURNKEY_SIGN_WITH"
+    ];
+    const present = requiredEnv.filter((key) => process.env[key]).length;
+    const baseUrl = process.env.TURNKEY_API_BASE_URL || "https://api.turnkey.com";
+    printOut(`address:       ${address2}`);
+    printOut("source:        turnkey");
+    printOut(
+      `key_location:  remote:turnkey (${baseUrl}; key held in AWS Nitro enclave, never leaves)`
+    );
+    printOut(
+      `credentials:   ${present}/${requiredEnv.length} TURNKEY_* env vars set`
+    );
+    return 0;
+  }
   const password = requirePassword2();
   const keystoreDir = resolveKeystoreDir2(projectRoot, null, walletCfg);
   const provider = new EVMWalletProvider({
@@ -7650,7 +7749,14 @@ async function cmdSign(msg, projectRootArg2) {
     );
   }
   let provider;
-  if (kind === "twak") {
+  if (kind === "turnkey") {
+    printErr(
+      "note: Turnkey signatures are billed (free tier 25/month at 1 req/s; pay-as-you-go $0.10 each)."
+    );
+    provider = buildWallet(walletCfg, projectRoot, {
+      network: projectNetwork(projectRoot)
+    });
+  } else if (kind === "twak") {
     provider = twakProvider(projectRoot, walletCfg);
   } else {
     const password = requirePassword2();
@@ -7675,10 +7781,10 @@ async function cmdBalance(opts) {
   const walletCfg = data.wallet !== null && typeof data.wallet === "object" ? data.wallet : {};
   let address;
   const kind = walletKind(walletCfg);
-  if (kind === "twak" || kind === "altana") {
+  if (kind === "twak" || kind === "altana" || kind === "turnkey") {
     address = String(walletCfg.address ?? "").trim();
     if (!address) {
-      const nextStep = kind === "twak" ? "(adopts the twak wallet's address) first." : "to create the Altana admin keystore first.";
+      const nextStep = kind === "twak" ? "(adopts the twak wallet's address) first." : kind === "turnkey" ? "(set TURNKEY_SIGN_WITH in .studio/.env.local first \u2014 `bag wallet new` adopts it)." : "to create the Altana admin keystore first.";
       throw new Error(
         `no [wallet].address anchored in studio.toml \u2014 run bag wallet new ${nextStep}`
       );
@@ -8044,7 +8150,7 @@ function registerInit(program) {
   ).addOption(
     new Option2(
       "--rails <rails>",
-      "Commerce rail(s) to scaffold: 8183, b402, or both (default; Altana defaults to 8183)."
+      "Commerce rail(s) to scaffold: 8183, b402, or both (default)."
     ).choices(["8183", "b402", "both"])
   ).option(
     "--erc8183-price <base-units>",
@@ -8068,8 +8174,8 @@ function registerInit(program) {
   ).addOption(
     new Option2(
       "--wallet-kind <kind>",
-      "Wallet backend for the Agent (default: evm-local = encrypted local keystore at the workspace root .studio/wallets/; CodeZip deploy). altana \u2014 encrypted local admin keystore plus a bounded runtime session; deploys ship ONLY the session (ALTANA_SESSION secret). twak \u2014 FULLY SUPPORTED, opt in: Trust Wallet Agent Kit CLI, self-custody encrypted mnemonic in a PROJECT-DEDICATED home (.studio/twak); deploys as a container image."
-    ).choices(["twak", "evm-local", "altana"])
+      "Wallet backend for the Agent (default: evm-local = encrypted local keystore at the workspace root .studio/wallets/; CodeZip deploy). altana \u2014 encrypted local admin keystore plus a bounded runtime session; deploys ship ONLY the session (ALTANA_SESSION secret). twak \u2014 FULLY SUPPORTED, opt in: Trust Wallet Agent Kit CLI, self-custody encrypted mnemonic in a PROJECT-DEDICATED home (.studio/twak); deploys as a container image. turnkey \u2014 remote signer: the key lives in Turnkey's AWS Nitro enclave and the Agent signs via TURNKEY_* API credentials; CodeZip deploy; every successful signature is billed."
+    ).choices(["twak", "evm-local", "altana", "turnkey"])
   ).option(
     "--twak-home <path>",
     "twak only: point this project at an EXISTING twak wallet home (the HOME-STYLE PARENT dir that contains .twak/wallet.json \u2014 NOT the .twak dir itself; a .twak path holding a wallet is auto-corrected to its parent) instead of the dedicated .studio/twak. Written to [wallet].twak_home."
@@ -8237,7 +8343,7 @@ async function cmdInitFlow(nameArg, opts) {
   if (llmProvider === null) {
     return 2;
   }
-  const inferredRails = opts.rails ?? (facesExplicit ? hasX402Face(faces) ? "both" : "8183" : walletKind2 === "altana" ? "8183" : void 0);
+  const inferredRails = opts.rails ?? (facesExplicit ? hasX402Face(faces) ? "both" : "8183" : void 0);
   let rails = await resolveRails(inferredRails, isTty);
   if (!facesExplicit) {
     faces = normalizeProtocolFaces(
@@ -8382,9 +8488,9 @@ async function cmdInitFlow(nameArg, opts) {
   }
   const budgetFlag = opts.enableAutoTopup ? "enable" : opts.autoTopup === false ? "disable" : null;
   const budgetChoice = llmProvider === "pieverse-llm" || budgetFlag !== null ? await resolveBudgetChoice(budgetFlag) : null;
-  if ((rails === "b402" || rails === "both") && x402SellerPricingState({ price_usd: b402Price }).kind === "paid" && !["evm-local", "twak"].includes(walletKind2)) {
+  if ((rails === "b402" || rails === "both") && x402SellerPricingState({ price_usd: b402Price }).kind === "paid" && !["evm-local", "twak", "turnkey", "altana"].includes(walletKind2)) {
     printErr(
-      `error: the b402 seller rail supports wallet.kind evm-local or twak only; '${walletKind2}' cannot act as the b402 payout wallet. Re-run with --rails 8183 or a supported --wallet-kind.`
+      `error: the b402 seller rail supports wallet.kind evm-local, twak, turnkey or altana only; '${walletKind2}' cannot act as the b402 payout wallet. Re-run with --rails 8183 or a supported --wallet-kind.`
     );
     fs23.rmSync(target, { recursive: true, force: true });
     return 2;
@@ -8481,6 +8587,8 @@ async function cmdInitFlow(nameArg, opts) {
     }
   } else if (walletKind2 === "altana") {
     printAltanaNotice();
+  } else if (walletKind2 === "turnkey") {
+    printTurnkeyNotice();
   } else {
     printEvmLocalNotice(
       derivePackaging(walletKind2, destination, platformArtifact2, runtime)
@@ -8717,6 +8825,9 @@ function computeAgentNodeDeps(runtime, provider, protocols = "A2A", walletKind2
   if (walletKind2 === "altana") {
     raw.push(...readRecipeNodeDeps("wallet", "altana"));
   }
+  if (walletKind2 === "turnkey") {
+    raw.push(...readRecipeNodeDeps("wallet", "turnkey"));
+  }
   const out = {};
   const core = splitDep(coreRequirement());
   for (const dep of raw) {
@@ -8890,6 +9001,18 @@ kind = "altana"
 keystore_dir = "../../.studio/wallets"
 session_file = "../../.studio/wallets/altana-session.json"
 # address = "0x..."   # filled by \`bag wallet new\`; session must match it`;
+  }
+  if (walletKind2 === "turnkey") {
+    return `[wallet]
+# Turnkey remote signer. The key is generated and held in Turnkey's AWS Nitro
+# enclave \u2014 no key material ever exists in this project or its deploys. The
+# Agent signs via the Turnkey API using the TURNKEY_* credentials in
+# .studio/.env.local. Billing: every successful signature is billed (free
+# tier: 25 signatures/month at 1 request/second; pay-as-you-go $0.10 each).
+# PRODUCTION: use a NON-ROOT API user restricted by an explicit ALLOW
+# policy \u2014 a root user's API key bypasses ALL Turnkey server-side policies.
+kind = "turnkey"
+# address = "0x..."   # filled by \`bag wallet new\` (adopts TURNKEY_SIGN_WITH)`;
   }
   return `[wallet]
 # Local keystore signer. The Agent is the SOLE key-holder/signer.
@@ -9088,6 +9211,23 @@ function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails, b402
       "# TWAK_ACCESS_ID=",
       "# TWAK_HMAC_SECRET="
     );
+  } else if (walletKind2 === "turnkey") {
+    lines.push(
+      "",
+      "# Turnkey API credentials (dashboard \u2192 API keys). The P-256 API key",
+      "# pair authenticates this Agent to the enclave; the wallet's signing",
+      "# key never leaves Turnkey. Use a NON-ROOT API user + explicit ALLOW",
+      "# policy in production (root keys bypass all Turnkey policies).",
+      "TURNKEY_API_PUBLIC_KEY=",
+      "TURNKEY_API_PRIVATE_KEY=",
+      "# Organization id (dashboard \u2192 settings):",
+      "TURNKEY_ORG_ID=",
+      "# Account to sign with \u2014 MUST be the 0x Ethereum ADDRESS itself, not",
+      "# a Turnkey wallet id. `bag wallet new` anchors it into studio.toml.",
+      "TURNKEY_SIGN_WITH=",
+      "# Optional API host override (default https://api.turnkey.com):",
+      "# TURNKEY_API_BASE_URL="
+    );
   } else if (walletKind2 === "evm-local" || walletKind2 === "altana") {
     lines.push(
       "",
@@ -9202,7 +9342,7 @@ entrypoint code in \`src/signing.ts\` \u2014 never an LLM-callable tool.
 ${mode === "both" ? filesBoth : mode === "mcp" ? filesMcp : filesA2a}
 ${shared}
 - \`.env.local\` \u2014 Agent secrets; on deploy they are sent to the **operator's**
-  Secrets Manager (the scoped, consented commitment-#2 exception). ${walletKind2 === "altana" ? "Only the\n  bounded session ships (as `ALTANA_SESSION`); tighten it with\n  `bag wallet session grant --force` \u2014 do not create a new wallet." : "Use a\n  THROWAWAY testnet wallet \u2014 `(cd app/agent && bag wallet new)`."}
+  Secrets Manager (the scoped, consented commitment-#2 exception). ${walletKind2 === "altana" ? "Only the\n  bounded session ships (as `ALTANA_SESSION`); tighten it with\n  `bag wallet session grant --force` \u2014 do not create a new wallet." : walletKind2 === "turnkey" ? "No key\n  material exists locally \u2014 only the TURNKEY_* API credentials ship; the\n  signing key stays in Turnkey's enclave. Fund the TURNKEY_SIGN_WITH\n  address with a little tBNB; every successful signature is billed." : "Use a\n  THROWAWAY testnet wallet \u2014 `(cd app/agent && bag wallet new)`."}
 
 ## Run locally
 
@@ -9311,12 +9451,12 @@ function ensureCursorGitignore(gitignore) {
 ${addition}`);
 }
 async function resolveWalletKind(flagValue, isTty) {
-  if (flagValue === "evm-local" || flagValue === "twak" || flagValue === "altana") {
+  if (flagValue === "evm-local" || flagValue === "twak" || flagValue === "altana" || flagValue === "turnkey") {
     return flagValue;
   }
   if (!isTty) {
     printErr(
-      "info: wallet backend defaulting to 'evm-local' (non-interactive). To choose explicitly, re-run with --wallet-kind evm-local or --wallet-kind twak or --wallet-kind altana."
+      "info: wallet backend defaulting to 'evm-local' (non-interactive). To choose explicitly, re-run with --wallet-kind evm-local or --wallet-kind twak, --wallet-kind altana or --wallet-kind turnkey."
     );
     return "evm-local";
   }
@@ -9328,11 +9468,15 @@ async function resolveWalletKind(flagValue, isTty) {
     "  2. twak    \u2014 Trust Wallet CLI wallet; forces container packaging for deploys"
   );
   printOut(
-    "  3. altana  \u2014 bounded session signer; incompatible with pieverse-llm and paid b402 selling"
+    "  3. altana  \u2014 bounded session signer; incompatible with pieverse-llm"
+  );
+  printOut(
+    "  4. turnkey \u2014 remote signer; key held in Turnkey's AWS Nitro enclave; billable signatures"
   );
-  const answer = (await promptUser("Wallet backend [1-3, Enter = evm-local]: ")).trim().toLowerCase();
+  const answer = (await promptUser("Wallet backend [1-4, Enter = evm-local]: ")).trim().toLowerCase();
   if (answer === "2" || answer === "twak") return "twak";
   if (answer === "3" || answer === "altana") return "altana";
+  if (answer === "4" || answer === "turnkey") return "turnkey";
   if (answer !== "" && answer !== "1" && answer !== "evm-local") {
     printErr(`hint: unknown wallet backend '${answer}' \u2014 using evm-local.`);
   }
@@ -9614,6 +9758,12 @@ async function runOnboarding(o) {
   if (o.walletKind === "twak") {
     return runOnboardingTwak(o);
   }
+  if (o.walletKind === "turnkey") {
+    printOut(
+      "turnkey onboarding: no local key is created. Fill the TURNKEY_* credentials in .studio/.env.local (Turnkey dashboard \u2192 API keys / settings / wallet account), then run `(cd app/agent && bag wallet new)` to adopt + anchor the signing address."
+    );
+    return false;
+  }
   const password = await promptPassword();
   if (password === null) {
     return false;
@@ -9983,7 +10133,33 @@ NOTE \u2014 wallet.kind = "altana" (bounded runtime session):
    \`bag wallet session grant --force\` and redeploy.`
   );
 }
+function printTurnkeyNotice() {
+  printOut(
+    `
+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.
+${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;
+   a root user's API key bypasses ALL Turnkey server-side policies.`
+  );
+}
 function printPlatformWalletSuggestion(walletKind2) {
+  if (walletKind2 === "turnkey") {
+    printOut(
+      `
+NOTE \u2014 destination = "platform" (48h TESTNET TRIAL on the BNB Chain managed platform):
+ \xB7 This is a sandbox, not a production seller \u2014 the runtime is auto-reclaimed at 48h.
+ \xB7 To sign, ONLY the TURNKEY_* API credentials are transmitted to the operator's
+   Secrets Manager on deploy \u2014 the signing key never leaves Turnkey's enclave.
+ \xB7 Want a smaller blast radius? Use a NON-ROOT API user whose ALLOW policy
+   covers only this Agent's operations, and revoke it from the Turnkey
+   dashboard when the trial ends.`
+    );
+    return;
+  }
   if (walletKind2 === "altana") {
     printOut(
       `
@@ -10214,6 +10390,17 @@ function printNextSteps(name, provider, o = {}) {
     printOut(
       "  (cd app/agent && bag wallet session status)   # local, secret-free summary"
     );
+  } else if (walletKind2 === "turnkey") {
+    printOut(
+      "  # 1. edit .studio/.env.local and set the TURNKEY_* credentials (Turnkey dashboard \u2192 API keys / settings / wallet account)"
+    );
+    printOut(
+      "  #    use a NON-ROOT API user + explicit ALLOW policy; TURNKEY_SIGN_WITH is the 0x ADDRESS, not a wallet id"
+    );
+    printOut(
+      "  # 2. adopt + anchor the Turnkey address (no local key is created):"
+    );
+    printOut("  (cd app/agent && bag wallet new)");
   } else {
     printOut(
       "  # 1. edit .studio/.env.local and set WALLET_PASSWORD (encrypts the keystore + signs all on-chain ops)"
@@ -10437,6 +10624,10 @@ function printConfigSummary(agentRoot2) {
         ".studio/wallets/altana-session.json"
       )}`
     );
+  } else if (walletKind2 === "turnkey") {
+    printOut(
+      "  wallet    : Turnkey remote signer (key in AWS Nitro enclave; TURNKEY_* credentials in .studio/.env.local) \u2014 the sole signer; receives your $U"
+    );
   } else {
     printOut(
       `  wallet    : local keystore (${shown(
@@ -10557,6 +10748,16 @@ function runtimeEnvKeysCore(cfg, resolvable) {
     }
   } else if (walletKind2 === "altana") {
     keys = [];
+  } else if (walletKind2 === "turnkey") {
+    keys = [
+      "TURNKEY_API_PUBLIC_KEY",
+      "TURNKEY_API_PRIVATE_KEY",
+      "TURNKEY_ORG_ID",
+      "TURNKEY_SIGN_WITH"
+    ];
+    if (resolvable("TURNKEY_API_BASE_URL")) {
+      keys.push("TURNKEY_API_BASE_URL");
+    }
   } else {
     keys = ["WALLET_PASSWORD"];
   }
@@ -11081,10 +11282,17 @@ async function cmdDev(opts) {
     );
     return 2;
   }
-  const pwEnv = walletKind2 === "twak" ? "TWAK_WALLET_PASSWORD" : "WALLET_PASSWORD";
-  if (walletKind2 !== "altana" && !process.env[pwEnv]) {
+  const requiredWalletEnv = walletKind2 === "twak" ? ["TWAK_WALLET_PASSWORD"] : walletKind2 === "altana" ? [] : walletKind2 === "turnkey" ? [
+    "TURNKEY_API_PUBLIC_KEY",
+    "TURNKEY_API_PRIVATE_KEY",
+    "TURNKEY_ORG_ID",
+    "TURNKEY_SIGN_WITH"
+  ] : ["WALLET_PASSWORD"];
+  const missingWalletEnv = requiredWalletEnv.filter((key) => !process.env[key]);
+  if (missingWalletEnv.length > 0) {
+    const plural = missingWalletEnv.length > 1 ? "vars are" : "var is";
     printErr(
-      `error: ${pwEnv} env var is required to run \`bag dev\` (the Agent is the sole signer). Set it in .studio/.env.local or your shell.`
+      `error: ${missingWalletEnv.join(", ")} env ${plural} required to run \`bag dev\` with wallet.kind='${walletKind2}' (the Agent is the sole signer). Set ${missingWalletEnv.length > 1 ? "them" : "it"} in .studio/.env.local or your shell.`
     );
     return 2;
   }
@@ -11465,6 +11673,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 [];
@@ -11490,6 +11701,9 @@ async function checkWalletPasswordEnvSet(root, _target) {
   if (kind === "altana") {
     return [];
   }
+  if (kind === "turnkey") {
+    return [];
+  }
   if (process.env.WALLET_PASSWORD) {
     return [];
   }
@@ -11832,11 +12046,11 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
     }
   }
   const walletKind2 = String(tableOf2(cfg, "wallet").kind ?? "evm-local");
-  if (paid && !["evm-local", "twak"].includes(walletKind2)) {
+  if (paid && !["evm-local", "twak", "turnkey", "altana"].includes(walletKind2)) {
     out.push({
       level: Level.CRITICAL,
       name: "x402_wallet_kind_unsupported",
-      message: `[wallet].kind = "${walletKind2}" cannot run the b402 seller rail; supported kinds are evm-local and twak.`,
+      message: `[wallet].kind = "${walletKind2}" cannot run the b402 seller rail; supported kinds are evm-local, twak, turnkey, and altana.`,
       details: { walletKind: walletKind2 }
     });
   }
@@ -12113,6 +12327,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 [];
@@ -12218,6 +12472,7 @@ var allChecks = [
   checkDeployCliRunnable,
   checkRuntimeSecretsInjected,
   checkAwsTargetsPopulated,
+  checkAwsAccountMatchesTarget,
   checkAgentcoreQuotaHeadroom
 ];
 
@@ -12353,7 +12608,7 @@ function collectRuntimeSecretsDetailed(root) {
       sources[KEYSTORE_JSON_ENV] = "wallet-file";
     }
   }
-  if (walletKind2 !== "altana" && !(KEYSTORE_JSON_ENV in payload) && !(TWAK_WALLET_JSON_ENV in payload)) {
+  if (walletKind2 !== "altana" && walletKind2 !== "turnkey" && !(KEYSTORE_JSON_ENV in payload) && !(TWAK_WALLET_JSON_ENV in payload)) {
     printErr(
       `WARNING: no wallet signing material found (${KEYSTORE_JSON_ENV} for evm-local / ${TWAK_WALLET_JSON_ENV} for twak). The deployed runtime won't be able to sign quotes or deliveries. Create/adopt a wallet first (e.g. \`bag wallet new\`) and redeploy.`
     );
@@ -15029,6 +15284,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,
@@ -15061,9 +15325,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."
     ],
@@ -16510,6 +16772,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,
@@ -16539,9 +16823,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."
     ],
@@ -17438,7 +17721,8 @@ var SECRET_ENV_KEYS = [
   "PIEVERSE_LLM_API_KEY",
   "STORAGE_API_KEY",
   "TWAK_ACCESS_ID",
-  "TWAK_HMAC_SECRET"
+  "TWAK_HMAC_SECRET",
+  "TURNKEY_API_PRIVATE_KEY"
 ];
 function tableOf14(cfg, key) {
   const v = cfg[key];
@@ -17685,6 +17969,9 @@ async function checkWallet(projectRoot, data) {
   if (walletCfg.kind === "altana") {
     return checkWalletAltana(walletCfg, projectRoot, data);
   }
+  if (walletCfg.kind === "turnkey") {
+    return checkWalletTurnkey(walletCfg);
+  }
   if (!isLocalEvmWallet(walletCfg)) {
     return [
       {
@@ -17738,7 +18025,59 @@ async function checkWallet(projectRoot, data) {
   }
   return out;
 }
-function checkWalletAltana(walletCfg, projectRoot, data) {
+var TURNKEY_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var TURNKEY_REQUIRED_ENV = [
+  "TURNKEY_API_PUBLIC_KEY",
+  "TURNKEY_API_PRIVATE_KEY",
+  "TURNKEY_ORG_ID",
+  "TURNKEY_SIGN_WITH"
+];
+function checkWalletTurnkey(walletCfg) {
+  const out = [];
+  const missing = TURNKEY_REQUIRED_ENV.filter((key) => !process.env[key]);
+  out.push(
+    missing.length === 0 ? {
+      name: "[wallet] turnkey credentials",
+      status: PASS,
+      detail: "API key pair + org id + sign-with address set; reminder: production should use a non-root API user with an explicit ALLOW policy (root keys bypass all Turnkey policies)"
+    } : {
+      name: "[wallet] turnkey credentials",
+      status: FAIL,
+      detail: `missing: ${missing.join(", ")} \u2014 set them in .studio/.env.local (Turnkey dashboard \u2192 API keys / settings / wallet account)`
+    }
+  );
+  const signWith = String(process.env.TURNKEY_SIGN_WITH ?? "").trim();
+  if (signWith !== "" && !TURNKEY_ADDRESS_RE.test(signWith)) {
+    out.push({
+      name: "TURNKEY_SIGN_WITH format",
+      status: FAIL,
+      detail: "must be the wallet account's Ethereum address (0x + 40 hex chars), not a Turnkey wallet id \u2014 copy it from the dashboard wallet-account view"
+    });
+  }
+  const anchored = String(walletCfg.address ?? "").trim();
+  if (anchored === "") {
+    out.push({
+      name: "[wallet] address anchor",
+      status: WARN,
+      detail: "no [wallet].address \u2014 run `bag wallet new` to adopt TURNKEY_SIGN_WITH"
+    });
+  } else if (signWith !== "" && TURNKEY_ADDRESS_RE.test(signWith)) {
+    const matches = anchored.toLowerCase() === signWith.toLowerCase();
+    out.push(
+      matches ? {
+        name: "[wallet] address anchor",
+        status: PASS,
+        detail: `${anchored} matches TURNKEY_SIGN_WITH`
+      } : {
+        name: "[wallet] address anchor",
+        status: FAIL,
+        detail: `[wallet].address ${anchored} does not match TURNKEY_SIGN_WITH ${signWith} \u2014 stale anchor or different Turnkey credentials; fix .studio/.env.local, then re-run \`bag wallet new\``
+      }
+    );
+  }
+  return out;
+}
+async function checkWalletAltana(walletCfg, projectRoot, data) {
   const out = [];
   const contracts = erc8183ContractOverrideState(
     erc8183ContractEnvForProject(projectRoot)
@@ -17824,13 +18163,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;
@@ -17930,6 +18297,20 @@ function checkPassword(data) {
       }
     ];
   }
+  if (walletKind2 === "turnkey") {
+    const missing = TURNKEY_REQUIRED_ENV.filter((key) => !process.env[key]);
+    return [
+      missing.length === 0 ? {
+        name: "TURNKEY_* env",
+        status: PASS,
+        detail: "all Turnkey credentials set (WALLET_PASSWORD is not used for this kind)"
+      } : {
+        name: "TURNKEY_* env",
+        status: WARN,
+        detail: `missing: ${missing.join(", ")} \u2014 signing will fail (set in .studio/.env.local)`
+      }
+    ];
+  }
   if (process.env.WALLET_PASSWORD) {
     return [{ name: "WALLET_PASSWORD env", status: PASS, detail: "set" }];
   }
@@ -18298,11 +18679,11 @@ function checkX402Seller(data, agentRoot2) {
     }
   ];
   const walletKind2 = String(tableOf14(data, "wallet").kind ?? "evm-local");
-  if (!["evm-local", "twak"].includes(walletKind2)) {
+  if (!["evm-local", "twak", "turnkey", "altana"].includes(walletKind2)) {
     out.push({
       name: "x402 payout wallet",
       status: FAIL,
-      detail: `PAID B402 supports evm-local or twak, not ${walletKind2}.`
+      detail: `PAID B402 supports evm-local, twak, turnkey or altana, not ${walletKind2}.`
     });
   }
   const credentials = b402Credentials(agentRoot2);
@@ -18376,7 +18757,7 @@ function checkStorage(data) {
 }
 function balanceAddress(projectRoot, data) {
   const walletCfg = tableOf14(data, "wallet");
-  if (walletCfg.kind === "twak" || walletCfg.kind === "altana") {
+  if (walletCfg.kind === "twak" || walletCfg.kind === "altana" || walletCfg.kind === "turnkey") {
     const addr = String(walletCfg.address ?? "").trim();
     return addr || null;
   }
@@ -21102,9 +21483,9 @@ async function cmdSellInit(priceFlag) {
   }
   const free = x402SellerPricingState({ price_usd: priceUsd }).kind === "free";
   const walletKind2 = String(tableOf16(cfg, "wallet").kind ?? "evm-local");
-  if (!free && !["evm-local", "twak"].includes(walletKind2)) {
+  if (!free && !["evm-local", "twak", "turnkey", "altana"].includes(walletKind2)) {
     printErr(
-      `error: the b402 seller rail supports wallet.kind evm-local or twak only; '${walletKind2}' cannot act as the b402 payout wallet.`
+      `error: the b402 seller rail supports wallet.kind evm-local, twak, turnkey or altana only; '${walletKind2}' cannot act as the b402 payout wallet.`
     );
     return 1;
   }
@@ -21230,16 +21611,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
+    );
+    const available = token.methods.filter(
+      (method) => matching(method) !== void 0
     );
-    if (methodKind && methodKind.extra.name === token.eip712Name && methodKind.extra.version === token.eip712Version) {
-      printOut(`B402 probe: exact/eip3009 U available for ${network}`);
+    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(
@@ -21368,6 +21754,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(
@@ -21407,7 +21817,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) {