@bnbagent/studio-cli 0.0.6-alpha.1

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

@@ -0,0 +1,260 @@
+---
+name: bnbagent-studio-using-twak-wallet
+description: When the user's project has [wallet].kind = "twak" (a fully-supported wallet kind, opt in with `--wallet-kind twak`) — creating the Trust Wallet Agent Kit wallet, anchoring its address, funding it, SIWE-binding for Pieverse, deploying it as a container, and working around its known limitations.
+---
+
+> **Reference file** of the `bnbagent-studio` router skill — installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill). Route here via the router's decision tree.
+
+# bnbagent-studio-using-twak-wallet
+
+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
+
+Needs Node ≥ 20:
+
+```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
+
+studio can't create it for you (the twak CLI takes the password on argv, upstream
+S-8, and studio never puts secrets on argv). Do these steps yourself.
+
+**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
+```
+
+**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:
+   ```bash
+   HOME="$DH" twak setup
+   ```
+   - **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).
+
+**3. Create the wallet** (password UPPER + lower + digit, e.g. `Mypasswd01`;
+   `mypasswd01` is rejected). **RECOMMENDED — let studio drive it with the
+   password OFF argv** (it resolves the project home from studio.toml, so no
+   `HOME=` juggling):
+   ```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
+   ```
+   It wraps `twak wallet create --no-keychain` (password reaches twak via env +
+   piped stdin only), tightens `wallet.json` to mode 600, and adopts the
+   address into studio.toml in one go — so steps 5's `bag wallet new` is
+   already done.
+
+   Manual alternative (password lands on argv → `ps` / shell history;
+   acceptable only for a throwaway hot wallet):
+   ```bash
+   HOME="$DH" twak wallet create --password '<StrongPw>' --no-keychain
+   ```
+   `--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.
+
+### 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:
+- **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>`.
+
+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`.
+
+## 3. Fund it — and keep it a HOT wallet
+
+Two assets, two different rules:
+
+- **U (payment token)** — the principal for x402 topups (LLM credit) and what
+  buyers pay you. x402 payments are **GASLESS** (EIP-3009, the facilitator
+  settles), so topping up burns no BNB. A twak wallet is also a supported
+  b402 **seller** payout wallet (`bag init --wallet-kind twak --rails b402`);
+  receiving needs no signature or gas either.
+- **BNB (gas)** — **testnet: none needed; mainnet: a little for ERC-8183.**
+  Testnet: the SDK forwards MegaFuel's testnet paymaster (`--paymaster-url`,
+  twak >= 0.20.0), so x402 topups (already gasless) plus **all** 8004/8183
+  writes are sponsored — a little tBNB (~0.007) is only a fallback in case
+  sponsorship declines a tx. Mainnet: x402 stays gasless and `bag 8004
+  register` is gas-sponsored by twak internally (Trust gateway — studio
+  passes no paymaster flag), but **`8183 settle` / `fund` self-pay gas**, so
+  keep ~0.007 BNB on the wallet for them.
+
+> ⚠️ **MegaFuel testnet relay reliability (BUG-029).** The bsctestnet relay
+> has been observed accepting a sponsored write, returning a tx hash, and
+> then never broadcasting it — the hash is unverifiable on every public
+> RPC and the wallet nonce never moves (reproduced 2026-07-24 and
+> 2026-07-28 with raw `twak erc8183 create-job --paymaster-url …`). Do NOT
+> treat raw `twak erc8183` sponsored bsctestnet writes as a stable PASS
+> path for tests/CI. Drive the write through studio (`bag erc8004 …`,
+> `bag erc8183 …`) or the SDK's `TWAKProvider` instead: those classify the
+> failure (`RelaySubmissionUnverifiedError` = relay swallowed it, never
+> persist the hash as pending; `TransactionPendingError` = the tx IS
+> visible, wait) instead of a bare receipt timeout. Self-pay escape
+> hatches: `--no-paymaster` on studio 8004 writes, or
+> `BNBAGENT_USE_PAYMASTER=0` for any studio/SDK call.
+
+**Hot-wallet rule**: fund only a few days of spend. The Agent wallet is an
+operational hot wallet, not a treasury — the on-chain balance is the one
+spending limit nothing can bypass. Studio's daily caps
+(`[budget].max_per_day_usd`) are in-process guardrails: real across CLI runs
+(persisted to `.studio/spend-ledger.json`), best-effort in the deployed
+runtime (in-memory, resets on cold start).
+
+Testnet faucet: https://www.bnbchain.org/en/testnet-faucet (tBNB, fallback only).
+Mainnet: U via PancakeSwap (BNB not needed — gas is sponsored).
+
+## 4. SIWE binding (Pieverse) — ALWAYS bind before paying
+
+Pieverse attributes x402 topups to the **SIWE-bound payer address** (the paid
+call carries no session header on the twak path). `bag llm activate` performs
+the SIWE login (an EIP-191 `sign_message`, which twak supports) before any
+payment, so the normal flow is safe. If you ever top up through a custom
+path: bind first, pay second — an unbound payment cannot be attributed.
+
+## 5. Local dev (no Docker) vs deploy (Container image)
+
+**Local dev needs no Docker.** `bag dev` runs the agent **in-process** by
+default (the TS entrypoint, no Docker) — the keystore/twak materialize hooks are
+no-ops locally, so in-process exercises the same code path as the deployed
+container minus the image. Use `bag dev --container` only if you want the
+AgentCore dev container for full image parity (that mode runs via `agentcore
+dev` and needs Docker / Podman / Finch); it is **not** required to develop or
+test the twak agent locally.
+
+**Deploy ships a Container image.** The managed AgentCore image can't host the
+twak CLI toolchain, so a twak Agent deploys as a **custom container** (Node ≥ 20
++ the twak CLI). `bag init` already configured everything: `agentcore.json`
+registers a `Container` runtime and `app/agent/Dockerfile` builds the image
+(linux/arm64 — an x86 machine needs docker buildx for cross-build).
+
+- Local Docker is **required** for `bag deploy --provider aws`: the pinned
+  `bnbagent-deploy` (to which Studio delegates all cloud execution
+  to) builds the image locally (linux/arm64) and pushes it to ECR — there is
+  no remote-build fallback, so the Docker daemon must be running.
+- Wallet material reaches the runtime ONLY via AWS Secrets Manager
+  (`TWAK_WALLET_JSON` / `TWAK_CREDENTIALS_JSON` / `TWAK_WALLET_PASSWORD`),
+  never inside the image. `bag deploy prepare` verifies all of this.
+
+## 6. Known limitations (upstream twak CLI v0.20.0)
+
+| Limitation | Upstream ref | What you see |
+|---|---|---|
+| ~~Seller `submit` unavailable~~ | ~~REQ-1~~ RESOLVED in v0.19.0 | `submit --opt-params` works — verified on-chain. |
+| ~~Seller `quote` signing broken~~ | ~~S-11 regression in v0.19.0~~ RESOLVED in v0.19.1 | v0.19.0 hex-decoded `0x…` messages and signed the bytes, so provider_sig never verified (testnet also rejected `sign-message --chain bsctestnet`). v0.19.1 signs the literal text (EIP-191): `sign_quote` works on both wallet kinds. |
+| ~~Testnet intent writes self-pay gas~~ | ~~REQ-2~~ RESOLVED in v0.20.0 | twak accepts `--paymaster-url`; the SDK forwards MegaFuel's testnet endpoint on every sponsored write, so testnet 8004/8183 writes are gasless too (the relay itself is flaky — see the BUG-029 warning in §3). Mainnet stays twak-internal (no flag passed). The CLI floor is now **0.20.0** — `bag doctor` / `bag deploy prepare` reject older. |
+| 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` (password via stdin / 0600 file / hidden prompt — never argv); the manual twak commands remain a fallback. |
+| 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. |
+
+## 7. Quick health checks
+
+```bash
+bag doctor                  # [wallet] twak CLI / wallet / address-anchor checks
+bag wallet show             # describe(): address, key_location, capabilities
+bag wallet balance          # BNB + U via RPC (works on testnet too)
+bag deploy prepare          # container/Dockerfile/secret checks before deploy
+```

package/skills/references/bnbagent-studio-wiring-llm-tools.md

@@ -0,0 +1,338 @@
+---
+name: bnbagent-studio-wiring-llm-tools
+description: When the user wants their agent's LLM to call read-only chain queries (wallet balance, ERC-8004 agent info, ERC-8183 job status, etc.) — exposes the 15 functions in `@bnbagent/studio-runtime/tools` as LLM tools via AI SDK `tool()` wrappers, or any other TS agent framework.
+---
+
+> **Reference file** of the `bnbagent-studio` router skill — installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill). Route here via the router's decision tree.
+
+# bnbagent-studio-wiring-llm-tools
+
+Wire `bnbagent-studio`'s 15 chain readonly functions into the user's agent so
+the LLM can autonomously query wallet, balance, ERC-8004 identity, ERC-8183
+jobs, etc. Studio ships the pure functions plus two emitted wrapper files: the
+runtime recipe's curated default (`app/agent/src/tools.ts`, `LLM_READ_TOOLS`)
+and the full-inventory `tools-chain` recipe
+(`tools-chain/code/{{PKG}}/chainTools.ts.tmpl`, emitted as
+`app/agent/src/chainTools.ts`); for a non-AI-SDK framework you (Claude Code)
+write a thin wrapping file in the Agent sub-project.
+
+In v1 the workspace contains one sub-project, `app/agent/` — the single
+selected-faces seller runtime. LLM tools always live in
+**`app/agent/src/tools.ts`**. The `{{PKG}}` recipe variable resolves to the
+agent's `src/` dir, so the emit target is `app/agent/src/tools.ts` — its
+meaning is "source dir of the agent sub-project", not "package inside a
+single-root project".
+
+## Audience
+
+Claude Code (or another agent) editing the user's workspace. The user has run
+`bag init` and wants their Agent sub-project to expose read-only chain queries
+to its LLM (`app/agent/src/tools.ts`). These are READ-ONLY — the Agent's
+signing always stays in `app/agent/src/signing.ts` (fixed code), never an LLM
+tool.
+
+## When to use this skill
+
+- The user says "let my agent query its balance" / "agent should know about its
+  on-chain jobs" / "give the LLM access to chain state"
+- The user wants to wire chain tools into a **non-AI-SDK** stack (LangChain.js,
+  a bare OpenAI/Anthropic SDK tool loop, custom)
+- The user wants to **customize** which chain queries their LLM sees
+- The user uses `bag init` but wants to extend / re-emit the tool list
+
+## When NOT to use this skill
+
+- The user wants the Agent to **sign transactions / pay** — in the single seller
+  model all signing (quote-sign, submit, settle) is FIXED code
+  in `app/agent/src/signing.ts` (called by A2A's `SellerAgentExecutor` or MCP's
+  `src/mcpMain.ts` tools), **never** an
+  LLM-callable tool. The LLM only produces work text after a job is verified
+  funded; fixed code prices, clamps, signs, and submits. There is no "wire a
+  signing tool into the LLM" path in v1.
+- The user is doing dev-time debugging via Claude Code — that's the `bag` CLI
+  read commands (`bag wallet`, `bag erc8183 status/list`, …), not LLM tools.
+
+---
+
+## The 15 functions
+
+All in `@bnbagent/studio-runtime/tools`. Each returns a plain object (or
+string); the wire-format keys stay snake_case (the tool contract shared with
+LLMs and MCP clients).
+
+### Wallet & chain basics — always safe
+
+| Function | Reads | Dependency |
+|---|---|---|
+| `walletInfo()` | active wallet address + source + keystore dir | none |
+| `walletAddress()` | active wallet address (alias of walletInfo) | none |
+| `walletList()` | all configured keystore addresses | dev concern |
+| `balanceNative(address?, network?)` | BNB / tBNB balance | none |
+| `balanceU(address?, network?)` | U token balance | `[u_token]` |
+| `networkInfo(network?)` | chain id, RPC host, contract addresses | none |
+| `txStatus(txHash, network?)` | tx receipt + revert reason | none |
+
+### LLM provider — Pieverse-specific
+
+| Function | Reads | Dependency |
+|---|---|---|
+| `pieverseUsage(days=7)` | LLM spend on Pieverse | `[llm.provider=pieverse-llm]` |
+
+Note: `pieverseUsage` does a SIWE EIP-191 personal_sign (no on-chain effect,
+domain-locked). Other functions are pure RPC reads.
+
+### ERC-8004 identity
+
+| Function | Reads | Dependency |
+|---|---|---|
+| `agentInfo(agentId, network?)` | on-chain ERC-8004 record by ID | `[erc8004]` |
+| `agentByAddress(address, network?)` | look up agent by owner address | `[erc8004]` |
+
+### ERC-8183 jobs
+
+| Function | Reads | Dependency |
+|---|---|---|
+| `jobStatus(jobId, network?)` | job state, client, provider, budget | `[erc8183]` |
+| `jobList(limit=10, mine=false, provider?, network?)` | recent jobs | `[erc8183]` |
+| `jobCount(network?)` | network-wide inflight job count | `[erc8183]` |
+
+### Advanced / footguns
+
+| Function | Reads | Why footgun |
+|---|---|---|
+| `blockInfo(block?, network?)` | block summary | usually noise for LLM |
+| `contractCallView(address, functionSignature, args?, outputTypes?, network?)` | arbitrary `eth_call` | accepts **any** ABI — LLM can be prompt-injected into calling attacker contracts |
+
+---
+
+## Step 1 — Confirm the user has run `bag init`
+
+```bash
+# from workspace root:
+ls app/agent/studio.toml && (ls app/agent/src/main.ts 2>/dev/null || ls app/agent/src/mcpMain.ts)
+```
+
+If `app/agent/src/tools.ts` already exists, the user has the AI SDK form
+already. Skip to Step 4 if they want to customize.
+
+---
+
+## Step 2 — Identify the stack
+
+Look at `app/agent/src/main.ts` or `app/agent/src/mcpMain.ts` imports /
+`app/agent/package.json`:
+
+| Sign in code | Stack |
+|---|---|
+| `import { tool, generateText } from "ai"` | **AI SDK** (use stock recipe) |
+| `from "langchain"` / `from "@langchain/core"` | **LangChain.js** |
+| `openai.chat.completions.create({ tools: ... })` | **bare OpenAI SDK loop** |
+| `anthropic.messages.create({ tools: ... })` | **bare Anthropic SDK loop** |
+
+If AI SDK: emit the stock recipe and stop.
+
+```bash
+bag recipe code tools-chain > app/agent/src/chainTools.ts    # full inventory + CHAIN_READ_TOOLS
+```
+
+Then in the protocol entrypoint (`app/agent/src/main.ts` for A2A,
+`app/agent/src/mcpMain.ts` for MCP), pass the tool set into the generate call:
+
+```ts
+import { LLM_READ_TOOLS } from "./tools.js";
+// inside runWork:
+const { text } = await generateText({ model, tools: LLM_READ_TOOLS, prompt });
+```
+
+For non-AI-SDK stacks, continue.
+
+---
+
+## Step 3 — Write a framework-specific wrapper
+
+Studio doesn't ship adapters for non-AI-SDK stacks (commitment: "agent code
+the user owns"). You write a wrapper file in the user's project. Pattern:
+import the pure functions, wrap each with the framework's tool primitive.
+
+### LangChain.js
+
+```ts
+// app/agent/src/tools.ts
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import * as cr from "@bnbagent/studio-runtime/tools";
+
+export const LLM_READ_TOOLS = [
+  tool(async () => cr.walletInfo(), {
+    name: "wallet_info",
+    description: "Describe the agent's active wallet.",
+    schema: z.object({}),
+  }),
+  tool(async ({ address, network }) => cr.balanceNative(address ?? null, network),
+    {
+      name: "balance_native",
+      description: "Native BNB balance of an address (defaults to the agent's wallet).",
+      schema: z.object({ address: z.string().optional(), network: z.string().optional() }),
+    }),
+  // balanceU (requires [u_token]), networkInfo, txStatus,
+  // pieverseUsage (requires [llm.provider=pieverse-llm]),
+  // agentInfo / agentByAddress (require [erc8004]),
+  // jobStatus / jobList (require [erc8183]) — same pattern.
+  // ⚠️ contractCallView accepts any ABI — keep it out unless deliberate.
+];
+```
+
+Wire into the agent (e.g. `createReactAgent({ llm, tools: LLM_READ_TOOLS })`).
+
+### Bare OpenAI / Anthropic tool loop
+
+For a hand-rolled tool loop, declare each function in the provider's tool JSON
+format and dispatch on the tool name:
+
+```ts
+// app/agent/src/tools.ts
+import * as cr from "@bnbagent/studio-runtime/tools";
+
+export const CHAIN_READ_FUNCTIONS: Record<string, (args: any) => Promise<unknown>> = {
+  wallet_info: async () => cr.walletInfo(),
+  balance_native: async (a) => cr.balanceNative(a.address ?? null, a.network),
+  balance_u: async (a) => cr.balanceU(a.address ?? null, a.network), // requires [u_token]
+  network_info: async (a) => cr.networkInfo(a.network),
+  tx_status: async (a) => cr.txStatus(a.tx_hash, a.network),
+  // pieverse_usage,                       // requires [llm.provider=pieverse-llm]
+  // agent_info, agent_by_address,         // require [erc8004]
+  // job_status, job_list,                 // require [erc8183]
+  // contract_call_view, block_info, wallet_list, wallet_address,
+};
+```
+
+### Generic
+
+For any framework that accepts a typed function + description, the pattern is
+identical — wrap each `cr.*` function in the framework's tool primitive and
+assemble a list. The emitted AI SDK files (`tools.ts` / `chainTools.ts`)
+already carry per-tool descriptions and zod input schemas you can copy from.
+
+---
+
+## Step 4 — Customize what the LLM sees
+
+The recipe gives a sensible default; the user owns the file. Common edits:
+
+**Remove tools** the agent doesn't need (smaller LLM context = better focus):
+
+```ts
+export const LLM_READ_TOOLS: ToolSet = {
+  balance_u: CHAIN_READ_TOOLS.balance_u,   // only thing this agent really needs
+  tx_status: CHAIN_READ_TOOLS.tx_status,
+};
+```
+
+**Uncomment Pieverse usage** if the user's `[llm].provider = "pieverse-llm"`:
+
+```ts
+pieverse_usage: ...,   // requires [llm.provider=pieverse-llm]
+```
+
+**Uncomment 8004 / 8183 reads** if the user added those sections to
+`studio.toml` after `bag init` (e.g., ran `bag erc8004 register` later).
+
+**Never uncomment** `contract_call_view` without thinking — it accepts any ABI
+signature and an LLM jailbreak / prompt injection can drain via reads from
+malicious contracts (or hammer expensive RPC). Keep commented unless the
+agent has a specific debug / introspection job and the user has read the
+tool description.
+
+---
+
+## Step 5 — Write operations live in fixed code, NOT LLM tools
+
+Read tools (this skill) are safe-ish — worst case the LLM gives wrong info.
+**Write operations** (quote-sign, submit, settle) are the whole point of the
+single seller model's signing boundary: they live as FIXED code in
+`app/agent/src/signing.ts`, are dispatched by A2A's `SellerCore` (in
+`app/agent/src/sellerCore.ts`, which `SellerAgentExecutor` inherits) or MCP's
+server tools (`negotiate`/`notify_funded`; `settle` is the manual `bag erc8183 settle`),
+and are **never** put in the LLM's `tools` set. The quote price is rule-based
+(fixed code reads the list `price`, clamps it to `[min,max]`, then signs — the
+LLM never touches the price); the LLM only PRODUCES the work text in `notify_funded` delivery —
+money never flows through a tool call.
+
+The one automatic signing path outside `signing.ts` is the budget-gated
+model-wrapper LLM-credit auto-renew hook (in the emitted
+`app/agent/src/model.ts`'s `buildModel()` factory, backed by
+`@bnbagent/studio-runtime/pieverse` `PieverseCreditEnsurer`) — also automatic,
+also **not** an LLM tool.
+
+The x402 buyer kernel (`@bnbagent/studio-runtime/x402`, the payment signer) is
+**not** an LLM tool either — in v1 it is reachable only as the Agent's
+automatic model-wrapper LLM-credit auto-renew (above), driven by fixed code,
+never the LLM. Do not wire it into the Agent's `tools` set. The SDK's
+`SigningPolicy` is the second-layer gate on every signature regardless.
+
+---
+
+## Common questions
+
+**Q: Why isn't `app/agent/src/tools.ts` auto-synced with `app/agent/studio.toml` changes?**
+
+A: The recipe is emitted once at `bag init` time; the file is the user's. To
+refresh after configuring new features (e.g., enabling `[erc8183]` later):
+
+```bash
+bag recipe code tools-chain > app/agent/src/chainTools.ts.new
+diff app/agent/src/chainTools.ts app/agent/src/chainTools.ts.new
+# manually merge — preserves any user customizations
+```
+
+**Q: Does this work in AgentCore deployment?**
+
+A: Yes. The functions only need `@bnbagent/studio-runtime` (already a
+dependency of the Agent sub-project via `app/agent/package.json`). No
+subprocess, no MCP transport — pure in-process calls. The deploy artifact
+ships the built `tools.ts` as part of the Agent that serves its selected
+A2A/MCP faces on AgentCore.
+
+**Q: Is this the same as `bag init --protocols MCP`?**
+
+A: No. `bag init --protocols MCP` selects an **external seller face**
+(streamable-HTTP `/mcp` for buyers). This skill wires read-only chain queries
+into the Agent's own LLM as in-process tools. v0.0.1 doesn't ship
+MCP-for-agent (the agent runtime consuming a subprocess MCP server as its LLM
+tools). MCP here is instead an *external seller face* (`bag init --protocols
+MCP` or `--protocols A2A,MCP`) — see `docs/design/decisions.md`. For
+now: in-process is simpler, faster, and matches commitment "agent code the
+user owns".
+
+**Q: How do I know if my `app/agent/src/tools.ts` is up to date?**
+
+A: Re-emit with `bag recipe code tools-chain > app/agent/src/chainTools.ts.new`
+and diff against your current file. If studio added new tools in a newer
+version, they'll appear in the emit; you decide whether to adopt.
+
+**Q: Can I reuse a Pieverse API key I created with a DIFFERENT wallet (BYOK)?**
+
+A: Yes, for inference — with one caveat. The LLM-credit auto-renew hook
+(`PieverseCreditEnsurer`) authenticates to Pieverse with the **agent's signing
+wallet** and can only inspect/allocate keys **that wallet owns**. If you set
+`[llm.pieverse].key_hash` to a key created by another wallet (the owner is your
+day-to-day wallet, not the agent's throwaway signer), the hook can't see it: it
+detects the owner mismatch, prints one warning, **disables itself for that
+session, and lets inference run on the key's existing Bearer credit**. It does
+not crash the agent and does not repeat the check.
+
+Recommended BYOK setup — do NOT hand the owner wallet's private key to the
+agent (that would violate the "keys stay in the user's environment" boundary):
+
+1. Put the key in the agent env: `PIEVERSE_LLM_API_KEY=sk-pv-…` in
+   `.studio/.env.local`, plus `[llm.pieverse].key_hash = "0x…"` and `network`
+   in `studio.toml`.
+2. Turn off auto-renew so the hook doesn't try to allocate a key it can't own:
+   `bag llm auto-renew llm off`.
+3. Top the key up yourself in the Pieverse portal (or from the owner wallet)
+   when it runs low — the agent will 402 upstream if the Bearer credit is
+   exhausted.
+
+If you instead want the agent to auto-allocate/topup, activate a key the
+**agent's own** signing wallet owns with `bag llm activate` (zero-deposit is
+fine) and keep auto-renew on.