dsh-gateway-provider 1.0.0

package/index.js

@@ -0,0 +1,398 @@
+/**
+ * Gateway model provider plugin for DeepSeek Harness.
+ *
+ * Registers one or more `gateway:*` provider routes on `ctx.llm`, each backed
+ * by an OpenAI-compatible `/v1/models` gateway (newapi, LiteLLM, Higress, or
+ * any generic gateway), or by a fully-custom gateway whose per-protocol
+ * endpoint URLs (`openaiURL` / `responsesURL` / `anthropicURL`) are written
+ * out in full. Backwards-compatible with the original single-connection
+ * `newapi` route: the legacy flat fields (`baseURL`, `apiKeyEnv`, …) build a
+ * default gateway, while the `gateways` array adds more.
+ *
+ * Per gateway:
+ * - auto-discovers the model list (`/v1/models`, falling back to the
+ *   management `/api/user/models`), including each model's
+ *   `supported_endpoint_types`;
+ * - enriches every model with models.dev parameters (context window, output
+ *   cap, reasoning, family, release date, input modalities);
+ * - picks each model's wire protocol from its advertised endpoint types (or an
+ *   explicit per-model override) and dispatches through the pi-ai SDK's
+ *   protocol layer (openai-completions / openai-responses / anthropic-messages
+ *   / google-generative-ai).
+ *
+ * Per model (in the gateway config) the user can: disable it (hide from
+ * picker), override its context/maxTokens/reasoning, force a protocol, or add a
+ * custom model the gateway does not advertise.
+ *
+ * @module dsh-gateway-provider
+ */
+
+import z from "@deepseek-ai/schemastery";
+import { LlmError, RetryPolicySchema, assertUsableApiKey, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { deepEqualJson, installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
+import { NewapiAdapter } from "./lib/adapter.js";
+import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_MAX_TOKENS, DEFAULT_CONTEXT_WINDOW } from "./lib/catalog.js";
+import { DEFAULT_ENDPOINT_PRIORITY, deriveProtocolURLs } from "./lib/protocols.js";
+
+export const name = "llm-newapi";
+export const inject = ["llm"];
+
+/** User-settings namespace whose section overrides this entry. */
+const NS = settingsNamespace("llm-newapi");
+/** The legacy single provider route (kept for backwards compatibility). */
+export const PROVIDER = "newapi";
+/** Prefix for additional gateway routes. */
+export const GATEWAY_PREFIX = "gateway:";
+
+const DEFAULT_API_KEY_ENV = "NEWAPI_API_KEY";
+const DEFAULT_BASE_URL_ENV = "NEWAPI_BASE_URL";
+const ALT_BASE_URL_ENV = "NEWAPI_API_URL";
+/** Public newapi.ai cloud gateway; a self-hosted instance overrides it. */
+export const PUBLIC_BASE_URL = "https://api.newapi.ai";
+export const DEFAULT_MODELS_URL = "https://models.dev/models.json";
+
+// Idle cap on waiting for the next stream chunk: a gateway that stays silent
+// for this long (long reasoning / buffered thinking phases) is treated as hung.
+// 10 minutes is generous enough for very long streaming responses.
+const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 600_000;
+const DEFAULT_CATALOG_TTL_MS = 30 * 60 * 1000;
+
+/** Schema for one model-level override on a gateway (all fields optional). */
+const ModelOverrideSchema = z.object({
+  /** Model id exactly as the gateway accepts it. */
+  id: z.string(),
+  /** Display name override. */
+  name: z.string(),
+  /** Hide this model from the picker. */
+  disabled: z.boolean(),
+  /** Force the wire protocol for this model (openai/anthropic/gemini/…). */
+  protocol: z.union(["openai","openai-response","anthropic","gemini"]),
+  /** Override the context window. */
+  contextWindow: z.number().step(1).min(1),
+  /** Override the output-token cap. */
+  maxTokens: z.number().step(1).min(1),
+  /** Reasoning level set (e.g. ["off","low","medium","high"]). */
+  reasoningLevels: z.array(z.string()),
+});
+
+/** Gateway-type templates the settings UI offers (informational labels). */
+const FLAVORS = ["newapi", "litellm", "higress", "openai-compatible", "custom"];
+
+/**
+ * Schema for one gateway in the `gateways` array (id required; either
+ * `baseURL` or at least one protocol URL must be set — the rest falls back
+ * to the shared defaults at resolution time).
+ */
+const GatewaySchema = z.object({
+  /** Short stable id; becomes the provider route suffix (`gateway:<id>`). */
+  id: z.string().required(),
+  /** Human-readable gateway name. */
+  label: z.string(),
+  /** Gateway base URL (unused when protocol URL fields are set). */
+  baseURL: z.string(),
+  /** Full chat-completions endpoint URL (custom template). */
+  openaiURL: z.string(),
+  /** Full Responses endpoint URL (custom template). */
+  responsesURL: z.string(),
+  /** Full Anthropic messages endpoint URL (custom template). */
+  anthropicURL: z.string(),
+  /** Environment-variable name (credential ref) holding the API key. */
+  apiKeyEnv: z.string().role("credential-ref"),
+  /** Gateway type label (newapi/litellm/higress/openai-compatible/custom). */
+  flavor: z.union(FLAVORS),
+  /** Model-list source: `auto` (prefer /v1/models), `v1`, or `management`. */
+  catalogMode: z.union(["auto", "v1", "management"]),
+  /** User id sent to the management API when it is used. */
+  userId: z.string(),
+  /** Per-model overrides and custom models. */
+  models: z.array(ModelOverrideSchema),
+  /** Wire-format preference order for this gateway. */
+  endpointPriority: z.array(z.string()),
+});
+
+export const Config = z.object({
+  // ---- Legacy single-connection fields (build the default `newapi` route) ----
+  /** Display name of the default gateway route (defaults to "NewAPI"). */
+  label: z.string(),
+  /** Environment-variable name (credential ref) holding the default gateway API key. */
+  apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+  /** Default gateway base URL; resolved from NEWAPI_BASE_URL / NEWAPI_API_URL then the public cloud default. */
+  baseURL: z.string(),
+  /** Full chat-completions endpoint URL (custom template for the default gateway). */
+  openaiURL: z.string(),
+  /** Full Responses endpoint URL (custom template for the default gateway). */
+  responsesURL: z.string(),
+  /** Full Anthropic messages endpoint URL (custom template for the default gateway). */
+  anthropicURL: z.string(),
+  /** Gateway type label shown in the UI (newapi/litellm/higress/openai-compatible/custom). */
+  flavor: z.union(FLAVORS).default("newapi"),
+  /** models.dev catalog URL (any fetch-able URL; file: works for offline mirrors). */
+  modelsUrl: z.string().default(DEFAULT_MODELS_URL),
+  /** Enrich gateway models with models.dev parameters. */
+  useModelsDev: z.boolean().default(true),
+  /** Widen the unknown-model reasoning fallback to the full off~max set. */
+  extendedReasoningLevels: z.boolean().default(false),
+  /** Sort the picker newest-first by release date (unknown dates first). */
+  sortModelsByRelease: z.boolean().default(true),
+  /** Model-list source: `auto` (prefer /v1/models), `v1`, or `management`. */
+  catalogMode: z.union(["auto", "v1", "management"]).default("auto"),
+  /** Model-list cache freshness window. */
+  catalogTtlMs: z.number().step(1).min(1_000).default(DEFAULT_CATALOG_TTL_MS),
+  /** Exclude non-chat model families from the picker. */
+  includeChatOnly: z.boolean().default(true),
+  /** Regex patterns excluding models from the picker. */
+  excludePatterns: z.array(z.string()).default(DEFAULT_EXCLUDE_PATTERNS),
+  /** Wire-format preference order, intersected with each model's supported types. */
+  endpointPriority: z.array(z.string()).default(DEFAULT_ENDPOINT_PRIORITY),
+  /** User id sent to the management API when it is used. */
+  userId: z.string().default("1"),
+  /** Fallback output-token cap for models without models.dev data. */
+  maxTokens: z.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
+  /** Fallback context window for models without models.dev data. */
+  defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+  streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  retryPolicy: RetryPolicySchema,
+  /** Per-model overrides for the default (legacy) gateway. */
+  models: z.array(ModelOverrideSchema).default([]),
+  // ---- Additional gateways ----
+  /** Additional gateways; each becomes a `gateway:<id>` provider route. */
+  gateways: z.array(GatewaySchema).default([]),
+});
+
+/**
+ * Normalize one gateway entry into the connection facts the adapter needs.
+ * Per-gateway fields fall back to the shared defaults. Protocol URL fields
+ * (`openaiURL` / `responsesURL` / `anthropicURL`, the "custom" template)
+ * redefine the gateway's protocol surface: each configured URL becomes the
+ * exact SDK base for its wire protocol, unconfigured protocols are
+ * unavailable, and the plain `baseURL` is no longer inherited from the
+ * shared defaults (nothing may silently point at another gateway).
+ */
+function gatewayConnection(gw, defaults, provider, label) {
+  const apiKeyEnv = gw.apiKeyEnv ?? defaults.apiKeyEnv;
+  const flavor = gw.flavor ?? defaults.flavor ?? "openai-compatible";
+  const proto = deriveProtocolURLs(gw);
+  const ownBase = typeof gw.baseURL === "string" && gw.baseURL.length > 0 ? gw.baseURL.replace(/\/+$/, "") : "";
+  const baseURL = proto !== undefined ? ownBase : (ownBase || defaults.baseURL);
+  return {
+    providerId: provider,
+    displayName: label,
+    apiKeyEnv: typeof apiKeyEnv === "string" ? credentialRef(apiKeyEnv) : defaults.apiKeyEnv,
+    baseURL,
+    apiBases: proto?.apiBases,
+    availableTypes: proto?.availableTypes,
+    catalogBase: proto !== undefined ? (proto.catalogBase ?? (ownBase || null)) : baseURL,
+    flavor,
+    modelsUrl: defaults.modelsUrl,
+    useModelsDev: defaults.useModelsDev,
+    extendedReasoningLevels: defaults.extendedReasoningLevels,
+    sortModelsByRelease: defaults.sortModelsByRelease,
+    catalogMode: gw.catalogMode ?? defaults.catalogMode,
+    catalogTtlMs: defaults.catalogTtlMs,
+    includeChatOnly: defaults.includeChatOnly,
+    excludePatterns: defaults.excludePatterns,
+    endpointPriority: gw.endpointPriority ?? defaults.endpointPriority,
+    userId: gw.userId ?? defaults.userId,
+    modelOverrides: indexModelOverrides(gw.models ?? []),
+    headers: defaults.headers,
+    maxTokens: defaults.maxTokens,
+    defaultContextWindow: defaults.defaultContextWindow,
+    streamIdleTimeoutMs: defaults.streamIdleTimeoutMs,
+    retryPolicy: defaults.retryPolicy,
+  };
+}
+
+/** Index a model-override array into an id → override map (disabled excluded). */
+function indexModelOverrides(models) {
+  const map = {};
+  if (!Array.isArray(models)) return map;
+  for (const m of models) {
+    if (m === null || typeof m !== "object" || typeof m.id !== "string" || m.id.length === 0) continue;
+    map[m.id] = m;
+  }
+  return map;
+}
+
+/** Sanitize a gateway id into a stable provider-route suffix. */
+function routeIdOf(id) {
+  return String(id ?? "").trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+/** Build the gateway list and provider-route map from the resolved config. */
+export function resolveGateways(config, environment) {
+  const rootProto = deriveProtocolURLs(config);
+  const explicitBase = config.baseURL
+    ?? environment?.get(DEFAULT_BASE_URL_ENV)?.value
+    ?? environment?.get(ALT_BASE_URL_ENV)?.value;
+  // Root protocol URLs (custom template) replace the base entirely; without
+  // them the base keeps its env / public-cloud fallback chain.
+  const baseURL = rootProto !== undefined ? (explicitBase ?? "") : (explicitBase ?? PUBLIC_BASE_URL);
+  if ((typeof baseURL !== "string" || baseURL.length === 0) && rootProto === undefined) {
+    throw new Error('llm-newapi: baseURL must be a non-empty string (set llm-newapi.baseURL in settings or export NEWAPI_BASE_URL)');
+  }
+  const defaults = {
+    apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
+    baseURL: baseURL.replace(/\/+$/, ""),
+    flavor: config.flavor ?? "newapi",
+    modelsUrl: config.modelsUrl ?? DEFAULT_MODELS_URL,
+    useModelsDev: config.useModelsDev ?? true,
+    extendedReasoningLevels: config.extendedReasoningLevels ?? false,
+    sortModelsByRelease: config.sortModelsByRelease ?? true,
+    catalogMode: config.catalogMode ?? "auto",
+    catalogTtlMs: config.catalogTtlMs ?? DEFAULT_CATALOG_TTL_MS,
+    includeChatOnly: config.includeChatOnly ?? true,
+    excludePatterns: config.excludePatterns ?? DEFAULT_EXCLUDE_PATTERNS,
+    endpointPriority: config.endpointPriority ?? DEFAULT_ENDPOINT_PRIORITY,
+    userId: config.userId ?? "1",
+    headers: config.headers,
+    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
+    defaultContextWindow: config.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
+    streamIdleTimeoutMs: config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+    retryPolicy: resolveRetryPolicy(config.retryPolicy, "llm-newapi: retryPolicy"),
+  };
+  // The legacy `newapi` route is always the first gateway, built from flat fields.
+  const defaultLabel = config.label ?? "NewAPI";
+  const gateways = [
+    { provider: PROVIDER, id: "default", label: defaultLabel, connection: gatewayConnection({
+      baseURL,
+      models: config.models ?? [],
+      openaiURL: config.openaiURL,
+      responsesURL: config.responsesURL,
+      anthropicURL: config.anthropicURL,
+    }, defaults, PROVIDER, defaultLabel) },
+  ];
+  // Additional gateways from the array.
+  for (const gw of config.gateways ?? []) {
+    const id = routeIdOf(gw.id);
+    if (id.length === 0) continue;
+    const hasBase = typeof gw.baseURL === "string" && gw.baseURL.length > 0;
+    if (!hasBase && deriveProtocolURLs(gw) === undefined) continue;
+    const provider = `${GATEWAY_PREFIX}${id}`;
+    const label = gw.label ?? provider;
+    gateways.push({
+      provider,
+      id,
+      label,
+      connection: gatewayConnection(gw, defaults, provider, label),
+    });
+  }
+  return gateways;
+}
+
+export function apply(ctx, config) {
+  let current = () => config;
+  let lastRaw;
+  let resolved = null;
+  /** Resolve (and cache) the gateway list from the current config snapshot. */
+  const resolve = () => {
+    const raw = current();
+    if (raw === lastRaw && resolved !== null) return resolved;
+    try {
+      const next = resolveGateways(raw, launchEnvironmentOf(ctx));
+      lastRaw = raw;
+      resolved = next;
+      return next;
+    } catch (error) {
+      if (resolved === null) throw error;
+      lastRaw = raw;
+      ctx.logger.error("llm-newapi: keeping the last good configuration after an invalid settings section");
+      ctx.logger.error(error);
+      return resolved;
+    }
+  };
+  resolve();
+
+  /** Adapter config: resolve the connection for one provider route. */
+  const options = (provider) => {
+    const gateways = resolve();
+    const gw = gateways.find((g) => g.provider === provider);
+    return (gw ?? gateways[0]).connection;
+  };
+  const providerInfo = (provider) => {
+    const gateways = resolve();
+    const gw = gateways.find((g) => g.provider === provider) ?? gateways[0];
+    return { id: gw.provider, name: gw.label };
+  };
+  const resolveApiKey = async (connection) => {
+    const ref = connection.apiKeyEnv;
+    const credentials = ctx.get("credentials");
+    if (credentials !== undefined) {
+      const hit = await credentials.resolve(ref);
+      if (hit !== undefined) return assertUsableApiKey(hit.value, "llm-newapi", ref);
+    } else {
+      const ambient = launchEnvironmentOf(ctx).get(ref);
+      if (ambient !== undefined && ambient.value.length > 0) return assertUsableApiKey(ambient.value, "llm-newapi", ref);
+    }
+    throw new LlmError(
+      `llm-newapi: no API key for gateway credential ref "${ref}"; store it through the credentials service (the web Models page writes it), or export ${ref} in the launching environment`,
+      "MISSING_CREDENTIAL",
+    );
+  };
+
+  const adapter = new NewapiAdapter({
+    options,
+    resolveApiKey,
+    providerInfo,
+    providerCache: new Map(),
+    resolveAttachments: () => ctx.get("attachments"),
+  });
+
+  /** Re-register the directory + adapter whenever the gateway list changes. */
+  let directory = undefined;
+  let registration = undefined;
+  let directoryFacts = undefined;
+  const ensureRegistration = () => {
+    const gateways = resolve();
+    // Include the per-protocol bases: URL-addressed (custom) gateways may
+    // share an empty plain baseURL, and URL-only edits must re-register.
+    const facts = gateways.map((g) => `${g.provider}:${g.connection.baseURL}:${g.label}:${g.connection.apiBases ? JSON.stringify(g.connection.apiBases) : ""}`);
+    if (deepEqualJson(facts, directoryFacts)) return;
+    const entries = gateways.map((g, i) => ({
+      provider: g.provider,
+      displayName: g.label,
+      settingsNs: NS,
+      settingsPath: i === 0 ? [] : ["gateways", String(g.id)],
+      declared: i > 0,
+    }));
+    const routes = gateways.map((g) => g.provider);
+    if (directory === undefined) directory = ctx.llm.registerConfigurableProviders(entries);
+    else directory.replace(entries);
+    if (registration === undefined) registration = ctx.llm.registerAdapter(routes, adapter);
+    else registration.replace(routes);
+    directoryFacts = facts;
+  };
+  ensureRegistration();
+
+  /** Expose model discovery so the web UI can fetch a gateway's model list. */
+  ctx.llm.registerModelDiscovery(NS, async (request) => {
+    const env = launchEnvironmentOf(ctx);
+    const gateways = resolve();
+    const gw = request.provider !== undefined ? gateways.find((g) => g.provider === request.provider) : gateways[0];
+    if (gw === undefined) return [];
+    // An explicit baseURL override (the settings UI's test/fetch path) wins
+    // for discovery; empty strings count as absent.
+    const reqBase = typeof request.baseURL === "string" && request.baseURL.length > 0
+      ? request.baseURL.replace(/\/+$/, "")
+      : undefined;
+    const connection = reqBase !== undefined
+      ? { ...gw.connection, baseURL: reqBase, catalogBase: reqBase }
+      : gw.connection;
+    const apiKey = request.apiKey ?? await resolveApiKey(gw.connection).catch(() => undefined);
+    const { discoverGatewayModels } = await import("./lib/catalog.js");
+    try {
+      return await discoverGatewayModels(connection, apiKey, request.signal);
+    } catch {
+      return [];
+    }
+  });
+
+  installSettingsSection(ctx, NS, Config, config, {
+    setSource: (source) => {
+      current = source;
+    },
+    onChange: ensureRegistration,
+  });
+}

package/lib/adapter.js

@@ -0,0 +1,222 @@
+/**
+ * NewapiAdapter: a pi-ai-backed LlmAdapter serving every model advertised by
+ * any configured gateway.
+ *
+ * Each gateway becomes a provider route (`gateway:<id>`, plus the legacy
+ * `newapi` route). For each request the adapter:
+ *  1. resolves the gateway's connection facts (baseURL, credential, catalog);
+ *  2. discovers the gateway's models and builds a pi-ai `Provider` whose
+ *     `Model` entries each carry the wire protocol (`api` field) pi-ai should
+ *     speak for them (openai-completions / openai-responses / anthropic-messages
+ *     / google-generative-ai);
+ *  3. converts the harness request into a pi-ai `Context`;
+ *  4. streams through pi-ai's protocol layer and translates the pi-ai event
+ *     stream back into harness `StreamChunk`s.
+ *
+ * The wire formats (OpenAI Chat Completions, OpenAI Responses, Anthropic
+ * Messages, Google Generative AI) are implemented entirely by the pi-ai SDK;
+ * this adapter owns only the gateway→pi-ai mapping and the harness↔pi-ai
+ * bridge.
+ *
+ * @module dsh-gateway-provider/adapter
+ */
+
+import {
+  LlmAdapter,
+  LlmError,
+  ReasoningEffortId,
+  contentHasImage,
+} from "@deepseek-ai/dsh-llm";
+import { idleWatchdog, timeoutOf } from "@deepseek-ai/dsh-timeout";
+import { createModels, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+import { getCatalog, listPickerModels, lookupCatalogEntry, DEFAULT_MAX_TOKENS, DEFAULT_CONTEXT_WINDOW } from "./catalog.js";
+import { buildModel, buildProvider, DEFAULT_ENDPOINT_PRIORITY } from "./pi-provider.js";
+import { effectiveEndpointTypes } from "./protocols.js";
+import { findPiModel, thinkingEffortsOf, effortsFromLevels } from "./thinking.js";
+import { toPiContext, toStreamChunks, requestHeaders } from "./pi-bridge.js";
+
+/** Default maximum idle interval while an adapter stream read is outstanding. */
+const STREAM_IDLE_TIMEOUT_CODE = "LLM_STREAM_IDLE_TIMEOUT";
+
+/** Detached display metadata for one picker model. */
+function modelInfo(provider, entry) {
+  return {
+    provider,
+    id: entry.id,
+    name: entry.name ?? entry.id,
+    ...entry.description === undefined ? {} : { description: entry.description },
+    inputModalities: entry.input ?? ["text"],
+  };
+}
+
+export class NewapiAdapter extends LlmAdapter {
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+
+  providerInfo(provider) {
+    return this.config.providerInfo(provider);
+  }
+
+  providerRetryPolicy(provider) {
+    return this.config.options(provider).retryPolicy;
+  }
+
+  async listModels(provider) {
+    const connection = this.config.options(provider);
+    const apiKey = await this.config.resolveApiKey(connection);
+    const entries = await listPickerModels(connection, apiKey);
+    return entries.map((entry) => modelInfo(provider, entry));
+  }
+
+  async resolveModel(provider, model, signal) {
+    const connection = this.config.options(provider);
+    let entry;
+    try {
+      const apiKey = await this.config.resolveApiKey(connection);
+      entry = await lookupCatalogEntry(connection, apiKey, model, signal);
+    } catch {
+      entry = undefined; // catalog failures must not break exact-model resolution
+    }
+    const configured = entry;
+    const override = connection.modelOverrides?.[model];
+    // Per-model overrides (context window / output cap) must win over the
+    // models.dev-enriched catalog, mirroring buildModel + applyModelConfig. The
+    // harness reads this `context.contextWindow` for context management, so a
+    // missing override here silently compacts on the wrong window.
+    const contextWindow = override?.contextWindow ?? configured?.contextWindow ?? connection.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW;
+    const maxTokens = override?.maxTokens ?? configured?.maxTokens ?? connection.maxTokens ?? DEFAULT_MAX_TOKENS;
+    // An explicit per-model reasoningLevels override wins over catalog inference.
+    const overrideEfforts = effortsFromLevels(override?.reasoningLevels);
+    const reasoning = overrideEfforts.length > 0
+      ? { efforts: overrideEfforts }
+      : thinkingEffortsOf(configured, findPiModel(model), { extended: connection.extendedReasoningLevels });
+    return {
+      ...configured === undefined ? { provider, id: model, name: model, inputModalities: ["text"] } : modelInfo(provider, configured),
+      context: { contextWindow },
+      defaultMaxTokens: maxTokens,
+      ...reasoning === undefined ? {} : { reasoning },
+    };
+  }
+
+  /**
+   * Build (and cache) one pi-ai Provider for a gateway connection.
+   * The provider's Model list is the gateway's discovered, enriched catalog;
+   * each model's `api` field dispatches pi-ai to the right wire protocol.
+   */
+  async piProviderOf(connection, apiKey) {
+    // Key by provider route + every base a request can hit: gateways with
+    // protocol URL fields (custom template) may share an empty plain base.
+    const cacheKey = connection.providerId + "|" + (connection.baseURL ?? "")
+      + (connection.apiBases !== undefined ? "|" + JSON.stringify(connection.apiBases) : "");
+    const cached = this.config.providerCache.get(cacheKey);
+    if (cached !== undefined && cached.apiKey === apiKey && cached.at > Date.now() - (connection.catalogTtlMs ?? 30 * 60 * 1000)) {
+      return cached.provider;
+    }
+    const entries = await getCatalog(connection, apiKey);
+    const priority = connection.endpointPriority ?? DEFAULT_ENDPOINT_PRIORITY;
+    // An explicit per-model protocol override pins the endpoint types to that
+    // single choice, so pickModelApi can no longer drift with the priority.
+    const pinnedTypes = (ov) => Array.isArray(ov?.protocol) ? ov.protocol : (typeof ov?.protocol === "string" && ov.protocol.length > 0 ? [ov.protocol] : undefined);
+    const models = [];
+    for (const entry of entries) {
+      const override = connection.modelOverrides?.[entry.id];
+      const pinned = pinnedTypes(override);
+      // URL-addressed gateways only serve their configured protocols; models
+      // that advertise none of them are dropped (unaddressable models would
+      // fail every request).
+      const types = effectiveEndpointTypes(pinned ?? entry.endpointTypes, connection.availableTypes);
+      if (types === null) continue;
+      const effective = types === entry.endpointTypes ? entry : { ...entry, endpointTypes: types };
+      models.push(buildModel(effective, connection.providerId, connection.baseURL, priority, connection, override));
+    }
+    // Apply user overrides that disable models (hide from the provider).
+    const visible = models.filter((m) => connection.modelOverrides?.[m.id]?.disabled !== true);
+    // Merge custom models declared in settings but absent from the gateway.
+    const present = new Set(visible.map((m) => m.id));
+    const custom = Object.entries(connection.modelOverrides ?? {})
+      .filter(([id, ov]) => {
+        if (present.has(id) || ov?.disabled === true) return false;
+        // A pinned custom model must also be servable on a configured protocol.
+        const pinned = pinnedTypes(ov);
+        return effectiveEndpointTypes(pinned ?? undefined, connection.availableTypes) !== null;
+      })
+      .map(([id, ov]) => {
+        const pinned = pinnedTypes(ov);
+        const types = effectiveEndpointTypes(pinned ?? undefined, connection.availableTypes);
+        return buildModel({ id, name: ov.name ?? id, endpointTypes: types }, connection.providerId, connection.baseURL, priority, connection, ov);
+      });
+    const provider = buildProvider({
+      providerId: connection.providerId,
+      displayName: connection.displayName ?? connection.providerId,
+      baseURL: connection.baseURL,
+      models: [...visible, ...custom],
+    });
+    this.config.providerCache.set(cacheKey, { provider, apiKey, at: Date.now() });
+    return provider;
+  }
+
+  async *stream(options) {
+    if (options.stop !== undefined) throw new LlmError("newapi adapter does not support GenerateOptions.stop", "UNSUPPORTED_OPTION");
+    const connection = this.config.options(options.provider);
+    const apiKey = await this.config.resolveApiKey(connection);
+
+    const consumer = new AbortController();
+    const upstream = options.signal === undefined ? consumer.signal : AbortSignal.any([options.signal, consumer.signal]);
+    const watchdog = idleWatchdog(upstream, connection.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE);
+
+    try {
+      const provider = await this.piProviderOf(connection, apiKey);
+      const models = createModels();
+      models.setProvider(provider);
+      const model = models.getModel(connection.providerId, options.model);
+      if (model === undefined) throw new LlmError(`gateway "${connection.providerId}" has no model "${options.model}"`, "UNKNOWN_MODEL");
+
+      const containsImage = options.messages.some((message) => contentHasImage(message.content));
+      if (containsImage && !model.input.includes("image")) throw new LlmError(`gateway model "${model.id}" does not support image input`, "UNSUPPORTED_CONTENT");
+      const attachments = containsImage ? this.config.resolveAttachments?.() : undefined;
+      if (containsImage && attachments === undefined) throw new LlmError("gateway image input requires the durable attachment service", "UNSUPPORTED_CONTENT");
+
+      const context = attachments === undefined ? toPiContext(options) : await toPiContext(options, attachments);
+
+      const reasoning = options.reasoningEffort === undefined
+        ? undefined
+        : (getSupportedThinkingLevels(model).some((level) => level === options.reasoningEffort) ? options.reasoningEffort : undefined);
+
+      const piStream = models.streamSimple(model, context, {
+        apiKey,
+        ...reasoning === undefined ? {} : { reasoning },
+        ...options.temperature === undefined ? {} : { temperature: options.temperature },
+        ...options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens },
+        signal: watchdog.signal,
+        headers: requestHeaders(connection.headers),
+        maxRetries: 0,
+      });
+
+      const iterator = toStreamChunks(piStream, model.contextWindow)[Symbol.asyncIterator]();
+      let exhausted = false;
+      try {
+        while (true) {
+          const result = await watchdog.next(iterator);
+          if (result.done) { exhausted = true; return; }
+          yield result.value;
+        }
+      } finally {
+        if (!exhausted) {
+          consumer.abort("gateway stream consumer stopped");
+          try { await iterator.return(undefined); } catch { /* aborted */ }
+        }
+      }
+    } catch (error) {
+      if (timeoutOf(watchdog.signal, STREAM_IDLE_TIMEOUT_CODE) !== undefined) {
+        throw new LlmError(`gateway stream idle timeout after ${connection.streamIdleTimeoutMs}ms`, "TIMEOUT", { cause: error });
+      }
+      if (options.signal?.aborted) throw new LlmError("gateway request aborted by caller", "ABORTED", { cause: error });
+      if (error instanceof LlmError) throw error;
+      throw new LlmError(`gateway API stream from ${connection.baseURL || connection.providerId} failed`, "TRANSPORT", { cause: error });
+    } finally {
+      consumer.abort("gateway stream consumer stopped");
+    }
+  }
+}