vidspotai-shared 1.0.82 → 1.0.83

package/lib/services/agent/llmCallerRegistry.js

@@ -7,7 +7,8 @@ exports.getAnthropicCaller = getAnthropicCaller;
 const llmCaller_1 = require("./llmCaller");
 /**
  * Singleton LlmCaller accessor. Host wires a concrete impl at boot
- * (e.g. GatewayLlmCaller); agent code reads via getLlmCaller().
+ * (the native ProviderRoutingLlmCaller via createNativeLlmCaller); agent code
+ * reads via getLlmCaller().
  *
  * Throwing UnconfiguredLlmCaller is the default so tests fail loud
  * if the host forgets to wire.
@@ -21,14 +22,13 @@ function getLlmCaller() {
 }
 /**
  * Optional Anthropic-direct caller. Wired only on hosts that have
- * ANTHROPIC_API_KEY set and need Anthropic-specific features (server-side
- * web_search, prompt caching, extended thinking). The Planner reads this
- * only when `useWebResearch` is requested — otherwise the default gateway
- * caller is used so provider portability is preserved.
+ * ANTHROPIC_API_KEY set and need Anthropic server-side web_search for the
+ * planner's research grounding. The Planner reads this only when
+ * `useWebResearch` is requested — otherwise it goes through the normal
+ * dispatcher (getLlmCaller()), which already routes Anthropic models natively.
  *
  * Null when unconfigured rather than throwing — caller code checks and
- * gracefully falls back to the gateway path. See AnthropicLlmCaller docstring
- * for deferred features (Tavily custom tools, fallback chain, streaming).
+ * gracefully falls back to the non-web-research planner path.
  */
 let anthropicInstance = null;
 function setAnthropicCaller(caller) {

package/lib/services/agent/llmCallerRouting.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { ChatRequest, ChatResponse, LlmCaller, StructuredRequest, StructuredResponse, StructuredWithToolsRequest } from "./llmCaller";
+/**
+ * Provider-dispatching LlmCaller — the native replacement for GatewayLlmCaller
+ * as the wired singleton (LLM_NATIVE_MIGRATION_PLAN Phase 5).
+ *
+ * It owns the two responsibilities the single gateway endpoint used to give us
+ * for free, now that each provider has its own SDK caller:
+ *   1. Dispatch by `req.model.provider` → the matching native caller.
+ *   2. Cross-provider `fallbackModel` (F2): when the primary exhausts retries on
+ *      a TRANSIENT error, attempt the fallback once (which may be a different
+ *      provider). Deterministic errors (schema/auth/4xx) do NOT trigger fallback
+ *      — identical semantics to the gateway.
+ *
+ * The native callers each handle ONE provider and do transport retry only; the
+ * dispatcher never re-implements backoff.
+ *
+ * Streaming: delegates to the chosen caller's `structuredStream` when present.
+ * All three native callers (Anthropic / OpenAI / Gemini) now implement native
+ * incremental streaming, so the dispatcher streams token-by-token on every
+ * provider. The single-chunk fallback below remains only as a safety net for
+ * any future caller that omits `structuredStream` — the LlmCaller contract
+ * explicitly allows a single full-payload emission.
+ */
+export interface ProviderCallers {
+    anthropic?: LlmCaller;
+    openai?: LlmCaller;
+    google?: LlmCaller;
+}
+export declare class ProviderRoutingLlmCaller implements LlmCaller {
+    private readonly callers;
+    constructor(callers: ProviderCallers);
+    private pick;
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    structured<T extends z.ZodTypeAny>(req: StructuredRequest<T>): Promise<StructuredResponse<T>>;
+    /**
+     * Forward to the chosen caller's native streaming when available; otherwise
+     * emit the full validated payload as a single chunk. Streaming does NOT apply
+     * cross-provider fallback mid-stream (matches the gateway): once bytes flow, a
+     * drop propagates and the planner's own retry loop (which awaits `result`)
+     * handles it.
+     */
+    structuredStream<T extends z.ZodTypeAny>(req: StructuredRequest<T>): {
+        tokens: AsyncIterable<string>;
+        result: Promise<StructuredResponse<T>>;
+    };
+    /**
+     * Anthropic (and any future non-streaming caller) path: run the blocking
+     * `structured` call, then surface its JSON as one token chunk. Failures reject
+     * the result promise and return cleanly from the generator rather than
+     * throwing — so the caller's token loop completes and its `await result`
+     * retry path fires (same contract as the streaming callers).
+     */
+    private singleChunkStream;
+    /**
+     * Anthropic-only server-tool path (web_search). Routes to the anthropic caller
+     * if it implements `structuredWithTools`; otherwise throws, since no other
+     * provider exposes Anthropic's server tools. Preserves the planner's
+     * useWebResearch behavior after the gateway is gone.
+     */
+    structuredWithTools<T extends z.ZodTypeAny>(req: StructuredWithToolsRequest<T>): Promise<StructuredResponse<T>>;
+}
+//# sourceMappingURL=llmCallerRouting.d.ts.map

package/lib/services/agent/llmCallerRouting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmCallerRouting.d.ts","sourceRoot":"","sources":["../../../src/services/agent/llmCallerRouting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,qBAAa,wBAAyB,YAAW,SAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,eAAe;IAErD,OAAO,CAAC,IAAI;IAYN,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAoB7C,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACrC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAsBjC;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACrC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACxB;QACD,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAC9B,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;KACxC;IASD;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAgCzB;;;;;OAKG;IACG,mBAAmB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAC9C,GAAG,EAAE,0BAA0B,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;CAUlC"}

package/lib/services/agent/llmCallerRouting.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderRoutingLlmCaller = void 0;
+const llmModelRegistry_1 = require("./llmModelRegistry");
+const llmRetry_1 = require("./llmRetry");
+class ProviderRoutingLlmCaller {
+    constructor(callers) {
+        this.callers = callers;
+    }
+    pick(model) {
+        const provider = (0, llmModelRegistry_1.providerFor)(model);
+        const caller = this.callers[provider];
+        if (!caller) {
+            throw new Error(`ProviderRoutingLlmCaller: no caller wired for provider="${provider}" ` +
+                `(model=${model.modelId}). Wire it in the host bootstrap.`);
+        }
+        return caller;
+    }
+    async chat(req) {
+        const attempted = [];
+        const run = (model) => {
+            attempted.push(model);
+            // Strip fallbackModel: the dispatcher owns fallback, the native caller
+            // should not attempt its own (it can't reach other providers anyway).
+            return this.pick(model).chat({ ...req, model, fallbackModel: undefined });
+        };
+        try {
+            const out = await run(req.model);
+            return { ...out, attemptedModels: [...attempted], usedFallback: false };
+        }
+        catch (err) {
+            if (req.fallbackModel && (0, llmRetry_1.isTransientLlmError)(err)) {
+                const out = await run(req.fallbackModel);
+                return { ...out, attemptedModels: [...attempted], usedFallback: true };
+            }
+            throw err;
+        }
+    }
+    async structured(req) {
+        const attempted = [];
+        const run = (model) => {
+            attempted.push(model);
+            return this.pick(model).structured({
+                ...req,
+                model,
+                fallbackModel: undefined,
+            });
+        };
+        try {
+            const out = await run(req.model);
+            return { ...out, attemptedModels: [...attempted], usedFallback: false };
+        }
+        catch (err) {
+            if (req.fallbackModel && (0, llmRetry_1.isTransientLlmError)(err)) {
+                const out = await run(req.fallbackModel);
+                return { ...out, attemptedModels: [...attempted], usedFallback: true };
+            }
+            throw err;
+        }
+    }
+    /**
+     * Forward to the chosen caller's native streaming when available; otherwise
+     * emit the full validated payload as a single chunk. Streaming does NOT apply
+     * cross-provider fallback mid-stream (matches the gateway): once bytes flow, a
+     * drop propagates and the planner's own retry loop (which awaits `result`)
+     * handles it.
+     */
+    structuredStream(req) {
+        const caller = this.pick(req.model);
+        const streamReq = { ...req, fallbackModel: undefined };
+        if (typeof caller.structuredStream === "function") {
+            return caller.structuredStream(streamReq);
+        }
+        return this.singleChunkStream(streamReq, caller);
+    }
+    /**
+     * Anthropic (and any future non-streaming caller) path: run the blocking
+     * `structured` call, then surface its JSON as one token chunk. Failures reject
+     * the result promise and return cleanly from the generator rather than
+     * throwing — so the caller's token loop completes and its `await result`
+     * retry path fires (same contract as the streaming callers).
+     */
+    singleChunkStream(req, caller) {
+        let resolveResult;
+        let rejectResult;
+        const result = new Promise((resolve, reject) => {
+            resolveResult = resolve;
+            rejectResult = reject;
+        });
+        const tokens = {
+            async *[Symbol.asyncIterator]() {
+                try {
+                    const res = await caller.structured(req);
+                    yield JSON.stringify(res.data);
+                    resolveResult({
+                        ...res,
+                        attemptedModels: res.attemptedModels ?? [req.model],
+                        usedFallback: false,
+                    });
+                }
+                catch (e) {
+                    rejectResult(e);
+                    return;
+                }
+            },
+        };
+        return { tokens, result };
+    }
+    /**
+     * Anthropic-only server-tool path (web_search). Routes to the anthropic caller
+     * if it implements `structuredWithTools`; otherwise throws, since no other
+     * provider exposes Anthropic's server tools. Preserves the planner's
+     * useWebResearch behavior after the gateway is gone.
+     */
+    async structuredWithTools(req) {
+        const caller = this.pick(req.model);
+        if (typeof caller.structuredWithTools !== "function") {
+            throw new Error(`ProviderRoutingLlmCaller: provider for model=${req.model.modelId} ` +
+                `does not support server-side tools (structuredWithTools).`);
+        }
+        return caller.structuredWithTools(req);
+    }
+}
+exports.ProviderRoutingLlmCaller = ProviderRoutingLlmCaller;

package/lib/services/agent/llmModelRegistry.d.ts

@@ -0,0 +1,59 @@
+import { ModelChoice } from "./modelRouter";
+/**
+ * Per-model capability registry for the native LLM callers.
+ *
+ * The gateway flattened every model to one OpenAI-compatible shape, so callers
+ * never had to know what a model could do. Native callers DO — prompt caching is
+ * Anthropic-only, `responseSchema` is Gemini's structured-output knob, etc. This
+ * registry is the single place that answers "what can model X do, and what native
+ * API id does it map to?" so callers branch on capability, not hardcoded strings.
+ *
+ * Pure + dependency-free (no SDKs, no env) so it stays unit-testable and cheap to
+ * import. Add a row when a new model joins `DEFAULT_MODEL_ROUTING` (modelRouter.ts).
+ */
+/** Providers we ship native callers for. */
+export type LlmProvider = "anthropic" | "openai" | "google";
+/** Native model ids we know are valid for their provider's SDK. */
+export interface ModelCapabilities {
+    provider: LlmProvider;
+    /**
+     * The id passed to the provider SDK. Defaults to the logical `modelId` when a
+     * model isn't in the table (most ids are pass-through today); listed
+     * explicitly so a future rename has one place to fix.
+     */
+    nativeModelId: string;
+    /** Accepts image input. */
+    vision: boolean;
+    /** Supports Anthropic ephemeral prompt caching (`cache_control`). */
+    promptCaching: boolean;
+    /**
+     * Native strict structured-output: OpenAI `json_schema` strict / Gemini
+     * `responseSchema` / Anthropic tool-forcing. All three native callers can
+     * always emit structured output one way or another, so this is informational
+     * (true for every row today) — kept for symmetry / future opt-outs.
+     */
+    structuredOutput: boolean;
+    /** Anthropic extended-thinking support. */
+    extendedThinking: boolean;
+}
+/**
+ * Capability rows keyed by the LOGICAL model id used in `DEFAULT_MODEL_ROUTING`.
+ * Native ids are pass-through today (proven in AnthropicLlmCaller / the Gemini
+ * vision services), so `nativeModelId` mirrors the key unless a provider needs a
+ * different wire id.
+ */
+export declare const MODEL_CAPABILITIES: Record<string, ModelCapabilities>;
+/**
+ * Normalize a `ModelChoice.provider` string to a known `LlmProvider`. Throws on
+ * a provider we don't ship a native caller for (e.g. the legacy `deepseek`
+ * executor fallback) — loud failure beats silently 404ing against the wrong SDK.
+ * See LLM_NATIVE_MIGRATION_PLAN decision #1.
+ */
+export declare function normalizeProvider(provider: string): LlmProvider;
+/** Capabilities for a model choice — registry row if known, else provider defaults. */
+export declare function capabilitiesFor(model: ModelChoice): ModelCapabilities;
+/** The native SDK model id to send for a given choice. */
+export declare function nativeModelId(model: ModelChoice): string;
+/** Which native caller a choice routes to. */
+export declare function providerFor(model: ModelChoice): LlmProvider;
+//# sourceMappingURL=llmModelRegistry.d.ts.map

package/lib/services/agent/llmModelRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmModelRegistry.d.ts","sourceRoot":"","sources":["../../../src/services/agent/llmModelRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;GAWG;AAEH,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,CAAC;IACtB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,2CAA2C;IAC3C,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAwGhE,CAAC;AAeF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAgB/D;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CAOrE;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAExD;AAED,8CAA8C;AAC9C,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAE3D"}

package/lib/services/agent/llmModelRegistry.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_CAPABILITIES = void 0;
+exports.normalizeProvider = normalizeProvider;
+exports.capabilitiesFor = capabilitiesFor;
+exports.nativeModelId = nativeModelId;
+exports.providerFor = providerFor;
+/**
+ * Capability rows keyed by the LOGICAL model id used in `DEFAULT_MODEL_ROUTING`.
+ * Native ids are pass-through today (proven in AnthropicLlmCaller / the Gemini
+ * vision services), so `nativeModelId` mirrors the key unless a provider needs a
+ * different wire id.
+ */
+exports.MODEL_CAPABILITIES = {
+    // ── Anthropic ──────────────────────────────────────────────────────────
+    "claude-haiku-4-5": {
+        provider: "anthropic",
+        nativeModelId: "claude-haiku-4-5",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: true,
+    },
+    "claude-sonnet-4-6": {
+        provider: "anthropic",
+        nativeModelId: "claude-sonnet-4-6",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: true,
+    },
+    // Legacy Opus tier — kept for compatibility; prefer claude-opus-4-8.
+    "claude-opus-4-7": {
+        provider: "anthropic",
+        nativeModelId: "claude-opus-4-7",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: true,
+    },
+    // Current top Opus tier (released 2026-05-28). The default high-capability
+    // choice; routed as premiumPlanner.
+    "claude-opus-4-8": {
+        provider: "anthropic",
+        nativeModelId: "claude-opus-4-8",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: true,
+    },
+    // ── OpenAI ─────────────────────────────────────────────────────────────
+    "gpt-5": {
+        provider: "openai",
+        nativeModelId: "gpt-5",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: false,
+    },
+    // Legacy fast tier — superseded by gpt-5.4-mini.
+    "gpt-5-mini": {
+        provider: "openai",
+        nativeModelId: "gpt-5-mini",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: false,
+    },
+    // Current OpenAI fast/cheap tier — supersedes gpt-5-mini. Cross-provider
+    // fallback for the prompt enhancer's primary (gemini-3.5-flash).
+    "gpt-5.4-mini": {
+        provider: "openai",
+        nativeModelId: "gpt-5.4-mini",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: false,
+    },
+    // ── Google ─────────────────────────────────────────────────────────────
+    // Current frontier Flash (stable). The prompt enhancer's default primary —
+    // frontier-Flash quality + vision at low cost.
+    "gemini-3.5-flash": {
+        provider: "google",
+        nativeModelId: "gemini-3.5-flash",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: false,
+    },
+    // Latest Pro tier. NOTE: no stable dateless id yet — the callable id is the
+    // `-preview` snapshot, so the logical id maps to it here. Cross-provider
+    // fallback for the enhancer's premium model.
+    "gemini-3.1-pro": {
+        provider: "google",
+        nativeModelId: "gemini-3.1-pro-preview",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: false,
+    },
+    // Older Gemini tiers — cheapest, kept for cost-sensitive / high-volume paths.
+    "gemini-2.5-flash": {
+        provider: "google",
+        nativeModelId: "gemini-2.5-flash",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: false,
+    },
+    "gemini-2.5-pro": {
+        provider: "google",
+        nativeModelId: "gemini-2.5-pro",
+        vision: true,
+        promptCaching: true,
+        structuredOutput: true,
+        extendedThinking: false,
+    },
+};
+/** Default capabilities when a model id isn't in the table — derive from provider. */
+function defaultsFor(model) {
+    const provider = normalizeProvider(model.provider);
+    return {
+        provider,
+        nativeModelId: model.modelId,
+        vision: model.vision ?? false,
+        promptCaching: provider === "anthropic",
+        structuredOutput: true,
+        extendedThinking: provider === "anthropic",
+    };
+}
+/**
+ * Normalize a `ModelChoice.provider` string to a known `LlmProvider`. Throws on
+ * a provider we don't ship a native caller for (e.g. the legacy `deepseek`
+ * executor fallback) — loud failure beats silently 404ing against the wrong SDK.
+ * See LLM_NATIVE_MIGRATION_PLAN decision #1.
+ */
+function normalizeProvider(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "anthropic";
+        case "openai":
+            return "openai";
+        case "google":
+        case "gemini":
+            return "google";
+        default:
+            throw new Error(`llmModelRegistry: no native caller for provider="${provider}". ` +
+                `Supported: anthropic, openai, google. Repoint routing/fallback off it ` +
+                `(see LLM_NATIVE_MIGRATION_PLAN decision #1).`);
+    }
+}
+/** Capabilities for a model choice — registry row if known, else provider defaults. */
+function capabilitiesFor(model) {
+    const row = exports.MODEL_CAPABILITIES[model.modelId];
+    if (row) {
+        // Honor an explicit vision flag from routing even if the row omits it.
+        return model.vision !== undefined ? { ...row, vision: model.vision } : row;
+    }
+    return defaultsFor(model);
+}
+/** The native SDK model id to send for a given choice. */
+function nativeModelId(model) {
+    return capabilitiesFor(model).nativeModelId;
+}
+/** Which native caller a choice routes to. */
+function providerFor(model) {
+    return capabilitiesFor(model).provider;
+}

package/lib/services/agent/llmRetry.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared transient-retry primitives for the native LLM callers.
+ *
+ * Extracted (Phase 1 of LLM_NATIVE_MIGRATION_PLAN) from the duplicated transient
+ * logic that lived in the per-caller implementations. All three native callers
+ * (OpenAI / Anthropic / Gemini) and the provider-dispatching caller share this so
+ * transient classification + backoff behave identically across providers — the
+ * single gateway endpoint used to give us this uniformity for free.
+ *
+ * Contract:
+ *   - `withRetry(fn)` retries `fn` up to `maxRetries` times on transient errors
+ *     with exponential backoff (base, base*4, base*16, …). The FINAL failure of a
+ *     transient error is re-thrown as a `TransientLlmError` so the dispatcher's
+ *     cross-provider `fallbackModel` path can catch it explicitly. Non-transient
+ *     errors (4xx other than 408/425/429, schema-validation, malformed JSON)
+ *     propagate immediately as their original error.
+ */
+/**
+ * Marks an error worth retrying / falling back on. The provider-dispatching caller
+ * catches this specifically to attempt `fallbackModel`; deterministic errors
+ * (bad schema, non-JSON, auth) are NOT wrapped and short-circuit the retry loop.
+ */
+export declare class TransientLlmError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function isTransientLlmError(err: unknown): err is TransientLlmError;
+/** HTTP statuses we treat as transient (worth a retry / fallback). */
+export declare const TRANSIENT_HTTP_STATUSES: Set<number>;
+/**
+ * Classify an arbitrary thrown value as transient. Covers:
+ *   - SDK errors carrying a numeric `status` in TRANSIENT_HTTP_STATUSES
+ *   - Node/undici network codes (ECONNRESET, ETIMEDOUT, UND_ERR_*, …)
+ *   - AbortError from our own per-request timeout (treated as transient so a
+ *     single slow call gets a retry / fallback instead of sinking the stage)
+ *   - SDK connection-error class names + common network phrases in the message
+ */
+export declare function isTransientError(err: unknown): boolean;
+export interface RetryOptions {
+    /** Max attempts on transient errors. Default 3. */
+    maxRetries?: number;
+    /** Base backoff in ms (exponential: base, base*4, base*16). Default 250. */
+    retryBaseMs?: number;
+    /**
+     * Optional sleep override (tests inject a no-op so retries don't wall-clock).
+     * Receives the planned delay in ms.
+     */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/**
+ * Run `fn` with transient-error retry + exponential backoff. On the terminal
+ * attempt of a transient failure, re-throws as `TransientLlmError`. Errors
+ * already classified transient by `isTransientError` but not yet wrapped are
+ * wrapped on the final attempt; pre-wrapped `TransientLlmError`s pass through.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+//# sourceMappingURL=llmRetry.d.ts.map

package/lib/services/agent/llmRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmRetry.d.ts","sourceRoot":"","sources":["../../../src/services/agent/llmRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAGxC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBADxB,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAE1E;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,aAElC,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CA+BtD;AAED,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAKD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,CAAC,CAAC,CA6BZ"}

package/lib/services/agent/llmRetry.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Shared transient-retry primitives for the native LLM callers.
+ *
+ * Extracted (Phase 1 of LLM_NATIVE_MIGRATION_PLAN) from the duplicated transient
+ * logic that lived in the per-caller implementations. All three native callers
+ * (OpenAI / Anthropic / Gemini) and the provider-dispatching caller share this so
+ * transient classification + backoff behave identically across providers — the
+ * single gateway endpoint used to give us this uniformity for free.
+ *
+ * Contract:
+ *   - `withRetry(fn)` retries `fn` up to `maxRetries` times on transient errors
+ *     with exponential backoff (base, base*4, base*16, …). The FINAL failure of a
+ *     transient error is re-thrown as a `TransientLlmError` so the dispatcher's
+ *     cross-provider `fallbackModel` path can catch it explicitly. Non-transient
+ *     errors (4xx other than 408/425/429, schema-validation, malformed JSON)
+ *     propagate immediately as their original error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRANSIENT_HTTP_STATUSES = exports.TransientLlmError = void 0;
+exports.isTransientLlmError = isTransientLlmError;
+exports.isTransientError = isTransientError;
+exports.withRetry = withRetry;
+/**
+ * Marks an error worth retrying / falling back on. The provider-dispatching caller
+ * catches this specifically to attempt `fallbackModel`; deterministic errors
+ * (bad schema, non-JSON, auth) are NOT wrapped and short-circuit the retry loop.
+ */
+class TransientLlmError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "TransientLlmError";
+    }
+}
+exports.TransientLlmError = TransientLlmError;
+function isTransientLlmError(err) {
+    return err instanceof Error && err.name === "TransientLlmError";
+}
+/** HTTP statuses we treat as transient (worth a retry / fallback). */
+exports.TRANSIENT_HTTP_STATUSES = new Set([
+    408, 425, 429, 500, 502, 503, 504,
+]);
+/**
+ * Classify an arbitrary thrown value as transient. Covers:
+ *   - SDK errors carrying a numeric `status` in TRANSIENT_HTTP_STATUSES
+ *   - Node/undici network codes (ECONNRESET, ETIMEDOUT, UND_ERR_*, …)
+ *   - AbortError from our own per-request timeout (treated as transient so a
+ *     single slow call gets a retry / fallback instead of sinking the stage)
+ *   - SDK connection-error class names + common network phrases in the message
+ */
+function isTransientError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (typeof e.status === "number" && exports.TRANSIENT_HTTP_STATUSES.has(e.status)) {
+        return true;
+    }
+    const code = e.code ?? e.cause?.code;
+    if (code && /^(ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|EPIPE|UND_ERR_.*)$/.test(code)) {
+        return true;
+    }
+    if (e.name === "AbortError" ||
+        e.name === "APIConnectionError" ||
+        e.name === "APIConnectionTimeoutError") {
+        return true;
+    }
+    const msg = String(e.message ?? "");
+    return /fetch failed|socket hang up|other side closed|network|timeout|operation was aborted|ECONNRESET|ETIMEDOUT/i.test(msg);
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Run `fn` with transient-error retry + exponential backoff. On the terminal
+ * attempt of a transient failure, re-throws as `TransientLlmError`. Errors
+ * already classified transient by `isTransientError` but not yet wrapped are
+ * wrapped on the final attempt; pre-wrapped `TransientLlmError`s pass through.
+ */
+async function withRetry(fn, opts = {}) {
+    const maxRetries = opts.maxRetries ?? 3;
+    const retryBaseMs = opts.retryBaseMs ?? 250;
+    const sleep = opts.sleepImpl ?? defaultSleep;
+    let lastErr;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            const transient = isTransientLlmError(err) || isTransientError(err);
+            if (!transient || attempt === maxRetries - 1) {
+                if (transient) {
+                    throw isTransientLlmError(err)
+                        ? err
+                        : new TransientLlmError(`transient LLM error after ${attempt + 1} attempts: ${String(err?.message ?? err)}`, err);
+                }
+                throw err;
+            }
+            await sleep(retryBaseMs * Math.pow(4, attempt));
+        }
+    }
+    throw lastErr;
+}

package/lib/services/agent/modelRouter.d.ts

@@ -8,15 +8,15 @@
  *   - critic     : vision QA across scenes, rubric-following
  *   - reference  : ingest a TikTok/Reel URL, extract structure
  *
- * The actual LLM call is delegated to an injected LlmCaller (wired to
- * Vercel AI Gateway / OpenRouter at the host layer) — this keeps the
+ * The actual LLM call is delegated to an injected LlmCaller (the native
+ * ProviderRoutingLlmCaller wired at the host layer) — this keeps the
  * agent code provider-agnostic and easy to A/B test against the eval set.
  */
 export type AgentRole = "router" | "planner" | "executor" | "critic" | "reference";
 export interface ModelChoice {
     /** Logical model id, e.g. "claude-sonnet-4.6", "claude-haiku-4.5", "gpt-5". */
     modelId: string;
-    /** Provider key for the LLM gateway, e.g. "anthropic", "openai", "google". */
+    /** Provider key for the LLM dispatcher, e.g. "anthropic", "openai", "google". */
     provider: string;
     /** Vision input supported. */
     vision?: boolean;

package/lib/services/agent/modelRouter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modelRouter.d.ts","sourceRoot":"","sources":["../../../src/services/agent/modelRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACnD,gFAAgF;IAChF,cAAc,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,eAAO,MAAM,qBAAqB,EAAE,kBAgCnC,CAAC;AAEF,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,GAAE,kBAA0C;IAE/E,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAOnE,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS;CAGtD"}
+{"version":3,"file":"modelRouter.d.ts","sourceRoot":"","sources":["../../../src/services/agent/modelRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACnD,gFAAgF;IAChF,cAAc,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,eAAO,MAAM,qBAAqB,EAAE,kBA8CnC,CAAC;AAEF,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,GAAE,kBAA0C;IAE/E,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAOnE,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS;CAGtD"}