@cerebro-labs/agentnava-sdk 0.26.0

package/import-tools.js

@@ -0,0 +1,686 @@
+// Turn an API you already describe somewhere into tools an agent can call.
+//
+// WHAT THIS IS FOR. A company adopting AgentNava has APIs already, and their
+// team already keeps a Postman collection, an OpenAPI document, or a handful of
+// curl commands that work. Asking them to hand-write a tool declaration per
+// endpoint is asking for a week of somebody's time, and asking them to produce
+// an artifact they do not already have is worse: it is a reason to stall.
+//
+// So this takes whichever of those three they have and gives back draft
+// `httpTools`. Self-serve, in the SDK, no support ticket.
+//
+// IT RUNS ENTIRELY ON YOUR MACHINE. Nothing here makes a network request except
+// `fromOpenApi` when you hand it a URL instead of a document, and that fetch
+// goes to YOUR server, not ours. That is a deliberate security property rather
+// than an implementation convenience: a Postman export routinely contains a live
+// token, and a collection you never upload is a token we can never receive.
+//
+// WHAT IT DOES NOT DO, and this is the honest part:
+//
+//   IT CANNOT WRITE THE DESCRIPTIONS. A tool's `description` is what the model
+//   reads to decide "this is the tool for this job", and none of these three
+//   formats contains that. Their summaries are written for a developer reading
+//   documentation, not for a model choosing between forty tools. "Fetch one
+//   order by its number, before deciding a refund" is what works; "Orders
+//   endpoint" is not. Where the source has nothing useful, the tool comes back
+//   with a warning rather than a confident-looking stub, because a bad
+//   description does not fail: it quietly makes the agent pick the wrong tool.
+//
+//   IT DOES NOT CREATE ANYTHING. It returns drafts. You read them, fix the
+//   descriptions, drop the endpoints an agent has no business calling, and pass
+//   what is left to `ws.agents.create({ httpTools })`.
+//
+// ```ts
+// import { fromPostman } from '@cerebro-labs/agentnava-sdk';
+//
+// const { tools, secrets, warnings } = fromPostman(collection);
+// for (const w of warnings) console.warn(w.message);
+// for (const s of secrets) await ws.secrets.create({ name: s.name, value: '...' });
+//
+// await ws.agents.create({ id: 'support', instructions: '...', httpTools: tools });
+// ```
+const DEFAULT_WARN_ABOVE = 15;
+/** Header names whose value is a credential whatever it looks like.
+ *
+ *  MATCHED ON THE NAME, NOT THE VALUE, and that is the safe direction. A value
+ *  test has to guess, and the cost of guessing wrong is a live token written
+ *  into an agent version, which is readable. A name test over-collects at worst:
+ *  it turns something harmless into a secret, which is an inconvenience. */
+const CREDENTIAL_HEADERS = new Set([
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'x-api-key',
+    'api-key',
+    'apikey',
+    'x-auth-token',
+    'auth-token',
+    'x-access-token',
+    'access-token',
+    'token',
+    'x-session-token',
+    'private-token',
+    'x-secret',
+]);
+/** Shapes that are a credential wherever they appear, including in a URL.
+ *
+ *  Deliberately narrow: each is a published prefix from a real provider, so a
+ *  match is near-certain rather than a heuristic. The header rule above is what
+ *  does the heavy lifting. */
+const CREDENTIAL_VALUE_RE = /\b(sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AIza[A-Za-z0-9_-]{30,}|AKIA[A-Z0-9]{16}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.)/;
+/** A tool name the API will accept: `^[a-z][a-z0-9_]{0,63}$`. */
+export function toolNameFrom(raw, fallback = 'call') {
+    const slug = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 64);
+    if (slug === '' || !/^[a-z]/.test(slug)) {
+        const prefixed = `${fallback}_${slug}`.replace(/_+$/, '').slice(0, 64);
+        return /^[a-z][a-z0-9_]*$/.test(prefixed) ? prefixed : fallback;
+    }
+    return slug;
+}
+/** A param name the API will accept: `^[A-Za-z][A-Za-z0-9_]*$`.
+ *
+ *  THE WIRE NAME IS NOT THE PARAM NAME, and conflating them is what broke this.
+ *  An API's query key is whatever the API says it is (`page-size`,
+ *  `filter[status]`), while a param name is an identifier both our validator and
+ *  the runtime's placeholder regex constrain to `[A-Za-z][A-Za-z0-9_]*`. Copying
+ *  the wire name into the param name produced `400 params has invalid key
+ *  "page-size"` on documents that are completely ordinary, which is exactly the
+ *  unactionable 400 `uniqueName` exists to avoid. So the key on the wire keeps
+ *  its spelling and only the identifier is normalised. */
+export function paramNameFrom(raw, fallback = 'arg') {
+    const slug = raw
+        .trim()
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 64);
+    if (slug === '' || !/^[A-Za-z]/.test(slug)) {
+        const prefixed = `${fallback}_${slug}`.replace(/_+$/, '').slice(0, 64);
+        return /^[A-Za-z][A-Za-z0-9_]*$/.test(prefixed) ? prefixed : fallback;
+    }
+    return slug;
+}
+/** A secret name the runtime's placeholder regex will match.
+ *
+ *  `[A-Za-z_][A-Za-z0-9_]*`, so a leading digit is the case that matters. A
+ *  Postman collection with a `{{2fa_token}}` variable produced
+ *  `{{secrets.2FA_TOKEN}}`, which that regex does not match at all, so nothing
+ *  substituted it and the LITERAL braces went out as the header value. No error,
+ *  just a 401 from the far end. A name that cannot resolve is worse than an ugly
+ *  one. */
+function normalizeSecretName(raw, fallback = 'API_TOKEN') {
+    const slug = raw
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toUpperCase()
+        .slice(0, 64);
+    if (slug === '')
+        return fallback;
+    return /^[A-Za-z_]/.test(slug) ? slug : `S_${slug}`.slice(0, 64);
+}
+/** A secret name from a header, or the caller's own choice. */
+function secretNameFor(header, options) {
+    if (options.secretName)
+        return options.secretName;
+    const h = header.toLowerCase();
+    if (h === 'authorization')
+        return 'API_TOKEN';
+    if (h === 'x-api-key' || h === 'api-key' || h === 'apikey')
+        return 'API_KEY';
+    return normalizeSecretName(header);
+}
+/** Accumulates tools, secrets and warnings, and keeps names unique.
+ *
+ *  UNIQUE BECAUSE THE API NOW REFUSES DUPLICATES. Two endpoints called "Get" in
+ *  different folders both slug to `get`, and a duplicate name makes which
+ *  request goes out a matter of list order: the agent looks like it called the
+ *  right tool and returns the wrong answer. Renaming here, with a warning, beats
+ *  a 400 the importer's caller cannot act on. */
+class Draft {
+    tools = [];
+    warnings = [];
+    #secrets = new Map();
+    #names = new Set();
+    /** `<tool>\0<wire name>` to the param name chosen for it. */
+    #paramNames = new Map();
+    uniqueName(wanted) {
+        if (!this.#names.has(wanted)) {
+            this.#names.add(wanted);
+            return wanted;
+        }
+        for (let i = 2; i < 1000; i++) {
+            const candidate = `${wanted}_${i}`.slice(0, 64);
+            if (!this.#names.has(candidate)) {
+                this.#names.add(candidate);
+                this.warnings.push({
+                    kind: 'name-collision',
+                    tool: candidate,
+                    message: `Two operations both became "${wanted}"; this one is "${candidate}". Give it a name that says what it does.`,
+                });
+                return candidate;
+            }
+        }
+        throw new Error(`cannot find a free name for ${wanted}`);
+    }
+    /** Records the secret. Returns true the FIRST time this name is seen, so the
+     *  caller can warn once rather than once per tool that uses it. */
+    secret(name, tool, from) {
+        const existing = this.#secrets.get(name);
+        if (existing) {
+            if (!existing.usedBy.includes(tool))
+                existing.usedBy.push(tool);
+            return false;
+        }
+        this.#secrets.set(name, { name, usedBy: [tool], from });
+        return true;
+    }
+    /** Every secret this tool references, for the tool's own `secrets` field.
+     *
+     *  LOAD-BEARING, NOT DECORATION. `collectSecretNames` in the control plane
+     *  builds a turn's secret map from each httpTool's `secrets` array; unlike
+     *  MCP servers it does NOT scan the tool's headers for {{secrets.X}}. A tool
+     *  that carries the placeholder but not the declaration therefore fails every
+     *  call with "missing required secret", which is what every drafted tool did
+     *  until this existed. */
+    secretsFor(tool) {
+        return [...this.#secrets.values()].filter((s) => s.usedBy.includes(tool)).map((s) => s.name);
+    }
+    /** Declare a param under a name the API accepts, warning when it had to
+     *  change, and return the name to use in the placeholder.
+     *
+     *  ONE WIRE NAME IS ONE PARAM, however many times it is mentioned. An
+     *  OpenAPI operation names a path variable twice: once in the path template
+     *  `/orders/{order-id}` and once in `parameters`. Treating the second sight
+     *  of it as a collision produced `order_id` in the url and a second,
+     *  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}`;
+        const already = this.#paramNames.get(key);
+        if (already !== undefined) {
+            params[already] = { ...params[already], ...def };
+            return already;
+        }
+        const wanted = paramNameFrom(wireName);
+        let name = wanted;
+        for (let i = 2; i < 1000 && name in params; i++)
+            name = `${wanted}_${i}`.slice(0, 64);
+        this.#paramNames.set(key, name);
+        if (name !== wireName) {
+            this.warnings.push({
+                kind: 'param-renamed',
+                tool,
+                message: `Parameter "${wireName}" is called "${name}" on the tool, because a param name has ` +
+                    `to be a plain identifier. The request still sends "${wireName}" on the wire.`,
+            });
+        }
+        params[name] = def;
+        return name;
+    }
+    finish(options) {
+        const limit = options.warnAbove ?? DEFAULT_WARN_ABOVE;
+        if (this.tools.length > limit) {
+            this.warnings.push({
+                kind: 'too-many-tools',
+                message: `${this.tools.length} tools. A model chooses markedly worse between forty than ` +
+                    `between eight, so keep the operations an agent genuinely needs and drop the rest ` +
+                    `(pass \`include\` to filter during the import).`,
+            });
+        }
+        return { tools: this.tools, secrets: [...this.#secrets.values()], warnings: this.warnings };
+    }
+}
+/** Headers with every credential replaced by a secret placeholder. */
+function safeHeaders(raw, toolName, draft, options, source) {
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        const isCredentialHeader = CREDENTIAL_HEADERS.has(name.toLowerCase());
+        const looksLikeOne = CREDENTIAL_VALUE_RE.test(value);
+        if (!isCredentialHeader && !looksLikeOne) {
+            out[name] = value;
+            continue;
+        }
+        const secret = secretNameFor(name, options);
+        // The SCHEME is preserved, the credential is not. `Bearer {{secrets.X}}`
+        // works; `{{secrets.X}}` alone silently drops the scheme and the server
+        // answers 401 about a malformed header.
+        const scheme = /^(Bearer|Basic|Token|ApiKey)\s+/i.exec(value)?.[1];
+        out[name] = scheme ? `${scheme} {{secrets.${secret}}}` : `{{secrets.${secret}}}`;
+        const firstTime = draft.secret(secret, toolName, `${source} header "${name}"`);
+        // ONCE PER SECRET, not once per tool. One token shared by twelve
+        // operations produced twelve identical warnings, and a list nobody can
+        // skim is a list nobody reads. `secrets[].usedBy` already names every tool
+        // that references it, so the detail is not lost.
+        if (firstTime) {
+            draft.warnings.push({
+                kind: 'credential-stripped',
+                message: `Header "${name}" held a credential. It is now {{secrets.${secret}}} and the value was ` +
+                    `NOT kept. Create it with ws.secrets.create({ name: '${secret}', value: '…' }).`,
+            });
+        }
+    }
+    return out;
+}
+/** A description the model can act on, or a warning that there is none. */
+function describe(candidates, toolName, method, path, draft) {
+    const found = candidates.map((c) => c?.trim()).find((c) => c && c.length >= 12);
+    if (found)
+        return found;
+    // The fallback is `METHOD /path`, and the path must be the RESOLVED one. Using
+    // the raw source url put `DELETE {{baseUrl}}/admin/purge` in a description,
+    // which shows a model a placeholder it cannot act on and reads like a bug.
+    // Collapse doubled slashes left behind by a stripped placeholder, but NOT the
+    // `//` in `https://`: a Postman collection that writes absolute urls rather
+    // than {{baseUrl}} produced the description "DELETE https:/api.acme.example/…",
+    // and that string is what the model reads to choose the tool.
+    const stripped = path.replace(/\{\{[^}]*\}\}/g, '');
+    const scheme = /^[a-z][a-z0-9+.-]*:\/\//i.exec(stripped)?.[0] ?? '';
+    const clean = `${scheme}${stripped.slice(scheme.length).replace(/\/{2,}/g, '/')}` || path;
+    draft.warnings.push({
+        kind: 'description-missing',
+        tool: toolName,
+        message: `"${toolName}" has no usable description. This is the field the model reads to decide ` +
+            `whether to call it, so write one line saying when someone would use it. ` +
+            `A bad description does not error, it makes the agent pick the wrong tool.`,
+    });
+    return `${method} ${clean}`;
+}
+/**
+ * Draft tools from a Postman collection export (v2.0 or v2.1).
+ *
+ * WHY POSTMAN AND NOT ONLY OPENAPI. OpenAPI is tidier; a collection is truer. It
+ * holds the requests somebody has actually run, with the header names that
+ * really work and real values in the body, which is what a tool has to
+ * reproduce. Teams also already have one, and the best format to ask for is the
+ * one nobody has to make.
+ *
+ * WHAT IT COSTS: a collection has no parameter TYPES, so every parameter comes
+ * back a string. That is usually right and always safe; `fromOpenApi` gives real
+ * types where a document exists.
+ *
+ * VARIABLES. Postman writes `{{baseUrl}}`, which is the same shape as our own
+ * placeholders, so they map across almost directly. A variable the collection
+ * DEFINES is substituted, unless it holds something that looks like a
+ * credential, in which case it becomes a secret instead of being inlined. An
+ * undefined variable becomes a secret too, with a warning, because the
+ * alternative is a URL with a placeholder nothing resolves.
+ */
+export function fromPostman(collection, options = {}) {
+    const draft = new Draft();
+    const vars = new Map();
+    for (const v of collection.variable ?? []) {
+        if (v.key)
+            vars.set(v.key, v.value ?? '');
+    }
+    /** Substitute defined variables; anything else becomes a secret. */
+    const resolveVars = (text, toolName) => text.replace(/\{\{([^}]+)\}\}/g, (_m, rawKey) => {
+        const keyName = rawKey.trim();
+        const value = vars.get(keyName);
+        // A DEFINED VARIABLE HOLDING A CREDENTIAL IS STILL A CREDENTIAL. Inlining
+        // it because the collection happened to define it is how a live token
+        // ends up in an agent version, which is readable.
+        if (value !== undefined && value !== '' && !CREDENTIAL_VALUE_RE.test(value)) {
+            return value;
+        }
+        const secret = normalizeSecretName(keyName);
+        draft.secret(secret, toolName, `collection variable "${keyName}"`);
+        if (value === undefined) {
+            draft.warnings.push({
+                kind: 'undefined-variable',
+                tool: toolName,
+                message: `{{${keyName}}} is not defined in the collection, so it became {{secrets.${secret}}}.`,
+            });
+        }
+        return `{{secrets.${secret}}}`;
+    });
+    const walk = (items, trail) => {
+        for (const item of items) {
+            if (item.item) {
+                walk(item.item, [...trail, item.name ?? '']);
+                continue;
+            }
+            const request = item.request;
+            if (!request || typeof request === 'string')
+                continue;
+            const rawUrl = typeof request.url === 'string'
+                ? request.url
+                : (request.url?.raw ??
+                    [
+                        (request.url?.host ?? []).join('.'),
+                        (request.url?.path ?? []).join('/'),
+                    ]
+                        .filter(Boolean)
+                        .join('/'));
+            if (!rawUrl)
+                continue;
+            const method = (request.method ?? 'GET').toUpperCase();
+            const candidateName = toolNameFrom(item.name ?? `${method} ${rawUrl}`);
+            if (options.include && !options.include({ name: candidateName, method, url: rawUrl })) {
+                continue;
+            }
+            const name = draft.uniqueName(candidateName);
+            // Postman path variables are `:id`; ours are `{{params.id}}`.
+            const params = {};
+            let url = resolveVars(rawUrl, name).replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => `{{params.${draft.param(params, p, { type: 'string', required: true }, name)}}}`);
+            // `?a=1&b=2` in the raw URL is kept as written; the structured `query`
+            // array is what a caller edits in Postman, so it wins where present.
+            const query = typeof request.url === 'string' ? [] : (request.url?.query ?? []);
+            const enabled = query.filter((q) => q.key && !q.disabled);
+            if (enabled.length > 0) {
+                url = url.split('?')[0];
+                const pairs = enabled.map((q) => {
+                    const key = q.key;
+                    const param = draft.param(params, key, { type: 'string', ...(q.description ? { description: q.description } : {}) }, name);
+                    return `${encodeURIComponent(key)}={{paramsEncoded.${param}}}`;
+                });
+                url = `${url}?${pairs.join('&')}`;
+            }
+            const headerPairs = {};
+            for (const h of request.header ?? []) {
+                if (h.key && !h.disabled)
+                    headerPairs[h.key] = resolveVars(h.value ?? '', name);
+            }
+            // Collection-level auth applies to a request that declares none.
+            const auth = request.auth ?? collection.auth;
+            if (auth?.type && !Object.keys(headerPairs).some((k) => CREDENTIAL_HEADERS.has(k.toLowerCase()))) {
+                const secret = secretNameFor('authorization', options);
+                headerPairs.Authorization =
+                    auth.type === 'basic' ? `Basic {{secrets.${secret}}}` : `Bearer {{secrets.${secret}}}`;
+                draft.secret(secret, name, `collection auth (${auth.type})`);
+            }
+            const headers = safeHeaders(headerPairs, name, draft, options, 'Postman');
+            let body;
+            const mode = request.body?.mode;
+            if (mode === 'raw' && request.body?.raw) {
+                body = resolveVars(request.body.raw, name);
+            }
+            else if (mode && mode !== 'raw' && mode !== 'none') {
+                draft.warnings.push({
+                    kind: 'unsupported-body',
+                    tool: name,
+                    message: `Body mode "${mode}" is not supported; the tool was created without a body.`,
+                });
+            }
+            draft.tools.push({
+                name,
+                description: describe([item.description, request.description, trail.filter(Boolean).join(' / ')], name, method, rawUrl, draft),
+                method: (['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)
+                    ? method
+                    : 'GET'),
+                url,
+                ...(Object.keys(headers).length > 0 && { headers }),
+                ...(Object.keys(params).length > 0 && { params }),
+                // DECLARED, because the placeholder alone does not reach the runtime.
+                ...(draft.secretsFor(name).length > 0 && { secrets: draft.secretsFor(name) }),
+                // GET carries no body: the API refuses one at authoring time.
+                ...(body !== undefined && method !== 'GET' && { body }),
+            });
+        }
+    };
+    walk(collection.item ?? [], []);
+    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';
+}
+/**
+ * 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.
+ */
+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 schemes = doc.components?.securitySchemes ?? doc.securityDefinitions ?? {};
+    const firstScheme = Object.values(schemes)[0];
+    for (const [path, operations] of Object.entries(doc.paths ?? {})) {
+        for (const method of OPENAPI_METHODS) {
+            const op = operations[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 })) {
+                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;
+                }
+                // 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 param = draft.param(params, p.name, def, name);
+                if (p.in === 'query') {
+                    queryPairs.push(`${encodeURIComponent(p.name)}={{paramsEncoded.${param}}}`);
+                }
+                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 (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'})`);
+            }
+            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);
+}
+/**
+ * Fetch an OpenAPI document and draft tools from it.
+ *
+ * THE FETCH GOES TO YOUR SERVER, NOT OURS. Pass `headers` if the document itself
+ * is behind auth. Nothing about the document is sent to AgentNava: the drafts
+ * are built in this process and you decide what to do with them.
+ */
+export async function fromOpenApiUrl(url, options = {}) {
+    const f = options.fetch ?? fetch;
+    const res = await f(url, { headers: options.headers ?? {} });
+    if (!res.ok) {
+        throw new Error(`could not read the OpenAPI document at ${url}: ${res.status}`);
+    }
+    return fromOpenApi((await res.json()), options);
+}
+// ------------------------------------------------------------------- curl
+/**
+ * Draft one tool from a curl command.
+ *
+ * THE LOWEST BAR ON PURPOSE. A team with no collection and no document still has
+ * a curl command that works, usually pasted in a chat thread, and that is enough
+ * to start. Handles the flags people actually use: `-X`, `-H`, `-d`/`--data`,
+ * `--data-raw`, `--url`, and a bare URL.
+ *
+ * Give it a `name` and a `description`: a curl command carries neither, and the
+ * description is the field that decides whether the agent picks this tool.
+ */
+export function fromCurl(command, options = {}) {
+    const draft = new Draft();
+    // Join line continuations, then split on whitespace outside quotes.
+    const flat = command.replace(/\\\r?\n/g, ' ').trim();
+    const tokens = flat.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+    const unquote = (s) => (s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))
+        ? s.slice(1, -1)
+        : s;
+    let method = '';
+    let url = '';
+    let body;
+    const headerPairs = {};
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === 'curl')
+            continue;
+        if (t === '-X' || t === '--request') {
+            method = unquote(tokens[++i] ?? 'GET').toUpperCase();
+        }
+        else if (t === '-H' || t === '--header') {
+            const raw = unquote(tokens[++i] ?? '');
+            const at = raw.indexOf(':');
+            if (at > 0)
+                headerPairs[raw.slice(0, at).trim()] = raw.slice(at + 1).trim();
+        }
+        else if (t === '-d' || t === '--data' || t === '--data-raw' || t === '--data-binary') {
+            body = unquote(tokens[++i] ?? '');
+        }
+        else if (t === '-u' || t === '--user') {
+            // `-u user:pass` IS a credential, and it used to vanish without a trace:
+            // `-u` matched no branch, and `user:pass` matched neither `^-` nor a
+            // url, so both tokens were skipped in silence. Routed through the
+            // Authorization header so safeHeaders strips it like any other, which
+            // also produces the credential-stripped warning.
+            headerPairs.Authorization = `Basic ${unquote(tokens[++i] ?? '')}`;
+        }
+        else if (t === '-b' || t === '--cookie') {
+            headerPairs.Cookie = unquote(tokens[++i] ?? '');
+        }
+        else if (t === '--url') {
+            url = unquote(tokens[++i] ?? '');
+        }
+        else if (!t.startsWith('-') && /^https?:\/\//.test(unquote(t))) {
+            url = unquote(t);
+        }
+    }
+    if (!url)
+        throw new Error('no URL found in that curl command');
+    // curl's own default: a body implies POST unless -X said otherwise.
+    if (!method)
+        method = body !== undefined ? 'POST' : 'GET';
+    const name = draft.uniqueName(toolNameFrom(options.name ?? `${method} ${url}`));
+    const headers = safeHeaders(headerPairs, name, draft, options, 'curl');
+    draft.tools.push({
+        name,
+        description: describe([options.description], name, method, url, draft),
+        method: (['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)
+            ? method
+            : 'GET'),
+        url,
+        ...(Object.keys(headers).length > 0 && { headers }),
+        ...(draft.secretsFor(name).length > 0 && { secrets: draft.secretsFor(name) }),
+        ...(body !== undefined && method !== 'GET' && { body }),
+    });
+    return draft.finish(options);
+}
+export function importTools(source, options = {}) {
+    if ('openapi' in source)
+        return fromOpenApi(source.openapi, options);
+    if ('postman' in source)
+        return fromPostman(source.postman, options);
+    if ('curl' in source) {
+        return fromCurl(source.curl, {
+            ...options,
+            ...(source.name !== undefined && { name: source.name }),
+            ...(source.description !== undefined && { description: source.description }),
+        });
+    }
+    if ('openapiUrl' in source) {
+        return fromOpenApiUrl(source.openapiUrl, {
+            ...options,
+            ...(source.headers !== undefined && { headers: source.headers }),
+            ...(source.fetch !== undefined && { fetch: source.fetch }),
+        });
+    }
+    // Named, not "invalid source": a caller who passed the wrong key wants to
+    // know which keys exist.
+    throw new Error('importTools needs one of: { openapi }, { openapiUrl }, { postman }, { curl }');
+}
+//# sourceMappingURL=import-tools.js.map