@bnbagent/studio-cli 0.0.6-alpha.1

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

@@ -0,0 +1,504 @@
+/**
+ * A2A executor — the seller agent's outward surface (two fixed-code skills).
+ *
+ * The agent serves A2A directly through the runtime's A2A entrypoint. For
+ * azure-foundry this is the cloud-neutral `@a2a-js/sdk` express app;
+ * AgentCore wraps the same protocol on its own runtime contract.
+ * {@link SellerAgentExecutor.execute} reads the inbound message's data part
+ * and dispatches on its `skill`:
+ *
+ *     negotiate     → `signing.signQuote` (rule-based price clamp + EIP-191 sign)
+ *     notify_funded → `signing.verifySignedJob` (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: it 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
+ * {@link SellerAgentExecutor.isBusy} reports busy; AgentCore's entrypoint
+ * feeds that to `/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). On each notification the executor also opportunistically
+ * sweeps OTHER funded jobs assigned to this provider — the buyer-push
+ * fallback for jobs whose buyer funded on-chain but never sent
+ * `notify_funded` (deduped against in-flight jobs). Negotiate stays
+ * sweep-free so quotes are fast. A periodic poller — which also covers the
+ * scale-to-zero cold window when no one is invoking — is the v2 robust path.
+ *
+ * You own this file — specialise the work hook / dispatch, 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 { ERC8183JobOps } from "@bnbagent/sdk/erc8183";
+import { SubmitPermanentlyUnsupportedError } from "@bnbagent/studio-runtime/erc8183";
+import { getWallet } from "@bnbagent/studio-runtime/wallet";
+import * as defaultSigning from "./signing.js";
+
+const log = {
+  info: (msg: string) => console.log(`[seller-agent.a2a] ${msg}`),
+  warn: (msg: string) => console.warn(`[seller-agent.a2a] WARNING ${msg}`),
+  error: (msg: string, e?: unknown) =>
+    console.error(`[seller-agent.a2a] ERROR ${msg}`, e ?? ""),
+};
+
+/**
+ * The LLM work hook: produce the deliverable text for a prompt. Built in
+ * `main.ts` / `foundryMain.ts`; called ONLY inside the background delivery.
+ */
+export type RunWork = (
+  prompt: string,
+  opts: { sessionId: string; abortSignal?: AbortSignal },
+) => Promise<string>;
+
+/** The `signing.ts` surface the executor drives (injectable for tests). */
+export interface SigningApi {
+  listPrice(): bigint;
+  clampPrice(proposedWei: bigint): bigint;
+  signQuote(
+    request: Record<string, unknown>,
+    clampedPriceWei: bigint,
+  ): Promise<Record<string, unknown>>;
+  verifySignedJob(
+    jobId: number,
+  ): Promise<{ ok: boolean; reason: string; permanent: boolean }>;
+  jobSpec(
+    jobId: number,
+  ): Promise<{ task: string; terms: Record<string, unknown> } | null>;
+  submitResult(
+    jobId: number,
+    responseContent: string,
+    metadata?: Record<string, unknown> | null,
+  ): Promise<{ submitTx: string; deliverableUrl: string | null }>;
+}
+
+/** Pending-job scanner used by the sweep (injectable for tests). */
+export type PendingJobsFetcher = (
+  network: string,
+) => Promise<Record<string, unknown>>;
+
+const defaultPendingJobs: PendingJobsFetcher = async (network) => {
+  const ops = await ERC8183JobOps.create({
+    walletProvider: getWallet(),
+    network,
+  });
+  return (await ops.getPendingJobs()) as Record<string, unknown>;
+};
+
+export interface SellerAgentExecutorOpts {
+  runWork: RunWork;
+  generator: string;
+  network?: string | null;
+  /** Test seam: replace the signing module (default: `./signing.js`). */
+  signing?: SigningApi;
+  /** Test seam: replace the sweep's pending-job scan. */
+  pendingJobs?: PendingJobsFetcher;
+}
+
+/**
+ * ERC-8183 seller A2A executor: negotiate + notify_funded, backed by
+ * signing.ts.
+ *
+ * `runWork(prompt, { sessionId })` is the LLM work hook (built in `main.ts` /
+ * `foundryMain.ts`); it is called inside the background delivery
+ * (`notify_funded` → `doWorkAndSubmit`) to produce the deliverable text.
+ *
+ * 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 implements AgentExecutor {
+  private readonly runWork: RunWork;
+  private readonly generator: string;
+  private readonly network: string;
+  private readonly signing: SigningApi;
+  private readonly pendingJobs: PendingJobsFetcher;
+  // Background delivery bookkeeping (see notifyFunded / isBusy):
+  //  tasks    — live background promises (busy-status source).
+  //  inflight — job ids in flight OR already terminally handled this
+  //             process (notify/sweep dedup; retained on success so a
+  //             slower sweep never re-delivers a just-submitted job).
+  private readonly tasks = new Set<Promise<void>>();
+  private readonly inflight = new Set<number>();
+
+  constructor(opts: SellerAgentExecutorOpts) {
+    this.runWork = opts.runWork;
+    this.generator = opts.generator;
+    this.network = opts.network ?? "bsc-testnet";
+    this.signing = opts.signing ?? defaultSigning;
+    this.pendingJobs = opts.pendingJobs ?? defaultPendingJobs;
+  }
+
+  /**
+   * True while any background delivery is in flight.
+   *
+   * AgentCore's entrypoint feeds this to `/ping` (`HEALTHY_BUSY` when busy)
+   * so a scale-to-zero runtime is not reaped on idle while work runs. The
+   * azure/local uvicorn-style process stays up on its own, so there it is
+   * informational only.
+   */
+  isBusy(): boolean {
+    return this.tasks.size > 0;
+  }
+
+  /** Await every in-flight background task (test helper — not on the wire). */
+  async drain(): Promise<void> {
+    while (this.tasks.size > 0) {
+      await Promise.allSettled([...this.tasks]);
+    }
+  }
+
+  // ── protocol-agnostic skill dispatch ──────────────────────────────────────
+
+  /**
+   * Run the skill named by `data.skill` and return its result dict.
+   *
+   * The single source of truth for the seller's behaviour, independent of
+   * the wire protocol. The @a2a-js path ({@link execute}) reads a DataPart
+   * into `data` and writes the result back as a DataPart; the Azure Foundry
+   * Invocations host (`foundryMain.ts`) parses a text-encoded JSON envelope
+   * into `data` and serialises the result back to text. Both call HERE so
+   * negotiate / notify_funded behave identically on every runtime.
+   *
+   * Never throws: a skill failure (or an unknown / missing skill) is
+   * returned as an `{"error": ...}` dict so the caller can always reply (an
+   * escaped exception would hang the A2A caller with no response).
+   */
+  async dispatch(
+    data: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const skill = data.skill;
+    try {
+      if (skill === "negotiate") {
+        return await this.negotiate(data);
+      }
+      if (skill === "notify_funded") {
+        return await this.notifyFunded(data);
+      }
+      // Includes a plain text message (no skill envelope → skill is
+      // undefined): the seller has no free-form skill, so prose is rejected
+      // here.
+      return {
+        error: `unknown skill: ${JSON.stringify(skill)}`,
+        skills: this.skills(),
+      };
+    } catch (e) {
+      // a skill failure must still ACK the buyer
+      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);
+      return { error: `${name}: ${msg}`, skill };
+    }
+  }
+
+  // ── A2A entrypoints ─────────────────────────────────────────────────────
+
+  execute = async (
+    context: RequestContext,
+    eventBus: ExecutionEventBus,
+  ): Promise<void> => {
+    const result = await this.dispatch(inbound(context));
+    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.
+    throw A2AError.unsupportedOperation("cancel");
+  };
+
+  // ── skills ────────────────────────────────────────────────────────────────
+
+  /**
+   * Rule-based quote → SDK `NegotiationResult` envelope (no LLM).
+   *
+   * The price is the FIXED list price from studio.toml, clamped to
+   * `[min,max]` BEFORE signing — a misconfigured or hostile request can
+   * never sign out of bounds. The buyer parses this envelope verbatim and
+   * anchors it on-chain via `createJob` + `fund`.
+   */
+  private async negotiate(
+    data: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    let request = data.request;
+    if (request === null || typeof request !== "object" || Array.isArray(request)) {
+      const picked: Record<string, unknown> = {};
+      for (const k of ["task_description", "terms"]) {
+        if (k in data) picked[k] = data[k];
+      }
+      request = picked;
+    }
+    const clamped = this.signing.clampPrice(this.signing.listPrice());
+    return this.signing.signQuote(request as Record<string, unknown>, clamped);
+  }
+
+  /** The seller's two advertised skills. */
+  skills(): string[] {
+    return ["negotiate", "notify_funded"];
+  }
+
+  /**
+   * Buyer notification: "I funded job X — please deliver."
+   *
+   * Verify the funded job synchronously (a couple of eth_calls) to ACK
+   * accepted/rejected at once, then run the slow LLM work + on-chain
+   * `submit` in a BACKGROUND task and reply IMMEDIATELY. The buyer reads
+   * the deliverable back from the CHAIN (SUBMITTED / `getDeliverableUrl`) —
+   * the chain is the source of truth (see erc8183-buyer-push.md).
+   *
+   * An accepted notification also kicks a background sweep (deduped against
+   * in-flight jobs), so a buyer that funded but forgot to notify is still
+   * served while we're warm. A rejected / malformed notification spawns
+   * nothing.
+   */
+  private async notifyFunded(
+    data: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const raw = data.job_id;
+    if (raw === undefined || raw === null || String(raw) === "") {
+      this.spawn(() => this.sweep()); // bare notify → just scan stragglers
+      return {
+        status: "accepted",
+        note: "no job_id — scanning funded jobs in the background; poll the chain for results",
+      };
+    }
+    let jobId: number;
+    try {
+      jobId = parseJobId(raw);
+    } catch {
+      return { status: "rejected", error: `invalid job_id: ${JSON.stringify(raw)}` };
+    }
+    let verified = false;
+    try {
+      const v = await this.signing.verifySignedJob(jobId);
+      if (!v.ok && v.permanent) {
+        return { status: "rejected", job_id: jobId, reason: v.reason };
+      }
+      verified = v.ok;
+    } catch (e) {
+      // pre-verify is best-effort; the background delivery re-verifies
+      log.warn(
+        `pre-verify of job ${jobId} failed (${e instanceof Error ? e.message : e}); accepting, will re-verify in background`,
+      );
+    }
+    this.spawnJob(jobId, { verified });
+    this.spawn(() => this.sweep()); // straggler fallback alongside the named job
+    return {
+      status: "accepted",
+      job_id: jobId,
+      note: "delivery started; poll the chain (SUBMITTED / get_deliverable_url) for the result",
+    };
+  }
+
+  // ── background delivery ───────────────────────────────────────────────────
+
+  /** Run `work` as a tracked background task (keeps {@link isBusy} true). */
+  private spawn(work: () => Promise<void>): void {
+    const task = work().catch((e) => {
+      // a background task must never crash the process
+      log.error("background task failed", e);
+    });
+    this.tasks.add(task);
+    task.finally(() => this.tasks.delete(task));
+  }
+
+  /**
+   * Background-deliver `jobId` once, deduped against in-flight jobs.
+   *
+   * `inflight` is updated SYNCHRONOUSLY here (before scheduling) so a
+   * concurrent notify + sweep can never double-deliver the same job.
+   */
+  private spawnJob(jobId: number, opts: { verified: boolean }): void {
+    if (this.inflight.has(jobId)) return;
+    this.inflight.add(jobId);
+    this.spawn(() => this.runJob(jobId, opts));
+  }
+
+  /**
+   * Background runner: deliver one job, log the outcome, free the slot.
+   *
+   * `verified` jobs (pre-verified in `notifyFunded`) skip straight to the
+   * work; unverified ones (the sweep) run the full verify gate first.
+   */
+  private async runJob(
+    jobId: number,
+    { verified }: { verified: boolean },
+  ): Promise<void> {
+    let terminal = false;
+    try {
+      const result = verified
+        ? await this.doWorkAndSubmit(jobId)
+        : await this.fulfillJob(jobId);
+      log.info(`notify_funded job ${jobId} → ${JSON.stringify(result)}`);
+      // A terminal outcome (delivered, or a permanent skip) must STAY in
+      // `inflight`: keeping it lets the dedup gate in spawnJob reject a
+      // slower concurrent sweep that still sees this job as FUNDED, so the
+      // just-submitted job is never re-delivered. Clearing on success
+      // reopened that race — the sweep re-ran the work and then failed the
+      // on-chain FUNDED gate (Job status is SUBMITTED). Only transient
+      // failures fall through to delete so a later sweep can retry them.
+      terminal = Boolean(result.ok || result.skip);
+    } catch (e) {
+      // a background job must never crash the process
+      log.error(`background delivery of job ${jobId} failed`, e);
+    } finally {
+      if (!terminal) {
+        this.inflight.delete(jobId);
+      }
+    }
+  }
+
+  // ── internals ─────────────────────────────────────────────────────────────
+
+  /**
+   * Verify the signed deal on-chain, then deliver (the sweep's per-job
+   * worker).
+   *
+   * VERIFY before working: confirm the funded job carries the exact quote
+   * THIS agent signed (ecrecover + budget ≥ price). A permanent failure
+   * (not our signature, tampered terms, underfunded, expired) returns
+   * `skip: true`; a transient one returns `ok: false` to retry.
+   */
+  private async fulfillJob(jobId: number): Promise<Record<string, unknown>> {
+    const v = await this.signing.verifySignedJob(jobId);
+    if (!v.ok) {
+      return { ok: false, job_id: jobId, skip: v.permanent, reason: v.reason };
+    }
+    return this.doWorkAndSubmit(jobId);
+  }
+
+  /**
+   * LLM work → sign + submit. Assumes `jobId` is already verified.
+   *
+   * DEVELOPER HOOK: the LLM block produces the deliverable text — specialise
+   * it for your seller. `signing.submitResult` re-runs the SDK `verifyJob`
+   * (defense in depth) and THROWS on a failed submit, so an `ok: true`
+   * result always carries a landed tx hash.
+   */
+  private async doWorkAndSubmit(
+    jobId: number,
+  ): Promise<Record<string, unknown>> {
+    const spec = await this.signing.jobSpec(jobId);
+    const task =
+      spec !== null
+        ? JSON.stringify({ task: spec.task, terms: spec.terms })
+        : `job ${jobId}`;
+    const prompt =
+      "You accepted and were paid for the following job. Produce the " +
+      "deliverable now. Be complete and self-contained.\n\n" +
+      `JOB CONTEXT:\n${task}`;
+    const work = await this.runWork(prompt, { sessionId: String(jobId) });
+
+    let res: { submitTx: string; deliverableUrl: string | null };
+    try {
+      res = await this.signing.submitResult(jobId, work, {
+        job_id: jobId,
+        generator: this.generator,
+        built_with: "https://github.com/bnb-chain/bnbagent-studio",
+      });
+    } catch (e) {
+      if (
+        e instanceof SubmitPermanentlyUnsupportedError ||
+        (e instanceof Error && e.name === "SubmitPermanentlyUnsupportedError")
+      ) {
+        // Deterministic for this wallet kind: submit can NEVER succeed →
+        // permanent skip (a transient error would burn one LLM call / retry).
+        return { ok: false, job_id: jobId, skip: true, reason: e.message };
+      }
+      throw e;
+    }
+    return {
+      ok: true,
+      job_id: jobId,
+      tx_hash: res.submitTx,
+      deliverable_url: res.deliverableUrl,
+    };
+  }
+
+  /**
+   * Best-effort background fallback: deliver any FUNDED jobs for this
+   * provider.
+   *
+   * Catches jobs whose buyer funded on-chain but never sent `notify_funded`.
+   * Each job is handed to `spawnJob` (deduped against in-flight jobs, so a
+   * concurrent notify never double-delivers); `verifySignedJob` returns
+   * non-OK for an already-SUBMITTED job (idempotent, no state file). Errors
+   * here are logged and never surface to the caller.
+   */
+  private async sweep(): Promise<void> {
+    let pending: Record<string, unknown>;
+    try {
+      pending = await this.pendingJobs(this.network);
+    } catch (e) {
+      // the sweep is best-effort
+      log.warn(`funded-job sweep failed: ${e instanceof Error ? e.message : e}`);
+      return;
+    }
+    const jobs = Array.isArray(pending?.jobs) ? pending.jobs : [];
+    for (const job of jobs) {
+      const jid =
+        job !== null && typeof job === "object" && !Array.isArray(job)
+          ? (job as Record<string, unknown>).jobId
+          : undefined;
+      if (jid === undefined || jid === null) continue;
+      try {
+        this.spawnJob(parseJobId(jid), { verified: false });
+      } catch {
+        // unparseable id — skip
+      }
+    }
+  }
+}
+
+// ── 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();
+}
+
+/** Normalise an envelope `job_id` (`0x..` / decimal string / number) to int. */
+export function parseJobId(raw: unknown): number {
+  if (typeof raw === "number" && Number.isInteger(raw)) return raw;
+  if (typeof raw === "bigint") return Number(raw);
+  // BigInt() parses both `0x..` hex and decimal strings, and throws on junk.
+  return Number(BigInt(String(raw).trim()));
+}