@cerebro-labs/agentnava-sdk 0.44.1 → 0.47.1

package/import-tools.js

@@ -426,113 +426,325 @@ export function fromPostman(collection, options = {}) {
     return draft.finish(options);
 }
 const OPENAPI_METHODS = ['get', 'post', 'put', 'delete', 'patch'];
-function dereference(value, doc, seen = new Set(), validateReference) {
-    if (!value.$ref)
-        return value;
-    validateReference?.(value);
-    if (!value.$ref.startsWith('#/') || seen.has(value.$ref))
+/** The object a local `#/...` reference names, one hop. */
+function refTarget(ref, doc) {
+    if (!ref.startsWith('#/'))
         throw Error('Only acyclic local OpenAPI references are supported');
-    seen.add(value.$ref);
     let target = doc;
-    for (const key of value.$ref.slice(2).split('/').map(x => x.replace(/~1/g, '/').replace(/~0/g, '~'))) {
+    for (const key of ref.slice(2).split('/').map(x => x.replace(/~1/g, '/').replace(/~0/g, '~'))) {
         if (!target || typeof target !== 'object' || !Object.hasOwn(target, key))
-            throw Error(`Unresolved OpenAPI reference ${value.$ref}`);
+            throw Error(`Unresolved OpenAPI reference ${ref}`);
         target = target[key];
     }
     if (!target || typeof target !== 'object' || Array.isArray(target))
         throw Error('OpenAPI reference must resolve to an object');
-    return dereference(target, doc, seen, validateReference);
+    return target;
+}
+function dereference(value, doc, seen = new Set()) {
+    if (!value.$ref)
+        return value;
+    if (seen.has(value.$ref))
+        throw Error('Only acyclic local OpenAPI references are supported');
+    seen.add(value.$ref);
+    return dereference(refTarget(value.$ref, doc), doc, seen);
+}
+/** Keywords that only narrow which values are valid: a bound, a length, a
+ * pattern, a format. A tool parameter has no field for them, so they go into
+ * its description for the model, and the API enforces them, as it does for
+ * every other caller.
+ *
+ * THEY USED TO SKIP THE WHOLE OPERATION, even on an optional parameter, on the
+ * theory that a tool which cannot enforce a rule must not exist. Real documents
+ * put these on almost every field: a generated document with 188 operations
+ * drafted 77 tools. The rule was never the tool's to enforce; the API already
+ * does, and its 400 tells the model what to fix. */
+const RULE_KEYWORDS = [
+    'minimum', 'exclusiveMinimum', 'maximum', 'exclusiveMaximum', 'multipleOf', 'minLength', 'maxLength',
+    'pattern', 'format', 'minItems', 'maxItems', 'uniqueItems', 'minProperties', 'maxProperties',
+];
+const PRIMITIVE_TYPES = new Set(['string', 'number', 'integer', 'boolean']);
+const PARAM_TYPES = new Set([...PRIMITIVE_TYPES, 'object', 'array']);
+const TYPE_PHRASE = {
+    string: 'a string', number: 'a number', integer: 'an integer', boolean: 'true or false', object: 'an object', array: 'a list',
+};
+const refName = (ref) => ref.slice(ref.lastIndexOf('/') + 1);
+/** Sentences joined into one description. A lone part gains no full stop. */
+function sentences(...parts) {
+    const kept = parts.map(p => p?.trim()).filter((p) => !!p);
+    if (kept.length <= 1)
+        return kept[0];
+    return kept.map(p => /[.!?]$/.test(p) ? p : `${p}.`).join(' ');
+}
+/** The type a resolved schema declares, or the one its other keywords imply. */
+function typeOf(s) {
+    if (typeof s.type === 'string')
+        return s.type;
+    if (s.properties !== undefined || s.additionalProperties !== undefined)
+        return 'object';
+    if (s.items !== undefined)
+        return 'array';
+    const values = s.enum?.filter(v => v !== null) ?? [];
+    if (values.length && values.every(v => typeof v === 'string'))
+        return 'string';
+    if (values.length && values.every(v => typeof v === 'boolean'))
+        return 'boolean';
+    if (values.length && values.every(v => typeof v === 'number'))
+        return values.every(Number.isInteger) ? 'integer' : 'number';
+    return undefined;
 }
-const OPENAPI_SCHEMA_FIELDS = new Set(['type', 'properties', 'items', 'required', 'enum', 'nullable', 'description', 'additionalProperties', '$ref', 'title', 'format', 'example', 'examples', 'default', 'readOnly', 'writeOnly', 'deprecated']);
-/** Schema Object siblings apply alongside the referenced schema in OpenAPI
- * 3.1. Reject them at every reference hop until that intersection is supported.
- * Parameter and request-body Reference Objects keep their separate semantics. */
-function checkSchemaReference(schema) {
-    const sibling = Object.keys(schema).find(key => key !== '$ref');
-    if (sibling !== undefined)
-        throw Error(`Schema keyword ${sibling} alongside $ref is not supported`);
+/** The rules a schema carries, in words: "at least 1", "3 to 64 characters". */
+function ruleText(s, type) {
+    const n = (key) => typeof s[key] === 'number' && Number.isFinite(s[key]) ? s[key] : undefined;
+    const span = (min, max, unit) => {
+        const of = (x) => `${x} ${unit}${x === 1 ? '' : 's'}`;
+        if (min !== undefined && max !== undefined)
+            return min === max ? `exactly ${of(min)}` : `${min} to ${of(max)}`;
+        if (min !== undefined)
+            return `at least ${of(min)}`;
+        return max !== undefined ? `at most ${of(max)}` : undefined;
+    };
+    const extra = s.additionalProperties;
+    const value = extra && typeof extra === 'object'
+        ? (typeof extra.type === 'string' ? TYPE_PHRASE[extra.type] : typeof extra.$ref === 'string' ? refName(extra.$ref) : undefined)
+        : undefined;
+    return [
+        // 3.0 writes `exclusiveMinimum: true` beside `minimum`; 3.1 makes it the bound.
+        n('minimum') !== undefined ? `${s.exclusiveMinimum === true ? 'more than' : 'at least'} ${n('minimum')}` : undefined,
+        n('exclusiveMinimum') !== undefined ? `more than ${n('exclusiveMinimum')}` : undefined,
+        n('maximum') !== undefined ? `${s.exclusiveMaximum === true ? 'less than' : 'at most'} ${n('maximum')}` : undefined,
+        n('exclusiveMaximum') !== undefined ? `less than ${n('exclusiveMaximum')}` : undefined,
+        n('multipleOf') !== undefined ? `a multiple of ${n('multipleOf')}` : undefined,
+        span(n('minLength'), n('maxLength'), 'character'),
+        typeof s.pattern === 'string' ? `pattern \`${s.pattern}\`` : undefined,
+        // int32, int64 and double say how a number is stored, not what to send.
+        typeof s.format === 'string' && type === 'string' ? `format ${s.format}` : undefined,
+        span(n('minItems'), n('maxItems'), 'item'),
+        s.uniqueItems === true ? 'no duplicate items' : undefined,
+        span(n('minProperties'), n('maxProperties'), 'field'),
+        extra && typeof extra === 'object' ? `any keys${value ? `, each value ${value}` : ''}` : undefined,
+    ].filter((rule) => rule !== undefined);
 }
-function checkSchemaKeywords(schema) {
-    for (const key of Object.keys(schema)) {
-        if (!OPENAPI_SCHEMA_FIELDS.has(key) && !key.startsWith('x-')) {
-            throw Error(`Unsupported JSON schema keyword ${key}`);
+/** One flat schema, every reference, composition and alternative folded in.
+ * Rules stay on it as keywords, for `ruleText` to put into words; nested
+ * properties and items are left for their own turn.
+ *
+ * `nesting` counts references and compositions, separately from how deep the
+ * parameter itself goes: the API allows 12 levels of fields, and a document
+ * that reaches each level through a $ref and an allOf should not spend three. */
+function resolveOpenApiSchema(raw, ctx, where, nesting = 0) {
+    if (nesting > 32)
+        throw Error('OpenAPI schema is recursive or nests references more than 32 deep');
+    if (typeof raw.$ref === 'string') {
+        const { $ref, ...siblings } = raw;
+        const target = refTarget($ref, ctx.doc);
+        // Keywords beside a $ref apply together with what it names (OpenAPI 3.1),
+        // which is also what a 3.0 author writing a description or a rule there means.
+        const next = Object.keys(siblings).length ? { ...siblings, allOf: [target, ...(siblings.allOf ?? [])] } : target;
+        return resolveOpenApiSchema(next, ctx, where, nesting + 1);
+    }
+    const { allOf, oneOf, anyOf, ...own } = raw;
+    if (allOf && !allOf.length)
+        throw Error('An allOf schema needs at least one member');
+    const parts = (allOf ?? []).map(part => resolveOpenApiSchema(part, ctx, where, nesting + 1));
+    const said = [];
+    const join = (alternatives) => {
+        const joined = joinAlternatives(alternatives, ctx, where, nesting + 1);
+        parts.push(joined.schema);
+        if (joined.text)
+            said.push(joined.text);
+    };
+    if (Array.isArray(own.type)) {
+        // `type: [a, b]` is anyOf by another name, and "null" in it is nullable.
+        const types = own.type.filter(t => t !== 'null');
+        if (own.type.includes('null'))
+            own.nullable = true;
+        if (types.length === 1)
+            own.type = types[0];
+        else if (types.length) {
+            delete own.type;
+            join(types.map(type => ({ type })));
         }
+        else
+            own.type = 'null';
     }
+    if (oneOf !== undefined)
+        join(oneOf);
+    if (anyOf !== undefined)
+        join(anyOf);
+    const merged = intersect(parts, own);
+    const description = sentences(merged.description, ...said);
+    return description === undefined ? merged : { ...merged, description };
 }
-/** Preserve the object composition used by generated request bodies. This is
- * not a general schema intersection: conflicting properties and closed-object
- * extensions need explicit configuration rather than a weakened contract. */
-function resolveOpenApiSchema(raw, doc, depth) {
-    if (depth > 12)
-        throw Error('OpenAPI schema is recursive or exceeds 12 levels');
-    const schema = dereference(raw, doc, new Set(), checkSchemaReference);
-    if (!schema.allOf)
-        return schema;
-    const { allOf, ...own } = schema;
-    if (!allOf.length)
-        throw Error('An allOf schema needs at least one member');
-    const parts = [...allOf.map(part => resolveOpenApiSchema(part, doc, depth + 1)), own];
+/** allOf: every part applies at once. Properties and required fields add up,
+ * types and enums must agree, and rules ride along to be described. A genuine
+ * contradiction, a value that has to be both a string and a number, is an error
+ * rather than a guess. Parts are flat; their properties and items are not yet. */
+function intersect(parts, own) {
+    const all = [...parts, own];
+    if (all.some(part => part.prefixItems !== undefined))
+        throw Error('Tuple arrays (prefixItems) are not supported');
+    // Annotations and rules: the outer schema's own word, else the first part's.
+    const first = (key) => [own, ...parts].map(part => part[key]).find(value => value !== undefined);
+    const types = [...new Set(all.map(part => part.type).filter((t) => typeof t === 'string'))];
+    const numeric = types.length === 2 && types.includes('integer') && types.includes('number');
+    if (types.length > 1 && !numeric)
+        throw Error(`allOf members disagree on the type (${types.join(' and ')})`);
+    const enums = all.map(part => part.const !== undefined ? [part.const] : part.enum).filter(e => e !== undefined);
+    const values = enums.length ? enums.reduce((kept, e) => kept.filter(v => e.includes(v))) : undefined;
+    if (values && !values.length)
+        throw Error('allOf members leave no allowed value');
     const properties = {};
-    const required = new Set();
-    for (const part of parts) {
-        checkSchemaKeywords(part);
-        if ((part.type !== undefined && part.type !== 'object') || part.enum || part.nullable || part.items) {
-            throw Error('Only non-nullable object allOf composition is supported');
-        }
-        if (part.additionalProperties !== undefined && typeof part.additionalProperties !== 'boolean') {
-            throw Error('Schema-valued additionalProperties is not supported');
-        }
+    for (const part of all) {
         for (const [key, property] of Object.entries(part.properties ?? {})) {
-            if (Object.hasOwn(properties, key) && JSON.stringify(properties[key]) !== JSON.stringify(property)) {
-                throw Error(`Overlapping allOf property ${key} needs explicit configuration`);
-            }
-            Object.defineProperty(properties, key, { value: property, enumerable: true, configurable: true });
+            const before = Object.hasOwn(properties, key) ? properties[key] : undefined;
+            // The same field from two parts must satisfy both, so its rules add up too.
+            const value = before === undefined || JSON.stringify(before) === JSON.stringify(property) ? property : { allOf: [before, property] };
+            Object.defineProperty(properties, key, { value, enumerable: true, configurable: true, writable: true });
         }
-        for (const key of part.required ?? [])
-            required.add(key);
     }
-    const closed = parts.filter(part => part.additionalProperties === false);
-    if (closed.some(part => Object.keys(properties).some(key => !Object.hasOwn(part.properties ?? {}, key)))) {
+    const extras = all.map(part => part.additionalProperties).filter(extra => extra !== undefined);
+    // Keys that match patternProperties are allowed even on a closed object.
+    const closed = extras.includes(false) && !all.some(part => part.patternProperties !== undefined);
+    if (closed && all.some(part => part.additionalProperties === false && Object.keys(properties).some(key => !Object.hasOwn(part.properties ?? {}, key)))) {
         throw Error('Extending a closed object with allOf is not supported');
     }
+    const items = all.map(part => part.items).filter((item) => item !== undefined);
+    const required = [...new Set(all.flatMap(part => part.required ?? []))];
+    const annotations = Object.fromEntries(['title', 'description', ...RULE_KEYWORDS]
+        .map(key => [key, first(key)]).filter(([, value]) => value !== undefined));
     return {
-        ...own,
-        type: 'object',
-        properties,
-        required: [...required],
-        ...(closed.length > 0 && { additionalProperties: false }),
+        ...annotations,
+        ...(types.length && { type: numeric ? 'integer' : types[0] }),
+        ...(all.some(part => part.nullable === true) && { nullable: true }),
+        ...(values && { enum: values }),
+        ...(all.some(part => part.properties !== undefined) && { properties }),
+        ...(required.length && { required }),
+        ...(items.length && { items: items.length === 1 ? items[0] : { allOf: items } }),
+        ...(extras.length && { additionalProperties: closed ? false : extras.find(extra => typeof extra === 'object') ?? true }),
         // A read-only member still makes the composed property response-only.
-        ...(parts.some(part => part.readOnly === true) && { readOnly: true }),
+        ...(all.some(part => part.readOnly === true) && { readOnly: true }),
     };
 }
-/** Supported JSON subset, including nested objects/arrays. Unsupported shapes
- * skip the operation with a warning rather than drafting a subtly wrong call. */
-function openApiParam(raw, doc, depth = 0) {
+/** oneOf / anyOf: one shape that admits every alternative, as closely as a tool
+ * parameter can say it, plus the alternatives in words for the model. The API
+ * then refuses a value that fits none of them, as it would from any caller. */
+function joinAlternatives(raw, ctx, where, nesting) {
+    if (!raw.length)
+        throw Error('oneOf and anyOf need at least one alternative');
+    const resolved = raw.map(alternative => resolveOpenApiSchema(alternative, ctx, where, nesting));
+    const onlyNull = (s) => s.type === 'null' || (!!s.enum?.length && s.enum.every(v => v === null));
+    const options = resolved.flatMap((schema, i) => onlyNull(schema) ? [] : [{ schema, raw: raw[i] }]);
+    if (!options.length)
+        throw Error('An alternative list that allows only null is not supported');
+    const nullable = options.length < resolved.length || options.some(option => option.schema.nullable === true);
+    const withNull = (schema) => nullable ? { ...schema, nullable: true } : schema;
+    // "X or null" is how most generators write an optional field.
+    if (options.length === 1)
+        return { schema: withNull(options[0].schema) };
+    const labels = options.map(option => alternativeLabel(option.raw, option.schema));
+    const types = [...new Set(options.map(option => typeOf(option.schema)).filter((t) => t !== undefined))];
+    const type = types.length <= 1 ? types[0]
+        : types.every(t => t === 'number' || t === 'integer') ? 'number'
+            // A string takes what any of these primitives would say, and on a query or
+            // path it is exactly what goes on the wire.
+            : types.includes('string') && types.every(t => PRIMITIVE_TYPES.has(t)) ? 'string'
+                : undefined;
+    if (types.length > 1 && type === undefined) {
+        // No one parameter takes both an object and a list. Every alternative is
+        // valid by the document's own account, so the first one is kept.
+        ctx.notes.add(`"${where}" accepts ${[...new Set(labels)].join(' or ')}. A tool parameter takes one shape, so it ` +
+            `sends ${labels[0]}; edit the tool if the agent needs another.`);
+        return { schema: withNull(options[0].schema) };
+    }
+    const all = options.map(option => option.schema);
+    const shared = new Map();
+    for (const schema of all) {
+        for (const [key, property] of Object.entries(schema.properties ?? {})) {
+            const seen = shared.get(key) ?? [];
+            if (!seen.some(s => JSON.stringify(s) === JSON.stringify(property)))
+                seen.push(property);
+            shared.set(key, seen);
+        }
+    }
+    const properties = {};
+    for (const [key, schemas] of shared) {
+        // A field several alternatives name may take any of their shapes.
+        Object.defineProperty(properties, key, { value: schemas.length === 1 ? schemas[0] : { anyOf: schemas }, enumerable: true, configurable: true, writable: true });
+    }
+    const required = all.map(schema => schema.required ?? []).reduce((kept, r) => kept.filter(key => r.includes(key)));
+    // Choices only when every alternative lists them, and only in one type.
+    const values = all.every(schema => schema.enum) && (types.length <= 1 || type === 'number')
+        ? [...new Set(all.flatMap(schema => schema.enum))] : undefined;
+    const items = all.map(schema => schema.items).filter((item) => item !== undefined);
+    const named = options.some(option => option.raw.$ref !== undefined || option.schema.title !== undefined);
+    const said = new Set(labels).size > 1 && !(values && !named);
+    return {
+        schema: withNull({
+            ...(type && { type }),
+            ...(shared.size && { properties }),
+            ...(required.length && { required }),
+            ...(values && { enum: values }),
+            ...(items.length && { items: items.length === 1 ? items[0] : { anyOf: items } }),
+            ...(all.every(schema => schema.additionalProperties === false) && { additionalProperties: false }),
+        }),
+        ...(said && { text: `One of: ${labels.join('; ')}.` }),
+    };
+}
+/** One alternative in a few words: its name, then its fields or its rules. */
+function alternativeLabel(raw, s) {
+    const name = typeof raw.$ref === 'string' ? refName(raw.$ref) : typeof s.title === 'string' ? s.title : undefined;
+    const type = typeOf(s);
+    const fields = s.required?.length ? s.required : Object.keys(s.properties ?? {});
+    const shown = `with ${[...fields.slice(0, 8), ...(fields.length > 8 ? ['…'] : [])].join(', ')}`;
+    // A fragment that only says which fields are required reads as "with email".
+    const detail = type === 'object' || (type === undefined && fields.length)
+        ? (!fields.length ? TYPE_PHRASE.object : name || type === undefined ? shown : `${TYPE_PHRASE.object} ${shown}`)
+        : [
+            s.enum?.length === 1 ? JSON.stringify(s.enum[0]) : s.enum ? `one of ${s.enum.map(v => JSON.stringify(v)).join(', ')}` : TYPE_PHRASE[type ?? ''],
+            ...ruleText(s, type),
+        ].filter(Boolean).join(', ');
+    return name && detail ? `${name} (${detail})` : name ?? (detail || 'any value');
+}
+/** Swagger 2 writes a non-body parameter's schema on the parameter itself. */
+function swaggerParamSchema(p) {
+    const schema = { type: p.type ?? 'string' };
+    for (const key of ['enum', 'items', ...RULE_KEYWORDS])
+        if (p[key] !== undefined)
+            schema[key] = p[key];
+    return schema;
+}
+/** A tool parameter from a schema. What a parameter cannot carry, a rule or a
+ * choice between shapes, is put into its description; a shape no parameter can
+ * take at all (a tuple, a recursive tree) still skips the operation, with a
+ * warning, rather than drafting a call that cannot be made. */
+function openApiParam(raw, ctx, depth = 0, where = 'body') {
     if (depth > 12)
         throw Error('OpenAPI schema is recursive or exceeds 12 levels');
-    const s = resolveOpenApiSchema(raw, doc, depth);
-    // Constraints such as minimum/pattern remain fail-closed until the shared
-    // runtime contract can enforce them; even an optional param must not silently
-    // discard validation rules from the source document.
-    checkSchemaKeywords(s);
-    const types = Array.isArray(s.type) ? s.type : [s.type ?? (s.properties ? 'object' : undefined)];
-    const concrete = types.filter(t => t !== 'null');
-    if (concrete.length !== 1 || !['string', 'number', 'integer', 'boolean', 'object', 'array'].includes(concrete[0] ?? ''))
+    const s = resolveOpenApiSchema(raw, ctx, where);
+    const t = typeOf(s);
+    if (t === undefined || !PARAM_TYPES.has(t))
         throw Error('JSON schema must declare one supported type (optionally nullable)');
-    const t = concrete[0];
-    const param = { type: (t === 'integer' ? 'number' : t), ...(t === 'integer' && { integer: true }), ...(s.description && { description: s.description }), ...(s.enum && { choices: s.enum }), ...((s.nullable || types.includes('null')) && { nullable: true }) };
+    const type = (t === 'integer' ? 'number' : t);
+    // Choices the API would refuse, a value of another type, are described instead.
+    const fits = (v) => v === null || (t === 'integer' ? Number.isInteger(v) : typeof v === type);
+    const choices = s.enum?.length && PRIMITIVE_TYPES.has(t) && s.enum.every(fits) ? s.enum : undefined;
+    const rules = ruleText(s, t);
+    if (s.enum?.length && !choices)
+        rules.push(`one of ${s.enum.map(v => JSON.stringify(v)).join(', ')}`);
+    const description = sentences(s.description, rules.length ? `Rules: ${rules.join('; ')}.` : undefined);
+    const nullable = s.nullable === true || (choices?.includes(null) ?? false);
+    const param = { type, ...(t === 'integer' && { integer: true }), ...(description && { description }), ...(choices && { choices }), ...(nullable && { nullable: true }) };
     if (t === 'object') {
         if (Object.hasOwn(s.properties ?? {}, '__proto__'))
             throw Error('Object property __proto__ is not supported');
-        if (s.additionalProperties !== undefined && typeof s.additionalProperties !== 'boolean')
-            throw Error('Schema-valued additionalProperties is not supported');
+        // A map (`additionalProperties` holding a schema) takes any key; its rule is described.
         if (s.additionalProperties !== undefined)
-            param.additionalProperties = s.additionalProperties;
+            param.additionalProperties = s.additionalProperties !== false;
         param.properties = Object.fromEntries(Object.entries(s.properties ?? {})
             .filter(([, value]) => value.readOnly !== true)
-            .map(([key, value]) => [key, resolveOpenApiSchema(value, doc, depth + 1)])
+            .map(([key, value]) => [key, resolveOpenApiSchema(value, ctx, `${where}.${key}`)])
             .filter(([, value]) => value.readOnly !== true)
-            .map(([key, value]) => [key, { ...openApiParam(value, doc, depth + 1), ...(s.required?.includes(key) && { required: true }) }]));
+            .map(([key, value]) => [key, { ...openApiParam(value, ctx, depth + 1, `${where}.${key}`), ...(s.required?.includes(key) && { required: true }) }]));
         for (const key of s.required ?? [])
             if (!Object.hasOwn(s.properties ?? {}, key))
                 throw Error(`Required property ${key} has no schema`);
@@ -540,7 +752,7 @@ function openApiParam(raw, doc, depth = 0) {
     if (t === 'array') {
         if (!s.items)
             throw Error('Array schema needs items');
-        param.items = openApiParam(s.items, doc, depth + 1);
+        param.items = openApiParam(s.items, ctx, depth + 1, `${where}[]`);
     }
     return param;
 }
@@ -614,6 +826,39 @@ function openApiSecretNames(schemes, options) {
     }
     return allocate;
 }
+/** The security for an operation the document says nothing about, when it
+ * defines a scheme and no `security` array anywhere names one.
+ *
+ * REAL DOCUMENTS DO THIS ALL THE TIME: the scheme is declared under components
+ * and the `security` array is never written. Read literally, every operation is
+ * then public, which is how drafted tools came out with no credential and failed
+ * every call with a 401 nobody had been warned about. One scheme is unambiguous,
+ * so it applies, and the developer is told. With several, choosing would be a
+ * guess, so none applies and the warning says so. An operation that writes
+ * `security: []` stays public: that was said on purpose. */
+function unlistedSecurity(doc, schemes, draft) {
+    const names = Object.keys(schemes);
+    const operations = Object.values(doc.paths ?? {}).flatMap(item => OPENAPI_METHODS.flatMap(method => item?.[method] ?? []));
+    const named = [doc.security, ...operations.map(op => op.security)].some(list => Array.isArray(list) && list.some(requirement => !!requirement && Object.keys(requirement).length > 0));
+    // Only an operation the document says nothing about takes the default.
+    const silent = doc.security === undefined && operations.some(op => op.security === undefined);
+    if (!names.length || named || !silent)
+        return [];
+    const only = names.length === 1 ? names[0] : undefined;
+    if (only !== undefined && supportedSecurityScheme(schemes[only])) {
+        draft.warnings.push({ kind: 'security-choice', message: `The document defines one security scheme, "${only}", and no operation lists it under "security", ` +
+                `so every tool whose operation does not set "security" sends it. Remove it from any tool that calls ` +
+                `a public endpoint.` });
+        return [{ [only]: [] }];
+    }
+    draft.warnings.push({ kind: 'security-choice', message: only !== undefined
+            ? `The document defines the security scheme "${only}" (${schemes[only]?.type ?? 'no type'}), which the import cannot set up, ` +
+                `and no operation lists it, so the tools send no credential. Add the header the API expects to each tool.`
+            : `The document defines ${names.length} security schemes (${names.map(n => `"${n}"`).join(', ')}) and no operation lists one ` +
+                `under "security", so the tools send no credential. List the one the API uses under "security" and import again, ` +
+                `or add the header to each tool.` });
+    return [];
+}
 /** Draft supported OpenAPI/Swagger requests; authentication follows each
  * operation's security requirement, including AND, alternatives and security:[]. */
 export function fromOpenApi(doc, options = {}) {
@@ -623,6 +868,7 @@ export function fromOpenApi(doc, options = {}) {
         draft.warnings.push({ kind: 'undefined-variable', message: 'The document names no server. Set absolute HTTP(S) tool URLs before creating the agent.' });
     const schemes = doc.components?.securitySchemes ?? doc.securityDefinitions ?? {};
     const secretName = openApiSecretNames(schemes, options);
+    const unlisted = unlistedSecurity(doc, schemes, draft);
     for (const [path, item] of Object.entries(doc.paths ?? {}))
         for (const method of OPENAPI_METHODS) {
             const op = item[method];
@@ -633,12 +879,13 @@ export function fromOpenApi(doc, options = {}) {
                 continue;
             const name = draft.uniqueName(candidate);
             try {
+                const ctx = { doc, notes: new Set() };
                 const merged = new Map();
                 for (const raw of [...(item.parameters ?? []), ...(op.parameters ?? [])]) {
                     const p = dereference(raw, doc);
                     merged.set(p.in + ':' + p.name, p);
                 }
-                const security = op.security ?? doc.security ?? [];
+                const security = op.security ?? doc.security ?? unlisted;
                 const selected = selectSecurity(security, schemes, options, merged.values());
                 const keys = Object.keys(security[selected] ?? {});
                 const credentialDestinations = new Set(keys.map(key => securityDestination(schemes[key])));
@@ -661,10 +908,9 @@ export function fromOpenApi(doc, options = {}) {
                     }
                     if (!['path', 'query', 'header', 'body'].includes(p.in ?? ''))
                         throw Error(`Unsupported parameter location ${p.in}`);
-                    const schema = p.schema ?? { type: p.type ?? 'string', ...(p.enum && { enum: p.enum }) };
-                    const def = openApiParam(schema, doc);
-                    if (p.description)
-                        def.description = p.description;
+                    const schema = p.schema ?? swaggerParamSchema(p);
+                    // The parameter's own description leads, and the schema's rules follow it.
+                    const def = openApiParam(p.description ? { ...schema, description: p.description } : schema, ctx, 0, p.name);
                     if (p.required || p.in === 'path')
                         def.required = true;
                     if (p.in !== 'body' && (['object', 'array'].includes(def.type) || (p.style && !['simple', 'form'].includes(p.style))))
@@ -688,7 +934,7 @@ export function fromOpenApi(doc, options = {}) {
                     const media = Object.entries(requestBody.content ?? {}).find(([type]) => /(?:\/json|\+json)$/.test(type));
                     if (!media?.[1].schema)
                         throw Error('Only a JSON request body with a declared schema is supported');
-                    const def = openApiParam(media[1].schema, doc);
+                    const def = openApiParam(media[1].schema, ctx);
                     if (requestBody.required)
                         def.required = true;
                     const param = draft.param(params, 'body', def, name, 'requestBody');
@@ -711,6 +957,8 @@ export function fromOpenApi(doc, options = {}) {
                 if (query.length)
                     url += '?' + query.join('&');
                 draft.tools.push({ name, description: describe([op.description, op.summary], name, method.toUpperCase(), path, draft), method: method.toUpperCase(), url, ...(Object.keys(headers).length && { headers }), ...(Object.keys(params).length && { params }), ...(draft.secretsFor(name).length && { secrets: draft.secretsFor(name) }), ...(body !== undefined && method !== 'get' && { body }) });
+                for (const note of ctx.notes)
+                    draft.warnings.push({ kind: 'unsupported-body', tool: name, message: note });
             }
             catch (error) {
                 draft.warnings.push({ kind: 'unsupported-operation', tool: name, message: `Skipped ${method.toUpperCase()} ${path}: ${error.message}. Configure this operation explicitly.` });