melchizedek-agents 0.9.0

package/dist/lib/models/gptLlm.js

@@ -0,0 +1,497 @@
+/**
+ * lib/models/gptLlm.ts — OpenAI GPT provider for the ADK LLMRegistry.
+ *
+ * WHY this file exists:
+ *   Model optionality: any agent YAML with model: "gpt-*" (or an o-series
+ *   id like "o4-mini") routes here after registration. Unlike Grok/Ollama
+ *   this adapter does NOT reuse the chat-completions base class — it speaks
+ *   OpenAI's Responses API through the official `openai` SDK, because the
+ *   Responses API is where OpenAI exposes reasoning summaries (the model's
+ *   thinking, surfaced as { thought: true } parts here) and the first-class
+ *   `web_search` tool this framework's web_search abstraction maps to.
+ *
+ * HOW TO ENABLE:
+ *   1. Install the SDK (already in package.json):  npm install
+ *   2. Add your API key to .env:  OPENAI_API_KEY=sk-...
+ *   3. Set model: "gpt-5-mini" (or any gpt-* / o-series id) in your YAML.
+ *   registerAvailableProviders() registers this adapter when the key is set.
+ *
+ * CONTENT FORMAT TRANSLATION:
+ *   ADK Content/Part objects → Responses API `input` items:
+ *     user/model text        → { role, content } message items
+ *     functionCall part      → { type:'function_call', call_id, name, arguments }
+ *     functionResponse part  → { type:'function_call_output', call_id, output }
+ *   The call_id round-trip matters: this adapter emits functionCall.id so
+ *   ADK echoes it back on the tool response, and the Responses API requires
+ *   function_call_output.call_id to match the originating call.
+ *
+ *   Response `output` items map back:
+ *     'reasoning' summary    → { text, thought: true } partial (display-only)
+ *     'message' output_text  → text part
+ *     'function_call'        → functionCall part
+ *   usage.input_tokens / output_tokens / output_tokens_details.reasoning_tokens
+ *   → LlmResponse.usageMetadata, so token telemetry works like every provider.
+ *
+ * STREAMING (ADK stream=true, i.e. RunConfig streamingMode: SSE):
+ *   The request is sent with { stream: true }; SSE deltas
+ *   (response.output_text.delta / response.reasoning_summary_text.delta)
+ *   are yielded as { partial: true } responses — the ADK Runner displays
+ *   but does NOT persist partial events — and the terminal
+ *   response.completed payload is mapped through the same final-response
+ *   translator as the non-streaming path, carrying full content + usage
+ *   as the ONE event that lands in the session. Function calls are never
+ *   delta-streamed (both OpenAI and xAI deliver them whole).
+ */
+import { BaseLlm, LLMRegistry } from '@google/adk';
+import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
+import { wantsWebSearch, isWebSearchSentinel, xaiWebSearchParamsFromEnv, } from "../tools/webSearchTool.js";
+import { wantsXSearch, isXSearchSentinel, xSearchParamsFromEnv, } from "../tools/xSearchTool.js";
+import { wantsCollectionsSearch, isCollectionsSearchSentinel, collectionIdsFromEnv, collectionsMaxResultsFromEnv, } from "../tools/collectionsSearchTool.js";
+import { providerForModel } from "./providerMap.js";
+import { toLowercaseJsonSchema } from "./schemaNormalize.js";
+/** Reasoning-capable ids: o-series and the gpt-5 family. The reasoning
+ *  param is also dropped and retried once on a 400, so a miss here only
+ *  costs one extra round trip. */
+function isReasoningModel(model) {
+    return /^o[0-9]/.test(model) || /^gpt-5/.test(model);
+}
+// ── Request building (exported for offline tests) ────────────────────────────
+/** ADK Contents → Responses API `input` items + `instructions` string. */
+export function buildResponsesInput(llmRequest) {
+    const systemParts = [];
+    const input = [];
+    for (const content of llmRequest.contents) {
+        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 role = content.role === 'model' ? 'assistant' : 'user';
+        const contentParts = [];
+        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) {
+                contentParts.push({
+                    type: role === 'assistant' ? 'output_text' : 'input_text',
+                    text: p.text,
+                });
+            }
+            else if (p.inlineData?.data && role === 'user') {
+                const mime = p.inlineData.mimeType ?? 'image/png';
+                contentParts.push({
+                    type: 'input_image',
+                    image_url: `data:${mime};base64,${p.inlineData.data}`,
+                });
+            }
+            else if (p.functionCall) {
+                input.push({
+                    type: 'function_call',
+                    call_id: p.functionCall.id ?? `call_${input.length}`,
+                    name: p.functionCall.name,
+                    arguments: JSON.stringify(p.functionCall.args ?? {}),
+                });
+            }
+            else if (p.functionResponse) {
+                input.push({
+                    type: 'function_call_output',
+                    call_id: p.functionResponse.id ?? '',
+                    output: JSON.stringify(p.functionResponse.response ?? {}),
+                });
+            }
+        }
+        if (contentParts.length > 0) {
+            input.push({ role, content: contentParts });
+        }
+    }
+    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);
+    }
+    return {
+        instructions: systemParts.length > 0 ? systemParts.join('\n\n') : undefined,
+        input,
+    };
+}
+/** ADK toolsDict (+ web_search sentinel) → Responses API tool definitions. */
+export function buildResponsesTools(llmRequest) {
+    const tools = [];
+    for (const [, tool] of Object.entries(llmRequest.toolsDict ?? {})) {
+        if (isWebSearchSentinel(tool))
+            continue; // added as a native tool below
+        if (isXSearchSentinel(tool))
+            continue; // added as a native tool below
+        if (isCollectionsSearchSentinel(tool))
+            continue; // added as a native tool below
+        const t = tool;
+        if (t.name && t.description) {
+            tools.push({
+                type: 'function',
+                name: t.name,
+                description: t.description,
+                parameters: toLowercaseJsonSchema(t.parameters ?? { type: 'object', properties: {} }),
+                strict: false,
+            });
+        }
+    }
+    if (wantsWebSearch(llmRequest)) {
+        // OpenAI-native, runs server-side. On the xAI path only, optional
+        // domain filters ride the tool object (XAI_WEB_SEARCH_* env vars —
+        // deployment config, the XAI_COLLECTION_IDS doctrine); xAI's web_search
+        // accepts no date bounds (docs.x.ai, 2026-08-08 — from_date/to_date are
+        // x_search-only). OpenAI's web_search takes no params and stays bare.
+        const xaiParams = llmRequest.model && providerForModel(llmRequest.model) === 'xai'
+            ? xaiWebSearchParamsFromEnv()
+            : {};
+        tools.push({ type: 'web_search', ...xaiParams });
+    }
+    if (wantsXSearch(llmRequest)) {
+        // xAI Agent Tools only (sentinel is xai-gated). Optional server-side
+        // constraints (date bounds, handle lists) are deployment config from
+        // XAI_X_SEARCH_* env vars — the XAI_COLLECTION_IDS doctrine; with none
+        // set this is the bare tool it always was.
+        tools.push({ type: 'x_search', ...xSearchParamsFromEnv() });
+    }
+    if (wantsCollectionsSearch(llmRequest)) {
+        // xAI Collections ride the OpenAI-compatible `file_search` wire shape;
+        // ids are deployment config (XAI_COLLECTION_IDS), never YAML.
+        const ids = collectionIdsFromEnv();
+        if (ids.length > 0) {
+            const max = collectionsMaxResultsFromEnv();
+            tools.push({
+                type: 'file_search',
+                vector_store_ids: ids,
+                ...(max !== undefined ? { max_num_results: max } : {}),
+            });
+        }
+        else {
+            console.warn('[collections_search] declared but XAI_COLLECTION_IDS is empty — tool omitted for this request.');
+        }
+    }
+    return tools;
+}
+// ── Stream-event mapping (exported for offline tests) ────────────────────────
+/** Maps one Responses-API SSE event to a displayable delta, or null for
+ *  event types that carry none. Function calls are NOT delta-streamed —
+ *  both OpenAI and xAI deliver them whole in the final response. */
+export function streamEventDelta(ev) {
+    if (!ev || typeof ev !== 'object')
+        return null;
+    if (ev.type === 'response.output_text.delta' && typeof ev.delta === 'string') {
+        return { thought: false, text: ev.delta };
+    }
+    if (ev.type === 'response.reasoning_summary_text.delta' &&
+        typeof ev.delta === 'string') {
+        return { thought: true, text: ev.delta };
+    }
+    return null;
+}
+// ── GptLlm ───────────────────────────────────────────────────────────────────
+export class GptLlm extends BaseLlm {
+    /** gpt-* and o-series ids route here after registration. */
+    static supportedModels = [
+        /^gpt-.+/,
+        /^o[0-9].*/,
+    ];
+    apiKey;
+    constructor({ model, apiKey }) {
+        super({ model });
+        this.apiKey = apiKey;
+    }
+    // ── Provider hooks ─────────────────────────────────────────────────────────
+    // The Responses API surface is spoken by more than one vendor: xAI's Agent
+    // Tools API (lib/models/grokLlm.ts) is wire-compatible, so GrokLlm
+    // subclasses this adapter and overrides only these hooks.
+    /** Provider id for telemetry and error codes. */
+    providerId() {
+        return 'openai';
+    }
+    /** SDK baseURL override; undefined = api.openai.com. */
+    baseURL() {
+        return undefined;
+    }
+    apiKeyFromEnv() {
+        return process.env.OPENAI_API_KEY;
+    }
+    missingKeyMessage() {
+        return 'OPENAI_API_KEY is not set in environment.';
+    }
+    /** Responses API `reasoning` request param, or undefined to omit it.
+     *  Base: reasoning summaries for OpenAI's reasoning-capable ids.
+     *  Subclasses override per vendor (GrokLlm pins grok-4.5 to a reasoning
+     *  effort). A 400 from a model that rejects the param is retried once
+     *  without it — see createWithRetry. */
+    reasoningParam() {
+        return isReasoningModel(this.model) ? { summary: 'auto' } : undefined;
+    }
+    /** Extra options for the OpenAI SDK client constructor. Subclasses
+     *  override per vendor (GrokLlm sets a long request timeout, per xAI's
+     *  streaming guidance for reasoning models). */
+    clientOptions() {
+        return {};
+    }
+    // ── Generation ─────────────────────────────────────────────────────────────
+    async *generateContentAsync(llmRequest, stream = false) {
+        yield* traceLlmGeneration({ provider: this.providerId(), model: this.model }, this.generateInner(llmRequest, stream));
+    }
+    async *generateInner(llmRequest, stream) {
+        const apiKey = this.apiKey || this.apiKeyFromEnv();
+        if (!apiKey) {
+            yield {
+                errorCode: 'MISSING_API_KEY',
+                errorMessage: this.missingKeyMessage(),
+            };
+            return;
+        }
+        // Dynamic import — mirrors claudeLlm.ts, so the framework boots without
+        // the openai SDK installed for users of other providers.
+        let OpenAI;
+        try {
+            const mod = await import('openai');
+            OpenAI = mod.default ?? mod.OpenAI;
+        }
+        catch {
+            yield {
+                errorCode: 'SDK_NOT_INSTALLED',
+                errorMessage: 'The openai package is not installed. Run: npm install openai',
+            };
+            return;
+        }
+        const client = new OpenAI({
+            apiKey,
+            ...(this.baseURL() ? { baseURL: this.baseURL() } : {}),
+            ...this.clientOptions(),
+        });
+        const { instructions, input } = buildResponsesInput(llmRequest);
+        const tools = buildResponsesTools(llmRequest);
+        if (wantsWebSearch(llmRequest)) {
+            setLlmSpanAttribute('llm.web_search.native', true);
+        }
+        if (wantsCollectionsSearch(llmRequest)) {
+            setLlmSpanAttribute(collectionIdsFromEnv().length > 0
+                ? 'llm.collections_search.native'
+                : 'llm.collections_search.omitted', true);
+        }
+        const cfg = llmRequest.config ?? {};
+        const reasoning = this.reasoningParam();
+        const request = {
+            model: this.model,
+            input,
+            ...(instructions ? { instructions } : {}),
+            ...(tools.length > 0 ? { tools } : {}),
+            ...(cfg.maxOutputTokens !== undefined
+                ? { max_output_tokens: cfg.maxOutputTokens }
+                : {}),
+            ...(cfg.temperature !== undefined && !isReasoningModel(this.model)
+                ? { temperature: cfg.temperature }
+                : {}),
+            // Structured output: outputSchema wins over bare JSON mode.
+            ...(cfg.responseSchema
+                ? {
+                    text: {
+                        format: {
+                            type: 'json_schema',
+                            name: 'response',
+                            schema: toLowercaseJsonSchema(cfg.responseSchema),
+                        },
+                    },
+                }
+                : cfg.responseMimeType === 'application/json'
+                    ? { text: { format: { type: 'json_object' } } }
+                    : {}),
+            // Reasoning param — summaries and/or vendor effort control (see
+            // reasoningParam hook; provider subclasses shape it).
+            ...(reasoning ? { reasoning } : {}),
+        };
+        try {
+            if (stream) {
+                yield* this.streamResponses(client, request);
+                return;
+            }
+            const response = await this.createWithRetry(client, request);
+            yield* this.mapFinalResponse(response);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            yield {
+                errorCode: `${this.providerId().toUpperCase()}_ERROR`,
+                errorMessage: msg,
+            };
+        }
+    }
+    /** responses.create with the guarded reasoning retry: if the model
+     *  rejects the reasoning param with a 400 (a non-reasoning model matched
+     *  the pattern), drop it and try once more. */
+    async createWithRetry(client, request) {
+        try {
+            return await client.responses.create(request);
+        }
+        catch (err) {
+            if (err?.status === 400 && request.reasoning) {
+                delete request.reasoning;
+                return await client.responses.create(request);
+            }
+            throw err;
+        }
+    }
+    /** Final (non-delta) Response → LlmResponse yields: reasoning summaries
+     *  as a display-only thought part, then text/functionCall parts with
+     *  usage. Shared by the non-streaming path and the stream finalizer
+     *  (which sets skipThoughts — its summaries already streamed as deltas). */
+    *mapFinalResponse(response, opts = {}) {
+        if (!opts.skipThoughts) {
+            const reasoningTexts = [];
+            for (const item of response.output ?? []) {
+                if (item.type === 'reasoning') {
+                    for (const s of item.summary ?? []) {
+                        if (s?.text)
+                            reasoningTexts.push(s.text);
+                    }
+                }
+            }
+            if (reasoningTexts.length > 0) {
+                yield {
+                    content: {
+                        role: 'model',
+                        parts: [{ text: reasoningTexts.join('\n\n'), thought: true }],
+                    },
+                    partial: true,
+                };
+            }
+        }
+        const parts = [];
+        for (const item of response.output ?? []) {
+            if (item.type === 'message') {
+                for (const c of item.content ?? []) {
+                    if (c.type === 'output_text' && c.text)
+                        parts.push({ text: c.text });
+                }
+            }
+            else if (item.type === 'function_call') {
+                let args = {};
+                try {
+                    args = JSON.parse(item.arguments ?? '{}');
+                }
+                catch {
+                    args = { raw: item.arguments };
+                }
+                parts.push({
+                    functionCall: { name: item.name, args, id: item.call_id },
+                });
+            }
+        }
+        const usage = response.usage;
+        yield {
+            content: { role: 'model', parts },
+            turnComplete: true,
+            ...(usage
+                ? {
+                    usageMetadata: {
+                        ...(usage.input_tokens !== undefined
+                            ? { promptTokenCount: usage.input_tokens }
+                            : {}),
+                        ...(usage.output_tokens !== undefined
+                            ? { candidatesTokenCount: usage.output_tokens }
+                            : {}),
+                        ...(usage.output_tokens_details?.reasoning_tokens !== undefined
+                            ? {
+                                thoughtsTokenCount: usage.output_tokens_details.reasoning_tokens,
+                            }
+                            : {}),
+                        ...(usage.total_tokens !== undefined
+                            ? { totalTokenCount: usage.total_tokens }
+                            : {}),
+                    },
+                }
+                : {}),
+        };
+    }
+    /** SSE streaming: yield displayable DELTAS as { partial: true } responses
+     *  (the ADK Runner shows but never persists partials), then map the
+     *  terminal response.completed payload through mapFinalResponse — full
+     *  content + usage, the ONE event that lands in the session. Usage rides
+     *  only the final response so the tracer never double-counts tokens. */
+    async *streamResponses(client, request) {
+        const events = await this.createWithRetry(client, {
+            ...request,
+            stream: true,
+        });
+        let finalResponse;
+        let streamedThoughts = false;
+        const textBuf = [];
+        const thoughtBuf = [];
+        for await (const ev of events) {
+            const delta = streamEventDelta(ev);
+            if (delta) {
+                if (delta.thought) {
+                    streamedThoughts = true;
+                    thoughtBuf.push(delta.text);
+                }
+                else {
+                    textBuf.push(delta.text);
+                }
+                yield {
+                    content: {
+                        role: 'model',
+                        parts: [
+                            delta.thought
+                                ? { text: delta.text, thought: true }
+                                : { text: delta.text },
+                        ],
+                    },
+                    partial: true,
+                };
+                continue;
+            }
+            if (ev?.type === 'response.completed' && ev.response) {
+                finalResponse = ev.response;
+            }
+            else if (ev?.type === 'response.failed' || ev?.type === 'error') {
+                const msg = ev?.response?.error?.message ?? ev?.message ?? 'response stream failed';
+                yield {
+                    errorCode: `${this.providerId().toUpperCase()}_STREAM_ERROR`,
+                    errorMessage: String(msg),
+                };
+                return;
+            }
+        }
+        if (finalResponse) {
+            yield* this.mapFinalResponse(finalResponse, {
+                skipThoughts: streamedThoughts,
+            });
+            return;
+        }
+        // Defensive: the stream ended without response.completed — aggregate
+        // the buffered deltas so the turn still persists a complete event.
+        const parts = [];
+        if (thoughtBuf.length > 0)
+            parts.push({ text: thoughtBuf.join(''), thought: true });
+        if (textBuf.length > 0)
+            parts.push({ text: textBuf.join('') });
+        yield { content: { role: 'model', parts }, turnComplete: true };
+    }
+    /** Live/bidirectional streaming is not wired for this adapter. */
+    async connect(_llmRequest) {
+        throw new Error('GptLlm does not support live bidirectional connections. ' +
+            'Use a Gemini model for live/streaming sessions.');
+    }
+}
+// ── Registration helper ───────────────────────────────────────────────────────
+/**
+ * Registers GptLlm with the ADK LLMRegistry. Called by
+ * registerAvailableProviders() when OPENAI_API_KEY is present.
+ */
+export function registerGptLlm() {
+    LLMRegistry.register(GptLlm);
+}

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

@@ -0,0 +1,64 @@
+/**
+ * lib/models/grokLlm.ts — xAI Grok provider for the ADK LLMRegistry.
+ *
+ * WHY this file exists:
+ *   Model optionality is a primary driver of this framework: the agent YAML
+ *   declares `model`, and the registry routes it to the right provider.
+ *
+ * WHY it subclasses GptLlm (Responses API) and not the chat-completions base:
+ *   xAI retired Live Search on chat completions (the API now returns
+ *   410 "Live search is deprecated. Please switch to the Agent Tools API").
+ *   The Agent Tools API lives at `https://api.x.ai/v1/responses` and is
+ *   wire-compatible with OpenAI's Responses API — same `input` items, same
+ *   `{ type: 'function' }` / `{ type: 'web_search' }` tools, same
+ *   `reasoning` summary / `message` / `function_call` output items (verified
+ *   live 2026-07-19). So Grok reuses the GptLlm translator via the openai
+ *   SDK's baseURL override, and gets for free:
+ *     - native web_search (server-side, with source citations)
+ *     - x_search (live X posts) and collections_search (hosted document
+ *       stores via the file_search wire shape — see collectionsSearchTool.ts)
+ *     - reasoning summaries surfaced as { thought: true } THINKING output
+ *     - SSE streaming (ADK RunConfig streamingMode: SSE → partial deltas)
+ *     - structured outputs (YAML outputSchema → text.format json_schema)
+ *     - function tools with call_id round-tripping, lowercased schemas
+ *     - usage → usageMetadata mapping for llm.request token spans
+ *
+ * HOW TO ENABLE:
+ *   1. Add your API key to .env:  XAI_API_KEY=xai-...   (console.x.ai — paid)
+ *   2. Set model: "grok-4.5" (or any grok-* id) in your YAML.
+ *   registerAvailableProviders() registers this adapter when the key is set.
+ *   grok-4.5 requests carry reasoning effort 'medium' by default — see
+ *   reasoningParam() below and DEFAULT_GROK_REASONING_EFFORT (lib/config.ts).
+ *
+ * API-DRIFT NOTE: every xAI-specific choice (endpoint, key env) is confined
+ * to the overrides below — upstream drift stays a one-file fix. Note xAI's
+ * Responses endpoint reports the serving backend in the response `model`
+ * field (e.g. "grok-4.3"), which may differ from the requested id; invalid
+ * ids are properly rejected with "Model not found".
+ */
+import { GptLlm } from './gptLlm.ts';
+export declare class GrokLlm extends GptLlm {
+    /** Any model: "grok-*" in a YAML config routes here after registration. */
+    static readonly supportedModels: Array<string | RegExp>;
+    protected providerId(): string;
+    protected baseURL(): string;
+    protected apiKeyFromEnv(): string | undefined;
+    protected missingKeyMessage(): string;
+    /** xAI's streaming docs advise a long request timeout for reasoning
+     *  models (their examples use 3600s) so slow thinking can't trip the
+     *  SDK's default mid-stream. Applied to all Grok requests. */
+    protected clientOptions(): Record<string, unknown>;
+    /** grok-4.5 exposes reasoning-effort control ('low' | 'medium' | 'high';
+     *  xAI defaults to 'high', and reasoning cannot be disabled) via the
+     *  Responses API `reasoning.effort` field — docs.x.ai › Model
+     *  capabilities › Text › Reasoning › Effort levels. We pin
+     *  DEFAULT_GROK_REASONING_EFFORT (medium). Other grok ids don't accept
+     *  the param and get none (their reasoning summaries arrive unrequested);
+     *  if xAI ever rejects it, GptLlm's guarded 400 retry drops it. */
+    protected reasoningParam(): Record<string, unknown> | undefined;
+}
+/**
+ * Registers GrokLlm with the ADK LLMRegistry. Called by
+ * registerAvailableProviders() when XAI_API_KEY is present.
+ */
+export declare function registerGrokLlm(): void;

package/dist/lib/models/grokLlm.js

@@ -0,0 +1,86 @@
+/**
+ * lib/models/grokLlm.ts — xAI Grok provider for the ADK LLMRegistry.
+ *
+ * WHY this file exists:
+ *   Model optionality is a primary driver of this framework: the agent YAML
+ *   declares `model`, and the registry routes it to the right provider.
+ *
+ * WHY it subclasses GptLlm (Responses API) and not the chat-completions base:
+ *   xAI retired Live Search on chat completions (the API now returns
+ *   410 "Live search is deprecated. Please switch to the Agent Tools API").
+ *   The Agent Tools API lives at `https://api.x.ai/v1/responses` and is
+ *   wire-compatible with OpenAI's Responses API — same `input` items, same
+ *   `{ type: 'function' }` / `{ type: 'web_search' }` tools, same
+ *   `reasoning` summary / `message` / `function_call` output items (verified
+ *   live 2026-07-19). So Grok reuses the GptLlm translator via the openai
+ *   SDK's baseURL override, and gets for free:
+ *     - native web_search (server-side, with source citations)
+ *     - x_search (live X posts) and collections_search (hosted document
+ *       stores via the file_search wire shape — see collectionsSearchTool.ts)
+ *     - reasoning summaries surfaced as { thought: true } THINKING output
+ *     - SSE streaming (ADK RunConfig streamingMode: SSE → partial deltas)
+ *     - structured outputs (YAML outputSchema → text.format json_schema)
+ *     - function tools with call_id round-tripping, lowercased schemas
+ *     - usage → usageMetadata mapping for llm.request token spans
+ *
+ * HOW TO ENABLE:
+ *   1. Add your API key to .env:  XAI_API_KEY=xai-...   (console.x.ai — paid)
+ *   2. Set model: "grok-4.5" (or any grok-* id) in your YAML.
+ *   registerAvailableProviders() registers this adapter when the key is set.
+ *   grok-4.5 requests carry reasoning effort 'medium' by default — see
+ *   reasoningParam() below and DEFAULT_GROK_REASONING_EFFORT (lib/config.ts).
+ *
+ * API-DRIFT NOTE: every xAI-specific choice (endpoint, key env) is confined
+ * to the overrides below — upstream drift stays a one-file fix. Note xAI's
+ * Responses endpoint reports the serving backend in the response `model`
+ * field (e.g. "grok-4.3"), which may differ from the requested id; invalid
+ * ids are properly rejected with "Model not found".
+ */
+import { LLMRegistry } from '@google/adk';
+import { DEFAULT_GROK_REASONING_EFFORT } from "../config.js";
+import { GptLlm } from "./gptLlm.js";
+const XAI_BASE_URL = 'https://api.x.ai/v1';
+// ── GrokLlm ───────────────────────────────────────────────────────────────────
+export class GrokLlm extends GptLlm {
+    /** Any model: "grok-*" in a YAML config routes here after registration. */
+    static supportedModels = [/^grok-.+/];
+    providerId() {
+        return 'xai';
+    }
+    baseURL() {
+        return XAI_BASE_URL;
+    }
+    apiKeyFromEnv() {
+        return process.env.XAI_API_KEY;
+    }
+    missingKeyMessage() {
+        return 'XAI_API_KEY is not set in environment.';
+    }
+    /** xAI's streaming docs advise a long request timeout for reasoning
+     *  models (their examples use 3600s) so slow thinking can't trip the
+     *  SDK's default mid-stream. Applied to all Grok requests. */
+    clientOptions() {
+        return { timeout: 3_600_000 };
+    }
+    /** grok-4.5 exposes reasoning-effort control ('low' | 'medium' | 'high';
+     *  xAI defaults to 'high', and reasoning cannot be disabled) via the
+     *  Responses API `reasoning.effort` field — docs.x.ai › Model
+     *  capabilities › Text › Reasoning › Effort levels. We pin
+     *  DEFAULT_GROK_REASONING_EFFORT (medium). Other grok ids don't accept
+     *  the param and get none (their reasoning summaries arrive unrequested);
+     *  if xAI ever rejects it, GptLlm's guarded 400 retry drops it. */
+    reasoningParam() {
+        if (/^grok-4\.5/.test(this.model)) {
+            return { effort: DEFAULT_GROK_REASONING_EFFORT };
+        }
+        return undefined;
+    }
+}
+// ── Registration helper ───────────────────────────────────────────────────────
+/**
+ * Registers GrokLlm with the ADK LLMRegistry. Called by
+ * registerAvailableProviders() when XAI_API_KEY is present.
+ */
+export function registerGrokLlm() {
+    LLMRegistry.register(GrokLlm);
+}