feat(ai-openrouter): per-request native combined tools + outputSchema mode

.changeset/openrouter-combined-tools-and-schema.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-openrouter': minor
+---
+
+Add native combined tools + `outputSchema` mode to both OpenRouter text adapters (chat-completions and Responses). When the resolved upstream model supports emitting a schema-constrained final answer alongside tool calls in a single pass, `chat({ outputSchema, tools, stream: true })` now wires the JSON Schema into the same streaming request as the tools and harvests the final-turn JSON, skipping the separate finalization round-trip.
+
+Because OpenRouter is a routing layer, capability is keyed per resolved upstream model via the new `OPENROUTER_COMBINED_TOOLS_AND_SCHEMA_MODELS` set, exported from `@tanstack/ai-openrouter/model-meta`, which both adapters consult from `supportsCombinedToolsAndSchema()`. The set is derived from each upstream provider's combined-mode gate (Anthropic 4.5+, Gemini 3.x, OpenAI's strict `json_schema` era, Grok 4.x) rather than the broader catalog `responseFormat` flag, so models that advertise structured output but predate native combined mode stay on the legacy finalization path.

packages/ai-openrouter/package.json

@@ -25,6 +25,10 @@
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
     },
+    "./model-meta": {
+      "types": "./dist/esm/model-meta.d.ts",
+      "import": "./dist/esm/model-meta.js"
+    },
     "./tools": {
       "types": "./dist/esm/tools/index.d.ts",
       "import": "./dist/esm/tools/index.js"

packages/ai-openrouter/src/adapters/openrouter-combined-structured-output.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  OPENROUTER_CHAT_MODELS,
+  OPENROUTER_COMBINED_TOOLS_AND_SCHEMA_MODELS,
+} from '../model-meta'
+import { createOpenRouterResponsesText } from './responses-text'
+import { createOpenRouterText } from './text'
+import type { Tool } from '@tanstack/ai'
+
+// The adapter constructor instantiates `new OpenRouter(config)`. Mock the SDK
+// so construction succeeds; these tests only exercise request building
+// (`mapOptionsToRequest`) and the capability gate, never an SDK call.
+vi.mock('@openrouter/sdk', () => ({
+  OpenRouter: class {
+    chat = { send: () => undefined }
+    beta = { responses: { send: () => undefined } }
+  },
+}))
+
+// JSON Schema as the engine hands it to the adapter on the combined path.
+const outputSchema = {
+  type: 'object',
+  properties: { answer: { type: 'string' } },
+  required: ['answer'],
+}
+
+const tools: Array<Tool> = [
+  { name: 'lookup_weather', description: 'Return the forecast for a location' },
+]
+
+// `mapOptionsToRequest` is protected; reach it directly to assert the wire
+// shape without standing up a full streaming round-trip.
+type BuiltOpenRouterRequest = Record<string, unknown> & {
+  model?: string
+  models?: Array<string>
+  responseFormat?: unknown
+  text?: Record<string, unknown> & {
+    format?: Record<string, unknown>
+    verbosity?: string
+  }
+  tools?: Array<unknown>
+}
+
+type RequestBuilder = {
+  mapOptionsToRequest: (options: Record<string, unknown>) => BuiltOpenRouterRequest
+}
+
+function asRequestBuilder(adapter: unknown): RequestBuilder {
+  return adapter as RequestBuilder
+}
+
+function buildChatRequest(
+  model: string,
+  modelOptions?: Record<string, unknown>,
+) {
+  const adapter = asRequestBuilder(
+    createOpenRouterText(model as 'openai/gpt-4o', 'test-key'),
+  )
+  return adapter.mapOptionsToRequest({
+    model,
+    messages: [{ role: 'user', content: 'hi' }],
+    tools,
+    outputSchema,
+    ...(modelOptions ? { modelOptions } : {}),
+  })
+}
+
+function buildResponsesRequest(model: string) {
+  const adapter = asRequestBuilder(
+    createOpenRouterResponsesText(model as 'openai/gpt-4o', 'test-key'),
+  )
+  return adapter.mapOptionsToRequest({
+    model,
+    messages: [{ role: 'user', content: 'hi' }],
+    tools,
+    outputSchema,
+  })
+}
+
+describe('OpenRouter combined tools + outputSchema (#612)', () => {
+  describe('supportsCombinedToolsAndSchema gate', () => {
+    it('returns true for combined-capable upstream models', () => {
+      expect(
+        createOpenRouterText(
+          'anthropic/claude-sonnet-4.5',
+          'k',
+        ).supportsCombinedToolsAndSchema(),
+      ).toBe(true)
+      expect(
+        createOpenRouterText(
+          'openai/gpt-4o',
+          'k',
+        ).supportsCombinedToolsAndSchema(),
+      ).toBe(true)
+      expect(
+        createOpenRouterText(
+          'x-ai/grok-4.3',
+          'k',
+        ).supportsCombinedToolsAndSchema(),
+      ).toBe(true)
+    })
+
+    it('returns false for upstream models the upstream gate excludes', () => {
+      // claude-opus-4.1 predates Anthropic combined mode (4.5+); gpt-4o-2024-05-13
+      // predates strict json_schema — both have `responseFormat` in the catalog
+      // but are deliberately excluded.
+      expect(
+        createOpenRouterText(
+          'anthropic/claude-opus-4.1',
+          'k',
+        ).supportsCombinedToolsAndSchema(),
+      ).toBe(false)
+      expect(
+        createOpenRouterText(
+          'openai/gpt-4o-2024-05-13',
+          'k',
+        ).supportsCombinedToolsAndSchema(),
+      ).toBe(false)
+    })
+
+    it('mirrors the gate on the Responses adapter', () => {
+      expect(
+        createOpenRouterResponsesText(
+          'openai/gpt-4o',
+          'k',
+        ).supportsCombinedToolsAndSchema(),
+      ).toBe(true)
+      expect(
+        createOpenRouterResponsesText(
+          'openai/gpt-4o-2024-05-13',
+          'k',
+        ).supportsCombinedToolsAndSchema(),
+      ).toBe(false)
+    })
+
+    it('requires every OpenRouter fallback model to support combined mode', () => {
+      const adapter = createOpenRouterText('openai/gpt-4o', 'k')
+
+      expect(
+        adapter.supportsCombinedToolsAndSchema({
+          models: ['anthropic/claude-sonnet-4.5'],
+        }),
+      ).toBe(true)
+      expect(
+        adapter.supportsCombinedToolsAndSchema({
+          models: ['openai/gpt-4o-2024-05-13'],
+        }),
+      ).toBe(false)
+    })
+  })
+
+  describe('chat-completions request payload', () => {
+    it('attaches responseFormat alongside tools on the combined path', () => {
+      const req = buildChatRequest('openai/gpt-4o')
+      expect(req.responseFormat).toEqual({
+        type: 'json_schema',
+        jsonSchema: {
+          name: 'structured_output',
+          schema: expect.any(Object),
+          strict: true,
+        },
+      })
+      expect(req.tools).toBeDefined()
+      expect(req.tools?.length).toBeGreaterThan(0)
+    })
+
+    it('omits responseFormat for an unsupported model (legacy finalization path)', () => {
+      const req = buildChatRequest('anthropic/claude-opus-4.1')
+      expect(req.responseFormat).toBeUndefined()
+      // tools still flow — only the schema attachment is gated.
+      expect(req.tools).toBeDefined()
+    })
+
+    it('omits responseFormat when any fallback model is unsupported', () => {
+      const req = buildChatRequest('openai/gpt-4o', {
+        models: ['openai/gpt-4o-2024-05-13'],
+      })
+      expect(req.responseFormat).toBeUndefined()
+      expect(req.models).toEqual(['openai/gpt-4o-2024-05-13'])
+      expect(req.tools).toBeDefined()
+    })
+
+    it('keys capability off the bare model id, ignoring the :variant suffix', () => {
+      const req = buildChatRequest('openai/gpt-4o', { variant: 'nitro' })
+      expect(req.responseFormat).toBeDefined()
+      // variant rides the model id, not the wire body.
+      expect(req.model).toBe('openai/gpt-4o:nitro')
+    })
+  })
+
+  describe('Responses request payload', () => {
+    it('attaches text.format alongside tools on the combined path', () => {
+      const req = buildResponsesRequest('openai/gpt-4o')
+      expect(req.text).toEqual({
+        format: {
+          type: 'json_schema',
+          name: 'structured_output',
+          schema: expect.any(Object),
+          strict: true,
+        },
+      })
+      expect(req.tools).toBeDefined()
+    })
+
+    it('omits text.format for an unsupported model', () => {
+      const req = buildResponsesRequest('openai/gpt-4o-2024-05-13')
+      expect(req.text).toBeUndefined()
+    })
+
+    it('omits text.format when any fallback model is unsupported', () => {
+      const adapter = asRequestBuilder(
+        createOpenRouterResponsesText('openai/gpt-4o', 'test-key'),
+      )
+      const req = adapter.mapOptionsToRequest({
+        model: 'openai/gpt-4o',
+        messages: [{ role: 'user', content: 'hi' }],
+        tools,
+        outputSchema,
+        modelOptions: { models: ['openai/gpt-4o-2024-05-13'] },
+      })
+      expect(req.text).toBeUndefined()
+      expect(req.models).toEqual(['openai/gpt-4o-2024-05-13'])
+      expect(req.tools).toBeDefined()
+    })
+
+    it('preserves caller-supplied text.* fields when attaching the schema format', () => {
+      const adapter = asRequestBuilder(
+        createOpenRouterResponsesText('openai/gpt-4o', 'test-key'),
+      )
+      const req = adapter.mapOptionsToRequest({
+        model: 'openai/gpt-4o',
+        messages: [{ role: 'user', content: 'hi' }],
+        tools,
+        outputSchema,
+        modelOptions: { text: { verbosity: 'low' } },
+      })
+      // `text.format` carries the combined-mode schema; the caller's
+      // `text.verbosity` rides alongside it rather than being clobbered.
+      expect(req.text?.verbosity).toBe('low')
+      expect(req.text?.format).toMatchObject({
+        type: 'json_schema',
+        name: 'structured_output',
+        strict: true,
+      })
+    })
+  })
+
+  describe('set integrity', () => {
+    it('every combined-mode id exists in the OpenRouter catalog', () => {
+      const catalog = new Set<string>(OPENROUTER_CHAT_MODELS)
+      for (const id of OPENROUTER_COMBINED_TOOLS_AND_SCHEMA_MODELS) {
+        expect(catalog.has(id), `${id} is not in OPENROUTER_CHAT_MODELS`).toBe(
+          true,
+        )
+      }
+    })
+  })
+})

packages/ai-openrouter/src/adapters/responses-text.ts

@@ -7,6 +7,7 @@ import {
 } from '@tanstack/ai/adapter-internals'
 import { generateId } from '@tanstack/ai-utils'
 import { extractRequestOptions } from '../internal/request-options'
+import { openRouterSupportsCombinedToolsAndSchema } from '../internal/combined-tools-and-schema'
 import { makeStructuredOutputCompatible } from '../internal/schema-converter'
 import { convertFunctionToolToResponsesFormat } from '../internal/responses-tool-converter'
 import { isWebSearchTool } from '../tools/web-search-tool'
@@ -29,6 +30,7 @@ import type {
 } from '@tanstack/ai/adapters'
 import type {
   ContentPart,
+  JSONSchema,
   ModelMessage,
   StreamChunk,
   TextOptions,
@@ -1566,6 +1568,23 @@ export class OpenRouterResponsesTextAdapter<
         )
       : undefined
 
+    // Native combined mode (#612): the engine populates `options.outputSchema`
+    // on the `chatStream` call ONLY when this adapter declared
+    // `supportsCombinedToolsAndSchema()` for the model. When set, attach the
+    // schema via `text.format: json_schema` alongside `tools` so it rides the
+    // same streaming request and the engine harvests it from the final-turn
+    // text. The legacy `structuredOutput*` methods strip `outputSchema` before
+    // calling this, so the branch only fires on the combined path.
+    const combinedOutputSchema: JSONSchema | undefined = options.outputSchema
+    const combinedSchema =
+      combinedOutputSchema &&
+      this.supportsCombinedToolsAndSchema(options.modelOptions)
+        ? this.makeStructuredOutputCompatible(
+            combinedOutputSchema,
+            combinedOutputSchema.required,
+          )
+        : undefined
+
     const built: Pick<
       ResponsesRequest,
       | 'model'
@@ -1578,6 +1597,7 @@ export class OpenRouterResponsesTextAdapter<
       | 'tools'
       | 'toolChoice'
       | 'parallelToolCalls'
+      | 'text'
     > = {
       ...modelOptions,
       model: options.model + variantSuffix,
@@ -1596,11 +1616,39 @@ export class OpenRouterResponsesTextAdapter<
         tools.length > 0 && {
           tools,
         }),
+      ...(combinedSchema && {
+        // Merge onto any caller-supplied `text` (spread above via
+        // `...modelOptions`) so sibling fields like `text.verbosity` survive;
+        // only `text.format` is overridden by the combined-mode schema.
+        text: {
+          ...modelOptions.text,
+          format: {
+            type: 'json_schema' as const,
+            name: 'structured_output',
+            schema: combinedSchema,
+            strict: true,
+          },
+        },
+      }),
     }
 
     return built
   }
 
+  /**
+   * Native combined tools + `outputSchema` (#612). OpenRouter routes to many
+   * upstream providers, so capability is per-request: `modelOptions.models`
+   * can add fallback routes, and native combined mode is safe only when every
+   * possible routed model supports it. `:variant` suffixes are routing
+   * directives and do not change combined-mode support. Models not in the set
+   * fall back to the legacy finalization path.
+   */
+  supportsCombinedToolsAndSchema(
+    modelOptions?: OpenRouterResponsesTextProviderOptions,
+  ): boolean {
+    return openRouterSupportsCombinedToolsAndSchema(this.model, modelOptions)
+  }
+
   /**
    * Convert a list of ModelMessage to OpenRouter's `InputsUnion` array form.
    * Emits camelCase shapes (`callId`, `imageUrl`, `videoUrl`, `fileData`,