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

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

@@ -9,101 +9,49 @@ description: When the user's project has [wallet].kind = "twak" (a fully-support
 
 Procedure for setting up and operating the **twak** wallet kind (Trust Wallet Agent Kit CLI) in a bnbagent-studio project. twak is a **fully-supported** wallet kind - opt in at scaffold with `bag init <name> --wallet-kind twak` (`evm-local`, a local keystore, is the default). The wallet is a **self-custody, AES-256-GCM-encrypted mnemonic** the user controls (not a hosted service), living by default in a **project-dedicated** home `.studio/twak` (`[wallet].twak_home`), isolated from your main `~/.twak`. The default kind is `evm-local` (local keystore); re-scaffold with `--wallet-kind twak` to use twak.
 
-## 1. Install the CLI
+## 1. CLI installation is project-managed
 
-Needs Node >=22:
+`bag init --wallet-kind twak` pins `@trustwallet/cli@0.20.0` in the generated `app/agent/package.json`; the normal `pnpm install` installs it. Do **not** ask the user for a global installation and do not call the upstream CLI directly. Studio and the runtime resolve `app/agent/node_modules/.bin/twak`, and `bag doctor` / `bag deploy prepare` verify the project-pinned version floor.
 
-```bash
-npm install -g @trustwallet/cli@0.20.0
-twak --version
-```
-
-studio requires **>= 0.20.0** (the SDK forwards `--paymaster-url` on sponsored bsc-testnet writes - the flag first shipped in v0.20.0; older CLIs reject it with "unknown option"); `bag doctor` and `bag deploy prepare` verify the floor.
-
-## 2. Create the wallet - one time, in YOUR terminal
-
-`bag wallet twak-init` drives creation for you (step 3) so you never type the password on a command line; the NaaS setup wizard below still has to be run by hand once, because it is interactive.
-
-**Every twak command is prefixed with the dedicated home.** Without `HOME=$DH`, twak uses your real `~/.twak` (your MAIN wallet) and macOS pops a login-keychain password prompt. Set it once:
-
-```bash
-DH=<workspace>/.studio/twak     # e.g. ~/proj/.studio/twak
-```
+## 2. Studio-managed setup - no upstream wizard
 
-**1. Get Trust Wallet NaaS API credentials** (one time; account-level, NOT wallet-specific). Make an app at https://portal.trustwallet.com/dashboard/apps → copy its Access ID + HMAC secret. (`twak wallet create` fails with "No API credentials found" without them.)
-
-**2. Run the setup wizard** - writes the credentials into the dedicated home:
+The user creates a Trust Wallet NaaS app at https://portal.trustwallet.com/dashboard/apps, but must never paste the Access ID, HMAC secret, or wallet password into the AI chat. On a human TTY, `bag init` performs the setup automatically. To retry or complete a non-onboarded scaffold, run from `app/agent`:
 
 ```bash
-HOME="$DH" twak setup
+bag wallet twak-init
 ```
 
-- **Step 1 (API credentials):** paste the Access ID + HMAC secret. WalletConnect Project ID → leave blank, ENTER.
-- **Step 2 ("which harnesses to wire up"): SELECT NONE - press ENTER** on the empty list (do NOT press SPACE or `a`). 🔒 This would register twak's signing MCP into Claude Code / Cursor / etc., handing wallet+signing power to your AI assistant (and any prompt-injection reaching it) - studio forbids that: signing is fixed `signing.ts` code, the LLM only receives read-only chain tools, and the deployed agent never calls twak via MCP.
-- **Step 3 (Wallet "Pick one"): choose `3) Skip for now`** (you create it in the next step). NOT `2) Use WalletConnect with my existing wallet` (binds your main/real wallet).
+This one Studio command:
 
-**3. Create the wallet** (password UPPER + lower + digit, e.g. `Mypasswd01`; `mypasswd01` is rejected). **RECOMMENDED - let studio drive it so you never type the password on a command line** (it resolves the project home from studio.toml, so no `HOME=` juggling):
+1. Collects the NaaS Access ID and HMAC secret through hidden Studio prompts. It never starts `twak setup` or asks which AI harnesses to wire.
+2. Runs the project-pinned `twak init --json` with the two credentials in the child environment.
+3. Performs an authenticated `twak search BNB --networks 20000714 --limit 1 --json` read. Newly written credentials are removed if this verification fails; pre-existing credentials are never deleted.
+4. Generates `TWAK_WALLET_PASSWORD` from 32 bytes of the OS cryptographic random source and writes it to `.studio/.env.local` (0600). There is no weak-random fallback and the value is never printed.
+5. Creates the project-dedicated wallet with `--no-keychain --json`, tightens `.twak/` to 0700 and its credential/wallet files to 0600, reads the BSC address, and anchors it into `studio.toml`.
+6. Refuses to replace an anchored identity and never overwrites an existing wallet or credential file.
 
-```bash
-bag wallet twak-init                                       # interactive hidden prompt
-printf %s "$PW" | bag wallet twak-init --password-stdin    # CI / scripts
-bag wallet twak-init --password-file pw.txt                # file must be chmod 600
-```
+Upstream twak v0.20.0 requires `--password` during wallet creation, so the generated password is briefly present in that one child process's argv. It does not enter the user's shell history, Studio output, diagnostics, or AI transcript. Runtime signing reads it from the environment and does not put it on argv.
 
-It seeds this home's `credentials.json` from `~/.twak` when step 2 was run there, wraps `twak wallet create --password … --no-keychain` (twak requires the flag on its own argv, so the value reaches that short-lived child - it never lands in YOUR shell history), tightens `wallet.json` to mode 600, and adopts the address into studio.toml in one go - so step 5's `bag wallet new` is already done.
+For non-interactive automation, the user can put `TWAK_ACCESS_ID` and `TWAK_HMAC_SECRET` in `.studio/.env.local` themselves before running `bag wallet twak-init`; Studio still generates the wallet password. The legacy `--password-stdin` and `--password-file <0600-file>` options remain explicit compatibility overrides, not the happy path.
 
-Manual alternative (you type the password on argv → `ps` / shell history; acceptable only for a throwaway hot wallet):
+After setup:
 
 ```bash
-HOME="$DH" twak wallet create --password '<StrongPw>' --no-keychain
+bag wallet show
+bag llm activate
+bag doctor
 ```
 
-`--no-keychain` keeps the password OUT of the OS keychain - it lives only in `TWAK_WALLET_PASSWORD` (step 4), so creation triggers **no macOS keychain prompt**. Expect: "Agent wallet created successfully / Wallet registered with backend / Generated addresses for 25 chains". (twak then prints "Restart your harness… / Try a sample query…" - that's for MCP users; ignore it, studio doesn't use twak's MCP.)
-
-> **Already have a wallet here?** If twak says `Wallet already exists. Back up … then delete it`, the wallet is already created - do **NOT** follow the literal "delete it". `wallet.json` is the ONLY copy of your AES-256-GCM encrypted mnemonic; deleting it without the mnemonic backed up loses the funds **forever**. Confirm it's yours (`HOME="$DH" twak wallet addresses`), skip create, and go straight to step 5 - `bag wallet new` just ADOPTS the existing address (idempotent, never destructive). Only recreate if you've safely backed up the mnemonic, and then `mv` `wallet.json` to a `.bak` rather than deleting.
-
-> **CI / scripts:** use `bag wallet twak-init --password-stdin` / `--password-file` above - it is the supported non-interactive path and works on headless runners (no keychain involved). Avoid the older `TWAK_NONINTERACTIVE=1 TWAK_SETUP_WALLET=create … twak setup` route: it has no `--no-keychain` equivalent, stores the password in the OS keychain, and aborts with `STORAGE_ERROR` on headless / Docker runners.
-
-**4. Put the unlock password in `.env.local`** - **YOU edit the file** (never through the chat, never `bag env set <literal>` - the password must not reach the assistant or argv). Same value as Step 3:
-
-```
-# .studio/.env.local
-TWAK_WALLET_PASSWORD=<StrongPw>
-```
-
-studio AND the deployed runtime unlock via this env - the keychain copy is local-only and never deploys, so this line is mandatory or deploy can't sign.
-
-**5. Anchor + activate** - back in a NORMAL shell (**no `HOME=` prefix**; studio resolves the home from `[wallet].twak_home` itself, and `bag wallet new` ADOPTS the address - it does not create a second wallet):
-
-```bash
-cd <workspace>/app/agent
-bag wallet new      # writes the NEW address into studio.toml [wallet].address - confirm it's the new wallet, not your main one
-bag llm activate    # zero-deposit Pieverse key
-bag doctor          # all PASS (zero balance is a WARN, fine)
-```
-
-### macOS keychain - bypassed by default
-
-With `--no-keychain` (step 3) the wallet password lives ONLY in `TWAK_WALLET_PASSWORD` (step 4) - twak never reads or writes the OS keychain, so both creation and signing trigger **no macOS password prompt**. studio and the deployed runtime unlock via that env, so nothing is lost by skipping the keychain.
-
-> **Safety net (you normally never see it):** for the rare case you create a wallet WITHOUT `--no-keychain`, `bag init` (and `bag wallet new`) also auto-creates an isolated, **empty-password** keychain under `$DH/Library/Keychains` - secret-free, scoped to `$DH` (your real login keychain untouched), never deployed. With `--no-keychain` twak doesn't touch any keychain at all.
-
-> ⚠️ **If you omitted `--no-keychain` and a macOS prompt LOOPS** (or a bare `twak setup` prompted against your **main** login keychain and rejects every password): **Do NOT click "Reset Default Keychain"** - it erases your Wi-Fi passwords, SSH passphrases, and saved app secrets. Quit it with `pkill -9 -f twak`, then recreate the wallet **disk-only**:
->
-> ```bash
-> HOME="$DH" twak wallet create --password '<StrongPw>' --no-keychain
-> ```
->
-> and rely on `TWAK_WALLET_PASSWORD` (step 4) to unlock - same end state, no keychain involved.
+No separate `bag wallet new` step is required. An existing wallet is adopted only after Studio verifies its password and reads its address. If its password is not already in `.studio/.env.local`, the user enters it through a hidden Studio prompt or supplies the original password using `--password-stdin` / `--password-file <0600 file>`; Studio never invents a replacement password for an existing wallet.
 
 ### Other wallet placements
 
-`bag init` always writes a project-dedicated `[wallet].twak_home`; the flow above is the default (a brand-new dedicated wallet). Alternatives:
+The default is a new project-dedicated `.studio/twak` home, isolated from the user's main `~/.twak`. Alternatives are explicit:
 
-- **Reuse an existing wallet** across agents → `bag init --twak-home <path>` (that wallet's HOME-style dir, containing `.twak/wallet.json`). Same flow: create with `--no-keychain`, unlock via `TWAK_WALLET_PASSWORD`.
-- **Your main `~/.twak`** (DISCOURAGED - real funds / bound identities) → opt-in only via `bag init --twak-home ~`, or "yes" to the warned prompt (default "no") when a machine wallet is detected. Recorded as `[wallet].twak_home = <$HOME>`.
+- Reuse an existing wallet across agents with `bag init --twak-home <home-style-path>`; the path contains `.twak/wallet.json`.
+- Reuse the main `~/.twak` only with `bag init --twak-home ~`. This is discouraged because deploy would ship that wallet material through the selected secrets channel.
 
-Each wallet is its own address → its own ERC-8004 identity, Pieverse SIWE binding, and secret bundle; `bag doctor` / `bag deploy` resolve the right one via `[wallet].twak_home`.
+Each wallet address has its own ERC-8004 identity, Pieverse SIWE binding, and secret bundle; `bag doctor` / `bag deploy` resolve the configured `[wallet].twak_home`.
 
 ## 3. Fund it - and keep it a HOT wallet
 
@@ -144,7 +92,7 @@ Pieverse attributes x402 topups to the **SIWE-bound payer address** (the paid ca
 | Custom ERC-8183 targets unavailable | upstream feature request | twak v0.20.0 has no Commerce/Router/Policy address option. Studio doctor/prepare and the SDK fail closed instead of silently executing on canonical contracts; use `evm-local` for a custom ERC-8183 deployment. |
 | No generic EIP-712 signing | P0 (won't fix) | `[wallet.signing]` is ignored; payments go through the delegated payer's own prechecks + `--max-payment`. Endpoints needing an `Authorization` header _and_ x402 are unavailable (e.g. `bag llm key new --initial-usd > 0` - use `--initial-usd 0` + topup + allocate instead, same end state). |
 | No wallet import | S-6 | Switching wallet kinds changes your address → re-run `bag 8004 register` (new on-chain identity). |
-| Programmatic wallet creation forces password onto argv | S-8 | Bridged by `bag wallet twak-init` (you supply it via stdin / 0600 file / hidden prompt; studio forwards it on the child's argv because twak requires the flag); the manual twak commands remain a fallback. |
+| Programmatic wallet creation forces password onto argv | S-8 | Bridged by `bag wallet twak-init`: Studio generates 32 CSPRNG bytes, persists the value privately before creation, and forwards it only to the short-lived child because twak requires the flag. The value never enters user shell history or output. |
 | CLI has no daily/monthly caps | - | Studio's policy layer (`[budget].max_per_day_usd`, host allowlist, per-request caps) is the spend authority for both wallet kinds. |
 | `twak wallet balance --chain bsctestnet` rejects the chain | BUG-031 | Fails with `CHAIN_UNSUPPORTED` even though `wallet address` and `erc8183` accept `bsctestnet`. Use `bag wallet balance` (RPC-based, works on testnet), or raw RPC: `eth_getBalance` for tBNB and an `eth_call` of `balanceOf(address)` on the U token for token balance. |
 | `twak tx <hash> --chain bsctestnet` rejects the chain | BUG-032 | Same chain-registry gap on the readback path: transactions twak itself just mined on `bsctestnet` cannot be inspected with `twak tx`. Use public RPC (`eth_getTransactionByHash` / `eth_getTransactionReceipt`) or BscScan testnet instead. |

package/dist/_twak-4XF4H5PL.js

@@ -1,25 +0,0 @@
-#!/usr/bin/env node
-import {
-  TWAK_CLI_MIN_VERSION,
-  TWAK_CLI_VERSION,
-  TWAK_NODE_MIN_MAJOR,
-  twakCreateGuidance,
-  twakDoubledHomeHint,
-  twakHomeDir,
-  twakInstalledVersion,
-  twakVersionBelowFloor,
-  twakWalletFile,
-  whichTwak
-} from "./chunk-RO726HJG.js";
-export {
-  TWAK_CLI_MIN_VERSION,
-  TWAK_CLI_VERSION,
-  TWAK_NODE_MIN_MAJOR,
-  twakCreateGuidance,
-  twakDoubledHomeHint,
-  twakHomeDir,
-  twakInstalledVersion,
-  twakVersionBelowFloor,
-  twakWalletFile,
-  whichTwak
-};

package/dist/chunk-RO726HJG.js

@@ -1,175 +0,0 @@
-#!/usr/bin/env node
-
-// src/cli/_twak.ts
-import * as os from "os";
-import * as path from "path";
-import { resolveTwakHome } from "@bnbagent/studio-runtime/wallet";
-
-// src/cli/proc.ts
-import { execa } from "execa";
-async function runCapture(cmd, args, opts = {}) {
-  const result = await execa(cmd, args, {
-    cwd: opts.cwd,
-    env: opts.env,
-    input: opts.input,
-    timeout: opts.timeoutMs,
-    reject: false,
-    stripFinalNewline: false
-  });
-  return {
-    code: result.exitCode ?? 1,
-    stdout: typeof result.stdout === "string" ? result.stdout : "",
-    stderr: typeof result.stderr === "string" ? result.stderr : ""
-  };
-}
-async function runStream(cmd, args, opts = {}) {
-  const result = await execa(cmd, args, {
-    cwd: opts.cwd,
-    env: opts.env,
-    timeout: opts.timeoutMs,
-    reject: false,
-    stdio: "inherit"
-  });
-  return result.exitCode ?? 1;
-}
-async function runCaptureOut(cmd, args, opts = {}) {
-  const result = await execa(cmd, args, {
-    cwd: opts.cwd,
-    env: opts.env,
-    input: opts.input,
-    timeout: opts.timeoutMs,
-    reject: false,
-    stripFinalNewline: false,
-    stdout: "pipe",
-    stderr: "inherit"
-  });
-  return {
-    code: result.exitCode ?? 1,
-    stdout: typeof result.stdout === "string" ? result.stdout : ""
-  };
-}
-
-// src/cli/_twak.ts
-var TWAK_CLI_VERSION = "0.20.0";
-var TWAK_CLI_MIN_VERSION = [
-  0,
-  20,
-  0
-];
-var TWAK_NODE_MIN_MAJOR = 20;
-function twakVersionBelowFloor(installed) {
-  const floor = TWAK_CLI_MIN_VERSION;
-  for (let i = 0; i < floor.length; i += 1) {
-    const a = installed[i] ?? 0;
-    const b = floor[i];
-    if (a !== b) {
-      return a < b;
-    }
-  }
-  return false;
-}
-async function whichTwak() {
-  const cmd = process.platform === "win32" ? "where" : "which";
-  const result = await runCapture(cmd, ["twak"]);
-  if (result.code !== 0) {
-    return null;
-  }
-  const line = result.stdout.split("\n")[0]?.trim();
-  return line ? line : null;
-}
-async function twakInstalledVersion() {
-  if (await whichTwak() === null) {
-    return null;
-  }
-  let out;
-  try {
-    const result = await runCapture("twak", ["--version"], {
-      timeoutMs: 15e3
-    });
-    out = result.stdout;
-  } catch {
-    return null;
-  }
-  const m = /(\d+)\.(\d+)\.(\d+)/.exec(out || "");
-  if (m === null) {
-    return null;
-  }
-  return [
-    Number.parseInt(m[1], 10),
-    Number.parseInt(m[2], 10),
-    Number.parseInt(m[3], 10)
-  ];
-}
-function twakHomeDir(walletCfg, projectRoot) {
-  const home = resolveTwakHome(walletCfg ?? {}, projectRoot ?? null);
-  return path.join(home ?? os.homedir(), ".twak");
-}
-function twakWalletFile(walletCfg, projectRoot) {
-  return path.join(twakHomeDir(walletCfg, projectRoot), "wallet.json");
-}
-function twakDoubledHomeHint(walletFile) {
-  const doubled = `${path.sep}.twak${path.sep}.twak${path.sep}`;
-  if (!walletFile.includes(doubled)) {
-    return null;
-  }
-  return `hint: the resolved wallet path ${walletFile} nests .twak/.twak \u2014 [wallet].twak_home in studio.toml likely points at the .twak directory itself. Set it to the PARENT directory (the runtime appends .twak/wallet.json) and re-run.`;
-}
-function twakCreateGuidance(fields) {
-  return `error: wallet.kind = "twak" \u2014 \`bag wallet new\` only adopts an existing
-twak wallet's address. Create the wallet ONCE (you choose the password; pick a
-strong one).
-
-RECOMMENDED \u2014 let studio drive the create step so you never type the password
-on a command line (twak requires --password on its own argv, so the value does
-reach that short-lived child process):
-
-    bag wallet twak-init --password-stdin      # CI: printf %s "$PW" | bag wallet twak-init --password-stdin
-    bag wallet twak-init --password-file <f>   # file must be chmod 600
-    bag wallet twak-init                       # interactive hidden prompt
-
-(the one-time NaaS setup below applies to BOTH paths; the manual twak
-commands follow it.)
-
-First get Trust Wallet NaaS API credentials (one time): make an app at
-https://portal.trustwallet.com/dashboard/apps \u2192 copy its Access ID + HMAC
-secret, then run \`twak setup\` (without them \`twak wallet create\` fails with
-"No API credentials found"):
-
-    ${fields.setupCmd}
-
-then create the wallet \u2014 interactive (you type the password on argv yourself;
-twak warns, and it lands in your shell history \u2014 acceptable for a throwaway hot
-wallet):
-
-    ${fields.createCmd}
-
-  \u2014 or, to keep the password out of your shell history (CI / scripts), pass it
-    via the environment and let \`twak setup\` create the wallet
-    non-interactively:
-
-    TWAK_NONINTERACTIVE=1 TWAK_SETUP_WALLET=create TWAK_WALLET_PASSWORD=<pw> ${fields.setupCmd}
-
-    (this stores the password in the OS keychain and needs one that persists;
-    on headless / Docker runners without a keychain it aborts \u2014 use the argv
-    form above there.)
-
-then set TWAK_WALLET_PASSWORD in .studio/.env.local and re-run
-    bag wallet new        # adopts the address into studio.toml
-Guide: the bnbagent-studio-using-twak-wallet.md reference (installed by \`bag skills install\`).`;
-}
-
-export {
-  runCapture,
-  runStream,
-  runCaptureOut,
-  TWAK_CLI_VERSION,
-  TWAK_CLI_MIN_VERSION,
-  TWAK_NODE_MIN_MAJOR,
-  twakVersionBelowFloor,
-  whichTwak,
-  twakInstalledVersion,
-  twakHomeDir,
-  twakWalletFile,
-  twakDoubledHomeHint,
-  twakCreateGuidance
-};