@devlab.group/agent-commerce 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, B as BackendHandler, A as AdapterDescriptor, a as AdapterHealth, C as CommerceResource, R as ResourceRegistry, b as PaymentProvider, L as Logger, c as Clock, d as IdGenerator } from './runtime-B-9IjMbO.js';
-export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PaymentChallenge, h as PaymentContext, i as PaymentRequirement, j as PaymentResult, k as PaymentSettlementContext, l as PaymentSubmission, m as PaymentVerificationContext, n as Pricing, o as ProtocolName, s as systemClock } from './runtime-B-9IjMbO.js';
+import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, B as BackendHandler, A as AdapterDescriptor, a as AdapterHealth, C as CommerceResource, R as ResourceRegistry, b as PaymentProvider, L as Logger, c as Clock, d as IdGenerator } from './runtime-Bqg9qW3t.js';
+export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PROTOCOL_NAMES, h as PaymentChallenge, i as PaymentContext, j as PaymentRequirement, k as PaymentResult, l as PaymentSettlementContext, m as PaymentSubmission, n as PaymentVerificationContext, o as Pricing, p as ProtocolName, s as systemClock } from './runtime-Bqg9qW3t.js';
 import { X as X402FacilitatorConfig } from './guardrails-Dmwi63KB.js';
-import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter } from './protocol-adapter-CZPOb9uG.js';
-export { d as COMMERCE_EVENT_TYPES, e as CanonicalRequest, f as CommerceEventType, g as EventSink, h as ExecutionOutcome, H as HttpProtocolAdapter, i as ProtocolAdapterContext, j as isHttpProtocolAdapter } from './protocol-adapter-CZPOb9uG.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter } from './protocol-adapter-BAKGnuZ4.js';
+export { A as AdapterHttpRoute, d as COMMERCE_EVENT_TYPES, e as CanonicalRequest, f as CommerceEventType, g as EventSink, h as ExecutionOutcome, H as HttpProtocolAdapter, i as ProtocolAdapterContext, j as isHttpProtocolAdapter } from './protocol-adapter-BAKGnuZ4.js';
 import { FastifyInstance } from 'fastify';
 import 'node:http';
 
@@ -316,7 +316,7 @@ interface ReceiptStore {
  * Two-phase validation:
  * 1. Zod validates *shape* (types, required fields, unknown-key rejection).
  * Numeric/boolean leaves accept either their native type or a string
- * (env substitution always produces a string), and are left as-is here —
+ * (env substitution always produces a string), and are left as-is here -
  * Zod's typed transforms have surprising inference interactions with
  * `.strict()` objects, so numeric/boolean coercion is done explicitly,
  * in plain TypeScript, in the normalisation pass below.
@@ -362,6 +362,10 @@ interface GatewayConfig {
             readonly enabled: boolean;
             readonly mountPath: string;
         };
+        readonly a2a: {
+            readonly enabled: boolean;
+            readonly mountPath: string;
+        };
     };
     /** Canonical resources, already normalised. */
     readonly resources: readonly CommerceResource[];

package/dist/index.js

@@ -1,6 +1,6 @@
-import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-MEPETSP6.js';
-import { CommerceError, PAYMENT_INPUT_FIELD, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, PAYMENT_HEADER, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-BQNE3A5H.js';
-export { COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-BQNE3A5H.js';
+import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-5TKNTWMC.js';
+import { PROTOCOL_NAMES, CommerceError, PAYMENT_INPUT_FIELD, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, PAYMENT_HEADER, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-EIACECVM.js';
+export { COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-EIACECVM.js';
 import { promises, existsSync, mkdirSync, accessSync, constants, closeSync, openSync, chmodSync } from 'fs';
 import * as path from 'path';
 import { dirname } from 'path';
@@ -96,33 +96,15 @@ var HttpBackendExecutor = class {
   async call(handler, request) {
     const timeoutMs = handler.timeoutMs ?? DEFAULT_BACKEND_TIMEOUT_MS;
     const inputRecord = isPlainObject2(request.input) ? request.input : {};
+    const context = { requestId: request.requestId, resourceId: request.resourceId };
+    const parts = buildBackendRequestParts(handler, inputRecord, context);
     let target;
-    let remaining;
     try {
-      const templated = applyPathTemplate(handler.url, inputRecord);
-      target = new URL(templated.url);
-      remaining = templated.remaining;
+      target = new URL(parts.url);
     } catch (error) {
-      if (error instanceof Error && error.message.startsWith("invalid-path-parameter:")) {
-        const field = error.message.slice("invalid-path-parameter:".length);
-        throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" is not a valid value`, {
-          requestId: request.requestId,
-          resourceId: request.resourceId,
-          details: { field }
-        });
-      }
-      if (error instanceof Error && error.message.startsWith("missing-path-parameter:")) {
-        const field = error.message.slice("missing-path-parameter:".length);
-        throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" was not supplied`, {
-          requestId: request.requestId,
-          resourceId: request.resourceId,
-          details: { field }
-        });
-      }
       throw new CommerceError("BACKEND_ERROR", "Backend URL could not be constructed from input", {
-        requestId: request.requestId,
-        resourceId: request.resourceId,
-        details: { reason: describeConstructionError(error) },
+        ...context,
+        details: { reason: "invalid-url" },
         cause: error
       });
     }
@@ -144,16 +126,12 @@ var HttpBackendExecutor = class {
     }
     const headers = { ...handler.headers ?? {} };
     let body;
-    if (handler.method === "GET" || handler.method === "DELETE") {
-      checkQueryCollision(target, remaining, {
-        requestId: request.requestId,
-        resourceId: request.resourceId
-      });
-      for (const [key, value] of Object.entries(remaining)) {
-        target.searchParams.set(key, stringifyPrimitive(value));
-      }
-    } else {
-      body = JSON.stringify(remaining);
+    checkQueryCollision(target, parts.query, context);
+    for (const [key, value] of Object.entries(parts.query)) {
+      target.searchParams.set(key, stringifyPrimitive(value));
+    }
+    if (parts.body !== void 0) {
+      body = JSON.stringify(parts.body.value);
       if (!hasHeader(headers, "content-type")) {
         headers["content-type"] = "application/json";
       }
@@ -256,37 +234,42 @@ function findUnparsedBraceToken(url) {
 }
 function validateBackendRequestShape(handler, input, context) {
   const inputRecord = isPlainObject2(input) ? input : {};
-  let templated;
+  const parts = buildBackendRequestParts(handler, inputRecord, context);
+  let target;
   try {
-    templated = applyPathTemplate(handler.url, inputRecord);
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith("invalid-path-parameter:")) {
-      const field = error.message.slice("invalid-path-parameter:".length);
-      throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" is not a valid value`, {
-        requestId: context.requestId,
-        resourceId: context.resourceId,
-        details: { field }
-      });
-    }
-    if (error instanceof Error && error.message.startsWith("missing-path-parameter:")) {
-      const field = error.message.slice("missing-path-parameter:".length);
-      throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" was not supplied`, {
-        requestId: context.requestId,
-        resourceId: context.resourceId,
-        details: { field }
-      });
-    }
+    target = new URL(parts.url);
+  } catch {
     return;
   }
-  if (handler.method === "GET" || handler.method === "DELETE") {
-    let target;
-    try {
-      target = new URL(templated.url);
-    } catch {
-      return;
-    }
-    checkQueryCollision(target, templated.remaining, context);
+  checkQueryCollision(target, parts.query, context);
+}
+function acceptsBody(method) {
+  return method !== "GET" && method !== "DELETE";
+}
+function buildBackendRequestParts(handler, input, context) {
+  const bindings = handler.inputBindings;
+  if (bindings === void 0) {
+    const { url: url2, remaining } = applyPathTemplate(handler.url, input, context);
+    return acceptsBody(handler.method) ? { url: url2, query: {}, body: { value: remaining } } : { url: url2, query: remaining };
+  }
+  const pathValues = bindings.path === void 0 ? {} : resolveBoundGroup(input, bindings.path, "path", context);
+  const { url } = applyPathTemplate(handler.url, pathValues, context);
+  const query = bindings.query === void 0 ? {} : resolveBoundGroup(input, bindings.query, "query", context);
+  const bodyValue = bindings.body === void 0 ? void 0 : input[bindings.body];
+  if (bodyValue === void 0 || !acceptsBody(handler.method)) return { url, query };
+  return { url, query, body: { value: bodyValue } };
+}
+function resolveBoundGroup(input, key, kind, context) {
+  const value = input[key];
+  if (value === void 0) return {};
+  if (!isPlainObject2(value)) {
+    throw new CommerceError(
+      "INPUT_INVALID",
+      `Input "${key}" must be an object of ${kind} parameters`,
+      { ...context, details: { field: key } }
+    );
   }
+  return value;
 }
 function checkQueryCollision(target, remaining, context) {
   const templateKeys = new Set(target.searchParams.keys());
@@ -304,7 +287,7 @@ function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var TRAVERSAL_PATH_VALUES = /* @__PURE__ */ new Set(["", ".", ".."]);
-function applyPathTemplate(template, input) {
+function applyPathTemplate(template, input, context) {
   const remaining = { ...input };
   let missing;
   let invalid;
@@ -323,19 +306,19 @@ function applyPathTemplate(template, input) {
     return encodeURIComponent(raw);
   });
   if (missing !== void 0) {
-    throw new Error(`missing-path-parameter:${missing}`);
+    throw new CommerceError("INPUT_INVALID", `Path parameter "${missing}" was not supplied`, {
+      ...context,
+      details: { field: missing }
+    });
   }
   if (invalid !== void 0) {
-    throw new Error(`invalid-path-parameter:${invalid}`);
+    throw new CommerceError("INPUT_INVALID", `Path parameter "${invalid}" is not a valid value`, {
+      ...context,
+      details: { field: invalid }
+    });
   }
   return { url, remaining };
 }
-function describeConstructionError(error) {
-  if (error instanceof Error && error.message.startsWith("missing-path-parameter:")) {
-    return error.message;
-  }
-  return "invalid-url";
-}
 function stringifyPrimitive(value) {
   if (value === void 0 || value === null) return "";
   if (typeof value === "string") return value;
@@ -1103,15 +1086,15 @@ var ServerSchema = z.object({
   adminToken: z.string().min(1).optional(),
   /** Browser origins allowed to read the dashboard-facing routes. Empty by default: closed. */
   // Entries are matched literally against the browser's
-  // `Origin` header, so `"*"` and a trailing slash match nothing at all —
+  // `Origin` header, so `"*"` and a trailing slash match nothing at all -
   // fail-closed (a lockout, not a bypass), but silently, and a lockout with
   // no explanation is the kind of thing an operator "fixes" by disabling the
   // check. Reject those two shapes with a pointer instead.
   allowedOrigins: z.array(
     z.string().min(1).refine((origin) => origin !== "*", {
-      message: `wildcard "*" is not supported \u2014 allowedOrigins entries are matched literally against the browser's Origin header, so "*" would match nothing. List each scheme://host[:port] explicitly.`
+      message: `wildcard "*" is not supported - allowedOrigins entries are matched literally against the browser's Origin header, so "*" would match nothing. List each scheme://host[:port] explicitly.`
     }).refine((origin) => !origin.endsWith("/"), {
-      message: 'must not end with "/" \u2014 a browser Origin header never has a trailing slash, so this entry would match nothing. Use e.g. "http://localhost:5173".'
+      message: 'must not end with "/" - a browser Origin header never has a trailing slash, so this entry would match nothing. Use e.g. "http://localhost:5173".'
     })
   ).optional()
 }).strict();
@@ -1125,16 +1108,19 @@ var RESERVED_GATEWAY_PATHS = [
   "/health",
   "/ready",
   "/.well-known/agent-commerce",
+  // Fixed by the A2A specification, so it is the adapter's to serve and never
+  // a configurable mount's to claim.
+  "/.well-known/agent-card.json",
   "/api/resources",
   "/api/resources/:id/invoke",
   "/api/receipts",
   "/api/events",
   "/api/events/stream"
 ];
-var McpMountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"), {
-  message: 'must start with "/" \u2014 it is an absolute gateway path, e.g. "/mcp".'
+var MountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"), {
+  message: 'must start with "/" - it is an absolute gateway path, e.g. "/mcp".'
 }).refine((value) => !/[:*?\s]/.test(value), {
-  message: 'must not contain ":", "*", "?" or whitespace \u2014 the mount is a literal path prefix, not a Fastify route pattern, and registers its own wildcard.'
+  message: 'must not contain ":", "*", "?" or whitespace - the mount is a literal path prefix, not a Fastify route pattern, and registers its own wildcard.'
 }).refine(
   (value) => {
     const base = value.replace(/\/+$/, "");
@@ -1150,16 +1136,29 @@ var ProtocolsSchema = z.object({
   http: z.object({ enabled: BooleanOrString }).strict(),
   mcp: z.object({
     enabled: BooleanOrString,
-    mountPath: McpMountPathSchema
-  }).strict()
+    mountPath: MountPathSchema
+  }).strict(),
+  // Optional block: A2A is off unless an operator asks for it, and an
+  // existing config predating the adapter stays valid.
+  a2a: z.object({
+    enabled: BooleanOrString,
+    mountPath: MountPathSchema.optional()
+  }).strict().optional()
 }).strict();
+var DEFAULT_A2A_MOUNT_PATH = "/a2a";
 var BackendMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+var BackendInputBindingsSchema = z.object({
+  path: z.string().min(1).optional(),
+  query: z.string().min(1).optional(),
+  body: z.string().min(1).optional()
+}).strict();
 var BackendHandlerSchema = z.object({
   type: z.literal("http"),
   method: BackendMethodSchema,
   url: z.string().min(1),
   headers: z.record(z.string(), z.string()).optional(),
-  timeoutMs: NumberOrString.optional()
+  timeoutMs: NumberOrString.optional(),
+  inputBindings: BackendInputBindingsSchema.optional()
 }).strict();
 var PricingSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("free") }).strict(),
@@ -1204,7 +1203,7 @@ var FacilitatorSchema = z.discriminatedUnion("mode", [
   z.object({
     mode: z.literal("remote"),
     url: z.string().min(1),
-    // Absent means "this facilitator takes no credential" — an explicit
+    // Absent means "this facilitator takes no credential" - an explicit
     // statement, normalised to `{ type: 'none' }` below. On a mainnet that
     // combination is refused outright, so the default can never quietly
     // become an unauthenticated production facilitator.
@@ -1222,7 +1221,7 @@ var X402Schema = z.object({
   payTo: z.string().min(1),
   maxTimeoutSeconds: NumberOrString,
   facilitator: FacilitatorSchema,
-  /** Real funds. Never defaulted — see src/payments/x402/guardrails.ts. */
+  /** Real funds. Never defaulted - see src/payments/x402/guardrails.ts. */
   allowMainnet: BooleanOrString.optional(),
   /** Accepts a mainnet facilitator that takes no credential. Never defaulted. */
   allowUnauthenticatedFacilitator: BooleanOrString.optional()
@@ -1336,7 +1335,7 @@ function toBoolean(value, path2) {
     { details: { path: path2 } }
   );
 }
-var SUPPORTED_PROTOCOLS = /* @__PURE__ */ new Set(["http", "mcp"]);
+var SUPPORTED_PROTOCOLS = new Set(PROTOCOL_NAMES);
 var SUPPORTED_PAYMENT_METHODS = /* @__PURE__ */ new Set(["x402"]);
 function normalise(raw) {
   const protocols = {
@@ -1344,8 +1343,13 @@ function normalise(raw) {
     mcp: {
       enabled: toBoolean(raw.protocols.mcp.enabled, "protocols.mcp.enabled"),
       mountPath: raw.protocols.mcp.mountPath
+    },
+    a2a: {
+      enabled: toBoolean(raw.protocols.a2a?.enabled ?? false, "protocols.a2a.enabled"),
+      mountPath: raw.protocols.a2a?.mountPath ?? DEFAULT_A2A_MOUNT_PATH
     }
   };
+  validateMountPaths(protocols);
   const x402Raw = raw.payments.x402;
   const facilitator = x402Raw === void 0 ? void 0 : x402Raw.facilitator.mode === "local" ? { mode: "local", signerPrivateKey: x402Raw.facilitator.signerPrivateKey } : {
     mode: "remote",
@@ -1420,6 +1424,25 @@ function normalise(raw) {
     }
   };
 }
+function validateMountPaths(protocols) {
+  const mounts = [
+    ["mcp", protocols.mcp],
+    ["a2a", protocols.a2a]
+  ].filter(([, p]) => p.enabled);
+  for (const [index, [nameA, a]] of mounts.entries()) {
+    for (const [nameB, b] of mounts.slice(index + 1)) {
+      const baseA = a.mountPath.replace(/\/+$/, "");
+      const baseB = b.mountPath.replace(/\/+$/, "");
+      if (baseA === baseB || baseA.startsWith(`${baseB}/`) || baseB.startsWith(`${baseA}/`)) {
+        throw new CommerceError(
+          "CONFIG_INVALID",
+          `protocols.${nameA}.mountPath ("${a.mountPath}") collides with protocols.${nameB}.mountPath ("${b.mountPath}") - each mount registers a wildcard, so overlapping prefixes cannot both be served`,
+          { details: { path: `protocols.${nameA}.mountPath` } }
+        );
+      }
+    }
+  }
+}
 function normaliseResource(id, entry, protocols, x402) {
   if (entry.input !== void 0) validateResourceSchemaKeywords(id, "input", entry.input);
   const inputProperties = entry.input?.["properties"];
@@ -1440,7 +1463,7 @@ function normaliseResource(id, entry, protocols, x402) {
       const hint = protocol === "ucp" ? " (UCP is planned, not supported in this release)" : "";
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: http, mcp.`,
+        `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: http, mcp, a2a.`,
         { details: { path: `resources.${id}.expose`, resourceId: id, protocol } }
       );
     }
@@ -1461,6 +1484,13 @@ function normaliseResource(id, entry, protocols, x402) {
       );
     }
   }
+  if (entry.expose.includes("a2a") && !protocols.a2a.enabled) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" is exposed via "a2a" but protocols.a2a.enabled is false`,
+      { details: { path: `resources.${id}.expose`, resourceId: id } }
+    );
+  }
   if (entry.expose.includes("http") && !protocols.http.enabled) {
     throw new CommerceError(
       "CONFIG_INVALID",
@@ -1469,7 +1499,8 @@ function normaliseResource(id, entry, protocols, x402) {
     );
   }
   validateBackendUrl(id, entry.backend.url);
-  validatePathParametersDeclared(id, entry.backend.url, entry.input);
+  const pathScope = validateInputBindings(id, entry.backend, entry.input);
+  validatePathParametersDeclared(id, entry.backend.url, pathScope.schema, pathScope.where);
   if (entry.pricing.type === "dynamic") {
     throw new CommerceError(
       "CONFIG_INVALID",
@@ -1522,7 +1553,8 @@ function normaliseResource(id, entry, protocols, x402) {
         timeoutMs: toNumber(entry.backend.timeoutMs, `resources.${id}.backend.timeoutMs`, {
           min: 1
         })
-      } : {}
+      } : {},
+      ...entry.backend.inputBindings !== void 0 ? { inputBindings: pickDefined(entry.backend.inputBindings) } : {}
     },
     pricing,
     exposedVia: entry.expose,
@@ -1602,7 +1634,7 @@ function validateResourceSchemaKeywords(id, path2, schema) {
   if ((Object.hasOwn(schema, "properties") || Object.hasOwn(schema, "required")) && excludesObjectType(schema)) {
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Resource "${id}" ${path2} declares "properties" and/or "required" but its "type" (${JSON.stringify(schema["type"])}) does not include "object" \u2014 the validator will never route a value through either check under that type, so this schema claims to constrain input it does not actually enforce. Remove "properties"/"required", or include "object" in "type".`,
+      `Resource "${id}" ${path2} declares "properties" and/or "required" but its "type" (${JSON.stringify(schema["type"])}) does not include "object" - the validator will never route a value through either check under that type, so this schema claims to constrain input it does not actually enforce. Remove "properties"/"required", or include "object" in "type".`,
       { details: { path: `resources.${id}.${path2}`, resourceId: id } }
     );
   }
@@ -1636,7 +1668,7 @@ function validateResourceSchemaKeywords(id, path2, schema) {
     validateResourceSchemaKeywords(id, `${path2}.items`, items);
   } else if (Array.isArray(items)) {
     console.warn(
-      `[agent-commerce] resource "${id}" ${path2}.items is a tuple (an array of schemas), which this gateway does not enforce \u2014 only a single schema applied to every array element is supported (see src/core/execution/validation.ts). Each position's schema is unenforced; treat it as documentation only.`
+      `[agent-commerce] resource "${id}" ${path2}.items is a tuple (an array of schemas), which this gateway does not enforce - only a single schema applied to every array element is supported (see src/core/execution/validation.ts). Each position's schema is unenforced; treat it as documentation only.`
     );
   }
 }
@@ -1647,14 +1679,14 @@ function validatePricingAmount(id, amount, x402) {
   if (!PRICING_AMOUNT_PATTERN.test(amount)) {
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Resource "${id}" has pricing.amount "${amount}", which is not a plain positive decimal (no currency symbol, no thousands separator, no exponent \u2014 e.g. "0.01")`,
+      `Resource "${id}" has pricing.amount "${amount}", which is not a plain positive decimal (no currency symbol, no thousands separator, no exponent - e.g. "0.01")`,
       { details: { path: path2, resourceId: id } }
     );
   }
   if (ZERO_AMOUNT_PATTERN.test(amount)) {
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Resource "${id}" has pricing.amount "0" \u2014 a paid resource cannot cost zero; use "pricing: { type: free }" instead`,
+      `Resource "${id}" has pricing.amount "0" - a paid resource cannot cost zero; use "pricing: { type: free }" instead`,
       { details: { path: path2, resourceId: id } }
     );
   }
@@ -1669,7 +1701,86 @@ function validatePricingAmount(id, amount, x402) {
     }
   }
 }
-function validatePathParametersDeclared(id, url, input) {
+function validateInputBindings(id, backend, input) {
+  const legacy = { schema: input, where: "its input schema" };
+  const bindings = backend.inputBindings;
+  const templated = extractPathParameterNames(backend.url).length > 0;
+  if (bindings === void 0) return legacy;
+  const path2 = `resources.${id}.backend.inputBindings`;
+  const fail = (message, details = {}) => {
+    throw new CommerceError("CONFIG_INVALID", `Resource "${id}" ${message}`, {
+      details: { path: path2, resourceId: id, ...details }
+    });
+  };
+  const entries = Object.entries(bindings).filter(
+    (entry) => entry[1] !== void 0
+  );
+  if (entries.length === 0) {
+    fail("has an empty backend.inputBindings - remove the block to use the default mapping");
+  }
+  if (backend.method === "GET" || backend.method === "DELETE") {
+    if (bindings.body !== void 0) {
+      fail(
+        `binds a request body on a ${backend.method}, which sends none - the value would be silently dropped`
+      );
+    }
+  }
+  if (templated && bindings.path === void 0) {
+    fail(
+      'has backend.url path parameters but no "path" binding - in explicit binding mode nothing else supplies them, so every call would fail to reach the backend'
+    );
+  }
+  const seen = /* @__PURE__ */ new Map();
+  const properties = isPlainObject4(input?.["properties"]) ? input["properties"] : {};
+  const required = new Set(
+    Array.isArray(input?.["required"]) ? input["required"].filter((value) => typeof value === "string") : []
+  );
+  for (const [location, property] of entries) {
+    if (property === PAYMENT_INPUT_FIELD) {
+      fail(
+        `binds "${location}" to "${PAYMENT_INPUT_FIELD}", which is reserved for payment proofs`,
+        { location }
+      );
+    }
+    const other = seen.get(property);
+    if (other !== void 0) {
+      fail(`binds both "${other}" and "${location}" to the input property "${property}"`, {
+        location,
+        property
+      });
+    }
+    seen.set(property, location);
+    if (!Object.hasOwn(properties, property)) {
+      fail(
+        `binds "${location}" to input property "${property}", which the input schema does not declare - the schema is closed, so a caller could never supply it`,
+        { location, property }
+      );
+    }
+    const declared = properties[property];
+    if (location !== "body" && isPlainObject4(declared) && !isObjectSchemaNode(declared)) {
+      fail(
+        `binds "${location}" to input property "${property}", which is not an object schema - ${location} parameters are read as an object of name/value pairs`,
+        { location, property }
+      );
+    }
+  }
+  if (templated && bindings.path !== void 0 && !required.has(bindings.path)) {
+    fail(
+      `binds path parameters to input property "${bindings.path}" without listing it in the input schema's "required" - a caller that omits it cannot supply any path parameter, so the request could never be built`,
+      { property: bindings.path }
+    );
+  }
+  if (bindings.path === void 0) return { schema: void 0, where: "its input schema" };
+  const group = properties[bindings.path];
+  return {
+    schema: isPlainObject4(group) ? group : void 0,
+    where: `input.properties.${bindings.path}`
+  };
+}
+function pickDefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
+}
+function validatePathParametersDeclared(id, url, input, where) {
   const stray = findUnparsedBraceToken(url);
   if (stray !== void 0) {
     throw new CommerceError(
@@ -1708,14 +1819,14 @@ function validatePathParametersDeclared(id, url, input) {
     if (!Object.hasOwn(properties, param)) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" has backend.url path parameter "{${param}}" which is not declared in its input schema \u2014 the caller has no way to supply it, so every call would settle payment (if priced) and then fail to reach the backend`,
+        `Resource "${id}" has backend.url path parameter "{${param}}" which is not declared in ${where} - the caller has no way to supply it, so every call would settle payment (if priced) and then fail to reach the backend`,
         { details: { path: path2, resourceId: id, param } }
       );
     }
     if (!required.has(param)) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" has backend.url path parameter "{${param}}" declared in its input schema but not listed in "required" \u2014 a caller that omits it hits the same unservable-request problem as an undeclared parameter`,
+        `Resource "${id}" has backend.url path parameter "{${param}}" declared in ${where} but not listed in its "required" - a caller that omits it hits the same unservable-request problem as an undeclared parameter`,
         { details: { path: path2, resourceId: id, param } }
       );
     }
@@ -1977,6 +2088,7 @@ function hashToken(value) {
 // src/gateway/adapters.ts
 var MOUNT_BODY_LIMIT_BYTES = 256 * 1024;
 async function startAndMountAdapters(options) {
+  assertNoRouteConflicts(options.adapters);
   const runtimes = [];
   for (const adapter of options.adapters) {
     const adapterLogger = options.logger.child({ adapter: adapter.name });
@@ -2002,11 +2114,51 @@ async function startAndMountAdapters(options) {
   }
   return runtimes;
 }
+function routeClaims(adapters) {
+  const claims = [];
+  for (const adapter of adapters) {
+    if (!isHttpProtocolAdapter(adapter)) continue;
+    claims.push({
+      adapter: adapter.name,
+      path: adapter.mountPath.replace(/\/+$/, ""),
+      wildcard: true,
+      method: "ALL"
+    });
+    for (const route of adapter.additionalHttpRoutes ?? []) {
+      claims.push({
+        adapter: adapter.name,
+        path: route.path.replace(/\/+$/, ""),
+        wildcard: false,
+        method: route.method
+      });
+    }
+  }
+  return claims;
+}
+function claimsCollide(a, b) {
+  if (a.wildcard && (b.path === a.path || b.path.startsWith(`${a.path}/`))) return true;
+  if (b.wildcard && a.path.startsWith(`${b.path}/`)) return true;
+  return a.path === b.path && (a.method === b.method || a.method === "ALL" || b.method === "ALL");
+}
+function assertNoRouteConflicts(adapters) {
+  const claims = routeClaims(adapters);
+  for (const [index, a] of claims.entries()) {
+    for (const b of claims.slice(index + 1)) {
+      if (a.adapter === b.adapter || !claimsCollide(a, b)) continue;
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Protocol adapters "${a.adapter}" and "${b.adapter}" both claim the HTTP path "${b.path}"; each adapter path must be served by exactly one adapter`,
+        { details: { adapters: [a.adapter, b.adapter], path: b.path } }
+      );
+    }
+  }
+}
 var MOUNT_MAX_CONCURRENT_REQUESTS = 20;
 var MOUNT_BUSY_RETRY_AFTER_SECONDS = 1;
 function mountHttpAdapter(server, adapter, logger) {
   const mountPath = adapter.mountPath;
   const wildcard = mountPath.endsWith("/") ? `${mountPath}*` : `${mountPath}/*`;
+  const additionalRoutes = adapter.additionalHttpRoutes ?? [];
   let inFlight = 0;
   void server.register(async (instance) => {
     instance.addContentTypeParser(
@@ -2018,7 +2170,7 @@ function mountHttpAdapter(server, adapter, logger) {
     instance.addContentTypeParser("*", (_request, _payload, done) => {
       done(null);
     });
-    const handler = async (request, reply) => {
+    const makeHandler = (handleHttp) => async (request, reply) => {
       if (inFlight >= MOUNT_MAX_CONCURRENT_REQUESTS) {
         const error = new CommerceError(
           "GATEWAY_BUSY",
@@ -2036,7 +2188,7 @@ function mountHttpAdapter(server, adapter, logger) {
           logger
         );
         try {
-          await adapter.handleHttp(request.raw, reply.raw);
+          await handleHttp(request.raw, reply.raw);
         } catch (error) {
           logger.error({ err: describeError3(error) }, "Protocol adapter request handler threw");
           if (!reply.raw.headersSent) {
@@ -2050,8 +2202,16 @@ function mountHttpAdapter(server, adapter, logger) {
         inFlight -= 1;
       }
     };
-    instance.all(mountPath, handler);
-    instance.all(wildcard, handler);
+    const mountHandler = makeHandler((req, res) => adapter.handleHttp(req, res));
+    instance.all(mountPath, mountHandler);
+    instance.all(wildcard, mountHandler);
+    for (const route of additionalRoutes) {
+      instance.route({
+        method: route.method,
+        url: route.path,
+        handler: makeHandler((req, res) => route.handleHttp(req, res))
+      });
+    }
   });
 }
 function enforceMountBodyLimit(req, res, maxBytes, logger) {