bnbagent-studio 0.0.1__tar.gz

bnbagent_studio-0.0.1/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual envs
+.venv/
+.venv-*/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/
+
+# Local scratch
+scratch/
+
+# Project secrets
+.env
+.env.local
+
+# Wallet keystores (never commit, even encrypted)
+.studio/wallets/
+*.keystore.json
+
+# Audit log (per-project; ADR #37 T37.9)
+.studio/audit-log.jsonl

bnbagent_studio-0.0.1/DISCLAIMER.md

@@ -0,0 +1,51 @@
+<!-- Synced copy of the repo-root DISCLAIMER.md — edit that one, then re-copy. -->
+
+# Disclaimer
+
+**bnbagent-studio** is open-source software provided under the
+[Apache-2.0 license](https://github.com/bnb-chain/bnbagent-studio/blob/main/LICENSE)
+**"AS IS", without warranty of any kind** (see Sections 7–8 of the license).
+This file spells out what that means for the parts of the project that touch
+your cloud account and your funds.
+
+## AWS permissions and resources
+
+Deploying the two-layer seller provisions resources **in your own AWS
+account**: Bedrock AgentCore and Secrets Manager for the Agent (Layer A),
+and — if you follow the EC2 runbook — an IAM role, security group and EC2
+instance for the Service (Layer B).
+
+The IAM policy documents this project publishes —
+[least-privilege-iam.md](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/least-privilege-iam.md)
+and
+[iam-policies.md](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/iam-policies.md)
+— are **reference configurations**, provided AS IS. They are a best effort at
+a least-privilege setup, but **you** apply them, **you** own the credentials,
+and **you** remain solely responsible for:
+
+- reviewing and scoping every policy before applying it to your account;
+- the conduct of any identity that holds these permissions;
+- all resulting AWS costs; and
+- the security posture and operation of the deployed resources.
+
+Before granting any permission, read the official AWS guidance:
+
+- [AWS IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)
+- [AWS Well-Architected Framework — security pillar](https://docs.aws.amazon.com/wellarchitected/latest/framework/security.html)
+
+## Wallet keys and on-chain funds
+
+The software manages wallet keys and on-chain funds. Private keys live only in
+environments you control — which also means only **you** can protect them.
+Start on testnet, fund mainnet wallets only with amounts you can afford to
+lose, and use the software at your own risk. Nothing in this project is
+financial advice.
+
+## No liability
+
+To the maximum extent permitted by law, the authors and contributors accept no
+liability for damages of any kind arising from the use of this software —
+including, without limitation, lost funds, compromised credentials, unexpected
+cloud charges, or security incidents in your AWS account. The
+[Apache-2.0 license](https://github.com/bnb-chain/bnbagent-studio/blob/main/LICENSE)
+is the authoritative statement of the terms.

bnbagent_studio-0.0.1/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: bnbagent-studio
+Version: 0.0.1
+Summary: The `bag` CLI to scaffold and deploy a two-layer bnbagent-sdk seller on BNB Chain.
+Project-URL: Homepage, https://github.com/bnb-chain/bnbagent-studio
+Project-URL: Repository, https://github.com/bnb-chain/bnbagent-studio
+Author: BNB Chain Studio
+License-Expression: Apache-2.0
+Keywords: agent,blockchain,bnb,cli,erc-8004,erc-8183,x402
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: bnbagent-studio-core==0.0.1
+Requires-Dist: boto3>=1.34
+Requires-Dist: fastapi>=0.110
+Requires-Dist: mcp>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# bnbagent-studio
+
+**`bag`** — the developer CLI, read-only MCP server, scaffolding recipes, and
+bundled IDE skills for **vibe-coding a two-layer blockchain seller** on BNB
+Chain: an Agent that earns $U by selling services over ERC-8004 (identity) +
+ERC-8183 (commerce) + x402 (payments), built on the `bnbagent` SDK.
+
+You drive most of it **in natural language from Claude Code (or Cursor)** — the
+bundled skills teach your AI tool how to scaffold, run, and deploy the agent for
+you. It is also a complete CLI you can run by hand.
+
+## ✨ Highlights
+
+- **Vibe-code a BNB Chain seller from your IDE** — install the skills, then ask
+  Claude Code to "create a BNB seller agent on testnet" and it drives the CLI
+  for you.
+- **Two-layer, key-isolated deploy** — a private, invoke-only **Agent** (the
+  sole key-holder/signer, on AWS Bedrock AgentCore) and a public, **keyless
+  Service** (no key, no LLM, never signs).
+- **Read-only MCP** — 15 chain-query tools for your IDE, with **no signing and
+  no on-chain state change** by design.
+- **Keys never leave your machine** — the encrypted keystore lives at your
+  workspace root, outside any deploy artifact; only your own Agent ever reads
+  it.
+- **Jump-ship friendly** — emitted project code is yours to edit, fork, or
+  migrate; no closed-source SaaS lock-in.
+- **$0 to start** — the default Pieverse LLM provider activates with a
+  zero-deposit API key; testnet funds and your own LLM key are optional.
+
+> ⚠️ **This project is under active development** and may introduce breaking
+> changes between releases. It manages wallet keys and on-chain funds: start on
+> **testnet**, and use it at your own risk.
+
+> ⚠️ **Deploying provisions AWS resources in your own account**, under IAM
+> policies you review and apply yourself. The published policy documents
+> ([least-privilege guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/least-privilege-iam.md),
+> [policy JSON](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/iam-policies.md))
+> are **reference configurations provided AS IS** — you remain responsible for
+> scoping, costs, and security. Full terms:
+> [DISCLAIMER.md](https://github.com/bnb-chain/bnbagent-studio/blob/main/DISCLAIMER.md)
+> (also shipped in this package as `bag/DISCLAIMER.md`).
+
+## Overview
+
+`bnbagent-studio` scaffolds and deploys a **two-layer seller** on BNB Chain:
+
+- **Layer A — the Agent** (deployed invoke-only to AWS Bedrock AgentCore): the
+  value (LLM, memory, tools) **and** the sole key-holder/signer. It is invoked
+  on an action envelope — `quote` / `fulfill` / `settle`. All signing is fixed
+  entrypoint code, never an LLM-callable tool.
+- **Layer B — the ERC-8183 Service** (deployed to EC2): a public, long-running,
+  **keyless** container — a funded-job poller plus a `/apex/negotiate` ingress.
+  It holds no key, runs no LLM, and never signs; it delegates every signing op
+  to the Agent.
+
+This package is the **dev-time tool**. It imports as `bag` and depends on
+**[`bnbagent-studio-core`](https://pypi.org/project/bnbagent-studio-core/)**
+(import `bnbagent_studio_core`), the agent-runtime library that runs inside the
+deployed Agent — installing this package auto-pulls core. Both sit on top of the
+[`bnbagent`](https://pypi.org/project/bnbagent/) SDK protocol layer.
+
+v1 is **seller-only**. Buyer product flows, KMS/remote signing, and multi-chain
+support are on the [roadmap](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/roadmap.md)
+for a later release.
+
+## Installation
+
+```bash
+uv tool install bnbagent-studio       # machine-wide CLI (recommended)
+# or
+pip install bnbagent-studio           # into the active environment
+# or
+uvx bnbagent-studio init my-agent     # one-shot, no install
+```
+
+Installing `bnbagent-studio` pulls in `bnbagent-studio-core` automatically.
+Verify:
+
+```bash
+bag --version
+bag --help            # lists every command group
+```
+
+### Requirements
+
+- **Python ≥ 3.10**.
+- **Claude Code or Cursor** — required to use the bundled skills (the
+  natural-language workflow). The CLI works without them.
+- **The native AgentCore CLI** — `bag init` / `bag dev` / `bag deploy agent`
+  shell out to it. Install with `npm install -g @aws/agentcore` (**Node ≥ 20**).
+  Make sure the npm CLI wins on `PATH` over any Python
+  `bedrock-agentcore-starter-toolkit` shim (`which -a agentcore`,
+  `node --version`).
+- An **AWS account** is needed only when you deploy — never for local
+  development.
+
+## 🚀 Getting started
+
+This is the canonical, beginner-friendly path: **install → install skills →
+drive from your IDE → run both layers locally → deploy.** You mostly talk to
+Claude Code in plain language; the studio runs the CLI for you. The full,
+deepest version of this walkthrough is in the
+[User Guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md).
+
+### What to prepare
+
+- Python ≥ 3.10 and Claude Code (or Cursor).
+- The native AgentCore CLI (`npm install -g @aws/agentcore`, Node ≥ 20).
+- **A wallet password you choose.** `bag` creates a *local* encrypted keystore;
+  the password lives only in your shell env as `WALLET_PASSWORD` and is never
+  written to disk.
+- **Optional:** testnet funds (tBNB + $U from a faucet) and your own LLM API
+  key. Neither is required to start — the default **Pieverse** LLM provider
+  activates with a **$0 deposit**.
+
+### 1. Install the CLI
+
+```bash
+uv tool install bnbagent-studio       # or: pip install bnbagent-studio
+bag --version                          # confirm it's on PATH
+```
+
+### 2. Install the skills into your IDE
+
+Claude Code doesn't know the studio exists until you install the skills.
+
+```bash
+bag skills install
+# On a TTY: auto-detects Claude Code / Cursor, lets you pick scope (user/project),
+# and installs 10 skills, e.g.:
+#   claude-code [user]: installed=10 target=~/.claude/skills
+```
+
+Non-interactive (CI) form:
+
+```bash
+bag skills install --target both --scope user      # Claude Code + Cursor, machine-wide
+bag skills install --target cursor --scope project # Cursor only, this workspace
+```
+
+**Then reload your IDE window** so it picks up the skills. (Remove them later
+with `bag skills uninstall`.)
+
+### 3. Drive it in natural language from Claude Code
+
+Open Claude Code where you want the project to live, and just say what you want.
+Concrete prompts that work:
+
+> "Create a new BNB seller agent named weather-seller on testnet that sells
+> weather forecasts."
+
+> "Start my agent and verify it works."
+
+> "Is my wallet funded? What's my $U balance?"
+
+> "Register my agent on chain so others can find it."
+
+The skills tell Claude Code how to chain the CLI for you — it runs `bag init`,
+sets up the per-layer virtualenvs, runs `bag wallet new` (prompting you for
+`WALLET_PASSWORD`), runs `bag doctor`, and edits your project files. It stops to
+ask you for the wallet password, for confirmation before any real on-chain
+transaction, and for a faucet step if your wallet has 0 tBNB.
+
+`bag init` emits a thin workspace root plus two independent sub-projects:
+`app/agent/` (Layer A — the Agent and sole signer) and `app/service/` (Layer B
+— the keyless Service). The encrypted keystore is written to the **workspace
+root** `.studio/wallets/`, deliberately outside the deploy code location.
+
+> Prefer to do it by hand? `bag init weather-seller` runs the same onboarding on
+> an interactive terminal — it prompts once for the wallet password, creates the
+> keystore, zero-deposit activates Pieverse, and prints testnet faucet URLs. For
+> a non-Pieverse provider, set the key afterward, e.g.
+> `echo "OPENROUTER_API_KEY=sk-or-..." >> weather-seller/app/agent/.env.local`.
+
+### 4. Run both layers locally
+
+```bash
+bag dev        # from the workspace root (or app/agent/)
+```
+
+`bag dev` mirrors the two-artifact deploy and **launches both layers by
+default**:
+
+- **Agent** on `:8080` — Layer A, the sole signer, runs the LLM
+  (`POST /invocations`).
+- **keyless Service** on `:8003` — Layer B, public `/apex/negotiate` +
+  funded-job poller.
+
+They're wired over `STUDIO_AGENT_LOCAL_URL` and share `STORAGE_LOCAL_PATH` for
+deliverable handoff. Useful flags: `--agent-only` / `--service-only`,
+`--port` / `--service-port`.
+
+Health check the Service: `curl localhost:8003/apex/health` →
+`{"status":"ok","keyless":true}`. Then exercise the full negotiate path:
+
+```bash
+curl -X POST http://localhost:8003/apex/negotiate \
+  -H 'Content-Type: application/json' \
+  -d '{"task_description": "5-day forecast for Singapore",
+       "terms": {"deliverables": "JSON forecast", "quality_standards": "hourly granularity"}}'
+# → the Service relays the Agent's signed offer
+#   (the Agent prices, clamps to [min_price, max_price], then EIP-191 signs)
+```
+
+### 5. Deploy
+
+When you're ready, ask Claude Code to deploy, or run it yourself. Deploy is
+**two-artifact**: the Agent goes to AWS Bedrock AgentCore (invoke-only), the
+keyless Service goes to an EC2 systemd host.
+
+```bash
+agentcore configure          # once — writes agentcore/agentcore.json
+bag deploy agent             # pushes secrets to AWS Secrets Manager, then delegates
+                             # to `agentcore deploy`; captures the runtime ARN
+bag deploy status            # what still needs deploying
+bag deploy verify --endpoint <service-url>   # probe + reconcile your ERC-8004 record
+```
+
+By default (`--secrets-mode secretsmanager`) the encrypted keystore is injected
+into the Agent via AWS Secrets Manager (`WALLET_KEYSTORE_JSON`) and is **never**
+bundled into the code package. The keyless Service never holds the key. For the
+EC2 Service deploy steps, ask Claude Code to load the
+`bnbagent-studio-deploying-service-to-ec2` skill.
+
+For the complete walkthrough — IDE/skill scopes, per-project MCP wiring, the
+manual two-terminal run, and the deploy details — see the
+[User Guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md).
+
+## Direct CLI use
+
+`bag` is also a full CLI you can run by hand. `bag --help` shows the complete
+surface, and `bag <group> --help` lists a group's subcommands. The command
+groups:
+
+| Group | What it does |
+|---|---|
+| `init` | Scaffold a two-layer agent project (`app/agent/` + `app/service/`) + onboarding |
+| `skills` | Install / remove the IDE skills (`install` / `uninstall` / `list`; `--target` / `--scope`) |
+| `install` / `uninstall` | Deprecated aliases of `bag skills install` / `bag skills uninstall` |
+| `dev` | Run BOTH layers locally (Agent :8080 + keyless Service :8003) |
+| `doctor` | Diagnose project + environment readiness across both sub-projects |
+| `wallet` | Local keystore: `new` / `show` / `list` / `sign` / `balance` / `policy` |
+| `erc8004` | Identity: `register` / `show` / `resolve` / `update-endpoint` |
+| `erc8183` | Commerce: `publish` / `list` / `buy` / `status` / `submit` / `fetch` / `settle` |
+| `x402` | x402 payment client helpers (`quote` / `buy`) |
+| `llm` | LLM provider helpers (`test` / `activate` / `status` / `topup` / `usage` / `list-models` / `rotate` / `allocate` / `auto-renew`) |
+| `deploy` | Two-layer deploy flow (`prepare` / `agent` / `package` / `verify` / `status` / `destroy` / `logs` / `fix-gitignore` / `fix-a2a-disable`) |
+| `mcp` | Run the read-only MCP server (`bag mcp serve` / `bag mcp tools`) |
+| `bundle` | Pack an agent project + local wheels into an offline-installable tarball |
+| `scan` | Detect project framework + manifest (read-only) |
+| `recipe` | Emit / re-emit a single recipe layer |
+| `config` | Read / write `studio.toml` (`show` / `get` / `set` / `list-keys`) |
+| `env` | Edit `.env.local` idempotently (`set` / `get`) |
+| `agents` | Local agent project registry (`~/.bnbagent-studio/projects.toml`) |
+| `budget` | Opt-in auto-topup policy for the Pieverse LLM |
+| `audit` | View the on-chain action audit log |
+
+### `bag dev` — the local two-service mirror
+
+`bag dev` runs from the workspace root (or `app/agent/`) and **launches both
+layers by default**:
+
+- **Agent** on `:8080` — Layer A, the sole signer, runs the LLM (`POST /invocations`).
+- **keyless Service** on `:8003` — Layer B, public `/apex/negotiate` + funded-job poller.
+
+Flags: `--agent-only` / `--service-only`, `--port` / `--service-port`,
+`--reload`.
+
+## 🔌 MCP server
+
+`bag mcp serve` runs a read-only MCP server over stdio — this is what an IDE
+launches. It exposes **15 read-only chain tools**:
+
+- **Wallet & balances** — `wallet_info`, `wallet_list`, `wallet_address`,
+  `balance_native`, `balance_u`
+- **Network & tx** — `network_info`, `tx_status`, `block_info`,
+  `contract_call_view`
+- **ERC-8004 identity** — `agent_info`, `agent_by_address`
+- **ERC-8183 commerce** — `job_status`, `job_list`, `job_count`
+- **LLM usage** — `pieverse_usage`
+
+Read-only by design: **no signing, no on-chain state change.** List the tools
+with `bag mcp tools`. Wire one MCP entry per project so your AI tool reads the
+right keystore + `studio.toml` — see the
+[User Guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md#4-install-the-mcp-server).
+Only **stdio** transport is supported in v1.
+
+## Relationship to `bnbagent-studio-core`
+
+This distribution ships, under the `bag` import package: `bag/cli`, `bag/mcp`,
+`bag/recipes`, `bag/utils`, `bag/skills_installer.py`, and the bundled
+`skills/`.
+
+It depends on the runtime library
+**[`bnbagent-studio-core`](https://pypi.org/project/bnbagent-studio-core/)**
+(import `bnbagent_studio_core`), which `pip install bnbagent-studio` pulls in
+automatically.
+
+A *deployed* Agent does **not** install this CLI — it depends only on
+`bnbagent-studio-core`. `bnbagent-studio` is the dev-time tool you use to
+scaffold, develop, and deploy; core is the library that runs in production.
+
+## 📚 Further reading
+
+- [Main repository](https://github.com/bnb-chain/bnbagent-studio)
+- [User Guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md) — full install → skills → Claude Code → `bag dev` walkthrough
+- [CLI / recipe / MCP reference](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/reference.md)
+- [Architecture](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/design/architecture.md)
+- [Roadmap](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/roadmap.md) — what's shipped and what's deferred
+
+## License
+
+Apache-2.0.