@cerebro-labs/agentnava-sdk 0.26.0 → 0.44.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,300 @@ 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')
-        return 'boolean';
-    return 'string';
+function dereference(value, doc, seen = new Set(), validateReference) {
+    if (!value.$ref)
+        return value;
+    validateReference?.(value);
+    if (!value.$ref.startsWith('#/') || seen.has(value.$ref))
+        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, '~'))) {
+        if (!target || typeof target !== 'object' || !Object.hasOwn(target, key))
+            throw Error(`Unresolved OpenAPI reference ${value.$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);
 }
-/**
- * Draft tools from an OpenAPI 3 or Swagger 2 document.
- *
- * 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.
- *
- * 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.
- */
+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`);
+}
+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}`);
+        }
+    }
+}
+/** 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];
+    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 [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 });
+        }
+        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)))) {
+        throw Error('Extending a closed object with allOf is not supported');
+    }
+    return {
+        ...own,
+        type: 'object',
+        properties,
+        required: [...required],
+        ...(closed.length > 0 && { additionalProperties: false }),
+        // A read-only member still makes the composed property response-only.
+        ...(parts.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) {
+    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] ?? ''))
+        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 }) };
+    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');
+        if (s.additionalProperties !== undefined)
+            param.additionalProperties = s.additionalProperties;
+        param.properties = Object.fromEntries(Object.entries(s.properties ?? {})
+            .filter(([, value]) => value.readOnly !== true)
+            .map(([key, value]) => [key, resolveOpenApiSchema(value, doc, depth + 1)])
+            .filter(([, value]) => value.readOnly !== true)
+            .map(([key, value]) => [key, { ...openApiParam(value, doc, depth + 1), ...(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, doc, depth + 1);
+    }
+    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;
+}
+/** 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);
+    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 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 ?? [];
+                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 ?? { type: p.type ?? 'string', ...(p.enum && { enum: p.enum }) };
+                    const def = openApiParam(schema, doc);
+                    if (p.description)
+                        def.description = p.description;
+                    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, doc);
+                    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 }) });
             }
-            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.