@bnbagent/studio-cli 0.0.6-alpha.1

package/dist/chunk-U7IDQ3K5.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// src/cli/_agentcoreName.ts
+var AGENTCORE_NAME_RE = /^[A-Za-z][A-Za-z0-9]{0,22}$/;
+function validateAgentcoreName(name) {
+  if (AGENTCORE_NAME_RE.test(name)) {
+    return null;
+  }
+  return `agentcore.json name '${name}' is invalid: the agentcore CLI requires a name that starts with a letter, contains only ASCII letters/digits (no '_', '-', '.'), and is at most 23 characters. The agentcore CLI's own error for this can be misleading ('No agentcore project found') \u2014 fix the 'name' field in agentcore/agentcore.json.`;
+}
+
+export {
+  validateAgentcoreName
+};

package/dist/deployCli-N6TPN6XA.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import {
+  BNB_PLATFORM_API_URL,
+  BNB_PLATFORM_API_URL_ENV,
+  DEPLOY_CLI_PACKAGE,
+  DEPLOY_CLI_VERSION,
+  LEGACY_BNB_PLATFORM_API_URL_ENV,
+  bnbEnv,
+  bnbPlatformApiUrl,
+  buildDeploySpec,
+  deployCommand,
+  deployEndpointValue,
+  providerPassthrough,
+  renderSecretEnvFile,
+  runDeployCliJson,
+  runDeployCliStream,
+  runPlatformAccountCommand,
+  trialFromDeployCliJson,
+  withDeployFiles
+} from "./chunk-M3ODFCA7.js";
+import "./chunk-7RAKL4AS.js";
+export {
+  BNB_PLATFORM_API_URL,
+  BNB_PLATFORM_API_URL_ENV,
+  DEPLOY_CLI_PACKAGE,
+  DEPLOY_CLI_VERSION,
+  LEGACY_BNB_PLATFORM_API_URL_ENV,
+  bnbEnv,
+  bnbPlatformApiUrl,
+  buildDeploySpec,
+  deployCommand,
+  deployEndpointValue,
+  providerPassthrough,
+  renderSecretEnvFile,
+  runDeployCliJson,
+  runDeployCliStream,
+  runPlatformAccountCommand,
+  trialFromDeployCliJson,
+  withDeployFiles
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@bnbagent/studio-cli",
+  "version": "0.0.6-alpha.1",
+  "description": "The `bag` CLI: scaffold, run, deploy, and monetize a single seller agent on BNB Chain (ERC-8004 identity, ERC-8183 commerce, x402 payments).",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bnb-chain/bnbagent-studio.git",
+    "directory": "packages/studio-cli"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "recipes",
+    "DISCLAIMER.md"
+  ],
+  "bin": {
+    "bag": "./dist/bag.js"
+  },
+  "dependencies": {
+    "@bnbagent/sdk": "0.5.0-alpha.1",
+    "ai": "^7.0.29",
+    "archiver": "^8.0.0",
+    "commander": "^15.0.0",
+    "esbuild": "^0.28.0",
+    "execa": "^9.5.0",
+    "picocolors": "^1.1.0",
+    "proper-lockfile": "^4.1.2",
+    "smol-toml": "^1.3.0",
+    "tar": "^7.4.0",
+    "viem": "^2.54.0",
+    "yaml": "^2.9.0",
+    "@bnbagent/studio-runtime": "0.0.6-alpha.1"
+  },
+  "devDependencies": {
+    "@a2a-js/sdk": "^0.3.14",
+    "@ai-sdk/openai": "^4.0.15",
+    "@aws-sdk/client-secrets-manager": "^3.600.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "express": "^5.2.1",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "zod": "^3.25.76"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "biome check src tests",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  }
+}

package/recipes/agent/code/{{PKG}}/signing.ts.tmpl

@@ -0,0 +1,287 @@
+/**
+ * Deterministic signing — the Agent is the SOLE key-holder/signer.
+ *
+ * Every on-chain WRITE the Agent performs lives here as FIXED code:
+ *
+ *     signQuote(...)    EIP-191 sign the (clamped) negotiated offer
+ *     submitResult(...) build manifest → upload → on-chain `submit`
+ *     settle(...)       claim payment after the dispute window
+ *
+ * These functions are NEVER registered as LLM-callable tools (`tools.ts` holds
+ * only read-only tools). The price is a FIXED list price from studio.toml
+ * (`listPrice()`, clamped by the entrypoint BEFORE it reaches here) — the LLM
+ * only produces the work text and never moves money or sets a price.
+ *
+ * The key is loaded by `@bnbagent/studio-runtime/wallet` `getWallet()` (local
+ * keystore, unlocked by `WALLET_PASSWORD`). It is injected into the AgentCore
+ * runtime via the secret store, never bundled into the code package.
+ *
+ * You own this file — edit the pricing clamp source / manifest shape if your
+ * domain needs it, but keep these ops OUT of the LLM tool list.
+ */
+
+import {
+  JobDescription,
+  NegotiationHandler,
+  type NegotiationResult,
+  type QuoteSigner,
+} from "@bnbagent/sdk/erc8183";
+import { getAddress as deployedAddresses } from "@bnbagent/sdk/networks";
+import {
+  loadStudioToml,
+  type TomlTable,
+} from "@bnbagent/studio-runtime/config";
+import {
+  get8183Client,
+  settleWorkflow,
+  type SubmitResult,
+  submitWorkflow,
+  type Verdict,
+  verifySignedJob as verifySignedJobCore,
+} from "@bnbagent/studio-runtime/erc8183";
+import { getNetwork } from "@bnbagent/studio-runtime/networks";
+import { getWallet } from "@bnbagent/studio-runtime/wallet";
+
+const MAX_UINT256 = (1n << 256n) - 1n;
+
+// ── test seams (mirror the studio-runtime `_set*` convention) ────────────────
+type StudioTomlLoader = () => TomlTable;
+const defaultTomlLoader: StudioTomlLoader = () => loadStudioToml();
+let tomlLoader: StudioTomlLoader = defaultTomlLoader;
+
+/** Test seam: replace the studio.toml loader. Pass null to restore. */
+export function _setStudioTomlLoader(loader: StudioTomlLoader | null): void {
+  tomlLoader = loader ?? defaultTomlLoader;
+  handler = null; // config feeds the cached handler — rebuild it
+}
+
+/** The narrow NegotiationHandler surface signQuote drives (test-fakeable). */
+export interface NegotiationHandlerLike {
+  negotiate(
+    request: Record<string, unknown>,
+    opts?: { price?: string; estimatedCompletionSeconds?: number },
+  ): Promise<NegotiationResult> | NegotiationResult;
+}
+
+let handler: NegotiationHandlerLike | null = null;
+
+type RuntimeWallet = ReturnType<typeof getWallet>;
+type SessionQuoteWallet = RuntimeWallet & {
+  sessionQuoteSigner(): QuoteSigner;
+};
+
+/** Select the narrow quote-only authority when the wallet exposes one. */
+export function negotiationSignerOptions(
+  wallet: RuntimeWallet,
+): { quoteSigner: QuoteSigner } | { walletProvider: RuntimeWallet } {
+  const candidate = wallet as Partial<SessionQuoteWallet>;
+  return typeof candidate.sessionQuoteSigner === "function"
+    ? { quoteSigner: candidate.sessionQuoteSigner.call(wallet) }
+    : { walletProvider: wallet };
+}
+
+/** Test seam: replace the cached NegotiationHandler. Pass null to restore. */
+export function _setNegotiationHandler(h: NegotiationHandlerLike | null): void {
+  handler = h;
+}
+
+// ── config readers ────────────────────────────────────────────────────────────
+
+/** Read `[payments.erc8183]` from studio.toml ({} when absent). */
+function erc8183Cfg(): Record<string, unknown> {
+  let cfg: TomlTable;
+  try {
+    cfg = tomlLoader();
+  } catch {
+    // No studio.toml here; use the safe empty-config fallback.
+    cfg = {};
+  }
+  const payments = (cfg.payments ?? {}) as Record<string, unknown>;
+  return (payments.erc8183 ?? {}) as Record<string, unknown>;
+}
+
+/** studio.toml `[network].default` (best-effort; binds the quote signature). */
+function defaultNetworkName(): string {
+  let cfg: TomlTable;
+  try {
+    cfg = tomlLoader();
+  } catch {
+    cfg = {};
+  }
+  return String(((cfg.network ?? {}) as TomlTable).default ?? "bsc-testnet");
+}
+
+/**
+ * Return `[minPrice, maxPrice]` in raw wei from studio.toml.
+ *
+ * These are the clamp bounds applied to the configured list price BEFORE
+ * signing. `min_price`/`max_price` are raw uint256 strings in
+ * `[payments.erc8183]`.
+ */
+export function priceBounds(): [bigint, bigint] {
+  const cfg = erc8183Cfg();
+  // TODO: if min/max are absent the bounds default to (0, +inf) — i.e. NO
+  // clamp. Set [payments.erc8183].min_price / max_price in studio.toml to
+  // enforce a real floor/ceiling (strongly recommended for production).
+  // The scaffold ships max_price = "" (an empty string, not absent), so treat
+  // empty/whitespace the same as missing → fall back to the default bound.
+  const raw = (key: string, dflt: bigint): bigint => {
+    const s = String(cfg[key] ?? "").trim();
+    return s ? BigInt(s) : dflt;
+  };
+  return [raw("min_price", 0n), raw("max_price", MAX_UINT256)];
+}
+
+/**
+ * Return the seller's list price in raw wei from studio.toml.
+ *
+ * Reads `[payments.erc8183].price` — the deterministic asking price every
+ * quote uses (rule-based pricing; no LLM in the quote path). Empty/absent → 0.
+ * Edit `price` in studio.toml to change what you charge. The value is still
+ * clamped to `[minPrice, maxPrice]` by {@link clampPrice} before signing.
+ */
+export function listPrice(): bigint {
+  const s = String(erc8183Cfg().price ?? "").trim();
+  return s ? BigInt(s) : 0n;
+}
+
+/** Clamp a proposed price into `[minPrice, maxPrice]`. */
+export function clampPrice(proposedWei: bigint): bigint {
+  const [lo, hi] = priceBounds();
+  const capped = proposedWei < hi ? proposedWei : hi;
+  return capped > lo ? capped : lo;
+}
+
+/**
+ * Return the process-wide NegotiationHandler (lazy, cached).
+ *
+ * The handler's chainId + verifyingContract are stable per process, so we
+ * build it once. The per-request clamped price is passed via
+ * `negotiate(..., { price })` (see {@link signQuote}), so the
+ * construction-time `servicePrice` is a placeholder that is always
+ * overridden.
+ *
+ * chainId + verifyingContract bind provider_sig to this chain/contract
+ * (prevents cross-chain replay). The runtime client facade does not expose
+ * them, so
+ * they come from the SDK's on-chain address registry for the configured
+ * network — the same addresses the live client is constructed from.
+ */
+function getHandler(): NegotiationHandlerLike {
+  if (handler === null) {
+    const cfg = erc8183Cfg();
+    const currency = String(cfg.currency ?? ""); // the Agent owns the currency now
+    const ttl = Number(cfg.quote_ttl_seconds ?? 900);
+    const est = Number(cfg.default_estimated_completion_seconds ?? 600);
+    const network = getNetwork(defaultNetworkName());
+    const wallet = getWallet();
+    handler = new NegotiationHandler({
+      servicePrice: "0", // placeholder — overridden per call via price=
+      currency,
+      estimatedCompletionSeconds: est,
+      ...negotiationSignerOptions(wallet),
+      quoteTtlSeconds: ttl,
+      chainId: network.chainId,
+      verifyingContract: deployedAddresses(network.chainId).commerceProxy,
+    });
+  }
+  return handler;
+}
+
+/**
+ * Negotiate + EIP-191-sign a quote at `clampedPriceWei`; return the SDK
+ * envelope.
+ *
+ * Reuses a process-wide NegotiationHandler (cached — its chainId +
+ * verifyingContract are stable per process) and overrides the price for this
+ * request via `negotiate(..., { price: String(clampedPriceWei) })`.
+ *
+ * Returns the SDK's `NegotiationResult.toDict()` envelope **verbatim** — the
+ * exact wire structure a buyer parses and feeds to `buildJobDescription` to
+ * anchor on-chain (see docs/design/erc8183-reference.md §2). On accept it
+ * carries `response.terms.price`/`currency`, `quote_expires_at`,
+ * `negotiation_hash`, `response_hash`, `provider_sig`, `chain_id`,
+ * `verifying_contract`; on reject it carries `response.reason_code` /
+ * `reason` (empty hash + sig). We do NOT invent a custom shape.
+ */
+export async function signQuote(
+  request: Record<string, unknown>,
+  clampedPriceWei: bigint,
+): Promise<Record<string, unknown>> {
+  const cfg = erc8183Cfg();
+  const est = Number(cfg.default_estimated_completion_seconds ?? 600);
+
+  const result = await getHandler().negotiate(request, {
+    price: String(clampedPriceWei),
+    estimatedCompletionSeconds: est,
+  });
+
+  // NegotiationHandler signs non-fatally: if signMessage failed it returns an
+  // accepted result WITHOUT provider_sig. Never relay an unsigned "accepted".
+  if (result.accepted && (!result.negotiationHash || !result.providerSig)) {
+    throw new Error(
+      "quote accepted but provider_sig is missing (wallet sign failed); " +
+        "refusing to relay an unsigned offer",
+    );
+  }
+
+  return result.toDict();
+}
+
+/**
+ * Verify funded `jobId` carries the quote THIS agent signed.
+ *
+ * Thin wrapper over `@bnbagent/studio-runtime/erc8183` `verifySignedJob` with
+ * `expectedSigner` = our own wallet address. Returns a `Verdict` `{ ok,
+ * reason, permanent }`: `ok` → safe to work; otherwise `permanent`
+ * distinguishes a job to skip-forever (record + tell the client) from a
+ * transient retry.
+ */
+export async function verifySignedJob(jobId: number): Promise<Verdict> {
+  return verifySignedJobCore(jobId, getWallet().address);
+}
+
+/**
+ * Return the on-chain `JobDescription` for `jobId` (`null` if unstructured).
+ *
+ * The task + terms the buyer ANCHORED ON-CHAIN — and that this agent's
+ * `provider_sig` covers — are the authoritative work spec. The work hook
+ * reads the task from HERE (the on-chain job description), so the Agent
+ * delivers exactly the deal it signed.
+ * Returns `null` for legacy/plain-text descriptions (caller falls back).
+ */
+export async function jobSpec(jobId: number): Promise<JobDescription | null> {
+  const client = await get8183Client();
+  const job = await client.getJob(BigInt(jobId));
+  return JobDescription.fromStr(job.description);
+}
+
+/**
+ * Sign + broadcast the on-chain `submit` for `jobId`.
+ *
+ * Delegates to `@bnbagent/studio-runtime/erc8183` `submitWorkflow`, which
+ * re-verifies the job is genuinely FUNDED + assigned to us (via the SDK's
+ * `ERC8183JobOps.verifyJob`), builds the `DeliverableManifest`, uploads it
+ * to storage, and calls on-chain `submit` — all `auditedOp`-wrapped.
+ * Returns the `SubmitResult` (`.submitTx` + `.deliverableUrl`);
+ * `deliverableUrl` is published on-chain by the submit, so the buyer fetches
+ * the canonical manifest from storage without an on-chain log scan.
+ */
+export async function submitResult(
+  jobId: number,
+  responseContent: string,
+  metadata?: Record<string, unknown> | null,
+): Promise<SubmitResult> {
+  return submitWorkflow(jobId, responseContent, { metadata: metadata ?? null });
+}
+
+/**
+ * Sign + broadcast `settle` (claim payment) for `jobId`.
+ *
+ * Delegates to `@bnbagent/studio-runtime/erc8183` `settleWorkflow` with the
+ * default `approve` action → SDK `router.settle(jobId)`, `auditedOp`-wrapped.
+ * Returns the settle tx hash.
+ */
+export async function settle(jobId: number): Promise<string> {
+  return settleWorkflow(jobId, { action: "approve" });
+}

package/recipes/agent/recipe.toml

@@ -0,0 +1,35 @@
+[recipe]
+name = "agent"
+description = "Agent — protocol-neutral signing entrypoints (signQuote / submitResult / settle). The Agent is the SOLE key-holder/signer; this recipe emits the fixed signing.ts glue that the LLM never calls. Runtime choice (AgentCore / Azure Foundry) lives in `runtimes/<runtime>/` (which also carries the chain tools + model factory — decision D9: no separate frameworks recipe in the TS line)."
+status = "signing-only"  # only signing.ts here; runtime/provider code lives in their own recipes
+
+[dependencies]
+node = [
+    # signing.ts imports only from @bnbagent/studio-runtime (erc8183 + wallet +
+    # config + networks subpaths) and the @bnbagent/sdk protocol layer
+    # (NegotiationHandler / JobDescription) — protocol-level glue, framework-
+    # neutral. The agent project's serving deps (@a2a-js/sdk / MCP SDK / ai)
+    # come from the runtimes/<R>/ recipe selected at `bag init` time.
+    "@bnbagent/studio-runtime",
+    "@bnbagent/sdk@0.5.0-alpha.1",
+]
+
+[env]
+# WALLET_PASSWORD unlocks the local keystore. The agent is the SOLE signer:
+# it uses the key for quote-sign + submit + settle (signing.ts, fixed code,
+# NOT LLM tools) AND automatic budget-gated Pieverse LLM-credit auto-renew.
+# The keystore is injected via the AgentCore secret store, NEVER bundled.
+WALLET_PASSWORD = "wallet keystore password (the agent is the sole on-chain signer)"
+PIEVERSE_LLM_API_KEY = "set by `bag llm activate` for the default Pieverse provider"
+# OPENROUTER_API_KEY = "set if [llm].provider=openrouter (legacy)"
+# STORAGE_API_URL / STORAGE_API_KEY: IPFS upload endpoint + write key — the
+# Agent pins deliverables at submit ([storage].kind=ipfs). Any pinning service
+# works (use its upload/pin endpoint + key/JWT), as does a self-hosted node's
+# /api/v0/add (usually keyless). Agent-only secrets — inject into the AgentCore
+# secret store at deploy, like WALLET_PASSWORD.
+STORAGE_API_URL = "IPFS upload endpoint (required when [storage].kind=ipfs)"
+STORAGE_API_KEY = "pinning-service write key/JWT (hosted services; self-hosted nodes usually need none)"
+# RPC_URL: dedicated BSC RPC for the deployed Agent (SDK var). Set it to avoid
+# the rate-limited public BSC RPC default; when set it is pushed with the
+# runtime secrets on deploy. The STUDIO_BSC_RPC* vars are CLI-side only.
+# RPC_URL = "https://your-dedicated-bsc-rpc"

package/recipes/providers/pieverse-llm/recipe.toml

@@ -0,0 +1,16 @@
+[recipe]
+name = "providers/pieverse-llm"
+description = "Provider-specific assets for Pieverse LLM: emits `funding-pieverse-llm` skill into the project's `.claude/skills/` so Claude Code knows how to handle Pieverse credit / topup / paid-model decisions."
+status = "v0.0.1"
+
+# This is a "provider" recipe — non-code: it emits documentation/skill
+# artifacts that travel with the chosen LLM provider. There is no `code/`
+# directory; the init flow's provider-skill emitter reads `skills/*.md`
+# and writes each to `<project>/.claude/skills/<stem>/SKILL.md`.
+#
+# Future on-chain providers (e.g. Bittensor, Aether) can follow the same
+# layout: drop `skills/<name>.md` files here under their own provider dir
+# and they'll be emitted at `bag init --llm-provider <name>` time.
+
+[skills]
+emit = ["funding-pieverse-llm"]

package/recipes/providers/pieverse-llm/skills/funding-pieverse-llm.md

@@ -0,0 +1,203 @@
+---
+name: funding-pieverse-llm
+description: When the user is dealing with Pieverse LLM funding — switching to a paid model, hitting InsufficientCreditsError / PieverseAccountBalanceExhaustedError, topping up the wallet for paid LLM usage, or asking "how do I pay for the LLM" / "why is my agent stuck on LLM". Covers the zero-deposit default + the paid-upgrade path.
+---
+
+# funding-pieverse-llm
+
+Procedure for **Pieverse LLM funding decisions** in a bnbagent-studio project.
+Audience: Claude Code helping a user who has already run `bag init` + `bag llm activate`.
+
+**Different from**: `-operating` (general ops) — this skill is specifically for the
+Pieverse credit lifecycle, paid-model upgrade, and topup troubleshooting.
+
+## Mental model (zero-deposit default)
+
+bnbagent-studio v0.0.x defaults to **zero-deposit Pieverse activation**:
+
+- `bag init` + `bag llm activate` together create a Pieverse account + API key
+  with **$0 initial allocation**. No wallet funding required.
+- Default model is **`auto/free`** (Pieverse's $0/token tier). The agent runs
+  unmetered against it.
+- The user **only needs to fund their wallet** when they want to:
+  1. Switch to a **paid model** (e.g. `auto/paid`, `claude-haiku-4.5`,
+     `anthropic/claude-sonnet-4.6`, etc.)
+  2. Run `bag erc8004 register` (needs **testnet tBNB** for gas)
+  3. `bag deploy` to AgentCore
+
+**Three independent balances**, on the same EOA address but different chains/assets:
+
+| Balance | Chain | Purpose | When needed |
+|---|---|---|---|
+| testnet tBNB | BSC testnet (97) | gas for ERC-8004 / ERC-8183 / deploy txs | register / deploy |
+| testnet U | BSC testnet (97) | ERC-8183 job settlement | when this agent buys/sells via 8183 |
+| mainnet U | BSC mainnet (56) | Pieverse paid LLM credits | switching to paid LLM model |
+
+Use `bag wallet balance --all` to see all three.
+
+## Quick triage decision tree
+
+| User said... | Run first |
+|---|---|
+| "how do I switch to claude/opus/sonnet/paid model" | Section A below |
+| `InsufficientCreditsError` during a negotiate or job delivery | Section B below |
+| `PieverseAccountBalanceExhaustedError` | Section B below |
+| `PieverseColdStartTopupBlockedError` | Section C below |
+| "I want auto-renew without being asked" / "turn auto-renew on/off" | Section D below (`bag llm auto-renew status`) |
+| "how much U / credit do I have" | `bag llm usage` (no password) + `bag llm status` (key credit) + `bag wallet balance --all` |
+| "why is gas failing" | testnet tBNB ≠ mainnet U; check `bag wallet balance --all` |
+
+## A. Switch from `auto/free` to a paid model
+
+```bash
+# 1. fund the wallet (mainnet U)
+#    The wallet address is the same EOA that signs ERC-8004 txs; on mainnet
+#    only the U balance matters here.
+bag wallet show
+#    Then either:
+#    - swap on PancakeSwap → https://pancakeswap.finance/swap
+#      ?outputCurrency=0xcE24439F2D9C6a2289F741120FE202248B666666
+#    - transfer U from another wallet to the address above
+bag wallet balance --all   # confirm mainnet U > 0
+
+# 2. allocate paid credits into the API key
+bag llm topup --amount 1   # start small ($1 covers many calls on auto/paid)
+
+# 3. change the default model in studio.toml
+bag config set llm.model auto/paid                # or anthropic/claude-haiku-4.5 etc.
+
+# 4. verify
+bag llm status               # should show non-zero key_credit
+bag llm test                 # one-shot smoke check
+```
+
+**Do NOT** silently fallback to `auto/free` when a paid call fails — see the
+zero-deposit hard-fail rule. The user explicitly chose a paid model; surface the failure.
+
+## B. InsufficientCreditsError / PieverseAccountBalanceExhaustedError
+
+The agent's API key ran out of credit (or never had any). Recovery:
+
+```bash
+# Diagnose
+bag llm status               # key_credit (per-key balance); Account Balance has no API endpoint
+bag llm usage --days 7       # see what was spent
+
+# If account balance > 0 but key balance = 0: allocate from account → key
+bag llm allocate --amount 1
+
+# If account balance = 0: topup from mainnet U first
+bag wallet balance --all     # check mainnet U
+bag llm topup --amount 1     # spends mainnet U via x402
+bag llm allocate --amount 1  # then allocate
+```
+
+Never edit `studio.toml [llm].model = auto/free` to "fix" a paid model's
+funding error — that's silently changing agent behavior. Either fund or
+explicitly downgrade, and tell the user which you did.
+
+## C. PieverseColdStartTopupBlockedError
+
+The auto-topup hook refuses to fund during the first 60 seconds after process
+start. This is a **safety feature** (闸门 5) — it prevents boot-loop
+scenarios from burning the user's monthly budget.
+
+Recovery:
+- Wait 60s, then retry the LLM call (auto-topup will engage).
+- Or topup manually: `bag llm topup --amount N` (CLI is not subject to the
+  cold-start gate; only the in-process auto-topup hook is).
+- **Never** advise the user to set `PIEVERSE_BUDGET_COLD_START_SECONDS=0` to
+  work around this — that env var is for CI/e2e only. If the user is hitting
+  this repeatedly, it indicates the agent is restarting too often; investigate
+  why.
+
+## D. Auto-renew: two independent tiers + their switches
+
+Auto-renew is a **two-tier ladder**, each with its own on/off switch. Inspect
+both at once:
+
+```bash
+bag llm auto-renew status        # prints the llm tier AND the wallet tier
+```
+
+**Tier 1 — `llm` (allocate from Pieverse Account Balance; no wallet spend).**
+Default **on**. Before each LLM call the agent tops the API key up from credit
+already parked in the Account Balance when it dips below `min_balance_usd`.
+
+```bash
+bag llm auto-renew llm off       # disable: agent runs as a plain model, no credit hook
+bag llm auto-renew llm on        # re-enable (writes [llm.auto_renew].enabled)
+```
+
+**Tier 2 — `wallet` (spend wallet U via x402 to refill the Account Balance).**
+Default **off** (opt-in; the agent will not autonomously spend the wallet until
+this is on). Turning it on records a consent stamp — required before any
+autonomous spend.
+
+```bash
+bag llm auto-renew wallet on     # opt in (= bag budget enable; records acknowledged_at)
+bag llm auto-renew wallet off    # opt out (= bag budget disable)
+```
+
+`bag llm auto-renew wallet on` is exactly `bag budget enable` and accepts the
+same cap overrides via that command:
+
+```bash
+bag budget show                                  # current state (default: disabled)
+bag budget enable                                # default caps: $1/topup, $3/day, $15/month
+# Or customize the caps:
+bag budget enable \
+    --max-per-topup-usd 0.5 \
+    --max-per-day-usd 2 \
+    --max-per-month-usd 10
+```
+
+Once enabled, the agent will:
+- Wait at least 60s after process start before any topup (cold-start gate)
+- Try to topup_x402 from mainnet U when the API key drops below
+  `min_balance_usd` (default $0.2)
+- Stop and raise on cap-exceeded; not retry on failure (exponential backoff
+  applies — next LLM call may retry)
+- Log every topup attempt to `~/.bnbagent-studio/<project>/logs/topup.jsonl`
+  and print a red-text notice to stdout
+
+`WALLET_PASSWORD` env must be present in the runtime — without it the gate
+falls back to allocate-only mode (no wallet spend, no error).
+
+## E. Protocol-level details (for advanced cases)
+
+When the user needs to understand the Pieverse protocol itself (raw SIWE,
+x402 v2 envelope, deposit methods schema, signing typed data), point them
+to Pieverse's official skill markdown — it is the authoritative reference:
+
+- https://llm.pieverse.io/ai-gateway/skill.md (overview)
+- https://llm.pieverse.io/ai-gateway/references/siwe-format.md (SIWE login)
+- https://llm.pieverse.io/ai-gateway/references/x402-payment.md (topup mechanics)
+- https://llm.pieverse.io/ai-gateway/references/api-reference.md (key/usage)
+
+Do **not** re-implement what these documents specify. studio's `bag llm` /
+`bag wallet` commands already wrap these flows.
+
+## Read-only inspection (no password needed)
+
+The CLI commands that only need the `sk-pv-...` API key (no wallet signature)
+work without prompting for `WALLET_PASSWORD`:
+
+```bash
+bag llm usage [--days 7]         # per-key usage, no session
+bag llm test --message "hi"      # one-shot LLM smoke (uses key only)
+```
+
+Anything that needs the session_token (balance / deposits / key management)
+will require `WALLET_PASSWORD` to be set in the environment or interactively.
+
+## Hard rules
+
+- Wallet private keys are never sent to Pieverse, never logged, and never put in
+  error messages. (Deploying to the managed platform is the one case a key leaves
+  your machine — it is sent to the operator to sign; self-deploy keeps it local.)
+- `session_token` is memory-only per Pieverse spec — never persist to disk.
+- When in doubt about a topup amount, suggest **smaller** values. Starting at
+  $0.5 – $1 is far better than $5+ for a user's first paid run.
+- If the user has not opted into `bag budget enable`, never trigger an
+  auto-topup on their behalf — surface the error and let them decide.

package/recipes/runtimes/agentcore/code/{{PKG}}/.dockerignore.tmpl

@@ -0,0 +1,8 @@
+# Defense-in-depth: secrets and local state must never enter the image.
+# (.env.local is also stashed out of the packaging window by `bag deploy`;
+# wallet material reaches the runtime ONLY via Secrets Manager injection.)
+node_modules/
+dist/
+.env.local
+.studio/
+*.tsbuildinfo