apps 0.0.1-beta.25 → 0.0.1-beta.26

package/js/openapi.js

@@ -8,20 +8,25 @@ import {
 import {
   protocolOperations,
   protocolRouter
-} from "./chunk-K3MQX2KO.js";
+} from "./chunk-OI7OI2U3.js";
 import {
+  OpenapiCompileError,
+  OpenapiCompileErrorCode,
   OpenapiError,
   OpenapiErrorResponse,
   OpenapiOperation,
   OpenapiParameter,
   OpenapiRequestBody,
+  OpenapiSkippedOperation,
   OpenapiToolsOptions,
   defaultOpenapiResponseLimits,
   isOpenapiFileSchema,
+  isOpenapiJsonSequence,
+  isOpenapiReadMethod,
   isOpenapiTextMedia,
   openapiBinaryResultSchema,
   openapiMediaKind
-} from "./chunk-J3RUZMLO.js";
+} from "./chunk-EXDR4HVM.js";
 import "./chunk-PC5RHPUP.js";
 import {
   fromPromise,
@@ -68,9 +73,11 @@ import {
   Duration_exports,
   Effect_exports,
   Encoding_exports,
+  Exit_exports,
   JsonPointer_exports,
   JsonSchema_exports,
   Option_exports,
+  SchemaIssue_exports,
   Schema_exports,
   Stream_exports
 } from "./chunk-DM5U7G7V.js";
@@ -189,6 +196,18 @@ function operationPath(op) {
   return new RegExp("^" + pattern + "$");
 }
 var bytes = (value) => Uint8Array.from(atob(scalar(value)), (char) => char.charCodeAt(0));
+function querystringValue(parameter, value) {
+  const [media] = Object.keys(parameter.content ?? {});
+  if (media === void 0) throw new Error("A querystring parameter declares no media type");
+  const kind = openapiMediaKind(media);
+  if (kind === "form") {
+    const form = new URLSearchParams();
+    for (const [name, field] of Object.entries(object(value)))
+      for (const item of Array.isArray(field) ? field : [field]) form.append(name, scalar(item));
+    return form.toString();
+  }
+  return encodeURIComponent(kind === "json" ? JSON.stringify(value) : scalar(value));
+}
 function createRequest(config) {
   const { methods, oauth } = config;
   function selectedCredentials(op, account) {
@@ -229,6 +248,7 @@ function createRequest(config) {
             throw new Error("The selected account cannot call this tool");
           const parameters = {};
           let path = op.path;
+          const querystrings = [];
           const swaggerParameters = op.request.parameters.filter((p) => {
             const group = args[p.in === "header" ? "headers" : p.in];
             const value = group === void 0 ? void 0 : object(group)[p.name];
@@ -237,6 +257,12 @@ function createRequest(config) {
               path = path.replaceAll(`{${p.name}}`, reservedPathValue(value));
               return false;
             }
+            if (p.in === "querystring") {
+              if (value !== void 0) querystrings.push(querystringValue(p, value));
+              else if (p.required === true)
+                throw new Error("A required querystring parameter is missing");
+              return false;
+            }
             if (group !== void 0) parameters[`${p.in}.${p.name}`] = value;
             return true;
           });
@@ -288,6 +314,8 @@ function createRequest(config) {
           if (pathname.split("/").some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment)))
             throw new Error("This path value would change the request path");
           const url = new URL(prepared2.url);
+          if (querystrings.length > 0)
+            url.search = [url.search.slice(1), ...querystrings].filter((part) => part !== "").join("&");
           const origin = new URL(op.baseUrl).origin;
           if (url.origin !== origin || !operationPath(op).test(url.pathname) || url.username || url.password)
             throw new Error("The request escaped its API operation");
@@ -337,7 +365,7 @@ function createRequest(config) {
       if (!isOpenapiTextMedia(contentType))
         return { base64: Encoding_exports.encodeBase64(data), contentType };
       const text = new TextDecoder().decode(data);
-      return contentType.includes("json") && !contentType.includes("ndjson") ? yield* Schema_exports.decodeUnknownEffect(Schema_exports.fromJsonString(Schema_exports.Json))(text) : text;
+      return contentType.includes("json") && !isOpenapiJsonSequence(contentType) ? yield* Schema_exports.decodeUnknownEffect(Schema_exports.fromJsonString(Schema_exports.Json))(text) : text;
     })
   ).pipe(
     Effect_exports.withSpan("provider.openapi.call", {
@@ -477,7 +505,7 @@ var openapiToolsEffect = (options, prepared) => Effect_exports.gen(function* ()
       const { input, errors } = schemas;
       const tool = {
         description: op.description,
-        readOnly: ["GET", "HEAD", "OPTIONS"].includes(op.method),
+        readOnly: isOpenapiReadMethod(op.method),
         input,
         run: (_context, value) => Schema_exports.decodeUnknownEffect(input)(
           fillParameterDefaults(op, config.parameterDefaults, value)
@@ -505,43 +533,6 @@ var openapiToolsEffect = (options, prepared) => Effect_exports.gen(function* ()
   return Object.fromEntries(entries);
 });
 
-// src/contracts/openapi-compile.ts
-var OpenapiCompileErrorCode = Schema_exports.Literals([
-  "server_protocol",
-  "server_url",
-  "external_reference",
-  "circular_reference",
-  "schema_keyword",
-  "schema_reference",
-  "missing_component",
-  "openapi_version",
-  "auth_helper",
-  "auth_missing",
-  "operation_path",
-  "duplicate_operation",
-  "server_missing",
-  "multiple_hosts",
-  "parameter_encoding",
-  "parameter_style",
-  "request_body",
-  "combined_oauth",
-  "auth_method",
-  "input_schema",
-  "no_operations",
-  "no_supported_operations",
-  "invalid_document",
-  "source_generation",
-  "authoring_reference"
-]);
-var OpenapiCompileError = class extends Schema_exports.TaggedError()(
-  "OpenapiCompileError",
-  {
-    code: OpenapiCompileErrorCode,
-    reason: Schema_exports.String
-  }
-) {
-};
-
 // ../../node_modules/.bun/js-yaml@5.4.2/node_modules/js-yaml/dist/js-yaml.mjs
 var NOT_RESOLVED = /* @__PURE__ */ Symbol("NOT_RESOLVED");
 function defineScalarTag(tagName, options) {
@@ -3908,7 +3899,8 @@ var yieldToRuntime = () => new Promise((resolve) => setTimeout(resolve, 0));
 
 // src/implementation/openapi-document.ts
 var DocumentObject = Schema_exports.declare(
-  (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+  (value) => typeof value === "object" && value !== null && !Array.isArray(value),
+  { expected: "object" }
 );
 var documentObject = Schema_exports.decodeUnknownSync(DocumentObject);
 var record = documentObject;
@@ -3916,6 +3908,79 @@ function fail(code, reason) {
   throw new OpenapiCompileError({ code, reason });
 }
 var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var pointerToken = (key) => key.replaceAll("~", "~0").replaceAll("/", "~1");
+var issueFormat = SchemaIssue_exports.makeFormatterStandardSchemaV1({
+  leafHook: (issue) => SchemaIssue_exports.hasInput(issue) ? "Invalid value" : SchemaIssue_exports.defaultLeafHook(issue),
+  checkHook: (issue) => SchemaIssue_exports.hasInput(issue) || SchemaIssue_exports.hasInput(issue.issue) ? SchemaIssue_exports.defaultCheckHook(issue) ?? "Invalid value" : SchemaIssue_exports.defaultCheckHook(issue)
+});
+var decodeDefinition = (schema2, value, at, what) => {
+  try {
+    return Schema_exports.decodeUnknownSync(schema2)(value);
+  } catch (error) {
+    if (!Schema_exports.isSchemaError(error)) throw error;
+    const [issue] = issueFormat(error.issue).issues;
+    const path = (issue?.path ?? []).map(
+      (key) => pointerToken(String(typeof key === "object" ? key.key : key))
+    );
+    return fail(
+      "invalid_document",
+      `The ${what} at ${[at, ...path].join("/")} is invalid: ${issue?.message ?? "it does not match OpenAPI"}.`
+    );
+  }
+};
+var schemaKeywords = /* @__PURE__ */ new Set([
+  "items",
+  "additionalProperties",
+  "not",
+  "if",
+  "then",
+  "else",
+  "contains",
+  "propertyNames",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+  "contentSchema"
+]);
+var schemaArrayKeywords = /* @__PURE__ */ new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+var schemaMapKeywords = /* @__PURE__ */ new Set(["properties", "patternProperties", "$defs", "dependentSchemas"]);
+var isSchemaValue = (value) => typeof value === "boolean" || isObject2(value);
+var jsonKind = (value) => Array.isArray(value) ? "an array" : value === null ? "null" : typeof value === "object" ? "an object" : `a ${typeof value}`;
+var holdsReference = (value) => Array.isArray(value) ? value.some(holdsReference) : isObject2(value) && (typeof value.$ref === "string" || Object.values(value).some(holdsReference));
+var checkSchemaKeywords = (schema2, at) => {
+  const path = [];
+  const child = (value, problem) => {
+    if (isSchemaValue(value)) return visit(value);
+    if (holdsReference(value))
+      fail(
+        "schema_keyword",
+        `The schema at ${[at, ...path].join("/")} is invalid: ${problem()}, so the reference inside it cannot be resolved.`
+      );
+  };
+  const visit = (node) => {
+    if (!isObject2(node)) return;
+    for (const [key, value] of Object.entries(node)) {
+      path.push(pointerToken(key));
+      if (schemaKeywords.has(key))
+        child(value, () => `"${key}" must be a schema, not ${jsonKind(value)}`);
+      else if (schemaArrayKeywords.has(key) || schemaMapKeywords.has(key)) {
+        const entries = schemaArrayKeywords.has(key) ? Array.isArray(value) ? [...value.entries()] : void 0 : isObject2(value) ? Object.entries(value) : void 0;
+        if (entries === void 0)
+          child(
+            value,
+            () => schemaArrayKeywords.has(key) ? `"${key}" must be an array of schemas, not ${jsonKind(value)}` : `"${key}" must map names to schemas, not ${jsonKind(value)}`
+          );
+        else
+          for (const [name, item] of entries) {
+            path.push(pointerToken(String(name)));
+            child(item, () => `each "${key}" entry must be a schema, not ${jsonKind(item)}`);
+            path.pop();
+          }
+      }
+      path.pop();
+    }
+  };
+  visit(schema2);
+};
 var pathItemMaps = /* @__PURE__ */ new Set(["paths", "webhooks", "pathItems"]);
 var localPath = (ref) => {
   if (!ref.startsWith("#")) return void 0;
@@ -3931,6 +3996,7 @@ var localPath = (ref) => {
 };
 function dereference(scope) {
   const active = /* @__PURE__ */ new Set();
+  const origins = /* @__PURE__ */ new WeakMap();
   const target = (ref) => {
     const path = localPath(ref);
     let node = scope;
@@ -3964,14 +4030,15 @@ function dereference(scope) {
     active.delete(ref);
     if (!isObject2(resolved2)) return resolved2;
     const { $ref: _, ...siblings } = value;
-    if (pathItem) return { ...resolved2, ...fields(siblings) };
-    return {
+    const result = pathItem ? { ...resolved2, ...fields(siblings) } : {
       ...resolved2,
       ...typeof siblings.summary === "string" ? { summary: siblings.summary } : {},
       ...typeof siblings.description === "string" ? { description: siblings.description } : {}
     };
+    origins.set(result, ref);
+    return result;
   };
-  return record(visit(scope, false));
+  return { document: record(visit(scope, false)), origins };
 }
 var DocumentSpecification = Schema_exports.Struct({
   ...Specification.fields,
@@ -3983,29 +4050,99 @@ var DocumentSpecification = Schema_exports.Struct({
     })
   )
 });
+var MediaTypes = Schema_exports.Array(Schema_exports.String);
+var Swagger2Parameters = Schema_exports.Array(DocumentObject);
+var Swagger2Operation = Schema_exports.Struct({
+  parameters: Schema_exports.optionalKey(Swagger2Parameters),
+  consumes: Schema_exports.optionalKey(MediaTypes),
+  produces: Schema_exports.optionalKey(MediaTypes),
+  responses: Schema_exports.optionalKey(DocumentObject)
+});
+var Swagger2PathItem = Schema_exports.Struct({
+  parameters: Schema_exports.optionalKey(Swagger2Parameters),
+  get: Schema_exports.optionalKey(Swagger2Operation),
+  put: Schema_exports.optionalKey(Swagger2Operation),
+  post: Schema_exports.optionalKey(Swagger2Operation),
+  delete: Schema_exports.optionalKey(Swagger2Operation),
+  options: Schema_exports.optionalKey(Swagger2Operation),
+  head: Schema_exports.optionalKey(Swagger2Operation),
+  patch: Schema_exports.optionalKey(Swagger2Operation)
+});
+var Swagger2Definition = Schema_exports.Struct({
+  paths: Schema_exports.optionalKey(DocumentObject),
+  consumes: Schema_exports.optionalKey(MediaTypes),
+  produces: Schema_exports.optionalKey(MediaTypes),
+  securityDefinitions: Schema_exports.optionalKey(Schema_exports.Record(Schema_exports.String, DocumentObject))
+});
+var swagger2Methods = ["get", "put", "post", "delete", "options", "head", "patch"];
+function checkSwagger2(document) {
+  const definition = decodeDefinition(Swagger2Definition, document, "#", "definition");
+  for (const [path, value] of Object.entries(definition.paths ?? {})) {
+    if (!path.startsWith("/")) continue;
+    const itemAt = `#/paths/${pointerToken(path)}`;
+    const item = decodeDefinition(Swagger2PathItem, value, itemAt, "path item");
+    for (const method of swagger2Methods)
+      for (const [status, response] of Object.entries(item[method]?.responses ?? {}))
+        if (!status.startsWith("x-"))
+          decodeDefinition(
+            DocumentObject,
+            response,
+            `${itemAt}/${method}/responses/${pointerToken(status)}`,
+            "response"
+          );
+  }
+}
 function upgradeOwned(document) {
-  return record(upgradeOpenApi30InPlace(record(upgradeFromTwoToThree(document))));
+  if (typeof document.swagger === "string" && document.swagger.startsWith("2.0"))
+    checkSwagger2(document);
+  let upgraded;
+  try {
+    upgraded = upgradeFromTwoToThree(document);
+  } catch (error) {
+    if (!(error instanceof TypeError)) throw error;
+    return fail(
+      "invalid_document",
+      "The Swagger 2.0 definition could not be converted to OpenAPI 3.0: part of it does not have the structure Swagger 2.0 requires, such as a null entry in a path item or response map."
+    );
+  }
+  return record(upgradeOpenApi30InPlace(record(upgraded)));
 }
+var supportedVersion = /^3\.[12]\.\d+$/;
 async function openApiDocument(input) {
   const root = upgradeOwned(record(input));
   await yieldToRuntime();
-  const spec = Schema_exports.decodeUnknownSync(DocumentSpecification)(root);
-  if (!spec.openapi.startsWith("3.1."))
-    fail("openapi_version", "This importer supports Swagger 2.0 and OpenAPI 3.0 and 3.1.");
+  const spec = decodeDefinition(DocumentSpecification, root, "#", "definition");
+  if (!supportedVersion.test(spec.openapi))
+    fail(
+      "openapi_version",
+      `This importer supports Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2, not openapi ${JSON.stringify(spec.openapi.slice(0, 32))}.`
+    );
   const components = spec.components?.schemas ?? {};
   const convert = JsonSchema_exports.fromSchemaOpenApi3_1;
   const componentsObject = root.components === void 0 ? {} : record(root.components);
-  const restored = dereference({ ...root, components: { ...componentsObject, schemas: {} } });
-  await yieldToRuntime();
-  const parsed = Schema_exports.decodeUnknownSync(DocumentSpecification)({
-    ...restored,
-    components: { ...record(restored.components), schemas: components }
+  const { document: restored, origins } = dereference({
+    ...root,
+    components: { ...componentsObject, schemas: {} }
   });
+  await yieldToRuntime();
+  const parsed = decodeDefinition(
+    DocumentSpecification,
+    { ...restored, components: { ...record(restored.components), schemas: components } },
+    "#",
+    "definition"
+  );
   const definitions = /* @__PURE__ */ new Map();
   const references2 = /* @__PURE__ */ new Map();
   return {
     spec: parsed,
     definitions,
+    /**
+     * The JSON Pointer of the object a local reference resolved to, so a diagnostic can locate
+     * a resolved Response, Parameter, Request Body or Path Item where the definition declares it.
+     */
+    origin(value) {
+      return isObject2(value) ? origins.get(value) : void 0;
+    },
     /** Inspect a component schema without expanding its children. OpenAPI object refs must already be resolved by Swagger. */
     resolve(value) {
       const visited = /* @__PURE__ */ new Set();
@@ -4013,53 +4150,88 @@ async function openApiDocument(input) {
         const ref = value.$ref;
         const path = typeof ref === "string" ? JsonPointer_exports.parseUriFragment(ref) : void 0;
         if (typeof ref !== "string" || path?.length !== 3 || path[0] !== "components" || path[1] !== "schemas" || path[2] === void 0)
-          fail("external_reference", "An OpenAPI object reference could not be resolved locally.");
+          fail(
+            "external_reference",
+            `The reference ${JSON.stringify(ref)} does not resolve within the definition. Only local references to objects the definition declares are supported.`
+          );
         if (visited.has(ref))
-          fail("circular_reference", "A circular schema alias cannot be imported.");
+          fail("circular_reference", `The schema ${ref} is a circular alias of itself.`);
         visited.add(ref);
-        value = record(Object.hasOwn(components, path[2]) ? components[path[2]] : void 0);
+        if (!Object.hasOwn(components, path[2]))
+          fail(
+            "missing_component",
+            `The reference ${ref} names a schema the definition does not declare.`
+          );
+        value = record(components[path[2]]);
       }
       return value;
     },
     /** Compose a Draft 2020-12 schema around API Schema Objects. Only values passed to
      * `api` use the document's OpenAPI dialect; Executor-authored wrappers are already
-     * Draft 2020-12 and must not be reinterpreted. Reached components are converted once into
-     * the shared `definitions` and stay references here; nothing is inlined or copied per operation.
+     * Draft 2020-12 and must not be reinterpreted. `api` takes the schema's JSON Pointer in the
+     * definition, which failures name. Reached components are converted once into the shared
+     * `definitions` and stay references here; nothing is inlined or copied per operation.
      */
     schema(build) {
       const added = [];
       const direct = /* @__PURE__ */ new Set();
       const local = {};
-      const visit = (input2, direct2) => {
-        const document = convert(input2, {
-          onReference(ref) {
-            const path = JsonPointer_exports.parseUriFragment(ref);
-            const name = path?.[2];
-            if (path?.length !== 3 || path[0] !== "components" || path[1] !== "schemas" || name === void 0)
-              fail("schema_reference", "Only local component schema references are supported.");
-            const component = Object.hasOwn(components, name) ? components[name] : void 0;
-            if (component === void 0)
-              fail("missing_component", "An API schema references a missing component.");
-            direct2.add(name);
-            if (!definitions.has(name)) {
-              added.push(name);
-              definitions.set(name, {});
-              const names = /* @__PURE__ */ new Set();
-              definitions.set(name, visit(component, names));
-              references2.set(name, names);
+      const visit = (input2, direct2, at) => {
+        checkSchemaKeywords(input2, at);
+        let document;
+        try {
+          document = convert(input2, {
+            onReference(ref) {
+              const path = JsonPointer_exports.parseUriFragment(ref);
+              const name = path?.[2];
+              if (path?.length !== 3 || path[0] !== "components" || path[1] !== "schemas" || name === void 0)
+                fail(
+                  "schema_reference",
+                  `The schema at ${at} references ${JSON.stringify(ref)}. Only references to #/components/schemas/<name> are supported.`
+                );
+              const component = Object.hasOwn(components, name) ? components[name] : void 0;
+              if (component === void 0)
+                fail(
+                  "missing_component",
+                  `The schema at ${at} references ${ref}, which the definition does not declare.`
+                );
+              direct2.add(name);
+              if (!definitions.has(name)) {
+                added.push(name);
+                definitions.set(name, {});
+                const names = /* @__PURE__ */ new Set();
+                definitions.set(
+                  name,
+                  visit(component, names, `#/components/schemas/${pointerToken(name)}`)
+                );
+                references2.set(name, names);
+              }
             }
-          }
-        });
+          });
+        } catch (error) {
+          if (error instanceof OpenapiCompileError) throw error;
+          return fail(
+            "schema_keyword",
+            `The schema at ${at} cannot be converted to JSON Schema 2020-12 without changing its constraints${error instanceof Error ? `: ${error.message}` : ""}.`
+          );
+        }
         return record({
           ...document.schema,
           ...Object.keys(document.definitions).length ? { $defs: document.definitions } : {}
         });
       };
-      const api = (input2) => {
-        const { $defs, ...converted } = visit(record(input2), direct);
+      const api = (input2, at) => {
+        const schema2 = input2 === true ? {} : input2 === false ? { not: {} } : isObject2(input2) ? input2 : fail(
+          "schema_keyword",
+          `The schema at ${at} must be a schema, not ${jsonKind(input2)}.`
+        );
+        const { $defs, ...converted } = visit(schema2, direct, at);
         for (const [name, definition] of Object.entries($defs === void 0 ? {} : record($defs))) {
           if (Object.hasOwn(local, name) && JSON.stringify(local[name]) !== JSON.stringify(definition))
-            fail("schema_reference", "An API schema has conflicting local definitions.");
+            fail(
+              "schema_reference",
+              `The schema at ${at} declares the local definition ${JSON.stringify(name)} differently from another schema of the same operation.`
+            );
           local[name] = definition;
         }
         return converted;
@@ -4074,10 +4246,11 @@ async function openApiDocument(input) {
             reached.add(name);
             pending.push(...references2.get(name) ?? []);
           }
-          if ([...reached].some((name) => Object.hasOwn(local, name)))
+          const shared = [...reached].find((name) => Object.hasOwn(local, name));
+          if (shared !== void 0)
             fail(
               "schema_reference",
-              "An API schema has conflicting local and component definitions."
+              `A local definition named ${JSON.stringify(shared)} conflicts with the component schema of the same name.`
             );
         }
         return {
@@ -4090,11 +4263,7 @@ async function openApiDocument(input) {
           definitions.delete(name);
           references2.delete(name);
         }
-        if (error instanceof OpenapiCompileError) throw error;
-        return fail(
-          "schema_keyword",
-          "An API schema cannot be converted without changing its constraints."
-        );
+        throw error;
       }
     }
   };
@@ -4130,6 +4299,15 @@ var leafOf = (input, group) => {
   const leaf = camel(seed);
   return leaf === "" || leaf === group ? fallbackLeaf(input, group) : leaf;
 };
+var pathTokens = (path) => segments(path).flatMap((segment) => {
+  if (version.test(segment) || segment.toLowerCase() === "api") return [];
+  const parameter = segment.startsWith("{") && segment.endsWith("}");
+  const word = camel(parameter ? segment.slice(1, -1) : segment);
+  return word === "" ? [] : [{ key: `${parameter ? "{" : ""}${word}`, word, parameter }];
+});
+var describePath = (tokens) => tokens.map(
+  (token, index) => token.parameter ? `${tokens[index - 1]?.parameter === true ? "And" : "By"}${pascal(token.word)}` : pascal(token.word)
+).join("");
 var hash = (input) => {
   const text = JSON.stringify([input.method.toUpperCase(), input.path, input.operationId ?? null]);
   let value = 0;
@@ -4142,18 +4320,30 @@ var planOperationNames = (inputs) => {
     const leaf = leafOf(input, group);
     const versionSegment = segments(input.path).map((segment) => segment.toLowerCase()).find((segment) => version.test(segment));
     const prefix = versionSegment === void 0 ? group : `${group}.${camel(versionSegment)}`;
-    return { input, group, leaf, prefix, versionSegment, name: `${group}.${leaf}` };
+    const tokens = pathTokens(input.path);
+    return { input, group, leaf, prefix, versionSegment, tokens, name: `${group}.${leaf}` };
   });
   const refine = (rename) => {
     const buckets = /* @__PURE__ */ new Map();
     for (const item of staged) buckets.set(item.name, [...buckets.get(item.name) ?? [], item]);
     for (const bucket of buckets.values())
-      if (bucket.length > 1) for (const item of bucket) item.name = rename(item);
+      if (bucket.length > 1) {
+        const names = bucket.map((item) => rename(item, bucket));
+        for (const [index, item] of bucket.entries()) item.name = names[index] ?? item.name;
+      }
   };
   refine((item) => item.versionSegment === void 0 ? item.name : `${item.prefix}.${item.leaf}`);
+  refine((item, bucket) => {
+    const shared = new Set(
+      item.tokens.map((token) => token.key).filter((key) => bucket.every((other) => other.tokens.some((token) => token.key === key)))
+    );
+    const distinct = item.tokens.filter((token) => !shared.has(token.key));
+    return distinct.length === 0 ? item.name : `${item.prefix}.${item.leaf}${describePath(distinct)}`;
+  });
+  refine((item) => `${item.prefix}.${item.leaf}${describePath(item.tokens)}`);
   refine((item) => `${item.prefix}.${item.leaf}${pascal(item.input.method)}`);
   refine((item) => `${item.prefix}.${item.leaf}${pascal(item.input.method)}${hash(item.input)}`);
-  return staged.map((item) => item.name);
+  return staged.map((item) => ({ ...item.input, name: item.name }));
 };
 
 // src/implementation/openapi-compile.ts
@@ -4166,12 +4356,25 @@ var OperationNaming = Schema_exports.Struct({
   tags: Schema_exports.optionalKey(Schema_exports.Array(Schema_exports.String))
 });
 var identifier = (name) => name.replace(/[^a-zA-Z0-9_]/g, "_");
+function parseUrl(value, base) {
+  try {
+    return new URL(value, base);
+  } catch {
+    return fail2(
+      "server_url",
+      base === void 0 && !/^[a-z][a-z0-9+.-]*:/i.test(value) ? "The server URL is relative, and an inline definition has no URL to resolve it against. Set baseUrl." : "The server URL is not a valid URL. Set baseUrl."
+    );
+  }
+}
 function absolute(value) {
-  const url = new URL(value);
+  const url = parseUrl(value);
   if (url.protocol !== "https:" && url.protocol !== "http:")
-    fail2("server_protocol", "Only HTTP APIs can be imported.");
+    fail2("server_protocol", `The server uses ${url.protocol}; only HTTP APIs can be imported.`);
   if (url.username || url.password || url.hash || url.search || /[{}]/.test(value))
-    fail2("server_url", "This API needs a configured server URL before import.");
+    fail2(
+      "server_url",
+      "The server URL has credentials, a query, a fragment or unresolved variables. Set baseUrl."
+    );
   return url.href.replace(/\/$/, "");
 }
 function serverAddress(server, connectUrl, documentServer) {
@@ -4196,16 +4399,19 @@ function serverAddress(server, connectUrl, documentServer) {
   }
   const relative = new URL(template, "https://relative.invalid");
   const base = url?.protocol && url.host ? `${url.protocol.replace(/\W/g, "")}://${url.host}${url.pathname}` : url?.pathname ?? (template.startsWith("/") ? relative.pathname : relative.pathname.slice(1));
-  return absolute(new URL(`${base.endsWith("/") ? base.slice(0, -1) : base}/`, connectUrl).href);
+  return absolute(parseUrl(`${base.endsWith("/") ? base.slice(0, -1) : base}/`, connectUrl).href);
 }
 var binaryInput = {
   type: "string",
   description: "File bytes encoded as base64.",
   contentEncoding: "base64"
 };
-function responseSchema(document, operation, method) {
+var declaredAt = (document, value, inline) => document.origin(value) ?? inline;
+var mediaSchemaAt = (document, at, type, media) => `${declaredAt(document, media, `${at}/content/${pointerToken(type)}`)}/schema`;
+var responsesOf = (operation) => operation.responses === void 0 ? {} : record2(operation.responses);
+function responseSchema(document, operation, at, method) {
   if (method === "HEAD") return { type: "null" };
-  const success = Object.entries(operation.responses ?? {}).filter(
+  const success = Object.entries(responsesOf(operation)).filter(
     ([status]) => /^2(?:[0-9]{2}|XX)$/i.test(status)
   );
   if (success.length === 0) return void 0;
@@ -4215,12 +4421,13 @@ function responseSchema(document, operation, method) {
       shapes.push(() => ({ type: "null" }));
       continue;
     }
-    const content = document.resolve(response).content;
+    const responseAt = declaredAt(document, response, `${at}/responses/${pointerToken(status)}`);
+    const content = document.resolve(record2(response)).content;
     if (content === void 0) return void 0;
     const media = Object.entries(record2(content));
     if (media.length === 0) return void 0;
     for (const [type, body] of media) {
-      if (!type.includes("json")) {
+      if (!type.includes("json") || isOpenapiJsonSequence(type)) {
         shapes.push(
           () => isOpenapiTextMedia(type) ? { type: "string" } : openapiBinaryResultSchema
         );
@@ -4228,7 +4435,8 @@ function responseSchema(document, operation, method) {
       }
       const schema2 = record2(body).schema;
       if (schema2 === void 0) return void 0;
-      shapes.push((api) => api(schema2));
+      const schemaAt = mediaSchemaAt(document, responseAt, type, body);
+      shapes.push((api) => api(schema2, schemaAt));
     }
   }
   return document.schema((api) => ({
@@ -4251,14 +4459,14 @@ function errorContent(document, response) {
     return void 0;
   }
 }
-function errorResponses(document, operation) {
+function errorResponses(document, operation, at) {
   const errors = [];
   const tagged = Schema_exports.Struct({
     description: Schema_exports.optionalKey(Schema_exports.String),
     required: Schema_exports.Array(Schema_exports.String),
     properties: Schema_exports.Record(Schema_exports.String, JsonObject)
   });
-  const visit = (status, input, visited = /* @__PURE__ */ new Set(), parents = []) => {
+  const visit = (status, input, schemaAt, visited = /* @__PURE__ */ new Set(), parents = []) => {
     const object2 = Schema_exports.decodeUnknownOption(JsonObject)(input);
     if (Option_exports.isNone(object2)) return;
     const value = object2.value;
@@ -4266,9 +4474,14 @@ function errorResponses(document, operation) {
       if (typeof value.$ref === "string" && visited.has(value.$ref)) return;
       const next = typeof value.$ref === "string" ? /* @__PURE__ */ new Set([...visited, value.$ref]) : visited;
       const shape = document.resolve(value);
+      const shapeAt = typeof value.$ref === "string" && value.$ref.startsWith("#/") ? value.$ref : schemaAt;
       const variants = shape.anyOf;
       if (Array.isArray(variants)) {
-        for (const variant of variants) visit(status, variant, next, [...parents, value]);
+        for (const [index, variant] of variants.entries())
+          visit(status, variant, `${shapeAt}/anyOf/${index}`, next, [
+            ...parents,
+            { schema: value, at: schemaAt }
+          ]);
         return;
       }
       const parsed = Schema_exports.decodeUnknownOption(tagged)(shape);
@@ -4283,26 +4496,49 @@ function errorResponses(document, operation) {
         code,
         status,
         message: hasMessage ? { source: "body" } : { source: "schema", value: parsed.value.description },
-        schema: document.schema((api) => ({ allOf: [...parents, value].map(api) }))
+        schema: document.schema((api) => ({
+          allOf: [...parents, { schema: value, at: schemaAt }].map(
+            (part) => api(part.schema, part.at)
+          )
+        }))
       });
       if (Option_exports.isSome(declaration)) errors.push(declaration.value);
     } catch (error) {
       if (!(error instanceof OpenapiCompileError) && !Schema_exports.isSchemaError(error)) throw error;
     }
   };
-  for (const [status, response] of Object.entries(operation.responses ?? {})) {
+  for (const [status, response] of Object.entries(responsesOf(operation))) {
     if (!/^[45][0-9]{2}$/.test(status)) continue;
-    const content = errorContent(document, response);
+    const content = errorContent(document, record2(response));
     if (content === void 0) continue;
+    const responseAt = declaredAt(document, response, `${at}/responses/${pointerToken(status)}`);
     for (const [type, body] of Object.entries(record2(content))) {
       if (!type.split(";")[0]?.trim().match(/^application\/(?:[\w.-]+\+)?json$/i))
         continue;
       const schema2 = record2(body).schema;
-      if (schema2 !== void 0) visit(Number(status), schema2);
+      if (schema2 !== void 0)
+        visit(Number(status), schema2, mediaSchemaAt(document, responseAt, type, body));
     }
   }
   return errors;
 }
+var fixedMethods = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+var fixedMethods32 = [...fixedMethods, "QUERY"];
+var isImportedMethod = Schema_exports.is(OpenapiOperation.fields.method);
+var pathPrefixPattern = /^(?:\/(?:[^/?#{}]|\{[A-Za-z_][\w.-]*\})+)+$/;
+function prefixParameters(prefix) {
+  if (!pathPrefixPattern.test(prefix))
+    fail2(
+      "operation_path",
+      "pathPrefix must start with /, have no empty segment, trailing /, ? or #, and write each parameter as {name}."
+    );
+  const names = [...prefix.matchAll(/\{([^{}]+)\}/g)].flatMap(
+    (match) => match[1] === void 0 ? [] : [match[1]]
+  );
+  if (new Set(names).size !== names.length)
+    fail2("operation_path", "pathPrefix names the same parameter twice.");
+  return names;
+}
 var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
   let owned = inputDocument;
   const take = () => {
@@ -4335,7 +4571,7 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
             { scheme: name, field: "password", part: "password", prefix: "" }
           ]);
         } else if (scheme.type === "oauth2") {
-          const code = record2(scheme.flows).authorizationCode;
+          const code = scheme.flows === void 0 ? void 0 : record2(scheme.flows).authorizationCode;
           if (code !== void 0) {
             const flow = record2(code);
             if (typeof flow.authorizationUrl === "string" && typeof flow.tokenUrl === "string")
@@ -4343,9 +4579,9 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
                 name,
                 config: entry.oauthDiscoveryUrl === void 0 ? {
                   authorizationUrl: absolute(
-                    new URL(flow.authorizationUrl, entry.connectUrl).href
+                    parseUrl(flow.authorizationUrl, entry.connectUrl).href
                   ),
-                  tokenUrl: absolute(new URL(flow.tokenUrl, entry.connectUrl).href),
+                  tokenUrl: absolute(parseUrl(flow.tokenUrl, entry.connectUrl).href),
                   scopes: [
                     ...entry.scopes ?? Object.keys(record2(flow.scopes ?? {}))
                   ].sort()
@@ -4378,11 +4614,10 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
           "This entry does not declare enough authentication details to generate an app."
         );
       const methods = /* @__PURE__ */ new Map();
-      const operations = [];
-      const skipped = /* @__PURE__ */ new Set();
-      const causes = /* @__PURE__ */ new Map();
+      const skipped = [];
       const built = [];
       const documentServer = spec.servers?.[0];
+      const prefix = options.pathPrefix === void 0 ? [] : prefixParameters(options.pathPrefix);
       const addresses = /* @__PURE__ */ new Map();
       const addressOf = (server) => {
         const key = JSON.stringify([server, documentServer?.variables ?? null]);
@@ -4398,64 +4633,128 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
         if ("error" in known) throw known.error;
         return known.address;
       };
+      const version32 = spec.openapi.startsWith("3.2.");
       const candidates = Object.entries(spec.paths).flatMap(([path, source]) => {
         const item = document.resolve(source);
-        return ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].filter((method) => item[method.toLowerCase()] !== void 0).map((method) => ({ path, item, method }));
+        const itemAt = declaredAt(document, source, `#/paths/${pointerToken(path)}`);
+        const additional = version32 && item.additionalOperations !== void 0 ? Object.entries(record2(item.additionalOperations)).map(([method, value]) => ({
+          method,
+          value,
+          at: `${itemAt}/additionalOperations/${pointerToken(method)}`
+        })) : [];
+        const fixed = (version32 ? fixedMethods32 : fixedMethods).filter((method) => item[method.toLowerCase()] !== void 0).map((method) => ({
+          method,
+          value: item[method.toLowerCase()],
+          at: `${itemAt}/${method.toLowerCase()}`
+        }));
+        return [...fixed, ...additional].map((operation) => ({ ...operation, path, item, itemAt }));
       });
       if (!candidates.length) fail2("no_operations", "This API does not contain any operations.");
-      const names = planOperationNames(
-        candidates.map(({ path, item, method }) => {
+      const named = planOperationNames(
+        candidates.map((candidate) => {
           const naming = Schema_exports.decodeUnknownOption(OperationNaming)(
-            resolvedOrUndefined(document, item[method.toLowerCase()])
+            resolvedOrUndefined(document, candidate.value)
           ).pipe(Option_exports.getOrUndefined);
           return {
+            ...candidate,
             operationId: naming?.operationId,
-            tag: naming?.tags?.find((tag) => tag.trim() !== ""),
-            method,
-            path
+            tag: naming?.tags?.find((tag) => tag.trim() !== "")
           };
         })
       );
-      for (const [index, { path, item, method }] of candidates.entries()) {
+      const order = new Map(named.map(({ name }, index) => [name, index]));
+      const inDefinitionOrder = (operations2) => [...operations2].sort((a, b) => (order.get(a.name) ?? 0) - (order.get(b.name) ?? 0));
+      for (const [index, { name, path, item, itemAt, method, value, at }] of named.entries()) {
         if (index % 100 === 99) await yieldToRuntime();
         try {
           if (!path.startsWith("/") || path.includes("?") || path.includes("#"))
-            fail2("operation_path", "An operation has an invalid API path.");
+            fail2("operation_path", "The path must start with / and contain no ? or #.");
+          if (!isImportedMethod(method))
+            fail2(
+              "operation_method",
+              `Executor does not send the HTTP method ${method}. It imports ${fixedMethods32.join(", ")} operations.`
+            );
           const operationMethods = [];
-          const resolved2 = document.resolve(record2(item[method.toLowerCase()]));
-          const operation = Schema_exports.decodeUnknownSync(Operation)(resolved2);
+          const resolved2 = document.resolve(record2(value));
+          const operation = decodeDefinition(Operation, resolved2, at, "operation");
           const tags = Option_exports.getOrUndefined(
             Schema_exports.decodeUnknownOption(Schema_exports.Array(Schema_exports.NonEmptyString))(resolved2.tags)
           );
-          const name = names[index] ?? fail2("operation_path", "An operation has no name.");
           if (built.some((op) => op.operation.name === name))
             fail2(
               "duplicate_operation",
-              "The API has duplicate tool names. Update its operation IDs first."
+              `Another operation has the same tool name, ${name}. Give one of them a distinct operationId.`
             );
-          const serverList = operation.servers ?? (Array.isArray(item.servers) ? Schema_exports.decodeUnknownSync(Specification.fields.servers)(item.servers) : void 0) ?? spec.servers;
+          const serverList = operation.servers ?? (Array.isArray(item.servers) ? decodeDefinition(
+            Specification.fields.servers,
+            item.servers,
+            `${itemAt}/servers`,
+            "servers"
+          ) : void 0) ?? spec.servers;
           const server = serverList?.[0];
           const serverUrl = options.baseUrl ?? server?.url;
           if (serverUrl === void 0)
-            fail2("server_missing", "The API has no server URL. Set an API base URL and try again.");
+            fail2(
+              "server_missing",
+              "The definition declares no server for this operation. Set baseUrl."
+            );
           const baseUrl = addressOf(
             options.baseUrl === void 0 && server !== void 0 ? server : { url: serverUrl }
           );
-          const combined = [
-            ...Array.isArray(item.parameters) ? item.parameters : [],
-            ...operation.parameters ?? []
+          const declared = [
+            ...(Array.isArray(item.parameters) ? item.parameters : []).map(
+              (parameter, position) => ({
+                parameter,
+                at: declaredAt(document, parameter, `${itemAt}/parameters/${position}`)
+              })
+            ),
+            ...(Array.isArray(resolved2.parameters) ? resolved2.parameters : []).map(
+              (parameter, position) => ({
+                parameter,
+                at: declaredAt(document, parameter, `${at}/parameters/${position}`)
+              })
+            )
           ];
           const parameters = /* @__PURE__ */ new Map();
-          for (const parameter of combined) {
-            const p = Schema_exports.decodeUnknownSync(OpenapiParameter)(document.resolve(record2(parameter)));
-            parameters.set(`${p.in}:${p.name}`, p);
+          for (const { parameter, at: parameterAt } of declared) {
+            const p = decodeDefinition(
+              OpenapiParameter,
+              document.resolve(record2(parameter)),
+              parameterAt,
+              "parameter"
+            );
+            if (p.in === "querystring") {
+              const [media, ...others] = Object.keys(p.content ?? {});
+              const kind = media === void 0 || others.length > 0 ? void 0 : openapiMediaKind(media);
+              if (kind !== "form" && kind !== "json" && kind !== "text")
+                fail2(
+                  "parameter_encoding",
+                  `The querystring parameter at ${parameterAt} must declare one form, JSON or text media type in content.`
+                );
+            }
+            parameters.set(`${p.in}:${p.name}`, { parameter: p, at: parameterAt });
+          }
+          for (const name2 of prefix) {
+            const key = `path:${name2}`;
+            if (path.includes(`{${name2}}`))
+              fail2(
+                "operation_path",
+                `pathPrefix adds the path parameter {${name2}}, which this operation's path already uses.`
+              );
+            if (!parameters.has(key))
+              parameters.set(key, {
+                parameter: { name: name2, in: "path", required: true, schema: { type: "string" } },
+                at: void 0
+              });
           }
           const groups = /* @__PURE__ */ new Map();
-          for (const p of parameters.values()) {
+          for (const { parameter: p, at: parameterAt } of parameters.values()) {
             const key = p.in === "header" ? "headers" : p.in;
             const group = groups.get(key) ?? { properties: {}, required: [] };
-            const content = p.content === void 0 ? void 0 : Object.values(p.content)[0];
-            group.properties[p.name] = p.schema ?? (content === void 0 ? {} : record2(content).schema ?? {});
+            const [mediaType, content] = p.content === void 0 ? [] : Object.entries(p.content)[0] ?? [];
+            const schema2 = p.schema ?? (content === void 0 ? {} : record2(content).schema ?? {});
+            const schemaAt = p.schema !== void 0 || mediaType === void 0 ? `${parameterAt}/schema` : mediaSchemaAt(document, `${parameterAt}`, mediaType, content);
+            group.properties[p.name] = parameterAt === void 0 ? () => schema2 : (api) => api(schema2, schemaAt);
             if (p.required || p.in === "path") group.required.push(p.name);
             groups.set(key, group);
           }
@@ -4465,7 +4764,7 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
             properties[key] = (api) => ({
               type: "object",
               properties: Object.fromEntries(
-                Object.entries(group.properties).map(([name2, schema2]) => [name2, api(schema2)])
+                Object.entries(group.properties).map(([name2, schema2]) => [name2, schema2(api)])
               ),
               required: group.required,
               additionalProperties: false
@@ -4475,16 +4774,27 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
           const bodyVariants = [];
           let retainedBody;
           if (operation.requestBody) {
-            const request = Schema_exports.decodeUnknownSync(OpenapiRequestBody)(
-              document.resolve(operation.requestBody)
+            const bodyAt = declaredAt(document, resolved2.requestBody, `${at}/requestBody`);
+            const request = decodeDefinition(
+              OpenapiRequestBody,
+              document.resolve(operation.requestBody),
+              bodyAt,
+              "request body"
             );
+            const rawContent = record2(document.resolve(record2(resolved2.requestBody)).content);
             const retainedContent = {};
             for (const [contentType, content] of Object.entries(request.content)) {
               const kind = openapiMediaKind(contentType);
               const schema2 = document.resolve(content.schema ?? {});
-              const declared = content.schema ?? {};
+              const declared2 = content.schema ?? {};
+              const schemaAt = mediaSchemaAt(
+                document,
+                bodyAt,
+                contentType,
+                rawContent[contentType]
+              );
               const retainedFiles = {};
-              let inputSchema = kind === "binary" ? () => binaryInput : kind === "text" ? () => ({ type: "string" }) : (api) => api(declared);
+              let inputSchema = kind === "binary" ? () => binaryInput : kind === "text" ? () => ({ type: "string" }) : (api) => api(declared2, schemaAt);
               if (kind === "multipart") {
                 const fields = { ...record2(schema2.properties ?? {}) };
                 const files = {};
@@ -4497,8 +4807,9 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
                   }
                 }
                 const form = schema2;
+                const formAt = typeof declared2.$ref === "string" ? declared2.$ref : schemaAt;
                 inputSchema = (api) => {
-                  const converted = api({ ...form, properties: fields });
+                  const converted = api({ ...form, properties: fields }, formAt);
                   return {
                     ...converted,
                     properties: { ...record2(converted.properties ?? {}), ...files }
@@ -4517,7 +4828,7 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
             }
             retainedBody = { ...request, content: retainedContent };
             if (!bodyVariants.length)
-              fail2("request_body", `Tool ${name} has no request media types.`);
+              fail2("request_body", "The request body declares no media types.");
             properties.body = () => ({});
             properties.contentType = () => ({
               type: "string",
@@ -4554,18 +4865,16 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
           try {
             jsonSchema(input);
           } catch {
-            fail2(
-              "input_schema",
-              `Tool ${name} has an input schema this importer cannot preserve yet.`
-            );
+            fail2("input_schema", "Its input schema is not valid JSON.");
           }
-          const outputSchema = responseSchema(document, operation, method);
+          const outputSchema = responseSchema(document, resolved2, at, method);
           const streaming = Object.values(operation.responses ?? {}).some((response) => {
             const content = errorContent(document, response);
             return content !== void 0 && Object.hasOwn(record2(content), "text/event-stream");
           });
           built.push({
             methods: operationMethods,
+            declared: { name, method, path },
             operation: {
               ...streaming ? { streaming: true } : {},
               ...tags === void 0 || tags.length === 0 ? {} : { tags },
@@ -4573,17 +4882,20 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
               ...operation.operationId === void 0 ? {} : { operationId: operation.operationId },
               description: operation.summary ?? operation.description ?? name,
               method,
-              path,
+              path: `${options.pathPrefix ?? ""}${path}`,
               baseUrl,
               openapi: spec.openapi,
               securitySchemes: Object.fromEntries(
                 [...new Set(security.flatMap(Object.keys))].map((key) => [
                   key,
-                  schemes[key] ?? fail2("auth_method", "A security requirement names a missing scheme.")
+                  schemes[key] ?? fail2(
+                    "auth_method",
+                    `A security requirement names ${JSON.stringify(key)}, which securitySchemes does not declare.`
+                  )
                 ])
               ),
               request: {
-                parameters: [...parameters.values()],
+                parameters: [...parameters.values()].map(({ parameter }) => parameter),
                 ...retainedBody === void 0 ? {} : { requestBody: retainedBody },
                 security,
                 responses: Object.fromEntries(
@@ -4604,14 +4916,20 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
               },
               input,
               ...outputSchema === void 0 ? {} : { outputSchema },
-              errorResponses: errorResponses(document, operation)
+              errorResponses: errorResponses(document, resolved2, at)
             }
           });
         } catch (error) {
           if (!(error instanceof OpenapiCompileError) && !Schema_exports.isSchemaError(error)) throw error;
-          const code = error instanceof OpenapiCompileError ? error.code : "invalid_document";
-          if (error instanceof OpenapiCompileError && !causes.has(code)) causes.set(code, error);
-          skipped.add(code);
+          skipped.push({
+            name,
+            method,
+            path,
+            ...error instanceof OpenapiCompileError ? { code: error.code, reason: error.reason } : {
+              code: "invalid_document",
+              reason: `The operation at ${at} does not match OpenAPI.`
+            }
+          });
         }
       }
       const counts = /* @__PURE__ */ new Map();
@@ -4631,35 +4949,84 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
         const best = pinnedOrigin === void 0 ? 0 : counts.get(pinnedOrigin) ?? 0;
         if (count > best || count === best && origin === documentOrigin) pinnedOrigin = origin;
       }
-      for (const { operation, methods: operationMethods } of built) {
-        if (new URL(operation.baseUrl).origin !== pinnedOrigin) {
-          skipped.add("multiple_hosts");
+      const imported = [];
+      for (const { operation, methods: operationMethods, declared } of built) {
+        const origin = new URL(operation.baseUrl).origin;
+        if (origin !== pinnedOrigin) {
+          skipped.push({
+            ...declared,
+            code: "multiple_hosts",
+            reason: options.allowedOrigin === void 0 ? `Its server origin ${origin} differs from ${pinnedOrigin ?? "the origin"} most operations use.` : `Its server origin ${origin} is not allowedOrigin ${options.allowedOrigin}.`
+          });
           continue;
         }
-        operations.push(operation);
+        imported.push({ operation, declared });
         for (const method of operationMethods) methods.set(method.name, method);
       }
+      const operations = imported.map(({ operation }) => operation);
       if (!operations.length) {
-        const [only, ...others] = causes.values();
-        if (only !== void 0 && others.length === 0 && [...skipped].every((reason) => reason === only.code))
-          throw only;
-        fail2(
-          "no_supported_operations",
-          "Executor cannot import any operation in this API definition."
-        );
+        const left = inDefinitionOrder(skipped);
+        if (options.allowedOrigin !== void 0 && built.length > 0)
+          throw new OpenapiCompileError({
+            code: "no_supported_operations",
+            reason: `allowedOrigin ${options.allowedOrigin} is not the origin of any operation. They resolve to ${[...counts.keys()].join(", ")}. Set allowedOrigin to the origin that receives the account's credentials, or set baseUrl.`,
+            skipped: left,
+            origins: [...counts.keys()]
+          });
+        const [first] = left;
+        if (first !== void 0 && left.every(({ code, reason }) => code === first.code && reason === first.reason))
+          throw new OpenapiCompileError({ code: first.code, reason: first.reason, skipped: left });
+        throw new OpenapiCompileError({
+          code: "no_supported_operations",
+          reason: "Executor cannot import any operation in this API definition.",
+          skipped: left
+        });
       }
-      if (!operations.some(
-        (operation) => operation.streaming !== true && (operation.request.security.length === 0 || operation.request.security.some((requirement) => {
-          const keys = Object.keys(requirement);
-          return keys.every((key) => bindings.has(key)) || keys.length === 1 && oauth.some((method) => method.name === keys[0]);
-        }))
-      ))
-        fail2(
-          "no_supported_operations",
-          "This API has no operations supported by the available authentication and response transports."
+      const supported = (requirement) => {
+        const keys = Object.keys(requirement);
+        return keys.every((key) => bindings.has(key)) || keys.length === 1 && oauth.some((method) => method.name === keys[0]);
+      };
+      const schemeLabel = (key) => {
+        const scheme = document.resolve(record2(schemes[key]));
+        const detail = scheme.type === "oauth2" ? Object.keys(record2(scheme.flows ?? {})).join("/") : scheme.type === "http" ? scheme.scheme : scheme.type === "apiKey" ? `in ${String(scheme.in)}` : void 0;
+        return `${key} (${[scheme.type, detail].filter((part) => typeof part === "string" && part !== "").join(" ")})`;
+      };
+      const unsupportedBy = (requirement) => {
+        const keys = Object.keys(requirement);
+        const unknown = keys.filter(
+          (key) => !bindings.has(key) && !oauth.some((method) => method.name === key)
         );
+        return unknown.length > 0 ? unknown.map(schemeLabel).join(" and ") : `${keys.map(schemeLabel).join(" with ")}, which combines OAuth sign-in with another scheme`;
+      };
+      const unusable = (operation) => {
+        const { security } = operation.request;
+        if (operation.streaming === true)
+          return {
+            code: "event_stream",
+            reason: "It responds with text/event-stream, which a tool cannot return. Write a subscription for it."
+          };
+        if (security.length === 0 || security.some(supported)) return void 0;
+        return {
+          code: "auth_method",
+          reason: `Executor cannot authenticate with any of its security requirements: ${security.map(unsupportedBy).join("; ")}.`
+        };
+      };
+      if (imported.every(({ operation }) => unusable(operation) !== void 0))
+        throw new OpenapiCompileError({
+          code: "no_supported_operations",
+          reason: "No operation can be called: each one is left out, streams its response, or needs authentication Executor does not support.",
+          skipped: inDefinitionOrder([
+            ...skipped,
+            ...imported.flatMap(({ operation, declared }) => {
+              const cause = unusable(operation);
+              return cause === void 0 ? [] : [{ ...declared, ...cause }];
+            })
+          ])
+        });
       return {
         operations,
+        /** Declared operations left out of `operations`, in definition order. */
+        skipped: inDefinitionOrder(skipped),
         definitions: Object.fromEntries(document.definitions),
         methods: Object.fromEntries(
           [...methods.values()].map((method) => [method.name, method.bindings])
@@ -4671,11 +5038,14 @@ var compileOpenApiDocument = (entry, inputDocument, options = {}) => {
         fallback
       };
     },
-    catch: (error) => error instanceof OpenapiCompileError ? error : new OpenapiCompileError({
-      code: "invalid_document",
-      reason: "This API definition could not be read. It may contain unsupported OpenAPI features."
-    })
-  });
+    // Expected failures stay typed; anything else is a defect in the importer, not the definition.
+    catch: (error) => error instanceof OpenapiCompileError ? Exit_exports.fail(error) : Schema_exports.isSchemaError(error) ? Exit_exports.fail(
+      new OpenapiCompileError({
+        code: "invalid_document",
+        reason: "The definition's structure does not match OpenAPI."
+      })
+    ) : Exit_exports.die(error)
+  }).pipe(Effect_exports.catch((exit) => exit));
 };
 
 // src/implementation/openapi-source.ts
@@ -4684,6 +5054,7 @@ var Manifest = Schema_exports.Struct({
   summaries: Schema_exports.Number,
   operations: Schema_exports.Number,
   definitions: Schema_exports.Number,
+  skipped: Schema_exports.Number,
   meta: Schema_exports.optionalKey(RouterMeta)
 });
 var OperationSummary = Schema_exports.Struct({
@@ -4815,7 +5186,7 @@ var decodeText = (decoder) => (text) => Effect_exports.try({ try: () => JSON.par
 var schema = (decoder) => wrap(decoder, false);
 var invoke = (work) => Effect_exports.tryPromise({ try: work, catch: (error) => error });
 var invalid = () => new OpenapiError({ reason: "invalid_definition" });
-var format = "openapi-v3";
+var format = "openapi-v4";
 var writeEntries = cacheLimits.batchEntries;
 var writeBytes = cacheLimits.batchBytes - 5e5;
 var readParts = Math.floor(cacheLimits.batchBytes / bucketLimit);
@@ -4969,6 +5340,7 @@ var liveOpenapiRouter = (options) => {
             source: options.source,
             allowedOrigin: options.allowedOrigin,
             baseUrl: options.baseUrl,
+            pathPrefix: options.pathPrefix,
             securitySchemes: options.securitySchemes,
             patches: options.patches,
             fallbackSecurity: options.fallbackSecurity
@@ -5016,7 +5388,8 @@ var liveOpenapiRouter = (options) => {
         allowedOrigin: options.allowedOrigin,
         securitySchemes: options.securitySchemes,
         ...options.fallbackSecurity === void 0 ? {} : { fallbackSecurity: options.fallbackSecurity },
-        ...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl }
+        ...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl },
+        ...options.pathPrefix === void 0 ? {} : { pathPrefix: options.pathPrefix }
       }
     );
     return { revision, meta, compiled };
@@ -5029,10 +5402,12 @@ var liveOpenapiRouter = (options) => {
       compiled.operations.map((operation) => [operation.name, operation])
     );
     const definitions = bucketize(Object.entries(compiled.definitions));
+    const skipped = compiled.skipped.length === 0 ? [] : bucketize(compiled.skipped.map((operation) => [operation.name, operation]));
     const parts = [
       ...summaries.map((value, name) => ({ kind: "summaries", name, value })),
       ...operations.map((value, name) => ({ kind: "operations", name, value })),
-      ...definitions.map((value, name) => ({ kind: "definitions", name, value }))
+      ...definitions.map((value, name) => ({ kind: "definitions", name, value })),
+      ...skipped.map((value, name) => ({ kind: "skipped", name, value }))
     ];
     const batches = [];
     let batch = [];
@@ -5061,6 +5436,7 @@ var liveOpenapiRouter = (options) => {
         summaries: summaries.length,
         operations: operations.length,
         definitions: definitions.length,
+        skipped: skipped.length,
         ...meta === void 0 ? {} : { meta }
       },
       batches,
@@ -5169,6 +5545,24 @@ var liveOpenapiRouter = (options) => {
       value: value === void 0 ? void 0 : yield* Schema_exports.decodeUnknownEffect(OpenapiOperation)(value)
     };
   });
+  const leftOutFor = (manifest, name) => Effect_exports.gen(function* () {
+    if (manifest.skipped === 0) return { value: void 0 };
+    const [bucket] = yield* read(
+      manifest.revision,
+      "skipped",
+      [bucketOf(name, manifest.skipped)],
+      Bucket
+    );
+    if (bucket === void 0) return void 0;
+    const value = Object.hasOwn(bucket, name) ? bucket[name] : void 0;
+    if (value === void 0) return { value: void 0 };
+    const operation = yield* Schema_exports.decodeUnknownEffect(OpenapiSkippedOperation)(value);
+    return yield* new OpenapiCompileError({
+      code: operation.code,
+      reason: operation.reason,
+      skipped: [operation]
+    });
+  });
   const operationsFor = (manifest) => Effect_exports.gen(function* () {
     const summaries = yield* summariesFor(manifest);
     if (summaries === void 0) return void 0;
@@ -5223,7 +5617,7 @@ var liveOpenapiRouter = (options) => {
   const kindOf = (op) => {
     const key = op.operationId ?? op.name;
     const kinds = options.kinds ?? {};
-    return Object.hasOwn(kinds, key) ? kinds[key] ?? "mutation" : ["GET", "HEAD", "OPTIONS"].includes(op.method) ? "query" : "mutation";
+    return Object.hasOwn(kinds, key) ? kinds[key] ?? "mutation" : isOpenapiReadMethod(op.method) ? "query" : "mutation";
   };
   const readOnly = (op) => kindOf(op) === "query";
   const summarize = (operation) => ({
@@ -5256,7 +5650,7 @@ var liveOpenapiRouter = (options) => {
         if (operation === void 0) {
           const found = yield* operationFor(manifest, name);
           if (found === void 0) return void 0;
-          if (found.value === void 0) return { value: void 0 };
+          if (found.value === void 0) return yield* leftOutFor(manifest, name);
           operation = found.value;
         }
         const definitions = memo?.definitions ?? (yield* definitionsFor(manifest, operation));
@@ -5301,7 +5695,7 @@ var liveOpenapiRouter = (options) => {
       (manifest) => Effect_exports.gen(function* () {
         const found = yield* operationFor(manifest, name);
         if (found === void 0) return void 0;
-        if (found.value === void 0) return { value: void 0 };
+        if (found.value === void 0) return yield* leftOutFor(manifest, name);
         const operation = found.value;
         if (!createRequest(options).available(operation, options.account))
           return { value: void 0 };
@@ -5325,6 +5719,7 @@ export {
   OpenapiErrorResponse,
   OpenapiParameter,
   OpenapiRequestBody,
+  OpenapiSkippedOperation,
   isOpenapiTextMedia,
   liveOpenapiRouter,
   openapiBinaryResultSchema,