modelrig 0.0.1 → 0.1.0

package/dist/adapters/openai-compat.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Generic openai-compatible adapter — Phase 4 addendum A1
+ * (provider-coverage-plan §1: "the DeepSeek adapter is its
+ * parameterization"). One adapter covers every OpenAI-dialect host; what
+ * varies is INJECTED: base URL, auth key, model-id shaping, and — the
+ * doctrine part — the per-model capability profile READ FROM THE REGISTRY.
+ * Speaking the dialect proves nothing: strict schema enforcement, caching,
+ * grounding are all probe-established facts, never dialect assumptions.
+ *
+ * Host quirks referenced from LiteLLM's per-provider transformation modules
+ * (vendor/litellm-upstream/litellm/llms/{deepinfra,fireworks_ai}/):
+ * DeepInfra base URL https://api.deepinfra.com/v1/openai (standard Bearer,
+ * OpenAI params incl. response_format); Fireworks base URL
+ * https://api.fireworks.ai/inference/v1 with model ids on the wire as
+ * accounts/fireworks/models/<short>.
+ * Portions derived from LiteLLM (https://github.com/BerriAI/litellm),
+ * Copyright (c) 2023 Berri AI, MIT License — retained per
+ * litellm-vendoring-strategy.md.
+ */
+import type { CapabilityFlag, ProviderAdapter, ProviderId } from "../types/provider";
+import type { ClassifiedFailure, ShapingInput } from "./gemini";
+/** Fireworks serves models at accounts/fireworks/models/<short> — routes
+ * declare the short name; the wire gets the full path (LiteLLM
+ * fireworks_ai transformation, harvested). */
+export declare function shapeFireworksModelId(model: string): string;
+export interface OpenAICompatHost {
+    readonly baseUrl: string;
+    readonly shapeModelId?: (model: string) => string;
+}
+/** The researched Tier-2 hosts (provider-coverage-plan §2, architect pick
+ * 2026-08-02): DeepInfra (widest open catalog, lowest price) + Fireworks
+ * (SOC 2/HIPAA reliability counterweight). Same weights on both on purpose
+ * — host-level conformance/latency/price deltas become registry facts. */
+export declare const OPENAI_COMPAT_HOSTS: Readonly<Record<"deepinfra" | "fireworks", OpenAICompatHost>>;
+export declare function classifyCompatFailure(message: string, host: string): ClassifiedFailure;
+interface ChatMessage {
+    readonly role: "system" | "user";
+    readonly content: string;
+}
+export interface OpenAICompatShapedParams {
+    readonly model: string;
+    readonly max_tokens: number;
+    readonly messages: readonly ChatMessage[];
+    readonly stream: true;
+    readonly stream_options: {
+        readonly include_usage: true;
+    };
+    readonly response_format?: {
+        readonly type: "json_object";
+    } | {
+        readonly type: "json_schema";
+        readonly json_schema: {
+            readonly name: string;
+            readonly strict: true;
+            readonly schema: object;
+        };
+    };
+}
+/** Pure request shaping. The PROFILE decides the wire shape: strict
+ * json_schema only when the registry granted structured_native for this
+ * model; else json_object (ajv still arbitrates above). */
+export declare function buildOpenAICompatParams(model: string, req: ShapingInput, profileFlags: ReadonlySet<CapabilityFlag>): OpenAICompatShapedParams;
+export interface OpenAICompatAdapterConfig {
+    readonly providerId: ProviderId;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly shapeModelId?: (model: string) => string;
+    /** Registry-fed per-model capability flags — the ONLY capability source.
+     * The conservative dialect baseline is json_mode alone. */
+    readonly capabilityProfile: (model: string) => ReadonlySet<CapabilityFlag>;
+}
+export declare function createOpenAICompatAdapter(config: OpenAICompatAdapterConfig): ProviderAdapter;
+export {};
+//# sourceMappingURL=openai-compat.d.ts.map

package/dist/adapters/openai-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-compat.d.ts","sourceRoot":"","sources":["../../src/adapters/openai-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAIV,cAAc,EACd,eAAe,EACf,UAAU,EACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAIhE;;8CAE8C;AAC9C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACnD;AAED;;;0EAG0E;AAC1E,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,GAAG,WAAW,EAAE,gBAAgB,CAAC,CAG7F,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAiBtF;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;KAAE,CAAC;IAC1D,QAAQ,CAAC,eAAe,CAAC,EACrB;QAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;KAAE,GAChC;QACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;KACjG,CAAC;CACP;AAOD;;2DAE2D;AAC3D,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,EACjB,YAAY,EAAE,WAAW,CAAC,cAAc,CAAC,GACxC,wBAAwB,CA4B1B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD;+DAC2D;IAC3D,QAAQ,CAAC,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,CAAC,cAAc,CAAC,CAAC;CAC5E;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,eAAe,CAqH5F"}

package/dist/adapters/openai-compat.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Generic openai-compatible adapter — Phase 4 addendum A1
+ * (provider-coverage-plan §1: "the DeepSeek adapter is its
+ * parameterization"). One adapter covers every OpenAI-dialect host; what
+ * varies is INJECTED: base URL, auth key, model-id shaping, and — the
+ * doctrine part — the per-model capability profile READ FROM THE REGISTRY.
+ * Speaking the dialect proves nothing: strict schema enforcement, caching,
+ * grounding are all probe-established facts, never dialect assumptions.
+ *
+ * Host quirks referenced from LiteLLM's per-provider transformation modules
+ * (vendor/litellm-upstream/litellm/llms/{deepinfra,fireworks_ai}/):
+ * DeepInfra base URL https://api.deepinfra.com/v1/openai (standard Bearer,
+ * OpenAI params incl. response_format); Fireworks base URL
+ * https://api.fireworks.ai/inference/v1 with model ids on the wire as
+ * accounts/fireworks/models/<short>.
+ * Portions derived from LiteLLM (https://github.com/BerriAI/litellm),
+ * Copyright (c) 2023 Berri AI, MIT License — retained per
+ * litellm-vendoring-strategy.md.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENAI_COMPAT_HOSTS = void 0;
+exports.shapeFireworksModelId = shapeFireworksModelId;
+exports.classifyCompatFailure = classifyCompatFailure;
+exports.buildOpenAICompatParams = buildOpenAICompatParams;
+exports.createOpenAICompatAdapter = createOpenAICompatAdapter;
+const openai_1 = __importDefault(require("openai"));
+const DEFAULT_MAX_TOKENS = 32000;
+/** Fireworks serves models at accounts/fireworks/models/<short> — routes
+ * declare the short name; the wire gets the full path (LiteLLM
+ * fireworks_ai transformation, harvested). */
+function shapeFireworksModelId(model) {
+    return model.startsWith("accounts/") ? model : `accounts/fireworks/models/${model}`;
+}
+/** The researched Tier-2 hosts (provider-coverage-plan §2, architect pick
+ * 2026-08-02): DeepInfra (widest open catalog, lowest price) + Fireworks
+ * (SOC 2/HIPAA reliability counterweight). Same weights on both on purpose
+ * — host-level conformance/latency/price deltas become registry facts. */
+exports.OPENAI_COMPAT_HOSTS = {
+    deepinfra: { baseUrl: "https://api.deepinfra.com/v1/openai" },
+    fireworks: { baseUrl: "https://api.fireworks.ai/inference/v1", shapeModelId: shapeFireworksModelId },
+};
+function classifyCompatFailure(message, host) {
+    const msg = message.toLowerCase();
+    if (/\b429\b|rate limit|\brate\b/.test(msg))
+        return { cls: "capacity_shed" };
+    if (/\b50[023]\b|service unavailable|overloaded/.test(msg))
+        return { cls: "capacity_shed" };
+    if (/timeout|etimedout|abort/.test(msg))
+        return { cls: "timeout" };
+    if (/econnreset|econnrefused|enotfound|fetch failed|network/.test(msg))
+        return { cls: "network" };
+    if (/\b401\b|\b403\b|api key|unauthorized/.test(msg)) {
+        // F2: non-retryable — a dead key never burns backoff retries.
+        return { cls: "config_auth", fixHint: `check the ${host} API key configured for this rig` };
+    }
+    if (/not found|does not exist/.test(msg)) {
+        return {
+            cls: "network",
+            fixHint: "the candidate model was not found — fix the model id in the route's candidate list",
+        };
+    }
+    return { cls: "network" };
+}
+/** json_object mode 400s on several compat backends when the literal word
+ * "JSON" appears nowhere in the prompt (the DeepSeek-family quirk; coached
+ * prompts normally guarantee it — this is belt-and-suspenders). */
+const JSON_GUARD = "Respond with a single valid JSON object.";
+/** Pure request shaping. The PROFILE decides the wire shape: strict
+ * json_schema only when the registry granted structured_native for this
+ * model; else json_object (ajv still arbitrates above). */
+function buildOpenAICompatParams(model, req, profileFlags) {
+    const wantJson = req.outputSchema !== null;
+    const strict = wantJson && profileFlags.has("structured_native");
+    let systemPrompt = req.systemPrompt;
+    if (wantJson && !strict && !req.systemPrompt.includes("JSON") && !req.userPrompt.includes("JSON")) {
+        systemPrompt = systemPrompt === "" ? JSON_GUARD : `${systemPrompt}\n\n${JSON_GUARD}`;
+    }
+    const messages = [
+        ...(systemPrompt !== "" ? [{ role: "system", content: systemPrompt }] : []),
+        { role: "user", content: req.userPrompt },
+    ];
+    return {
+        model,
+        max_tokens: req.maxOutputTokens ?? DEFAULT_MAX_TOKENS,
+        messages,
+        stream: true,
+        stream_options: { include_usage: true },
+        ...(wantJson
+            ? strict
+                ? {
+                    response_format: {
+                        type: "json_schema",
+                        json_schema: { name: "output", strict: true, schema: req.outputSchema },
+                    },
+                }
+                : { response_format: { type: "json_object" } }
+            : {}),
+    };
+}
+function createOpenAICompatAdapter(config) {
+    const shapeModel = config.shapeModelId ?? ((m) => m);
+    return {
+        id: config.providerId,
+        supports(feature, model) {
+            return config.capabilityProfile(model).has(feature);
+        },
+        async call(req) {
+            const model = req.candidate.model;
+            const fail = (cls, message, fixHint, usage) => ({
+                ok: false,
+                failure: {
+                    class: cls,
+                    message,
+                    provider: config.providerId,
+                    model,
+                    ...(fixHint !== undefined ? { fixHint } : {}),
+                },
+                ...(usage !== undefined ? { usage } : {}),
+            });
+            try {
+                const client = new openai_1.default({
+                    apiKey: config.apiKey,
+                    baseURL: config.baseUrl,
+                    timeout: req.timeoutMs,
+                });
+                const params = buildOpenAICompatParams(shapeModel(model), req, config.capabilityProfile(model));
+                const dispatchedAt = Date.now();
+                const stream = await client.chat.completions.create(params);
+                let text = "";
+                let promptTokens = 0;
+                let completionTokens = 0;
+                let cachedTokens = 0;
+                let finishReason = null;
+                // TTFB (Phase 4 WS3): first streamed chunk = first body byte.
+                let ttfbMs;
+                for await (const chunk of stream) {
+                    if (ttfbMs === undefined)
+                        ttfbMs = Date.now() - dispatchedAt;
+                    const choice = chunk.choices[0];
+                    if (choice?.delta?.content)
+                        text += choice.delta.content;
+                    if (choice?.finish_reason)
+                        finishReason = choice.finish_reason;
+                    if (chunk.usage) {
+                        promptTokens = chunk.usage.prompt_tokens ?? 0;
+                        completionTokens = chunk.usage.completion_tokens ?? 0;
+                        cachedTokens = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+                    }
+                }
+                // Hosts have no service tiers in this dialect — standard, always.
+                const usage = {
+                    tokensIn: promptTokens,
+                    tokensOut: completionTokens,
+                    tokensCached: cachedTokens,
+                    servedTier: "standard",
+                    ...(ttfbMs !== undefined ? { ttfbMs } : {}),
+                };
+                if (text.trim().length === 0) {
+                    return fail("content_invalid", `empty response from ${config.providerId} (finish_reason=${finishReason ?? "none"})`, undefined, usage);
+                }
+                if (finishReason === "length" && req.outputSchema !== null) {
+                    return fail("content_invalid", `${config.providerId} JSON output truncated (finish_reason=length)`, "raise maxOutputTokens for this route", usage);
+                }
+                return { ok: true, text, usage };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const { cls, fixHint } = classifyCompatFailure(message, config.providerId);
+                return {
+                    ok: false,
+                    failure: {
+                        class: cls,
+                        message,
+                        provider: config.providerId,
+                        model,
+                        cause: error,
+                        ...(fixHint !== undefined ? { fixHint } : {}),
+                    },
+                };
+            }
+        },
+    };
+}

package/dist/adapters/openai.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OpenAI ProviderAdapter — plan step 5.
+ * Transformation logic ported from apps/api/src/services/openai-provider.ts:
+ * response_format json_schema strict, service tiers (flex allowlist + served
+ * tier from the stream), prompt-cache key + retention passthrough, streaming
+ * with usage, structured-output refusal detection, suspicious-short guard.
+ * NOT ported: logging, pricing tables, env reads, the analyst-persona system
+ * prompt (route templates own prompt content).
+ *
+ * Portions may be derived from LiteLLM (https://github.com/BerriAI/litellm),
+ * Copyright (c) 2023 Berri AI, MIT License — retain this notice if LiteLLM's
+ * openai transformation logic is consulted during the port.
+ */
+import type { CapabilityFlag, ProviderAdapter } from "../types/provider";
+import type { ClassifiedFailure, ShapingInput } from "./gemini";
+export interface OpenAIAdapterConfig {
+    readonly apiKey: string;
+}
+export declare function isModelFlexEligible(modelName: string): boolean;
+export declare function openaiSupports(feature: CapabilityFlag, model: string): boolean;
+export declare function classifyOpenAIFailure(message: string): ClassifiedFailure;
+interface ChatMessage {
+    readonly role: "system" | "user";
+    readonly content: string;
+}
+export interface OpenAIShapedParams {
+    readonly model: string;
+    readonly max_completion_tokens: number;
+    readonly messages: readonly ChatMessage[];
+    readonly stream: true;
+    readonly stream_options: {
+        readonly include_usage: true;
+    };
+    readonly service_tier?: "flex" | "priority";
+    readonly prompt_cache_key?: string;
+    readonly prompt_cache_retention?: "24h";
+    readonly response_format?: {
+        readonly type: "json_schema";
+        readonly json_schema: {
+            readonly name: string;
+            readonly schema: object;
+            readonly strict: true;
+        };
+    };
+}
+export declare function buildOpenAIParams(model: string, req: ShapingInput): OpenAIShapedParams;
+export declare function createOpenAIAdapter(config: OpenAIAdapterConfig): ProviderAdapter;
+export {};
+//# sourceMappingURL=openai.d.ts.map

package/dist/adapters/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAIV,cAAc,EACd,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAMD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAc9E;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAiBxE;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;KAAE,CAAC;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,KAAK,CAAC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE;QACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;SAAE,CAAC;KACjG,CAAC;CACH;AAID,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,kBAAkB,CAoCtF;AAcD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CAiJhF"}

package/dist/adapters/openai.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * OpenAI ProviderAdapter — plan step 5.
+ * Transformation logic ported from apps/api/src/services/openai-provider.ts:
+ * response_format json_schema strict, service tiers (flex allowlist + served
+ * tier from the stream), prompt-cache key + retention passthrough, streaming
+ * with usage, structured-output refusal detection, suspicious-short guard.
+ * NOT ported: logging, pricing tables, env reads, the analyst-persona system
+ * prompt (route templates own prompt content).
+ *
+ * Portions may be derived from LiteLLM (https://github.com/BerriAI/litellm),
+ * Copyright (c) 2023 Berri AI, MIT License — retain this notice if LiteLLM's
+ * openai transformation logic is consulted during the port.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isModelFlexEligible = isModelFlexEligible;
+exports.openaiSupports = openaiSupports;
+exports.classifyOpenAIFailure = classifyOpenAIFailure;
+exports.buildOpenAIParams = buildOpenAIParams;
+exports.createOpenAIAdapter = createOpenAIAdapter;
+const openai_1 = __importDefault(require("openai"));
+/** OpenAI's documented flex-eligible allowlist as of 2026-05 (ported).
+ * Mini and nano variants are silently downgraded to default tier. */
+const FLEX_ELIGIBLE_PREFIXES = ["gpt-5.4", "gpt-5.2", "gpt-5.1", "gpt-5", "gpt-4.1"];
+function isModelFlexEligible(modelName) {
+    if (!modelName)
+        return false;
+    if (modelName.includes("-mini") || modelName.includes("-nano"))
+        return false;
+    return FLEX_ELIGIBLE_PREFIXES.some((prefix) => modelName.startsWith(prefix));
+}
+function openaiSupports(feature, model) {
+    switch (feature) {
+        case "structured_native":
+        case "json_mode":
+        case "prompt_cache_key":
+        case "prefix_cache_implicit":
+            return true;
+        case "tier_flex":
+            return isModelFlexEligible(model);
+        case "grounded_native":
+        case "context_cache_explicit":
+        case "trace_visible": // reasoning tokens are billed but never exposed
+            return false;
+    }
+}
+function classifyOpenAIFailure(message) {
+    const msg = message.toLowerCase();
+    if (/\b429\b|rate limit|\brate\b/.test(msg))
+        return { cls: "capacity_shed" };
+    if (/\b50[023]\b|service unavailable|overloaded/.test(msg))
+        return { cls: "capacity_shed" };
+    if (/timeout|etimedout|abort/.test(msg))
+        return { cls: "timeout" };
+    if (/econnreset|econnrefused|enotfound|fetch failed|network/.test(msg))
+        return { cls: "network" };
+    if (/\b401\b|api key/.test(msg)) {
+        // F2: non-retryable — a dead key never burns backoff retries.
+        return { cls: "config_auth", fixHint: "check the OpenAI API key configured for this rig" };
+    }
+    if (/does not exist|not found|\bmodel\b.*invalid/.test(msg)) {
+        return {
+            cls: "network",
+            fixHint: "the candidate model was not found — fix the model id in the route's candidate list",
+        };
+    }
+    return { cls: "network" };
+}
+const DEFAULT_MAX_COMPLETION_TOKENS = 32000;
+function buildOpenAIParams(model, req) {
+    const messages = [
+        ...(req.systemPrompt !== "" ? [{ role: "system", content: req.systemPrompt }] : []),
+        { role: "user", content: req.userPrompt },
+    ];
+    return {
+        model,
+        max_completion_tokens: req.maxOutputTokens ?? DEFAULT_MAX_COMPLETION_TOKENS,
+        messages,
+        stream: true,
+        stream_options: { include_usage: true },
+        ...(req.requestedTier === "flex"
+            ? { service_tier: "flex" }
+            : req.requestedTier === "priority"
+                ? { service_tier: "priority" }
+                : {}),
+        ...(req.cache?.key !== undefined && req.cache.key !== ""
+            ? {
+                prompt_cache_key: req.cache.key,
+                // Extended retention only when the directive asks for a day or more.
+                ...((req.cache.ttlSeconds ?? 0) >= 86400 ? { prompt_cache_retention: "24h" } : {}),
+            }
+            : {}),
+        ...(req.outputSchema !== null
+            ? {
+                response_format: {
+                    type: "json_schema",
+                    json_schema: {
+                        name: "modelrig_route_output",
+                        schema: req.outputSchema,
+                        strict: true,
+                    },
+                },
+            }
+            : {}),
+    };
+}
+/** Ported suspicious-short heuristic: finish_reason 'stop' + <200 visible
+ * completion tokens on a 50K+ token prompt = flex degradation / stream drop. */
+const SUSPICIOUSLY_SHORT_VISIBLE = 200;
+const LONG_FORM_PROMPT_THRESHOLD = 50000;
+function mapServedTier(raw, requested) {
+    if (raw === "flex")
+        return "flex";
+    if (raw === "priority")
+        return "priority";
+    if (raw === "default" || raw === "auto")
+        return "standard";
+    return requested === "flex" || requested === "priority" ? requested : "standard";
+}
+function createOpenAIAdapter(config) {
+    return {
+        id: "openai",
+        supports: openaiSupports,
+        async call(req) {
+            const model = req.candidate.model;
+            // F1: post-stream failures still billed tokens — attach usage.
+            const fail = (cls, message, fixHint, usage) => ({
+                ok: false,
+                failure: {
+                    class: cls,
+                    message,
+                    provider: "openai",
+                    model,
+                    ...(fixHint !== undefined ? { fixHint } : {}),
+                },
+                ...(usage !== undefined ? { usage } : {}),
+            });
+            try {
+                const client = new openai_1.default({ apiKey: config.apiKey, timeout: req.timeoutMs });
+                const params = buildOpenAIParams(model, req);
+                const dispatchedAt = Date.now();
+                const stream = await client.chat.completions.create(params);
+                // TTFB (Phase 4 WS3): first streamed chunk = first body byte.
+                let ttfbMs;
+                let text = "";
+                let refusalText = "";
+                let promptTokens = 0;
+                let completionTokens = 0;
+                let cachedTokens = 0;
+                let reasoningTokens = 0;
+                let responseTier = null;
+                let finishReason = null;
+                for await (const chunk of stream) {
+                    if (ttfbMs === undefined)
+                        ttfbMs = Date.now() - dispatchedAt;
+                    if (responseTier === null && chunk.service_tier !== undefined) {
+                        responseTier = chunk.service_tier;
+                    }
+                    const choice = chunk.choices[0];
+                    if (choice?.delta?.content)
+                        text += choice.delta.content;
+                    if (typeof choice?.delta?.refusal === "string" && choice.delta.refusal.length > 0) {
+                        refusalText += choice.delta.refusal;
+                    }
+                    if (choice?.finish_reason)
+                        finishReason = choice.finish_reason;
+                    if (chunk.usage) {
+                        promptTokens = chunk.usage.prompt_tokens ?? 0;
+                        completionTokens = chunk.usage.completion_tokens ?? 0;
+                        cachedTokens = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+                        reasoningTokens = chunk.usage.completion_tokens_details?.reasoning_tokens ?? 0;
+                    }
+                }
+                const usage = {
+                    tokensIn: promptTokens,
+                    tokensOut: completionTokens,
+                    tokensCached: cachedTokens,
+                    servedTier: mapServedTier(responseTier, req.requestedTier),
+                    ...(ttfbMs !== undefined ? { ttfbMs } : {}),
+                };
+                // Any streamed refusal is terminal for this call, even alongside
+                // partial content — OpenAI's structured-output semantics (ported).
+                if (refusalText.length > 0) {
+                    return fail("refusal", `OpenAI refused structured output: ${refusalText.slice(0, 200)}`, undefined, usage);
+                }
+                const visibleCompletionTokens = Math.max(0, completionTokens - reasoningTokens);
+                if (finishReason === "stop" &&
+                    completionTokens > 0 &&
+                    visibleCompletionTokens < SUSPICIOUSLY_SHORT_VISIBLE &&
+                    promptTokens >= LONG_FORM_PROMPT_THRESHOLD) {
+                    return fail("content_invalid", `suspiciously short OpenAI response: ${visibleCompletionTokens} visible completion tokens ` +
+                        `for ${promptTokens} prompt tokens (likely flex-tier degradation or stream drop)`, undefined, usage);
+                }
+                if (text.trim().length === 0) {
+                    return fail("content_invalid", `empty response from OpenAI (finish_reason=${finishReason ?? "none"})`, undefined, usage);
+                }
+                if (finishReason === "length" && req.outputSchema !== null) {
+                    return fail("content_invalid", "OpenAI structured output truncated (finish_reason=length)", "raise maxOutputTokens for this route", usage);
+                }
+                return { ok: true, text, usage };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const { cls, fixHint } = classifyOpenAIFailure(message);
+                return {
+                    ok: false,
+                    failure: {
+                        class: cls,
+                        message,
+                        provider: "openai",
+                        model,
+                        cause: error,
+                        ...(fixHint !== undefined ? { fixHint } : {}),
+                    },
+                };
+            }
+        },
+    };
+}

package/dist/bakeoff/engine.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bake-off engine — Phase 3 spec WS5 (closed core). Replays the last N
+ * captures through each named variant, aggregates per-variant metrics
+ * (stats.ts), and assembles the BakeoffArtifact with the proposal verdict.
+ *
+ * Proposal gate (builder decision, flagged): the incumbent is the "default"
+ * variant when compared, else the FIRST listed variant. A challenger
+ * proposes when (a) its conformance CI lower bound ≥ the incumbent's CI
+ * lower bound, and (b) its effective $/1K-conformant is strictly lower.
+ * Value gates beyond mechanical conformance arrive with Phase 4 judges —
+ * the artifact records value_accuracy where the hook supplies it.
+ */
+import type { CaptureStore } from "../telemetry/capture";
+import type { RunDeps } from "../run/run";
+import type { ArmSamples, KeepOutputsMode } from "./samples";
+import type { BakeoffArtifact, VariantMetrics } from "./types";
+/** Sink for retained review samples (addendum A3). The engine assembles the
+ * arms to persist (incumbent + winner, or all); the caller — createRig with
+ * the service-role config — does the truncation + PostgREST insert. Keeps
+ * payloads out of the engine and out of the (anon-readable) BakeoffArtifact. */
+export type BakeoffSamplesSink = (input: {
+    readonly bakeoffId: string;
+    readonly route: string;
+    readonly arms: readonly ArmSamples[];
+}) => Promise<void>;
+export interface BakeoffRequest {
+    readonly route: string;
+    /** Variant names to compare; "default" = the route's base config. */
+    readonly variants: readonly string[];
+    readonly replayLastN: number;
+    /** Hard cap PER VARIANT replay pass (spec: replay is envelope-guarded). */
+    readonly envelopeUsdPerVariant: number;
+    /** Addendum A3: retain outputs for a value review. "winner" = incumbent +
+     * winning challenger; "all" = every arm. Undefined = keep nothing (the
+     * default pure-metrics path). Requires a samplesSink to persist. */
+    readonly keepOutputs?: KeepOutputsMode;
+}
+export declare function runBakeoff(deps: RunDeps, captures: CaptureStore, req: BakeoffRequest, samplesSink?: BakeoffSamplesSink): Promise<BakeoffArtifact>;
+/** Winner among gate-passing challengers; null when nobody beats the
+ * incumbent. Exported for direct unit testing. */
+export declare function computeProposal(requested: readonly string[], metrics: readonly VariantMetrics[]): BakeoffArtifact["proposal"];
+export interface BakeoffMirrorConfig {
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    readonly sourceId: string;
+    readonly fetchFn?: typeof fetch;
+}
+/** Upsert the artifact into the `bakeoffs` mirror table (console read path).
+ * Same PostgREST transport pattern as the telemetry exporter; captures have
+ * no cloud surface — ONLY aggregate metrics travel. */
+export declare function mirrorBakeoff(artifact: BakeoffArtifact, config: BakeoffMirrorConfig): Promise<void>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/bakeoff/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/bakeoff/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAO1C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;gFAGgF;AAChF,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;CACtC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAgBpB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;wEAEoE;IACpE,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC;CACxC;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,YAAY,EACtB,GAAG,EAAE,cAAc,EACnB,WAAW,CAAC,EAAE,kBAAkB,GAC/B,OAAO,CAAC,eAAe,CAAC,CA2E1B;AAED;kDACkD;AAClD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,EAAE,SAAS,cAAc,EAAE,GACjC,eAAe,CAAC,UAAU,CAAC,CA4B7B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED;;uDAEuD;AACvD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Bf"}