@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

package/import-tools.js

@@ -199,8 +199,8 @@ class Draft {
      *  never-sent `order_id_2` in `params`, which is the very "declared and never
      *  sent" defect this class is meant to prevent. So a repeat returns the same
      *  name and merges the richer definition over the first guess. */
-    param(params, wireName, def, tool) {
-        const key = `${tool}\u0000${wireName}`;
+    param(params, wireName, def, tool, identity = wireName) {
+        const key = `${tool}\u0000${identity}`;
         const already = this.#paramNames.get(key);
         if (already !== undefined) {
             params[already] = { ...params[already], ...def };
@@ -426,146 +426,548 @@ export function fromPostman(collection, options = {}) {
     return draft.finish(options);
 }
 const OPENAPI_METHODS = ['get', 'post', 'put', 'delete', 'patch'];
-function openApiType(t) {
-    if (t === 'integer' || t === 'number')
-        return 'number';
-    if (t === 'boolean')
+/** The object a local `#/...` reference names, one hop. */
+function refTarget(ref, doc) {
+    if (!ref.startsWith('#/'))
+        throw Error('Only acyclic local OpenAPI references are supported');
+    let target = doc;
+    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 ${ref}`);
+        target = target[key];
+    }
+    if (!target || typeof target !== 'object' || Array.isArray(target))
+        throw Error('OpenAPI reference must resolve to an object');
+    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';
-    return 'string';
+    if (values.length && values.every(v => typeof v === 'number'))
+        return values.every(Number.isInteger) ? 'integer' : 'number';
+    return undefined;
 }
-/**
- * Draft tools from an OpenAPI 3 or Swagger 2 document.
+/** 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);
+}
+/** 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.
  *
- * WHAT THIS GIVES THAT POSTMAN DOES NOT: real parameter types and required
- * flags, which is exactly the shape `HttpToolParam` wants, and an enum where the
- * document declares one. FastAPI publishes this at `/openapi.json` without
- * anybody writing it, so for a FastAPI shop this is usually the richer source.
+ * `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 };
+}
+/** 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 = {};
+    for (const part of all) {
+        for (const [key, property] of Object.entries(part.properties ?? {})) {
+            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 });
+        }
+    }
+    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 {
+        ...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.
+        ...(all.some(part => part.readOnly === true) && { readOnly: true }),
+    };
+}
+/** 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, 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 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');
+        // A map (`additionalProperties` holding a schema) takes any key; its rule is described.
+        if (s.additionalProperties !== undefined)
+            param.additionalProperties = s.additionalProperties !== false;
+        param.properties = Object.fromEntries(Object.entries(s.properties ?? {})
+            .filter(([, value]) => value.readOnly !== true)
+            .map(([key, value]) => [key, resolveOpenApiSchema(value, ctx, `${where}.${key}`)])
+            .filter(([, value]) => value.readOnly !== 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`);
+    }
+    if (t === 'array') {
+        if (!s.items)
+            throw Error('Array schema needs items');
+        param.items = openApiParam(s.items, ctx, depth + 1, `${where}[]`);
+    }
+    return param;
+}
+/** Headers are case-insensitive, while query parameter names are not. */
+function securityDestination(scheme) {
+    if (scheme.type === 'apiKey' && scheme.in === 'query')
+        return `query:${scheme.name}`;
+    return `header:${(scheme.type === 'apiKey' ? scheme.name : 'Authorization').toLowerCase()}`;
+}
+function supportedSecurityScheme(scheme) {
+    return !!scheme && (scheme.type === 'basic' ||
+        (scheme.type === 'http' && ['bearer', 'basic'].includes(scheme.scheme ?? '')) ||
+        (scheme.type === 'apiKey' && ['header', 'query'].includes(scheme.in ?? '') && !!scheme.name));
+}
+function selectSecurity(security, schemes, options, parameters) {
+    const headerCredentials = new Set();
+    for (const p of parameters) {
+        if (p.in === 'header' && p.name && CREDENTIAL_HEADERS.has(p.name.toLowerCase())) {
+            headerCredentials.add(`header:${p.name.toLowerCase()}`);
+        }
+    }
+    let reason = 'No supported security alternative; cookie auth, OAuth acquisition and refresh require explicit configuration';
+    // Public operations can still declare credential headers as parameters.
+    for (const [index, requirement] of (security.length ? security : [{}]).entries()) {
+        const keys = Object.keys(requirement);
+        if (!keys.every(key => supportedSecurityScheme(schemes[key])))
+            continue;
+        if (keys.length > 1 && options.secretName) {
+            reason = 'One secretName cannot represent an AND requirement with multiple credentials';
+            continue;
+        }
+        const destinations = keys.map(key => securityDestination(schemes[key]));
+        if (new Set(destinations).size !== destinations.length) {
+            reason = 'Security requirements conflict on the same header or query parameter';
+            continue;
+        }
+        // Check parameter credentials against each alternative before selecting it.
+        if (options.secretName && new Set([...headerCredentials, ...destinations]).size > 1) {
+            reason = 'One secretName cannot represent multiple credentials in one operation';
+            continue;
+        }
+        return security.length ? index : -1;
+    }
+    throw Error(reason);
+}
+/** A document can give different schemes names that normalize identically.
+ * Allocate per identity and reserve suffix space before truncating. */
+function openApiSecretNames(schemes, options) {
+    const names = new Map();
+    const used = new Set();
+    const allocate = (identity, wanted) => {
+        const existing = names.get(identity);
+        if (existing)
+            return existing;
+        const normalized = normalizeSecretName(options.secretName || wanted);
+        let name = normalized;
+        if (!options.secretName) {
+            for (let index = 2; used.has(name); index++) {
+                const suffix = `_${index}`;
+                name = normalized.slice(0, 64 - suffix.length) + suffix;
+            }
+        }
+        names.set(identity, name);
+        used.add(name);
+        return name;
+    };
+    const defaults = Object.entries(schemes).filter(([, scheme]) => supportedSecurityScheme(scheme))
+        .map(([key, scheme]) => [key, secretNameFor(scheme.type === 'apiKey' ? scheme.name : 'Authorization', {})]);
+    for (const [key, wanted] of defaults) {
+        allocate(`scheme:${key}`, defaults.filter(([, name]) => name === wanted).length > 1 ? key : wanted);
+    }
+    return allocate;
+}
+/** The security for an operation the document says nothing about, when it
+ * defines a scheme and no `security` array anywhere names one.
  *
- * WHAT IT STILL DOES NOT GIVE: a description a model can choose on. `summary`
- * is written for a developer reading a reference. Read the warnings.
- */
+ * 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 = {}) {
     const draft = new Draft();
-    // OpenAPI 3 `servers`, or Swagger 2's three separate fields.
-    const base = doc.servers?.[0]?.url ??
-        (doc.host ? `${doc.schemes?.[0] ?? 'https'}://${doc.host}${doc.basePath ?? ''}` : '');
-    if (!base) {
-        draft.warnings.push({
-            kind: 'undefined-variable',
-            message: 'The document names no server, so every url is a path with no host. Set one, or edit ' +
-                'the urls before creating the agent: the API refuses a url that is not absolute.',
-        });
-    }
+    const base = doc.servers?.[0]?.url ?? (doc.host ? `${doc.schemes?.[0] ?? 'https'}://${doc.host}${doc.basePath ?? ''}` : '');
+    if (!base)
+        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 firstScheme = Object.values(schemes)[0];
-    for (const [path, operations] of Object.entries(doc.paths ?? {})) {
+    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 = operations[method];
+            const op = item[method];
             if (!op)
                 continue;
-            const candidateName = toolNameFrom(op.operationId ?? `${method}_${path}`, 'op');
-            const fullUrl = `${base}${path}`;
-            if (options.include && !options.include({ name: candidateName, method: method.toUpperCase(), url: fullUrl })) {
+            const candidate = toolNameFrom(op.operationId ?? `${method}_${path}`, 'op');
+            if (options.include && !options.include({ name: candidate, method: method.toUpperCase(), url: base + path }))
                 continue;
-            }
-            const name = draft.uniqueName(candidateName);
-            const params = {};
-            const headerPairs = {};
-            // A path template's `{order-id}` is a wire name like any other, so it
-            // gets the same normalisation as a query key. Declared or not: a brace
-            // in the path has to resolve, and an operation that never declared the
-            // parameter would otherwise leave `{{params.order-id}}` in the url.
-            let url = `${base}${path}`.replace(/\{([^}]+)\}/g, (_m, p) => `{{params.${draft.param(params, p, { type: 'string', required: true }, name)}}}`);
-            const queryPairs = [];
-            for (const p of op.parameters ?? []) {
-                if (!p.name)
-                    continue;
-                const def = {
-                    type: openApiType(p.schema?.type),
-                    ...(p.description ? { description: p.description } : {}),
-                    ...(p.required ? { required: true } : {}),
-                    ...(p.schema?.enum ? { choices: p.schema.enum } : {}),
-                };
-                // A CREDENTIAL HEADER IS NEVER A PARAM. The model would have to be
-                // handed the token to fill it in, and the whole point of the secret
-                // placeholder is that it never sees one.
-                if (p.in === 'header' && CREDENTIAL_HEADERS.has(p.name.toLowerCase())) {
-                    const secret = secretNameFor(p.name, options);
-                    headerPairs[p.name] = `{{secrets.${secret}}}`;
-                    draft.secret(secret, name, `securityScheme (header parameter "${p.name}")`);
-                    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);
                 }
-                // A cookie parameter cannot be expressed: it would have to be merged
-                // into a single Cookie header with every other one. Say so rather
-                // than declaring a param that goes nowhere.
-                if (p.in === 'cookie') {
-                    draft.warnings.push({
-                        kind: 'unsupported-body',
-                        tool: name,
-                        message: `Cookie parameter "${p.name}" is not supported; the tool was created without it.`,
-                    });
-                    continue;
+                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])));
+                const params = {}, headers = {}, query = [];
+                let url = (base + path).replace(/\{([^}]+)\}/g, (_match, p) => `{{paramsEncoded.${draft.param(params, p, { type: 'string', required: true }, name, 'path:' + p)}}}`);
+                let body;
+                for (const p of merged.values()) {
+                    if (!p.name)
+                        throw Error('Parameter has no name');
+                    // A declared auth parameter and a security scheme describe the same
+                    // wire credential. Emit it once, as a secret, never as model input.
+                    const destination = `${p.in}:${p.in === 'header' ? p.name.toLowerCase() : p.name}`;
+                    if (credentialDestinations.has(destination))
+                        continue;
+                    if (p.in === 'cookie') {
+                        if (p.required)
+                            throw Error('Required cookie parameters are not supported');
+                        draft.warnings.push({ kind: 'unsupported-body', tool: name, message: `Optional cookie parameter "${p.name}" is not supported; it was omitted.` });
+                        continue;
+                    }
+                    if (!['path', 'query', 'header', 'body'].includes(p.in ?? ''))
+                        throw Error(`Unsupported parameter location ${p.in}`);
+                    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))))
+                        throw Error('Structured parameter serialization is unsupported outside a JSON body');
+                    if (p.in === 'header' && CREDENTIAL_HEADERS.has(p.name.toLowerCase())) {
+                        const secret = secretName(`header:${p.name.toLowerCase()}`, secretNameFor(p.name, {}));
+                        headers[p.name] = `{{secrets.${secret}}}`;
+                        draft.secret(secret, name, `header parameter ${p.name}`);
+                        continue;
+                    }
+                    const param = draft.param(params, p.name, def, name, p.in + ':' + p.name);
+                    if (p.in === 'query')
+                        query.push(`${encodeURIComponent(p.name)}={{paramsEncoded.${param}}}`);
+                    if (p.in === 'header')
+                        headers[p.name] = `{{params.${param}}}`;
+                    if (p.in === 'body')
+                        body = `{{paramsJson.${param}}}`;
                 }
-                const param = draft.param(params, p.name, def, name);
-                if (p.in === 'query') {
-                    queryPairs.push(`${encodeURIComponent(p.name)}={{paramsEncoded.${param}}}`);
+                if (op.requestBody && method !== 'get') {
+                    const requestBody = dereference(op.requestBody, doc);
+                    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, ctx);
+                    if (requestBody.required)
+                        def.required = true;
+                    const param = draft.param(params, 'body', def, name, 'requestBody');
+                    body = `{{paramsJson.${param}}}`;
+                    headers['Content-Type'] = media[0];
                 }
-                else if (p.in === 'header') {
-                    // DECLARED AND NEVER SENT is the failure this closes. Every
-                    // parameter used to land in `params` whatever its `in` was, but
-                    // only query and path were wired to anything, so a required
-                    // `X-Tenant-Id` made the model supply a value that was dropped on
-                    // the floor and the request went out without the header.
-                    headerPairs[p.name] = `{{params.${param}}}`;
+                if (security.length > 1)
+                    draft.warnings.push({ kind: 'security-choice', tool: name, message: `Selected security alternative ${selected + 1}; review the choice before creating the agent.` });
+                for (const key of keys) {
+                    const scheme = schemes[key];
+                    const header = scheme.type === 'apiKey' ? scheme.name : 'Authorization';
+                    const secret = secretName(`scheme:${key}`, header);
+                    if (scheme.type === 'apiKey' && scheme.in === 'query')
+                        query.push(`${encodeURIComponent(header)}={{secretsEncoded.${secret}}}`);
+                    else {
+                        headers[header] = scheme.type === 'apiKey' ? `{{secrets.${secret}}}` : `${scheme.type === 'basic' || scheme.scheme === 'basic' ? 'Basic' : 'Bearer'} {{secrets.${secret}}}`;
+                    }
+                    draft.secret(secret, name, `securityScheme ${key}`);
                 }
+                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 });
             }
-            if (queryPairs.length > 0)
-                url = `${url}?${queryPairs.join('&')}`;
-            if (firstScheme) {
-                const secret = secretNameFor(firstScheme.in === 'header' && firstScheme.name ? firstScheme.name : 'authorization', options);
-                const headerName = firstScheme.type === 'apiKey' && firstScheme.in === 'header' && firstScheme.name
-                    ? firstScheme.name
-                    : 'Authorization';
-                headerPairs[headerName] =
-                    headerName.toLowerCase() === 'authorization'
-                        ? `${firstScheme.scheme === 'basic' ? 'Basic' : 'Bearer'} {{secrets.${secret}}}`
-                        : `{{secrets.${secret}}}`;
-                draft.secret(secret, name, `securityScheme (${firstScheme.type ?? 'unknown'})`);
+            catch (error) {
+                draft.warnings.push({ kind: 'unsupported-operation', tool: name, message: `Skipped ${method.toUpperCase()} ${path}: ${error.message}. Configure this operation explicitly.` });
             }
-            const headers = safeHeaders(headerPairs, name, draft, options, 'OpenAPI');
-            const upper = method.toUpperCase();
-            let body;
-            if (op.requestBody && upper !== 'GET') {
-                const types = Object.keys(op.requestBody.content ?? {});
-                if (types.some((t) => t.includes('json'))) {
-                    // A LITERAL EXAMPLE IS NOT INVENTED HERE. The schema says what the
-                    // shape is; guessing values would produce a tool that posts
-                    // plausible nonsense. The agent fills this in, so it is left for
-                    // the developer to shape.
-                    body = '{{paramsJson.body}}';
-                    params.body = { type: 'string', description: 'JSON body for this request.', required: true };
-                }
-                else if (types.length > 0) {
-                    draft.warnings.push({
-                        kind: 'unsupported-body',
-                        tool: name,
-                        message: `Request body is ${types.join(', ')}, which is not supported; the tool was created without one.`,
-                    });
-                }
-            }
-            draft.tools.push({
-                name,
-                description: describe([op.description, op.summary], name, upper, path, draft),
-                method: upper,
-                url,
-                ...(Object.keys(headers).length > 0 && { headers }),
-                ...(Object.keys(params).length > 0 && { params }),
-                ...(draft.secretsFor(name).length > 0 && { secrets: draft.secretsFor(name) }),
-                ...(body !== undefined && { body }),
-            });
         }
-    }
-    return draft.finish(options);
+    const result = draft.finish(options);
+    const emitted = new Set(result.tools.map(t => t.name));
+    result.secrets = result.secrets.map(s => ({ ...s, usedBy: s.usedBy.filter(name => emitted.has(name)) })).filter(s => s.usedBy.length > 0);
+    return result;
 }
 /**
  * Fetch an OpenAPI document and draft tools from it.