melchizedek-agents 0.18.0 → 0.20.0

package/dist/lib/models/openAiCompatibleLlm.js

@@ -1,692 +1,130 @@
 /**
- * lib/models/openAiCompatibleLlm.ts — shared base class for every provider
- * that speaks the OpenAI chat-completions wire format.
+ * lib/models/openAiCompatibleLlm.ts — the ADK shim base for every
+ * chat-completions adapter (Ollama, Kimi, the gateway).
  *
  * 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).
+ *   The chat-completions translation lives on the engine's own model
+ *   contract, in lib/models/chatCompletionsAdapter.ts and one adapter per
+ *   provider (ollamaAdapter.ts, kimiAdapter.ts, gatewayAdapter.ts). ADK
+ *   still runs every turn (ADR 0045), so each adapter runs behind an ADK
+ *   BaseLlm: OllamaLlm, KimiLlm and GatewayLlm, subclasses of this class,
+ *   which is an AdkShim (lib/models/adkShim.ts, ADR 0053). The shim charges
+ *   the turn, opens the llm.request span and maps the request and responses;
+ *   the adapter does the provider's work.
  *
- * 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).
- *   - 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.
+ * WHAT THIS CLASS ADDS TO THE SHIM (ADR 0057): the ADK path stays what it
+ * was before the adapters moved onto the contract.
+ *   - The request: an agent's older generateContentConfig spelling that the
+ *     contract leaves out rides beside it (olderSpellingOf): an effort word
+ *     that is no contract level (Kimi K3's `max`). JSON mode without a
+ *     schema is the contract's `outputFormat` (ADR 0061).
+ *   - The response: the final keeps the shape these classes always yielded,
+ *     which the ledger and FallbackLlm read. usageMetadata counts the
+ *     reasoning inside candidatesTokenCount, as the provider's
+ *     completion_tokens does, so llm.tokens.output and the turn's charge are
+ *     unchanged (the shim's default is Gemini's meaning, which excludes it).
+ *     finishReason is set only for a reply cut short (MAX_TOKENS); a final
+ *     with no parts keeps its empty content; an HTTP failure keeps its
+ *     top-level `status` and `retryable` beside the verdict in
+ *     customMetadata.
+ *
+ * A /chat/completions provider of your own is a ChatCompletionsAdapter
+ * subclass (the endpoint, headers, wire name, reasoning field and error
+ * wording), run under ADK as `adkShim(adapter)` or as a subclass of this
+ * class.
  */
-import { BaseLlm } from '@google/adk';
 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>';
+import { AdkShim } from './adkShim.js';
+import { setLlmSpanAttribute } from '../observability/tracer.js';
+import { isRetryableStatus } from './retry.js';
+import { statusDecision, withRetryVerdict } from './errorResponse.js';
+export { REASONING_CONTENT_KIND, splitThinkBlocks, ThinkStreamSplitter } from './chatCompletionsAdapter.js';
+/** The effort words a contract ReasoningSetting carries (genaiMapping's reasoningOf); any other rides as the older spelling. */
+const CONTRACT_EFFORT_WORDS = new Set(['none', 'minimal', 'low', 'medium', 'high']);
 /**
- * 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.
+ * What a generateContentConfig asks of a chat-completions provider that the
+ * contract has no field for, or undefined when it asks nothing more:
+ * `reasoningEffort` when it is a word no ReasoningSetting carries (`max`,
+ * `xhigh`), sent as written. JSON mode without a schema is no longer here:
+ * the genai mapping reads it as `outputFormat: 'json'` (ADR 0061).
  */
-export function splitThinkBlocks(text) {
-    const blocks = [];
-    let answer = text.replace(/<think>([\s\S]*?)<\/think>/g, (_, inner) => {
-        blocks.push(inner.trim());
-        return '';
-    });
-    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() };
-}
-/** 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);
-    for (let n = max; n > 0; n--) {
-        if (s.endsWith(tag.slice(0, n)))
-            return n;
-    }
-    return 0;
+export function olderSpellingOf(config) {
+    const cfg = (config ?? {});
+    const out = {};
+    const effort = cfg.reasoningEffort;
+    if (typeof effort === 'string' && !CONTRACT_EFFORT_WORDS.has(effort))
+        out.reasoningEffort = effort;
+    return Object.keys(out).length > 0 ? out : undefined;
 }
 /**
- * Incremental counterpart to splitThinkBlocks, for the SSE path.
- *
- * WHY a state machine rather than the regex: on a stream the closing
- * `</think>` has usually NOT arrived yet, so the regex matches nothing and
- * the whole scratchpad would be printed as the reply. A tag can also be
- * split mid-delta ("<thi" + "nk>"), so any tail that could still grow into
- * a tag is held back instead of being emitted as answer text.
- *
- * Providers that report reasoning in a discrete field (Ollama's
- * `delta.reasoning`, others' `reasoning_content`) never open a think block
- * and pass straight through this untouched.
+ * Usage as the chat-completions classes have always reported it on the ADK
+ * path: candidatesTokenCount is the provider's completion_tokens, reasoning
+ * included, and thoughtsTokenCount the reasoning part of it.
  */
-export class ThinkStreamSplitter {
-    inThink = false;
-    held = '';
-    /** Routes one content delta into reasoning/answer text. */
-    push(chunk) {
-        let buf = this.held + chunk;
-        let reasoning = '';
-        let answer = '';
-        for (;;) {
-            const tag = this.inThink ? CLOSE_THINK : OPEN_THINK;
-            const at = buf.indexOf(tag);
-            if (at === -1)
-                break;
-            if (this.inThink)
-                reasoning += buf.slice(0, at);
-            else
-                answer += buf.slice(0, at);
-            buf = buf.slice(at + tag.length);
-            this.inThink = !this.inThink;
-        }
-        // Hold back only what could still become the tag we're watching for.
-        const pending = this.inThink ? CLOSE_THINK : OPEN_THINK;
-        const keep = partialTagSuffix(buf, pending);
-        this.held = keep > 0 ? buf.slice(buf.length - keep) : '';
-        const emit = keep > 0 ? buf.slice(0, buf.length - keep) : buf;
-        if (this.inThink)
-            reasoning += emit;
-        else
-            answer += emit;
-        return { reasoning, answer };
-    }
-    /** Releases the held tail; the stream ended, so it was never a tag. */
-    flush() {
-        const rest = this.held;
-        this.held = '';
-        return this.inThink
-            ? { reasoning: rest, answer: '' }
-            : { reasoning: '', answer: rest };
-    }
-}
-/** Yields parsed `data:` payloads from an SSE response body. */
-async function* sseChunks(res) {
-    const reader = res.body?.getReader?.();
-    if (!reader)
-        return;
-    const decoder = new TextDecoder();
-    let buf = '';
-    for (;;) {
-        const { value, done } = await reader.read();
-        if (done)
-            break;
-        buf += decoder.decode(value, { stream: true });
-        let nl;
-        while ((nl = buf.indexOf('\n')) !== -1) {
-            const line = buf.slice(0, nl).trim();
-            buf = buf.slice(nl + 1);
-            // Blank separators and ":" keep-alive comments carry no payload.
-            if (!line.startsWith('data:'))
-                continue;
-            const payload = line.slice('data:'.length).trim();
-            if (payload === '[DONE]')
-                return;
-            try {
-                yield JSON.parse(payload);
-            }
-            catch {
-                /* a chunk that isn't valid JSON is not worth killing the turn for */
-            }
-        }
-    }
+export function chatUsageMetadata(usage) {
+    return {
+        promptTokenCount: usage.inputTokens,
+        candidatesTokenCount: usage.outputTokens,
+        ...(usage.thinkingTokens !== undefined ? { thoughtsTokenCount: usage.thinkingTokens } : {}),
+        totalTokenCount: usage.inputTokens + usage.outputTokens,
+    };
 }
 // ── 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() {
-        return true;
-    }
-    /**
-     * Whether the endpoint honors stream_options.include_usage. Without it an
-     * SSE turn reports no token counts at all; Ollama and xAI both support it.
-     */
-    supportsStreamUsage() {
-        return true;
-    }
-    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,
-        };
+export class OpenAiCompatibleLlm extends AdkShim {
+    constructor(adapter, options = {}) {
+        super(adapter, options);
     }
-    /** 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, 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.`,
-            };
+    /** Provider id for telemetry: the adapter's (a gateway reports the upstream provider). */
+    providerId() {
+        return this.adapter.provider;
     }
-    /** 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, 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 ?? {};
-        const body = {
-            model: this.wireModelName(),
-            messages,
-            stream,
-            // SSE reports token usage only if asked, in a final choices-less chunk.
-            ...(stream && this.supportsStreamUsage()
-                ? { stream_options: { include_usage: true } }
-                : {}),
-            ...(cfg.temperature !== undefined ? { temperature: cfg.temperature } : {}),
-            ...(cfg.topP !== undefined ? { top_p: cfg.topP } : {}),
-            ...(cfg.maxOutputTokens !== undefined
-                ? { max_tokens: cfg.maxOutputTokens }
-                : {}),
-            // Reasoning budget. Qwen3-family models think before answering, and on
-            // a constraint-dense prompt they can spend the whole budget doing it
-            // 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.
-            ...((reasoningEffort ?? cfg.reasoningEffort) !== undefined
-                ? { reasoning_effort: reasoningEffort ?? cfg.reasoningEffort }
-                : {}),
-            ...(openAiTools.length > 0 ? { tools: openAiTools } : {}),
-            // Structured output: an ADK outputSchema becomes a strict json_schema
-            // response_format where the endpoint supports it (xAI does; Ollama's
-            // OpenAI-compatible endpoint does not, see supportsJsonSchemaFormat),
-            // else plain JSON mode.
-            ...(cfg.responseSchema && this.supportsJsonSchemaFormat()
-                ? { response_format: { type: 'json_schema', json_schema: { name: 'response', strict: true, schema: toStrictJsonSchema(cfg.responseSchema) } } }
-                : cfg.responseMimeType === 'application/json' || cfg.responseSchema
-                    ? { 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);
-                setLlmSpanAttribute('llm.capability.dropped', 'web_search');
-                if (!this.webSearchWarned) {
-                    this.webSearchWarned = true;
-                    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 {
-            // 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 withHttpStatus(this.httpError(res.status, detail), res.status);
-                return;
-            }
-            if (stream) {
-                yield* this.streamResponse(res);
-                return;
-            }
-            const data = await res.json();
-            const choice = data.choices?.[0] ?? {};
-            const message = choice.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 this.finalResponse(parts, choice.finish_reason, Boolean(reasoning), usageMetadata);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            yield this.unreachable(msg);
-        }
-    }
-    /**
-     * SSE path: display-only partials as the tokens land, then ONE final
-     * non-partial response carrying the complete text, tool calls and usage.
-     *
-     * WHY the final repeats text already streamed: ADK's runner persists only
-     * non-partial events (`if (!event.partial) appendEvent(...)`), so a final
-     * without text would show the reply on screen and lose it from session
-     * history. Printers therefore skip text on a turnComplete event whose
-     * partials they already rendered — see scripts/syndicate_chat.ts.
-     *
-     * Thinking is deliberately NOT carried on the final: the scratchpad is
-     * display-only and stays out of history, which is what keeps it from
-     * being replayed to the model on the next turn.
-     */
-    async *streamResponse(res) {
-        const splitter = new ThinkStreamSplitter();
-        const toolCalls = new Map();
-        let answer = '';
-        let answerStarted = false;
-        let sawReasoning = false;
-        let finishReason;
-        let usage;
-        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;
-            // Reasoning as a discrete field (Ollama `reasoning`, others
-            // `reasoning_content`) — already separated, no tag parsing needed.
-            const fieldReasoning = delta.reasoning ?? delta.reasoning_content ?? '';
-            if (fieldReasoning)
-                yield partial(fieldReasoning, true);
-            if (typeof delta.content === 'string' && delta.content) {
-                const split = splitter.push(delta.content);
-                if (split.reasoning)
-                    yield partial(split.reasoning, true);
-                if (split.answer) {
-                    const text = openAnswer(split.answer);
-                    if (text) {
-                        answerStarted = true;
-                        answer += text;
-                        yield partial(text, false);
-                    }
-                }
-            }
-            // Tool arguments arrive as fragments keyed by index, not whole.
-            for (const call of delta.tool_calls ?? []) {
-                const index = call.index ?? 0;
-                const acc = toolCalls.get(index) ?? { args: '' };
-                if (call.id)
-                    acc.id = call.id;
-                if (call.function?.name)
-                    acc.name = call.function.name;
-                if (call.function?.arguments)
-                    acc.args += call.function.arguments;
-                toolCalls.set(index, acc);
-            }
-        }
-        const tail = splitter.flush();
-        if (tail.reasoning)
-            yield partial(tail.reasoning, true);
-        if (tail.answer) {
-            const text = openAnswer(tail.answer);
-            if (text) {
-                answer += text;
-                yield partial(text, false);
-            }
-        }
-        const parts = [];
-        if (answer)
-            parts.push({ text: answer });
-        for (const [, acc] of [...toolCalls.entries()].sort((a, b) => a[0] - b[0])) {
-            let args = {};
-            try {
-                args = JSON.parse(acc.args || '{}');
-            }
-            catch {
-                args = { raw: acc.args };
-            }
-            parts.push({ functionCall: { name: acc.name, args, id: acc.id } });
-        }
-        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,
-            ...(truncated ? { finishReason: FinishReason.MAX_TOKENS } : {}),
-            ...usage,
-        };
+    /** How the request reaches the provider: 'direct' or 'gateway:<id>' (llm.transport). */
+    transport() {
+        return this.adapter.transport();
     }
-    // ── Translation helpers ────────────────────────────────────────────────────
-    /** ADK Contents (Google GenAI format) → OpenAI-compatible chat messages. */
+    /** The chat messages the adapter sends for this LlmRequest. */
     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;
+        return this.adapter.messagesFor(this.toModelRequest(llmRequest, { model: this.model }));
     }
-    /** ADK toolsDict → OpenAI function-tool definitions (lowercase schemas). */
+    /** The function tools the adapter sends for this LlmRequest (lowercase schemas). */
     buildTools(llmRequest) {
-        const openAiTools = [];
-        for (const [, tool] of Object.entries(llmRequest.toolsDict ?? {})) {
-            if (isWebSearchSentinel(tool))
-                continue; // handled via body fields
-            const decl = toolDeclarationFor(tool);
-            if (decl) {
-                openAiTools.push({
-                    type: 'function',
-                    function: {
-                        name: decl.name,
-                        description: decl.description,
-                        parameters: decl.parameters,
-                    },
-                });
-            }
-        }
-        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.');
+        return this.adapter.toolsFor(this.toModelRequest(llmRequest, { model: this.model }));
+    }
+    /** The genai mapping's request, with the older spelling the contract leaves out. */
+    toModelRequest(llmRequest, options) {
+        const request = super.toModelRequest(llmRequest, options);
+        const olderSpelling = olderSpellingOf(llmRequest.config);
+        return olderSpelling ? { ...request, olderSpelling } : request;
+    }
+    /** The genai mapping's response, in the shape these classes have always yielded (see the header). */
+    toLlmResponse(response) {
+        const mapped = super.toLlmResponse(response);
+        if (response.partial)
+            return mapped;
+        const { finishReason: _finish, usageMetadata: _usage, ...rest } = mapped;
+        const error = response.error;
+        return {
+            ...(error ? {} : { content: { role: 'model', parts: [] } }),
+            ...rest,
+            ...(!error && response.finishReason === 'max_tokens' ? { finishReason: FinishReason.MAX_TOKENS } : {}),
+            ...(response.usage ? { usageMetadata: chatUsageMetadata(response.usage) } : {}),
+            ...(error?.status !== undefined ? { status: error.status, retryable: error.retryable } : {}),
+        };
     }
 }
+// ── Kept for callers of the ADK-path helpers ─────────────────────────────────
 /**
  * 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.
+ * status is transient, and the same verdict in customMetadata
+ * ('error.retryable', 'error.status'), where FallbackLlm reads it
+ * (lib/models/errorResponse.ts). The chat-completions shims take these
+ * fields from their adapter's error final instead (toLlmResponse).
  */
 export function withHttpStatus(resp, status) {
     setLlmSpanAttribute('llm.http_status', status);
-    return { ...resp, status, retryable: isRetryableStatus(status) };
+    return { ...withRetryVerdict(resp, statusDecision(status)), 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. */
+/** Two genai usage records summed, field by field. */
 export function addUsage(a, b) {
     if (!a)
         return b;
@@ -699,20 +137,20 @@ export function addUsage(a, b) {
     }
     return out;
 }
+/**
+ * OpenAI-style usage → GenAI usageMetadata in the ADK-path meaning
+ * (completion_tokens, reasoning included, as candidatesTokenCount), or
+ * undefined when absent. The contract's meaning is chatUsage in
+ * lib/models/chatCompletionsAdapter.ts.
+ */
 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 }
-            : {}),
+        ...(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 }
-            : {}),
+        ...(usage.total_tokens !== undefined ? { totalTokenCount: usage.total_tokens } : {}),
     };
 }