fix(byok): honor compat.openRouterRouting for BYOK custom providers

packages/local-runtime-v2/src/service/model-system/catalog/provider-presets/provider-presets.service.test.ts

@@ -241,6 +241,49 @@ describe('models.dev Provider Presets', () => {
     expect(presets.map((preset) => preset.providerId)).toEqual(['compatible']);
   });
 
+  it('maps OpenRouter onto Chat Completions without admitting other OpenRouter SDK providers', async () => {
+    const presets = await parsePresetsForTest({
+      openrouter: {
+        name: 'OpenRouter',
+        npm: '@openrouter/ai-sdk-provider',
+        api: 'https://openrouter.ai/api/v1',
+        models: {
+          'xiaomi/mimo-v2.6-pro': {
+            name: 'MiMo-V2.6-Pro',
+            tool_call: true,
+            reasoning: true,
+          },
+          'text-only': { name: 'Text only', tool_call: false },
+        },
+      },
+      standardcompute: {
+        name: 'Standard Compute',
+        npm: '@openrouter/ai-sdk-provider',
+        api: 'https://api.stdcmpt.com/v1',
+        models: { model: { name: 'Model', tool_call: true } },
+      },
+    });
+
+    expect(
+      presets.map(({ providerId, baseUrl, apiFormat, models }) => ({
+        providerId,
+        baseUrl,
+        apiFormat,
+        modelIds: models.map((model) => model.modelId),
+      })),
+    ).toEqual([
+      {
+        providerId: 'openrouter',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        apiFormat: 'openai-completions',
+        modelIds: ['xiaomi/mimo-v2.6-pro'],
+      },
+    ]);
+    expect(providerCompletionUrl('openai-completions', presets[0]!.baseUrl)).toBe(
+      'https://openrouter.ai/api/v1/chat/completions',
+    );
+  });
+
   it('maps the three supported transports and normalizes their request bases', async () => {
     const messagesProviderId = 'anthropic';
     const presets = await parsePresetsForTest({

packages/local-runtime-v2/src/service/model-system/catalog/provider-presets/provider-presets.service.ts

@@ -164,6 +164,12 @@ function resolveTransport(
       providerId === 'anthropic' && provider.api === undefined
         ? MESSAGES_API_BASE_URL
         : stringValue(provider.api);
+  } else if (providerId === 'openrouter') {
+    // models.dev publishes OpenRouter as @openrouter/ai-sdk-provider. Its HTTP
+    // API is OpenAI-compatible Chat Completions, which this runtime already speaks.
+    // Match the provider id, not the npm package: other catalogs reuse that package.
+    apiFormat = 'openai-completions';
+    baseUrl = stringValue(provider.api);
   } else {
     return undefined;
   }

packages/local-runtime-v2/src/service/model-system/contracts.ts

@@ -1,4 +1,4 @@
-import type { Api } from '@earendil-works/pi-ai';
+import type { Api, OpenRouterRouting, VercelGatewayRouting } from '@earendil-works/pi-ai';
 import type { StreamFn } from '@earendil-works/pi-agent-core';
 import type { LLMModelConfig } from '@mavis/agent-core/pi-turn-runner';
 import type {
@@ -60,6 +60,30 @@ export interface LocalModelCompatOverrides {
     | 'string-thinking'
     | 'ant-ling';
   cacheControlFormat?: 'anthropic';
+  /**
+   * OpenRouter provider routing preferences, sent as the request `provider`
+   * field.
+   *
+   * The pi openai-completions transport attaches this whenever it is present,
+   * for any endpoint on that transport — it does not check the base URL, unlike
+   * the Vercel gateway routing beside it. Set it only on models served by
+   * OpenRouter: other OpenAI-compatible gateways receive the extra `provider`
+   * field in the request body.
+   * @see https://openrouter.ai/docs/guides/routing/provider-selection
+   */
+  openRouterRouting?: OpenRouterRouting;
+  /**
+   * Vercel AI Gateway provider routing preferences, sent as
+   * `providerOptions.gateway` on the request.
+   *
+   * Only `only` and `order` are declared, and the pi transport reads only those
+   * two. The transport's own endpoint check is a substring test on the base URL
+   * (`includes("ai-gateway.vercel.sh")`), which a lookalike host would pass, so
+   * the BYOK reader additionally gates this on an exact hostname — the field is
+   * only produced for a real Vercel AI Gateway endpoint.
+   * @see https://vercel.com/docs/ai-gateway/models-and-providers#provider-routing
+   */
+  vercelGatewayRouting?: VercelGatewayRouting;
 }
 
 export interface LocalModelConfig extends Omit<
@@ -217,8 +241,7 @@ export interface LocalModelResolverOptions {
     loginEpoch?: string,
   ) => void | Promise<void>;
   readonly routingContextGetter?: () =>
-    | import('@mavis/agent-tools/desktop').ManagedBackendRoutingContext
-    | undefined;
+    import('@mavis/agent-tools/desktop').ManagedBackendRoutingContext | undefined;
   readonly providerAuthGetter?: (
     provider: string,
   ) => Promise<string | undefined> | string | undefined;
@@ -365,8 +388,7 @@ export interface DiscoveredModel {
 }
 
 export type ModelDiscoveryResult =
-  | { ok: true; models: DiscoveredModel[] }
-  | { ok: false; errorCode: string; errorMessage: string };
+  { ok: true; models: DiscoveredModel[] } | { ok: false; errorCode: string; errorMessage: string };
 
 export interface ModelDiscoveryClientLike {
   discover(target: ModelDiscoveryTarget): Promise<ModelDiscoveryResult>;

packages/local-runtime-v2/src/service/model-system/resolution/local-model-resolver.test.ts

@@ -1505,20 +1505,12 @@ describe('LocalModelResolver custom provider compat overrides', () => {
     'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
     'https://example-workspace.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
   ])('honors an explicit developer-role override on %s', async (baseURL) => {
-    expect(
-      await systemPromptRoleFor(
-        { supportsDeveloperRole: true },
-        baseURL,
-      ),
-    ).toBe('developer');
+    expect(await systemPromptRoleFor({ supportsDeveloperRole: true }, baseURL)).toBe('developer');
   });
 
   it('honors an explicit developer-role override on a Kimi Coding endpoint', async () => {
     expect(
-      await systemPromptRoleFor(
-        { supportsDeveloperRole: true },
-        'https://api.kimi.com/coding/v1',
-      ),
+      await systemPromptRoleFor({ supportsDeveloperRole: true }, 'https://api.kimi.com/coding/v1'),
     ).toBe('developer');
   });
 });
@@ -1539,10 +1531,7 @@ describe('LocalModelResolver custom provider session affinity', () => {
     );
   };
 
-  const requestFor = async (
-    compat: LocalModelConfig['compat'],
-    cacheRetention?: 'none',
-  ) => {
+  const requestFor = async (compat: LocalModelConfig['compat'], cacheRetention?: 'none') => {
     const modelConfig: LocalModelConfig = compat ? { compat } : {};
     const resolver = new LocalModelResolver({
       byokConfigGetter: () => ({
@@ -1609,6 +1598,140 @@ describe('LocalModelResolver custom provider session affinity', () => {
 
     expect(headers['x-session-affinity']).toBeUndefined();
   });
+
+  // The routing readers exist to get a value onto the wire, so these pin the
+  // request pi would actually send rather than the resolved compat in between.
+  // Without them a regression after readModelCompat() would leave every reader
+  // test green while BYOK routing is still omitted from the request.
+  const routingPayloadFor = async (input: {
+    providerKey: string;
+    baseURL: string;
+    modelId: string;
+    compat: LocalModelConfig['compat'];
+  }) => {
+    const modelConfig: LocalModelConfig = input.compat ? { compat: input.compat } : {};
+    const resolver = new LocalModelResolver({
+      byokConfigGetter: () => ({
+        custom_provider: {
+          [input.providerKey]: {
+            api: 'openai-completions',
+            options: { apiKey: 'route-key', baseURL: input.baseURL },
+            models: { [input.modelId]: modelConfig },
+          },
+        },
+      }),
+    });
+    const resolved = await resolver.resolveModel({
+      sessionId: 'session-routing-wire',
+      turnId: 'turn-routing-wire',
+      agentConfig: {
+        ...AGENT_CONFIG,
+        model: modelRefForModel(`custom_provider:${input.providerKey}`, input.modelId, modelConfig),
+      },
+    });
+
+    let payload: { provider?: unknown; providerOptions?: unknown } | undefined;
+    await streamSimple(
+      resolved.model,
+      {
+        systemPrompt: 'Follow instructions.',
+        messages: [{ role: 'user', content: 'Hi', timestamp: Date.now() }],
+      },
+      {
+        apiKey: 'route-key',
+        onPayload: (params: unknown) => {
+          payload = params as { provider?: unknown; providerOptions?: unknown };
+        },
+        // The payload is captured before transport, so the request never leaves the test.
+        fetch: (() => Promise.reject(new Error('offline'))) as typeof globalThis.fetch,
+      },
+    ).result();
+    // Absence assertions below are only meaningful if a payload was actually
+    // captured: with an uncaptured payload every `toBeUndefined()` on it would
+    // pass for the wrong reason, so fail loudly rather than report green.
+    if (!payload) {
+      throw new Error('onPayload captured nothing; an absence assertion would be vacuous.');
+    }
+    return payload;
+  };
+
+  const providerRoutingFor = async (compat: LocalModelConfig['compat']) =>
+    (
+      await routingPayloadFor({
+        providerKey: 'openrouter',
+        baseURL: 'https://openrouter.ai/api/v1',
+        modelId: 'deepseek/deepseek-v4.1-flash',
+        compat,
+      })
+    ).provider;
+
+  const vercelRoutingFor = async (
+    compat: LocalModelConfig['compat'],
+    baseURL = 'https://ai-gateway.vercel.sh/v1',
+  ) =>
+    routingPayloadFor({
+      providerKey: 'vercel',
+      baseURL,
+      modelId: 'anthropic/claude',
+      compat,
+    });
+
+  it('sends OpenRouter routing preferences as the request provider field', async () => {
+    expect(
+      await providerRoutingFor({
+        openRouterRouting: { only: ['DeepSeek'], allow_fallbacks: false },
+      }),
+    ).toEqual({ only: ['DeepSeek'], allow_fallbacks: false });
+  });
+
+  it('omits the provider field when no OpenRouter routing is configured', async () => {
+    expect(await providerRoutingFor(undefined)).toBeUndefined();
+    expect(await providerRoutingFor({ supportsStrictMode: false })).toBeUndefined();
+  });
+
+  // The Vercel keys take a different route: the transport gates them on the base
+  // URL and builds `providerOptions.gateway`, so this pins that separate path.
+  it('sends Vercel gateway routing as providerOptions.gateway', async () => {
+    const payload = await vercelRoutingFor({
+      vercelGatewayRouting: { only: ['bedrock', 'anthropic'], order: ['anthropic'] },
+    });
+
+    expect(payload.providerOptions).toEqual({
+      gateway: { only: ['bedrock', 'anthropic'], order: ['anthropic'] },
+    });
+    // The OpenRouter field is not a Vercel field, and must stay out of it.
+    expect(payload.provider).toBeUndefined();
+  });
+
+  it('does not send Vercel gateway options off the Vercel host', async () => {
+    // The transport gates on the base URL, so the same config is inert elsewhere.
+    const payload = await vercelRoutingFor(
+      { vercelGatewayRouting: { only: ['bedrock'] } },
+      'https://gateway.example/v1',
+    );
+
+    expect(payload.providerOptions).toBeUndefined();
+  });
+
+  it('omits providerOptions.gateway when no Vercel routing is configured', async () => {
+    const payload = await vercelRoutingFor(undefined);
+
+    expect(payload.providerOptions).toBeUndefined();
+  });
+
+  it('sends Vercel gateway options for a mixed-case host', async () => {
+    // The transport's endpoint check is case-sensitive, so a host the reader
+    // approved must actually reach the wire in the form the transport matches.
+    // Without host folding this asserted nothing: the reader said yes and the
+    // request silently carried no gateway options.
+    const payload = await vercelRoutingFor(
+      { vercelGatewayRouting: { only: ['bedrock'] } },
+      'https://AI-GATEWAY.VERCEL.SH/v1',
+    );
+
+    expect(payload.providerOptions).toEqual({ gateway: { only: ['bedrock'] } });
+    expect(payload.provider).toBeUndefined();
+  });
 });
 
 describe('LocalModelResolver request image ceiling (#425)', () => {