melchizedek-agents 0.9.0

package/dist/lib/models/openAiCompatibleLlm.js

@@ -0,0 +1,331 @@
+/**
+ * lib/models/openAiCompatibleLlm.ts — shared base class for every provider
+ * that speaks the OpenAI chat-completions wire format.
+ *
+ * WHY this file exists:
+ *   Separates the OpenAI chat-completions wire translation (ADK Content →
+ *   chat messages, tool-definition building, tool_call parsing, usage
+ *   accounting, reasoning surfacing) from provider specifics, so any
+ *   /chat/completions-speaking provider is a small subclass supplying only
+ *   the endpoint, auth headers, wire model name, and extra body fields.
+ *   Current subclass: Ollama (local, keyless). xAI Grok used to live here
+ *   too, but xAI's Agent Tools API is Responses-shaped, so GrokLlm now
+ *   subclasses GptLlm instead (see lib/models/grokLlm.ts).
+ *
+ * WHAT THE BASE PROVIDES (uniformly, for every subclass):
+ *   - Tool schemas normalized to lowercase JSON-Schema types
+ *     (lib/models/schemaNormalize.ts — the ADK/Gemini dialect is uppercase).
+ *   - usage → LlmResponse.usageMetadata mapping (prompt_tokens →
+ *     promptTokenCount, completion_tokens → candidatesTokenCount,
+ *     completion_tokens_details.reasoning_tokens → thoughtsTokenCount),
+ *     so traceAgentRun / traceLlmGeneration count tokens for every provider.
+ *   - Reasoning ("<think>…</think>" blocks, reasoning_content fields)
+ *     surfaced as a { text, thought: true } part in a partial response —
+ *     printers display it dimmed; it never enters session history.
+ *   - A per-request `llm.request` OpenTelemetry span (lib/observability).
+ *   - web_search handling: subclasses with native search return its body
+ *     fields from webSearchBodyFields(); those without return null and the
+ *     base omits the tool with a one-time warning + span attribute.
+ */
+import { BaseLlm } from '@google/adk';
+import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
+import { wantsWebSearch, isWebSearchSentinel, } from "../tools/webSearchTool.js";
+import { toLowercaseJsonSchema } from "./schemaNormalize.js";
+/** Splits "<think>…</think>" scratchpad from the reply. */
+export function splitThinkBlocks(text) {
+    const blocks = [];
+    const answer = text
+        .replace(/<think>([\s\S]*?)<\/think>/g, (_, inner) => {
+        blocks.push(inner.trim());
+        return '';
+    })
+        .trimStart();
+    return { reasoning: blocks.join('\n\n'), answer };
+}
+// ── OpenAiCompatibleLlm ──────────────────────────────────────────────────────
+export class OpenAiCompatibleLlm extends BaseLlm {
+    webSearchWarned = false;
+    /** Model id as the wire expects it (e.g. strip the "ollama/" namespace). */
+    wireModelName() {
+        return this.model;
+    }
+    /** Provider-specific request body fields (merged last). */
+    extraBodyFields(_llmRequest) {
+        return {};
+    }
+    /**
+     * Body fields enabling the provider's NATIVE web search, or null when the
+     * provider has none (the base then omits the tool and warns once).
+     */
+    webSearchBodyFields() {
+        return null;
+    }
+    /**
+     * Extracts reasoning from the response message. Default: "<think>" blocks
+     * in content plus the reasoning_content / reasoning fields emitted by
+     * OpenAI-compatible reasoning models.
+     */
+    extractReasoning(message) {
+        const { reasoning: thinkReasoning, answer } = splitThinkBlocks(message.content ?? '');
+        const fieldReasoning = message.reasoning_content ?? message.reasoning ?? '';
+        return {
+            reasoning: [fieldReasoning, thinkReasoning].filter(Boolean).join('\n\n'),
+            answer,
+        };
+    }
+    /** Yielded before the HTTP call when a precondition is missing (e.g. no
+     *  API key). Return undefined when ready to call. */
+    missingRequirement() {
+        return undefined;
+    }
+    /** Error response for a non-2xx HTTP status. */
+    httpError(status, detail) {
+        return {
+            errorCode: `${this.providerId().toUpperCase()}_HTTP_ERROR`,
+            errorMessage: `${this.providerId()} returned ${status}: ${detail.slice(0, 400)}`,
+        };
+    }
+    /** Error response when the endpoint can't be reached at all. */
+    unreachable(message) {
+        return {
+            errorCode: `${this.providerId().toUpperCase()}_UNREACHABLE`,
+            errorMessage: `Could not reach ${this.endpointUrl()} (${message}).`,
+        };
+    }
+    // ── Generation ─────────────────────────────────────────────────────────────
+    async *generateContentAsync(llmRequest, stream = false) {
+        yield* traceLlmGeneration({ provider: this.providerId(), model: this.model }, this.generateInner(llmRequest, stream));
+    }
+    async *generateInner(llmRequest, _stream) {
+        const missing = this.missingRequirement();
+        if (missing) {
+            yield missing;
+            return;
+        }
+        const messages = this.buildMessages(llmRequest);
+        const openAiTools = this.buildTools(llmRequest);
+        const cfg = llmRequest.config ?? {};
+        const body = {
+            model: this.wireModelName(),
+            messages,
+            stream: false,
+            ...(cfg.temperature !== undefined ? { temperature: cfg.temperature } : {}),
+            ...(cfg.topP !== undefined ? { top_p: cfg.topP } : {}),
+            ...(cfg.maxOutputTokens !== undefined
+                ? { max_tokens: cfg.maxOutputTokens }
+                : {}),
+            ...(openAiTools.length > 0 ? { tools: openAiTools } : {}),
+            // critic-style structured output: responseMimeType JSON → json mode
+            ...(cfg.responseMimeType === 'application/json'
+                ? { response_format: { type: 'json_object' } }
+                : {}),
+            ...this.extraBodyFields(llmRequest),
+        };
+        // web_search: enable the provider's native search, or omit with a warning.
+        if (wantsWebSearch(llmRequest)) {
+            const searchFields = this.webSearchBodyFields();
+            if (searchFields) {
+                Object.assign(body, searchFields);
+                setLlmSpanAttribute('llm.web_search.native', true);
+            }
+            else {
+                setLlmSpanAttribute('llm.web_search.omitted', true);
+                if (!this.webSearchWarned) {
+                    this.webSearchWarned = true;
+                    console.warn(`⚠ web_search requested but ${this.model} has no native web search — ` +
+                        'tool omitted (the agent runs without search).');
+                }
+            }
+        }
+        try {
+            const res = await fetch(this.endpointUrl(), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...this.headers() },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const detail = await res.text().catch(() => '');
+                yield this.httpError(res.status, detail);
+                return;
+            }
+            const data = await res.json();
+            const message = data.choices?.[0]?.message ?? {};
+            const usageMetadata = mapUsage(data.usage);
+            const { reasoning, answer } = this.extractReasoning(message);
+            if (reasoning) {
+                // Scratchpad, not reply: shown by printers, kept out of history.
+                yield {
+                    content: {
+                        role: 'model',
+                        parts: [{ text: reasoning, thought: true }],
+                    },
+                    partial: true,
+                };
+            }
+            const parts = [];
+            if (answer)
+                parts.push({ text: answer });
+            for (const call of message.tool_calls ?? []) {
+                let args = {};
+                try {
+                    args = JSON.parse(call.function?.arguments ?? '{}');
+                }
+                catch {
+                    args = { raw: call.function?.arguments };
+                }
+                parts.push({
+                    functionCall: {
+                        name: call.function?.name,
+                        args,
+                        id: call.id,
+                    },
+                });
+            }
+            yield {
+                content: { role: 'model', parts },
+                turnComplete: true,
+                ...(usageMetadata ? { usageMetadata } : {}),
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            yield this.unreachable(msg);
+        }
+    }
+    // ── Translation helpers ────────────────────────────────────────────────────
+    /** ADK Contents (Google GenAI format) → OpenAI-compatible chat messages. */
+    buildMessages(llmRequest) {
+        const systemParts = [];
+        const messages = [];
+        for (const content of llmRequest.contents) {
+            // ADK injects the system instruction as a 'system' role content.
+            if (content.role === 'system') {
+                const text = content.parts
+                    ?.filter((p) => p.text)
+                    .map((p) => p.text)
+                    .join('\n');
+                if (text)
+                    systemParts.push(text);
+                continue;
+            }
+            const isModel = content.role === 'model';
+            const textChunks = [];
+            const imageParts = [];
+            const toolCalls = [];
+            for (const part of content.parts ?? []) {
+                const p = part;
+                if (p.thought) {
+                    // Prior-turn scratchpad is display-only; never replay it.
+                    continue;
+                }
+                if (p.text) {
+                    textChunks.push(p.text);
+                }
+                else if (p.inlineData?.data) {
+                    // ADK inline image → OpenAI image_url data URI (vision models)
+                    const mime = p.inlineData.mimeType ?? 'image/png';
+                    imageParts.push({
+                        type: 'image_url',
+                        image_url: { url: `data:${mime};base64,${p.inlineData.data}` },
+                    });
+                }
+                else if (p.functionCall) {
+                    // ADK function_call → OpenAI assistant tool_calls entry
+                    toolCalls.push({
+                        id: p.functionCall.id ?? `call_${toolCalls.length}`,
+                        type: 'function',
+                        function: {
+                            name: p.functionCall.name,
+                            arguments: JSON.stringify(p.functionCall.args ?? {}),
+                        },
+                    });
+                }
+                else if (p.functionResponse) {
+                    // ADK function_response → OpenAI 'tool' role message
+                    messages.push({
+                        role: 'tool',
+                        tool_call_id: p.functionResponse.id ?? '',
+                        content: JSON.stringify(p.functionResponse.response ?? {}),
+                    });
+                }
+            }
+            const text = textChunks.join('\n');
+            if (isModel) {
+                if (text || toolCalls.length > 0) {
+                    messages.push({
+                        role: 'assistant',
+                        content: text || null,
+                        ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+                    });
+                }
+            }
+            else if (text || imageParts.length > 0) {
+                messages.push({
+                    role: 'user',
+                    content: imageParts.length > 0
+                        ? [...(text ? [{ type: 'text', text }] : []), ...imageParts]
+                        : text,
+                });
+            }
+        }
+        // Also pull system instruction from generateContentConfig if present
+        const configSystem = llmRequest.config?.systemInstruction;
+        if (configSystem) {
+            const text = typeof configSystem === 'string'
+                ? configSystem
+                : configSystem.parts?.map((p) => p.text).join('\n') ?? '';
+            if (text)
+                systemParts.unshift(text);
+        }
+        if (systemParts.length > 0) {
+            messages.unshift({ role: 'system', content: systemParts.join('\n\n') });
+        }
+        return messages;
+    }
+    /** ADK toolsDict → OpenAI function-tool definitions (lowercase schemas). */
+    buildTools(llmRequest) {
+        const openAiTools = [];
+        for (const [, tool] of Object.entries(llmRequest.toolsDict ?? {})) {
+            if (isWebSearchSentinel(tool))
+                continue; // handled via body fields
+            const t = tool;
+            if (t.name && t.description) {
+                openAiTools.push({
+                    type: 'function',
+                    function: {
+                        name: t.name,
+                        description: t.description,
+                        parameters: toLowercaseJsonSchema(t.parameters ?? { type: 'object', properties: {} }),
+                    },
+                });
+            }
+        }
+        return openAiTools;
+    }
+    /**
+     * Live/bidirectional streaming — not part of the OpenAI-compatible
+     * chat-completions surface. Throws to surface this clearly.
+     */
+    async connect(_llmRequest) {
+        throw new Error(`${this.constructor.name} does not support live bidirectional connections. ` +
+            'Use a Gemini model for live/streaming sessions.');
+    }
+}
+/** OpenAI-style usage → GenAI usageMetadata (undefined when absent). */
+export function mapUsage(usage) {
+    if (!usage || typeof usage !== 'object')
+        return undefined;
+    const reasoning = usage.completion_tokens_details?.reasoning_tokens;
+    return {
+        ...(usage.prompt_tokens !== undefined
+            ? { promptTokenCount: usage.prompt_tokens }
+            : {}),
+        ...(usage.completion_tokens !== undefined
+            ? { candidatesTokenCount: usage.completion_tokens }
+            : {}),
+        ...(reasoning !== undefined ? { thoughtsTokenCount: reasoning } : {}),
+        ...(usage.total_tokens !== undefined
+            ? { totalTokenCount: usage.total_tokens }
+            : {}),
+    };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * lib/models/providerMap.ts — the single source of truth mapping a model id
+ * (as declared in an agent YAML) to its provider.
+ *
+ * WHY a leaf module:
+ *   Both the LLM registry (lib/models/registry.ts) and the web-search
+ *   abstraction (lib/tools/webSearchTool.ts) need this mapping; keeping it
+ *   dependency-free avoids an import cycle between adapters and tools.
+ *
+ * Model-name conventions (see DOCUMENTATION.md §7):
+ *   claude-*   → anthropic     gpt-* / o<digit>* → openai
+ *   grok-*     → xai           ollama/<model>    → ollama (local, keyless)
+ *   everything else            → gemini (the ADK-native default)
+ */
+export type ProviderId = 'gemini' | 'anthropic' | 'openai' | 'xai' | 'ollama';
+interface ProviderInfo {
+    /** Env var holding the API key; null = keyless (local). */
+    keyEnv: string | null;
+    /** Human-readable label for logs and demo banners. */
+    label: string;
+}
+export declare const PROVIDERS: Record<ProviderId, ProviderInfo>;
+/** Maps a model id to its provider. Unknown ids default to gemini — the
+ *  ADK-native provider — matching the LLMRegistry's fallback behavior. */
+export declare function providerForModel(model: string): ProviderId;
+/** True when the provider's key is present (always true for local Ollama). */
+export declare function providerKeyPresent(provider: ProviderId): boolean;
+export {};

package/dist/lib/models/providerMap.js

@@ -0,0 +1,45 @@
+/**
+ * lib/models/providerMap.ts — the single source of truth mapping a model id
+ * (as declared in an agent YAML) to its provider.
+ *
+ * WHY a leaf module:
+ *   Both the LLM registry (lib/models/registry.ts) and the web-search
+ *   abstraction (lib/tools/webSearchTool.ts) need this mapping; keeping it
+ *   dependency-free avoids an import cycle between adapters and tools.
+ *
+ * Model-name conventions (see DOCUMENTATION.md §7):
+ *   claude-*   → anthropic     gpt-* / o<digit>* → openai
+ *   grok-*     → xai           ollama/<model>    → ollama (local, keyless)
+ *   everything else            → gemini (the ADK-native default)
+ */
+export const PROVIDERS = {
+    gemini: { keyEnv: 'GOOGLE_GENAI_API_KEY', label: 'Google Gemini' },
+    anthropic: { keyEnv: 'ANTHROPIC_API_KEY', label: 'Anthropic Claude' },
+    openai: { keyEnv: 'OPENAI_API_KEY', label: 'OpenAI GPT' },
+    xai: { keyEnv: 'XAI_API_KEY', label: 'xAI Grok' },
+    ollama: { keyEnv: null, label: 'Ollama (local)' },
+};
+/** Maps a model id to its provider. Unknown ids default to gemini — the
+ *  ADK-native provider — matching the LLMRegistry's fallback behavior. */
+export function providerForModel(model) {
+    if (/^ollama\//.test(model))
+        return 'ollama';
+    if (/^claude-/.test(model))
+        return 'anthropic';
+    if (/^gpt-/.test(model) || /^o[0-9]/.test(model))
+        return 'openai';
+    if (/^grok-/.test(model))
+        return 'xai';
+    return 'gemini';
+}
+/** True when the provider's key is present (always true for local Ollama). */
+export function providerKeyPresent(provider) {
+    const keyEnv = PROVIDERS[provider].keyEnv;
+    if (!keyEnv)
+        return true;
+    // Gemini historically accepts either env name.
+    if (provider === 'gemini') {
+        return !!(process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY);
+    }
+    return !!process.env[keyEnv];
+}

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

@@ -0,0 +1,71 @@
+/**
+ * lib/models/registry.ts — unified model routing. THE seam for model
+ * optionality: an agent's YAML declares `model`, and this module makes sure
+ * that string reaches the right provider adapter.
+ *
+ * TWO RESOLUTION PATHS, ONE PREFIX TABLE (lib/models/providerMap.ts):
+ *
+ *   1. registerAvailableProviders() — for entrypoints that pass `model` as a
+ *      STRING to LlmAgent (scripts/syndicate_chat.ts). Registers every
+ *      adapter whose credentials exist into the ADK LLMRegistry; the
+ *      registry then string-matches supportedModels patterns:
+ *        claude-*  → ClaudeLlm      gpt-* / o<digit>* → GptLlm
+ *        grok-*    → GrokLlm        ollama/<model>    → OllamaLlm
+ *        gemini-*  → TracedGemini (ADK's Gemini + llm.request spans)
+ *
+ *   2. resolveModel() — instance factory for BYOK paths (scripts/
+ *      a2a_server.ts), where a per-request API key from an HTTP header must
+ *      be injected into the adapter. Same prefix table; the YAML model
+ *      string always wins over the X-Provider header (which only selects a
+ *      DEFAULT model when the YAML omits `model` — a deprecated affordance).
+ *
+ * Register BEFORE constructing any agent: the LLMRegistry caches model→class
+ * resolution (LRU), so late registration can be masked by stale cache hits.
+ */
+import { Gemini } from '@google/adk';
+import type { BaseLlm, LlmRequest, LlmResponse } from '@google/adk';
+import { PROVIDERS, providerForModel, providerKeyPresent } from './providerMap.ts';
+import type { ProviderId } from './providerMap.ts';
+export { providerForModel, providerKeyPresent, PROVIDERS };
+export type { ProviderId };
+export declare class TracedGemini extends Gemini {
+    static readonly supportedModels: Array<string | RegExp>;
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
+    /** Tags the llm.request span (web_search = Gemini grounding), then
+     *  delegates to ADK's Gemini. Runs inside the span context. */
+    private tagAndGenerate;
+}
+export interface ProviderStatus {
+    provider: ProviderId;
+    label: string;
+    available: boolean;
+    /** Why the provider is unavailable (e.g. which env var is missing). */
+    reason?: string;
+}
+/** Availability report without side effects (used by demos and key gates). */
+export declare function providerStatuses(): ProviderStatus[];
+/**
+ * Registers every adapter whose credentials exist into the ADK LLMRegistry
+ * (Ollama unconditionally — local needs no key; Gemini always, since the
+ * registry needs a fallback class, and a missing Gemini key surfaces as a
+ * clear API error at call time). Returns the per-provider statuses so
+ * entrypoints can log which models are routable.
+ */
+export declare function registerAvailableProviders(log?: (msg: string) => void): ProviderStatus[];
+export interface ResolveModelOptions {
+    /** Per-request API key (e.g. the A2A X-Api-Key header). */
+    apiKey?: string;
+    /**
+     * DEPRECATED — the A2A X-Provider header. Only consulted when `model` is
+     * undefined, to pick that provider's default model. A model id in the
+     * YAML always wins.
+     */
+    defaultProvider?: string;
+}
+/**
+ * Resolves a model id (from YAML) to a provider adapter INSTANCE, injecting
+ * a per-request apiKey where the provider accepts one. When `model` is
+ * undefined, falls back to the default model of `defaultProvider` (or
+ * Gemini).
+ */
+export declare function resolveModel(model: string | undefined, options?: ResolveModelOptions): BaseLlm;

package/dist/lib/models/registry.js

@@ -0,0 +1,159 @@
+/**
+ * lib/models/registry.ts — unified model routing. THE seam for model
+ * optionality: an agent's YAML declares `model`, and this module makes sure
+ * that string reaches the right provider adapter.
+ *
+ * TWO RESOLUTION PATHS, ONE PREFIX TABLE (lib/models/providerMap.ts):
+ *
+ *   1. registerAvailableProviders() — for entrypoints that pass `model` as a
+ *      STRING to LlmAgent (scripts/syndicate_chat.ts). Registers every
+ *      adapter whose credentials exist into the ADK LLMRegistry; the
+ *      registry then string-matches supportedModels patterns:
+ *        claude-*  → ClaudeLlm      gpt-* / o<digit>* → GptLlm
+ *        grok-*    → GrokLlm        ollama/<model>    → OllamaLlm
+ *        gemini-*  → TracedGemini (ADK's Gemini + llm.request spans)
+ *
+ *   2. resolveModel() — instance factory for BYOK paths (scripts/
+ *      a2a_server.ts), where a per-request API key from an HTTP header must
+ *      be injected into the adapter. Same prefix table; the YAML model
+ *      string always wins over the X-Provider header (which only selects a
+ *      DEFAULT model when the YAML omits `model` — a deprecated affordance).
+ *
+ * Register BEFORE constructing any agent: the LLMRegistry caches model→class
+ * resolution (LRU), so late registration can be masked by stale cache hits.
+ */
+import { Gemini, LLMRegistry } from '@google/adk';
+import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_OLLAMA_MODEL, } from "../config.js";
+import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
+import { ClaudeLlm, registerClaudeLlm } from "./claudeLlm.js";
+import { GptLlm, registerGptLlm } from "./gptLlm.js";
+import { GrokLlm, registerGrokLlm } from "./grokLlm.js";
+import { OllamaLlm, registerOllamaLlm } from "./ollamaLlm.js";
+import { PROVIDERS, providerForModel, providerKeyPresent, } from "./providerMap.js";
+export { providerForModel, providerKeyPresent, PROVIDERS };
+// ── TracedGemini ─────────────────────────────────────────────────────────────
+// ADK's built-in Gemini adapter, wrapped so Gemini calls emit the same
+// per-request llm.request spans (tokens, latency) as every other provider.
+export class TracedGemini extends Gemini {
+    // CRITICAL: reuse Gemini's exact regex instances. The LLMRegistry dict is
+    // keyed by the regex OBJECT — registering the same instances REPLACES the
+    // built-in Gemini entries instead of adding shadowed duplicates.
+    static supportedModels = Gemini.supportedModels;
+    async *generateContentAsync(llmRequest, stream) {
+        yield* traceLlmGeneration({ provider: 'gemini', model: this.model }, this.tagAndGenerate(llmRequest, stream));
+    }
+    /** Tags the llm.request span (web_search = Gemini grounding), then
+     *  delegates to ADK's Gemini. Runs inside the span context. */
+    async *tagAndGenerate(llmRequest, stream) {
+        const hasGrounding = (llmRequest.config?.tools ?? []).some((t) => t && (t.googleSearch || t.googleSearchRetrieval));
+        if (hasGrounding)
+            setLlmSpanAttribute('llm.web_search.native', true);
+        yield* super.generateContentAsync(llmRequest, stream);
+    }
+}
+/** Availability report without side effects (used by demos and key gates). */
+export function providerStatuses() {
+    return Object.keys(PROVIDERS).map((provider) => {
+        const available = providerKeyPresent(provider);
+        return {
+            provider,
+            label: PROVIDERS[provider].label,
+            available,
+            ...(available
+                ? {}
+                : { reason: `${PROVIDERS[provider].keyEnv} not set` }),
+        };
+    });
+}
+const REGISTRARS = {
+    gemini: () => LLMRegistry.register(TracedGemini),
+    anthropic: registerClaudeLlm,
+    openai: registerGptLlm,
+    xai: registerGrokLlm,
+    ollama: registerOllamaLlm,
+};
+let providersRegistered = false;
+/**
+ * Registers every adapter whose credentials exist into the ADK LLMRegistry
+ * (Ollama unconditionally — local needs no key; Gemini always, since the
+ * registry needs a fallback class, and a missing Gemini key surfaces as a
+ * clear API error at call time). Returns the per-provider statuses so
+ * entrypoints can log which models are routable.
+ */
+export function registerAvailableProviders(log) {
+    const statuses = providerStatuses();
+    if (!providersRegistered) {
+        providersRegistered = true;
+        for (const status of statuses) {
+            if (status.available || status.provider === 'gemini') {
+                REGISTRARS[status.provider]();
+            }
+        }
+    }
+    if (log) {
+        for (const s of statuses) {
+            log(s.available
+                ? `✓ ${s.label} — active`
+                : `⚠ ${s.label} disabled (${s.reason}) — ${modelHint(s.provider)} models unavailable`);
+        }
+    }
+    return statuses;
+}
+function modelHint(provider) {
+    switch (provider) {
+        case 'anthropic':
+            return 'claude-*';
+        case 'openai':
+            return 'gpt-*/o*';
+        case 'xai':
+            return 'grok-*';
+        case 'ollama':
+            return 'ollama/*';
+        case 'gemini':
+            return 'gemini-*';
+    }
+}
+const DEFAULT_MODEL_FOR = {
+    gemini: DEFAULT_GEMINI_MODEL,
+    anthropic: DEFAULT_CLAUDE_MODEL,
+    openai: DEFAULT_GPT_MODEL,
+    xai: DEFAULT_GROK_MODEL,
+    ollama: DEFAULT_OLLAMA_MODEL,
+};
+/**
+ * Resolves a model id (from YAML) to a provider adapter INSTANCE, injecting
+ * a per-request apiKey where the provider accepts one. When `model` is
+ * undefined, falls back to the default model of `defaultProvider` (or
+ * Gemini).
+ */
+export function resolveModel(model, options = {}) {
+    const resolved = model ??
+        DEFAULT_MODEL_FOR[normalizeProvider(options.defaultProvider)];
+    // BYOK is scoped to the CALLER'S provider: the X-API-Key a client sends
+    // authenticates that client's own provider (typically Gemini). Passing it
+    // to a different provider's adapter would override the server's env key
+    // (adapters prefer a passed key) and fail auth — e.g. a Gemini key sent to
+    // xAI. Cross-provider agents therefore resolve keys from server env.
+    const apiKey = providerForModel(model ?? DEFAULT_MODEL_FOR[normalizeProvider(options.defaultProvider)]) === normalizeProvider(options.defaultProvider)
+        ? options.apiKey
+        : undefined;
+    switch (providerForModel(resolved)) {
+        case 'ollama':
+            return new OllamaLlm({ model: resolved });
+        case 'anthropic':
+            return new ClaudeLlm({ model: resolved, apiKey });
+        case 'openai':
+            return new GptLlm({ model: resolved, apiKey });
+        case 'xai':
+            return new GrokLlm({ model: resolved, apiKey });
+        case 'gemini':
+            return new TracedGemini({ model: resolved, apiKey });
+    }
+}
+function normalizeProvider(provider) {
+    const p = provider?.toLowerCase();
+    if (p === 'ollama' || p === 'anthropic' || p === 'openai' || p === 'xai') {
+        return p;
+    }
+    return 'gemini';
+}

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

@@ -0,0 +1,22 @@
+/**
+ * lib/models/schemaNormalize.ts — JSON-Schema dialect bridge.
+ *
+ * WHY this file exists:
+ *   The ADK is Gemini-native, and Gemini's Schema type spells JSON-Schema
+ *   types in UPPERCASE ('OBJECT', 'STRING', …). Every other provider this
+ *   framework routes to (Anthropic, OpenAI, xAI, Ollama's OpenAI-compatible
+ *   endpoint) requires standard lowercase JSON-Schema types and rejects the
+ *   Gemini spelling — Anthropic, for example, with:
+ *     400 invalid_request_error: tools.N.custom.input_schema.type:
+ *         Input should be 'object'
+ *   Tools are declared once (YAML / MCP discovery) in the Gemini dialect, so
+ *   every non-Gemini adapter runs its tool schemas through this function at
+ *   request-build time. See DOCUMENTATION.md §7.1.
+ */
+/**
+ * Deep-clones a Gemini/ADK-style JSON schema, lowercasing every `type` value
+ * ('OBJECT' → 'object', ['STRING','NULL'] → ['string','null']) while leaving
+ * `description`, `enum`, `required`, `format`, and unknown keywords untouched.
+ * Never mutates the input — a Gemini agent may hold the same tool object.
+ */
+export declare function toLowercaseJsonSchema(schema: unknown): Record<string, unknown>;