@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/engenty/connections-external/import-service.js

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+import { encryptToken, getConnectorDefinition } from "../shims/connections-sdk.js";
+import { ImportValidationError } from "./errors.js";
+import { mapAuth } from "./importer/map-auth.js";
+import { normalizeMcpServer } from "./importer/normalize-mcp.js";
+import { MAX_SPEC_BYTES, normalizeOpenApiSpec, } from "./importer/normalize-openapi.js";
+import { isUnauthorizedMcpError } from "./invoke/mcp-client.js";
+import { createGuardedFetch, fetchTextBounded } from "./net/guarded-fetch.js";
+import { resolveMcpTransport, } from "./registry-client.js";
+/**
+ * Import/refresh pipeline shared by the admin routes: fetch source → apply the
+ * registry's spec overrides → normalize → map auth → assemble the stored
+ * record. Pure of DB and registry-transport concerns — the routes/plugin own
+ * persistence, registry lookups and (re-)registration.
+ *
+ * Every registry fact this pipeline reads is either applied or refuses the
+ * import. A surface that needs a URL variable, an environment-sourced header,
+ * or auth we cannot express never becomes a half-working connector.
+ */
+const SPEC_FETCH_TIMEOUT_MS = 30_000;
+/** Operation/tool ids must satisfy core's strict snake_case tool-id contract. */
+const TOOL_PREFIX_RE = /^[a-z][a-z0-9_]{1,30}$/u;
+export function validateConnectorNaming(params) {
+    if (!/^[a-z][a-z0-9-]{1,59}$/u.test(params.id)) {
+        throw new ImportValidationError(`connector id "${params.id}" must be kebab-case (a-z, 0-9, -)`);
+    }
+    if (!TOOL_PREFIX_RE.test(params.toolPrefix)) {
+        throw new ImportValidationError(`tool prefix "${params.toolPrefix}" must be snake_case, start with a letter, and stay short`);
+    }
+    const existing = getConnectorDefinition(params.id, params.tenantId);
+    if (existing && existing.moduleId !== "connections-external") {
+        throw new ImportValidationError(`connector id "${params.id}" collides with built-in connector "${existing.name}"`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Registry surface → import decisions
+// ---------------------------------------------------------------------------
+/** Connector id suggested by a registry surface slug ("stripe-mcp-server"). */
+export function connectorIdFromSlug(slug) {
+    return slug
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^[-0-9]+|-+$/gu, "")
+        .slice(0, 60);
+}
+/** Tool prefix suggested by a registry surface slug ("stripe_mcp_server"). */
+export function toolPrefixFromSlug(slug) {
+    return slug
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "_")
+        .replace(/^[_0-9]+|_+$/gu, "")
+        .slice(0, 30);
+}
+/**
+ * Static headers the API requires on every request. The registry also sources
+ * headers from the environment of the machine that talks to the API; those
+ * have no value we could store, so they block the import rather than being
+ * dropped on the floor.
+ */
+export function resolveRequiredHeaders(surface) {
+    const headers = [];
+    for (const header of surface.required_headers) {
+        const kind = header.source?.kind ?? "unknown";
+        if (kind !== "static") {
+            throw new ImportValidationError(`the registry requires header "${header.name}" from a ${kind} source — only static header values can be stored on an imported connector`);
+        }
+        const value = header.source?.value;
+        if (!value) {
+            throw new ImportValidationError(`the registry requires header "${header.name}" but publishes no value for it`);
+        }
+        headers.push({
+            description: header.description ?? null,
+            name: header.name,
+            value,
+        });
+    }
+    return headers;
+}
+/** Registry variables have no value at import time — reject, never guess. */
+export function assertNoRegistryVariables(surface) {
+    if (surface.variables.length === 0) {
+        return;
+    }
+    const names = surface.variables.map((variable) => variable.name).join(", ");
+    throw new ImportValidationError(`this surface is templated on ${names} (${surface.variables
+        .map((variable) => variable.resolveFrom ?? variable.name)
+        .join("; ")}) — per-tenant URL variables are not supported; paste a resolved spec or endpoint URL instead`);
+}
+// ---------------------------------------------------------------------------
+// Fetch + normalize
+// ---------------------------------------------------------------------------
+export async function fetchSpecText(url, fetchImpl = createGuardedFetch()) {
+    return await fetchTextBounded({
+        fetchImpl,
+        headers: { accept: "application/json, application/yaml, text/yaml, */*" },
+        maxBytes: MAX_SPEC_BYTES,
+        signal: AbortSignal.timeout(SPEC_FETCH_TIMEOUT_MS),
+        url,
+    });
+}
+/** Registry surface whose MCP/API calls need a credential. */
+export function surfaceRequiresAuth(surface) {
+    return surface?.auth.status === "required";
+}
+function emptyMcpNormalize() {
+    return {
+        actions: [],
+        applied_overrides: 0,
+        base_url: null,
+        description: null,
+        dropped_count: 0,
+        security_schemes: null,
+        skipped: [],
+        title: null,
+    };
+}
+export function deferredMcpPrepared(sourceUrl) {
+    return {
+        deferred_mcp_tools: true,
+        normalized: emptyMcpNormalize(),
+        spec_hash: createHash("sha256")
+            .update(`deferred-mcp:${sourceUrl}`)
+            .digest("hex"),
+    };
+}
+/** Fetch + normalize one source. openapi → spec text; mcp → live tools/list. */
+export async function prepareSource(params) {
+    const fetchImpl = params.fetchImpl ?? createGuardedFetch();
+    const overrides = params.specOverrides ?? [];
+    if (params.sourceKind === "openapi") {
+        const specText = await fetchSpecText(params.sourceUrl, fetchImpl);
+        const normalized = await normalizeOpenApiSpec(specText, {
+            specOverrides: overrides,
+        });
+        return {
+            normalized,
+            // Overrides are part of what was imported: a changed patch must show up
+            // as a changed spec hash on refresh.
+            spec_hash: createHash("sha256")
+                .update(specText)
+                .update(JSON.stringify(overrides))
+                .digest("hex"),
+        };
+    }
+    if (params.deferMcpTools) {
+        return deferredMcpPrepared(params.sourceUrl);
+    }
+    try {
+        const normalized = await normalizeMcpServer({
+            endpoint: params.sourceUrl,
+            fetchImpl,
+            headers: {
+                ...headersFromRequired(params.requiredHeaders ?? []),
+                ...params.mcpHeaders,
+            },
+            transport: params.transport ?? null,
+        });
+        return {
+            normalized,
+            spec_hash: createHash("sha256")
+                .update(JSON.stringify(normalized.actions))
+                .digest("hex"),
+        };
+    }
+    catch (error) {
+        if ((params.deferOnUnauthorized ?? true) && isUnauthorizedMcpError(error)) {
+            return deferredMcpPrepared(params.sourceUrl);
+        }
+        throw error;
+    }
+}
+/** Stored required headers as a request header map. */
+export function headersFromRequired(headers) {
+    const out = {};
+    for (const header of headers) {
+        out[header.name] = header.value;
+    }
+    return out;
+}
+export function assembleRecord(params) {
+    validateConnectorNaming({
+        id: params.id,
+        tenantId: params.tenantId,
+        toolPrefix: params.toolPrefix,
+    });
+    const { normalized } = params.prepared;
+    const warnings = [];
+    const surface = params.surface ?? null;
+    if (surface) {
+        assertNoRegistryVariables(surface);
+    }
+    const requiredHeaders = surface ? resolveRequiredHeaders(surface) : [];
+    const mapped = mapAuth({
+        discover: params.discover ?? null,
+        securitySchemes: normalized.security_schemes,
+        sourceKind: params.sourceKind,
+        surface,
+    });
+    if (!mapped.ok) {
+        throw new ImportValidationError(mapped.reason);
+    }
+    const auth = mapped.auth;
+    if (auth.kind === "oauth2" && !params.oauthClient) {
+        if (auth.dcr && auth.registration_endpoint) {
+            warnings.push("oauth2 client will be registered on first authenticate (dynamic client registration)");
+        }
+        else {
+            warnings.push("oauth2 connector imported without client credentials — connects will fail until they are set");
+        }
+    }
+    const filter = params.actionFilter?.length
+        ? new Set(params.actionFilter)
+        : null;
+    const actions = filter
+        ? normalized.actions.filter((action) => filter.has(action.id))
+        : normalized.actions;
+    const deferredMcp = params.prepared.deferred_mcp_tools === true && params.sourceKind === "mcp";
+    if (actions.length === 0 && !deferredMcp) {
+        throw new ImportValidationError("no importable actions (empty spec, all filtered out, or all skipped)");
+    }
+    if (deferredMcp) {
+        warnings.push("tools load once an account is connected");
+    }
+    if (normalized.dropped_count > 0) {
+        warnings.push(`${normalized.dropped_count} operation(s) dropped by the per-connector cap`);
+    }
+    if (normalized.skipped.length > 0) {
+        warnings.push(`${normalized.skipped.length} operation(s) skipped: ${normalized.skipped
+            .slice(0, 5)
+            .map((s) => `${s.id} (${s.reason})`)
+            .join(", ")}${normalized.skipped.length > 5 ? ", …" : ""}`);
+    }
+    if (normalized.applied_overrides > 0) {
+        warnings.push(`${normalized.applied_overrides} registry spec override(s) applied before normalization`);
+    }
+    const baseUrl = params.baseUrlOverride ?? normalized.base_url ?? null;
+    if (params.sourceKind === "openapi" && !baseUrl) {
+        throw new ImportValidationError("spec declares no server URL — provide base_url explicitly");
+    }
+    const record = {
+        actions,
+        auth_config: auth,
+        base_url: baseUrl,
+        client_id_enc: params.oauthClient
+            ? encryptToken(params.oauthClient.clientId)
+            : null,
+        client_secret_enc: params.oauthClient
+            ? encryptToken(params.oauthClient.clientSecret)
+            : null,
+        domain: params.domain,
+        id: params.id,
+        imported_at: new Date().toISOString(),
+        imported_by: params.importedBy,
+        mcp_transport: params.sourceKind === "mcp"
+            ? ((surface ? resolveMcpTransport(surface) : null) ?? "streamable-http")
+            : null,
+        name: params.name ?? normalized.title ?? surface?.name ?? params.domain,
+        refreshed_at: null,
+        registry_snapshot: params.rawDiscover ?? null,
+        registry_surface_slug: surface?.slug ?? null,
+        required_headers: requiredHeaders,
+        source_kind: params.sourceKind,
+        source_url: params.sourceUrl,
+        spec_hash: params.prepared.spec_hash,
+        status: "enabled",
+        tenant_id: params.tenantId,
+        tool_prefix: params.toolPrefix,
+    };
+    return { record, warnings };
+}

package/apps/runtime/dist/engenty/connections-external/importer/classify.js

@@ -0,0 +1,34 @@
+/**
+ * Map an HTTP method (plus path hints) onto the connections-framework action
+ * groups. Groups drive default policy (read→allow, write/destructive→ask) and
+ * the approval contract, so lean conservative: anything ambiguous is `write`,
+ * clearly irreversible verbs are `destructive`.
+ */
+const DESTRUCTIVE_PATH_HINT = /\b(delete|remove|destroy|purge|revoke|cancel|terminate)\b/iu;
+export function classifyHttpOperation(method, pathTemplate) {
+    const m = method.toLowerCase();
+    if (m === "get" || m === "head" || m === "options") {
+        return "read";
+    }
+    if (m === "delete") {
+        return "destructive";
+    }
+    if (DESTRUCTIVE_PATH_HINT.test(pathTemplate)) {
+        return "destructive";
+    }
+    return "write";
+}
+/**
+ * MCP tool annotations → classification. `readOnlyHint` is trusted for reads;
+ * `destructiveHint` for destructive; everything else defaults to `write`
+ * (server-provided hints are advisory, so no hint never yields `read`).
+ */
+export function classifyMcpTool(annotations) {
+    if (annotations.readOnlyHint === true) {
+        return "read";
+    }
+    if (annotations.destructiveHint === true) {
+        return "destructive";
+    }
+    return "write";
+}

package/apps/runtime/dist/engenty/connections-external/importer/map-auth.js

@@ -0,0 +1,185 @@
+import { discoverOAuthFacts, } from "../registry-client.js";
+/** Map an OpenAPI 3.x securitySchemes object (spec wins over registry facts). */
+export function mapAuthFromSecuritySchemes(schemes) {
+    const entries = Object.entries(schemes);
+    // Prefer a static API key / bearer when the spec also advertises OAuth —
+    // personal access tokens work without an admin-registered developer app.
+    // Figma REST is the canonical case (PersonalAccessToken + OAuth2).
+    const bearer = entries.find(([, s]) => s.type === "http" && s.scheme?.toLowerCase() === "bearer");
+    if (bearer) {
+        return {
+            fields: [
+                { key: "api_token", label: "API token", required: true, secret: true },
+            ],
+            kind: "api_key",
+            placement: {
+                in: "header",
+                name: "Authorization",
+                value_template: "Bearer {{api_token}}",
+            },
+        };
+    }
+    const apiKey = entries.find(([, s]) => s.type === "apiKey" && (s.in === "header" || s.in === "query"));
+    if (apiKey) {
+        const scheme = apiKey[1];
+        return {
+            fields: [
+                { key: "api_key", label: "API key", required: true, secret: true },
+            ],
+            kind: "api_key",
+            placement: {
+                in: scheme.in === "query" ? "query" : "header",
+                name: scheme.name ?? "X-API-Key",
+                value_template: "{{api_key}}",
+            },
+        };
+    }
+    const oauth = entries.find(([, s]) => s.type === "oauth2" && s.flows?.authorizationCode);
+    if (oauth) {
+        const flow = oauth[1].flows?.authorizationCode;
+        if (flow?.authorizationUrl && flow.tokenUrl) {
+            return {
+                auth_url: flow.authorizationUrl,
+                kind: "oauth2",
+                scopes: Object.keys(flow.scopes ?? {}),
+                token_url: flow.tokenUrl,
+            };
+        }
+    }
+    return null;
+}
+/** Fallback: map the domain's discovered OAuth facts. */
+export function mapAuthFromRegistry(discover) {
+    const oauth = discoverOAuthFacts(discover);
+    if (oauth?.authorizationEndpoint &&
+        oauth.tokenEndpoint &&
+        (oauth.grantTypes.length === 0 ||
+            oauth.grantTypes.includes("authorization_code"))) {
+        const dcr = oauth.dcr === true && Boolean(oauth.registrationEndpoint?.trim());
+        return {
+            auth_url: oauth.authorizationEndpoint,
+            kind: "oauth2",
+            scopes: oauth.scopes,
+            token_url: oauth.tokenEndpoint,
+            ...(dcr
+                ? {
+                    dcr: true,
+                    registration_endpoint: oauth.registrationEndpoint,
+                }
+                : {}),
+        };
+    }
+    return null;
+}
+/** A credential id reduced to a stored field key. */
+function fieldKey(credentialId) {
+    const key = credentialId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 40);
+    return key || "api_key";
+}
+/** Whether a mechanic describes an OAuth flow rather than a static credential. */
+function isOauthMechanics(mechanics) {
+    if (mechanics.source === "well-known") {
+        return true;
+    }
+    return (mechanics.source === "spec" &&
+        (mechanics.scheme ?? "").toLowerCase().includes("oauth"));
+}
+/**
+ * Map one registry auth alternative. Returns null when this alternative is not
+ * expressible — the caller tries the next one before giving up.
+ */
+function mapSurfaceAuthEntry(params) {
+    const { entry } = params;
+    if (entry.use.length === 0) {
+        return null;
+    }
+    if (entry.use.length === 1 && isOauthMechanics(entry.use[0].mechanics)) {
+        return params.discover ? mapAuthFromRegistry(params.discover) : null;
+    }
+    // A single header/query credential is the only static placement the stored
+    // config can express; multi-credential alternatives (client id + secret
+    // headers) have no single placement and fall through to the next entry.
+    if (entry.use.length !== 1) {
+        return null;
+    }
+    const { id, mechanics } = entry.use[0];
+    if (mechanics.source !== "http") {
+        return null;
+    }
+    const placementIn = mechanics.in === "query" ? "query" : "header";
+    const name = mechanics.headerName ?? (placementIn === "query" ? "api_key" : "X-API-Key");
+    if (placementIn === "header" && !mechanics.headerName) {
+        return null;
+    }
+    const key = fieldKey(id);
+    const scheme = mechanics.scheme?.trim();
+    return {
+        fields: [
+            {
+                key,
+                label: params.credentialLabel(id),
+                required: true,
+                secret: true,
+            },
+        ],
+        kind: "api_key",
+        placement: {
+            in: placementIn,
+            name,
+            value_template: scheme ? `${scheme} {{${key}}}` : `{{${key}}}`,
+        },
+    };
+}
+/** Human-readable summary of what the registry said, for reject reasons. */
+function describeSurfaceAuth(surface) {
+    if (surface.auth.entries.length === 0) {
+        return `auth status "${surface.auth.status}" with no credential facts`;
+    }
+    const shapes = surface.auth.entries.map((entry) => entry.use.map((use) => `${use.id} via ${use.mechanics.source}`).join(" + "));
+    return `alternatives: ${shapes.join("; ")}`;
+}
+export function mapAuth(params) {
+    const surface = params.surface ?? null;
+    if (surface?.auth.status === "none") {
+        return { auth: { kind: "none" }, ok: true };
+    }
+    if (params.securitySchemes) {
+        const fromSpec = mapAuthFromSecuritySchemes(params.securitySchemes);
+        if (fromSpec) {
+            return { auth: fromSpec, ok: true };
+        }
+    }
+    if (surface) {
+        const credentials = params.discover?.credentials ?? {};
+        const credentialLabel = (id) => credentials[id]?.label ?? "API credential";
+        for (const entry of surface.auth.entries) {
+            const mapped = mapSurfaceAuthEntry({
+                credentialLabel,
+                discover: params.discover ?? null,
+                entry,
+            });
+            if (mapped) {
+                return { auth: mapped, ok: true };
+            }
+        }
+    }
+    if (params.discover) {
+        const fromRegistry = mapAuthFromRegistry(params.discover);
+        if (fromRegistry) {
+            return { auth: fromRegistry, ok: true };
+        }
+    }
+    const found = surface
+        ? describeSurfaceAuth(surface)
+        : params.sourceKind === "openapi"
+            ? "no usable securitySchemes in the spec"
+            : "no registry auth facts for this endpoint";
+    return {
+        ok: false,
+        reason: `cannot map authentication (${found}) — supported: no auth, OAuth 2 authorization_code, or a single header/query API key`,
+    };
+}

package/apps/runtime/dist/engenty/connections-external/importer/normalize-mcp.js

@@ -0,0 +1,63 @@
+import { mcpListTools } from "../invoke/mcp-client.js";
+import { classifyMcpTool } from "./classify.js";
+import { MAX_ACTIONS_PER_CONNECTOR } from "./normalize-openapi.js";
+function humanizeToolName(name) {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/gu, "$1 $2")
+        .replace(/[_\-.]+/gu, " ")
+        .trim();
+    return words ? words[0].toUpperCase() + words.slice(1).toLowerCase() : name;
+}
+/** MCP server tools/list → normalized actions. */
+export async function normalizeMcpServer(params) {
+    const tools = await mcpListTools(params);
+    const actions = [];
+    const skipped = [];
+    const seenIds = new Set();
+    let droppedCount = 0;
+    for (const tool of tools) {
+        if (actions.length >= MAX_ACTIONS_PER_CONNECTOR) {
+            droppedCount += 1;
+            continue;
+        }
+        const id = tool.name
+            .replace(/[^a-zA-Z0-9]+/gu, "_")
+            .replace(/^_+|_+$/gu, "")
+            .toLowerCase()
+            .slice(0, 60);
+        if (!id || seenIds.has(id)) {
+            skipped.push({
+                id: tool.name,
+                reason: id ? "duplicate tool name" : "unusable tool name",
+            });
+            continue;
+        }
+        seenIds.add(id);
+        // Humanize bare tool names ("read_wiki_structure" → "Read wiki structure")
+        // so catalogs, the permissions matrix, and approval cards read naturally.
+        const summary = tool.title ?? humanizeToolName(tool.name);
+        actions.push({
+            classification: classifyMcpTool(tool.annotations ?? {}),
+            description: tool.description ?? summary,
+            id,
+            input_json_schema: tool.inputSchema ?? {
+                additionalProperties: false,
+                properties: {},
+                type: "object",
+            },
+            invoke: { kind: "mcp", tool_name: tool.name },
+            summary,
+            tags: [],
+        });
+    }
+    return {
+        actions,
+        applied_overrides: 0,
+        base_url: null,
+        description: null,
+        dropped_count: droppedCount,
+        security_schemes: null,
+        skipped,
+        title: null,
+    };
+}

package/apps/runtime/dist/engenty/connections-external/importer/normalize-openapi.js

@@ -0,0 +1,130 @@
+import { ImportValidationError } from "../errors.js";
+import { classifyHttpOperation } from "./classify.js";
+/**
+ * OpenAPI spec text → normalized actions, via the executor openapi core
+ * (`parse` + `extract` handle $refs, parameter styles, and merge path/query/
+ * header/body params into one JSON-Schema input with the body under `body`).
+ *
+ * The executor/effect packages are imported LAZILY: they run ONLY at admin
+ * import/refresh time, never at plugin boot or action execute time — the
+ * stored `NormalizedAction[]` is what boot and execute consume. (Same
+ * lazy-import posture the AI app uses for heavyweight optional deps.)
+ *
+ * Registry `specOverrides` are RFC 6902 patches the registry publishes to
+ * correct a published spec (Figma's truncated OAuth scopes, say). They are
+ * applied to the parsed document *before* extraction, and a patch that does
+ * not apply fails the import instead of silently normalizing the unpatched
+ * spec.
+ */
+/** Hard cap per connector; drops are counted and surfaced, never silent. */
+export const MAX_ACTIONS_PER_CONNECTOR = 500;
+/** Spec size ceiling, checked before the body is read and again after. */
+export const MAX_SPEC_BYTES = 5 * 1024 * 1024;
+function snakeCaseId(raw) {
+    return raw
+        .replace(/([a-z0-9])([A-Z])/gu, "$1_$2")
+        .replace(/[^a-zA-Z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .toLowerCase()
+        .slice(0, 60);
+}
+export async function normalizeOpenApiSpec(specText, options) {
+    if (Buffer.byteLength(specText, "utf8") > MAX_SPEC_BYTES) {
+        throw new ImportValidationError(`spec too large (> ${MAX_SPEC_BYTES / (1024 * 1024)} MB); import a smaller spec or use a filtered variant`);
+    }
+    const overrides = options?.specOverrides ?? [];
+    const [{ extract, parse }, { Effect, Option }] = await Promise.all([
+        import("@executor-js/plugin-openapi/core"),
+        import("effect"),
+    ]);
+    const optional = (value) => Option.getOrUndefined(value);
+    const doc = await Effect.runPromise(parse(specText));
+    if (overrides.length > 0) {
+        const { applyPatch } = await import("rfc6902");
+        const failures = applyPatch(doc, overrides).filter((error) => error !== null);
+        if (failures.length > 0) {
+            throw new ImportValidationError(`registry spec overrides do not apply to this spec: ${failures
+                .map((error) => error.message)
+                .join("; ")}`);
+        }
+    }
+    const extracted = await Effect.runPromise(extract(doc));
+    /** Substitute server-URL variables with their declared defaults. */
+    const resolveServerBaseUrl = () => {
+        const server = extracted.servers[0];
+        if (!server) {
+            return null;
+        }
+        const variables = optional(server.variables) ?? {};
+        const url = server.url.replace(/\{([^}]+)\}/gu, (match, name) => variables[name]?.default ?? match);
+        return url.replace(/\/+$/u, "");
+    };
+    const actions = [];
+    const skipped = [];
+    const seenIds = new Set();
+    let droppedCount = 0;
+    for (const op of extracted.operations) {
+        if (op.deprecated) {
+            skipped.push({ id: op.operationId, reason: "deprecated" });
+            continue;
+        }
+        if (actions.length >= MAX_ACTIONS_PER_CONNECTOR) {
+            droppedCount += 1;
+            continue;
+        }
+        let id = snakeCaseId(op.operationId);
+        if (!id) {
+            id = snakeCaseId(`${op.method}_${op.pathTemplate}`);
+        }
+        if (!id) {
+            skipped.push({ id: op.operationId, reason: "unusable operation id" });
+            continue;
+        }
+        while (seenIds.has(id)) {
+            id = `${id}_${op.method.toLowerCase()}`.slice(0, 60);
+            if (seenIds.has(id)) {
+                id = `${id}2`;
+            }
+        }
+        seenIds.add(id);
+        const inputSchema = optional(op.inputSchema);
+        const requestBody = optional(op.requestBody);
+        const summary = optional(op.summary) ??
+            `${op.method.toUpperCase()} ${op.pathTemplate}`;
+        actions.push({
+            classification: classifyHttpOperation(op.method, op.pathTemplate),
+            description: optional(op.description) ?? summary,
+            id,
+            input_json_schema: inputSchema ?? {
+                additionalProperties: false,
+                properties: {},
+                type: "object",
+            },
+            invoke: {
+                body_content_type: requestBody?.contentType ?? null,
+                kind: "http",
+                method: op.method,
+                params: op.parameters.map((param) => ({
+                    location: param.location,
+                    name: param.name,
+                    required: param.required,
+                })),
+                path_template: op.pathTemplate,
+            },
+            summary,
+            tags: [...op.tags],
+        });
+    }
+    const securitySchemes = doc
+        .components?.securitySchemes ?? null;
+    return {
+        actions,
+        applied_overrides: overrides.length,
+        base_url: resolveServerBaseUrl(),
+        description: optional(extracted.description) ?? null,
+        dropped_count: droppedCount,
+        security_schemes: securitySchemes,
+        skipped,
+        title: optional(extracted.title) ?? null,
+    };
+}