@devlab.group/agent-commerce 1.1.0 → 1.2.0

package/dist/cli/index.js

@@ -2,14 +2,15 @@
 import { ZodError, z } from 'zod';
 import { existsSync, mkdirSync, accessSync, constants, closeSync, openSync, readFileSync, chmodSync, promises } from 'fs';
 import * as path from 'path';
-import { resolve, dirname, join } from 'path';
-import { stringify, parse, YAMLError } from 'yaml';
+import { resolve, dirname, basename as basename$1, extname, join } from 'path';
+import { stringify, parse, Document, YAMLError } from 'yaml';
 import { CommanderError, Command } from 'commander';
 import picocolors from 'picocolors';
 import { randomUUID } from 'crypto';
 import Database from 'better-sqlite3';
 import { createRequire } from 'module';
-import { writeFile } from 'fs/promises';
+import { writeFile, stat, readFile, rename, rm } from 'fs/promises';
+import { validate } from '@scalar/openapi-parser';
 import * as clack from '@clack/prompts';
 
 var __defProp = Object.defineProperty;
@@ -30,12 +31,34 @@ var init_filename = __esm({
   }
 });
 
+// src/core/domain/common.ts
+var PROTOCOL_NAMES;
+var init_common = __esm({
+  "src/core/domain/common.ts"() {
+    PROTOCOL_NAMES = ["http", "mcp", "a2a"];
+  }
+});
+
+// src/core/domain/event.ts
+var init_event = __esm({
+  "src/core/domain/event.ts"() {
+  }
+});
+
 // src/core/domain/resource.ts
 var init_resource = __esm({
   "src/core/domain/resource.ts"() {
   }
 });
 
+// src/core/domain/wire.ts
+var PAYMENT_INPUT_FIELD;
+var init_wire = __esm({
+  "src/core/domain/wire.ts"() {
+    PAYMENT_INPUT_FIELD = "_payment";
+  }
+});
+
 // src/core/errors/codes.ts
 var COMMERCE_ERROR_HTTP_STATUS, RETRYABLE_ERROR_CODES;
 var init_codes = __esm({
@@ -142,6 +165,45 @@ var init_logger = __esm({
   }
 });
 
+// src/core/interfaces/protocol-adapter.ts
+var init_protocol_adapter = __esm({
+  "src/core/interfaces/protocol-adapter.ts"() {
+  }
+});
+
+// src/core/interfaces/runtime.ts
+var systemClock;
+var init_runtime = __esm({
+  "src/core/interfaces/runtime.ts"() {
+    systemClock = {
+      now: () => /* @__PURE__ */ new Date(),
+      nowIso: () => (/* @__PURE__ */ new Date()).toISOString(),
+      monotonicMs: () => performance.now()
+    };
+  }
+});
+
+// src/core/public-types.ts
+var init_public_types = __esm({
+  "src/core/public-types.ts"() {
+    init_common();
+    init_event();
+    init_resource();
+    init_wire();
+    init_errors();
+    init_logger();
+    init_protocol_adapter();
+    init_runtime();
+  }
+});
+
+// src/core/index.ts
+var init_core = __esm({
+  "src/core/index.ts"() {
+    init_public_types();
+  }
+});
+
 // src/core/execution/backend-http.ts
 function extractPathParameterNames(url) {
   return [...url.matchAll(PATH_PARAM_PATTERN)].map((match) => match[1]);
@@ -169,14 +231,6 @@ var init_event_bus = __esm({
   }
 });
 
-// src/core/domain/wire.ts
-var PAYMENT_INPUT_FIELD;
-var init_wire = __esm({
-  "src/core/domain/wire.ts"() {
-    PAYMENT_INPUT_FIELD = "_payment";
-  }
-});
-
 // src/core/execution/validation.ts
 function typeList(raw) {
   if (typeof raw === "string") return [raw];
@@ -223,50 +277,6 @@ var init_execution = __esm({
   }
 });
 
-// src/core/domain/event.ts
-var init_event = __esm({
-  "src/core/domain/event.ts"() {
-  }
-});
-
-// src/core/interfaces/protocol-adapter.ts
-var init_protocol_adapter = __esm({
-  "src/core/interfaces/protocol-adapter.ts"() {
-  }
-});
-
-// src/core/interfaces/runtime.ts
-var systemClock;
-var init_runtime = __esm({
-  "src/core/interfaces/runtime.ts"() {
-    systemClock = {
-      now: () => /* @__PURE__ */ new Date(),
-      nowIso: () => (/* @__PURE__ */ new Date()).toISOString(),
-      monotonicMs: () => performance.now()
-    };
-  }
-});
-
-// src/core/public-types.ts
-var init_public_types = __esm({
-  "src/core/public-types.ts"() {
-    init_event();
-    init_resource();
-    init_wire();
-    init_errors();
-    init_logger();
-    init_protocol_adapter();
-    init_runtime();
-  }
-});
-
-// src/core/index.ts
-var init_core = __esm({
-  "src/core/index.ts"() {
-    init_public_types();
-  }
-});
-
 // src/payments/x402/networks.ts
 function findNetworkProfile(id) {
   return BY_ID.get(id);
@@ -770,7 +780,7 @@ function validateMountPaths(protocols) {
       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}") \u2014 each mount registers a wildcard, so overlapping prefixes cannot both be served`,
+          `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` } }
         );
       }
@@ -833,7 +843,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",
@@ -886,7 +897,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,
@@ -940,7 +952,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 } }
     );
   }
@@ -974,7 +986,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.`
     );
   }
 }
@@ -983,14 +995,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 } }
     );
   }
@@ -1005,7 +1017,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 = isPlainObject2(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" && isPlainObject2(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: isPlainObject2(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(
@@ -1044,14 +1135,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 } }
       );
     }
@@ -1094,7 +1185,7 @@ function validateAddress(path2, value) {
     );
   }
 }
-var SUPPORTED_CONFIG_VERSION, ADDRESS_PATTERN, ZERO_ADDRESS_PATTERN, MCP_TOOL_NAME_PATTERN, NumberOrString, BooleanOrString, MerchantSchema, ServerSchema, StorageSchema, RESERVED_GATEWAY_PATHS, MountPathSchema, ProtocolsSchema, DEFAULT_A2A_MOUNT_PATH, BackendMethodSchema, BackendHandlerSchema, PricingSchema, JsonSchemaValueSchema, ResourceEntrySchema, ResourcesMapSchema, FacilitatorAuthSchema, FacilitatorSchema, X402Schema, PaymentsSchema, RawConfigSchema, SUPPORTED_PROTOCOLS, SUPPORTED_PAYMENT_METHODS, EMPTY_CLOSED_OBJECT_SCHEMA, UNSUPPORTED_SCHEMA_KEYWORDS, PRICING_AMOUNT_PATTERN, ZERO_AMOUNT_PATTERN;
+var SUPPORTED_CONFIG_VERSION, ADDRESS_PATTERN, ZERO_ADDRESS_PATTERN, MCP_TOOL_NAME_PATTERN, NumberOrString, BooleanOrString, MerchantSchema, ServerSchema, StorageSchema, RESERVED_GATEWAY_PATHS, MountPathSchema, ProtocolsSchema, DEFAULT_A2A_MOUNT_PATH, BackendMethodSchema, BackendInputBindingsSchema, BackendHandlerSchema, PricingSchema, JsonSchemaValueSchema, ResourceEntrySchema, ResourcesMapSchema, FacilitatorAuthSchema, FacilitatorSchema, X402Schema, PaymentsSchema, RawConfigSchema, SUPPORTED_PROTOCOLS, SUPPORTED_PAYMENT_METHODS, EMPTY_CLOSED_OBJECT_SCHEMA, UNSUPPORTED_SCHEMA_KEYWORDS, PRICING_AMOUNT_PATTERN, ZERO_AMOUNT_PATTERN;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     init_execution();
@@ -1119,15 +1210,15 @@ var init_schema = __esm({
       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();
@@ -1151,9 +1242,9 @@ var init_schema = __esm({
       "/api/events/stream"
     ];
     MountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"), {
-      message: 'must start with "/" \u2014 it is an absolute gateway path, e.g. "/mcp".'
+      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(/\/+$/, "");
@@ -1180,12 +1271,18 @@ var init_schema = __esm({
     }).strict();
     DEFAULT_A2A_MOUNT_PATH = "/a2a";
     BackendMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+    BackendInputBindingsSchema = z.object({
+      path: z.string().min(1).optional(),
+      query: z.string().min(1).optional(),
+      body: z.string().min(1).optional()
+    }).strict();
     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();
     PricingSchema = z.discriminatedUnion("type", [
       z.object({ type: z.literal("free") }).strict(),
@@ -1230,7 +1327,7 @@ var init_schema = __esm({
       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.
@@ -1248,7 +1345,7 @@ var init_schema = __esm({
       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()
@@ -1265,7 +1362,7 @@ var init_schema = __esm({
       resources: ResourcesMapSchema,
       payments: PaymentsSchema
     }).strict();
-    SUPPORTED_PROTOCOLS = /* @__PURE__ */ new Set(["http", "mcp", "a2a"]);
+    SUPPORTED_PROTOCOLS = new Set(PROTOCOL_NAMES);
     SUPPORTED_PAYMENT_METHODS = /* @__PURE__ */ new Set(["x402"]);
     EMPTY_CLOSED_OBJECT_SCHEMA = {
       type: "object",
@@ -1387,6 +1484,7 @@ var init_config = __esm({
 
 // src/cli/program.ts
 init_filename();
+init_core();
 
 // src/cli/commands/demo.ts
 function defaultDemoSteps() {
@@ -1493,7 +1591,7 @@ var A2A_UNSUPPORTED = [
 
 // src/storage/receipts/store.ts
 init_core();
-var PACKAGE_VERSION = "1.1.0" ;
+var PACKAGE_VERSION = "1.2.0" ;
 
 // src/storage/receipts/redact.ts
 var SECRET_KEY_PATTERN = /private[-_ ]?key|secret|password|mnemonic|seed[-_ ]?phrase|api[-_ ]?key|authoriz(e|ation)|^auth$|auth[-_]?header|payment[-_ ]?proof|^proof$|x-payment|signature|signed[-_ ]?message|token|bearer|credential|cookie|session|jwt/i;
@@ -2246,7 +2344,7 @@ function maskMiddle(value, keep = 6) {
 }
 createRequire(import.meta.url);
 function readVersionReport() {
-  const injected = '{"cliVersion":"1.1.0","pinned":[{"name":"@coinbase/x402","version":"2.1.0","via":"@devlab.group/agent-commerce"},{"name":"@modelcontextprotocol/sdk","version":"1.30.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/core","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/evm","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"viem","version":"2.55.18","via":"@devlab.group/agent-commerce"},{"name":"better-sqlite3","version":"13.0.3","via":"@devlab.group/agent-commerce"},{"name":"fastify","version":"5.12.0","via":"@devlab.group/agent-commerce"},{"name":"pino","version":"10.3.1","via":"@devlab.group/agent-commerce"},{"name":"zod","version":"3.25.76","via":"@devlab.group/agent-commerce"}]}' ;
+  const injected = '{"cliVersion":"1.2.0","pinned":[{"name":"@coinbase/x402","version":"2.1.0","via":"@devlab.group/agent-commerce"},{"name":"@modelcontextprotocol/sdk","version":"1.30.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/core","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/evm","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"viem","version":"2.55.18","via":"@devlab.group/agent-commerce"},{"name":"better-sqlite3","version":"13.0.3","via":"@devlab.group/agent-commerce"},{"name":"fastify","version":"5.12.0","via":"@devlab.group/agent-commerce"},{"name":"pino","version":"10.3.1","via":"@devlab.group/agent-commerce"},{"name":"zod","version":"3.25.76","via":"@devlab.group/agent-commerce"}]}' ;
   {
     return JSON.parse(injected);
   }
@@ -2552,6 +2650,1109 @@ function printDoctorReport(report, io, json) {
   io.stdout(`Score: ${report.score.passed}/${report.score.total} checks passed`);
 }
 
+// src/cli/commands/import-openapi.ts
+init_core();
+
+// src/openapi/discover.ts
+init_errors();
+init_execution();
+
+// src/openapi/refs.ts
+init_errors();
+var MAX_REF_DEPTH = 100;
+function isRefNode(value) {
+  return typeof value === "object" && value !== null && typeof value.$ref === "string";
+}
+function dereference(document, node, stack = []) {
+  let current = node;
+  let chain = stack;
+  while (isRefNode(current)) {
+    const pointer = current.$ref;
+    if (!pointer.startsWith("#")) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `OpenAPI document contains an external reference "${pointer}". Only internal references (#/...) are supported`,
+        { details: { ref: pointer } }
+      );
+    }
+    if (chain.includes(pointer)) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `OpenAPI reference "${pointer}" is circular (${[...chain, pointer].join(" -> ")})`,
+        { details: { ref: pointer, chain: [...chain, pointer] } }
+      );
+    }
+    if (chain.length >= MAX_REF_DEPTH) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `OpenAPI reference chain exceeds ${MAX_REF_DEPTH} hops at "${pointer}"`,
+        { details: { ref: pointer } }
+      );
+    }
+    current = resolvePointer(document, pointer);
+    chain = [...chain, pointer];
+  }
+  return { value: current, stack: chain };
+}
+function resolvePointer(document, ref) {
+  const pointer = ref.slice(1);
+  if (pointer === "" || pointer === "/") return document;
+  if (!pointer.startsWith("/")) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `OpenAPI reference "${ref}" is not a JSON Pointer. Plain names and anchors are not supported`,
+      { details: { ref } }
+    );
+  }
+  let current = document;
+  for (const rawSegment of pointer.slice(1).split("/")) {
+    const segment = decodeURIComponent(rawSegment).replaceAll("~1", "/").replaceAll("~0", "~");
+    if (Array.isArray(current)) {
+      const index = Number(segment);
+      current = Number.isInteger(index) ? current[index] : void 0;
+    } else if (typeof current === "object" && current !== null) {
+      current = current[segment];
+    } else {
+      current = void 0;
+    }
+    if (current === void 0) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `OpenAPI reference "${ref}" does not resolve to anything in the document`,
+        { details: { ref } }
+      );
+    }
+  }
+  return current;
+}
+
+// src/openapi/discover.ts
+var SUPPORTED_METHODS = {
+  get: "GET",
+  post: "POST",
+  put: "PUT",
+  patch: "PATCH",
+  delete: "DELETE"
+};
+var NON_OPERATION_KEYS = /* @__PURE__ */ new Set(["summary", "description", "servers", "parameters", "$ref"]);
+var ID_ALLOWED = /[^A-Za-z0-9_.-]+/g;
+var MAX_ID_LENGTH = 128;
+function discoverOperations(loaded, options = {}) {
+  const { document } = loaded;
+  const diagnostics = [];
+  const operations = [];
+  const claimed = /* @__PURE__ */ new Map();
+  if (options.baseUrl !== void 0) assertAbsoluteHttpUrl(options.baseUrl, "--base-url");
+  const paths = document["paths"];
+  if (!isRecord(paths)) {
+    return { operations, diagnostics };
+  }
+  const rootServers = document["servers"];
+  const rootSecurity = document["security"];
+  for (const [path2, rawPathItem] of Object.entries(paths)) {
+    if (path2.startsWith("x-")) continue;
+    if (!path2.startsWith("/")) {
+      diagnostics.push({
+        severity: "warning",
+        code: "invalid-path-key",
+        operation: path2,
+        message: `Skipped "${path2}": a Paths key must start with "/"`
+      });
+      continue;
+    }
+    const pathItem = dereference(document, rawPathItem).value;
+    if (!isRecord(pathItem)) continue;
+    for (const [key, rawOperation] of Object.entries(pathItem)) {
+      if (NON_OPERATION_KEYS.has(key) || key.startsWith("x-")) continue;
+      const method = SUPPORTED_METHODS[key.toLowerCase()];
+      if (method === void 0) {
+        diagnostics.push({
+          severity: "warning",
+          code: "unsupported-method",
+          operation: `${key.toUpperCase()} ${path2}`,
+          message: `Skipped ${key.toUpperCase()} ${path2}: only GET, POST, PUT, PATCH and DELETE are supported`
+        });
+        continue;
+      }
+      const operation = dereference(document, rawOperation).value;
+      if (!isRecord(operation)) continue;
+      const where = `${method} ${path2}`;
+      const operationId = typeof operation["operationId"] === "string" ? operation["operationId"] : void 0;
+      const resourceId = toResourceId(operationId, method, path2);
+      const previous = claimed.get(resourceId);
+      if (previous !== void 0) {
+        throw new CommerceError(
+          "CONFIG_INVALID",
+          `Operations "${previous}" and "${where}" both produce the resource id "${resourceId}". Give one of them a distinct operationId - ids are what agents discover, so the importer will not rename either`,
+          { details: { resourceId, operations: [previous, where] } }
+        );
+      }
+      claimed.set(resourceId, where);
+      const server = selectServer(
+        document,
+        [operation["servers"], pathItem["servers"], rootServers],
+        { where, resourceId },
+        options,
+        diagnostics
+      );
+      if (server === void 0) continue;
+      const backendUrl = `${server.replace(/\/+$/, "")}${path2}`;
+      const stray = findUnparsedBraceToken(backendUrl);
+      if (stray !== void 0) {
+        diagnostics.push({
+          severity: "error",
+          code: "unsupported-path-template",
+          operation: resourceId,
+          message: `Skipped ${where}: path template "${stray}" uses characters the gateway cannot substitute (allowed: A-Z a-z 0-9 _ . -)`
+        });
+        continue;
+      }
+      const summary = typeof operation["summary"] === "string" ? operation["summary"] : void 0;
+      const description = typeof operation["description"] === "string" ? operation["description"] : summary;
+      const security = operation["security"] ?? rootSecurity;
+      operations.push({
+        resourceId,
+        method,
+        path: path2,
+        backendUrl,
+        ...operationId !== void 0 ? { operationId } : {},
+        tags: toArray(operation["tags"]).filter((tag) => typeof tag === "string"),
+        name: summary ?? operationId ?? resourceId,
+        ...description !== void 0 ? { description } : {},
+        parameters: [
+          ...toArray(pathItem["parameters"]),
+          // Operation parameters last: Phase 4 lets the later one win, which is
+          // the OpenAPI override rule (same name + in).
+          ...toArray(operation["parameters"])
+        ],
+        ...operation["requestBody"] !== void 0 ? { requestBody: operation["requestBody"] } : {},
+        ...operation["responses"] !== void 0 ? { responses: operation["responses"] } : {},
+        security: toArray(security)
+      });
+    }
+  }
+  return { operations, diagnostics };
+}
+function toResourceId(operationId, method, path2) {
+  const fromOperationId = operationId === void 0 ? "" : normaliseId(operationId);
+  if (fromOperationId !== "") return fromOperationId;
+  return normaliseId(`${method.toLowerCase()}_${path2}`);
+}
+function normaliseId(value) {
+  return value.replace(ID_ALLOWED, "_").replace(/_+/g, "_").replace(/^[_.-]+|[_.-]+$/g, "").slice(0, MAX_ID_LENGTH);
+}
+function selectServer(document, candidates, context, options, diagnostics) {
+  if (options.baseUrl !== void 0) return options.baseUrl;
+  for (const candidate of candidates) {
+    const servers = toArray(candidate);
+    const first = servers.length > 0 ? dereference(document, servers[0]).value : void 0;
+    if (!isRecord(first)) continue;
+    const url = first["url"];
+    if (typeof url !== "string" || url === "") continue;
+    const substituted = substituteServerVariables(url, first["variables"], context, diagnostics);
+    if (substituted === void 0) return void 0;
+    if (!isAbsoluteHttpUrl(substituted)) {
+      diagnostics.push({
+        severity: "error",
+        code: "relative-server-url",
+        operation: context.resourceId,
+        message: `Skipped ${context.where}: server URL "${substituted}" is relative, so no backend host is known. Pass --base-url`
+      });
+      return void 0;
+    }
+    return substituted;
+  }
+  diagnostics.push({
+    severity: "error",
+    code: "no-server-url",
+    operation: context.resourceId,
+    message: `Skipped ${context.where}: the document declares no server URL. Pass --base-url`
+  });
+  return void 0;
+}
+function substituteServerVariables(url, variables, context, diagnostics) {
+  if (!url.includes("{")) return url;
+  const declared = isRecord(variables) ? variables : {};
+  const used = [];
+  let missing;
+  const substituted = url.replace(/\{([^{}]*)\}/g, (match, name) => {
+    const variable = declared[name];
+    const fallback = isRecord(variable) ? variable["default"] : void 0;
+    if (typeof fallback !== "string") {
+      missing = name;
+      return match;
+    }
+    used.push(`${name}=${fallback}`);
+    return fallback;
+  });
+  if (missing !== void 0) {
+    diagnostics.push({
+      severity: "error",
+      code: "server-variable-without-default",
+      operation: context.resourceId,
+      message: `Skipped ${context.where}: server variable "{${missing}}" has no default value. Pass --base-url`
+    });
+    return void 0;
+  }
+  if (used.length > 0) {
+    diagnostics.push({
+      severity: "warning",
+      code: "server-variable-default",
+      operation: context.resourceId,
+      message: `Server URL for ${context.where} uses declared defaults (${used.join(", ")}); override with --base-url if that is not the deployment you mean`
+    });
+  }
+  return substituted;
+}
+function isAbsoluteHttpUrl(value) {
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+    return parsed.search === "" && parsed.hash === "";
+  } catch {
+    return false;
+  }
+}
+function assertAbsoluteHttpUrl(value, label) {
+  if (!isAbsoluteHttpUrl(value)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `${label} "${value}" must be an absolute http:// or https:// URL with no query string or fragment`,
+      { details: { value } }
+    );
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+// src/openapi/request.ts
+init_execution();
+
+// src/openapi/schema.ts
+init_errors();
+var SUPPORTED_TYPES = /* @__PURE__ */ new Set([
+  "object",
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "array",
+  "null"
+]);
+var METADATA_KEYWORDS = ["title", "description", "default", "example", "examples", "deprecated"];
+var ANNOTATION_KEYWORDS = /* @__PURE__ */ new Set([
+  "xml",
+  "externalDocs",
+  "readOnly",
+  "writeOnly",
+  "$schema",
+  "$id",
+  "$comment",
+  "$defs",
+  "definitions"
+]);
+function isPrimitiveSchema(schema) {
+  const types = typeList2(schema["type"]);
+  if (types === void 0) return false;
+  return types.every((type) => type !== "object" && type !== "array" && SUPPORTED_TYPES.has(type));
+}
+function convertSchema(document, node, stack = []) {
+  const dropped = /* @__PURE__ */ new Set();
+  try {
+    const schema = convertNode(document, node, stack, dropped);
+    return schema === void 0 ? { supported: false, reason: "schema could not be represented" } : { supported: true, schema, dropped: [...dropped] };
+  } catch (error) {
+    if (error instanceof UnsupportedSchema) return { supported: false, reason: error.message };
+    if (isCommerceError(error)) return { supported: false, reason: error.message };
+    throw error;
+  }
+}
+var UnsupportedSchema = class extends Error {
+};
+function convertNode(document, node, stack, dropped) {
+  if (node === true) return {};
+  if (node === false) throw new UnsupportedSchema("schema is `false`, which accepts no value");
+  const resolved = dereference(document, node, stack);
+  const source = resolved.value;
+  if (typeof source !== "object" || source === null || Array.isArray(source)) {
+    throw new UnsupportedSchema("schema node is not an object");
+  }
+  const schemaNode = source;
+  if (Array.isArray(schemaNode["allOf"])) {
+    return mergeAllOf(document, schemaNode, resolved.stack, dropped);
+  }
+  for (const keyword of ["oneOf", "anyOf", "not", "discriminator"]) {
+    if (Object.hasOwn(schemaNode, keyword)) {
+      throw new UnsupportedSchema(
+        `schema uses "${keyword}", which this gateway cannot enforce - accepting it would advertise validation that never runs`
+      );
+    }
+  }
+  const result = {};
+  const types = resolveTypes(schemaNode);
+  if (types !== void 0) result["type"] = types.length === 1 ? types[0] : types;
+  for (const keyword of METADATA_KEYWORDS) {
+    if (Object.hasOwn(schemaNode, keyword)) result[keyword] = schemaNode[keyword];
+  }
+  if (Array.isArray(schemaNode["enum"])) result["enum"] = [...schemaNode["enum"]];
+  const properties = schemaNode["properties"];
+  if (isRecord2(properties)) {
+    const converted = {};
+    for (const [name, sub] of Object.entries(properties)) {
+      const child = convertNode(document, sub, resolved.stack, dropped);
+      if (child !== void 0) converted[name] = child;
+    }
+    result["properties"] = converted;
+  }
+  const required = schemaNode["required"];
+  if (Array.isArray(required)) {
+    const names = required.filter((name) => typeof name === "string");
+    if (names.length > 0) result["required"] = names;
+  }
+  const additional = schemaNode["additionalProperties"];
+  if (typeof additional === "boolean") {
+    result["additionalProperties"] = additional;
+  } else if (additional !== void 0) {
+    const child = convertNode(document, additional, resolved.stack, dropped);
+    if (child !== void 0) result["additionalProperties"] = child;
+  } else if (isRecord2(properties)) {
+    result["additionalProperties"] = false;
+  }
+  const items = schemaNode["items"];
+  if (Array.isArray(items)) {
+    dropped.add("items (tuple form)");
+  } else if (items !== void 0) {
+    const child = convertNode(document, items, resolved.stack, dropped);
+    if (child !== void 0) result["items"] = child;
+  }
+  for (const keyword of Object.keys(schemaNode)) {
+    if (isCarriedKeyword(keyword) || ANNOTATION_KEYWORDS.has(keyword) || keyword.startsWith("x-")) {
+      continue;
+    }
+    dropped.add(keyword);
+  }
+  return result;
+}
+function isCarriedKeyword(keyword) {
+  return keyword === "type" || keyword === "properties" || keyword === "required" || keyword === "additionalProperties" || keyword === "enum" || keyword === "items" || keyword === "nullable" || keyword === "$ref" || METADATA_KEYWORDS.includes(keyword);
+}
+function resolveTypes(schema) {
+  const declared = typeList2(schema["type"]);
+  if (declared === void 0) return void 0;
+  const known = declared.filter((type) => SUPPORTED_TYPES.has(type));
+  if (known.length === 0) {
+    throw new UnsupportedSchema(`schema type "${String(schema["type"])}" is not a JSON type`);
+  }
+  if (schema["nullable"] === true && !known.includes("null")) known.push("null");
+  return known;
+}
+function typeList2(raw) {
+  if (typeof raw === "string") return [raw];
+  if (Array.isArray(raw) && raw.every((entry) => typeof entry === "string")) {
+    return raw;
+  }
+  return void 0;
+}
+function mergeAllOf(document, schema, stack, dropped) {
+  const branches = schema["allOf"];
+  const siblings = { ...schema };
+  delete siblings["allOf"];
+  const merged = { type: "object", properties: {}, required: [] };
+  const properties = merged["properties"];
+  const required = /* @__PURE__ */ new Set();
+  const parts = [...branches, ...Object.keys(siblings).length > 0 ? [siblings] : []];
+  for (const branch of parts) {
+    const converted = convertNode(document, branch, stack, dropped);
+    if (converted === void 0) throw new UnsupportedSchema("allOf branch is empty");
+    const types = typeList2(converted["type"]);
+    if (types !== void 0 && !types.includes("object")) {
+      throw new UnsupportedSchema("allOf mixes object and non-object schemas");
+    }
+    const branchProperties = converted["properties"];
+    if (isRecord2(branchProperties)) {
+      for (const [name, sub] of Object.entries(branchProperties)) {
+        const existing = properties[name];
+        if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(sub)) {
+          throw new UnsupportedSchema(
+            `allOf branches declare property "${name}" differently, which cannot be merged`
+          );
+        }
+        properties[name] = sub;
+      }
+    }
+    for (const name of Array.isArray(converted["required"]) ? converted["required"] : []) {
+      if (typeof name === "string") required.add(name);
+    }
+    for (const keyword of ["enum", "items"]) {
+      if (Object.hasOwn(converted, keyword)) {
+        throw new UnsupportedSchema(`allOf branch uses "${keyword}", which cannot be merged`);
+      }
+    }
+    if (typeof converted["description"] === "string" && merged["description"] === void 0) {
+      merged["description"] = converted["description"];
+    }
+  }
+  if (required.size > 0) merged["required"] = [...required];
+  else delete merged["required"];
+  merged["additionalProperties"] = false;
+  return merged;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/openapi/request.ts
+var PATH_GROUP = "path";
+var QUERY_GROUP = "query";
+var BODY_GROUP = "body";
+var IGNORED_HEADER_NAMES = /* @__PURE__ */ new Set(["accept", "content-type", "authorization"]);
+var UNSUPPORTED_QUERY_STYLES = /* @__PURE__ */ new Set(["deepObject", "spaceDelimited", "pipeDelimited"]);
+function mapRequest(loaded, candidate) {
+  const { document } = loaded;
+  const diagnostics = [];
+  const dropped = /* @__PURE__ */ new Set();
+  const operation = candidate.resourceId;
+  const warn = (code, message) => {
+    diagnostics.push({ severity: "warning", code, operation, message });
+  };
+  const skip = (code, message) => {
+    diagnostics.push({
+      severity: "error",
+      code,
+      operation,
+      message: `Skipped ${candidate.method} ${candidate.path}: ${message}`
+    });
+    return { supported: false, diagnostics };
+  };
+  const pathProperties = {};
+  const queryProperties = {};
+  const requiredQuery = [];
+  const templateParams = new Set(extractPathParameterNames(candidate.path));
+  for (const parameter of mergeParameters(document, candidate.parameters)) {
+    const name = typeof parameter["name"] === "string" ? parameter["name"] : void 0;
+    const location = typeof parameter["in"] === "string" ? parameter["in"] : void 0;
+    if (name === void 0 || location === void 0) continue;
+    const required2 = parameter["required"] === true || location === "path";
+    const label = `${location} parameter "${name}"`;
+    if (location === "header" || location === "cookie") {
+      if (location === "header" && IGNORED_HEADER_NAMES.has(name.toLowerCase())) continue;
+      if (required2) {
+        return skip(
+          "unsupported-required-parameter",
+          `${label} is required, and ${location} parameters are operator configuration in this release, not agent input`
+        );
+      }
+      warn(
+        "unsupported-optional-parameter",
+        `Omitted optional ${label}: ${location} parameters are not imported. Configure it under backend.headers if the API needs it`
+      );
+      continue;
+    }
+    if (location !== "path" && location !== "query") {
+      if (required2) return skip("unsupported-required-parameter", `${label} has unknown location`);
+      warn("unsupported-optional-parameter", `Omitted optional ${label}: unknown location`);
+      continue;
+    }
+    const unsupported = describeUnsupportedParameter(document, parameter, location);
+    if (unsupported !== void 0) {
+      if (required2) return skip("unsupported-required-parameter", `${label} ${unsupported}`);
+      warn("unsupported-optional-parameter", `Omitted optional ${label}: it ${unsupported}`);
+      continue;
+    }
+    const converted = convertSchema(document, parameter["schema"]);
+    if (!converted.supported) {
+      if (required2) return skip("unsupported-required-parameter", `${label} ${converted.reason}`);
+      warn("unsupported-optional-parameter", `Omitted optional ${label}: ${converted.reason}`);
+      continue;
+    }
+    for (const keyword of converted.dropped) dropped.add(keyword);
+    if (location === "path") {
+      if (!templateParams.has(name)) {
+        warn(
+          "path-parameter-not-in-template",
+          `Ignored path parameter "${name}": it does not appear in "${candidate.path}"`
+        );
+        continue;
+      }
+      pathProperties[name] = converted.schema;
+    } else {
+      queryProperties[name] = converted.schema;
+      if (required2) requiredQuery.push(name);
+    }
+  }
+  for (const param of templateParams) {
+    if (!Object.hasOwn(pathProperties, param)) {
+      return skip(
+        "undeclared-path-parameter",
+        `"{${param}}" appears in the path but is not declared as a path parameter, so a caller could never supply it`
+      );
+    }
+  }
+  const body = resolveBody(document, candidate);
+  if (body.kind === "unsupported") {
+    if (body.required) return skip("unsupported-request-body", body.reason);
+    warn("unsupported-request-body", `Omitted the request body: ${body.reason}`);
+  }
+  if (body.kind === "schema") {
+    for (const keyword of body.dropped) dropped.add(keyword);
+  }
+  const properties = {};
+  const required = [];
+  const bindings = {};
+  if (Object.keys(pathProperties).length > 0) {
+    properties[PATH_GROUP] = closedObject(pathProperties, Object.keys(pathProperties));
+    required.push(PATH_GROUP);
+    bindings.path = PATH_GROUP;
+  }
+  if (Object.keys(queryProperties).length > 0) {
+    properties[QUERY_GROUP] = closedObject(queryProperties, requiredQuery);
+    if (requiredQuery.length > 0) required.push(QUERY_GROUP);
+    bindings.query = QUERY_GROUP;
+  }
+  if (body.kind === "schema") {
+    properties[BODY_GROUP] = body.schema;
+    if (body.required) required.push(BODY_GROUP);
+    bindings.body = BODY_GROUP;
+  }
+  return {
+    supported: true,
+    inputSchema: {
+      type: "object",
+      properties,
+      ...required.length > 0 ? { required } : {},
+      additionalProperties: false
+    },
+    inputBindings: bindings,
+    ...body.kind === "schema" && body.contentType !== void 0 ? { contentType: body.contentType } : {},
+    droppedKeywords: [...dropped],
+    diagnostics
+  };
+}
+function mergeParameters(document, parameters) {
+  const byIdentity = /* @__PURE__ */ new Map();
+  for (const raw of parameters) {
+    const resolved = dereference(document, raw).value;
+    if (typeof resolved !== "object" || resolved === null || Array.isArray(resolved)) continue;
+    const parameter = resolved;
+    byIdentity.set(`${String(parameter["in"])}:${String(parameter["name"])}`, parameter);
+  }
+  return [...byIdentity.values()];
+}
+function describeUnsupportedParameter(document, parameter, location) {
+  if (parameter["content"] !== void 0) {
+    return "uses the `content` form, whose media-type serialization the gateway does not perform";
+  }
+  const style = parameter["style"];
+  if (location === "query" && typeof style === "string" && UNSUPPORTED_QUERY_STYLES.has(style)) {
+    return `uses style "${style}", which the gateway does not serialize`;
+  }
+  if (location === "path" && typeof style === "string" && style !== "simple") {
+    return `uses style "${style}"; the gateway substitutes plain values only`;
+  }
+  const converted = convertSchema(document, parameter["schema"]);
+  if (!converted.supported) return converted.reason;
+  if (!isPrimitiveSchema(converted.schema)) {
+    return "is not a primitive; object and array parameters need serialization the gateway does not perform";
+  }
+  return void 0;
+}
+function resolveBody(document, candidate) {
+  if (candidate.requestBody === void 0) return { kind: "none" };
+  const resolved = dereference(document, candidate.requestBody).value;
+  if (typeof resolved !== "object" || resolved === null || Array.isArray(resolved)) {
+    return { kind: "none" };
+  }
+  const requestBody = resolved;
+  const required = requestBody["required"] === true;
+  if (candidate.method === "GET" || candidate.method === "DELETE") {
+    return {
+      kind: "unsupported",
+      required: false,
+      reason: `a ${candidate.method} request body is not sent by the gateway`
+    };
+  }
+  const content = requestBody["content"];
+  if (!isRecord3(content)) return { kind: "none" };
+  const mediaType = pickJsonMediaType(Object.keys(content));
+  if (mediaType === void 0) {
+    return {
+      kind: "unsupported",
+      required,
+      reason: `no JSON request body content type (found: ${Object.keys(content).join(", ") || "none"}). Only application/json and application/*+json are supported - multipart and form data are never serialized as JSON`
+    };
+  }
+  const media = content[mediaType];
+  const schemaNode = isRecord3(media) ? media["schema"] : void 0;
+  if (schemaNode === void 0) {
+    return {
+      kind: "schema",
+      schema: { type: "object", additionalProperties: true },
+      required,
+      ...mediaType === "application/json" ? {} : { contentType: mediaType },
+      dropped: []
+    };
+  }
+  const converted = convertSchema(document, schemaNode);
+  if (!converted.supported) return { kind: "unsupported", required, reason: converted.reason };
+  return {
+    kind: "schema",
+    schema: converted.schema,
+    required,
+    ...mediaType === "application/json" ? {} : { contentType: mediaType },
+    dropped: converted.dropped
+  };
+}
+function pickJsonMediaType(keys) {
+  const normalised = keys.map((key) => ({ key, type: key.split(";")[0]?.trim().toLowerCase() }));
+  const exact = normalised.find((entry) => entry.type === "application/json");
+  if (exact !== void 0) return exact.key;
+  return [...normalised].sort((a, b) => (a.type ?? "").localeCompare(b.type ?? "")).find((entry) => entry.type?.startsWith("application/") && entry.type.endsWith("+json"))?.key;
+}
+function closedObject(properties, required) {
+  return {
+    type: "object",
+    properties,
+    ...required.length > 0 ? { required: [...required] } : {},
+    additionalProperties: false
+  };
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/openapi/draft.ts
+function buildResourceDrafts(loaded, options = {}) {
+  const discovery = discoverOperations(
+    loaded,
+    options.baseUrl !== void 0 ? { baseUrl: options.baseUrl } : {}
+  );
+  const diagnostics = [...discovery.diagnostics];
+  const drafts = [];
+  const wanted = options.include?.operationIds;
+  const wantedTags = options.include?.tags;
+  const matched = /* @__PURE__ */ new Set();
+  for (const candidate of discovery.operations) {
+    if (wanted !== void 0 && !selects(wanted, candidate)) continue;
+    if (wantedTags !== void 0 && !candidate.tags.some((tag) => wantedTags.includes(tag))) {
+      continue;
+    }
+    if (wanted !== void 0) {
+      for (const id of wanted) if (selects([id], candidate)) matched.add(id);
+    }
+    const mapping = mapRequest(loaded, candidate);
+    diagnostics.push(...mapping.diagnostics);
+    if (!mapping.supported) continue;
+    const dropped = new Set(mapping.droppedKeywords);
+    const output = selectOutputSchema(loaded.document, candidate, diagnostics, dropped);
+    if (dropped.size > 0) {
+      diagnostics.push({
+        severity: "warning",
+        code: "unenforced-schema-constraints",
+        operation: candidate.resourceId,
+        message: `${candidate.resourceId}: dropped ${[...dropped].join(", ")} - this gateway validates structure only, and keeping them would advertise checks it never performs`
+      });
+    }
+    const review = [];
+    if (declaresSecurity(candidate)) {
+      diagnostics.push({
+        severity: "warning",
+        code: "backend-authentication-required",
+        operation: candidate.resourceId,
+        message: `${candidate.resourceId} declares backend authentication. OpenAPI credentials were not imported. Configure backend.headers with environment placeholders before enabling the resource`
+      });
+      review.push(
+        "This operation declares backend authentication. No credential was imported.",
+        "Add it under backend.headers with an ${ENV_VAR} placeholder before enabling."
+      );
+    }
+    if (options.policy?.pricing === void 0 || options.policy.expose === void 0) {
+      review.push(
+        "REVIEW: pricing and exposure are not inferred from OpenAPI. Add e.g.",
+        '  pricing: { type: free }   # or { type: fixed, amount: "0.01", currency: USDC }',
+        "  expose: [http]           # http | mcp | a2a"
+      );
+    }
+    drafts.push({
+      id: candidate.resourceId,
+      ...candidate.operationId !== void 0 ? { operationId: candidate.operationId } : {},
+      tags: candidate.tags,
+      source: `${candidate.method} ${candidate.path}`,
+      resource: {
+        name: candidate.name,
+        ...candidate.description !== void 0 ? { description: candidate.description } : {},
+        input: mapping.inputSchema,
+        ...output !== void 0 ? { output } : {},
+        backend: {
+          type: "http",
+          method: candidate.method,
+          url: candidate.backendUrl,
+          ...mapping.contentType !== void 0 ? { headers: { "Content-Type": mapping.contentType } } : {},
+          ...Object.keys(mapping.inputBindings).length > 0 ? { inputBindings: mapping.inputBindings } : {}
+        },
+        // Policy is written only when the operator asked for it. An absent
+        // `pricing`/`expose` is what makes the draft fail config validation
+        // until a human has decided.
+        ...options.policy?.pricing !== void 0 ? { pricing: options.policy.pricing } : {},
+        ...options.policy?.expose !== void 0 ? { expose: [...options.policy.expose] } : {},
+        ...options.policy?.payments !== void 0 ? { payments: [...options.policy.payments] } : {}
+      },
+      review
+    });
+  }
+  return {
+    version: loaded.version,
+    sourcePath: loaded.sourcePath,
+    drafts,
+    diagnostics,
+    unmatchedOperationIds: (wanted ?? []).filter((id) => !matched.has(id))
+  };
+}
+function selects(ids, candidate) {
+  return ids.includes(candidate.resourceId) || candidate.operationId !== void 0 && ids.includes(candidate.operationId);
+}
+function declaresSecurity(candidate) {
+  return candidate.security.some(
+    (requirement) => typeof requirement === "object" && requirement !== null && Object.keys(requirement).length > 0
+  );
+}
+function selectOutputSchema(document, candidate, diagnostics, dropped) {
+  const responses = candidate.responses;
+  if (!isRecord4(responses)) return void 0;
+  const successes = Object.keys(responses).filter((status) => /^2\d\d$/.test(status)).sort((a, b) => rank(a) - rank(b));
+  if (successes.length === 0) return void 0;
+  const withBody = successes.filter((status) => {
+    const response2 = responses[status];
+    const content2 = isRecord4(response2) ? response2["content"] : void 0;
+    return isRecord4(content2) && pickJsonMediaType(Object.keys(content2)) !== void 0;
+  });
+  const chosen = withBody[0];
+  if (chosen === void 0) return void 0;
+  const response = responses[chosen];
+  const content = response["content"];
+  const mediaType = pickJsonMediaType(Object.keys(content));
+  const media = content[mediaType];
+  const schemaNode = isRecord4(media) ? media["schema"] : void 0;
+  if (schemaNode === void 0) return void 0;
+  const converted = convertSchema(document, schemaNode);
+  if (!converted.supported) {
+    diagnostics.push({
+      severity: "warning",
+      code: "unsupported-output-schema",
+      operation: candidate.resourceId,
+      message: `${candidate.resourceId}: omitted the output schema (${converted.reason})`
+    });
+    return void 0;
+  }
+  for (const keyword of converted.dropped) dropped.add(keyword);
+  if (withBody.length > 1) {
+    diagnostics.push({
+      severity: "warning",
+      code: "multiple-success-responses",
+      operation: candidate.resourceId,
+      message: `${candidate.resourceId}: responses ${withBody.join(", ")} all carry a JSON body; used ${chosen}`
+    });
+  }
+  return converted.schema;
+}
+function rank(status) {
+  const preferred = ["200", "201", "202"].indexOf(status);
+  return preferred === -1 ? 100 + Number(status) : preferred;
+}
+function renderResourcesYaml(result) {
+  const resources = {};
+  for (const draft of result.drafts) resources[draft.id] = draft.resource;
+  const doc = new Document({ resources });
+  doc.commentBefore = [
+    " Generated by agent-commerce import openapi. Review before use.",
+    ` Source: ${basename(result.sourcePath)} (OpenAPI ${result.version})`,
+    " Merge the resources below into config.yaml once pricing, exposure and",
+    " any backend authentication have been decided."
+  ].join("\n");
+  const map = doc.getIn(["resources"], true);
+  map?.items.forEach((item, index) => {
+    const draft = result.drafts[index];
+    const key = item.key;
+    if (draft === void 0 || draft.review.length === 0 || key === null) return;
+    key.commentBefore = draft.review.map((line) => ` ${line}`).join("\n");
+  });
+  return doc.toString({ lineWidth: 0 });
+}
+function basename(path2) {
+  return path2.split(/[\\/]/).pop() ?? path2;
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/openapi/load.ts
+init_errors();
+var MAX_SOURCE_BYTES = 10 * 1024 * 1024;
+var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".yaml", ".yml", ".json"]);
+var SUPPORTED_VERSIONS = /* @__PURE__ */ new Set(["3.0", "3.1", "3.2"]);
+function invalid2(message, details, cause) {
+  return new CommerceError("CONFIG_INVALID", message, {
+    details,
+    ...cause !== void 0 ? { cause } : {}
+  });
+}
+async function loadOpenApiDocument(sourcePath) {
+  const details = { sourcePath };
+  let stats;
+  try {
+    stats = await stat(sourcePath);
+  } catch (error) {
+    throw invalid2(`OpenAPI document "${sourcePath}" could not be read`, details, error);
+  }
+  if (stats.isDirectory()) {
+    throw invalid2(`"${sourcePath}" is a directory, not an OpenAPI document`, details);
+  }
+  if (stats.size > MAX_SOURCE_BYTES) {
+    throw invalid2(
+      `OpenAPI document "${sourcePath}" is ${stats.size} bytes, over the ${MAX_SOURCE_BYTES}-byte limit`,
+      { ...details, size: stats.size, maxBytes: MAX_SOURCE_BYTES }
+    );
+  }
+  const extension = extname(sourcePath).toLowerCase();
+  if (!SUPPORTED_EXTENSIONS.has(extension)) {
+    throw invalid2(
+      `OpenAPI document "${sourcePath}" has an unsupported extension "${extension || "(none)"}". Supported: .yaml, .yml, .json`,
+      details
+    );
+  }
+  const source = await readFile(sourcePath, "utf8");
+  if (source.trim() === "") {
+    throw invalid2(`OpenAPI document "${sourcePath}" is empty`, details);
+  }
+  let parsed;
+  try {
+    parsed = extension === ".json" ? JSON.parse(source) : parse(source);
+  } catch (error) {
+    throw invalid2(
+      `OpenAPI document "${sourcePath}" is not valid ${extension === ".json" ? "JSON" : "YAML"}: ${error instanceof Error ? error.message : String(error)}`,
+      details,
+      error
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw invalid2(`OpenAPI document "${sourcePath}" is not an object`, details);
+  }
+  const document = parsed;
+  const version = readVersion(document, sourcePath);
+  rejectExternalReferences(document, sourcePath);
+  const result = await validate(document);
+  if (!result.valid) {
+    const first = result.errors?.[0];
+    throw invalid2(
+      `OpenAPI document "${sourcePath}" is not a valid OpenAPI ${version} description: ${first ? `${first.message}${first.path ? ` (at ${first.path})` : ""}` : "unknown validation error"}`,
+      { ...details, errors: result.errors?.slice(0, 10) ?? [] }
+    );
+  }
+  return { version, document, sourcePath };
+}
+function readVersion(document, sourcePath) {
+  const details = { sourcePath };
+  if (typeof document["swagger"] === "string") {
+    throw invalid2(
+      `"${sourcePath}" is a Swagger ${document["swagger"]} document. Only OpenAPI 3.0, 3.1 and 3.2 are supported - convert it first`,
+      details
+    );
+  }
+  const declared = document["openapi"];
+  if (typeof declared !== "string") {
+    throw invalid2(`"${sourcePath}" has no "openapi" version field`, details);
+  }
+  const featureVersion = /^(\d+\.\d+)(?:\.|$)/.exec(declared)?.[1];
+  if (featureVersion === void 0 || !SUPPORTED_VERSIONS.has(featureVersion)) {
+    throw invalid2(
+      `OpenAPI version "${declared}" is not supported. Supported: 3.0.x, 3.1.x, 3.2.x`,
+      { ...details, version: declared }
+    );
+  }
+  return featureVersion;
+}
+function rejectExternalReferences(document, sourcePath) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const queue = [document];
+  while (queue.length > 0) {
+    const node = queue.pop();
+    if (typeof node !== "object" || node === null) continue;
+    if (seen.has(node)) continue;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      queue.push(...node);
+      continue;
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "$ref" && typeof value === "string" && !value.startsWith("#")) {
+        throw invalid2(
+          `OpenAPI document "${sourcePath}" contains an external reference "${value}". Only internal references (#/...) are supported; the importer performs no network or filesystem lookups`,
+          { sourcePath, ref: value }
+        );
+      }
+      queue.push(value);
+    }
+  }
+}
+
+// src/cli/commands/import-openapi.ts
+function defaultOutputPath(source) {
+  const name = basename$1(source);
+  const stem = name.slice(0, name.length - extname(name).length) || name;
+  return `${stem}.agent-commerce.yaml`;
+}
+async function runImportOpenApi(options, io, deps = {}) {
+  const fileExists = deps.fileExists ?? existsSync;
+  const outputPath = options.output ?? defaultOutputPath(options.source);
+  let policy;
+  try {
+    policy = buildPolicy(options);
+  } catch (error) {
+    io.stderr(`FAIL  ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (fileExists(outputPath) && options.force !== true) {
+    io.stderr(`FAIL  ${outputPath} already exists. Re-run with --force to overwrite.`);
+    return 1;
+  }
+  let result;
+  try {
+    const loaded = await loadOpenApiDocument(options.source);
+    result = buildResourceDrafts(loaded, {
+      ...options.baseUrl !== void 0 ? { baseUrl: options.baseUrl } : {},
+      ...Object.keys(policy).length > 0 ? { policy } : {},
+      ...options.operations !== void 0 || options.tags !== void 0 ? {
+        include: {
+          ...options.operations !== void 0 ? { operationIds: options.operations } : {},
+          ...options.tags !== void 0 ? { tags: options.tags } : {}
+        }
+      } : {}
+    });
+  } catch (error) {
+    io.stderr(`FAIL  ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  const skipped = result.diagnostics.filter((entry) => entry.severity === "error");
+  const warnings = result.diagnostics.filter((entry) => entry.severity === "warning");
+  const failures = [];
+  if (result.unmatchedOperationIds.length > 0) {
+    failures.push(`no operation matched ${result.unmatchedOperationIds.join(", ")}`);
+  }
+  if (result.drafts.length === 0) {
+    failures.push("no supported operations were imported");
+  }
+  if (options.strict === true && warnings.length > 0) {
+    failures.push(`${warnings.length} warning(s) with --strict`);
+  }
+  const wrote = failures.length === 0;
+  if (wrote) {
+    try {
+      await writeAtomically(outputPath, renderResourcesYaml(result), deps);
+    } catch (error) {
+      io.stderr(`FAIL  ${outputPath} could not be written: ${describe(error)}`);
+      return 1;
+    }
+  }
+  if (options.json === true) {
+    io.stdout(
+      JSON.stringify(
+        {
+          source: options.source,
+          openapi: result.version,
+          output: wrote ? outputPath : null,
+          imported: result.drafts.length,
+          skipped: skipped.length,
+          warnings: warnings.length,
+          resources: result.drafts.map((draft) => ({
+            id: draft.id,
+            source: draft.source,
+            ...draft.operationId !== void 0 ? { operationId: draft.operationId } : {},
+            tags: draft.tags
+          })),
+          diagnostics: result.diagnostics,
+          unmatchedOperationIds: result.unmatchedOperationIds,
+          exitCode: failures.length === 0 ? 0 : 1
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    printSummary(result, { outputPath, wrote, policy }, io);
+  }
+  for (const failure of failures) io.stderr(`FAIL  ${failure}`);
+  return failures.length === 0 ? 0 : 1;
+}
+function buildPolicy(options) {
+  const policy = {};
+  if (options.free === true) policy.pricing = { type: "free" };
+  if (options.expose !== void 0) {
+    const requested = options.expose.split(",").map((name) => name.trim()).filter((name) => name !== "");
+    if (requested.length === 0) {
+      throw new Error(`--expose needs at least one protocol (${PROTOCOL_NAMES.join(", ")})`);
+    }
+    for (const name of requested) {
+      if (!PROTOCOL_NAMES.includes(name)) {
+        throw new Error(
+          `--expose "${name}" is not a supported protocol. Supported: ${PROTOCOL_NAMES.join(", ")}`
+        );
+      }
+    }
+    policy.expose = requested;
+  }
+  return policy;
+}
+async function writeAtomically(outputPath, content, deps) {
+  if (deps.writeFile !== void 0) {
+    await deps.writeFile(outputPath, content);
+    return;
+  }
+  const target = resolve(outputPath);
+  const temporary = `${target}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, content, "utf8");
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+function printSummary(result, context, io) {
+  const skipped = result.diagnostics.filter((entry) => entry.severity === "error");
+  const warnings = result.diagnostics.filter((entry) => entry.severity === "warning");
+  io.stdout(`OpenAPI ${result.version}: ${result.sourcePath}`);
+  io.stdout("");
+  io.stdout(`Imported: ${result.drafts.length}`);
+  io.stdout(`Skipped:  ${skipped.length}`);
+  io.stdout(`Warnings: ${warnings.length}`);
+  if (skipped.length > 0) {
+    io.stdout("");
+    io.stdout("Skipped operations:");
+    for (const entry of skipped) io.stdout(`  ${entry.message}`);
+  }
+  if (warnings.length > 0) {
+    io.stdout("");
+    io.stdout("Warnings:");
+    for (const entry of warnings) io.stdout(`  ${entry.message}`);
+  }
+  if (context.wrote) {
+    io.stdout("");
+    io.stdout("Generated:");
+    io.stdout(`  ${context.outputPath}`);
+  }
+  io.stdout("");
+  if (context.policy.pricing === void 0 || context.policy.expose === void 0) {
+    io.stdout("Pricing/exposure were not inferred.");
+  }
+  io.stdout("Review the generated resources before merging them into config.yaml.");
+}
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/cli/commands/init.ts
 init_filename();
 
@@ -2770,7 +3971,7 @@ var processIo = {
 // src/cli/program.ts
 function buildProgram(io = processIo) {
   const program = new Command();
-  program.name("agent-commerce").description("CLI for the Agent Commerce Gateway: init, validate, doctor, demo.").version(readVersionReport().cliVersion, "-v, --version", "Print the CLI version.").exitOverride().configureOutput({
+  program.name("agent-commerce").description("CLI for the Agent Commerce Gateway: init, import, validate, doctor, demo.").version(readVersionReport().cliVersion, "-v, --version", "Print the CLI version.").exitOverride().configureOutput({
     writeOut: (str) => io.stdout(str.replace(/\n+$/, "")),
     writeErr: (str) => io.stderr(str.replace(/\n+$/, ""))
   });
@@ -2799,6 +4000,31 @@ function buildProgram(io = processIo) {
     const code = await runInit({ outputPath: opts.output, force: opts.force, yes: opts.yes }, io);
     process.exitCode = code;
   });
+  const importCommand = program.command("import").description("Generate Agent Commerce resource drafts from an API description.");
+  importCommand.command("openapi").description("Convert a local OpenAPI 3.0/3.1/3.2 document into resource drafts.").argument("<source>", "path to a local .yaml, .yml or .json OpenAPI document").option("--output <path>", "output path (default: <source>.agent-commerce.yaml)").option("--force", "overwrite an existing output file", false).option("--base-url <url>", "backend base URL, overriding the document servers").option(
+    "--operation <operationId>",
+    "import only this operation (repeatable)",
+    collect,
+    void 0
+  ).option("--tag <tag>", "import only operations with this tag (repeatable, OR-ed)", collect).option("--free", "mark generated resources as pricing.type free", false).option("--expose <protocols>", `comma-separated: ${PROTOCOL_NAMES.join(",")}`).option("--strict", "exit non-zero when the import produced warnings", false).option("--json", "emit a machine-readable summary instead of a report", false).action(
+    async (source, opts) => {
+      process.exitCode = await runImportOpenApi(
+        {
+          source,
+          ...opts.output !== void 0 ? { output: opts.output } : {},
+          force: opts.force,
+          ...opts.baseUrl !== void 0 ? { baseUrl: opts.baseUrl } : {},
+          ...opts.operation !== void 0 ? { operations: opts.operation } : {},
+          ...opts.tag !== void 0 ? { tags: opts.tag } : {},
+          free: opts.free,
+          ...opts.expose !== void 0 ? { expose: opts.expose } : {},
+          strict: opts.strict,
+          json: opts.json
+        },
+        io
+      );
+    }
+  );
   program.command("demo").description(
     "Run the documented docker compose + demo agent quickstart, verifying health between steps."
   ).action(async () => {
@@ -2806,6 +4032,9 @@ function buildProgram(io = processIo) {
   });
   return program;
 }
+function collect(value, previous) {
+  return [...previous ?? [], value];
+}
 
 // src/cli/index.ts
 for (const stream of [process.stdout, process.stderr]) {