refactor(openai-base): rename, adopt openai SDK, decouple ai-openrouter

.changeset/decouple-openrouter-collapse-openai-base.md

@@ -0,0 +1,35 @@
+---
+'@tanstack/openai-base': minor
+'@tanstack/ai-openai': patch
+'@tanstack/ai-grok': patch
+'@tanstack/ai-groq': patch
+'@tanstack/ai-openrouter': patch
+---
+
+Decouple `@tanstack/ai-openrouter` from the shared OpenAI base, and collapse the base into a thinner shim over the `openai` SDK.
+
+Three changes that ship together:
+
+**1. Rename `@tanstack/ai-openai-compatible` → `@tanstack/openai-base`.** The previous name implied a multi-vendor protocol surface. After ai-openrouter is decoupled (see below), the only remaining consumers (`ai-openai`, `ai-grok`, `ai-groq`) all back onto the `openai` SDK with a different `baseURL` — "base" describes that role accurately. Imports change:
+
+```diff
+- import { OpenAICompatibleChatCompletionsTextAdapter } from '@tanstack/ai-openai-compatible'
++ import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+- import { OpenAICompatibleResponsesTextAdapter } from '@tanstack/ai-openai-compatible'
++ import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
+```
+
+`@tanstack/ai-openai-compatible@0.2.x` remains published for anyone with a pinned lockfile reference but will receive no further updates.
+
+**2. `@tanstack/openai-base` adopts the `openai` SDK directly.** The previous package vendored ~720 LOC of hand-written wire-format types (`ChatCompletion`, `ResponseStreamEvent`, etc.) and exposed abstract `callChatCompletion*` / `callResponse*` hooks subclasses had to implement. Both are gone:
+
+- The base now depends on `openai` again and imports types directly from `openai/resources/...`. The vendored `src/types/` directory is removed; consumers that imported wire types from the package (e.g. `import type { ResponseInput } from '@tanstack/ai-openai-compatible'`) should now import from the openai SDK.
+- The abstract SDK-call methods are removed. The base constructor takes a pre-built `OpenAI` client (`new OpenAIBaseChatCompletionsTextAdapter(model, name, openaiClient)`) and calls `client.chat.completions.create` / `client.responses.create` itself. Subclasses (`ai-openai`, `ai-grok`, `ai-groq`) now just construct the SDK with their provider-specific `baseURL` and pass it to `super` — `callChatCompletion*` / `callResponse*` overrides go away.
+
+The other extension hooks (`extractReasoning`, `extractTextFromResponse`, `processStreamChunks`, `makeStructuredOutputCompatible`, `transformStructuredOutput`, `mapOptionsToRequest`, `convertMessage`) remain. Groq's `processStreamChunks` and `makeStructuredOutputCompatible` overrides (for `x_groq.usage` promotion and Groq's structured-output schema quirks) are unchanged.
+
+**3. Decouple `@tanstack/ai-openrouter` from the OpenAI base entirely.** OpenRouter ships its own SDK (`@openrouter/sdk`) with a camelCase shape, so inheriting from the OpenAI-shaped base forced a snake_case ↔ camelCase round-trip on every request and stream event. ai-openrouter now extends `BaseTextAdapter` directly and inlines its own stream processors (`OpenRouterTextAdapter` for chat-completions, `OpenRouterResponsesTextAdapter` for the Responses beta), reading OpenRouter's camelCase types natively. The `@tanstack/openai-base` and `openai` dependencies are removed from ai-openrouter; only `@openrouter/sdk`, `@tanstack/ai`, and `@tanstack/ai-utils` remain.
+
+Public API is unchanged: `openRouterText`, `openRouterResponsesText`, `createOpenRouterText`, `createOpenRouterResponsesText`, the OpenRouter tool factories, provider routing surface (`provider`, `models`, `plugins`, `variant`, `transforms`), app attribution headers (`httpReferer`, `appTitle`), `:variant` model suffixing, `RequestAbortedError` propagation, and the OpenRouter-specific structured-output null-preservation all behave the same. The ~300 LOC of inbound/outbound shape converters (`toOpenRouterRequest`, `toChatCompletion`, `adaptOpenRouterStreamChunks`, `toSnakeResponseResult`, …) are gone.
+
+`ai-ollama` remains on `BaseTextAdapter` directly — its native API uses a different wire format from Chat Completions and was never on the shared base.

.changeset/openrouter-narrow-stream-chunk-types.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-openrouter': patch
+---
+
+Internal: drop the remaining duck-typed `as { ... }` casts on stream chunks in `OpenRouterResponsesTextAdapter`. Five sites (`response.created/in_progress/incomplete/failed` model + error capture, `response.content_part.added/done` payload, and the `response.completed` function-call detection) now narrow via the SDK's discriminated unions directly. Behaviourally identical; reduces the chance of a SDK type rename silently slipping past us.

.changeset/summarize-unify-on-chat-stream-wrapper.md

@@ -0,0 +1,23 @@
+---
+'@tanstack/ai': patch
+'@tanstack/ai-anthropic': patch
+'@tanstack/ai-gemini': patch
+'@tanstack/ai-grok': patch
+'@tanstack/ai-ollama': patch
+'@tanstack/ai-openai': patch
+'@tanstack/ai-openrouter': patch
+---
+
+Unify the summarize subsystem on a shared chat-stream wrapper, plumb `modelOptions` through end-to-end, and tighten the `TProviderOptions` generic.
+
+**Provider summarize adapters now share one implementation.** Anthropic, Gemini, Ollama, and OpenRouter previously each shipped a bespoke 200–300 LOC summarize adapter that re-implemented streaming, error handling, usage accounting, and chunk assembly on top of their text adapter. They now construct a `ChatStreamSummarizeAdapter` (formerly `ChatStreamWrapperAdapter`, renamed and exported from `@tanstack/ai/activities`) wrapping their own text adapter, matching the existing OpenAI/Grok pattern. Removes ~600 LOC of duplicated logic across the six providers and ensures behavioural parity.
+
+**`SummarizationOptions.modelOptions` now reaches the wire.** Previously the activity layer (`runSummarize` / `runStreamingSummarize`) silently dropped `modelOptions` when building the internal `SummarizationOptions` it forwarded to the adapter. Provider-specific knobs (Anthropic cache control, OpenRouter plugins, Gemini safety settings, Groq tuning params, …) now flow through correctly.
+
+**Provider summarize types resolve from the wrapped text adapter.** Each provider previously shipped a bespoke `XSummarizeProviderOptions` interface (a partial copy of its text provider options). Those interfaces are removed; summarize provider options are now inferred from the text adapter's `~types` via the new `InferTextProviderOptions<TAdapter>` helper exported from `@tanstack/ai/activities`. IntelliSense for `modelOptions` on `summarize({ adapter: openai('gpt-4o'), … })` now matches what `chat({ adapter: openai('gpt-4o'), … })` would show.
+
+**`SummarizeAdapter` interface methods are now generic in `TProviderOptions`.** `summarize` and `summarizeStream` previously took `SummarizationOptions` (defaulted, so `modelOptions` was effectively `Record<string, any>` regardless of the adapter's typed shape). They now take `SummarizationOptions<TProviderOptions>`, threading the class's `TProviderOptions` generic through. Source-compatible for callers that didn't specify the generic; type-tighter for implementers and downstream consumers.
+
+**Default aligned across the summarize surface.** `SummarizationOptions`, `SummarizeAdapter`, `BaseSummarizeAdapter`, and `ChatStreamSummarizeAdapter` previously had a mixed `Record<string, any>` / `Record<string, unknown>` / `object` set of defaults for `TProviderOptions`. They now uniformly default to `Record<string, unknown>` so unparameterised consumers narrow before indexed access on `modelOptions`. The `extends object` constraint is unchanged — per-model typed interfaces (e.g. `OpenAIBaseOptions & OpenAIReasoningOptions & ...`) inferred via `InferTextProviderOptions<TAdapter>` continue to satisfy it without needing a string index signature. No public-surface signature change for callers that supply a concrete provider-options shape (every shipping adapter does).
+
+Bespoke `*SummarizeProviderOptions` interfaces (e.g. `OpenAISummarizeProviderOptions`, `AnthropicSummarizeProviderOptions`, `GeminiSummarizeProviderOptions`, `OllamaSummarizeProviderOptions`, `OpenRouterSummarizeProviderOptions`) are removed from the provider packages' public exports. Consumers who imported them should switch to inferring the type from the adapter (`InferTextProviderOptions<typeof adapter>`) or remove the explicit annotation (it'll be inferred from the adapter argument).

docs/adapters/openrouter.md

@@ -35,16 +35,17 @@ const stream = chat({
 ## Configuration
 
 ```typescript
-import { createOpenRouter, type OpenRouterConfig } from "@tanstack/ai-openrouter";
-
-const config: OpenRouterConfig = {
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  baseURL: "https://openrouter.ai/api/v1", // Optional
-  httpReferer: "https://your-app.com", // Optional, for rankings
-  xTitle: "Your App Name", // Optional, for rankings
-};
-
-const adapter = createOpenRouter(config.apiKey, config);
+import { createOpenRouterText } from "@tanstack/ai-openrouter";
+
+const adapter = createOpenRouterText(
+  "openai/gpt-5",
+  process.env.OPENROUTER_API_KEY!,
+  {
+    serverURL: "https://openrouter.ai/api/v1", // Optional
+    httpReferer: "https://your-app.com", // Optional, for rankings
+    appTitle: "Your App Name", // Optional, for rankings
+  },
+);
 ```
 
 ## Available Models
@@ -122,18 +123,52 @@ OpenRouter can automatically route requests to the best available provider:
 ```typescript
 const stream = chat({
   adapter: openRouterText("openrouter/auto"),
-  messages, 
-  providerOptions: {
+  messages,
+  modelOptions: {
     models: [
       "openai/gpt-4o",
       "anthropic/claude-3.5-sonnet",
       "google/gemini-pro",
     ],
-    route: "fallback", // Use fallback if primary fails
   },
 });
 ```
-
+
+## Chat Completions vs Responses (beta)
+
+OpenRouter exposes two OpenAI-compatible wire formats, and the adapter
+package ships one of each:
+
+| Adapter                    | Endpoint                  | Status   | When to use                                                                  |
+| -------------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------- |
+| `openRouterText`           | `/v1/chat/completions`    | Stable   | Default for almost everything. Broadest model + tool support.                |
+| `openRouterResponsesText`  | `/v1/responses`           | Beta     | OpenAI Responses-shaped request/response; richer multi-turn state on OpenAI-style models. |
+
+Both adapters route to any underlying model OpenRouter supports
+(`anthropic/...`, `google/...`, `meta-llama/...`, etc.) — the wire format
+describes how your client talks to OpenRouter, not which provider answers.
+`/v1/responses` is OpenAI's newer API surface; OpenRouter implements it so
+clients that prefer that wire format can use it across the same 300+
+model catalogue.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { openRouterResponsesText } from "@tanstack/ai-openrouter";
+
+const stream = chat({
+  adapter: openRouterResponsesText("anthropic/claude-sonnet-4.5"),
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+Caveats while the Responses adapter is in beta:
+
+- Function tools are supported; OpenRouter's branded server-tools (web
+  search, file search, …) are not yet wired through this path — use
+  `openRouterText` if you need those.
+- If in doubt, prefer `openRouterText`. The Chat Completions endpoint has
+  broader provider coverage and feature parity today.
+
 ## Next Steps
 
 - [Getting Started](../getting-started/quick-start) - Learn the basics