melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/models/ollamaLlm.js

@@ -71,9 +71,19 @@
  *   - generate_image / inspect_image call Gemini image models directly and
  *     still require a Gemini key regardless of the inference model.
  *   - thinkingConfig is Gemini-only; qwen3 thinks on its own schedule.
+ *     generateContentConfig.reasoningEffort travels as reasoning_effort, and
+ *     on Ollama 0.31 only "none" changes anything (it turns thinking off);
+ *     "low" does not bound a qwen3.5 scratchpad, and `think: false` is
+ *     ignored on this path.
+ *   - Context window: 4,096 tokens unless the Modelfile (PARAMETER num_ctx)
+ *     or OLLAMA_CONTEXT_LENGTH on the server says otherwise — /v1 ignores
+ *     num_ctx. A thinking model that fills it, or stops after thinking, is
+ *     retried once with thinking off (retriesWithoutThinking); only if that
+ *     fails too does the turn end with OLLAMA_MAX_TOKENS or
+ *     OLLAMA_EMPTY_RESPONSE, never an empty reply (see noAnswerError).
  */
 import { LLMRegistry } from '@google/adk';
-import { OpenAiCompatibleLlm } from "./openAiCompatibleLlm.js";
+import { OpenAiCompatibleLlm } from './openAiCompatibleLlm.js';
 const DEFAULT_BASE_URL = 'http://localhost:11434/v1';
 // ── OllamaLlm ─────────────────────────────────────────────────────────────────
 export class OllamaLlm extends OpenAiCompatibleLlm {
@@ -119,9 +129,41 @@ export class OllamaLlm extends OpenAiCompatibleLlm {
                 'Is it running? Start the Ollama app or run: ollama serve',
         };
     }
+    /**
+     * Out of tokens on Ollama almost always means the CONTEXT WINDOW, not
+     * max_tokens: Ollama loads a model with a 4,096-token window unless told
+     * otherwise, the prompt and the scratchpad share it, and this /v1 path
+     * ignores num_ctx (and `options` entirely). A qwen3.5 explainer prompt can
+     * think for 3,700+ tokens and hit the ceiling before the answer starts.
+     * The two levers that work are named in the message.
+     */
+    noAnswerError(truncated) {
+        if (!truncated)
+            return super.noAnswerError(truncated);
+        const name = this.wireModelName();
+        return {
+            errorCode: 'OLLAMA_MAX_TOKENS',
+            errorMessage: `${name} filled its context window while thinking and never wrote a reply ` +
+                '(finish_reason "length"). Ollama defaults to a 4,096-token window and its ' +
+                'OpenAI-compatible endpoint ignores num_ctx, so either set ' +
+                'generateContentConfig.reasoningEffort: "none" on the agent to skip thinking, ' +
+                `or give the model a larger window: a Modelfile with "FROM ${name}" and ` +
+                '"PARAMETER num_ctx 32768" (ollama create), or OLLAMA_CONTEXT_LENGTH=32768 ' +
+                'on the ollama serve process.',
+        };
+    }
     extraBodyFields(_llmRequest) {
         return {};
     }
+    /**
+     * A local reasoning model that thinks its way to no answer is asked once
+     * more with thinking off ("none" is the one reasoning_effort Ollama 0.31
+     * honors), so the turn answers instead of failing. Off with
+     * OLLAMA_RETRY_WITHOUT_THINKING=false.
+     */
+    retriesWithoutThinking() {
+        return process.env.OLLAMA_RETRY_WITHOUT_THINKING?.trim().toLowerCase() !== 'false';
+    }
 }
 // ── Registration helper ───────────────────────────────────────────────────────
 /**

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

@@ -23,6 +23,8 @@
  *     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).
+ *   - Retries of transient failures (lib/models/retry.ts) before any byte
+ *     is yielded, and HTTP errors carrying `status` + `retryable`.
  *   - 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.
@@ -61,7 +63,13 @@ type OpenAiMessage = {
     tool_call_id: string;
     content: string;
 };
-/** Splits "<think>…</think>" scratchpad from the reply. */
+/**
+ * Splits "<think>…</think>" scratchpad from the reply.
+ *
+ * A block the model never closed is scratchpad too: it means the model ran
+ * out of budget mid-thought, so everything after the opening tag is
+ * reasoning — never reply text with a raw "<think>" in it.
+ */
 export declare function splitThinkBlocks(text: string): {
     reasoning: string;
     answer: string;
@@ -95,6 +103,7 @@ export declare class ThinkStreamSplitter {
 }
 export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
     private webSearchWarned;
+    private retryWarned;
     /** Provider id for telemetry, e.g. 'ollama', 'xai'. */
     protected abstract providerId(): string;
     /** Full chat-completions URL, e.g. "https://api.x.ai/v1/chat/completions". */
@@ -103,6 +112,13 @@ export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
     protected abstract headers(): Record<string, string>;
     /** Model id as the wire expects it (e.g. strip the "ollama/" namespace). */
     protected wireModelName(): string;
+    /**
+     * How the request reaches the provider: 'direct' (the provider's own
+     * endpoint) or 'gateway:<id>' (lib/models/gatewayLlm.ts). Recorded on the
+     * llm.request span as llm.transport so the ledger can tell a native call
+     * from a proxied one while llm.provider keeps the upstream attribution.
+     */
+    protected transport(): string;
     /** Provider-specific request body fields (merged last). */
     /** Whether the endpoint accepts response_format json_schema (strict). */
     protected supportsJsonSchemaFormat(): boolean;
@@ -135,10 +151,32 @@ export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
     protected missingRequirement(): LlmResponse | undefined;
     /** Error response for a non-2xx HTTP status. */
     protected httpError(status: number, detail: string): LlmResponse;
+    /**
+     * Whether a turn that ended with no answer after thinking (noAnswerError)
+     * is sent once more with reasoning_effort "none". Default: never. An
+     * adapter for local reasoning models turns it on (OllamaLlm).
+     */
+    protected retriesWithoutThinking(): boolean;
+    /**
+     * Error response for a turn that produced reasoning or ran out of tokens
+     * but no reply and no tool call. `truncated` is true when the provider
+     * reported finish_reason "length" (the token budget or context window
+     * filled up); false when it stopped after thinking with nothing to say.
+     */
+    protected noAnswerError(truncated: boolean): LlmResponse;
     /** Error response when the endpoint can't be reached at all. */
     protected unreachable(message: string): LlmResponse;
     generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
+    /**
+     * One request, retried once without thinking when the adapter opts in and
+     * the model thought its way to no answer (ADR 0027): a local reasoning
+     * model can spend its whole context window on the scratchpad. The first
+     * attempt's error is held back, never yielded; what it spent is added to
+     * the retry's usage, so budgets and the ledger still count it. An agent
+     * that already runs with reasoningEffort "none" is not retried.
+     */
     private generateInner;
+    private attempt;
     /**
      * SSE path: display-only partials as the tokens land, then ONE final
      * non-partial response carrying the complete text, tool calls and usage.
@@ -154,6 +192,22 @@ export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
      * being replayed to the model on the next turn.
      */
     private streamResponse;
+    /**
+     * The one non-partial response that closes a turn, on both paths.
+     *
+     * WHY an empty reply becomes an error: ADK drops a final response with no
+     * parts and no errorCode (llm_agent: "empty content → return"), so the
+     * last event left is the thought partial — ADK logs "The last event is
+     * partial, which is not expected." and the turn ends with empty text and
+     * no reason. That is exactly what a thinking model does when its
+     * scratchpad fills the budget (finish_reason "length"): the answer never
+     * starts. Naming it lets the caller see why, and still carries the usage
+     * so the tokens spent thinking are counted.
+     *
+     * A reply that was cut short but did start keeps its text and is marked
+     * finishReason MAX_TOKENS.
+     */
+    private finalResponse;
     /** ADK Contents (Google GenAI format) → OpenAI-compatible chat messages. */
     protected buildMessages(llmRequest: LlmRequest): OpenAiMessage[];
     /** ADK toolsDict → OpenAI function-tool definitions (lowercase schemas). */
@@ -164,7 +218,18 @@ export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
      */
     connect(_llmRequest: LlmRequest): Promise<BaseLlmConnection>;
 }
-/** OpenAI-style usage → GenAI usageMetadata (undefined when absent). */
+/**
+ * Stamps an HTTP error response with its numeric status and whether that
+ * status is transient, so callers above (and the ledger, via the tracer's
+ * llm.payload.response) can tell a rate limit from a bad request without
+ * parsing the message. Applied in the base so a subclass's httpError
+ * override (Ollama's hint, the gateway's GATEWAY_HTTP_ERROR) keeps its
+ * errorCode and wording and still gets the fields.
+ */
+export declare function withHttpStatus(resp: LlmResponse, status: number): LlmResponse;
+type Usage = NonNullable<ReturnType<typeof mapUsage>>;
+/** Two usage records summed, field by field. */
+export declare function addUsage(a: Usage | undefined, b: Usage | undefined): Usage | undefined;
 export declare function mapUsage(usage: any): {
     promptTokenCount?: number;
     candidatesTokenCount?: number;

package/dist/lib/models/openAiCompatibleLlm.js

@@ -23,27 +23,43 @@
  *     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).
+ *   - Retries of transient failures (lib/models/retry.ts) before any byte
+ *     is yielded, and HTTP errors carrying `status` + `retryable`.
  *   - 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, toStrictJsonSchema } from "./schemaNormalize.js";
-/** Splits "<think>…</think>" scratchpad from the reply. */
+import { FinishReason } from '@google/genai';
+import { traceLlmGeneration, setLlmSpanAttribute, } from '../observability/tracer.js';
+import { wantsWebSearch, isWebSearchSentinel, } from '../tools/webSearchTool.js';
+import { currentTurnSignal } from '../runtime/turnControl.js';
+import { toStrictJsonSchema, toolDeclarationFor } from './schemaNormalize.js';
+import { fetchWithRetry, isRetryableStatus } from './retry.js';
+const OPEN_THINK = '<think>';
+const CLOSE_THINK = '</think>';
+/**
+ * Splits "<think>…</think>" scratchpad from the reply.
+ *
+ * A block the model never closed is scratchpad too: it means the model ran
+ * out of budget mid-thought, so everything after the opening tag is
+ * reasoning — never reply text with a raw "<think>" in it.
+ */
 export function splitThinkBlocks(text) {
     const blocks = [];
-    const answer = text
-        .replace(/<think>([\s\S]*?)<\/think>/g, (_, inner) => {
+    let answer = text.replace(/<think>([\s\S]*?)<\/think>/g, (_, inner) => {
         blocks.push(inner.trim());
         return '';
-    })
-        .trimStart();
-    return { reasoning: blocks.join('\n\n'), answer };
+    });
+    const unclosed = answer.indexOf(OPEN_THINK);
+    if (unclosed !== -1) {
+        const inner = answer.slice(unclosed + OPEN_THINK.length).trim();
+        if (inner)
+            blocks.push(inner);
+        answer = answer.slice(0, unclosed).trimEnd();
+    }
+    return { reasoning: blocks.join('\n\n'), answer: answer.trimStart() };
 }
-const OPEN_THINK = '<think>';
-const CLOSE_THINK = '</think>';
 /** Length of the longest suffix of `s` that is a proper prefix of `tag`. */
 function partialTagSuffix(s, tag) {
     const max = Math.min(s.length, tag.length - 1);
@@ -140,10 +156,20 @@ async function* sseChunks(res) {
 // ── OpenAiCompatibleLlm ──────────────────────────────────────────────────────
 export class OpenAiCompatibleLlm extends BaseLlm {
     webSearchWarned = false;
+    retryWarned = false;
     /** Model id as the wire expects it (e.g. strip the "ollama/" namespace). */
     wireModelName() {
         return this.model;
     }
+    /**
+     * How the request reaches the provider: 'direct' (the provider's own
+     * endpoint) or 'gateway:<id>' (lib/models/gatewayLlm.ts). Recorded on the
+     * llm.request span as llm.transport so the ledger can tell a native call
+     * from a proxied one while llm.provider keeps the upstream attribution.
+     */
+    transport() {
+        return 'direct';
+    }
     /** Provider-specific request body fields (merged last). */
     /** Whether the endpoint accepts response_format json_schema (strict). */
     supportsJsonSchemaFormat() {
@@ -191,6 +217,34 @@ export class OpenAiCompatibleLlm extends BaseLlm {
             errorMessage: `${this.providerId()} returned ${status}: ${detail.slice(0, 4000)}`,
         };
     }
+    /**
+     * Whether a turn that ended with no answer after thinking (noAnswerError)
+     * is sent once more with reasoning_effort "none". Default: never. An
+     * adapter for local reasoning models turns it on (OllamaLlm).
+     */
+    retriesWithoutThinking() {
+        return false;
+    }
+    /**
+     * Error response for a turn that produced reasoning or ran out of tokens
+     * but no reply and no tool call. `truncated` is true when the provider
+     * reported finish_reason "length" (the token budget or context window
+     * filled up); false when it stopped after thinking with nothing to say.
+     */
+    noAnswerError(truncated) {
+        const id = this.providerId();
+        return truncated
+            ? {
+                errorCode: `${id.toUpperCase()}_MAX_TOKENS`,
+                errorMessage: `${this.model} ran out of tokens before it wrote a reply ` +
+                    '(finish_reason "length"). Raise max_tokens, or lower ' +
+                    'generateContentConfig.reasoningEffort so less goes to thinking.',
+            }
+            : {
+                errorCode: `${id.toUpperCase()}_EMPTY_RESPONSE`,
+                errorMessage: `${this.model} finished thinking but returned no reply.`,
+            };
+    }
     /** Error response when the endpoint can't be reached at all. */
     unreachable(message) {
         return {
@@ -202,12 +256,49 @@ export class OpenAiCompatibleLlm extends BaseLlm {
     async *generateContentAsync(llmRequest, stream = false) {
         yield* traceLlmGeneration({ provider: this.providerId(), model: this.model, llmRequest }, this.generateInner(llmRequest, stream));
     }
+    /**
+     * One request, retried once without thinking when the adapter opts in and
+     * the model thought its way to no answer (ADR 0027): a local reasoning
+     * model can spend its whole context window on the scratchpad. The first
+     * attempt's error is held back, never yielded; what it spent is added to
+     * the retry's usage, so budgets and the ledger still count it. An agent
+     * that already runs with reasoningEffort "none" is not retried.
+     */
     async *generateInner(llmRequest, stream) {
+        const cfg = llmRequest.config ?? {};
+        const mayRetry = this.retriesWithoutThinking() && cfg.reasoningEffort !== 'none';
+        let held;
+        for await (const r of this.attempt(llmRequest, stream)) {
+            if (mayRetry && NO_ANSWER.has(r)) {
+                held = r;
+                continue;
+            }
+            yield r;
+        }
+        if (!held)
+            return;
+        setLlmSpanAttribute('llm.retry_without_thinking', held.errorCode ?? true);
+        if (!this.retryWarned) {
+            this.retryWarned = true;
+            console.warn(`⚠ ${this.model} thought without answering (${held.errorCode}); retrying once with thinking off.`);
+        }
+        let carried = held.usageMetadata;
+        for await (const r of this.attempt(llmRequest, stream, 'none')) {
+            if (carried && !r.partial && (r.turnComplete || r.errorCode)) {
+                yield { ...r, usageMetadata: addUsage(carried, r.usageMetadata) };
+                carried = undefined;
+                continue;
+            }
+            yield r;
+        }
+    }
+    async *attempt(llmRequest, stream, reasoningEffort) {
         const missing = this.missingRequirement();
         if (missing) {
             yield missing;
             return;
         }
+        setLlmSpanAttribute('llm.transport', this.transport());
         const messages = this.buildMessages(llmRequest);
         const openAiTools = this.buildTools(llmRequest);
         const cfg = llmRequest.config ?? {};
@@ -229,8 +320,8 @@ export class OpenAiCompatibleLlm extends BaseLlm {
             // and return an empty turn. Ollama's OpenAI-compatible endpoint honors
             // `reasoning_effort` and IGNORES the native `think` field, so this is
             // the only lever on this path. Opt-in per agent; omitted = unchanged.
-            ...(cfg.reasoningEffort !== undefined
-                ? { reasoning_effort: cfg.reasoningEffort }
+            ...((reasoningEffort ?? cfg.reasoningEffort) !== undefined
+                ? { reasoning_effort: reasoningEffort ?? cfg.reasoningEffort }
                 : {}),
             ...(openAiTools.length > 0 ? { tools: openAiTools } : {}),
             // Structured output: an ADK outputSchema becomes a strict json_schema
@@ -253,22 +344,34 @@ export class OpenAiCompatibleLlm extends BaseLlm {
             }
             else {
                 setLlmSpanAttribute('llm.web_search.omitted', true);
+                setLlmSpanAttribute('llm.capability.dropped', 'web_search');
                 if (!this.webSearchWarned) {
                     this.webSearchWarned = true;
-                    console.warn(`⚠ web_search requested but ${this.model} has no native web search — ` +
+                    const via = this.transport().startsWith('gateway')
+                        ? ` through ${this.transport()} (a gateway cannot enable upstream native search)`
+                        : '';
+                    console.warn(`⚠ web_search requested but ${this.model}${via} has no native web search — ` +
                         'tool omitted (the agent runs without search).');
                 }
             }
         }
         try {
-            const res = await fetch(this.endpointUrl(), {
+            // Transient failures (429/5xx, connection resets) are retried here, on
+            // the REQUEST only — the body is read after, so a stream that dies
+            // half-way is reported, never replayed (lib/models/retry.ts).
+            const signal = currentTurnSignal();
+            const { response: res } = await fetchWithRetry(this.endpointUrl(), {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.headers() },
                 body: JSON.stringify(body),
+                signal,
+            }, {
+                signal,
+                onRetry: ({ retries }) => setLlmSpanAttribute('llm.retries', retries),
             });
             if (!res.ok) {
                 const detail = await res.text().catch(() => '');
-                yield this.httpError(res.status, detail);
+                yield withHttpStatus(this.httpError(res.status, detail), res.status);
                 return;
             }
             if (stream) {
@@ -276,7 +379,8 @@ export class OpenAiCompatibleLlm extends BaseLlm {
                 return;
             }
             const data = await res.json();
-            const message = data.choices?.[0]?.message ?? {};
+            const choice = data.choices?.[0] ?? {};
+            const message = choice.message ?? {};
             const usageMetadata = mapUsage(data.usage);
             const { reasoning, answer } = this.extractReasoning(message);
             if (reasoning) {
@@ -308,11 +412,7 @@ export class OpenAiCompatibleLlm extends BaseLlm {
                     },
                 });
             }
-            yield {
-                content: { role: 'model', parts },
-                turnComplete: true,
-                ...(usageMetadata ? { usageMetadata } : {}),
-            };
+            yield this.finalResponse(parts, choice.finish_reason, Boolean(reasoning), usageMetadata);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -338,20 +438,29 @@ export class OpenAiCompatibleLlm extends BaseLlm {
         const toolCalls = new Map();
         let answer = '';
         let answerStarted = false;
+        let sawReasoning = false;
+        let finishReason;
         let usage;
-        const partial = (text, thought) => ({
-            content: {
-                role: 'model',
-                parts: [thought ? { text, thought: true } : { text }],
-            },
-            partial: true,
-        });
+        const partial = (text, thought) => {
+            if (thought)
+                sawReasoning = true;
+            return {
+                content: {
+                    role: 'model',
+                    parts: [thought ? { text, thought: true } : { text }],
+                },
+                partial: true,
+            };
+        };
         // The scratchpad is usually trailed by blank lines; the reply must not
         // open with them, but only the FIRST answer text may be trimmed.
         const openAnswer = (text) => answerStarted ? text : text.trimStart();
         for await (const chunk of sseChunks(res)) {
             if (chunk.usage)
                 usage = chunk.usage;
+            const finish = chunk.choices?.[0]?.finish_reason;
+            if (finish)
+                finishReason = finish;
             const delta = chunk.choices?.[0]?.delta;
             if (!delta)
                 continue;
@@ -409,11 +518,38 @@ export class OpenAiCompatibleLlm extends BaseLlm {
             }
             parts.push({ functionCall: { name: acc.name, args, id: acc.id } });
         }
-        const usageMetadata = mapUsage(usage);
-        yield {
+        yield this.finalResponse(parts, finishReason, sawReasoning, mapUsage(usage));
+    }
+    /**
+     * The one non-partial response that closes a turn, on both paths.
+     *
+     * WHY an empty reply becomes an error: ADK drops a final response with no
+     * parts and no errorCode (llm_agent: "empty content → return"), so the
+     * last event left is the thought partial — ADK logs "The last event is
+     * partial, which is not expected." and the turn ends with empty text and
+     * no reason. That is exactly what a thinking model does when its
+     * scratchpad fills the budget (finish_reason "length"): the answer never
+     * starts. Naming it lets the caller see why, and still carries the usage
+     * so the tokens spent thinking are counted.
+     *
+     * A reply that was cut short but did start keeps its text and is marked
+     * finishReason MAX_TOKENS.
+     */
+    finalResponse(parts, finishReason, sawReasoning, usageMetadata) {
+        if (finishReason)
+            setLlmSpanAttribute('llm.finish_reason', finishReason);
+        const truncated = finishReason === 'length';
+        const usage = usageMetadata ? { usageMetadata } : {};
+        if (parts.length === 0 && (truncated || sawReasoning)) {
+            const noAnswer = { ...this.noAnswerError(truncated), turnComplete: true, ...usage };
+            NO_ANSWER.add(noAnswer);
+            return noAnswer;
+        }
+        return {
             content: { role: 'model', parts },
             turnComplete: true,
-            ...(usageMetadata ? { usageMetadata } : {}),
+            ...(truncated ? { finishReason: FinishReason.MAX_TOKENS } : {}),
+            ...usage,
         };
     }
     // ── Translation helpers ────────────────────────────────────────────────────
@@ -512,14 +648,14 @@ export class OpenAiCompatibleLlm extends BaseLlm {
         for (const [, tool] of Object.entries(llmRequest.toolsDict ?? {})) {
             if (isWebSearchSentinel(tool))
                 continue; // handled via body fields
-            const t = tool;
-            if (t.name && t.description) {
+            const decl = toolDeclarationFor(tool);
+            if (decl) {
                 openAiTools.push({
                     type: 'function',
                     function: {
-                        name: t.name,
-                        description: t.description,
-                        parameters: toLowercaseJsonSchema(t.parameters ?? { type: 'object', properties: {} }),
+                        name: decl.name,
+                        description: decl.description,
+                        parameters: decl.parameters,
                     },
                 });
             }
@@ -535,7 +671,34 @@ export class OpenAiCompatibleLlm extends BaseLlm {
             'Use a Gemini model for live/streaming sessions.');
     }
 }
+/**
+ * Stamps an HTTP error response with its numeric status and whether that
+ * status is transient, so callers above (and the ledger, via the tracer's
+ * llm.payload.response) can tell a rate limit from a bad request without
+ * parsing the message. Applied in the base so a subclass's httpError
+ * override (Ollama's hint, the gateway's GATEWAY_HTTP_ERROR) keeps its
+ * errorCode and wording and still gets the fields.
+ */
+export function withHttpStatus(resp, status) {
+    setLlmSpanAttribute('llm.http_status', status);
+    return { ...resp, status, retryable: isRetryableStatus(status) };
+}
 /** OpenAI-style usage → GenAI usageMetadata (undefined when absent). */
+/** Responses built by noAnswerError: the ones a retry without thinking may replace. */
+const NO_ANSWER = new WeakSet();
+/** Two usage records summed, field by field. */
+export function addUsage(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const out = {};
+    for (const k of ['promptTokenCount', 'candidatesTokenCount', 'thoughtsTokenCount', 'totalTokenCount']) {
+        if (a[k] !== undefined || b[k] !== undefined)
+            out[k] = (a[k] ?? 0) + (b[k] ?? 0);
+    }
+    return out;
+}
 export function mapUsage(usage) {
     if (!usage || typeof usage !== 'object')
         return undefined;

package/dist/lib/models/providerMap.js

@@ -39,7 +39,14 @@ export function providerKeyPresent(provider) {
         return true;
     // Gemini historically accepts either env name.
     if (provider === 'gemini') {
-        return !!(process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY);
+        return realValue(process.env.GOOGLE_GENAI_API_KEY) || realValue(process.env.GEMINI_API_KEY);
     }
-    return !!process.env[keyEnv];
+    return realValue(process.env[keyEnv]);
+}
+/** Set, and not a `.env.example` placeholder (`your_..._here`, `<...>`).
+ *  Inlined rather than imported: this module stays a dependency-free leaf. */
+function realValue(v) {
+    if (!v || !v.trim())
+        return false;
+    return !/^your[_-].*[_-]here$/i.test(v.trim()) && !/^<[^>]*>$/.test(v.trim());
 }

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

@@ -23,22 +23,51 @@
  * 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 type { BaseLlm, GeminiParams, LlmRequest, LlmResponse } from '@google/adk';
+import type { ProviderEndpoint } from './endpoints.ts';
+import { GatewayLlm } from './gatewayLlm.ts';
 import { PROVIDERS, providerForModel, providerKeyPresent } from './providerMap.ts';
 import type { ProviderId } from './providerMap.ts';
 export { providerForModel, providerKeyPresent, PROVIDERS };
+export { endpointFromEnv, endpointLabel, endpointProblems, PLATFORMS_FOR, platformFromEnv, providerReady, } from './endpoints.ts';
+export type { Platform, ProviderEndpoint } from './endpoints.ts';
 export type { ProviderId };
+export { gatewayConfig, gatewayProblem, gatewayUsable, planTransport, GATEWAYS } from './gateway.ts';
+export type { GatewayId, GatewayInfo, TransportPlan } from './gateway.ts';
+export { describeCapabilities, capabilitySummary } from './capabilities.ts';
+export type { CapabilityReport } from './capabilities.ts';
+export { GatewayLlm };
 export declare class TracedGemini extends Gemini {
     static readonly supportedModels: Array<string | RegExp>;
-    generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
+    /**
+     * The Gemini platform (ADR 0023) applies to every construction, the
+     * LLMRegistry's included: on Vertex AI the client authenticates with
+     * Google Application Default Credentials for the configured project and
+     * location, and an AI Studio key (the environment's or a caller's) is not
+     * sent. `endpoint` overrides the environment's (the credentials plug point).
+     */
+    constructor(params?: GeminiParams & {
+        endpoint?: ProviderEndpoint;
+    });
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean, abortSignal?: AbortSignal): AsyncGenerator<LlmResponse, void>;
     /** Tags the llm.request span (web_search = Gemini grounding), then
-     *  delegates to ADK's Gemini. Runs inside the span context. */
+     *  delegates to ADK's Gemini. Runs inside the span context. The abort
+     *  signal is forwarded so a canceled turn stops the request in flight
+     *  (ADK's Gemini puts it on the genai request config). */
     private tagAndGenerate;
 }
 export interface ProviderStatus {
     provider: ProviderId;
     label: string;
     available: boolean;
+    /**
+     * How this provider's ids will be served: its own endpoint, or the
+     * configured gateway standing in because the direct key is absent
+     * (lib/models/gateway.ts). Absent when unavailable.
+     */
+    transport?: 'direct' | 'gateway';
+    /** Gateway id when transport is 'gateway'. */
+    gateway?: string;
     /** Why the provider is unavailable (e.g. which env var is missing). */
     reason?: string;
 }
@@ -48,8 +77,10 @@ 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.
+ * clear API error at call time). When MODEL_GATEWAY is configured, a
+ * provider whose direct key is ABSENT is served by the gateway stand-in
+ * instead (lib/models/gateway.ts — the fallback rule). 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 {
@@ -61,6 +92,12 @@ export interface ResolveModelOptions {
      * YAML always wins.
      */
     defaultProvider?: string;
+    /**
+     * Where this request goes and how it authenticates (ADR 0023), merged over
+     * the environment's endpoint for the model's provider: the credentials plug
+     * point's per-request answer.
+     */
+    endpoint?: Partial<ProviderEndpoint>;
 }
 /**
  * Resolves a model id (from YAML) to a provider adapter INSTANCE, injecting