@bnbagent/studio-cli 0.0.6-alpha.1

package/recipes/runtimes/agentcore/code/{{PKG}}/tools.ts.tmpl

@@ -0,0 +1,157 @@
+/**
+ * Read-only chain tools exposed to this agent's LLM (AI SDK `tool` wrap).
+ *
+ * Each entry in `LLM_READ_TOOLS` is a function from
+ * `@bnbagent/studio-runtime/tools` wrapped as a Vercel AI SDK tool. The LLM
+ * may call any tool in this set while producing the deliverable (the
+ * `notify_funded` work step); the `description` is what the LLM sees.
+ *
+ * You own this file — edit `LLM_READ_TOOLS` to control exactly what your
+ * agent can read on-chain. Entries for features your project doesn't use are
+ * commented out by default; uncomment after you've added the dependency to
+ * `studio.toml`.
+ *
+ * **All tools are read-only** by the studio definition: no on-chain state
+ * change, no transferable authority, no transaction signing, no EIP-712
+ * typed-data signing. The agent IS the sole on-chain signer, but ALL of its
+ * signing — quote-sign, submitResult, settle, plus the automatic
+ * budget-gated Pieverse LLM-credit auto-renew inside `buildModel()` — lives
+ * in `signing.ts` / `model.ts` as FIXED entrypoint code and is NEVER a tool
+ * the LLM can invoke. The LLM only produces work text after a job is
+ * verified funded; it can never price, sign, spend, or mutate chain state.
+ * Keep this set read-only.
+ *
+ * (`pieverseUsage` is the one exception in the underlying module: it does a
+ * SIWE EIP-191 personal_sign, domain-locked to llm.pieverse.io, no on-chain
+ * effect. It is commented out below.)
+ */
+
+import * as cr from "@bnbagent/studio-runtime/tools";
+import { loadStudioToml } from "@bnbagent/studio-runtime/config";
+import { tool, type ToolSet } from "ai";
+import { z } from "zod";
+
+/**
+ * The project-wide default network (`[network].default`) — tool calls that
+ * omit `network` fall back to it, never to a hardcoded name.
+ */
+function defaultNetwork(): string {
+  try {
+    const cfg = loadStudioToml();
+    return String(
+      ((cfg.network ?? {}) as Record<string, unknown>).default ?? "bsc-testnet",
+    );
+  } catch {
+    return "bsc-testnet";
+  }
+}
+
+const networkArg = z
+  .string()
+  .optional()
+  .describe("studio network name (defaults to the project's [network].default)");
+
+export const LLM_READ_TOOLS: ToolSet = {
+  // --- Wallet & chain basics ---
+  wallet_info: tool({
+    description:
+      "Describe the agent's active wallet (address, kind, key location).",
+    inputSchema: z.object({}),
+    execute: async () => cr.walletInfo(),
+  }),
+  balance_native: tool({
+    description:
+      "Native BNB balance of an address (defaults to the agent's own wallet).",
+    inputSchema: z.object({
+      address: z.string().optional().describe("0x address; omit for own wallet"),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.balanceNative(address ?? null, network ?? defaultNetwork()),
+  }),
+  balance_u: tool({
+    // requires [u_token] in studio.toml
+    description:
+      "$U (payment token) balance of an address (defaults to the agent's own wallet).",
+    inputSchema: z.object({
+      address: z.string().optional().describe("0x address; omit for own wallet"),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.balanceU(address ?? null, network ?? defaultNetwork()),
+  }),
+  network_info: tool({
+    description: "Chain id / RPC / token info for a studio network.",
+    inputSchema: z.object({ network: networkArg }),
+    execute: async ({ network }) => cr.networkInfo(network ?? defaultNetwork()),
+  }),
+  tx_status: tool({
+    description: "Status + receipt summary of a transaction hash.",
+    inputSchema: z.object({
+      tx_hash: z.string().describe("0x transaction hash"),
+      network: networkArg,
+    }),
+    execute: async ({ tx_hash, network }) =>
+      cr.txStatus(tx_hash, network ?? defaultNetwork()),
+  }),
+
+  // --- LLM provider ---
+  // pieverse_usage: tool({
+  //   // SIWE personal_sign; requires [llm.provider=pieverse-llm]
+  //   description: "Pieverse LLM usage/credit summary for the last N days.",
+  //   inputSchema: z.object({ days: z.number().int().optional() }),
+  //   execute: async ({ days }) => cr.pieverseUsage(days ?? 7),
+  // }),
+
+  // --- ERC-8004 identity (read-only lookups the LLM may want for context) ---
+  agent_info: tool({
+    // requires [erc8004] in studio.toml
+    description: "ERC-8004 identity record for an agent id.",
+    inputSchema: z.object({
+      agent_id: z.number().int().describe("ERC-8004 agent id"),
+      network: networkArg,
+    }),
+    execute: async ({ agent_id, network }) =>
+      cr.agentInfo(agent_id, network ?? defaultNetwork()),
+  }),
+  agent_by_address: tool({
+    // requires [erc8004] in studio.toml
+    description: "Look up an ERC-8004 agent registration by wallet address.",
+    inputSchema: z.object({
+      address: z.string().describe("0x wallet address"),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.agentByAddress(address, network ?? defaultNetwork()),
+  }),
+
+  // --- ERC-8183 jobs (READ-ONLY status/list — writes live in signing.ts) ---
+  job_status: tool({
+    // requires [erc8183] in studio.toml
+    description: "Read-only ERC-8183 job summary (status, budget, deliverable URL).",
+    inputSchema: z.object({
+      job_id: z.number().int().describe("on-chain job id"),
+      network: networkArg,
+    }),
+    execute: async ({ job_id, network }) =>
+      cr.jobStatus(job_id, network ?? defaultNetwork()),
+  }),
+  job_list: tool({
+    // requires [erc8183] in studio.toml
+    description: "List recent ERC-8183 jobs (optionally only this agent's).",
+    inputSchema: z.object({
+      limit: z.number().int().optional(),
+      mine: z.boolean().optional().describe("only jobs assigned to this agent"),
+      network: networkArg,
+    }),
+    execute: async ({ limit, mine, network }) =>
+      cr.jobList({ limit, mine, network: network ?? defaultNetwork() }),
+  }),
+  // job_count: ...        // network-wide stat — usually noise
+
+  // --- Advanced / footguns (commented by default) ---
+  // contract_call_view: ...  // accepts any ABI — LLM-callable footgun
+  // block_info: ...
+  // wallet_list: ...          // multi-wallet management — dev concern
+  // wallet_address: ...       // alias of wallet_info
+};

package/recipes/runtimes/agentcore/recipe.toml

@@ -0,0 +1,97 @@
+[recipe]
+name = "runtimes/agentcore"
+description = "Runtime adapter for AWS Bedrock AgentCore. A project selects one or more public faces on one runtime and signer: A2A emits main.ts, MCP emits mcpMain.ts, and A2A+MCP emits the A2A-native dualMain.ts plus mcpMain.ts as its MCP server library. X402 is an optional sibling route on whichever entrypoint is selected. The chain tools (tools.ts) + model factory (model.ts) are shared by every mode."
+status = "a2a|mcp|both"
+
+# Emits the AgentCore serving layer for the chosen protocol:
+#   A2A — main.ts (express + @a2a-js/sdk on AGENT_PORT/9000 + /ping),
+#         executor.ts + sellerCore.ts (negotiate + notify_funded; signing stays
+#         fixed code in signing.ts, never an LLM tool), agentCard.ts.
+#   MCP — mcpMain.ts (stateful streamable-HTTP on 0.0.0.0:8000/mcp):
+#         negotiate (signed quote) + notify_funded (verify → work → submit,
+#         synchronously in-call) + read-only chain tools.
+#   BOTH — dualMain.ts uses A2A natively on :9000 and mounts the stateful MCP
+#          server from mcpMain.ts at /mcp for envelope-v1 tunneling.
+# signing.ts comes from the `agent` recipe; tools.ts + model.ts are shared
+# files here (always emitted, both protocols).
+
+# NOTE (EX-6): `bag init` writes agentcore.json itself (runtimeVersion =
+# "NODE_22", entrypoint = the built .js) — no native CLI is needed to
+# scaffold. The descriptor names the deploy (resource-naming continuity) and
+# drives `bag dev --container` (the one flow that still uses the npm
+# `@aws/agentcore` CLI); `bag deploy --provider aws` delegates all cloud execution to
+# the pinned @bnbagent/deploy-cli.
+
+# Deps split by face. The scaffolder reads `[dependencies].node` (shared) plus
+# one or both face groups, so single-face deploys stay minimal while the both
+# mode receives their union.
+[dependencies]
+node = [
+    # loadRuntimeSecrets() in every entrypoint (main.ts / mcpMain.ts) pulls the
+    # runtime secret bundle from AWS Secrets Manager when
+    # BNBAGENT_RUNTIME_SECRET_ID is set (default secretsmanager mode + platform).
+    "@aws-sdk/client-secrets-manager@^3.600.0",
+    "@bnbagent/studio-runtime",
+    "@bnbagent/sdk@0.5.0-alpha.1",
+    # The LLM work hook (generateText + tools) and the model factory.
+    "ai@^7.0.29",
+    # Tool input schemas (AI SDK tools + MCP registerTool).
+    "zod@^3.25.0",
+    # Both protocol entrypoints serve over express (the @a2a-js/sdk server
+    # integration and the MCP streamable-HTTP wiring are express-based).
+    "express@^5.1.0",
+]
+
+[dependencies.a2a]
+node = [
+    # The official A2A JS SDK hosts the A2A surface (agent card + JSON-RPC
+    # message/send). MUST be <1.0: 1.0.0-beta reshapes the server surface
+    # so 0.3.14 remains the spike-verified line (EX-3).
+    "@a2a-js/sdk@>=0.3.14 <1.0",
+]
+
+[dependencies.mcp]
+node = [
+    # The official MCP TS SDK hosts the MCP surface on /mcp; AgentCore wraps
+    # the protocol. No @a2a-js/sdk needed.
+    "@modelcontextprotocol/sdk@^1.29.0",
+]
+
+# Modes are selected from public faces plus the packaging axis:
+#   protocol — a2a: main.ts (@a2a-js/sdk express) + executor.ts + sellerCore.ts + agentCard.ts
+#              mcp: mcpMain.ts (streamable-HTTP /mcp; negotiate + notify_funded sync-delivery + read tools)
+#              both: dualMain.ts (A2A native) + mcpMain.ts library + A2A support files
+#   deploy   — codezip   (evm-local) — managed NODE_22 runtime, no Dockerfile.
+#              container (twak)      — custom image: the twak CLI must be
+#                                      installed globally (npm @trustwallet/cli)
+#                                      in a node:22 Dockerfile.
+# A project picks one or more faces on ONE runtime and signer. signing.ts lives
+# in the `agent` recipe (emitted in all modes). tools.ts + model.ts are shared
+# files (unlisted below → always emitted). sellerCore.ts is the
+# protocol-neutral seller core (negotiate + notify_funded + background
+# delivery); the A2A executor inherits it.
+#
+# Provider `bnb` is UNIFIED with AWS packaging:
+# it reuses the a2a-container / mcp-container modes (same entrypoint + fixed
+# port), and the platform gateway routes to the protocol's native surface.
+# There is no platform-specific recipe mode.
+[modes]
+default = "a2a-codezip"
+
+[modes.a2a-codezip]
+files = ["{{PKG}}/main.ts", "{{PKG}}/executor.ts", "{{PKG}}/sellerCore.ts", "{{PKG}}/agentCard.ts"]
+
+[modes.a2a-container]
+files = ["{{PKG}}/main.ts", "{{PKG}}/executor.ts", "{{PKG}}/sellerCore.ts", "{{PKG}}/agentCard.ts", "{{PKG}}/Dockerfile", "{{PKG}}/.dockerignore"]
+
+[modes.mcp-codezip]
+files = ["{{PKG}}/mcpMain.ts"]
+
+[modes.mcp-container]
+files = ["{{PKG}}/mcpMain.ts", "{{PKG}}/Dockerfile", "{{PKG}}/.dockerignore"]
+
+[modes.both-codezip]
+files = ["{{PKG}}/dualMain.ts", "{{PKG}}/mcpMain.ts", "{{PKG}}/executor.ts", "{{PKG}}/sellerCore.ts", "{{PKG}}/agentCard.ts"]
+
+[modes.both-container]
+files = ["{{PKG}}/dualMain.ts", "{{PKG}}/mcpMain.ts", "{{PKG}}/executor.ts", "{{PKG}}/sellerCore.ts", "{{PKG}}/agentCard.ts", "{{PKG}}/Dockerfile", "{{PKG}}/.dockerignore"]

package/recipes/runtimes/azure-foundry/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 Key Vault injection.)
+node_modules/
+dist/
+.env.local
+.studio/
+*.tsbuildinfo

package/recipes/runtimes/azure-foundry/code/{{PKG}}/Dockerfile.tmpl

@@ -0,0 +1,47 @@
+# Azure AI Foundry Hosted Agent image — SHIPPED BY `bag init`.
+# NOTE: deliberately NO `# syntax=docker/dockerfile:1` directive AND no BuildKit-only
+# instruction flags (`FROM --platform=…`, `RUN --mount=…`) — the file stays
+# classic-builder-compatible so any builder (a "classic" builder rejects
+# `FROM --platform=…` with "unable to understand line FROM --platform=…") can
+# process it. The target arch is pinned OUTSIDE the Dockerfile instead: the
+# pinned bnbagent-deploy (which `bag deploy --provider azure` delegates all cloud
+# execution to) builds this Dockerfile LOCALLY with Docker for linux/amd64
+# (`--platform` on the build command) and pushes the image to the
+# auto-provisioned Azure Container Registry; Foundry Agent Service pulls +
+# runs it, assigning a dedicated agent identity + endpoint.
+#
+# Why a custom image: azure-foundry deploys are container-only (the deploy
+# provider rejects Node zip), and a twak wallet additionally shells out to the
+# `twak` CLI (npm @trustwallet/cli) for every signing / on-chain intent, so
+# the image must carry it globally.
+FROM docker.io/library/node:22-slim
+
+# The pinned twak CLI + pnpm.
+#
+# ARCH WARNING: `npm install` MUST run with this image's own node (as below).
+# Installing on the host (or any other arch) and COPYing node_modules in
+# breaks at runtime: twak's `@napi-rs/keyring` native binding is selected at
+# install time per-arch (known npm optional-deps bug) — a cross-arch-installed
+# tree crashes at runtime. Multi-arch images must install per-arch too.
+RUN npm install -g @trustwallet/cli@{{TWAK_CLI_VERSION}} pnpm@{{PNPM_VERSION}} \
+ && npm cache clean --force
+
+WORKDIR /app
+# Install deps first (layer cache), then build. The lockfile is copied when
+# present; a project without one falls back to a plain install. (No BuildKit
+# cache mounts here — see the classic-builder note above.)
+COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml ./
+COPY vendor ./vendor
+RUN pnpm install
+
+COPY . .
+RUN pnpm build
+
+# Runtime deps only in the final tree (drops typescript etc.).
+RUN pnpm prune --prod
+
+# {{CONTAINER_PORT}} / {{ENTRYPOINT}} are rendered by `bag init` from the
+# provider contract (Foundry uses 8088 + dist/foundryMain.js).
+ENV AGENT_PORT={{CONTAINER_PORT}}
+EXPOSE {{CONTAINER_PORT}}
+CMD ["node", "{{ENTRYPOINT}}"]

package/recipes/runtimes/azure-foundry/code/{{PKG}}/agentCard.ts.tmpl

@@ -0,0 +1,131 @@
+/**
+ * A2A AgentCard — the seller agent's outward, discoverable identity.
+ *
+ * Built by `main.ts` and served at `/.well-known/agent-card.json`. On
+ * AgentCore, `$AGENTCORE_RUNTIME_URL` overrides `card.url` at boot;
+ * azure-foundry/local runs keep the client-routable local placeholder.
+ *
+ * The card advertises exactly two skills — `negotiate` and `notify_funded` —
+ * and the OAuth2 (Cognito) security scheme buyers must satisfy when deployed
+ * behind AgentCore: A2A endpoints require an inbound OAuth2 bearer (there is
+ * no anonymous mode).
+ * The token URL + scope come from the Cognito user pool
+ * `bag deploy provision-cognito` creates (env `OAUTH_TOKEN_URL` /
+ * `OAUTH_SCOPE`, injected at deploy); the runtime's inbound JWT authorizer
+ * validates the same pool. Locally (no Cognito env) the card omits the scheme
+ * so `bag dev` is reachable without a token.
+ *
+ * You own this file — edit the skill descriptions / card metadata for your
+ * seller.
+ */
+
+import type { AgentCard, AgentSkill, SecurityScheme } from "@a2a-js/sdk";
+import { loadStudioToml } from "@bnbagent/studio-runtime/config";
+
+const NEGOTIATE: AgentSkill = {
+  id: "negotiate",
+  name: "Negotiate an ERC-8183 job",
+  description:
+    'Send a data part {"skill": "negotiate", "task_description": "...", ' +
+    '"terms": {"deliverables": "...", "quality_standards": "..."}} (both ' +
+    "terms keys are REQUIRED) and receive a " +
+    "wallet-signed price quote (price, currency, negotiation_hash, provider_sig). " +
+    "Anchor the returned envelope on-chain via createJob + fund, then send the " +
+    "`notify_funded` skill with the job_id to request delivery.",
+  tags: ["erc8183", "negotiation", "bnb-chain"],
+  inputModes: ["application/json"],
+  outputModes: ["application/json"],
+};
+
+const NOTIFY_FUNDED: AgentSkill = {
+  id: "notify_funded",
+  name: "Notify the seller a job is funded (request delivery)",
+  description:
+    'After you fund the job on-chain, send {"skill": "notify_funded", ' +
+    '"job_id": <int>} to tell the seller "I funded job X — please deliver". ' +
+    "The seller verifies the funded job carries its signed quote and replies " +
+    'AT ONCE with {"status": "accepted"|"rejected", "job_id"}; delivery then ' +
+    "runs in the background (work takes time). Do NOT wait on this call for " +
+    "the result — read the deliverable back from the CHAIN once the job " +
+    "reaches SUBMITTED (the `submit` tx carries the deliverable_url; " +
+    "ERC-8183 `get_deliverable_url`). The agent serves no job-query endpoint.",
+  tags: ["erc8183", "delivery", "bnb-chain"],
+  inputModes: ["application/json"],
+  outputModes: ["application/json"],
+};
+
+/** Card name from studio.toml `[project].name` (best-effort). */
+function agentName(): string {
+  let name = "";
+  try {
+    const cfg = loadStudioToml();
+    name = String(
+      ((cfg.project ?? {}) as Record<string, unknown>).name ?? "",
+    );
+  } catch {
+    // a card label must never break boot
+  }
+  return name || "bnbagent-seller";
+}
+
+/**
+ * OAuth2 (Cognito client-credentials) scheme from env, or null locally.
+ *
+ * `bag deploy provision-cognito` emits a Cognito user pool + app client and
+ * injects `OAUTH_TOKEN_URL` + `OAUTH_SCOPE`; the AgentCore runtime's inbound
+ * JWT authorizer is wired to the same pool. Absent (local `bag dev`) →
+ * return null so the card advertises no auth requirement.
+ */
+function oauth2Scheme(): SecurityScheme | null {
+  const tokenUrl = process.env.OAUTH_TOKEN_URL;
+  const scope = process.env.OAUTH_SCOPE;
+  if (!tokenUrl || !scope) {
+    return null;
+  }
+  return {
+    type: "oauth2",
+    flows: {
+      clientCredentials: {
+        tokenUrl,
+        scopes: { [scope]: "Invoke the seller agent" },
+      },
+    },
+  };
+}
+
+/** Build the A2A AgentCard advertising the two seller skills (+ OAuth2 if set). */
+export function buildAgentCard(): AgentCard {
+  const name = agentName();
+  const extra: Partial<AgentCard> = {};
+  const scheme = oauth2Scheme();
+  if (scheme !== null) {
+    const scope = process.env.OAUTH_SCOPE as string;
+    extra.securitySchemes = { oauth2: scheme };
+    extra.security = [{ oauth2: [scope] }];
+  }
+  return {
+    name,
+    description: `ERC-8183 seller agent (${name}) — negotiate + notify_funded over A2A.`,
+    // $AGENTCORE_RUNTIME_URL wins when deployed behind AgentCore.
+    // Local-dev fallback: a client-routable localhost URL (not the 0.0.0.0
+    // bind address). Host via AGENT_HOST (default localhost); port via the
+    // same PORT → AGENT_PORT → 9000 resolution main.ts serves on.
+    url:
+      process.env.AGENTCORE_RUNTIME_URL ??
+      `http://${process.env.AGENT_HOST ?? "localhost"}:${process.env.PORT || process.env.AGENT_PORT || "9000"}/`,
+    version: "1.0.0",
+    protocolVersion: "0.3.0",
+    preferredTransport: "JSONRPC",
+    // Non-streaming: negotiate / notify_funded are request/response
+    // (message/send). Do NOT flip this on to satisfy the AgentCore
+    // inspector's chat box — that box can't drive a seller agent (it can
+    // only send plain text, never the {"skill": ...} DataPart these skills
+    // require, and its streaming view expects Task events). Test locally
+    // with curl / an A2A client sending a DataPart (see the operating skill).
+    capabilities: { streaming: false },
+    defaultInputModes: ["application/json"],
+    defaultOutputModes: ["application/json"],
+    skills: [NEGOTIATE, NOTIFY_FUNDED],
+    ...extra,
+  };
+}