@every-app/sdk 0.3.0-rc.1 → 0.3.0-rc.10

package/dist/internal/providerSpec.d.ts

@@ -6,30 +6,41 @@
  * JSON into an {@link ApiKeyCapability} or names every problem; nothing
  * here reads a value: a spec names Gateway settings, never holds one.
  *
- * This slice parses API-key providers (`auth.kind` bearer, header, query
- * or basic). An AI provider or an OAuth client is a catalog entry only;
- * the parser says so rather than guessing.
+ * Three kinds parse: API-key providers (`auth.kind` bearer, header, query
+ * or basic), OAuth providers (`auth.kind` oauth2-user, the half in
+ * ./oauthSpec.ts: the Gateway runs the flow and holds the tokens,
+ * docs/design/2026-10-oauth-providers.md), and OpenAI-compatible model
+ * providers (`mode: "ai"`: a `baseUrl`, the key's placement, the models
+ * it serves and the default, its inference routes; the AI proxy serves a
+ * row exactly as it serves a catalog `ai` entry, inference POSTs alone,
+ * `store: false` on chat, the usage tap, so a new model vendor is a
+ * registered spec, not a catalog release).
  *
  * The rules that make a row safe on a particular gateway (its secret names
  * are its own, its hosts are public, it shadows no catalog entry) are the
  * registry's (./providerRegistry.ts), run after this parse.
  */
-import { type ApiKeyCapability } from "./capabilities.js";
+import { type AiProviderCapability, type ApiKeyCapability, type OAuthClientCapability } from "./capabilities.js";
 /** A provider id: lowercase, a letter first, 2 to 40 characters. */
 export declare const PROVIDER_ID: RegExp;
 /** A Gateway setting name a provider may hold: upper case, 3 to 64 characters. */
 export declare const PROVIDER_SECRET_NAME: RegExp;
 /** A bare lowercase host with at least one dot: labels of letters, digits and hyphens. */
 export declare const PROVIDER_HOST: RegExp;
+/** What an `ai` row serves by default: chat, and embeddings when it names an embeddings model. */
+export declare const AI_SPEC_CHAT_ROUTE = "/v1/chat/completions";
+export declare const AI_SPEC_EMBEDDINGS_ROUTE = "/v1/embeddings";
 export interface ProviderSpecProblem {
     /** Dotted: `auth.secret`, `hosts.1`, or `(root)`. */
     path: string;
     message: string;
 }
+/** What a row or a preset may be: an API key, an OAuth provider with a `flow`, or an OpenAI-compatible model provider. */
+export type RegistrableCapability = ApiKeyCapability | OAuthClientCapability | AiProviderCapability;
 export type ParsedProviderSpec = {
     ok: true;
     id: string;
-    capability: ApiKeyCapability;
+    capability: RegistrableCapability;
 } | {
     ok: false;
     problems: ProviderSpecProblem[];
@@ -49,7 +60,7 @@ export declare function describeSpecProblems(problems: readonly ProviderSpecProb
  * defaults the parser fills in spelled out, so `parseProviderSpec` of it
  * gives the entry back.
  */
-export declare function providerSpecOf(id: string, capability: ApiKeyCapability): Record<string, unknown>;
+export declare function providerSpecOf(id: string, capability: RegistrableCapability): Record<string, unknown>;
 /** The methods an app with `access: "write"` may use on `capability` besides its read methods. */
-export declare function writeMethodsOf(capability: ApiKeyCapability): readonly string[];
+export declare function writeMethodsOf(capability: RegistrableCapability): readonly string[];
 //# sourceMappingURL=providerSpec.d.ts.map

package/dist/internal/providerSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"providerSpec.d.ts","sourceRoot":"","sources":["../../src/internal/providerSpec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAIL,KAAK,gBAAgB,EAMtB,MAAM,mBAAmB,CAAC;AAE3B,oEAAoE;AACpE,eAAO,MAAM,WAAW,QAA2B,CAAC;AACpD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,QAA2B,CAAC;AAC7D,0FAA0F;AAC1F,eAAO,MAAM,aAAa,QACoD,CAAC;AA0D/E,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AA+fnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAqKpE;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,GACvC,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,gBAAgB,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwCzB;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,gBAAgB,GAC3B,SAAS,MAAM,EAAE,CAEnB"}
+{"version":3,"file":"providerSpec.d.ts","sourceRoot":"","sources":["../../src/internal/providerSpec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAM3B,MAAM,mBAAmB,CAAC;AAG3B,oEAAoE;AACpE,eAAO,MAAM,WAAW,QAA2B,CAAC;AACpD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,QAA2B,CAAC;AAC7D,0FAA0F;AAC1F,eAAO,MAAM,aAAa,QACoD,CAAC;AA4C/E,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AACzD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AA+EzD,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0HAA0H;AAC1H,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,qBAAqB,GACrB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,qBAAqB,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AA+iBnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CA2NpE;AAkOD,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,GACvC,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuGzB;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,qBAAqB,GAChC,SAAS,MAAM,EAAE,CAKnB"}

package/dist/internal/providerSpec.js

@@ -6,15 +6,22 @@
  * JSON into an {@link ApiKeyCapability} or names every problem; nothing
  * here reads a value: a spec names Gateway settings, never holds one.
  *
- * This slice parses API-key providers (`auth.kind` bearer, header, query
- * or basic). An AI provider or an OAuth client is a catalog entry only;
- * the parser says so rather than guessing.
+ * Three kinds parse: API-key providers (`auth.kind` bearer, header, query
+ * or basic), OAuth providers (`auth.kind` oauth2-user, the half in
+ * ./oauthSpec.ts: the Gateway runs the flow and holds the tokens,
+ * docs/design/2026-10-oauth-providers.md), and OpenAI-compatible model
+ * providers (`mode: "ai"`: a `baseUrl`, the key's placement, the models
+ * it serves and the default, its inference routes; the AI proxy serves a
+ * row exactly as it serves a catalog `ai` entry, inference POSTs alone,
+ * `store: false` on chat, the usage tap, so a new model vendor is a
+ * registered spec, not a catalog release).
  *
  * The rules that make a row safe on a particular gateway (its secret names
  * are its own, its hosts are public, it shadows no catalog entry) are the
  * registry's (./providerRegistry.ts), run after this parse.
  */
 import { DEFAULT_WRITE_METHODS, authSettingNames, } from "./capabilities.js";
+import { oauthSpecOf, parseOAuthUserSpec } from "./oauthSpec.js";
 /** A provider id: lowercase, a letter first, 2 to 40 characters. */
 export const PROVIDER_ID = /^[a-z][a-z0-9-]{1,39}$/;
 /** A Gateway setting name a provider may hold: upper case, 3 to 64 characters. */
@@ -26,7 +33,12 @@ const SEGMENT = /^[a-z0-9_-]{1,64}$/;
 const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
 const QUERY_PARAM = /^[A-Za-z0-9_.-]{1,64}$/;
 const SCHEME = /^[A-Za-z][A-Za-z0-9-]{0,31}$/;
-const RESPONSE_FIELD = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+/**
+ * A JSON field name, or a dotted path to a nested one (`usage.cost`, at
+ * most four segments): the capability proxy reads a top-level name off the
+ * answer's head, the AI proxy a path into the usage object off its tail.
+ */
+const RESPONSE_FIELD = /^[A-Za-z_][A-Za-z0-9_]{0,63}(?:\.[A-Za-z_][A-Za-z0-9_]{0,63}){0,3}$/;
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 const TAG = /^[a-z][a-z0-9-]{0,31}$/;
 /** Control and format characters: in no text a spec carries. */
@@ -52,6 +64,15 @@ const RESERVED_HEADERS = new Set([
 ]);
 const MAX_HOSTS = 20;
 const MAX_ACCOUNT_WIDE_PATHS = 50;
+/** An inference route an `ai` row names: `/v1/chat/completions`, segments of lowercase letters, digits, `_` and `-`. */
+const AI_ROUTE = /^(?:\/[a-z0-9_-]+)+$/;
+const MAX_AI_ROUTES = 20;
+const MAX_MODELS = 100;
+/** A model name as OpenAI-compatible APIs spell them: `gpt-6-luna`, `meta-llama/llama-4`, `claude-haiku-5-5:beta`. */
+const MODEL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,199}$/;
+/** What an `ai` row serves by default: chat, and embeddings when it names an embeddings model. */
+export const AI_SPEC_CHAT_ROUTE = "/v1/chat/completions";
+export const AI_SPEC_EMBEDDINGS_ROUTE = "/v1/embeddings";
 const KNOWN_FIELDS = new Set([
     "id",
     "mode",
@@ -75,7 +96,59 @@ const KNOWN_FIELDS = new Set([
     "example",
     "verified",
     "tags",
+    // An `oauth2-user` spec's own (./oauthSpec.ts).
+    "scopeSets",
+    "alwaysRequested",
+    "tolerated",
+    // An `ai` spec's own.
+    "baseUrl",
+    "models",
+    "defaultModel",
+    "embeddingsModel",
+    "routes",
+    "chatRoute",
+    "embeddingsRoute",
 ]);
+/** Fields only an `ai` spec has. */
+const AI_ONLY_FIELDS = [
+    "baseUrl",
+    "models",
+    "defaultModel",
+    "embeddingsModel",
+    "routes",
+    "chatRoute",
+    "embeddingsRoute",
+];
+/** Fields an `ai` spec never has: the key goes to one base URL, and the AI proxy's rules replace the capability proxy's. */
+const NOT_AI_FIELDS = [
+    "hosts",
+    "hostSetting",
+    "data",
+    "access",
+    "readMethods",
+    "writeMethods",
+    "accountWidePaths",
+    ...OAUTH_ONLY_FIELDS_LIST(),
+];
+function OAUTH_ONLY_FIELDS_LIST() {
+    return ["scopeSets", "alwaysRequested", "tolerated"];
+}
+/** Fields an API-key spec has that an `oauth2-user` spec does not. */
+const API_KEY_ONLY_FIELDS = [
+    "hostSetting",
+    "data",
+    "secrets",
+    "accountWidePaths",
+    "smoke",
+    "cost",
+    "rate",
+    "verified",
+];
+const OAUTH_ONLY_FIELDS = [
+    "scopeSets",
+    "alwaysRequested",
+    "tolerated",
+];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -300,7 +373,7 @@ function auth(value, problems) {
         default:
             problems.push({
                 path: "auth.kind",
-                message: "must be bearer, header, query or basic (an OAuth client or an AI provider is a catalog entry, not a spec this gateway takes)",
+                message: "must be bearer, header, query, basic or oauth2-user (an AI provider is a catalog entry, not a spec this gateway takes)",
             });
             return undefined;
     }
@@ -475,11 +548,11 @@ function cost(value, problems) {
     }
     const usd = nonNegative(value["usd"], "cost.usd", problems);
     const note = text(value["note"], "cost.note", problems, { max: 200 });
-    const responseField = text(value["responseField"], "cost.responseField", problems, { max: 64 });
+    const responseField = text(value["responseField"], "cost.responseField", problems, { max: 128 });
     if (responseField !== undefined && !RESPONSE_FIELD.test(responseField)) {
         problems.push({
             path: "cost.responseField",
-            message: "must be a JSON field name",
+            message: "must be a JSON field name, or a dotted path to a nested one",
         });
     }
     if (unit !== "call" && unit !== "result" && unit !== "token")
@@ -532,6 +605,43 @@ function verified(value, problems) {
     });
     return undefined;
 }
+/** `access`, `readMethods` and `writeMethods`, shared by both kinds. */
+function grants(input, problems) {
+    const access = stringList(input["access"], "access", problems, {
+        max: 2,
+        each: (level, at) => {
+            if (level !== "read" && level !== "write") {
+                problems.push({ path: at, message: "must be read or write" });
+            }
+        },
+    });
+    if (access && access.length === 0) {
+        problems.push({ path: "access", message: "must list read, write or both" });
+    }
+    const readMethods = methods(input["readMethods"], "readMethods", problems);
+    // A write-only provider (a sender, a GraphQL API) reads with nothing:
+    // every call needs the write grant. Anything that offers read lists how.
+    if (readMethods &&
+        readMethods.length === 0 &&
+        (!Array.isArray(access) || access.includes("read"))) {
+        problems.push({
+            path: "readMethods",
+            message: "must list a method unless access is write alone",
+        });
+    }
+    const writeMethods = methods(input["writeMethods"], "writeMethods", problems);
+    return { access, readMethods, writeMethods };
+}
+function tagList(value, problems) {
+    return stringList(value, "tags", problems, {
+        max: 10,
+        each: (tag, at) => {
+            if (!TAG.test(tag)) {
+                problems.push({ path: at, message: "must be a lowercase word" });
+            }
+        },
+    });
+}
 /**
  * Parse a provider spec. Every problem is reported, with its path, so a
  * person fixes the file once. On success the id and the catalog-shaped
@@ -558,10 +668,21 @@ export function parseProviderSpec(input) {
             message: "must be lowercase letters, digits and hyphens, a letter first, 2 to 40 characters (stripe)",
         });
     }
-    if (input["mode"] !== undefined && input["mode"] !== "api_key") {
+    const isOAuth = isRecord(input["auth"]) && input["auth"]["kind"] === "oauth2-user";
+    const isAi = input["mode"] === "ai";
+    const expectedMode = isOAuth ? "oauth_client" : "api_key";
+    if (!isAi && input["mode"] !== undefined && input["mode"] !== expectedMode) {
         problems.push({
             path: "mode",
-            message: "this gateway registers api_key providers; an AI provider or an OAuth client is a catalog entry",
+            message: isOAuth
+                ? "an oauth2-user spec's mode is oauth_client (or left out)"
+                : 'this gateway registers api_key, oauth_client (auth.kind oauth2-user) and ai (mode: "ai", an OpenAI-compatible model provider) providers',
+        });
+    }
+    if (isAi && isOAuth) {
+        problems.push({
+            path: "auth.kind",
+            message: "an ai spec's key is a bearer, header, query or basic key, never oauth2-user",
         });
     }
     const name = text(input["name"], "name", problems, { max: 64 });
@@ -590,6 +711,64 @@ export function parseProviderSpec(input) {
             }
         },
     });
+    if (isAi && !isOAuth) {
+        return parseAiSpec(input, problems, { id, name, description, docs, api });
+    }
+    if (isOAuth) {
+        const { access, readMethods, writeMethods } = grants(input, problems);
+        const hint = text(input["hint"], "hint", problems, { max: 500 });
+        const example = text(input["example"], "example", problems, { max: 200 });
+        const tags = tagList(input["tags"], problems);
+        // An OAuth provider: its token goes to `hosts` alone, so the API-key
+        // fields that shape a key's placement have no meaning here.
+        for (const field of API_KEY_ONLY_FIELDS) {
+            if (input[field] !== undefined) {
+                problems.push({
+                    path: field,
+                    message: "not a field of an oauth2-user spec",
+                });
+            }
+        }
+        if (input["hosts"] === undefined || (hosts && hosts.length === 0)) {
+            problems.push({
+                path: "hosts",
+                message: "required: at least one API host the token is sent to",
+            });
+        }
+        const parsed = typeof id === "string" &&
+            name !== undefined &&
+            docs !== undefined &&
+            hosts !== undefined
+            ? parseOAuthUserSpec(input, {
+                id,
+                name,
+                docs,
+                hosts,
+                ...(description === undefined ? {} : { description }),
+                ...(api === undefined ? {} : { reference: api }),
+                ...(access === undefined
+                    ? {}
+                    : { access: access }),
+                ...(readMethods === undefined ? {} : { readMethods }),
+                ...(writeMethods === undefined ? {} : { writeMethods }),
+                ...(hint === undefined ? {} : { hint }),
+                ...(example === undefined ? {} : { example }),
+                ...(tags === undefined ? {} : { tags }),
+            }, problems)
+            : undefined;
+        if (problems.length > 0 || !parsed || typeof id !== "string") {
+            return { ok: false, problems };
+        }
+        return { ok: true, id, capability: parsed.capability };
+    }
+    for (const field of OAUTH_ONLY_FIELDS) {
+        if (input[field] !== undefined) {
+            problems.push({
+                path: field,
+                message: "only an oauth2-user spec has it",
+            });
+        }
+    }
     const hostSetting = input["hostSetting"] === undefined
         ? undefined
         : secretName(input["hostSetting"], "hostSetting", problems);
@@ -623,22 +802,7 @@ export function parseProviderSpec(input) {
         ...(parsedAuth ? authSettingNames(parsedAuth) : []),
         ...(hostSetting === undefined ? [] : [hostSetting]),
     ], problems);
-    const access = stringList(input["access"], "access", problems, {
-        max: 2,
-        each: (level, at) => {
-            if (level !== "read" && level !== "write") {
-                problems.push({ path: at, message: "must be read or write" });
-            }
-        },
-    });
-    if (access && access.length === 0) {
-        problems.push({ path: "access", message: "must list read, write or both" });
-    }
-    const readMethods = methods(input["readMethods"], "readMethods", problems);
-    if (readMethods && readMethods.length === 0) {
-        problems.push({ path: "readMethods", message: "must list a method" });
-    }
-    const writeMethods = methods(input["writeMethods"], "writeMethods", problems);
+    const { access, readMethods, writeMethods } = grants(input, problems);
     const paths = accountWidePaths(input["accountWidePaths"], problems);
     const hint = text(input["hint"], "hint", problems, { max: 500 });
     const smokeRequest = smoke(input["smoke"], hosts ?? [], problems);
@@ -646,14 +810,7 @@ export function parseProviderSpec(input) {
     const parsedRate = rate(input["rate"], problems);
     const example = text(input["example"], "example", problems, { max: 200 });
     const parsedVerified = verified(input["verified"], problems);
-    const tags = stringList(input["tags"], "tags", problems, {
-        max: 10,
-        each: (tag, at) => {
-            if (!TAG.test(tag)) {
-                problems.push({ path: at, message: "must be a lowercase word" });
-            }
-        },
-    });
+    const tags = tagList(input["tags"], problems);
     if (problems.length > 0 ||
         typeof id !== "string" ||
         name === undefined ||
@@ -687,6 +844,197 @@ export function parseProviderSpec(input) {
     };
     return { ok: true, id, capability };
 }
+/**
+ * The `ai` half of `parseProviderSpec`: an OpenAI-compatible model
+ * provider. `baseUrl` is where the app's path is joined (`https://api.groq.com/openai`:
+ * the origin, and a base path the proxy keeps in front of every route);
+ * `auth` places the key as an API-key spec does; `models` lists what the
+ * provider serves (1 to 100; the proxy refuses any other) with
+ * `defaultModel` the one the Gateway's default route fills in and
+ * `embeddingsModel` the one for `/api/ai/default/v1/embeddings`; `routes`
+ * are the inference paths apps may POST to (default chat, and embeddings
+ * with an embeddings model), `chatRoute` and `embeddingsRoute` which of
+ * them the default route maps onto. Chat answers are never stored
+ * (`store: false` on the chat route). `cost.responseField` is where the
+ * answer carries the call's price, read by the usage tap as OpenRouter's
+ * `usage.cost` is.
+ */
+function parseAiSpec(input, problems, common) {
+    for (const field of NOT_AI_FIELDS) {
+        if (input[field] !== undefined) {
+            problems.push({ path: field, message: "not a field of an ai spec" });
+        }
+    }
+    const base = httpsUrl(input["baseUrl"], "baseUrl", problems);
+    let origin;
+    let basePath;
+    if (input["baseUrl"] === undefined) {
+        problems.push({
+            path: "baseUrl",
+            message: "required: the https URL the app's paths are joined onto (https://api.groq.com/openai)",
+        });
+    }
+    else if (base !== undefined) {
+        const url = new URL(base);
+        if (url.search || url.hash || url.username || url.password || url.port) {
+            problems.push({
+                path: "baseUrl",
+                message: "must be an https URL with no query, fragment, credentials or port",
+            });
+        }
+        else if (!PROVIDER_HOST.test(url.hostname)) {
+            problems.push({
+                path: "baseUrl",
+                message: "must name a public host with a dot (api.groq.com)",
+            });
+        }
+        else {
+            origin = url.origin;
+            const path = url.pathname.replace(/\/+$/, "");
+            if (path && !AI_ROUTE.test(path)) {
+                problems.push({
+                    path: "baseUrl",
+                    message: "its path must be segments of lowercase letters, digits, _ and -",
+                });
+            }
+            else if (path) {
+                basePath = path;
+            }
+        }
+    }
+    const parsedAuth = auth(input["auth"], problems);
+    if (input["auth"] === undefined) {
+        problems.push({ path: "auth", message: "required" });
+    }
+    const secrets = secretDetails(input["secrets"], parsedAuth ? authSettingNames(parsedAuth) : [], problems);
+    const models = stringList(input["models"], "models", problems, {
+        max: MAX_MODELS,
+        each: (model, at) => {
+            if (!MODEL_NAME.test(model)) {
+                problems.push({
+                    path: at,
+                    message: "must be a model name (gpt-6-luna, meta-llama/llama-4)",
+                });
+            }
+        },
+    });
+    if (input["models"] === undefined || (models && models.length === 0)) {
+        problems.push({
+            path: "models",
+            message: "required: the models the provider serves, at least one",
+        });
+    }
+    const defaultModel = text(input["defaultModel"], "defaultModel", problems, {
+        max: 200,
+    });
+    if (input["defaultModel"] === undefined) {
+        problems.push({
+            path: "defaultModel",
+            message: "required: the chat model the Gateway fills in when an app names none; one of models",
+        });
+    }
+    else if (defaultModel !== undefined &&
+        models &&
+        !models.includes(defaultModel)) {
+        problems.push({ path: "defaultModel", message: "must be one of models" });
+    }
+    const embeddingsModel = text(input["embeddingsModel"], "embeddingsModel", problems, { max: 200 });
+    if (embeddingsModel !== undefined &&
+        models &&
+        !models.includes(embeddingsModel)) {
+        problems.push({
+            path: "embeddingsModel",
+            message: "must be one of models",
+        });
+    }
+    const routeList = (value, path) => stringList(value, path, problems, {
+        max: MAX_AI_ROUTES,
+        each: (route, at) => {
+            if (!AI_ROUTE.test(route)) {
+                problems.push({
+                    path: at,
+                    message: "must be a path of lowercase segments starting with / (/v1/chat/completions)",
+                });
+            }
+        },
+    });
+    const chatRoute = text(input["chatRoute"], "chatRoute", problems, { max: 200 }) ??
+        AI_SPEC_CHAT_ROUTE;
+    const embeddingsRoute = text(input["embeddingsRoute"], "embeddingsRoute", problems, { max: 200 }) ??
+        AI_SPEC_EMBEDDINGS_ROUTE;
+    for (const [field, route] of [
+        ["chatRoute", chatRoute],
+        ["embeddingsRoute", embeddingsRoute],
+    ]) {
+        if (!AI_ROUTE.test(route)) {
+            problems.push({
+                path: field,
+                message: "must be a path of lowercase segments starting with /",
+            });
+        }
+    }
+    const routes = routeList(input["routes"], "routes") ?? [
+        chatRoute,
+        ...(embeddingsModel !== undefined ? [embeddingsRoute] : []),
+    ];
+    if (routes.length === 0) {
+        problems.push({ path: "routes", message: "must list a route" });
+    }
+    if (!routes.includes(chatRoute)) {
+        problems.push({ path: "chatRoute", message: "must be one of routes" });
+    }
+    if (embeddingsModel !== undefined && !routes.includes(embeddingsRoute)) {
+        problems.push({
+            path: "embeddingsRoute",
+            message: "must be one of routes",
+        });
+    }
+    const hint = text(input["hint"], "hint", problems, { max: 500 });
+    const smokeRequest = smoke(input["smoke"], origin ? [new URL(origin).host] : [], problems);
+    const parsedCost = cost(input["cost"], problems);
+    const parsedRate = rate(input["rate"], problems);
+    const example = text(input["example"], "example", problems, { max: 200 });
+    const parsedVerified = verified(input["verified"], problems);
+    const tags = tagList(input["tags"], problems);
+    const { id, name, description, docs, api } = common;
+    if (problems.length > 0 ||
+        typeof id !== "string" ||
+        name === undefined ||
+        docs === undefined ||
+        origin === undefined ||
+        !parsedAuth ||
+        !models ||
+        defaultModel === undefined) {
+        return { ok: false, problems };
+    }
+    const capability = {
+        mode: "ai",
+        label: name,
+        auth: parsedAuth,
+        docs,
+        origin,
+        ...(basePath === undefined ? {} : { basePath }),
+        inferenceRoutes: routes,
+        unstoredRoutes: [chatRoute],
+        shape: "openai",
+        chat: { path: chatRoute, seedModel: defaultModel },
+        ...(embeddingsModel === undefined
+            ? {}
+            : { embeddings: { path: embeddingsRoute, seedModel: embeddingsModel } }),
+        models,
+        ...(description === undefined ? {} : { description }),
+        ...(api === undefined ? {} : { api }),
+        ...(secrets === undefined ? {} : { secrets }),
+        ...(hint === undefined ? {} : { hint }),
+        ...(smokeRequest === undefined ? {} : { smoke: smokeRequest }),
+        ...(parsedCost === undefined ? {} : { cost: parsedCost }),
+        ...(parsedRate === undefined ? {} : { rate: parsedRate }),
+        ...(example === undefined ? {} : { example }),
+        ...(parsedVerified === undefined ? {} : { verified: parsedVerified }),
+        ...(tags === undefined ? {} : { tags }),
+    };
+    return { ok: true, id, capability };
+}
 /** The problems as one line: `auth.secret: must name a Gateway setting; hosts.0: …`. */
 export function describeSpecProblems(problems) {
     return problems
@@ -700,6 +1048,65 @@ export function describeSpecProblems(problems) {
  * gives the entry back.
  */
 export function providerSpecOf(id, capability) {
+    if (capability.mode === "oauth_client") {
+        const spec = oauthSpecOf(id, capability);
+        if (!spec) {
+            throw new Error(`${id} is a catalog OAuth client without a Gateway-owned flow: it has no spec`);
+        }
+        return spec;
+    }
+    if (capability.mode === "ai") {
+        if (!capability.chat || !capability.models) {
+            throw new Error(`${id} is a catalog AI entry without a model list: it has no spec`);
+        }
+        return {
+            id,
+            mode: "ai",
+            name: capability.label,
+            ...(capability.description === undefined
+                ? {}
+                : { description: capability.description }),
+            docs: capability.docs,
+            ...(capability.api === undefined ? {} : { api: capability.api }),
+            baseUrl: `${capability.origin}${capability.basePath ?? ""}`,
+            auth: { ...capability.auth },
+            ...(capability.secrets === undefined
+                ? {}
+                : { secrets: capability.secrets.map((detail) => ({ ...detail })) }),
+            models: [...capability.models],
+            defaultModel: capability.chat.seedModel,
+            ...(capability.embeddings === undefined
+                ? {}
+                : { embeddingsModel: capability.embeddings.seedModel }),
+            routes: [...capability.inferenceRoutes],
+            chatRoute: capability.chat.path,
+            ...(capability.embeddings === undefined
+                ? {}
+                : { embeddingsRoute: capability.embeddings.path }),
+            ...(capability.hint === undefined ? {} : { hint: capability.hint }),
+            ...(capability.smoke === undefined
+                ? {}
+                : {
+                    smoke: {
+                        ...capability.smoke,
+                        expect: [...capability.smoke.expect],
+                    },
+                }),
+            ...(capability.cost === undefined
+                ? {}
+                : { cost: { ...capability.cost } }),
+            ...(capability.rate === undefined
+                ? {}
+                : { rate: { ...capability.rate } }),
+            ...(capability.example === undefined
+                ? {}
+                : { example: capability.example }),
+            ...(capability.verified === undefined
+                ? {}
+                : { verified: capability.verified }),
+            ...(capability.tags === undefined ? {} : { tags: [...capability.tags] }),
+        };
+    }
     return {
         id,
         name: capability.label,
@@ -742,5 +1149,6 @@ export function providerSpecOf(id, capability) {
 }
 /** The methods an app with `access: "write"` may use on `capability` besides its read methods. */
 export function writeMethodsOf(capability) {
-    return capability.writeMethods ?? DEFAULT_WRITE_METHODS;
+    return ((capability.mode === "ai" ? undefined : capability.writeMethods) ??
+        DEFAULT_WRITE_METHODS);
 }