melchizedek-agents 0.18.0 → 0.19.0

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

@@ -0,0 +1,63 @@
+/**
+ * lib/models/providerState.ts — provider-opaque reasoning state carried on a
+ * model content part from one model step to the next (ADR 0046).
+ *
+ * WHY: some providers want back, on the next request of a tool loop, state
+ * only they can read: Anthropic's signed `thinking` and `redacted_thinking`
+ * blocks, OpenAI's and xAI's reasoning items, Moonshot's reasoning_content.
+ * ADK's request is built from each event's `content` alone (event metadata
+ * never reaches it), and @google/genai serializes a part field by field, so
+ * the state rides as one extra field on a part the model actually produced:
+ *
+ *     { functionCall: {...}, providerState: { provider, kind, payload } }
+ *
+ * THE RULES:
+ *   - The adapter that produced the response writes it, on the part the
+ *     state belongs before (Claude: the part its signed blocks preceded).
+ *   - Only an adapter of the same `provider` replays it, and only the `kind`
+ *     it wrote (and, when `model` is set, only that model). Every other
+ *     adapter ignores the field, so a model switch between steps drops the
+ *     state rather than misreading it.
+ *   - `payload` is opaque to everything but the writer, JSON-serializable,
+ *     and replayed verbatim. The session services store it with the event;
+ *     the transcript projection drops it with the rest of a past turn's
+ *     machinery (lib/session/transcript.ts).
+ */
+/** The field name on a content part. */
+export declare const PROVIDER_STATE_FIELD = "providerState";
+export interface ProviderState {
+    /** The writer's provider id (lib/models/providerMap.ts), e.g. `anthropic`. */
+    provider: string;
+    /** What the payload is, in the writer's terms, e.g. `thinking_blocks`. */
+    kind: string;
+    /**
+     * The model that wrote it, when the provider binds the state to a model
+     * (Anthropic's signed thinking): a reader skips state another model wrote.
+     */
+    model?: string;
+    /** Opaque to everyone but the writer; replayed verbatim. */
+    payload: unknown;
+}
+/**
+ * The state `provider` wrote on a part, or undefined when the part carries
+ * none, another provider's, another kind, a malformed one, or (with `model`
+ * given) one another model wrote.
+ */
+export declare function providerStateOf(part: unknown, provider: string, kind: string, model?: string): ProviderState | undefined;
+/** A copy of `part` carrying `state`; the input is not mutated. */
+export declare function withProviderState<T extends object>(part: T, state: ProviderState): T & {
+    providerState: ProviderState;
+};
+/**
+ * Where the current turn starts in `contents`: the index of the last user
+ * content that is not purely tool results, or -1 when there is none (every
+ * content is then this turn's, the first included). The model contents
+ * after it are this turn's tool loop, the only place an adapter replays its
+ * state. Earlier turns' state is left out: dropping it from the front of
+ * the history is allowed, and the stored history before it may differ from
+ * what the model saw (tool payloads are elided before storage).
+ */
+export declare function currentTurnStart(contents: ReadonlyArray<{
+    role?: string;
+    parts?: ReadonlyArray<unknown>;
+}>): number;

package/dist/lib/models/providerState.js

@@ -0,0 +1,61 @@
+/**
+ * lib/models/providerState.ts — provider-opaque reasoning state carried on a
+ * model content part from one model step to the next (ADR 0046).
+ *
+ * WHY: some providers want back, on the next request of a tool loop, state
+ * only they can read: Anthropic's signed `thinking` and `redacted_thinking`
+ * blocks, OpenAI's and xAI's reasoning items, Moonshot's reasoning_content.
+ * ADK's request is built from each event's `content` alone (event metadata
+ * never reaches it), and @google/genai serializes a part field by field, so
+ * the state rides as one extra field on a part the model actually produced:
+ *
+ *     { functionCall: {...}, providerState: { provider, kind, payload } }
+ *
+ * THE RULES:
+ *   - The adapter that produced the response writes it, on the part the
+ *     state belongs before (Claude: the part its signed blocks preceded).
+ *   - Only an adapter of the same `provider` replays it, and only the `kind`
+ *     it wrote (and, when `model` is set, only that model). Every other
+ *     adapter ignores the field, so a model switch between steps drops the
+ *     state rather than misreading it.
+ *   - `payload` is opaque to everything but the writer, JSON-serializable,
+ *     and replayed verbatim. The session services store it with the event;
+ *     the transcript projection drops it with the rest of a past turn's
+ *     machinery (lib/session/transcript.ts).
+ */
+/** The field name on a content part. */
+export const PROVIDER_STATE_FIELD = 'providerState';
+/**
+ * The state `provider` wrote on a part, or undefined when the part carries
+ * none, another provider's, another kind, a malformed one, or (with `model`
+ * given) one another model wrote.
+ */
+export function providerStateOf(part, provider, kind, model) {
+    const state = part?.[PROVIDER_STATE_FIELD];
+    if (!state || typeof state !== 'object')
+        return undefined;
+    if (state.provider !== provider || state.kind !== kind)
+        return undefined;
+    return model !== undefined && state.model !== undefined && state.model !== model ? undefined : state;
+}
+/** A copy of `part` carrying `state`; the input is not mutated. */
+export function withProviderState(part, state) {
+    return { ...part, [PROVIDER_STATE_FIELD]: state };
+}
+/**
+ * Where the current turn starts in `contents`: the index of the last user
+ * content that is not purely tool results, or -1 when there is none (every
+ * content is then this turn's, the first included). The model contents
+ * after it are this turn's tool loop, the only place an adapter replays its
+ * state. Earlier turns' state is left out: dropping it from the front of
+ * the history is allowed, and the stored history before it may differ from
+ * what the model saw (tool payloads are elided before storage).
+ */
+export function currentTurnStart(contents) {
+    for (let i = contents.length - 1; i >= 0; i--) {
+        const c = contents[i];
+        if (c.role === 'user' && (c.parts ?? []).some((p) => !p?.functionResponse))
+            return i;
+    }
+    return -1;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * lib/models/reasoning.ts — the generateContentConfig fields a `reasoning:`
+ * setting becomes for one model (ADR 0047).
+ *
+ * WHY HERE: the compiler maps an agent's `reasoning:` key through this, and
+ * a model adapter on the contract (lib/models/geminiAdapter.ts) maps a
+ * ModelRequest's `reasoning` the same way. Keeping it out of lib/compile.ts
+ * keeps ADK out of an adapter's imports. lib/compile.ts re-exports both
+ * names, so existing imports keep working.
+ */
+import type { ReasoningLevel, ReasoningSetting } from './contract.ts';
+/**
+ * Thinking tokens per level, for the providers that take a budget (Claude,
+ * Gemini 2.x). The same table rounds a `budget_tokens` value up to a level
+ * for the providers that take only a level or an effort word.
+ */
+export declare const REASONING_BUDGETS: Readonly<Record<ReasoningLevel, number>>;
+/**
+ * The generateContentConfig fields a `reasoning:` setting becomes for one
+ * model (ADR 0047). `reasoningEffort` is always set, so the gateway (which
+ * may serve any id) carries the level too; the Claude adapter reads it first
+ * on the adaptive generations (ADR 0049), and the genai SDK drops it from a
+ * Gemini request. Claude and Gemini also get the `thinkingConfig` their
+ * adapters read.
+ */
+export declare function reasoningConfig(model: string, setting: ReasoningSetting): Record<string, unknown>;

package/dist/lib/models/reasoning.js

@@ -0,0 +1,59 @@
+import { providerForModel } from './providerMap.js';
+/**
+ * Thinking tokens per level, for the providers that take a budget (Claude,
+ * Gemini 2.x). The same table rounds a `budget_tokens` value up to a level
+ * for the providers that take only a level or an effort word.
+ */
+export const REASONING_BUDGETS = { none: 0, low: 2048, medium: 8192, high: 16384 };
+const GEMINI_THINKING_LEVEL = { none: 'MINIMAL', low: 'LOW', medium: 'MEDIUM', high: 'HIGH' };
+/** The smallest level whose budget covers the setting: never less thought than asked. */
+function reasoningLevel(setting) {
+    if (typeof setting === 'string')
+        return setting;
+    const n = setting.budget_tokens;
+    return n <= 0 ? 'none' : n <= REASONING_BUDGETS.low ? 'low' : n <= REASONING_BUDGETS.medium ? 'medium' : 'high';
+}
+/**
+ * The effort word for `generateContentConfig.reasoningEffort`, which the
+ * chat-completions adapters, the gateway and the Responses adapters read.
+ * A word the provider lacks becomes its nearest setting above.
+ */
+function reasoningEffort(model, level) {
+    switch (providerForModel(model)) {
+        case 'openai':
+            if (level !== 'none')
+                return level;
+            // o-series cannot stop reasoning; the first GPT-5 generation says
+            // "minimal"; GPT-5.1 and later say "none".
+            return /^o\d/.test(model) ? 'low' : /^gpt-5(?![.\d])/.test(model) ? 'minimal' : 'none';
+        case 'xai':
+            return level === 'none' ? 'low' : level; // Grok 4.5/4.7 cannot stop reasoning
+        case 'moonshot':
+            return level === 'medium' ? 'high' : level; // K3 has low | high | max
+        default:
+            return level;
+    }
+}
+/**
+ * The generateContentConfig fields a `reasoning:` setting becomes for one
+ * model (ADR 0047). `reasoningEffort` is always set, so the gateway (which
+ * may serve any id) carries the level too; the Claude adapter reads it first
+ * on the adaptive generations (ADR 0049), and the genai SDK drops it from a
+ * Gemini request. Claude and Gemini also get the `thinkingConfig` their
+ * adapters read.
+ */
+export function reasoningConfig(model, setting) {
+    const level = reasoningLevel(setting);
+    const budget = typeof setting === 'string' ? REASONING_BUDGETS[setting] : setting.budget_tokens;
+    const out = { reasoningEffort: reasoningEffort(model, level) };
+    const provider = providerForModel(model);
+    if (provider === 'anthropic')
+        out.thinkingConfig = { thinkingBudget: budget };
+    if (provider === 'gemini') {
+        // Gemini 3 takes a level; 2.x and older take only a budget. An explicit
+        // budget is sent as one on any Gemini, except 0, which is `none`.
+        const budgetOnly = /^gemini-[12]\./.test(model);
+        out.thinkingConfig = budgetOnly || (typeof setting !== 'string' && budget > 0) ? { thinkingBudget: budget } : { thinkingLevel: GEMINI_THINKING_LEVEL[level] };
+    }
+    return out;
+}

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

@@ -3,28 +3,49 @@
  * optionality: an agent's YAML declares `model`, and this module makes sure
  * that string reaches the right provider adapter.
  *
- * TWO RESOLUTION PATHS, ONE PREFIX TABLE (lib/models/providerMap.ts):
+ * THREE RESOLUTION PATHS, ONE PREFIX TABLE (lib/models/providerMap.ts):
  *
  *   1. registerAvailableProviders() — for entrypoints that pass `model` as a
  *      STRING to LlmAgent (scripts/syndicate_chat.ts). Registers every
- *      adapter whose credentials exist into the ADK LLMRegistry; the
- *      registry then string-matches supportedModels patterns:
+ *      provider's own ADK class whose credentials exist into the ADK
+ *      LLMRegistry; the registry then string-matches supportedModels patterns:
  *        claude-*  → ClaudeLlm      gpt-* / o<digit>* → GptLlm
  *        grok-*    → GrokLlm        ollama/<model>    → OllamaLlm
  *        kimi-*    → KimiLlm        gemini-*          → TracedGemini (ADK's Gemini + llm.request spans)
+ *      Each non-Gemini class is the ADK shim around its contract adapter,
+ *      with the provider's own toLlmResponse (ADR 0056, ADR 0057); never a
+ *      bare adkShimClass, which would lose it.
  *
- *   2. resolveModel() — instance factory for BYOK paths (scripts/
- *      a2a_server.ts), where a per-request API key from an HTTP header must
- *      be injected into the adapter. Same prefix table; the YAML model
- *      string always wins over the X-Provider header (which only selects a
- *      DEFAULT model when the YAML omits `model` — a deprecated affordance).
+ *   2. resolveModel() — the ADK BaseLlm INSTANCE for one id, for BYOK paths
+ *      (lib/a2a/app.ts), where a per-request API key or endpoint must be
+ *      injected. The same classes. The YAML model string always wins over
+ *      the X-Provider header (which only selects a DEFAULT model when the
+ *      YAML omits `model` — a deprecated affordance).
+ *
+ *   3. resolveAdapter() — the engine's own ModelAdapter (lib/models/
+ *      contract.ts, ADR 0048) for one id, with no ADK LLMRegistry, for the
+ *      native loop (ADR 0045). The same transport rule (the gateway when the
+ *      direct key is absent), the same BYOK and endpoint injection. Gemini
+ *      ids get the temporary AdkGeminiAdapter until gate G3, or the engine's
+ *      GeminiAdapter when GEMINI_ADAPTER=engine or `{ gemini: 'engine' }`
+ *      asks for it (ADR 0060). resolveAdapterWithFallback() wraps a pair in a
+ *      FallbackAdapter; the ADK path keeps FallbackLlm(shim, shim) (ADR 0053).
+ *
+ * Paths 2 and 3 read one routing step (routeFor) and one table per path
+ * keyed by provider, so a key or endpoint reaches the same place on both.
+ * routeFor and the contract table live in lib/models/adapterResolver.ts,
+ * which imports no ADK; `melchizedek-agents/model` exports its resolver,
+ * which gives a Gemini id GeminiAdapter (ADR 0068).
  *
  * Register BEFORE constructing any agent: the LLMRegistry caches model→class
  * resolution (LRU), so late registration can be masked by stale cache hits.
  */
-import { Gemini } from '@google/adk';
-import type { BaseLlm, GeminiParams, LlmRequest, LlmResponse } from '@google/adk';
+import type { BaseLlm } from '@google/adk';
 import type { ProviderEndpoint } from './endpoints.ts';
+import type { ModelAdapter } from './contract.ts';
+import type { GeminiAdapterChoice, ResolveAdapterOptions } from './adapterResolver.ts';
+import type { FallbackAdapterOptions } from './fallbackAdapter.ts';
+import { TracedGemini } from './tracedGemini.ts';
 import { GatewayLlm } from './gatewayLlm.ts';
 import { PROVIDERS, providerForModel, providerKeyPresent } from './providerMap.ts';
 import type { ProviderId } from './providerMap.ts';
@@ -32,30 +53,12 @@ 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 type { GeminiAdapterChoice, ResolveAdapterOptions };
 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>;
-    /**
-     * 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. 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 { GatewayLlm, TracedGemini };
 export interface ProviderStatus {
     provider: ProviderId;
     label: string;
@@ -89,7 +92,7 @@ export interface ResolveModelOptions {
     /**
      * DEPRECATED — the A2A X-Provider header. Only consulted when `model` is
      * undefined, to pick that provider's default model. A model id in the
-     * YAML always wins.
+     * YAML always wins. It also names the provider `apiKey` belongs to.
      */
     defaultProvider?: string;
     /**
@@ -100,9 +103,29 @@ export interface ResolveModelOptions {
     endpoint?: Partial<ProviderEndpoint>;
 }
 /**
- * Resolves a model id (from YAML) to a provider adapter INSTANCE, injecting
- * a per-request apiKey where the provider accepts one. When `model` is
- * undefined, falls back to the default model of `defaultProvider` (or
- * Gemini).
+ * Resolves a model id (from YAML) to a provider adapter INSTANCE for the ADK
+ * runtime, injecting a per-request apiKey where the provider accepts one.
+ * When `model` is undefined, falls back to the default model of
+ * `defaultProvider` (or Gemini).
  */
 export declare function resolveModel(model: string | undefined, options?: ResolveModelOptions): BaseLlm;
+/** GEMINI_ADAPTER (`adk`, the default here, or `engine`). Any other value is a configuration error. */
+export declare function geminiAdapterChoice(env?: NodeJS.ProcessEnv): GeminiAdapterChoice;
+/**
+ * Resolves a model id to the engine's own ModelAdapter (ADR 0048), from the
+ * same prefix table and transport rule as resolveModel, with no ADK
+ * LLMRegistry: the provider's adapter when its key (env, BYOK or endpoint)
+ * is present, the gateway's when it is absent and MODEL_GATEWAY is set.
+ * The adapter opens no span and charges nothing: its caller does (ADR 0053).
+ */
+export declare function resolveAdapter(modelId: string, options?: ResolveAdapterOptions): ModelAdapter;
+/**
+ * An agent's model and its `fallback_model:` on the contract path: a
+ * FallbackAdapter (ADR 0044) around resolveAdapter's two adapters, or the
+ * primary alone when there is no fallback. The caller's key stays with its
+ * own provider: unless `keyProvider` says otherwise it belongs to the
+ * primary's, so a fallback on another provider resolves from server env.
+ * Nothing calls this yet; the ADK path's pair stays
+ * FallbackLlm(shim(primary), shim(fallback)) (ADR 0053).
+ */
+export declare function resolveAdapterWithFallback(modelId: string, fallbackId: string | undefined, options?: ResolveAdapterOptions, fallbackOptions?: FallbackAdapterOptions): ModelAdapter;

package/dist/lib/models/registry.js

@@ -3,105 +3,62 @@
  * optionality: an agent's YAML declares `model`, and this module makes sure
  * that string reaches the right provider adapter.
  *
- * TWO RESOLUTION PATHS, ONE PREFIX TABLE (lib/models/providerMap.ts):
+ * THREE RESOLUTION PATHS, ONE PREFIX TABLE (lib/models/providerMap.ts):
  *
  *   1. registerAvailableProviders() — for entrypoints that pass `model` as a
  *      STRING to LlmAgent (scripts/syndicate_chat.ts). Registers every
- *      adapter whose credentials exist into the ADK LLMRegistry; the
- *      registry then string-matches supportedModels patterns:
+ *      provider's own ADK class whose credentials exist into the ADK
+ *      LLMRegistry; the registry then string-matches supportedModels patterns:
  *        claude-*  → ClaudeLlm      gpt-* / o<digit>* → GptLlm
  *        grok-*    → GrokLlm        ollama/<model>    → OllamaLlm
  *        kimi-*    → KimiLlm        gemini-*          → TracedGemini (ADK's Gemini + llm.request spans)
+ *      Each non-Gemini class is the ADK shim around its contract adapter,
+ *      with the provider's own toLlmResponse (ADR 0056, ADR 0057); never a
+ *      bare adkShimClass, which would lose it.
  *
- *   2. resolveModel() — instance factory for BYOK paths (scripts/
- *      a2a_server.ts), where a per-request API key from an HTTP header must
- *      be injected into the adapter. Same prefix table; the YAML model
- *      string always wins over the X-Provider header (which only selects a
- *      DEFAULT model when the YAML omits `model` — a deprecated affordance).
+ *   2. resolveModel() — the ADK BaseLlm INSTANCE for one id, for BYOK paths
+ *      (lib/a2a/app.ts), where a per-request API key or endpoint must be
+ *      injected. The same classes. The YAML model string always wins over
+ *      the X-Provider header (which only selects a DEFAULT model when the
+ *      YAML omits `model` — a deprecated affordance).
+ *
+ *   3. resolveAdapter() — the engine's own ModelAdapter (lib/models/
+ *      contract.ts, ADR 0048) for one id, with no ADK LLMRegistry, for the
+ *      native loop (ADR 0045). The same transport rule (the gateway when the
+ *      direct key is absent), the same BYOK and endpoint injection. Gemini
+ *      ids get the temporary AdkGeminiAdapter until gate G3, or the engine's
+ *      GeminiAdapter when GEMINI_ADAPTER=engine or `{ gemini: 'engine' }`
+ *      asks for it (ADR 0060). resolveAdapterWithFallback() wraps a pair in a
+ *      FallbackAdapter; the ADK path keeps FallbackLlm(shim, shim) (ADR 0053).
+ *
+ * Paths 2 and 3 read one routing step (routeFor) and one table per path
+ * keyed by provider, so a key or endpoint reaches the same place on both.
+ * routeFor and the contract table live in lib/models/adapterResolver.ts,
+ * which imports no ADK; `melchizedek-agents/model` exports its resolver,
+ * which gives a Gemini id GeminiAdapter (ADR 0068).
  *
  * Register BEFORE constructing any agent: the LLMRegistry caches model→class
  * resolution (LRU), so late registration can be masked by stale cache hits.
  */
 import { Gemini, LLMRegistry } from '@google/adk';
-import { endpointFromEnv, endpointProblems, mergeEndpoint, platformModel, providerReady } from './endpoints.js';
-import { currentTurnSignal } from '../runtime/turnControl.js';
-import { errorStatus, retryUntilFirstYield } from './retry.js';
+import { endpointFromEnv, endpointProblems, providerReady } from './endpoints.js';
 import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_KIMI_MODEL, DEFAULT_OLLAMA_MODEL, } from '../config.js';
-import { traceLlmGeneration, setLlmSpanAttribute, } from '../observability/tracer.js';
+import { AdkGeminiAdapter } from './adkGeminiAdapter.js';
+import { adapterResolver, geminiAdapterSetting, normalizeProvider, routeFor, scopedKey } from './adapterResolver.js';
+import { TracedGemini } from './tracedGemini.js';
 import { ClaudeLlm, registerClaudeLlm } from './claudeLlm.js';
 import { GptLlm, registerGptLlm } from './gptLlm.js';
 import { GrokLlm, registerGrokLlm } from './grokLlm.js';
 import { KimiLlm, registerKimiLlm } from './kimiLlm.js';
 import { OllamaLlm, registerOllamaLlm } from './ollamaLlm.js';
 import { GatewayLlm, registerGatewayLlm } from './gatewayLlm.js';
-import { gatewayConfig, gatewayProblem, gatewayUsable, planTransport, } from './gateway.js';
+import { gatewayConfig, gatewayProblem, gatewayUsable } from './gateway.js';
 import { PROVIDERS, providerForModel, providerKeyPresent, } from './providerMap.js';
 export { providerForModel, providerKeyPresent, PROVIDERS };
 export { endpointFromEnv, endpointLabel, endpointProblems, PLATFORMS_FOR, platformFromEnv, providerReady, } from './endpoints.js';
 export { gatewayConfig, gatewayProblem, gatewayUsable, planTransport, GATEWAYS } from './gateway.js';
 export { describeCapabilities, capabilitySummary } from './capabilities.js';
-export { GatewayLlm };
-// ── TracedGemini ─────────────────────────────────────────────────────────────
-// ADK's built-in Gemini adapter, wrapped so Gemini calls emit the same
-// per-request llm.request spans (tokens, latency) as every other provider,
-// and get the shared transient-failure retries (lib/models/retry.ts).
-export class TracedGemini extends Gemini {
-    // CRITICAL: reuse Gemini's exact regex instances. The LLMRegistry dict is
-    // keyed by the regex OBJECT — registering the same instances REPLACES the
-    // built-in Gemini entries instead of adding shadowed duplicates.
-    static supportedModels = Gemini.supportedModels;
-    /**
-     * 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 = {}) {
-        const { endpoint: given, ...rest } = params;
-        const e = given ?? endpointFromEnv('gemini');
-        const model = rest.model ? platformModel(e, rest.model) : rest.model;
-        super(e.platform === 'vertex'
-            ? { ...rest, model, apiKey: e.apiKey, vertexai: true, project: e.project, location: e.location }
-            : { ...rest, model, ...(e.apiKey && !rest.apiKey ? { apiKey: e.apiKey } : {}) });
-    }
-    async *generateContentAsync(llmRequest, stream, abortSignal) {
-        yield* traceLlmGeneration({ provider: 'gemini', model: this.model, llmRequest }, this.tagAndGenerate(llmRequest, stream, abortSignal ?? currentTurnSignal()));
-    }
-    /** Tags the llm.request span (web_search = Gemini grounding), then
-     *  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). */
-    async *tagAndGenerate(llmRequest, stream, abortSignal) {
-        const hasGrounding = (llmRequest.config?.tools ?? []).some((t) => t && (t.googleSearch || t.googleSearchRetrieval));
-        if (hasGrounding)
-            setLlmSpanAttribute('llm.web_search.native', true);
-        // Retries live here, not in genai's own httpOptions.retryOptions: that
-        // hook (p-retry 4, client-level only) ignores the abort signal — it
-        // sleeps and re-sends after a canceled turn — honours no Retry-After,
-        // does not retry Node's "fetch failed" resets, and replaces a 4xx's
-        // error body (e.g. "API key not valid") with a bare statusText. Wrapping
-        // the call keeps genai's ApiError intact and applies the same policy as
-        // every other adapter. A retry is only made while nothing has been
-        // yielded, so a stream that fails mid-reply is surfaced, not replayed.
-        // ADK's request preprocessing is idempotent, so re-sending the same
-        // llmRequest is safe. Both the registry class and resolveModel()'s
-        // per-request instances are TracedGemini, so both get this.
-        try {
-            yield* retryUntilFirstYield(() => super.generateContentAsync(llmRequest, stream, abortSignal), {
-                signal: abortSignal,
-                onRetry: ({ retries }) => setLlmSpanAttribute('llm.retries', retries),
-            });
-        }
-        catch (err) {
-            // genai's ApiError carries the status; put it where the ledger reads.
-            const status = errorStatus(err);
-            if (status !== undefined)
-                setLlmSpanAttribute('llm.http_status', status);
-            throw err;
-        }
-    }
-}
+export { GatewayLlm, TracedGemini };
 /** Availability report without side effects (used by demos and key gates). */
 export function providerStatuses() {
     const gw = gatewayUsable() ? gatewayConfig() : null;
@@ -229,50 +186,64 @@ const DEFAULT_MODEL_FOR = {
     ollama: DEFAULT_OLLAMA_MODEL,
 };
 /**
- * Resolves a model id (from YAML) to a provider adapter INSTANCE, injecting
- * a per-request apiKey where the provider accepts one. When `model` is
- * undefined, falls back to the default model of `defaultProvider` (or
- * Gemini).
+ * Each provider's ADK class for a direct route: the provider's own exported
+ * class, so GptLlm's and the chat-completions shims' toLlmResponse keep the
+ * ledger's usage meaning (ADR 0056, ADR 0057). Grok has no platforms, so it
+ * takes no endpoint; Kimi takes its base URL; Ollama is local and takes
+ * neither.
+ */
+const ADK_LLM = {
+    ollama: (r) => new OllamaLlm({ model: r.model }),
+    anthropic: (r) => new ClaudeLlm({ model: r.model, apiKey: r.apiKey, endpoint: r.endpoint }),
+    openai: (r) => new GptLlm({ model: r.model, apiKey: r.apiKey, endpoint: r.endpoint }),
+    xai: (r) => new GrokLlm({ model: r.model, apiKey: r.apiKey }),
+    moonshot: (r) => new KimiLlm({ model: r.model, apiKey: r.apiKey, baseUrl: r.endpoint?.baseURL }),
+    gemini: (r) => new TracedGemini({ model: r.model, apiKey: r.apiKey, endpoint: r.endpoint }),
+};
+/**
+ * Resolves a model id (from YAML) to a provider adapter INSTANCE for the ADK
+ * runtime, injecting a per-request apiKey where the provider accepts one.
+ * When `model` is undefined, falls back to the default model of
+ * `defaultProvider` (or Gemini).
  */
 export function resolveModel(model, options = {}) {
-    const resolved = model ??
-        DEFAULT_MODEL_FOR[normalizeProvider(options.defaultProvider)];
-    // BYOK is scoped to the CALLER'S provider: the X-API-Key a client sends
-    // authenticates that client's own provider (typically Gemini). Passing it
-    // to a different provider's adapter would override the server's env key
-    // (adapters prefer a passed key) and fail auth — e.g. a Gemini key sent to
-    // xAI. Cross-provider agents therefore resolve keys from server env.
-    const apiKey = providerForModel(model ?? DEFAULT_MODEL_FOR[normalizeProvider(options.defaultProvider)]) === normalizeProvider(options.defaultProvider)
-        ? options.apiKey
-        : undefined;
-    // The fallback rule (lib/models/gateway.ts): the direct adapter whenever
-    // the provider's key — from env, or the caller's own BYOK key — is
-    // present; the gateway stand-in only when it is absent and a gateway is
-    // configured. The gateway key is server env only, never a request header.
-    const provider = providerForModel(resolved);
-    const endpoint = options.endpoint ? mergeEndpoint(provider, options.endpoint) : undefined;
-    if (planTransport(resolved, { callerKey: !!apiKey || !!endpoint }).transport === 'gateway') {
-        return new GatewayLlm({ model: resolved });
-    }
-    switch (provider) {
-        case 'ollama':
-            return new OllamaLlm({ model: resolved });
-        case 'anthropic':
-            return new ClaudeLlm({ model: resolved, apiKey, endpoint });
-        case 'openai':
-            return new GptLlm({ model: resolved, apiKey, endpoint });
-        case 'xai':
-            return new GrokLlm({ model: resolved, apiKey });
-        case 'moonshot':
-            return new KimiLlm({ model: resolved, apiKey, baseUrl: endpoint?.baseURL });
-        case 'gemini':
-            return new TracedGemini({ model: resolved, apiKey, endpoint });
-    }
+    const keyProvider = normalizeProvider(options.defaultProvider);
+    const resolved = model ?? DEFAULT_MODEL_FOR[keyProvider];
+    const route = routeFor(resolved, scopedKey(resolved, options.apiKey, keyProvider), options.endpoint);
+    return route.transport === 'gateway' ? new GatewayLlm({ model: resolved }) : ADK_LLM[route.provider](route);
 }
-function normalizeProvider(provider) {
-    const p = provider?.toLowerCase();
-    if (p === 'ollama' || p === 'anthropic' || p === 'openai' || p === 'xai' || p === 'moonshot') {
-        return p;
-    }
-    return 'gemini';
+// ── Contract adapters (the native runtime) ───────────────────────────────────
+/** GEMINI_ADAPTER (`adk`, the default here, or `engine`). Any other value is a configuration error. */
+export function geminiAdapterChoice(env = process.env) {
+    return geminiAdapterSetting(env) ?? 'adk';
+}
+/**
+ * The contract resolver with the temporary AdkGeminiAdapter (ADR 0060): a
+ * Gemini id gets it until gate G3, or the engine's GeminiAdapter when
+ * GEMINI_ADAPTER=engine or `{ gemini: 'engine' }` asks for it. The
+ * ADK-free resolver in lib/models/adapterResolver.ts, which
+ * `melchizedek-agents/model` exports, defaults to GeminiAdapter (ADR 0068).
+ */
+const WITH_ADK_GEMINI = adapterResolver((r) => new AdkGeminiAdapter(r));
+/**
+ * Resolves a model id to the engine's own ModelAdapter (ADR 0048), from the
+ * same prefix table and transport rule as resolveModel, with no ADK
+ * LLMRegistry: the provider's adapter when its key (env, BYOK or endpoint)
+ * is present, the gateway's when it is absent and MODEL_GATEWAY is set.
+ * The adapter opens no span and charges nothing: its caller does (ADR 0053).
+ */
+export function resolveAdapter(modelId, options = {}) {
+    return WITH_ADK_GEMINI.resolveAdapter(modelId, options);
+}
+/**
+ * An agent's model and its `fallback_model:` on the contract path: a
+ * FallbackAdapter (ADR 0044) around resolveAdapter's two adapters, or the
+ * primary alone when there is no fallback. The caller's key stays with its
+ * own provider: unless `keyProvider` says otherwise it belongs to the
+ * primary's, so a fallback on another provider resolves from server env.
+ * Nothing calls this yet; the ADK path's pair stays
+ * FallbackLlm(shim(primary), shim(fallback)) (ADR 0053).
+ */
+export function resolveAdapterWithFallback(modelId, fallbackId, options = {}, fallbackOptions = {}) {
+    return WITH_ADK_GEMINI.resolveAdapterWithFallback(modelId, fallbackId, options, fallbackOptions);
 }

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

@@ -14,7 +14,8 @@
  * THE POLICY:
  *   - Bounded: MODEL_RETRY_MAX_ATTEMPTS total attempts (default 3, clamped
  *     1..10; 1 disables retries). Matches the vendor SDKs' 1 + 2 retries.
- *   - Retried: HTTP 408/409/425/429/500/502/503/504, and connection-level
+ *   - Retried: HTTP 408/409/425/429/500/502/503/504/529 (Anthropic's
+ *     "overloaded"), and connection-level
  *     failures that say nothing about the request (ECONNRESET, ETIMEDOUT,
  *     EPIPE, ECONNABORTED, EAI_AGAIN, undici socket/connect-timeout). Every
  *     other 4xx is the request's own fault and is never repeated.

package/dist/lib/models/retry.js

@@ -14,7 +14,8 @@
  * THE POLICY:
  *   - Bounded: MODEL_RETRY_MAX_ATTEMPTS total attempts (default 3, clamped
  *     1..10; 1 disables retries). Matches the vendor SDKs' 1 + 2 retries.
- *   - Retried: HTTP 408/409/425/429/500/502/503/504, and connection-level
+ *   - Retried: HTTP 408/409/425/429/500/502/503/504/529 (Anthropic's
+ *     "overloaded"), and connection-level
  *     failures that say nothing about the request (ECONNRESET, ETIMEDOUT,
  *     EPIPE, ECONNABORTED, EAI_AGAIN, undici socket/connect-timeout). Every
  *     other 4xx is the request's own fault and is never repeated.
@@ -51,7 +52,7 @@
  * setLlmSpanAttribute).
  */
 export const RETRYABLE_STATUSES = new Set([
-    408, 409, 425, 429, 500, 502, 503, 504,
+    408, 409, 425, 429, 500, 502, 503, 504, 529,
 ]);
 export const RETRYABLE_NETWORK_CODES = new Set([
     'ECONNRESET',