@bnbagent/studio-cli 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +269 -9
  2. package/package.json +19 -3
package/README.md CHANGED
@@ -1,19 +1,279 @@
1
1
  # @bnbagent/studio-cli
2
2
 
3
- `bag` scaffolds, runs, and deploys BNB Chain seller agents using ERC-8004 identity, ERC-8183 commerce, and x402 payments.
3
+ [![npm version](https://img.shields.io/npm/v/@bnbagent/studio-cli.svg)](https://www.npmjs.com/package/@bnbagent/studio-cli) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933)](https://nodejs.org/) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
4
+
5
+ Build and operate a TypeScript seller agent on BNB Chain by describing what you want in Claude Code or Cursor.
6
+
7
+ The bundled `/bnbagent-studio` skill is the primary interface. It turns your intent into a safe, reviewable workflow and drives the `bag` CLI for you. `bag` remains available as the executable interface for automation and for developers who prefer direct control.
8
+
9
+ > Studio is under active development and may introduce breaking changes. Start on BSC testnet with a wallet funded only for the task.
10
+
11
+ ## What Studio builds
12
+
13
+ - **One valuable agent, one wallet, one signer.** The same runtime can serve A2A, MCP, and X402 faces without splitting custody across services.
14
+ - **On-chain identity.** ERC-8004 makes the deployed agent discoverable and records its live service endpoint.
15
+ - **Two ways to earn.** ERC-8183 handles negotiated, escrowed jobs; x402 handles instant HTTP requests, with B402 settlement in paid mode.
16
+ - **Bounded signing.** Quotes and payment checks run in fixed code. Raw signing is never exposed to the LLM, whose chain tools are read-only.
17
+ - **A project you own.** Studio generates ordinary TypeScript under `app/agent/`; edit, fork, or move that code whenever you want.
18
+ - **A guided path to production.** Run locally, diagnose readiness, deploy to the managed BSC testnet trial or your own AWS AgentCore account, then register the public endpoint.
19
+
20
+ ## Start with the skill
21
+
22
+ ### Requirements
23
+
24
+ - Node.js 22 or newer.
25
+ - Claude Code or Cursor.
26
+ - Corepack and pnpm 10 for the generated workspace.
27
+ - Bun 1.3 or newer when you deploy.
28
+ - Docker only for container paths such as a `twak` deployment. The AWS CLI is optional and is used only for a read-only AgentCore quota check.
29
+
30
+ ### 1. Install Studio and its IDE skill
4
31
 
5
32
  ```bash
6
33
  npm install --global @bnbagent/studio-cli
7
- bag init myseller
34
+ bag skills install
35
+ ```
36
+
37
+ `bag skills install` detects Claude Code and Cursor, lets you choose user or project scope, and installs the `/bnbagent-studio` router plus its on-demand playbooks. For a scripted install, choose the target and scope explicitly:
38
+
39
+ ```bash
40
+ bag skills install --target both --scope user
41
+ ```
42
+
43
+ Reload the IDE after installation so it discovers the skill.
44
+
45
+ ### 2. Tell the skill what you want to sell
46
+
47
+ Open Claude Code or Cursor in the directory where the project should be created, then start with a prompt such as:
48
+
49
+ ```text
50
+ /bnbagent-studio Create a BNB Chain seller agent named weatheragent.
51
+ Start on BSC testnet, explain the available choices, then build and run it.
52
+ ```
53
+
54
+ You can be more specific:
55
+
56
+ ```text
57
+ /bnbagent-studio Create an agent named researchagent that sells cited research reports.
58
+ Use ERC-8183, expose A2A and MCP, use the default wallet and LLM, store
59
+ deliverables on IPFS, and prepare it for the 48-hour BNB testnet trial.
60
+ ```
61
+
62
+ Continue in natural language after creation:
63
+
64
+ ```text
65
+ /bnbagent-studio Implement the report-generation work, then run the agent locally
66
+ and diagnose anything blocking a funded delivery.
67
+
68
+ /bnbagent-studio Check deployment readiness, explain every permission and cost,
69
+ then deploy after I approve the target.
70
+ ```
71
+
72
+ The skill asks for the decisions it needs in one round, shows its work as a todo list, and routes each stage to the relevant bundled playbook. You do not need to memorize the CLI.
73
+
74
+ ### 3. Keep control of sensitive steps
75
+
76
+ The skill can prepare and run the workflow, but it leaves consequential decisions with you:
77
+
78
+ - approve each shell command in your IDE; do not grant a blanket `bag:*` permission because the CLI includes deploy and payment commands;
79
+ - enter wallet passwords through hidden prompts or `.studio/.env.local`, never in chat or command-line arguments;
80
+ - obtain testnet funds and decide how much value a wallet may hold;
81
+ - review cloud permissions, runtime-secret exposure, and possible costs before deployment;
82
+ - confirm on-chain transactions and buyer settlement actions.
83
+
84
+ ## The choices are composable
85
+
86
+ Studio does not force every agent through one fixed path. The skill guides these independent choices and checks incompatible combinations before it changes the project.
87
+
88
+ | Dimension | Choices | What to know |
89
+ | --- | --- | --- |
90
+ | Network | `bsc-testnet`, `bsc-mainnet` | Start on testnet. The managed BNB trial always uses BSC testnet. |
91
+ | Wallet | `evm-local`, `twak`, `altana` | Local encrypted keystore, Trust Wallet Agent Kit custody, or a bounded Altana runtime session. |
92
+ | LLM | Pieverse, OpenRouter, OpenAI, Anthropic, Bedrock | Pieverse is the default; `auto/free` starts at $0/token. Other providers use your own credentials. |
93
+ | Commerce rails | ERC-8183, B402, or both | ERC-8183 is job escrow. B402 settles x402 requests. Rails and public faces are separate choices. |
94
+ | Public faces | A2A, MCP, X402, or a combination | One seller core and one wallet serve every selected face. |
95
+ | Deployment | BNB managed trial or AWS AgentCore | Every deploy asks for `bnb` or `aws`; a previous deployment is never a silent default. |
96
+ | Deliverable storage | local or IPFS | Local storage is for offline development and fails deployment readiness. IPFS is durable, public, and deploy-ready. |
97
+
98
+ ### Wallet choices
99
+
100
+ | Wallet | Custody model | Packaging | Important limits |
101
+ | --- | --- | --- | --- |
102
+ | `evm-local` (default) | Encrypted keystore in workspace-root `.studio/wallets/` | Node code zip by default | Set `WALLET_PASSWORD` in the owner-only local env file. The keystore stays outside `app/agent/`. |
103
+ | `twak` | Self-custody wallet managed by Trust Wallet Agent Kit in a project-dedicated home | Container | Requires the supported TWAK CLI. Docker is required for the managed-platform image path. |
104
+ | `altana` | Local admin keystore grants a budget- and time-bounded runtime session | Node code zip | The runtime receives only the session. Pieverse SIWE activation and paid B402 selling are not supported; renew or revoke the session explicitly. |
105
+
106
+ For AWS, runtime material is injected into infrastructure in your own account. For the managed BNB trial, the runtime runs in the operator's cloud: `evm-local` and `twak` signing material is transmitted to its managed secret store. Use a fresh testnet-only wallet and never reuse it on mainnet. An Altana deployment sends only its bounded session; keep the budget and expiry tight.
107
+
108
+ ## The end-to-end journey
109
+
110
+ The skill normally takes a new seller through six stages:
111
+
112
+ 1. **Install and design.** It gathers the agent name, what it sells, network, wallet, LLM, rails, faces, storage, pricing, and deployment intent, then runs `bag init`.
113
+ 2. **Create custody and activate the model.** It creates or adopts the selected wallet without putting a password on the command line, helps fund the testnet wallet, and activates or tests the LLM.
114
+ 3. **Implement the value.** You edit the generated `runWork` hook in `app/agent/src/sellerCore.ts`. Pricing and signing stay in deterministic code.
115
+ 4. **Run and diagnose.** `bag doctor` checks the project, wallet, balances, LLM, network, and local runtime; `bag dev` starts the selected faces. Before deployment, `bag deploy prepare` adds storage, provider, and deploy-tooling gates.
116
+ 5. **Deploy and publish identity.** `bag deploy prepare` gates readiness, `bag deploy --provider ...` ships the runtime, and `bag deploy verify --provider ...` reconciles its ERC-8004 identity with the live endpoint.
117
+ 6. **Earn and settle.** Buyers fund ERC-8183 jobs or pay an x402 request. The agent verifies payment before work, submits the result, and records an audit trail.
118
+
119
+ ## What gets generated
120
+
121
+ ```text
122
+ weatheragent/
123
+ ├── package.json workspace marker
124
+ ├── pnpm-workspace.yaml
125
+ ├── AGENTS.md generated safety rules for coding agents
126
+ ├── agentcore/
127
+ │ ├── agentcore.json deployment descriptor
128
+ │ └── aws-targets.json AWS account and region for self-deploy
129
+ ├── .studio/
130
+ │ ├── .env.local gitignored secrets, mode 0600
131
+ │ └── wallets/ encrypted keystore outside deployable code
132
+ └── app/agent/
133
+ ├── studio.toml network, wallet, LLM, policy, rails, faces
134
+ └── src/
135
+ ├── sellerCore.ts the work your agent sells
136
+ ├── signing.ts fixed quote, verification, and submission path
137
+ ├── tools.ts read-only chain tools for the LLM
138
+ ├── main.ts A2A/X402 entrypoint
139
+ ├── mcpMain.ts MCP-only entrypoint
140
+ └── dualMain.ts combined A2A + MCP entrypoint
141
+ ```
142
+
143
+ The generated agent depends on [`@bnbagent/studio-runtime`](https://www.npmjs.com/package/@bnbagent/studio-runtime), not on the CLI. Removing the global CLI does not remove or disable an already generated runtime.
144
+
145
+ ## How a seller gets paid
146
+
147
+ ### ERC-8183: negotiated work with escrow
148
+
149
+ ERC-8183 is the default rail for work that has a description, deliverables, quality standards, and a settlement decision.
150
+
151
+ 1. A buyer calls `negotiate`. Fixed code clamps the configured list price and signs a quote; no LLM participates in pricing.
152
+ 2. The buyer creates the on-chain job, registers it, sets a budget, and funds escrow.
153
+ 3. The buyer sends `notify_funded` with the job ID.
154
+ 4. The seller verifies the signed terms, assigned provider, status, budget, and funded state on-chain before doing paid work.
155
+ 5. The LLM performs only the requested work. A2A acknowledges first and delivers in the background; MCP completes inside the tool call.
156
+ 6. The seller stores the deliverable and submits its reference on-chain.
157
+ 7. The buyer fetches the result and manually chooses approve, reject, or dispute. Studio never silently auto-settles a buyer's job.
158
+
159
+ `price = "0"` is an explicit FREE ERC-8183 job. It skips U-token escrow, but state-changing calls still need the configured gas or sponsored path.
160
+
161
+ ### x402: pay per HTTP request
162
+
163
+ The X402 face exposes `/x402`. Its seller rail has two intentional modes:
164
+
165
+ - a positive `price_usd` returns a payment challenge and uses B402 to verify and settle before work starts;
166
+ - `price_usd = "0"` is anonymous FREE passthrough and bypasses B402 credentials, verification, settlement, and payment auditing.
167
+
168
+ Paid mode requires a complete per-agent B402 merchant setup and a supported `evm-local` or `twak` payout wallet. Payment settles before work; if later work fails, there is no automatic refund. On self-hosted AWS AgentCore the rail runs in-process, but a buyer-facing x402 URL requires your own gateway that authenticates its relay call to AgentCore and, for paid mode, a fixed-egress path to B402.
169
+
170
+ ## Service faces
171
+
172
+ | Face | Local surface | Commerce behavior |
173
+ | --- | --- | --- |
174
+ | A2A | agent card plus JSON-RPC on port `9000` | `negotiate` and background `notify_funded` delivery over ERC-8183. |
175
+ | MCP | Streamable HTTP at `http://localhost:8000/mcp` | The same seller operations, with funded delivery completed synchronously. |
176
+ | A2A + MCP | A2A-native process on port `9000`, with `/mcp` tunneled | Both faces share one seller core, wallet, and busy-state lifecycle. |
177
+ | X402 | `/x402` on the selected runtime entrypoint | One paid or explicitly FREE request; independent of ERC-8183 escrow. |
178
+
179
+ For an A2A project, inspect the local agent card at <http://localhost:9000/.well-known/agent-card.json>. A seller expects structured A2A data parts, so a plain-text chat box is not a complete commerce test.
180
+
181
+ ## Deployment targets
182
+
183
+ Run the readiness sweep before either target:
184
+
185
+ ```bash
186
+ bag deploy prepare
187
+ ```
188
+
189
+ ### BNB Chain managed trial
190
+
191
+ ```bash
192
+ bag platform login
193
+ bag platform credit
194
+ bag deploy --provider bnb
195
+ bag deploy verify --provider bnb
196
+ ```
197
+
198
+ This is a 48-hour BSC testnet sandbox in the operator's cloud. The clock starts on the first successful deploy and redeploying does not reset it. Runtime and data are automatically reclaimed at expiry. Use a throwaway wallet, review the key-exposure notice, and destroy the deployment early if you are finished.
199
+
200
+ ### Your own AWS AgentCore account
201
+
202
+ ```bash
203
+ bag deploy --provider aws
204
+ bag deploy verify --provider aws
8
205
  ```
9
206
 
10
- ## Fund an ERC-8183 wallet on BSC testnet
207
+ The delegated deploy validates your AWS identity, builds the agent, provisions runtime secrets and inbound Cognito OAuth, and records the live endpoint. You own the account, IAM permissions, retained resources, and charges. A default `evm-local` code-zip deploy does not need Docker; container paths do.
208
+
209
+ For both providers, `bag deploy verify` checks live provider status and then registers or updates the ERC-8004 endpoint. `bag erc8004 register --endpoint <url>` is the manual path when you intentionally need an identity before the normal post-deploy verification step. Altana cannot perform the generic registration signature; use the custody-specific admin flow and verify with `--skip-register`.
210
+
211
+ Useful lifecycle commands:
212
+
213
+ ```bash
214
+ bag deploy status
215
+ bag deploy logs --provider aws
216
+ bag deploy verify --provider aws
217
+ bag deploy destroy --provider aws # dry-run plan
218
+ bag deploy destroy --provider aws --execute
219
+ ```
220
+
221
+ When multiple deployments exist, select the provider explicitly for logs, verification, and destruction.
222
+
223
+ ## Fund a BSC testnet seller
224
+
225
+ ERC-8183 uses the 18-decimal testnet **U** token. tBNB pays fallback gas; it is not the escrow currency.
226
+
227
+ 1. Run `bag wallet show` and copy the agent wallet address.
228
+ 2. Claim ERC-8183 testnet U from <https://united-coin-u.github.io/u-faucet/>.
229
+ 3. Claim tBNB from the [BNB Chain testnet faucet](https://testnet.bnbchain.org/faucet-smart).
230
+ 4. Run `bag wallet balance --all` and `bag doctor` before testing paid work.
231
+
232
+ The ERC-8183 testnet U contract is `0xc70B8741B8B07A6d61E54fd4B20f22Fa648E5565`. Do not substitute the 6-decimal B402/x402 test token; it belongs to a different rail. Canonical ERC-8004 and testnet ERC-8183 calls may use the configured sponsored-gas path, but keep a little tBNB for unsupported methods, token approval, custom contracts, or relay fallback.
233
+
234
+ ## Direct CLI reference
235
+
236
+ Use the CLI directly for automation, incident response, or when you already understand the lifecycle. The skill calls the same commands and remains the best source of context-sensitive guidance.
237
+
238
+ | Area | Commands |
239
+ | --- | --- |
240
+ | Skills | `skills install`, `skills list`, `skills uninstall` |
241
+ | Project | `init`, `scan`, `recipe`, `dev`, `doctor`, `bundle` |
242
+ | Configuration | `config`, `env`, `agents` |
243
+ | Wallet and policy | `wallet`, `wallet session`, `budget`, `audit` |
244
+ | Identity | `erc8004 register`, `show`, `resolve`, `update-endpoint`, `update-metadata` |
245
+ | Escrowed commerce | `erc8183 list`, `buy`, `status`, `submit`, `fetch`, `settle` |
246
+ | Instant payments | `x402 quote`, `buy`, `trust`, `sell init`, `sell status` |
247
+ | LLM | `llm activate`, `test`, `status`, `list-models`, `usage`, `topup`, `auto-renew` |
248
+ | Deployment | `deploy`, `deploy prepare`, `verify`, `status`, `info`, `logs`, `destroy` |
249
+ | Managed trial | `platform login`, `whoami`, `credit`, `agents`, `invoke-client`, `kill` |
250
+
251
+ Run `bag --help` and `bag <command> --help` for the executable reference. Run `bag scan` for a non-mutating project inspection and `bag doctor` for readiness diagnostics.
252
+
253
+ ## Security model
254
+
255
+ - Keep `.studio/.env.local`, `.studio/wallets/`, TWAK custody files, and Altana admin material out of version control and chat.
256
+ - Keep wallet files at the workspace root, never under deployable `app/agent/`.
257
+ - Keep quote creation, funded-job verification, submission, and x402 settlement in fixed code.
258
+ - Give the LLM only read-only chain tools; do not add raw signing or arbitrary transaction tools.
259
+ - Treat x402 host, recipient, asset, network, amount, retry, and daily budget as policy boundaries.
260
+ - Change signing allowlists only after reviewing the exact domain, primary type, contract, and spend authority being added.
261
+ - Use `bag deploy`; bypassing it skips Studio's readiness, secret-handling, and deployment reconciliation.
262
+
263
+ ## Package relationship
264
+
265
+ | Package | Role |
266
+ | --- | --- |
267
+ | `@bnbagent/studio-cli` | Development and operations layer: IDE skills, scaffolding, wallet setup, diagnostics, commerce commands, and deployment. |
268
+ | [`@bnbagent/studio-runtime`](https://www.npmjs.com/package/@bnbagent/studio-runtime) | Library imported by the generated agent: config, wallet providers, policy, audit, identity, commerce, payments, storage, LLM, and read-only tools. |
269
+ | `@bnbagent/sdk` | Lower-level BNB Chain protocol implementations consumed through the runtime. |
270
+
271
+ The CLI and runtime are versioned and released together.
272
+
273
+ ## Disclaimer
11
274
 
12
- ERC-8183 escrow is denominated in the 18-decimal testnet **U** token at `0xc70B8741B8B07A6d61E54fd4B20f22Fa648E5565`. Testnet BNB (tBNB) pays gas; it is not the escrow currency.
275
+ Studio can create wallet material, sign blockchain transactions, spend tokens through configured commerce flows, and provision cloud resources. Blockchain transactions may be irreversible, and external contracts, RPC services, payment facilitators, model providers, storage providers, and cloud platforms may fail or change independently of this package.
13
276
 
14
- 1. Run `bag wallet show` and copy the wallet address.
15
- 2. Claim ERC-8183 testnet U at <https://united-coin-u.github.io/u-faucet/>.
16
- 3. Get a little tBNB for gas from the [BNB Chain testnet faucet](https://testnet.bnbchain.org/faucet-smart).
17
- 4. Run `bag doctor` to verify both balances before buying paid work.
277
+ You are responsible for protecting keys and credentials, reviewing every transaction and permission, limiting wallet funds and session budgets, evaluating buyer and seller counterparties, securing deployed infrastructure, and paying any resulting network or cloud costs. The managed BNB trial runs in the operator's cloud and receives the runtime material described in [Wallet choices](#wallet-choices); use it only with a testnet wallet or a tightly bounded session.
18
278
 
19
- Do not substitute the 6-decimal B402/x402 testnet Mock U token. It belongs to a different commerce rail. FREE ERC-8183 jobs do not escrow U, but still require the configured gas or paymaster path for their state-changing calls.
279
+ This package is licensed under Apache-2.0 and provided **as is**, without warranties or guarantees. The authors and contributors are not responsible for lost funds, compromised credentials, service interruptions, unexpected charges, or other damages arising from its use. Nothing in this package is financial, investment, legal, or tax advice.
package/package.json CHANGED
@@ -1,7 +1,23 @@
1
1
  {
2
2
  "name": "@bnbagent/studio-cli",
3
- "version": "0.0.6",
4
- "description": "The `bag` CLI: scaffold, run, deploy, and monetize a single seller agent on BNB Chain (ERC-8004 identity, ERC-8183 commerce, x402 payments).",
3
+ "version": "0.0.7",
4
+ "description": "Skills-first toolkit and bag CLI for BNB Chain seller agents: ERC-8004 identity, ERC-8183 escrowed commerce, and x402 payments.",
5
+ "keywords": [
6
+ "bnb-chain",
7
+ "bsc",
8
+ "agent",
9
+ "ai-agent",
10
+ "seller-agent",
11
+ "erc-8004",
12
+ "erc-8183",
13
+ "x402",
14
+ "a2a",
15
+ "mcp",
16
+ "web3",
17
+ "payments",
18
+ "cli",
19
+ "scaffold"
20
+ ],
5
21
  "license": "Apache-2.0",
6
22
  "repository": {
7
23
  "type": "git",
@@ -35,7 +51,7 @@
35
51
  },
36
52
  "dependencies": {
37
53
  "@bnbagent/sdk": "0.5.0",
38
- "@bnbagent/studio-runtime": "0.0.6",
54
+ "@bnbagent/studio-runtime": "0.0.7",
39
55
  "ai": "^7.0.29",
40
56
  "archiver": "^8.0.0",
41
57
  "commander": "^15.0.0",