melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/models/endpoints.js

@@ -0,0 +1,282 @@
+/**
+ * lib/models/endpoints.ts — where each provider's requests go and how they
+ * authenticate (ADR 0023).
+ *
+ * The model id still picks the provider (lib/models/providerMap.ts). This
+ * module picks the provider's PLATFORM: its own public API, or the cloud an
+ * enterprise reaches it through, plus a base URL for an internal proxy and a
+ * map from the YAML id to the id (or deployment) that platform knows.
+ *
+ *   provider   platforms                 credential on a cloud platform
+ *   gemini     direct | vertex           Google Application Default Credentials
+ *   anthropic  direct | bedrock | vertex AWS credential chain / Google ADC
+ *   openai     direct | azure            AZURE_OPENAI_API_KEY, else Entra ID
+ *   xai, ollama direct only
+ *
+ * Configuration comes from the environment (`endpointFromEnv`) or, per
+ * request, from the server's `credentials` plug point, which may return an
+ * API key or a partial endpoint merged over the environment's.
+ *
+ * The Vertex AI, Bedrock and Azure paths are built on each vendor SDK's own
+ * client for that platform and are tested against mocks; they have not been
+ * run against the live clouds from this repository. The doctor says so.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { PROVIDERS, providerKeyPresent } from './providerMap.js';
+export const PLATFORMS_FOR = {
+    gemini: ['direct', 'vertex'],
+    anthropic: ['direct', 'bedrock', 'vertex'],
+    openai: ['direct', 'azure'],
+    xai: ['direct'],
+    ollama: ['direct'],
+};
+const PLATFORM_ENV = {
+    gemini: 'GEMINI_PLATFORM',
+    anthropic: 'ANTHROPIC_PLATFORM',
+    openai: 'OPENAI_PLATFORM',
+};
+const MODEL_MAP_ENV = {
+    gemini: 'GEMINI_MODEL_MAP',
+    anthropic: 'ANTHROPIC_MODEL_MAP',
+    openai: 'OPENAI_MODEL_MAP',
+};
+const trimmed = (v) => (v && v.trim() ? v.trim() : undefined);
+function parseModelMap(raw, name) {
+    if (!trimmed(raw))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${name} must be a JSON object of model id → platform id.`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || Object.values(parsed).some((v) => typeof v !== 'string')) {
+        throw new Error(`${name} must be a JSON object of model id → platform id.`);
+    }
+    return parsed;
+}
+/** The platform the environment selects for a provider (default direct). */
+export function platformFromEnv(provider, env = process.env) {
+    const name = PLATFORM_ENV[provider];
+    const raw = name ? trimmed(env[name])?.toLowerCase() : undefined;
+    // @google/genai's own switch selects Vertex too, so honour it rather than
+    // run a Vertex-configured process against AI Studio.
+    if (!raw && provider === 'gemini' && /^(1|true)$/i.test(env.GOOGLE_GENAI_USE_VERTEXAI ?? ''))
+        return 'vertex';
+    if (!raw)
+        return 'direct';
+    if (!PLATFORMS_FOR[provider].includes(raw)) {
+        throw new Error(`${name}=${raw} is not a platform for ${PROVIDERS[provider].label}; use one of ${PLATFORMS_FOR[provider].join(', ')}.`);
+    }
+    return raw;
+}
+/** A provider's endpoint as the environment configures it. */
+export function endpointFromEnv(provider, env = process.env) {
+    const platform = platformFromEnv(provider, env);
+    const mapEnv = MODEL_MAP_ENV[provider];
+    const models = mapEnv ? parseModelMap(env[mapEnv], mapEnv) : undefined;
+    const base = { platform, ...(models ? { models } : {}) };
+    switch (`${provider}/${platform}`) {
+        case 'gemini/vertex':
+            return { ...base, project: trimmed(env.GOOGLE_CLOUD_PROJECT), location: trimmed(env.GOOGLE_CLOUD_LOCATION) };
+        case 'anthropic/vertex':
+            return {
+                ...base,
+                project: trimmed(env.ANTHROPIC_VERTEX_PROJECT_ID) ?? trimmed(env.GOOGLE_CLOUD_PROJECT),
+                location: trimmed(env.CLOUD_ML_REGION) ?? trimmed(env.GOOGLE_CLOUD_LOCATION),
+            };
+        case 'anthropic/bedrock':
+            return { ...base, region: trimmed(env.AWS_REGION) ?? trimmed(env.AWS_DEFAULT_REGION) };
+        case 'anthropic/direct':
+            return { ...base, ...(trimmed(env.ANTHROPIC_BASE_URL) ? { baseURL: trimmed(env.ANTHROPIC_BASE_URL) } : {}) };
+        case 'openai/direct':
+            return { ...base, ...(trimmed(env.OPENAI_BASE_URL) ? { baseURL: trimmed(env.OPENAI_BASE_URL) } : {}) };
+        case 'openai/azure': {
+            const endpoint = trimmed(env.AZURE_OPENAI_ENDPOINT);
+            const key = trimmed(env.AZURE_OPENAI_API_KEY);
+            return {
+                ...base,
+                ...(endpoint ? { baseURL: azureBaseURL(endpoint) } : {}),
+                ...(key ? { apiKey: key } : {}),
+            };
+        }
+        default:
+            return base;
+    }
+}
+/** Azure OpenAI's v1 API, which the plain OpenAI client speaks. */
+export function azureBaseURL(endpoint) {
+    const root = endpoint.replace(/\/+$/, '').replace(/\/openai(\/v1)?$/, '');
+    return `${root}/openai/v1/`;
+}
+/** The id to send: the platform's name for a YAML model id. */
+export function platformModel(endpoint, model) {
+    return endpoint?.models?.[model] ?? model;
+}
+/** What is missing for an endpoint to be usable; empty when complete. */
+export function endpointProblems(provider, e) {
+    const problems = [];
+    switch (`${provider}/${e.platform}`) {
+        case 'gemini/vertex':
+        case 'anthropic/vertex':
+            if (!e.project)
+                problems.push(provider === 'gemini' ? 'GOOGLE_CLOUD_PROJECT not set' : 'ANTHROPIC_VERTEX_PROJECT_ID (or GOOGLE_CLOUD_PROJECT) not set');
+            if (!e.location)
+                problems.push(provider === 'gemini' ? 'GOOGLE_CLOUD_LOCATION not set' : 'CLOUD_ML_REGION (or GOOGLE_CLOUD_LOCATION) not set');
+            break;
+        case 'anthropic/bedrock':
+            if (!e.region)
+                problems.push('AWS_REGION not set');
+            break;
+        case 'openai/azure':
+            if (!e.baseURL)
+                problems.push('AZURE_OPENAI_ENDPOINT not set');
+            break;
+    }
+    return problems;
+}
+/**
+ * True when a provider can be called: its key is present on the direct
+ * platform, or its cloud platform is fully configured (the cloud's own
+ * credential chain is then trusted to authenticate; the doctor says it was
+ * not checked).
+ */
+export function providerReady(provider) {
+    let e;
+    try {
+        e = endpointFromEnv(provider);
+    }
+    catch {
+        return false;
+    }
+    if (e.platform === 'direct')
+        return providerKeyPresent(provider);
+    return endpointProblems(provider, e).length === 0;
+}
+/** Merge a per-request endpoint (the credentials plug point) over the environment's. */
+export function mergeEndpoint(provider, override) {
+    const fromEnv = endpointFromEnv(provider);
+    if (!override)
+        return fromEnv;
+    if (override.platform && override.platform !== fromEnv.platform) {
+        // A different platform shares nothing with the environment's settings.
+        return { ...override, platform: override.platform };
+    }
+    return { ...fromEnv, ...override, platform: fromEnv.platform };
+}
+/** The label for logs and the doctor: "Claude on Bedrock (us-east-1)". */
+export function endpointLabel(provider, e) {
+    const where = e.platform === 'vertex'
+        ? `Vertex AI${e.project ? ` (${e.project}, ${e.location ?? '?'})` : ''}`
+        : e.platform === 'bedrock'
+            ? `Bedrock${e.region ? ` (${e.region})` : ''}`
+            : e.platform === 'azure'
+                ? `Azure OpenAI${e.baseURL ? ` (${new URL(e.baseURL).host})` : ''}`
+                : e.baseURL
+                    ? `proxy ${safeHost(e.baseURL)}`
+                    : 'direct';
+    return `${PROVIDERS[provider].label} on ${where}`;
+}
+function safeHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return '(invalid URL)';
+    }
+}
+/** How a cloud platform authenticates, for the doctor. */
+export function credentialSource(provider, e) {
+    if (e.platform === 'vertex')
+        return 'Google Application Default Credentials';
+    if (e.platform === 'bedrock')
+        return 'the AWS credential chain';
+    if (e.platform === 'azure')
+        return e.apiKey ? 'AZURE_OPENAI_API_KEY' : e.token ? 'a token callback' : 'Entra ID (@azure/identity)';
+    return PROVIDERS[provider].keyEnv ?? 'none (local)';
+}
+/** The vendor SDK package a platform needs, beyond the direct one. */
+export const PLATFORM_SDK = {
+    'anthropic/bedrock': '@anthropic-ai/bedrock-sdk',
+    'anthropic/vertex': '@anthropic-ai/vertex-sdk',
+};
+let sdkImporter = (module) => import(__rewriteRelativeImportExtension(module));
+/**
+ * Replace how vendor SDKs are imported: for tests (a mock Bedrock client)
+ * and for bundlers that need static imports. Undefined restores the default.
+ */
+export function setSdkImporter(importer) {
+    sdkImporter = importer ?? ((module) => import(__rewriteRelativeImportExtension(module)));
+}
+/** Import a spec's module and construct its client. Throws SdkMissingError when absent. */
+export async function instantiateClient(spec) {
+    let mod;
+    try {
+        mod = await sdkImporter(spec.module);
+    }
+    catch {
+        throw new SdkMissingError(spec.module);
+    }
+    const Ctor = spec.exportNames.map((n) => mod?.[n]).find((c) => typeof c === 'function');
+    if (!Ctor)
+        throw new Error(`${spec.module} exports none of ${spec.exportNames.join(', ')}.`);
+    return new Ctor(spec.options);
+}
+export class SdkMissingError extends Error {
+    module;
+    constructor(module) {
+        super(`The ${module} package is not installed. Run: npm install ${module}`);
+        this.module = module;
+    }
+}
+/** The Anthropic client for an endpoint, or why it cannot be built. */
+export function claudeClientSpec(e, apiKey) {
+    const problems = endpointProblems('anthropic', e);
+    if (problems.length)
+        return { error: `Claude on ${e.platform}: ${problems.join('; ')}.` };
+    switch (e.platform) {
+        case 'bedrock':
+            return { module: '@anthropic-ai/bedrock-sdk', exportNames: ['AnthropicBedrock', 'default'], options: { awsRegion: e.region } };
+        case 'vertex':
+            return { module: '@anthropic-ai/vertex-sdk', exportNames: ['AnthropicVertex', 'default'], options: { projectId: e.project, region: e.location } };
+        default:
+            if (!apiKey)
+                return { error: 'ANTHROPIC_API_KEY is not set in environment.' };
+            return { module: '@anthropic-ai/sdk', exportNames: ['default', 'Anthropic'], options: { apiKey, ...(e.baseURL ? { baseURL: e.baseURL } : {}) } };
+    }
+}
+/** The scope Azure OpenAI tokens are issued for. */
+export const AZURE_COGNITIVE_SCOPE = 'https://cognitiveservices.azure.com/.default';
+let entraProvider;
+/**
+ * A bearer-token source from Entra ID (DefaultAzureCredential: managed
+ * identity, workload identity, the Azure CLI...), shared by every client in
+ * the process so tokens are cached and refreshed once.
+ */
+export function entraTokenSource() {
+    return async () => {
+        entraProvider ??= sdkImporter('@azure/identity').then((m) => m.getBearerTokenProvider(new m.DefaultAzureCredential(), AZURE_COGNITIVE_SCOPE), () => {
+            entraProvider = undefined;
+            throw new Error('Azure OpenAI without AZURE_OPENAI_API_KEY authenticates with Entra ID through @azure/identity, which is not installed. Run: npm install @azure/identity');
+        });
+        return (await entraProvider)();
+    };
+}
+/** Platforms whose adapter does not send the provider's native web search. */
+export function nativeSearchOn(provider, platform) {
+    if (platform === 'direct')
+        return true;
+    // Gemini grounding is a Vertex AI feature as much as an AI Studio one.
+    // Anthropic's server-side web search and OpenAI's web_search tool are not
+    // sent on Bedrock, Claude-on-Vertex or Azure: availability there varies by
+    // region and version and has not been verified from this repository.
+    return provider === 'gemini';
+}

package/dist/lib/models/gateway.d.ts

@@ -0,0 +1,107 @@
+/**
+ * lib/models/gateway.ts — the optional "one key" transport.
+ *
+ * WHY this file exists:
+ *   A newcomer should be able to run every starter-pack syndicate with ONE
+ *   credential when they choose to. A hosted gateway (Vercel AI Gateway,
+ *   OpenRouter) fronts OpenAI, Anthropic, Google and xAI behind a single
+ *   OpenAI-compatible endpoint, so a model id whose direct key is absent can
+ *   still be served. This module owns that decision and nothing else.
+ *
+ * THE RULE (plans/model-access-tiers.md, ADR 0012):
+ *   Direct adapters are canonical. A model id routes to its provider's own
+ *   adapter whenever that provider's key is present. Only when the key is
+ *   ABSENT and a gateway is configured does the id route through the
+ *   gateway. Ollama never does. So the gateway is a fallback, never a
+ *   preempt: adding a direct key beside the gateway key silently upgrades
+ *   that provider's agents back to native fidelity (Gemini grounding, xAI
+ *   search, Anthropic's server-side web_search) with no YAML change.
+ *
+ * WHAT A GATEWAY LOSES — reported, never silent:
+ *   Every server-side tool sentinel (web_search, google_search, x_search,
+ *   collections_search) is dropped on the gateway path, because a
+ *   chat-completions endpoint has no uniform way to enable a provider's
+ *   native search. lib/models/capabilities.ts turns that into a per-agent
+ *   report the doctor, the A2A startup log and the ledger all read.
+ *
+ * WHY a leaf (imports providerMap and endpoints only):
+ *   The registry, the gateway adapter, the capability report and the
+ *   doctor all need this decision; keeping it free of adapter imports
+ *   avoids the cycle model-routing warns about.
+ *
+ * Env (deployment config, never YAML):
+ *   MODEL_GATEWAY          vercel | openrouter   (unset = off, the default)
+ *   MODEL_GATEWAY_API_KEY  the gateway's key
+ *   MODEL_GATEWAY_BASE_URL optional endpoint override (self-hosted proxies
+ *                          that speak the same dialect, e.g. LiteLLM)
+ *   MODEL_GATEWAY_MODEL_MAP optional "from=to,from=to" wire-name overrides
+ *                          for ids the default mapper gets wrong
+ */
+import type { ProviderId } from './providerMap.ts';
+export type GatewayId = 'vercel' | 'openrouter';
+/** Providers a gateway can front (everything cloud; never Ollama). */
+export type CloudProviderId = Exclude<ProviderId, 'ollama'>;
+export interface GatewayInfo {
+    id: GatewayId;
+    label: string;
+    /** OpenAI-compatible base URL (chat/completions is appended). */
+    baseUrl: string;
+    /** Where the operator creates the key. */
+    consoleUrl: string;
+    /** The gateway's slug for each upstream provider, e.g. "x-ai" vs "xai". */
+    slugs: Record<CloudProviderId, string>;
+}
+export declare const GATEWAY_ENV = "MODEL_GATEWAY";
+export declare const GATEWAY_KEY_ENV = "MODEL_GATEWAY_API_KEY";
+export declare const GATEWAY_BASE_URL_ENV = "MODEL_GATEWAY_BASE_URL";
+export declare const GATEWAY_MODEL_MAP_ENV = "MODEL_GATEWAY_MODEL_MAP";
+export declare const GATEWAYS: Record<GatewayId, GatewayInfo>;
+export interface GatewayConfig {
+    gateway: GatewayInfo;
+    /** Effective base URL (env override or the gateway's default). */
+    baseUrl: string;
+    keyPresent: boolean;
+}
+/**
+ * The configured gateway, or null when MODEL_GATEWAY is unset. A set but
+ * unknown value also yields null — `gatewayProblem()` says why, so the
+ * doctor and the registry log can name the mistake instead of routing
+ * silently to nothing.
+ */
+export declare function gatewayConfig(): GatewayConfig | null;
+/** A human-readable misconfiguration, or undefined when the gateway is
+ *  either off or usable. */
+export declare function gatewayProblem(): string | undefined;
+/** True when a gateway is configured well enough to serve requests. */
+export declare function gatewayUsable(): boolean;
+/**
+ * The id a gateway expects for a YAML model id.
+ *
+ * Gateways prefix every id with the upstream provider's slug and spell
+ * Anthropic's version segment with a dot ("claude-sonnet-4-6" is
+ * "anthropic/claude-sonnet-4.6" on both Vercel and OpenRouter). Gemini,
+ * GPT and Grok ids already carry dots, so only the prefix is added. An id
+ * the mapper gets wrong is fixed in MODEL_GATEWAY_MODEL_MAP, not in code.
+ */
+export declare function gatewayWireModel(model: string, gateway: GatewayInfo): string;
+export type Transport = 'direct' | 'gateway';
+export interface TransportPlan {
+    provider: ProviderId;
+    transport: Transport;
+    /** Set when transport is 'gateway'. */
+    gateway?: GatewayInfo;
+    /** True when this transport has a credential (or needs none). */
+    funded: boolean;
+    /** The direct key env, for the "set X to unlock" message. */
+    keyEnv: string | null;
+}
+/**
+ * Where a model id will be served from under the current environment.
+ *
+ * `callerKey` is the A2A BYOK case: a per-request key the caller sent for
+ * its own provider counts as that provider's key being present, so a BYOK
+ * request never falls through to the operator's gateway.
+ */
+export declare function planTransport(model: string, opts?: {
+    callerKey?: boolean;
+}): TransportPlan;

package/dist/lib/models/gateway.js

@@ -0,0 +1,157 @@
+/**
+ * lib/models/gateway.ts — the optional "one key" transport.
+ *
+ * WHY this file exists:
+ *   A newcomer should be able to run every starter-pack syndicate with ONE
+ *   credential when they choose to. A hosted gateway (Vercel AI Gateway,
+ *   OpenRouter) fronts OpenAI, Anthropic, Google and xAI behind a single
+ *   OpenAI-compatible endpoint, so a model id whose direct key is absent can
+ *   still be served. This module owns that decision and nothing else.
+ *
+ * THE RULE (plans/model-access-tiers.md, ADR 0012):
+ *   Direct adapters are canonical. A model id routes to its provider's own
+ *   adapter whenever that provider's key is present. Only when the key is
+ *   ABSENT and a gateway is configured does the id route through the
+ *   gateway. Ollama never does. So the gateway is a fallback, never a
+ *   preempt: adding a direct key beside the gateway key silently upgrades
+ *   that provider's agents back to native fidelity (Gemini grounding, xAI
+ *   search, Anthropic's server-side web_search) with no YAML change.
+ *
+ * WHAT A GATEWAY LOSES — reported, never silent:
+ *   Every server-side tool sentinel (web_search, google_search, x_search,
+ *   collections_search) is dropped on the gateway path, because a
+ *   chat-completions endpoint has no uniform way to enable a provider's
+ *   native search. lib/models/capabilities.ts turns that into a per-agent
+ *   report the doctor, the A2A startup log and the ledger all read.
+ *
+ * WHY a leaf (imports providerMap and endpoints only):
+ *   The registry, the gateway adapter, the capability report and the
+ *   doctor all need this decision; keeping it free of adapter imports
+ *   avoids the cycle model-routing warns about.
+ *
+ * Env (deployment config, never YAML):
+ *   MODEL_GATEWAY          vercel | openrouter   (unset = off, the default)
+ *   MODEL_GATEWAY_API_KEY  the gateway's key
+ *   MODEL_GATEWAY_BASE_URL optional endpoint override (self-hosted proxies
+ *                          that speak the same dialect, e.g. LiteLLM)
+ *   MODEL_GATEWAY_MODEL_MAP optional "from=to,from=to" wire-name overrides
+ *                          for ids the default mapper gets wrong
+ */
+import { providerReady } from './endpoints.js';
+import { PROVIDERS, providerForModel } from './providerMap.js';
+export const GATEWAY_ENV = 'MODEL_GATEWAY';
+export const GATEWAY_KEY_ENV = 'MODEL_GATEWAY_API_KEY';
+export const GATEWAY_BASE_URL_ENV = 'MODEL_GATEWAY_BASE_URL';
+export const GATEWAY_MODEL_MAP_ENV = 'MODEL_GATEWAY_MODEL_MAP';
+export const GATEWAYS = {
+    vercel: {
+        id: 'vercel',
+        label: 'Vercel AI Gateway',
+        baseUrl: 'https://ai-gateway.vercel.sh/v1',
+        consoleUrl: 'https://vercel.com/ai-gateway',
+        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'xai' },
+    },
+    openrouter: {
+        id: 'openrouter',
+        label: 'OpenRouter',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        consoleUrl: 'https://openrouter.ai/keys',
+        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'x-ai' },
+    },
+};
+/**
+ * The configured gateway, or null when MODEL_GATEWAY is unset. A set but
+ * unknown value also yields null — `gatewayProblem()` says why, so the
+ * doctor and the registry log can name the mistake instead of routing
+ * silently to nothing.
+ */
+export function gatewayConfig() {
+    const id = (process.env[GATEWAY_ENV] ?? '').trim().toLowerCase();
+    if (!id)
+        return null;
+    const gateway = GATEWAYS[id];
+    if (!gateway)
+        return null;
+    const override = (process.env[GATEWAY_BASE_URL_ENV] ?? '').trim();
+    return {
+        gateway,
+        baseUrl: (override || gateway.baseUrl).replace(/\/+$/, ''),
+        keyPresent: !!process.env[GATEWAY_KEY_ENV],
+    };
+}
+/** A human-readable misconfiguration, or undefined when the gateway is
+ *  either off or usable. */
+export function gatewayProblem() {
+    const id = (process.env[GATEWAY_ENV] ?? '').trim();
+    if (!id)
+        return undefined;
+    const cfg = gatewayConfig();
+    if (!cfg) {
+        return `${GATEWAY_ENV}=${id} is not a known gateway (expected one of: ${Object.keys(GATEWAYS).join(', ')})`;
+    }
+    if (!cfg.keyPresent)
+        return `${GATEWAY_ENV}=${cfg.gateway.id} is set but ${GATEWAY_KEY_ENV} is not`;
+    return undefined;
+}
+/** True when a gateway is configured well enough to serve requests. */
+export function gatewayUsable() {
+    const cfg = gatewayConfig();
+    return !!cfg && cfg.keyPresent;
+}
+/** Parses "a=b,c=d" into a map; malformed pairs are skipped. */
+function modelMapFromEnv() {
+    const raw = process.env[GATEWAY_MODEL_MAP_ENV] ?? '';
+    const map = {};
+    for (const pair of raw.split(',')) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const from = pair.slice(0, eq).trim();
+        const to = pair.slice(eq + 1).trim();
+        if (from && to)
+            map[from] = to;
+    }
+    return map;
+}
+/**
+ * The id a gateway expects for a YAML model id.
+ *
+ * Gateways prefix every id with the upstream provider's slug and spell
+ * Anthropic's version segment with a dot ("claude-sonnet-4-6" is
+ * "anthropic/claude-sonnet-4.6" on both Vercel and OpenRouter). Gemini,
+ * GPT and Grok ids already carry dots, so only the prefix is added. An id
+ * the mapper gets wrong is fixed in MODEL_GATEWAY_MODEL_MAP, not in code.
+ */
+export function gatewayWireModel(model, gateway) {
+    const override = modelMapFromEnv()[model];
+    if (override)
+        return override;
+    if (model.includes('/'))
+        return model; // already provider-qualified
+    const provider = providerForModel(model);
+    if (provider === 'ollama')
+        return model;
+    const slug = gateway.slugs[provider];
+    const wire = provider === 'anthropic' ? model.replace(/-(\d+)-(\d+)/, '-$1.$2') : model;
+    return `${slug}/${wire}`;
+}
+/**
+ * Where a model id will be served from under the current environment.
+ *
+ * `callerKey` is the A2A BYOK case: a per-request key the caller sent for
+ * its own provider counts as that provider's key being present, so a BYOK
+ * request never falls through to the operator's gateway.
+ */
+export function planTransport(model, opts = {}) {
+    const provider = providerForModel(model);
+    const keyEnv = PROVIDERS[provider].keyEnv;
+    const direct = providerReady(provider) || !!opts.callerKey;
+    if (direct || provider === 'ollama') {
+        return { provider, transport: 'direct', funded: true, keyEnv };
+    }
+    const cfg = gatewayConfig();
+    if (cfg && cfg.keyPresent) {
+        return { provider, transport: 'gateway', gateway: cfg.gateway, funded: true, keyEnv };
+    }
+    return { provider, transport: 'direct', funded: false, keyEnv };
+}

package/dist/lib/models/gatewayLlm.d.ts

@@ -0,0 +1,57 @@
+/**
+ * lib/models/gatewayLlm.ts — the one-key fallback adapter.
+ *
+ * WHY this file exists:
+ *   Serves any cloud model id through a hosted gateway's OpenAI-compatible
+ *   chat-completions endpoint when the provider's direct key is absent
+ *   (lib/models/gateway.ts owns that decision). It subclasses the
+ *   chat-completions base the way Ollama does — not GptLlm, which speaks
+ *   OpenAI's Responses API — because chat completions is the one dialect
+ *   every gateway serves.
+ *
+ * WHAT STAYS TRUE THROUGH THE GATEWAY:
+ *   - Attribution. providerId() is the YAML id's provider (anthropic,
+ *     openai, gemini, xai), never "gateway", so the ledger and any per-agent
+ *     cost view keep the same provider column (ADR 0009). The
+ *     transport is a separate span attribute: llm.transport = gateway:<id>.
+ *   - Tool calling, structured output, reasoning_effort, streaming and
+ *     token accounting — all provided by the base class.
+ *
+ * WHAT IS LOST — and reported:
+ *   Every server-side tool sentinel (web_search, google_search, x_search,
+ *   collections_search). The base omits web_search with a warning and marks
+ *   the span; lib/models/capabilities.ts names the loss per agent for the
+ *   doctor and the A2A startup log.
+ *
+ * Registration: LLMRegistry keys on regex OBJECTS, so a gateway class must
+ * carry the SAME supportedModels instances as the direct adapter it stands
+ * in for (see gatewayClassFor in registry.ts).
+ */
+import type { LlmRequest, LlmResponse } from '@google/adk';
+import { OpenAiCompatibleLlm } from './openAiCompatibleLlm.ts';
+export declare class GatewayLlm extends OpenAiCompatibleLlm {
+    /** Never registered directly — see gatewayClassFor(). */
+    static readonly supportedModels: Array<string | RegExp>;
+    private readonly cfg;
+    constructor({ model }: {
+        model: string;
+    });
+    /** Attribution stays with the upstream provider named by the YAML id. */
+    protected providerId(): string;
+    protected transport(): string;
+    protected endpointUrl(): string;
+    protected headers(): Record<string, string>;
+    protected wireModelName(): string;
+    protected missingRequirement(): LlmResponse | undefined;
+    protected httpError(status: number, detail: string): LlmResponse;
+    protected extraBodyFields(_llmRequest: LlmRequest): Record<string, unknown>;
+}
+/**
+ * A GatewayLlm subclass that answers for the given model patterns. Pass the
+ * direct adapter's OWN `supportedModels` array so the registry entry
+ * REPLACES that adapter's (the dict is keyed by regex object) rather than
+ * adding a second, shadowed match.
+ */
+export declare function gatewayClassFor(patterns: Array<string | RegExp>): typeof GatewayLlm;
+/** Registers a gateway stand-in for the given patterns. */
+export declare function registerGatewayLlm(patterns: Array<string | RegExp>): void;