@bnbagent/studio-cli 0.0.6-alpha.1

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

@@ -0,0 +1,147 @@
+/**
+ * A2A executor — the seller agent's outward A2A surface (two fixed-code
+ * skills).
+ *
+ * The agent serves A2A directly (an `@a2a-js/sdk` express app on the
+ * AgentCore A2A runtime contract). This module is ONLY the a2a wire:
+ * {@link SellerAgentExecutor} inherits all of the seller logic +
+ * background-delivery machinery from `sellerCore.ts` `SellerCore` (which
+ * imports nothing from `@a2a-js/sdk`) and adds the a2a-specific
+ * {@link SellerAgentExecutor.execute} / {@link SellerAgentExecutor.cancelTask}
+ * entrypoints plus the request/response wire helpers. `execute` reads the
+ * inbound message's data part and dispatches on its `skill`:
+ *
+ *     negotiate     → `SellerCore.negotiate` (rule-based price clamp + EIP-191 sign)
+ *     notify_funded → `SellerCore.notifyFunded` (fast on-chain gate) → ACK at
+ *                     once, then in the BACKGROUND: LLM work → `signing.submitResult`
+ *
+ * `notify_funded` is the buyer's "I funded job X — please deliver"
+ * notification. Because the work takes time, the executor does NOT block the
+ * caller: the core verifies the funded job synchronously (a couple of
+ * eth_calls) to ACK accepted/rejected, then runs the slow LLM work + on-chain
+ * `submit` in a background task and replies immediately. The buyer reads the
+ * deliverable back from the CHAIN (SUBMITTED / `getDeliverableUrl`) — the
+ * chain is the source of truth. While any background delivery is in flight
+ * `isBusy` (from `SellerCore`) reports busy, which `main.ts` feeds to
+ * AgentCore's `/ping` as `HEALTHY_BUSY` so the scale-to-zero runtime stays
+ * warm until the work lands (within the session max-lifetime).
+ *
+ * ALL signing is FIXED code in `signing.ts` — NEVER an LLM-callable tool
+ * (money is never in the LLM; the LLM only produces the work text, via the
+ * `runWork` hook). See `sellerCore.ts` for the negotiate / notifyFunded /
+ * sweep logic.
+ *
+ * You own this file — specialise the work hook / dispatch in `sellerCore.ts`,
+ * but keep signing OUT of the LLM tool list.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { DataPart, Message } from "@a2a-js/sdk";
+import {
+  A2AError,
+  type AgentExecutor,
+  type ExecutionEventBus,
+  type RequestContext,
+} from "@a2a-js/sdk/server";
+import { SellerCore } from "./sellerCore.js";
+
+const log = {
+  error: (msg: string, e?: unknown) =>
+    console.error(`[seller-agent.a2a] ERROR ${msg}`, e ?? ""),
+};
+
+/**
+ * ERC-8183 seller A2A executor: the a2a wire over `SellerCore`.
+ *
+ * All seller logic (negotiate, notifyFunded, background delivery, `isBusy`,
+ * the constructor bookkeeping, the `runWork` hook) lives in
+ * `sellerCore.ts` `SellerCore`; this class adds only the A2A entrypoints and
+ * request/response wire helpers.
+ *
+ * The agent exposes ONLY the two paid, structured skills — there is no
+ * free-form chat skill. A plain text message (no `{"skill": ...}` DataPart)
+ * is rejected: negotiate / notify_funded always need a structured DataPart,
+ * so prose never triggers an LLM call or a paid action.
+ */
+export class SellerAgentExecutor extends SellerCore implements AgentExecutor {
+  // ── A2A entrypoints ───────────────────────────────────────────────────────
+  execute = async (
+    context: RequestContext,
+    eventBus: ExecutionEventBus,
+  ): Promise<void> => {
+    const data = inbound(context);
+    const skill = data.skill;
+    let result: Record<string, unknown>;
+    try {
+      if (skill === "negotiate") {
+        result = await this.negotiate(data);
+      } else if (skill === "notify_funded") {
+        result = await this.notifyFunded(data);
+      } else {
+        // Includes a plain text message (no DataPart → skill is undefined):
+        // the seller has no free-form skill, so prose is rejected here.
+        result = {
+          error: `unknown skill: ${JSON.stringify(skill)}`,
+          skills: this.skills(),
+        };
+        if (skill === undefined) {
+          // Most common cause: the caller put the JSON envelope in a
+          // "text" part. Structured skill calls must ride in a DataPart.
+          result.hint =
+            'send the skill envelope as an A2A data part: parts:[{"kind":"data","data":{"skill":"negotiate",...}}]';
+        }
+      }
+    } catch (e) {
+      // A genuine internal fault is surfaced as a JSON-RPC error, NOT masked
+      // as a successful result. Throwing `A2AError.internalError` is caught
+      // by @a2a-js/sdk's request handler and serialized to a proper -32603
+      // carrying the request id. CLASSIFIED business outcomes are
+      // returned as a result above (peer of the MCP runtime: faults →
+      // isError, business outcomes → result).
+      log.error(`skill ${JSON.stringify(skill)} failed`, e);
+      const name = e instanceof Error ? e.constructor.name : "Error";
+      const msg = e instanceof Error ? e.message : String(e);
+      throw A2AError.internalError(`${name}: ${msg}`);
+    }
+    reply(eventBus, context, result);
+  };
+
+  cancelTask = async (
+    _taskId: string,
+    _eventBus: ExecutionEventBus,
+  ): Promise<void> => {
+    // negotiate is synchronous; notify_funded acks then delivers on-chain in
+    // the background — once submitted it is anchored on-chain and cannot be
+    // cancelled via A2A. Nothing to cancel here. (@a2a-js/sdk hands cancel
+    // only a taskId — no message to reply to — so this surfaces as the
+    // standard JSON-RPC unsupported-operation error.)
+    throw A2AError.unsupportedOperation("cancel");
+  };
+}
+
+// ── wire helpers ──────────────────────────────────────────────────────────────
+
+function inbound(context: RequestContext): Record<string, unknown> {
+  const parts = context.userMessage?.parts ?? [];
+  const dataPart = parts.find((p): p is DataPart => p.kind === "data");
+  return dataPart?.data ?? {};
+}
+
+function reply(
+  eventBus: ExecutionEventBus,
+  context: RequestContext,
+  data: Record<string, unknown>,
+): void {
+  const message: Message = {
+    kind: "message",
+    role: "agent",
+    messageId: randomUUID(),
+    parts: [{ kind: "data", data }],
+    contextId: context.contextId,
+    taskId: context.taskId,
+  };
+  // publish + finished() — without finished() the event stream never closes
+  // and the caller hangs.
+  eventBus.publish(message);
+  eventBus.finished();
+}

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

@@ -0,0 +1,344 @@
+/**
+ * Single A2A seller agent entrypoint. Generated by `bag recipe code agent`.
+ *
+ * This is the VALUABLE agent AND the SOLE key-holder/signer. It serves its
+ * two ERC-8183 seller skills DIRECTLY over the A2A protocol on AWS Bedrock
+ * AgentCore (`--protocol A2A`): an `@a2a-js/sdk` express app exposes the
+ * agent card at `/.well-known/agent-card.json` + JSON-RPC `message/send` on
+ * `0.0.0.0:9000` (`AGENT_PORT` overrides locally), plus `GET /ping` for the
+ * AgentCore liveness contract. There is no separate forwarding service — the
+ * agent IS the seller (see executor.ts + agentCard.ts).
+ *
+ * A2A skills (executor.ts):
+ *
+ *     negotiate     → read the FIXED list price → CLAMP to [min,max] → EIP-191 SIGN
+ *                     the offer (no LLM, no tools) → return the signed offer (or reject)
+ *     notify_funded → re-verify the funded job on-chain (fast) → ACK accepted at once,
+ *                     then in the BACKGROUND: LLM work → manifest → storage →
+ *                     submitResult (SIGN + broadcast). The buyer polls the chain for
+ *                     the deliverable. Each notify also sweeps other FUNDED jobs
+ *                     (buyer-push fallback). While background work is in flight the
+ *                     `/ping` handler reports HEALTHY_BUSY so AgentCore keeps the
+ *                     scale-to-zero runtime warm until it lands.
+ *
+ * Buyers reach this endpoint with an OAuth2 (Cognito) bearer — AgentCore A2A
+ * mandates inbound auth (see agentCard.ts + `bag deploy provision-cognito`).
+ *
+ * ## Boundaries (do NOT cross — they are the whole point)
+ *
+ * - The agent does ALL deterministic SIGNING (quote-sign + submit + settle +
+ *   automatic Pieverse LLM-credit auto-renew). ALL signing is FIXED code in
+ *   `signing.ts` — NEVER an LLM-callable tool (money never in the LLM).
+ * - The price is a FIXED list price from studio.toml (clamped before
+ *   signing) — the LLM never prices; it only PRODUCES the work text in the
+ *   delivery step.
+ * - Chain access for the LLM is READ-ONLY tools only (`tools.ts`).
+ * - `settle` (claim payment after the dispute window) is operator-driven —
+ *   run `bag erc8183 settle <job_id>`; it is deliberately NOT an A2A skill.
+ */
+
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import {
+  GetSecretValueCommand,
+  SecretsManagerClient,
+} from "@aws-sdk/client-secrets-manager";
+import { DefaultRequestHandler, InMemoryTaskStore } from "@a2a-js/sdk/server";
+import {
+  agentCardHandler,
+  jsonRpcHandler,
+  UserBuilder,
+} from "@a2a-js/sdk/server/express";
+import {
+  loadStudioToml,
+  type TomlTable,
+} from "@bnbagent/studio-runtime/config";
+import {
+  ensureAltanaSessionLoaded,
+  ensureKeystoreMaterialized,
+  ensureTwakMaterialized,
+  getWallet,
+} from "@bnbagent/studio-runtime/wallet";
+import {
+  createEnvelopeMiddleware,
+  X402_SELL_PATH,
+  type X402HttpRequest,
+  type X402RunWork,
+  X402Seller,
+} from "@bnbagent/studio-runtime/x402";
+import { generateText, stepCountIs } from "ai";
+import express from "express";
+import { buildAgentCard } from "./agentCard.js";
+import { SellerAgentExecutor } from "./executor.js";
+import { buildModel } from "./model.js";
+import type { RunWork } from "./sellerCore.js";
+import { LLM_READ_TOOLS } from "./tools.js";
+
+const APP_NAME = "agent";
+
+/**
+ * Deliverable `generator` label: this seller's own name, read from
+ * studio.toml `[project].name` (minus the `-agent` suffix) so each delivered
+ * manifest is self-identifying. Best-effort — falls back to `APP_NAME` if
+ * the config can't be read.
+ */
+function generatorTag(): string {
+  let name = "";
+  try {
+    const cfg = loadStudioToml();
+    name = String(((cfg.project ?? {}) as Record<string, unknown>).name ?? "");
+  } catch {
+    // a metadata label must never break delivery
+    return APP_NAME;
+  }
+  return name.endsWith("-agent")
+    ? name.slice(0, -"-agent".length)
+    : name || APP_NAME;
+}
+
+// ── Runtime secrets ───────────────────────────────────────────────────────────
+// Keep plaintext secrets OUT of agentcore.json. When BNBAGENT_RUNTIME_SECRET_ID
+// is set (deployed runtime), pull a JSON {ENV_NAME: value} blob from AWS
+// Secrets Manager into the process env BEFORE anything reads it (keystore
+// unlock, provider key, buildModel, Cognito OAuth env). No-op locally, where
+// .env.local already populated the environment. In a deployed runtime the
+// managed secret bundle is authoritative and replaces any stale spec-level
+// value left by an earlier runtime revision.
+async function loadRuntimeSecrets(): Promise<void> {
+  const secretId = process.env.BNBAGENT_RUNTIME_SECRET_ID;
+  if (!secretId) {
+    return;
+  }
+  const resp = await new SecretsManagerClient({}).send(
+    new GetSecretValueCommand({ SecretId: secretId }),
+  );
+  const bundle = JSON.parse(resp.SecretString ?? "{}") as Record<
+    string,
+    unknown
+  >;
+  for (const [key, value] of Object.entries(bundle)) {
+    process.env[key] = String(value);
+  }
+  const pieverseKey = process.env.PIEVERSE_LLM_API_KEY;
+  if (pieverseKey) {
+    const fingerprint = createHash("sha256")
+      .update(pieverseKey, "utf-8")
+      .digest("hex")
+      .slice(0, 12);
+    console.info(
+      `[runtime-secrets] PIEVERSE_LLM_API_KEY source=secretsmanager sha256=${fingerprint}…`,
+    );
+  }
+}
+
+/** studio.toml `[network].default` (best-effort; used by the funded sweep). */
+function defaultNetwork(): string {
+  try {
+    const cfg = loadStudioToml();
+    return String(
+      ((cfg.network ?? {}) as Record<string, unknown>).default ?? "bsc-testnet",
+    );
+  } catch {
+    return "bsc-testnet";
+  }
+}
+
+// ── One-shot LLM helper (the executor's delivery work hook) ──────────────────
+// LLM credit auto-renew (Pieverse path): `buildModel()` (in model.ts) returns
+// a model wrapped with a middleware that auto-tops up the active Pieverse key
+// before each generate call when [llm.auto_renew] is enabled. That top-up is
+// the ONLY automatic signing path outside signing.ts — it is budget-gated and
+// is NOT an LLM tool. It rides transparently into the delivery step.
+//
+// The LLM runs ONLY in the delivery step (the value hook). `negotiate` is
+// rule-based and never touches the LLM. The read-only chain tools are
+// attached so the work can read on-chain context if it needs to — drop them
+// from `tools.ts` if your work doesn't read chain. Signing / settle are NEVER
+// tools — they are fixed code in signing.ts, triggered by the A2A skills,
+// never callable by the LLM. (The one deliberate exception: the x402-buyer
+// recipe's PAID fetch tools — see the `tools:` note below — the LLM picks the
+// URL, but who gets paid and the per-call/daily caps stay locked in
+// studio.toml.)
+export function buildRunWork(): RunWork {
+  // The model is resolved LAZILY on first delivery, not at boot: a seller
+  // with no provider key yet must still serve negotiate (which never calls
+  // the LLM) — missing-key errors surface at notify_funded delivery time.
+  let model: ReturnType<typeof buildModel> | undefined;
+  return async (prompt, { abortSignal }) => {
+    model ??= buildModel(); // managed model with the auto-renew hook (delivery only)
+    const result = await generateText({
+      model,
+      system:
+        "You are a seller agent. You do the actual work once a job is funded. " +
+        "Be concrete and concise. Use the read-only chain tools when on-chain " +
+        "context helps. If a paid-data tool such as `buy_with_x402` is available " +
+        "to you, USE IT to fetch the data a task needs — those merchants (e.g. " +
+        "CoinMarketCap) charge via on-chain wallet payment, NOT an API key; never " +
+        "reply that you cannot complete the task for lack of an API key.",
+      prompt,
+      // LLM_READ_TOOLS = read-only chain tools (wallet, balances,
+      // ERC-8004/8183 queries). Edit `tools.ts` to add/remove. These are
+      // READ-ONLY — the agent never signs via a tool; all signing is in
+      // signing.ts (fixed code).
+      // To let the agent BUY paid data at work time (e.g. CMC market data
+      // after `bag x402 trust cmc` + `bag recipe code x402-buyer`), spread
+      // the emitted tool set — payee + per-call/daily caps stay locked in
+      // studio.toml:
+      //   import { X402_BUYER_TOOLS } from "./x402Buyer.js";
+      //   tools: { ...LLM_READ_TOOLS, ...X402_BUYER_TOOLS },
+      tools: LLM_READ_TOOLS,
+      stopWhen: stepCountIs(8), // bounded tool-call loop, then final text
+      abortSignal,
+    });
+    return result.text.trim();
+  };
+}
+
+function hasErc8183Rail(cfg: TomlTable): boolean {
+  const payments = asTable(cfg.payments);
+  return asTable(payments?.erc8183) !== null;
+}
+
+function asTable(value: unknown): TomlTable | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as TomlTable)
+    : null;
+}
+
+function flatHeaders(
+  headers: Record<string, string | string[] | undefined>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (typeof value === "string") out[name] = value;
+    else if (value !== undefined) out[name] = value[0] ?? "";
+  }
+  return out;
+}
+
+function flatQuery(query: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(query)) {
+    if (typeof value === "string") out[name] = value;
+  }
+  return out;
+}
+
+function x402Work(runWork: RunWork): X402RunWork {
+  return ({ prompt }) => runWork(prompt, { sessionId: "x402" });
+}
+
+// ── serving ───────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  await loadRuntimeSecrets();
+
+  // Wallet material is NEVER bundled into the deploy artifact. `bag deploy`
+  // injects it via Secrets Manager and these calls (run once at cold start,
+  // before any signing) materialize it on disk. Each is a no-op for the
+  // other wallet kind and locally, where the wallet already lives on disk:
+  //  - evm-local: WALLET_KEYSTORE_JSON → keystore file (unlocked with WALLET_PASSWORD)
+  //  - twak:      TWAK_WALLET_JSON / TWAK_CREDENTIALS_JSON → $TMPDIR/twak-home/.twak
+  //               (exported as TWAK_HOME_DIR; twak reads TWAK_WALLET_PASSWORD itself)
+  ensureKeystoreMaterialized();
+  ensureTwakMaterialized();
+  await ensureAltanaSessionLoaded();
+
+  const cfg = loadStudioToml();
+  const rails = { erc8183: hasErc8183Rail(cfg) };
+  const host = process.env.AGENT_BIND_HOST || "0.0.0.0";
+  const port = Number(process.env.AGENT_PORT || "9000");
+  const runWork = buildRunWork();
+
+  // The executor backs the seller skills with signing.ts fixed code (NEVER an
+  // LLM tool). The express app hosts the agent card + JSON-RPC message/send
+  // on 0.0.0.0:9000 and GET /ping for AgentCore's liveness probe.
+  const executor = new SellerAgentExecutor({
+    runWork,
+    generator: generatorTag(),
+    network: defaultNetwork(),
+    commerceSkills: rails.erc8183,
+  });
+  const agentCard = buildAgentCard({ commerceSkills: rails.erc8183 });
+  const seller = await X402Seller.create({
+    cfg,
+    runWork: x402Work(runWork),
+    walletAddress: getWallet().address,
+    resourceUrl: `${
+      process.env.AGENTCORE_RUNTIME_URL ?? `http://localhost:${port}`
+    }${X402_SELL_PATH}`,
+  });
+
+  const handler = new DefaultRequestHandler(
+    agentCard,
+    new InMemoryTaskStore(),
+    executor,
+  );
+
+  const app = express();
+
+  // GET /ping status fed to AgentCore: HEALTHY_BUSY while a background
+  // delivery is in flight, else HEALTHY.
+  //
+  // notify_funded acks immediately and runs the slow work (LLM + on-chain
+  // submit) in the background. Reporting HEALTHY_BUSY tells AgentCore the
+  // runtime is still working, so the scale-to-zero runtime is NOT reaped on
+  // idle before delivery lands (bounded by the session max-lifetime; ≤8h).
+  app.get("/ping", (_req, res) => {
+    res.json({ status: executor.isBusy() ? "HEALTHY_BUSY" : "HEALTHY" });
+  });
+
+  if (seller.state !== "disabled") {
+    app.all(
+      X402_SELL_PATH,
+      express.text({ type: "*/*", limit: "1mb" }),
+      async (req, res) => {
+        const request: X402HttpRequest = {
+          method: req.method,
+          path: req.path,
+          query: flatQuery(req.query),
+          headers: flatHeaders(req.headers),
+          body:
+            typeof req.body === "string"
+              ? req.body
+              : JSON.stringify(req.body ?? ""),
+        };
+        const out = await seller.handle(request);
+        res.status(out.status).set(out.headers).send(out.body);
+      },
+    );
+  }
+
+  app.use(express.json({ limit: "8mb" }));
+  app.use(createEnvelopeMiddleware({ port }));
+
+  app.use(
+    "/.well-known/agent-card.json",
+    agentCardHandler({ agentCardProvider: handler }),
+  );
+  app.use(
+    jsonRpcHandler({
+      requestHandler: handler,
+      userBuilder: UserBuilder.noAuthentication,
+    }),
+  );
+
+  // AgentCore's A2A contract is 0.0.0.0:9000. Do not honor the HTTP
+  // protocol's $PORT=8080 convention here; AGENT_PORT is the local-dev /
+  // rendered-container override.
+  app.listen(port, host, () => {
+    console.log(`[seller-agent] A2A serving on ${host}:${port}`);
+  });
+}
+
+// Run only as an entrypoint (`node main.js` / the AgentCore runtime), never
+// on import — tests import the builders above without starting a server.
+const isMain =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  main().catch((e) => {
+    console.error("[seller-agent] fatal:", e);
+    process.exit(1);
+  });
+}