@bnbagent/studio-cli 0.0.13-alpha.6 → 0.0.13-alpha.8

package/dist/{chunk-LEBIBQWN.js → chunk-NTDWVEW2.js}

@@ -9,6 +9,7 @@ import {
 
 // src/cli/_deploy/deployCli.ts
 import * as fs5 from "fs";
+import { createRequire } from "module";
 import * as os from "os";
 import * as path6 from "path";
 import {
@@ -415,10 +416,10 @@ function packageVersionOf(entry, packageName) {
 async function pack(buildRoot, outZip) {
   fs.rmSync(outZip, { force: true });
   const ZipArchive = await loadZipArchive();
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     const output = fs.createWriteStream(outZip);
     const archive = new ZipArchive({ zlib: { level: 9 } });
-    output.on("close", () => resolve());
+    output.on("close", () => resolve2());
     archive.on("error", (err) => reject(err));
     archive.pipe(output);
     for (const file of listFiles(buildRoot).sort()) {
@@ -571,6 +572,21 @@ function printErr(line) {
 `);
 }
 
+// src/cli/_deploy/commandOverride.ts
+function isVitestProcess(environment, argv) {
+  return environment === process.env && environment.VITEST === "true" && argv.some(
+    (arg) => /(?:^|[/\\])vitest(?:\.mjs|\.js)?$/u.test(arg) || /(?:^|[/\\])tinypool[/\\]dist[/\\]entry[/\\](?:process|worker)\.js$/u.test(
+      arg
+    )
+  );
+}
+function deployCommandOverrideAllowed(environment = process.env, argv = process.argv) {
+  if (isVitestProcess(environment, argv)) return true;
+  const ci = (environment.CI ?? "").trim().toLowerCase();
+  const inCi = ci !== "" && !["0", "false", "no"].includes(ci);
+  return !inCi && ["development", "test"].includes(environment.NODE_ENV ?? "");
+}
+
 // src/cli/preflight.ts
 var OK = "ok";
 var WARN = "warn";
@@ -615,29 +631,30 @@ function agentcoreFlavor(binPath) {
 async function checkBunx() {
   const override = (process.env.BNBAGENT_DEPLOY_COMMAND ?? "").trim();
   if (override) {
+    const allowed = deployCommandOverrideAllowed();
     return {
       name: "bnbagent-deploy",
-      ok: true,
-      level: OK,
-      detail: `command overridden via BNBAGENT_DEPLOY_COMMAND (${override})`,
-      fix: ""
+      ok: allowed,
+      level: allowed ? OK : WARN,
+      detail: allowed ? `local development/test command override (${override})` : "BNBAGENT_DEPLOY_COMMAND is disabled outside local development/tests and in CI",
+      fix: allowed ? "" : "unset BNBAGENT_DEPLOY_COMMAND"
     };
   }
-  const found = await whichBin("bunx");
+  const found = await whichBin("bun");
   if (found === null) {
     return {
       name: "bnbagent-deploy",
       ok: false,
       level: WARN,
-      detail: "bunx not found (deploys delegate to the pinned @bnbagent/deploy-cli via bunx)",
-      fix: "install Bun 1.3+ (https://bun.sh) or set BNBAGENT_DEPLOY_COMMAND"
+      detail: "bun not found (required by the declared @bnbagent/deploy-cli dependency)",
+      fix: "install Bun 1.3+ (https://bun.sh)"
     };
   }
   return {
     name: "bnbagent-deploy",
     ok: true,
     level: OK,
-    detail: `bunx on PATH (${found}); deploys delegate to the pinned @bnbagent/deploy-cli`,
+    detail: `bun on PATH (${found}); deploys use the declared @bnbagent/deploy-cli dependency`,
     fix: ""
   };
 }
@@ -791,8 +808,8 @@ function packageRoot() {
   }
 }
 function studioCliVersion() {
-  if ("0.0.13-alpha.6") {
-    return "0.0.13-alpha.6";
+  if ("0.0.13-alpha.8") {
+    return "0.0.13-alpha.8";
   }
   const file = path3.join(packageRoot(), "package.json");
   const pkg = JSON.parse(fs3.readFileSync(file, "utf-8"));
@@ -1035,7 +1052,7 @@ function x402DeploySummaryFromSnapshot(snapshot, runtime, destination, publicUrl
   const settlement = [
     "B402 settlement can add significant latency; buyer timeout must be at least 120 s.",
     "Settlement happens before work. If work later fails, the payment is retained and is not refunded automatically.",
-    "B402 classifies an asynchronous pending response or other ambiguous settlement outcome as unknown; reconcile it and do not replay the paid request."
+    "Compatibility note: @bnb-chain/b402@0.2.1 guards credential replays, but an asynchronous pending response or otherwise ambiguous settlement is outcome unknown; reconcile it and do not replay the paid request."
   ];
   if (protocol === "mpp") {
     settlement.push(
@@ -1073,6 +1090,21 @@ function isTable(value) {
 // src/cli/_deploy/deployCli.ts
 var DEPLOY_CLI_VERSION = "0.5.15";
 var DEPLOY_CLI_PACKAGE = `@bnbagent/deploy-cli@${DEPLOY_CLI_VERSION}`;
+var require2 = createRequire(import.meta.url);
+function resolveLocalDeployCli() {
+  try {
+    const manifest = require2.resolve("@bnbagent/deploy-cli/package.json");
+    const pkg = JSON.parse(fs5.readFileSync(manifest, "utf-8"));
+    if (pkg.version !== DEPLOY_CLI_VERSION) return null;
+    const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.["bnbagent-deploy"];
+    if (typeof bin !== "string") return null;
+    const entry = path6.resolve(path6.dirname(manifest), bin);
+    return fs5.statSync(entry).isFile() ? entry : null;
+  } catch {
+    return null;
+  }
+}
+var LOCAL_DEPLOY_CLI_ENTRY = resolveLocalDeployCli();
 var BNB_PLATFORM_API_URL = "https://bnbagent-api.bnbchain.world";
 var BNB_PLATFORM_API_URL_ENV = "BNBAGENT_API_URL";
 var LEGACY_BNB_PLATFORM_API_URL_ENV = "BAG_PLATFORM_API_BASE";
@@ -1135,8 +1167,16 @@ function bnbPlatformApiUrl(environment = process.env) {
 function deployCommand(environment = process.env) {
   const override = (environment.BNBAGENT_DEPLOY_COMMAND ?? "").trim();
   if (override) {
+    if (!deployCommandOverrideAllowed(environment)) {
+      throw new Error(
+        "BNBAGENT_DEPLOY_COMMAND is allowed only for local development/tests and is disabled in CI"
+      );
+    }
     return override.split(/\s+/u);
   }
+  if (LOCAL_DEPLOY_CLI_ENTRY !== null) {
+    return ["bun", LOCAL_DEPLOY_CLI_ENTRY];
+  }
   return ["bunx", "--bun", DEPLOY_CLI_PACKAGE];
 }
 function providerPassthrough(studio, table4) {
@@ -1351,11 +1391,11 @@ async function withDeployFiles(root, opts, fn) {
     fs5.rmSync(scratch, { recursive: true, force: true });
   }
 }
-var BUNX_HINT = "error: could not start bnbagent-deploy (bunx not found); install Bun 1.3+ or set BNBAGENT_DEPLOY_COMMAND.";
+var DEPLOY_CLI_HINT = "error: could not start the lockfile-pinned bnbagent-deploy; install Bun 1.3+ and reinstall @bnbagent/studio-cli.";
 async function ensureRunnable(environment = process.env) {
   const [bin] = deployCommand(environment);
   if (bin && await whichBin(bin) === null) {
-    printErr(BUNX_HINT);
+    printErr(DEPLOY_CLI_HINT);
     return false;
   }
   return true;
@@ -1365,8 +1405,8 @@ var BUNX_TREE_HINT = [
   `error: ${DEPLOY_CLI_PACKAGE} could not load its own dependencies \u2014 its `,
   "bunx install directory is incomplete. Remove it and retry:\n",
   '  rm -rf "${TMPDIR:-/tmp}"/bunx-*-@bnbagent\n',
-  "If it persists, clear Bun's package cache (`bun pm cache rm`), or point ",
-  "BNBAGENT_DEPLOY_COMMAND at a local checkout."
+  "If it persists, clear Bun's package cache (`bun pm cache rm`) and reinstall ",
+  "@bnbagent/studio-cli."
 ].join("");
 function bunxInstallDir(environment = process.env) {
   if (deployCommand(environment)[0] !== "bunx") {
@@ -1521,6 +1561,7 @@ export {
   x402SellerUsesB402,
   x402SellerIsFree,
   b402PaymentProtocol,
+  deployCommandOverrideAllowed,
   whichBin,
   agentcoreFlavor,
   checkBunx,
@@ -1542,6 +1583,7 @@ export {
   x402DeploySummaryFromSnapshot,
   DEPLOY_CLI_VERSION,
   DEPLOY_CLI_PACKAGE,
+  LOCAL_DEPLOY_CLI_ENTRY,
   BNB_PLATFORM_API_URL,
   BNB_PLATFORM_API_URL_ENV,
   LEGACY_BNB_PLATFORM_API_URL_ENV,

package/dist/{deployCli-H65YVV3V.js → deployCli-ZESBUWQB.js}

@@ -5,6 +5,7 @@ import {
   DEPLOY_CLI_PACKAGE,
   DEPLOY_CLI_VERSION,
   LEGACY_BNB_PLATFORM_API_URL_ENV,
+  LOCAL_DEPLOY_CLI_ENTRY,
   bnbEnv,
   bnbPlatformApiUrl,
   buildDeploySpec,
@@ -18,7 +19,7 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-LEBIBQWN.js";
+} from "./chunk-NTDWVEW2.js";
 import "./chunk-RO726HJG.js";
 export {
   BNB_PLATFORM_API_URL,
@@ -26,6 +27,7 @@ export {
   DEPLOY_CLI_PACKAGE,
   DEPLOY_CLI_VERSION,
   LEGACY_BNB_PLATFORM_API_URL_ENV,
+  LOCAL_DEPLOY_CLI_ENTRY,
   bnbEnv,
   bnbPlatformApiUrl,
   buildDeploySpec,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bnbagent/studio-cli",
-  "version": "0.0.13-alpha.6",
+  "version": "0.0.13-alpha.8",
   "description": "Skills-first toolkit and bag CLI for BNB Chain seller agents: ERC-8004 identity, ERC-8183 escrowed commerce, and x402 payments.",
   "keywords": [
     "bnb-chain",
@@ -42,7 +42,8 @@
     "bag": "./dist/bag.js"
   },
   "dependencies": {
-    "@bnbagent/sdk": "0.5.3",
+    "@bnbagent/deploy-cli": "0.5.15",
+    "@bnbagent/sdk": "0.5.5",
     "ai": "^7.0.29",
     "archiver": "^8.0.0",
     "commander": "^15.0.0",
@@ -54,7 +55,7 @@
     "tar": "^7.4.0",
     "viem": "^2.54.0",
     "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.13-alpha.6"
+    "@bnbagent/studio-runtime": "0.0.13-alpha.8"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",

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

@@ -229,8 +229,8 @@ export async function signQuote(
     estimatedCompletionSeconds: est,
   });
 
-  // NegotiationHandler signs non-fatally: if signMessage failed it returns an
-  // accepted result WITHOUT provider_sig. Never relay an unsigned "accepted".
+  // SDK 0.5.4 throws QuoteSigningError when signing fails. Keep this shape
+  // check as defense in depth for injected handlers and mixed deployments.
   if (result.accepted && (!result.negotiationHash || !result.providerSig)) {
     throw new Error(
       "quote accepted but provider_sig is missing (wallet sign failed); " +

package/recipes/agent/recipe.toml

@@ -11,7 +11,7 @@ node = [
     # 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.3",
+    "@bnbagent/sdk@0.5.5",
 ]
 
 [env]

package/recipes/mpp-buyer/recipe.toml

@@ -6,7 +6,7 @@ status = "v0.0.x"
 [dependencies]
 node = [
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.3",
+    "@bnbagent/sdk@0.5.5",
     "ai@^7.0.29",
     "zod@^3.25.0",
 ]

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

@@ -80,6 +80,7 @@ import { buildAgentCard } from "./agentCard.js";
 import { SellerAgentExecutor } from "./executor.js";
 import { buildMcpServer } from "./mcpMain.js";
 import { buildModel } from "./model.js";
+import { requestLimitContext } from "./requestLimits.js";
 import type { RunWork } from "./sellerCore.js";
 import { LLM_READ_TOOLS } from "./tools.js";
 
@@ -296,6 +297,7 @@ export async function buildDualApp(): Promise<{
   );
 
   const app = express();
+  app.use(requestLimitContext);
 
   // GET /ping status fed to AgentCore: HEALTHY_BUSY while a background
   // delivery is in flight, else HEALTHY.

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

@@ -43,6 +43,7 @@ import {
   type ExecutionEventBus,
   type RequestContext,
 } from "@a2a-js/sdk/server";
+import { isCommerceRateLimitError } from "./requestLimits.js";
 import { SellerCore } from "./sellerCore.js";
 
 const log = {
@@ -94,9 +95,10 @@ export class SellerAgentExecutor extends SellerCore implements AgentExecutor {
     } 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 };
+      if (isCommerceRateLimitError(e)) {
+        return { status: "retry", error: "seller rate limit exceeded", skill };
+      }
+      return { error: "seller operation failed; retry later", skill };
     }
   }
 
@@ -135,9 +137,15 @@ export class SellerAgentExecutor extends SellerCore implements AgentExecutor {
       // 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}`);
+      if (isCommerceRateLimitError(e)) {
+        result = {
+          status: "retry",
+          error: "seller rate limit exceeded",
+          skill,
+        };
+      } else {
+        throw A2AError.internalError("seller operation failed; retry later");
+      }
     }
     reply(eventBus, context, result);
   };

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

@@ -79,6 +79,11 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { generateText, stepCountIs } from "ai";
 import express from "express";
 import { z } from "zod";
+import {
+  isCommerceRateLimitError,
+  limitCommerceOperation,
+  requestLimitContext,
+} from "./requestLimits.js";
 import * as signing from "./signing.js";
 
 const APP_NAME = "agent";
@@ -88,6 +93,11 @@ const log = {
     console.error(`[seller-agent.mcp] ERROR ${msg}`, e ?? ""),
 };
 
+function protocolFailure(scope: string, error: unknown): never {
+  log.error(scope, error);
+  throw new Error("seller operation failed; retry later");
+}
+
 // ── 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
@@ -296,16 +306,24 @@ export function buildMcpServer(
       annotations: COMMERCE_ANNOTATIONS,
     },
     // Error contract (unified with the A2A executor): an unexpected fault
-    // here (wallet/signing failure) is left to PROPAGATE — the MCP SDK turns
-    // it into a tool result with `isError: true` (MCP's tool-execution-error
-    // channel), the peer of the A2A executor throwing
-    // `A2AError.internalError` → JSON-RPC -32603. Only CLASSIFIED business
-    // outcomes are returned as a normal result. So do NOT wrap this in a
-    // try/catch that masks a fault as a successful quote.
+    // becomes an MCP `isError` result with a generic public message; its full
+    // detail is logged server-side. Classified quota exhaustion is returned
+    // as a normal retry result and never as a fake quote.
     async ({ task_description, terms }) => {
-      const request = { task_description, terms: terms ?? {} };
-      const clamped = signing.clampPrice(signing.listPrice());
-      return toolResult(await signing.signQuote(request, clamped));
+      try {
+        await limitCommerceOperation("negotiate");
+        const request = { task_description, terms: terms ?? {} };
+        const clamped = signing.clampPrice(signing.listPrice());
+        return toolResult(await signing.signQuote(request, clamped));
+      } catch (e) {
+        if (isCommerceRateLimitError(e)) {
+          return toolResult({
+            status: "retry",
+            reason: "seller rate limit exceeded",
+          });
+        }
+        return protocolFailure("negotiate failed", e);
+      }
     },
     );
 
@@ -327,6 +345,17 @@ export function buildMcpServer(
       annotations: COMMERCE_ANNOTATIONS,
     },
     async ({ job_id }, extra) => {
+      try {
+        await limitCommerceOperation("notify_funded");
+      } catch (e) {
+        if (isCommerceRateLimitError(e)) {
+          return toolResult({
+            status: "retry",
+            reason: "seller rate limit exceeded",
+          });
+        }
+        return protocolFailure("notify_funded limiter failed", e);
+      }
       let jid: number;
       try {
         jid = parseJobId(job_id);
@@ -348,40 +377,43 @@ export function buildMcpServer(
       } catch (e) {
         // a failed verify is transient; tell the buyer to retry
         log.error(`verify of job ${jid} failed`, e);
-        const name = e instanceof Error ? e.constructor.name : "Error";
-        const msg = e instanceof Error ? e.message : String(e);
         return toolResult({
           status: "retry",
           job_id: jid,
-          reason: `${name}: ${msg}`,
+          reason: "chain verification temporarily unavailable",
         });
       }
       if (!verdict.ok) {
         return toolResult({
           status: verdict.permanent ? "rejected" : "retry",
           job_id: jid,
-          reason: verdict.reason,
+          reason: verdict.permanent
+            ? verdict.reason
+            : "chain verification temporarily unavailable",
         });
       }
 
       // 2/4 — produce the deliverable (THE ONLY LLM CALL; specialise the
       // prompt here)
       await reportProgress(extra, 2, 4);
-      const spec = await signing.jobSpec(jid);
-      const task =
-        spec !== null
-          ? JSON.stringify({ task: spec.task, terms: spec.terms })
-          : `job ${jid}`;
-      const prompt =
-        "You accepted and were paid for the following job. Produce the deliverable " +
-        `now. Be complete and self-contained.\n\nJOB CONTEXT:\n${task}`;
-      // An unexpected fault below (LLM unavailable, RPC/submit hiccup) is
-      // left to PROPAGATE — the MCP SDK returns it as an isError tool result
-      // (the peer of the A2A executor's internalError/-32603). Only the
-      // deterministic, classified outcome SubmitPermanentlyUnsupportedError
-      // is a "rejected" business result.
-      const work = await runLlm(prompt);
-
+      let work: string;
+      try {
+        const spec = await signing.jobSpec(jid);
+        const task =
+          spec !== null
+            ? JSON.stringify({ task: spec.task, terms: spec.terms })
+            : `job ${jid}`;
+        const prompt =
+          "You accepted and were paid for the following job. Produce the deliverable " +
+          `now. Be complete and self-contained.\n\nJOB CONTEXT:\n${task}`;
+        work = await runLlm(prompt);
+      } catch (e) {
+        return protocolFailure(`delivery preparation for job ${jid} failed`, e);
+      }
+      // Unexpected LLM/RPC faults are logged in full, then surfaced through
+      // MCP's isError channel with a generic public message. Only the
+      // deterministic SubmitPermanentlyUnsupportedError is a classified
+      // "rejected" business result.
       // 3/4 — sign + broadcast the on-chain submit (re-verifies FUNDED inside)
       await reportProgress(extra, 3, 4);
       let res: { submitTx: string; deliverableUrl: string | null };
@@ -401,10 +433,10 @@ export function buildMcpServer(
             status: "rejected",
             job_id: jid,
             skip: true,
-            reason: e.message,
+            reason: "seller wallet does not support result submission",
           });
         }
-        throw e;
+        return protocolFailure(`submit of job ${jid} failed`, e);
       }
 
       // 4/4 — done
@@ -606,6 +638,7 @@ async function main(): Promise<void> {
   });
 
   const app = express();
+  app.use(requestLimitContext);
 
   if (seller.state !== "disabled") {
     app.all(

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

@@ -0,0 +1,178 @@
+/**
+ * Application-level quotas for the two public seller operations.
+ *
+ * A process-wide bucket is always enforced, including when the hosting
+ * platform exposes no trustworthy caller identity. A second per-caller
+ * bucket is enabled only when the operator names a header that its trusted
+ * edge sets after stripping caller-supplied values. Request payload fields
+ * and forwarded IP headers are deliberately never treated as identities.
+ * The defaults are process-local; multi-replica owners can inject async
+ * shared limiters without making that infrastructure mandatory.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { RateLimitExceeded, SlidingWindowLimiter } from "@bnbagent/sdk/utils";
+import type { NextFunction, Request, Response } from "express";
+
+type CommerceOperation = "negotiate" | "notify_funded";
+
+const DEFAULT_GLOBAL_MAX = 120;
+const DEFAULT_CALLER_MAX = 20;
+const DEFAULT_WINDOW_SECONDS = 60;
+const DEFAULT_MAX_CALLERS = 10_000;
+const SHARED_LIMITER_TIMEOUT_MS = 5_000;
+
+export interface CommerceRateLimiter {
+  /** Consume one request; honor cancellation and reject denied requests. */
+  check(key: string, signal?: AbortSignal): void | Promise<void>;
+}
+
+export interface CommerceRateLimiters {
+  readonly global: CommerceRateLimiter;
+  readonly caller: CommerceRateLimiter;
+}
+
+interface CachedLimiters extends CommerceRateLimiters {
+  readonly configKey: string;
+}
+
+const callerContext = new AsyncLocalStorage<string | undefined>();
+let cached: CachedLimiters | undefined;
+let injected: CommerceRateLimiters | undefined;
+let warnedProcessLocal = false;
+
+/** Replace process-local counters with application-owned shared limiters. */
+export function setCommerceRateLimiters(
+  value: CommerceRateLimiters | null,
+): void {
+  injected = value ?? undefined;
+}
+
+function positiveEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || !/^\d+$/u.test(raw)) return fallback;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+function limiters(): CommerceRateLimiters {
+  if (injected) return injected;
+  const environment = (
+    process.env.ENV ||
+    process.env.ENVIRONMENT ||
+    process.env.NODE_ENV ||
+    ""
+  )
+    .trim()
+    .toLowerCase();
+  if (
+    !warnedProcessLocal &&
+    !["dev", "development", "test"].includes(environment)
+  ) {
+    warnedProcessLocal = true;
+    console.warn(
+      "[seller-agent] this process is using process-local rate limits; " +
+        "inject shared limiters or enforce equivalent limits at a trusted edge before scaling out.",
+    );
+  }
+  const names = [
+    "SELLER_RATE_LIMIT_GLOBAL_MAX_REQUESTS",
+    "SELLER_RATE_LIMIT_CALLER_MAX_REQUESTS",
+    "SELLER_RATE_LIMIT_WINDOW_SECONDS",
+    "SELLER_RATE_LIMIT_MAX_CALLERS",
+  ] as const;
+  const configKey = names.map((name) => process.env[name] ?? "").join("\0");
+  if (cached?.configKey === configKey) return cached;
+
+  const windowSeconds = positiveEnv(
+    "SELLER_RATE_LIMIT_WINDOW_SECONDS",
+    DEFAULT_WINDOW_SECONDS,
+  );
+  cached = {
+    configKey,
+    global: new SlidingWindowLimiter(
+      positiveEnv("SELLER_RATE_LIMIT_GLOBAL_MAX_REQUESTS", DEFAULT_GLOBAL_MAX),
+      windowSeconds,
+      2,
+    ),
+    caller: new SlidingWindowLimiter(
+      positiveEnv("SELLER_RATE_LIMIT_CALLER_MAX_REQUESTS", DEFAULT_CALLER_MAX),
+      windowSeconds,
+      positiveEnv("SELLER_RATE_LIMIT_MAX_CALLERS", DEFAULT_MAX_CALLERS),
+    ),
+  };
+  return cached;
+}
+
+async function checkLimiter(
+  limiter: CommerceRateLimiter,
+  key: string,
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const controller = new AbortController();
+  try {
+    await Promise.race([
+      Promise.resolve(limiter.check(key, controller.signal)),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () => {
+            controller.abort();
+            reject(new RateLimitExceeded("Seller rate limiter unavailable"));
+          },
+          SHARED_LIMITER_TIMEOUT_MS,
+        );
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+function trustedCaller(headers: Request["headers"]): string | undefined {
+  const header = (process.env.SELLER_TRUSTED_CALLER_HEADER ?? "")
+    .trim()
+    .toLowerCase();
+  if (!/^[a-z0-9-]+$/u.test(header)) return undefined;
+
+  const raw = headers[header];
+  if (typeof raw !== "string") return undefined;
+  const value = raw.trim();
+  if (value.length === 0 || value.length > 256 || /[\r\n]/u.test(value)) {
+    return undefined;
+  }
+  return value;
+}
+
+/** Carry only an operator-configured, edge-authenticated identity. */
+export function withTrustedCaller<T>(
+  headers: Request["headers"],
+  work: () => T,
+): T {
+  return callerContext.run(trustedCaller(headers), work);
+}
+
+/** Express middleware that makes the trusted identity available to handlers. */
+export function requestLimitContext(
+  req: Request,
+  _res: Response,
+  next: NextFunction,
+): void {
+  withTrustedCaller(req.headers, next);
+}
+
+/** Consume both the mandatory process bucket and optional caller bucket. */
+export async function limitCommerceOperation(
+  operation: CommerceOperation,
+): Promise<void> {
+  const active = limiters();
+  await checkLimiter(active.global, operation);
+  const caller = callerContext.getStore();
+  if (caller !== undefined) {
+    await checkLimiter(active.caller, `${operation}:${caller}`);
+  }
+}
+
+export function isCommerceRateLimitError(error: unknown): boolean {
+  return error instanceof RateLimitExceeded;
+}