melchizedek-agents 0.9.6 → 0.15.0

package/dist/lib/models/capabilities.js

@@ -0,0 +1,81 @@
+/**
+ * lib/models/capabilities.ts — what an agent keeps and loses on the path
+ * its model will actually take.
+ *
+ * WHY this file exists:
+ *   A model id is the whole routing decision, and some of what an agent
+ *   declares only exists on one provider: Gemini grounding, xAI's x_search
+ *   and Collections, the server-side web_search sentinel that every cloud
+ *   adapter turns into its provider's native search. Until now the only
+ *   defence against losing one was a one-time console.warn inside an
+ *   adapter. This module states the loss BEFORE a request is made, per
+ *   agent, on the RESOLVED transport (direct or gateway), so the doctor
+ *   (lib/doctor.ts), the A2A startup log (lib/compile.ts) and the ledger
+ *   (llm.capability.dropped) all say the same thing.
+ *
+ * It knows nothing about gateways beyond planTransport(); a future
+ * transport that restores a native feature changes the table here, not
+ * the callers.
+ */
+import { PROVIDERS } from "./providerMap.js";
+import { planTransport } from "./gateway.js";
+/**
+ * Server-side tool sentinels and the providers whose DIRECT adapter
+ * honours them natively. Anything not listed is a client-side function
+ * tool and travels on every path.
+ */
+export const SERVER_SIDE_TOOLS = {
+    web_search: ['gemini', 'anthropic', 'openai', 'xai'],
+    google_search: ['gemini'],
+    x_search: ['xai'],
+    collections_search: ['xai'],
+};
+export function describeCapabilities(model, tools = [], opts = {}) {
+    const plan = planTransport(model, opts);
+    const native = [];
+    const dropped = [];
+    const portable = [];
+    for (const name of tools) {
+        const providers = SERVER_SIDE_TOOLS[name];
+        if (!providers) {
+            portable.push(name);
+        }
+        else if (plan.transport === 'direct' && providers.includes(plan.provider)) {
+            native.push(name);
+        }
+        else {
+            dropped.push(name);
+        }
+    }
+    return {
+        model,
+        provider: plan.provider,
+        providerLabel: PROVIDERS[plan.provider].label,
+        transport: plan.transport,
+        ...(plan.gateway ? { gateway: plan.gateway.id } : {}),
+        funded: plan.funded,
+        keyEnv: plan.keyEnv,
+        native,
+        dropped,
+        portable,
+    };
+}
+/**
+ * One line for a startup log, or undefined when there is nothing to say —
+ * a funded direct path with no dropped tool is the quiet default.
+ */
+export function capabilitySummary(agentName, r) {
+    if (!r.funded) {
+        return `${agentName}: ${r.model} has no route — set ${r.keyEnv ?? 'a provider key'} (or a MODEL_GATEWAY).`;
+    }
+    const via = r.transport === 'gateway' ? ` via gateway:${r.gateway}` : '';
+    if (r.dropped.length === 0) {
+        return via ? `${agentName}: ${r.model}${via}.` : undefined;
+    }
+    const why = r.transport === 'gateway'
+        ? 'a gateway cannot enable upstream native search'
+        : r.provider === 'ollama'
+            ? 'a local model has no native search'
+            : `${r.providerLabel} has no native ${r.dropped.join('/')}`;
+    return `${agentName}: ${r.model}${via} — dropped ${r.dropped.join(', ')} (${why}).`;
+}

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 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,156 @@
+/**
+ * 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 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 { PROVIDERS, providerForModel, providerKeyPresent } 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 = providerKeyPresent(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 ymir's
+ *     per-agent cost trends 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;

package/dist/lib/models/gatewayLlm.js

@@ -0,0 +1,105 @@
+/**
+ * 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 ymir's
+ *     per-agent cost trends 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 { LLMRegistry } from '@google/adk';
+import { OpenAiCompatibleLlm } from "./openAiCompatibleLlm.js";
+import { GATEWAY_ENV, GATEWAY_KEY_ENV, GATEWAY_MODEL_MAP_ENV, gatewayConfig, gatewayWireModel, } from "./gateway.js";
+import { providerForModel } from "./providerMap.js";
+export class GatewayLlm extends OpenAiCompatibleLlm {
+    /** Never registered directly — see gatewayClassFor(). */
+    static supportedModels = [];
+    cfg;
+    constructor({ model }) {
+        super({ model });
+        this.cfg = gatewayConfig();
+    }
+    /** Attribution stays with the upstream provider named by the YAML id. */
+    providerId() {
+        return providerForModel(this.model);
+    }
+    transport() {
+        return this.cfg ? `gateway:${this.cfg.gateway.id}` : 'gateway';
+    }
+    endpointUrl() {
+        const base = this.cfg?.baseUrl ?? '';
+        return `${base}/chat/completions`;
+    }
+    headers() {
+        return { Authorization: `Bearer ${process.env[GATEWAY_KEY_ENV] ?? ''}` };
+    }
+    wireModelName() {
+        return this.cfg ? gatewayWireModel(this.model, this.cfg.gateway) : this.model;
+    }
+    missingRequirement() {
+        if (!this.cfg) {
+            return {
+                errorCode: 'GATEWAY_NOT_CONFIGURED',
+                errorMessage: `${GATEWAY_ENV} is not set to a known gateway, so ${this.model} has no route.`,
+            };
+        }
+        if (!this.cfg.keyPresent) {
+            return {
+                errorCode: 'GATEWAY_KEY_MISSING',
+                errorMessage: `${GATEWAY_ENV}=${this.cfg.gateway.id} but ${GATEWAY_KEY_ENV} is not set.`,
+            };
+        }
+        return undefined;
+    }
+    // webSearchBodyFields() stays at the base default (null): a gateway has no
+    // uniform switch for upstream native search, so the tool is dropped and
+    // the loss is reported (llm.capability.dropped, the doctor, the startup log).
+    httpError(status, detail) {
+        const label = this.cfg?.gateway.label ?? 'gateway';
+        const hint = status === 404 || status === 400
+            ? ` If the model id is the problem, map it with ${GATEWAY_MODEL_MAP_ENV}=${this.model}=<gateway id>.`
+            : '';
+        return {
+            errorCode: 'GATEWAY_HTTP_ERROR',
+            errorMessage: `${label} returned ${status} for ${this.wireModelName()}: ${detail.slice(0, 4000)}.${hint}`,
+        };
+    }
+    extraBodyFields(_llmRequest) {
+        return {};
+    }
+}
+/**
+ * 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 function gatewayClassFor(patterns) {
+    return class GatewayLlmFor extends GatewayLlm {
+        static supportedModels = patterns;
+    };
+}
+/** Registers a gateway stand-in for the given patterns. */
+export function registerGatewayLlm(patterns) {
+    LLMRegistry.register(gatewayClassFor(patterns));
+}

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

@@ -27,10 +27,15 @@
  *
  *   Response `output` items map back:
  *     'reasoning' summary    → { text, thought: true } partial (display-only)
- *     'message' output_text  → text part
+ *     'message' output_text  → text part (2nd+ message item opens a new paragraph)
  *     'function_call'        → functionCall part
+ *     '*_call' / 'custom_tool_call' (server-side: web_search, x_search…)
+ *                            → customMetadata['responses.server_tool_calls'],
+ *                              never a functionCall (ADK must not run them)
  *   usage.input_tokens / output_tokens / output_tokens_details.reasoning_tokens
  *   → LlmResponse.usageMetadata, so token telemetry works like every provider.
+ *   xAI's server-side tool counters → customMetadata['responses.server_tool_usage']
+ *   and llm.server_tools.* span attributes.
  *
  * STREAMING (ADK stream=true, i.e. RunConfig streamingMode: SSE):
  *   The request is sent with { stream: true }; SSE deltas
@@ -59,6 +64,29 @@ export declare function streamEventDelta(ev: any): {
     thought: boolean;
     text: string;
 } | null;
+/** One tool call the vendor ran on its own side inside a single Responses
+ *  call. It never comes back to ADK as a functionCall, so without this
+ *  record a searched answer and a recalled one look identical in a trace. */
+export interface ServerToolCall {
+    name: string;
+    args: Record<string, unknown>;
+    status?: string;
+    /** URLs the vendor reports the call returned (web search only). */
+    sources?: string[];
+}
+/**
+ * The server-side tool calls in a Responses `output` array. Two shapes,
+ * both verified against a live xAI response (2026-09-25):
+ *   web_search_call   → { status, action: { type:'search', query, sources:[{url}] } }
+ *   custom_tool_call  → { name:'x_keyword_search'|'x_semantic_search', input:'<json>', status }
+ * Any other `*_call` item (code_interpreter_call, file_search_call…) is
+ * recorded by its type with its `action` as args. `custom_tool_call` is
+ * server-side here because this adapter never declares a client custom tool.
+ */
+export declare function extractServerToolCalls(output: unknown): ServerToolCall[];
+/** xAI's server-side tool counters off `usage` (num_server_side_tools_used +
+ *  server_side_tool_usage_details), non-zero entries only; {} for OpenAI. */
+export declare function serverToolUsage(usage: any): Record<string, number>;
 export declare class GptLlm extends BaseLlm {
     /** gpt-* and o-series ids route here after registration. */
     static readonly supportedModels: Array<string | RegExp>;