melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/models/registry.js

@@ -23,45 +23,119 @@
  * resolution (LRU), so late registration can be masked by stale cache hits.
  */
 import { Gemini, LLMRegistry } from '@google/adk';
-import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_OLLAMA_MODEL, } from "../config.js";
-import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
-import { ClaudeLlm, registerClaudeLlm } from "./claudeLlm.js";
-import { GptLlm, registerGptLlm } from "./gptLlm.js";
-import { GrokLlm, registerGrokLlm } from "./grokLlm.js";
-import { OllamaLlm, registerOllamaLlm } from "./ollamaLlm.js";
-import { PROVIDERS, providerForModel, providerKeyPresent, } from "./providerMap.js";
+import { endpointFromEnv, endpointProblems, mergeEndpoint, platformModel, providerReady } from './endpoints.js';
+import { currentTurnSignal } from '../runtime/turnControl.js';
+import { errorStatus, retryUntilFirstYield } from './retry.js';
+import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_OLLAMA_MODEL, } from '../config.js';
+import { traceLlmGeneration, setLlmSpanAttribute, } from '../observability/tracer.js';
+import { ClaudeLlm, registerClaudeLlm } from './claudeLlm.js';
+import { GptLlm, registerGptLlm } from './gptLlm.js';
+import { GrokLlm, registerGrokLlm } from './grokLlm.js';
+import { OllamaLlm, registerOllamaLlm } from './ollamaLlm.js';
+import { GatewayLlm, registerGatewayLlm } from './gatewayLlm.js';
+import { gatewayConfig, gatewayProblem, gatewayUsable, planTransport, } 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.
+// 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;
-    async *generateContentAsync(llmRequest, stream) {
-        yield* traceLlmGeneration({ provider: 'gemini', model: this.model, llmRequest }, this.tagAndGenerate(llmRequest, stream));
+    /**
+     * 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. */
-    async *tagAndGenerate(llmRequest, stream) {
+     *  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);
-        yield* super.generateContentAsync(llmRequest, stream);
+        // 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;
+        }
     }
 }
 /** Availability report without side effects (used by demos and key gates). */
 export function providerStatuses() {
+    const gw = gatewayUsable() ? gatewayConfig() : null;
     return Object.keys(PROVIDERS).map((provider) => {
-        const available = providerKeyPresent(provider);
+        const label = PROVIDERS[provider].label;
+        if (providerReady(provider)) {
+            return { provider, label, available: true, transport: 'direct' };
+        }
+        // A cloud platform that is not fully configured is not covered by the
+        // gateway: the deployment chose that platform on purpose.
+        let cloudProblem;
+        try {
+            const e = endpointFromEnv(provider);
+            if (e.platform !== 'direct')
+                cloudProblem = endpointProblems(provider, e).join('; ');
+        }
+        catch (err) {
+            cloudProblem = err instanceof Error ? err.message : String(err);
+        }
+        if (cloudProblem)
+            return { provider, label, available: false, reason: cloudProblem };
+        if (gw && provider !== 'ollama') {
+            return {
+                provider,
+                label,
+                available: true,
+                transport: 'gateway',
+                gateway: gw.gateway.id,
+            };
+        }
         return {
             provider,
-            label: PROVIDERS[provider].label,
-            available,
-            ...(available
-                ? {}
-                : { reason: `${PROVIDERS[provider].keyEnv} not set` }),
+            label,
+            available: false,
+            reason: `${PROVIDERS[provider].keyEnv} not set`,
         };
     });
 }
@@ -72,29 +146,57 @@ const REGISTRARS = {
     xai: registerGrokLlm,
     ollama: registerOllamaLlm,
 };
+/**
+ * The direct adapter's OWN supportedModels per provider. A gateway stand-in
+ * must register under these exact regex instances so it REPLACES the
+ * direct entry (the LLMRegistry dict is keyed by regex object) instead of
+ * sitting behind it unmatched. Gemini's are ADK's built-in patterns, which
+ * are registered at import time — replacing them is how TracedGemini works
+ * too.
+ */
+const PATTERNS = {
+    gemini: Gemini.supportedModels,
+    anthropic: ClaudeLlm.supportedModels,
+    openai: GptLlm.supportedModels,
+    xai: GrokLlm.supportedModels,
+};
 let providersRegistered = false;
 /**
  * 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 function registerAvailableProviders(log) {
     const statuses = providerStatuses();
     if (!providersRegistered) {
         providersRegistered = true;
         for (const status of statuses) {
-            if (status.available || status.provider === 'gemini') {
+            if (status.transport === 'gateway' && status.provider !== 'ollama') {
+                registerGatewayLlm(PATTERNS[status.provider]);
+            }
+            else if (status.available || status.provider === 'gemini') {
                 REGISTRARS[status.provider]();
             }
         }
     }
     if (log) {
+        const problem = gatewayProblem();
+        if (problem)
+            log(`⚠ ${problem} — gateway ignored`);
         for (const s of statuses) {
-            log(s.available
-                ? `✓ ${s.label} — active`
-                : `⚠ ${s.label} disabled (${s.reason}) — ${modelHint(s.provider)} models unavailable`);
+            if (!s.available) {
+                log(`⚠ ${s.label} disabled (${s.reason}) — ${modelHint(s.provider)} models unavailable`);
+            }
+            else if (s.transport === 'gateway') {
+                log(`◇ ${s.label} — via gateway:${s.gateway} (${modelHint(s.provider)} served without native search)`);
+            }
+            else {
+                log(`✓ ${s.label} — active`);
+            }
         }
     }
     return statuses;
@@ -137,17 +239,26 @@ export function resolveModel(model, options = {}) {
     const apiKey = providerForModel(model ?? DEFAULT_MODEL_FOR[normalizeProvider(options.defaultProvider)]) === normalizeProvider(options.defaultProvider)
         ? options.apiKey
         : undefined;
-    switch (providerForModel(resolved)) {
+    // 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 });
+            return new ClaudeLlm({ model: resolved, apiKey, endpoint });
         case 'openai':
-            return new GptLlm({ model: resolved, apiKey });
+            return new GptLlm({ model: resolved, apiKey, endpoint });
         case 'xai':
             return new GrokLlm({ model: resolved, apiKey });
         case 'gemini':
-            return new TracedGemini({ model: resolved, apiKey });
+            return new TracedGemini({ model: resolved, apiKey, endpoint });
     }
 }
 function normalizeProvider(provider) {

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

@@ -0,0 +1,146 @@
+/**
+ * lib/models/retry.ts — the one retry policy for transient provider failures.
+ *
+ * WHY this file exists:
+ *   Before it, resilience was an accident of which SDK an adapter used.
+ *   Claude and GPT/Grok inherited their vendor SDKs' two retries; Gemini —
+ *   the default provider — got none (`@google/genai` does a single fetch
+ *   unless retryOptions is set, and ADK's Gemini never sets it); the
+ *   chat-completions path (Ollama, gateways) was one bare `fetch`. A 503
+ *   "high demand" from Google failed the whole turn. One policy here, used by
+ *   every adapter that does not get it from its SDK, keeps the behaviour the
+ *   same whichever provider an agent's YAML names.
+ *
+ * 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
+ *     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.
+ *   - NOT retried: ECONNREFUSED / ENOTFOUND. Against Ollama on localhost a
+ *     refused connection means the server is not running, and the adapter's
+ *     own message already says how to start it; retrying only delays that
+ *     diagnosis by seconds, and no daemon restarts inside our backoff window.
+ *     Against a remote gateway it means a wrong host or port — configuration,
+ *     not load. Response-wait timeouts (undici headers/body timeout) are not
+ *     retried either: a request that already ran for minutes is better
+ *     reported than repeated at the same cost.
+ *   - Backoff: full jitter, uniform in [0, min(8 s, 500 ms * 2^(n-1))], so
+ *     callers that failed together do not come back together.
+ *   - Retry-After (seconds, HTTP date, or OpenAI's retry-after-ms; Google's
+ *     RetryInfo `retryDelay` in an error body) replaces the jittered delay
+ *     when present. Above 60 s the call is NOT retried at all: per-minute
+ *     quota windows reset inside a minute, so a longer wait signals a daily
+ *     or hard quota that waiting will not fix — surface it now.
+ *   - Cancellation: the turn's AbortSignal (lib/runtime/turnControl.ts) is
+ *     checked before every retry and wakes the backoff sleep, so a canceled
+ *     or timed-out turn never sleeps past its abort and never re-sends.
+ *
+ * THE STREAMING RULE:
+ *   A retry is only ever made BEFORE the caller has received any response
+ *   bytes. A failure after the first partial has been yielded would, if
+ *   retried, replay text the user has already seen (and that ADK may have
+ *   already turned into events). `fetchWithRetry` retries the request and
+ *   hands back the Response before its body is read; `retryUntilFirstYield`
+ *   retries a generator only while it has yielded nothing.
+ *
+ * Retries run inside one `llm.request` span and one step-budget charge: a
+ * retried call is still one logical model call. The count lands on the span
+ * as `llm.retries` (via the onRetry hook each adapter wires to
+ * setLlmSpanAttribute).
+ */
+export declare const RETRYABLE_STATUSES: ReadonlySet<number>;
+export declare const RETRYABLE_NETWORK_CODES: ReadonlySet<string>;
+export interface RetryPolicy {
+    /** Total attempts including the first; 1 = no retries. */
+    maxAttempts: number;
+    /** Backoff ceiling for attempt 1; doubles per attempt. */
+    baseDelayMs: number;
+    /** Backoff ceiling never grows past this. */
+    maxDelayMs: number;
+    /** A Retry-After longer than this is not waited out — the call fails. */
+    maxRetryAfterMs: number;
+}
+export declare const DEFAULT_RETRY_POLICY: Readonly<RetryPolicy>;
+export declare const MAX_ATTEMPTS_ENV = "MODEL_RETRY_MAX_ATTEMPTS";
+/**
+ * Process-wide overrides for the policy (tests shrink the delays; an
+ * embedding app can tune them). Returns a function restoring the previous
+ * overrides. The env var still sets maxAttempts unless overridden here.
+ */
+export declare function setRetryPolicyOverrides(next: Partial<RetryPolicy>): () => void;
+/** The effective policy: defaults ← MODEL_RETRY_MAX_ATTEMPTS ← overrides. */
+export declare function retryPolicy(env?: NodeJS.ProcessEnv): RetryPolicy;
+/** What one failed attempt says about trying again. */
+export interface RetryDecision {
+    retryable: boolean;
+    /** HTTP status, when the failure had one. */
+    status?: number;
+    /** Server-requested wait, when it sent one. */
+    retryAfterMs?: number;
+}
+export declare function isRetryableStatus(status: number): boolean;
+/** The system/undici error code anywhere on an error's cause chain. */
+export declare function networkErrorCode(err: unknown): string | undefined;
+/** A numeric HTTP status carried on an error (genai ApiError, SDK errors). */
+export declare function errorStatus(err: unknown): number | undefined;
+/** Classifies a non-2xx HTTP response. */
+export declare function classifyResponse(res: Pick<Response, 'status' | 'headers'>): RetryDecision;
+/** Classifies a thrown error (an HTTP error from an SDK, or a network one). */
+export declare function classifyError(err: unknown): RetryDecision;
+/**
+ * Parses a Retry-After value: delta-seconds ("30", "1.5") or an HTTP date.
+ * Returns milliseconds (never negative), or undefined when unparseable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/** Retry-After from response headers, preferring OpenAI's retry-after-ms. */
+export declare function retryAfterFromHeaders(headers: Pick<Headers, 'get'> | undefined, now?: number): number | undefined;
+/**
+ * Google RPC's RetryInfo, which genai only exposes inside the error message
+ * (its ApiError drops the response headers): `"retryDelay": "37s"`.
+ */
+export declare function googleRetryDelayMs(message: string): number | undefined;
+/** Full-jitter backoff for the given (1-based) failed attempt. */
+export declare function backoffDelayMs(attempt: number, policy?: RetryPolicy, random?: () => number): number;
+/**
+ * How long to wait before attempt `attempt + 1`, or undefined to stop:
+ * not retryable, attempts exhausted, the turn aborted, or the server asked
+ * for a wait beyond the cap.
+ */
+export declare function nextRetryDelay(attempt: number, decision: RetryDecision, policy?: RetryPolicy, signal?: AbortSignal, random?: () => number): number | undefined;
+/**
+ * Sleeps `ms`, waking early if `signal` aborts. Resolves true when the full
+ * wait elapsed, false when it was cut short by an abort.
+ */
+export declare function sleepUnlessAborted(ms: number, signal?: AbortSignal): Promise<boolean>;
+export interface RetryOptions {
+    signal?: AbortSignal;
+    policy?: RetryPolicy;
+    /** Called before each wait; `retries` counts retries made so far + 1. */
+    onRetry?: (info: {
+        retries: number;
+        delayMs: number;
+        decision: RetryDecision;
+    }) => void;
+    /** Injectable for tests. */
+    random?: () => number;
+}
+/**
+ * `fetch` with the policy applied to the REQUEST. Returns the first 2xx, or
+ * the last non-2xx Response once retrying stops (body unread, so the caller
+ * builds its own error from it). Throws the last error when the final
+ * attempt failed at the network level. The body of a successful response is
+ * never touched here — reading (and streaming) it is the caller's, and a
+ * failure there is not retried (see THE STREAMING RULE above).
+ */
+export declare function fetchWithRetry(url: string, init: RequestInit, opts?: RetryOptions): Promise<{
+    response: Response;
+    retries: number;
+}>;
+/**
+ * Re-runs a generator factory while it fails BEFORE its first yield. Once
+ * anything has been yielded a failure is rethrown untouched: retrying then
+ * would duplicate output the caller has already passed on.
+ */
+export declare function retryUntilFirstYield<T>(start: (attempt: number) => AsyncGenerator<T, void>, opts?: RetryOptions): AsyncGenerator<T, void>;