fix(sse): forward configured combo service tier

changelog.d/features/18553-combo-service-tier.md

@@ -0,0 +1 @@
+- **feat(sse):** A combo can pin an OpenAI tier with `config.service_tier` (or `serviceTier`). It reaches `openai`, `azure-openai` and `codex` targets on every attempt, replacing the client's tier there, and other targets get the request as the client sent it. API writes reject values outside `auto`, `default`, `flex`, `priority` and `scale`. ([#18553](https://github.com/cheaper-inference/OmniRoute/pull/18553)) — thanks @dankarization

open-sse/config/serviceTier.ts

@@ -0,0 +1,12 @@
+/** OpenAI `service_tier` values, shared by the request translators and combo config. */
+export const OPENAI_SERVICE_TIER_VALUES = ["auto", "default", "flex", "priority", "scale"] as const;
+
+export const OPENAI_SERVICE_TIERS: ReadonlySet<string> = new Set(OPENAI_SERVICE_TIER_VALUES);
+
+// Only targets known to accept a top-level service_tier get it; strict
+// OpenAI-compatible gateways reject unknown fields with a 400.
+export const SERVICE_TIER_PROVIDERS: ReadonlySet<string> = new Set([
+  "openai",
+  "azure-openai",
+  "codex",
+]);

open-sse/services/combo.ts

@@ -36,6 +36,7 @@ import { parseModel } from "./model.ts";
 import { rejectRetiredAutoComboCandidates } from "./modelLifecycle.ts";
 import { createComboContext } from "./combo/context.ts";
 import { phaseComboSetup } from "./combo/comboSetup.ts";
+import { withComboServiceTier } from "./combo/comboServiceTier.ts";
 
 import { projectAccountTier, type ProviderCandidate } from "./autoCombo/scoring.ts";
 
@@ -797,7 +798,7 @@ export async function handleComboChat(options: HandleComboChatOptions): Promise<
 async function handleComboChatInner({
   body,
   combo,
-  handleSingleModel,
+  handleSingleModel: dispatchSingleModel,
   isModelAvailable,
   log,
   settings,
@@ -817,6 +818,7 @@ async function handleComboChatInner({
   invocationId,
 }: HandleComboChatOptions): Promise<Response> {
   hiddenModelsByProvider ??= await getHiddenChatModels();
+  const handleSingleModel = withComboServiceTier(dispatchSingleModel, combo);
   const comboCtx = createComboContext({ body, combo, settings, relayOptions, log });
   const {
     strategy,

open-sse/services/combo/comboServiceTier.ts

@@ -0,0 +1,37 @@
+import { OPENAI_SERVICE_TIERS, SERVICE_TIER_PROVIDERS } from "../../config/serviceTier.ts";
+import { parseModel } from "../model.ts";
+import type { HandleSingleModel, SingleModelTarget } from "./types.ts";
+
+type ComboWithConfig = { config?: Record<string, unknown> | null } | null | undefined;
+
+/** The combo's configured tier (`service_tier` beats `serviceTier`), or null when absent or invalid. */
+export function resolveComboServiceTier(combo: ComboWithConfig): string | null {
+  const raw = combo?.config?.service_tier ?? combo?.config?.serviceTier;
+  if (typeof raw !== "string") return null;
+  const tier = raw.trim().toLowerCase();
+  return OPENAI_SERVICE_TIERS.has(tier) ? tier : null;
+}
+
+function targetProvider(modelStr: string, target?: SingleModelTarget): string | null {
+  const resolved = target && "provider" in target ? target.provider : null;
+  return resolved || parseModel(modelStr).provider;
+}
+
+/**
+ * Per-combo tier is a bucket policy: on a target that accepts `service_tier` it replaces the
+ * client's tier on every strategy and attempt. Any other target gets the body as the client
+ * sent it, so a mixed combo never sends a strict gateway a field it rejects. An API key's
+ * forced Codex tier still wins in the executor, and the tier beats a connection's default.
+ */
+export function withComboServiceTier(
+  handleSingleModel: HandleSingleModel,
+  combo: ComboWithConfig
+): HandleSingleModel {
+  const tier = resolveComboServiceTier(combo);
+  if (!tier) return handleSingleModel;
+  return (body, modelStr, target) => {
+    const provider = targetProvider(modelStr, target);
+    const accepted = provider !== null && SERVICE_TIER_PROVIDERS.has(provider);
+    return handleSingleModel(accepted ? { ...body, service_tier: tier } : body, modelStr, target);
+  };
+}

open-sse/services/combo/comboSetup.ts

@@ -105,6 +105,7 @@ export function phaseComboSetup(ctx: ComboContext): ComboSetup {
     "" // provider/model not yet known — resolved per-model in loop
   );
   ctx.body = agentBody;
+
   const clientRequestedStream = ctx.body?.stream === true;
 
   // Use config cascade before dispatch so all strategies, pinned context routes,

open-sse/translator/request/claude-to-openai.ts

@@ -1,3 +1,4 @@
+import { OPENAI_SERVICE_TIERS, SERVICE_TIER_PROVIDERS } from "../../config/serviceTier.ts";
 import { register } from "../registry.ts";
 import { FORMATS } from "../formats.ts";
 import { adjustMaxTokens } from "../helpers/maxTokensHelper.ts";
@@ -98,14 +99,10 @@ function nativeWebSearchTargetFormat(credentials: unknown): string | null {
 
 // OpenAI service_tier values. Anthropic's "standard_only" has no OpenAI twin beyond
 // "default"; "fast" is the alias the Codex billing/executor path already accepts.
-const OPENAI_SERVICE_TIERS = new Set(["auto", "default", "flex", "priority", "scale"]);
 const CLAUDE_TO_OPENAI_SERVICE_TIER: Record<string, string> = {
   standard_only: "default",
   fast: "priority",
 };
-// Only targets known to accept a top-level service_tier get it; strict
-// OpenAI-compatible gateways reject unknown fields with a 400.
-const SERVICE_TIER_PROVIDERS = new Set(["openai", "azure-openai", "codex"]);
 
 /** Client service_tier to keep across the Claude → OpenAI pivot, or undefined to drop it. */
 function resolveOpenAIServiceTier(tier: unknown, credentials: unknown): string | undefined {

src/shared/validation/schemas/combo.ts

@@ -13,6 +13,7 @@ import {
   isForbiddenCustomHeaderName,
 } from "@/shared/constants/upstreamHeaders";
 import { MAX_TIMER_TIMEOUT_MS } from "@/shared/utils/runtimeTimeouts";
+import { OPENAI_SERVICE_TIER_VALUES } from "@omniroute/open-sse/config/serviceTier.ts";
 
 // ──── Combo Schemas ────
 
@@ -167,6 +168,12 @@ export const responseValidationSchema = z
   })
   .strict();
 
+const comboServiceTierSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .pipe(z.enum(OPENAI_SERVICE_TIER_VALUES));
+
 export const comboRuntimeConfigSchema = z
   .object({
     responseValidation: responseValidationSchema.optional(),
@@ -303,6 +310,10 @@ export const comboRuntimeConfigSchema = z
       })
       .strict()
       .optional(),
+    // Per-combo OpenAI tier, forwarded only to targets that accept service_tier. Read from the
+    // combo's own config: comboDefaults and providerOverrides share this schema but do not apply it.
+    service_tier: comboServiceTierSchema.optional(),
+    serviceTier: comboServiceTierSchema.optional(),
     // Optional client-side sort hint for combo models.
     // Honored in the dashboard builder; reserved for future server-side use. Inert on execution.
     modelSort: z

tests/integration/combo-routing-e2e.test.ts

@@ -421,3 +421,83 @@ test("strategy updates take effect for later requests on the same combo name", a
   }
   assert.deepEqual(seenProviders, ["openai", "openai", "openai", "openai", "claude"]);
 });
+
+for (const tier of [undefined, "flex"]) {
+  test(`combo forwards ${tier ?? "default"} tier to every OpenAI upstream attempt`, async () => {
+    await seedConnection("openai", { apiKey: "sk-openai-tier-test" });
+    const comboName = tier ? "tier-flex" : "tier-default";
+    await combosDb.createCombo({
+      name: comboName,
+      strategy: "priority",
+      config: { maxRetries: 0, retryDelayMs: 0, ...(tier ? { service_tier: tier } : {}) },
+      models: ["openai/gpt-4o-mini", "openai/gpt-4o"],
+    });
+    const attempts: Array<Record<string, unknown>> = [];
+    globalThis.fetch = async (_url, init = {}) => {
+      const payload = JSON.parse(String(init.body)) as Record<string, unknown>;
+      attempts.push(payload);
+      if (attempts.length === 1) {
+        // A missing model is model-scoped; a provider 503 intentionally skips
+        // the same connection's remaining targets rather than retrying it.
+        return new Response(
+          JSON.stringify({ error: { code: "model_not_found", message: "model not found" } }),
+          {
+            status: 404,
+            headers: { "content-type": "application/json" },
+          }
+        );
+      }
+      return buildOpenAIResponse("Tier fallback answered");
+    };
+    const body = buildOpenAIChatBody(comboName);
+    const response = await handleChat(buildRequest({ body }));
+    const json = (await response.json()) as { choices: Array<{ message: { content: string } }> };
+    assert.equal(response.status, 200);
+    assert.equal(json.choices[0].message.content, "Tier fallback answered");
+    assert.deepEqual(
+      attempts.map((payload) => payload.model),
+      ["gpt-4o-mini", "gpt-4o"]
+    );
+    for (const payload of attempts) {
+      assert.equal(payload.service_tier, tier);
+      assert.equal(Object.hasOwn(payload, "service_tier"), tier !== undefined);
+      assert.equal(payload.stream, false);
+    }
+    assert.equal(Object.hasOwn(body, "service_tier"), false);
+  });
+}
+
+test("a mixed combo sends its tier to the OpenAI target and not to a strict gateway", async () => {
+  await seedConnection("groq", { apiKey: "gsk-groq-tier-test" });
+  await seedConnection("openai", { apiKey: "sk-openai-tier-test" });
+  await combosDb.createCombo({
+    name: "tier-mixed",
+    strategy: "priority",
+    config: { maxRetries: 0, retryDelayMs: 0, service_tier: "flex" },
+    models: ["groq/llama-3.3-70b-versatile", "openai/gpt-4o-mini"],
+  });
+  const attempts: Array<Record<string, unknown>> = [];
+  globalThis.fetch = async (_url, init = {}) => {
+    const payload = JSON.parse(String(init.body)) as Record<string, unknown>;
+    attempts.push(payload);
+    if (attempts.length === 1) {
+      return new Response(
+        JSON.stringify({ error: { code: "model_not_found", message: "model not found" } }),
+        { status: 404, headers: { "content-type": "application/json" } }
+      );
+    }
+    return buildOpenAIResponse("Tier mixed answered");
+  };
+
+  const response = await handleChat(buildRequest({ body: buildOpenAIChatBody("tier-mixed") }));
+
+  assert.equal(response.status, 200);
+  await response.body?.cancel();
+  assert.deepEqual(
+    attempts.map((payload) => [payload.model, payload.service_tier]),
+    [
+      ["llama-3.3-70b-versatile", undefined],
+      ["gpt-4o-mini", "flex"],
+    ]
+  );
+});

tests/unit/combo/combo-context.test.ts

@@ -8,14 +8,23 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { createComboContext } from "../../../open-sse/services/combo/context.ts";
 import { phaseComboSetup } from "../../../open-sse/services/combo/comboSetup.ts";
+import { withComboServiceTier } from "../../../open-sse/services/combo/comboServiceTier.ts";
+import { comboRuntimeConfigSchema } from "../../../src/shared/validation/schemas/combo.ts";
+import { resetDbInstance } from "../../../src/lib/db/core.ts";
+
+test.after(() => resetDbInstance());
 
 const log = { info() {}, warn() {}, error() {}, debug() {} };
 
 test("createComboContext carries inputs and the body BY REFERENCE", () => {
   const body = { model: "auto", messages: [], stream: true };
   const combo = { name: "c1", models: ["a", "b"] };
   const ctx = createComboContext({ body, combo, log });
-  assert.equal(ctx.body, body, "body must be the same reference (not copied) for byte-identical pinning");
+  assert.equal(
+    ctx.body,
+    body,
+    "body must be the same reference (not copied) for byte-identical pinning"
+  );
   assert.equal(ctx.combo, combo);
   assert.equal(ctx.settings, null);
   assert.equal(ctx.relayOptions, null);
@@ -63,3 +72,113 @@ test("phaseComboSetup normalizes an unknown strategy to a valid routing strategy
   assert.equal(typeof setup.strategy, "string");
   assert.ok(setup.strategy.length > 0);
 });
+
+function captureDispatch() {
+  const seen: Array<{ body: Record<string, unknown>; model: string; target: unknown }> = [];
+  const dispatch = async (body: Record<string, unknown>, model: string, target?: unknown) => {
+    seen.push({ body, model, target });
+    return new Response("ok");
+  };
+  return { seen, dispatch };
+}
+
+test("phaseComboSetup leaves the tier to the per-target dispatch", () => {
+  const body = { model: "bucket", messages: [] };
+  const ctx = createComboContext({
+    body,
+    combo: { name: "bucket", models: ["openai/gpt-4o"], config: { service_tier: "flex" } },
+    log,
+  });
+  phaseComboSetup(ctx);
+  assert.equal(Object.hasOwn(ctx.body, "service_tier"), false);
+});
+
+for (const stream of [false, true]) {
+  test(`combo tier: an unconfigured combo dispatches the same body (stream=${stream})`, async () => {
+    const { seen, dispatch } = captureDispatch();
+    const body = { model: "bucket", messages: [], stream };
+    const handle = withComboServiceTier(dispatch, { config: {} });
+    assert.equal(handle, dispatch);
+    await handle(body, "openai/gpt-4o");
+    assert.equal(seen[0].body, body);
+  });
+
+  for (const field of ["service_tier", "serviceTier"]) {
+    test(`combo tier: config.${field} reaches an accepting target (stream=${stream})`, async () => {
+      const { seen, dispatch } = captureDispatch();
+      const body = { model: "bucket", messages: [], stream };
+      const config = { [field]: "flex" };
+      const target = { modelAbortSignal: new AbortController().signal };
+      await withComboServiceTier(dispatch, { config })(body, "openai/gpt-4o", target);
+      assert.deepEqual(seen[0].body, { ...body, service_tier: "flex" });
+      assert.equal(seen[0].target, target);
+      assert.equal(Object.hasOwn(body, "service_tier"), false, "do not mutate caller body");
+      assert.deepEqual(config, { [field]: "flex" });
+    });
+  }
+}
+
+for (const model of ["openai/gpt-4o", "azure-openai/gpt-4o", "codex/gpt-5.5"]) {
+  test(`combo tier: ${model} accepts service_tier`, async () => {
+    const { seen, dispatch } = captureDispatch();
+    await withComboServiceTier(dispatch, { config: { service_tier: "priority" } })({}, model);
+    assert.equal(seen[0].body.service_tier, "priority");
+  });
+}
+
+for (const model of ["groq/llama-3", "deepseek/deepseek-chat", "gemini/gemini-flash", "nr/x"]) {
+  test(`combo tier: ${model} never receives the combo's service_tier`, async () => {
+    const { seen, dispatch } = captureDispatch();
+    const body = { model: "bucket", messages: [] };
+    await withComboServiceTier(dispatch, { config: { service_tier: "flex" } })(body, model);
+    assert.equal(seen[0].body, body);
+    assert.equal(Object.hasOwn(seen[0].body, "service_tier"), false);
+  });
+}
+
+test("combo tier: a refusing target keeps the tier the client sent", async () => {
+  const { seen, dispatch } = captureDispatch();
+  const body = { model: "bucket", messages: [], service_tier: "priority" };
+  await withComboServiceTier(dispatch, { config: { service_tier: "flex" } })(body, "groq/llama-3");
+  assert.equal(seen[0].body.service_tier, "priority");
+});
+
+test("combo tier: the resolved target provider beats the prefix in the model string", async () => {
+  const { seen, dispatch } = captureDispatch();
+  const target = { provider: "groq", modelAbortSignal: new AbortController().signal };
+  await withComboServiceTier(dispatch, { config: { service_tier: "flex" } })(
+    {},
+    "openai/gpt-4o",
+    target as never
+  );
+  assert.equal(Object.hasOwn(seen[0].body, "service_tier"), false);
+});
+
+test("combo tier: a valid snake-case tier wins over camel-case and the client", async () => {
+  const { seen, dispatch } = captureDispatch();
+  const combo = { config: { service_tier: " FLEX ", serviceTier: "default" } };
+  await withComboServiceTier(dispatch, combo)({ service_tier: "priority" }, "openai/gpt-4o");
+  assert.equal(seen[0].body.service_tier, "flex");
+});
+
+test("combo tier: invalid or absent values preserve the client request", async () => {
+  for (const tier of [undefined, null, "", "invalid", 7, {}, ["flex"]]) {
+    const { seen, dispatch } = captureDispatch();
+    const body = { model: "bucket", messages: [], service_tier: "priority" };
+    await withComboServiceTier(dispatch, { config: { service_tier: tier } })(body, "openai/gpt-4o");
+    assert.equal(seen[0].body, body);
+  }
+});
+
+test("comboRuntimeConfigSchema validates and normalizes both tier spellings", () => {
+  for (const field of ["service_tier", "serviceTier"]) {
+    for (const tier of ["auto", "default", "flex", "priority", "scale"]) {
+      assert.equal(comboRuntimeConfigSchema.parse({ [field]: tier })[field], tier);
+    }
+    assert.equal(comboRuntimeConfigSchema.parse({ [field]: " FLEX " })[field], "flex");
+    for (const tier of ["turbo", "", 7, null, ["flex"]]) {
+      assert.equal(comboRuntimeConfigSchema.safeParse({ [field]: tier }).success, false, `${tier}`);
+    }
+  }
+  assert.equal(comboRuntimeConfigSchema.safeParse({}).success, true);
+});