fix: address Round 1 cr-loop findings (subject-scope bucket-a)

Six-agent unbiased review surfaced behavioural and audit-hygiene
regressions across the extracted base classes. Fixes:

openai-base/adapters/chat-completions-text.ts
- Defer RUN_FINISHED until end-of-stream so the trailing usage-only
  chunk that OpenAI emits AFTER finish_reason (when
  stream_options.include_usage is on) is captured. Previous fix emitted
  RUN_FINISHED with usage: undefined and dropped the trailing chunk.
- Forward upstream finish_reason ('length', 'content_filter', etc.)
  instead of collapsing all non-tool reasons to 'stop'.
- Surface tool-args JSON parse failures via logger.errors so a model
  emitting malformed JSON for tool arguments is debuggable instead of
  silently invoking the tool with input: {}.
- Fix mapOptionsToRequest precedence: `{...modelOptions, temperature:
  options.temperature, ...}` clobbered `modelOptions.temperature` with
  undefined whenever the caller didn't set the top-level option. Now
  spreads top-level fields only when defined.
- Throw on user message with zero content parts instead of silently
  sending content: '' (a paid request with no input).

openai-base/adapters/responses-text.ts
- Only reset accumulators on response.created. Previous code reset on
  response.failed/incomplete too, which left TEXT_MESSAGE_START events
  unbalanced when a response failed mid-stream. On terminal failure
  events we now emit TEXT_MESSAGE_END before RUN_ERROR.
- Synthesize a terminal RUN_FINISHED if the stream ends without
  response.completed (truncated upstream connection), matching the
  chat-completions adapter's behavior so consumers always see a
  terminal event for every started run.
- Surface tool-args JSON parse failures via logger.errors (parallel to
  chat-completions fix).
- Distinguish refusals from unsupported content_part types in
  handleContentPart instead of always reporting 'Unknown refusal'.
- Fix mapOptionsToRequest precedence: previously `...modelOptions` was
  spread LAST, silently shadowing the canonical top-level fields. Now
  matches the chat-completions adapter (modelOptions first, then
  defined top-level options), so callers tuning either backend see
  identical behaviour.
- extractTextFromResponse now throws a distinct refusal error instead
  of returning '' and letting JSON.parse('') produce a confusing
  'Failed to parse structured output as JSON. Content: ' message.

openai-base/adapters/summarize.ts
- generateId(this.name) for the result id (was hard-coded to '').
- Throw when chatStream emits RUN_ERROR instead of pretending a failed
  run succeeded with summary: ''.

openai-base/adapters/{image,transcription,tts}.ts
- Wrap SDK calls in try/catch + logger.errors with toRunErrorPayload
  so raw SDK errors (which can carry request metadata including auth
  headers) never reach user-supplied loggers. Matches the audit
  hygiene main #465 applied to ai-openai/text.ts before the
  extraction.
- tts.ts: cross-runtime ArrayBuffer→base64 helper so the adapter works
  in browser/edge runtimes that lack Buffer.
- transcription.ts: confidence calculation no longer treats
  avg_logprob === 0 (perfect-confidence) as missing.

openai-base/tools/file-search-tool.ts
- validateMaxNumResults(0) now correctly throws (was skipped because
  `if (maxNumResults && ...)` short-circuited on falsy zero).

ai-openai/adapters/transcription.ts
- shouldDefaultToVerbose returns true ONLY for whisper-1. The
  gpt-4o-transcribe* models reject 'verbose_json' with HTTP 400, so
  defaulting them to verbose was a guaranteed-failure regression. The
  previous logic was inverted.

ai-openai/tools/{file-search,image-generation}-tool.ts
- Drop locally duplicated validators; import from openai-base. The
  local copy of validateMaxNumResults had the same falsy-zero bug.

ai-openai/tools/computer-use-tool.ts
- Document that the brand discriminator ('computer_use') intentionally
  differs from the runtime tool name ('computer_use_preview'). The
  brand matches the model-meta capability union; the runtime name
  matches the OpenAI SDK literal that the special-tool dispatcher
  switches on.

ai-utils/src/transforms.ts
- Document transformNullsToUndefined's actual behavior (object keys
  are removed, top-level null becomes undefined, arrays preserve
  positional null). Restrict scope to JSON-shaped values; class
  instances/Date/Map/Set are not preserved by Object.entries recursion.

ai-elevenlabs/src/utils/client.ts
- Wire getElevenLabsApiKeyFromEnv and generateId through
  @tanstack/ai-utils so the dependency added during the merge is
  actually consumed (was unused after main's #504 SDK migration).

ai-openrouter/package.json
- Move @tanstack/ai from dependencies to devDependencies (it's
  already declared as a peerDependency). Avoids dual-instance hazards
  where the workspace package gets installed twice. Also bump the
  peer range to workspace:^ to match every other adapter.

.changeset/refactor-providers-to-shared-packages.md
- Correct the description: only ai-openai/ai-grok/ai-groq inherit
  from @tanstack/openai-base; the other six providers only consume
  @tanstack/ai-utils. Previous wording implied all nine adapters
  delegated to openai-base.

Verification:
- pnpm test:lib    : 31 projects pass (116+ unit tests)
- pnpm test:types  : 32 projects pass
- pnpm test:eslint : 31 projects pass
- pnpm build      : 33 projects pass

Author: AlemTuzlak

.changeset/refactor-providers-to-shared-packages.md

@@ -10,4 +10,4 @@
 '@tanstack/ai-elevenlabs': patch
 ---
 
-Internal refactor: delegate shared utilities to `@tanstack/ai-utils` and OpenAI-compatible adapter logic to `@tanstack/openai-base`. No breaking changes — all public APIs remain identical.
+Internal refactor: every provider now delegates `getApiKeyFromEnv` / `generateId` / `transformNullsToUndefined` / `ModelMeta` helpers to the new `@tanstack/ai-utils` package. `ai-openai`, `ai-grok`, and `ai-groq` additionally inherit OpenAI-compatible adapter base classes from the new `@tanstack/openai-base` package (Chat Completions / Responses text adapters, image / summarize / transcription / TTS / video adapters, schema converter, tool converters). The other providers (`ai-anthropic`, `ai-gemini`, `ai-ollama`, `ai-openrouter`, `ai-fal`, `ai-elevenlabs`) only consume `@tanstack/ai-utils` because they speak provider-native protocols, not OpenAI-compatible ones. No breaking changes — all public APIs remain identical.

packages/typescript/ai-elevenlabs/src/utils/client.ts

@@ -1,4 +1,8 @@
 import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js'
+import {
+  getApiKeyFromEnv,
+  generateId as sharedGenerateId,
+} from '@tanstack/ai-utils'
 import type { ElevenLabsOutputFormat } from '../model-meta'
 
 /**
@@ -39,14 +43,7 @@ function getEnvironment(): EnvObject | undefined {
 }
 
 export function getElevenLabsApiKeyFromEnv(): string {
-  const key = getEnvironment()?.ELEVENLABS_API_KEY
-  if (!key) {
-    throw new Error(
-      'ELEVENLABS_API_KEY is required. Please set it in your environment ' +
-        'variables or pass it explicitly to the adapter factory.',
-    )
-  }
-  return key
+  return getApiKeyFromEnv('ELEVENLABS_API_KEY')
 }
 
 export function getElevenLabsAgentIdFromEnv(): string {
@@ -80,9 +77,9 @@ export function createElevenLabsClient(
   })
 }
 
-export function generateId(prefix: string): string {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(2)}`
-}
+// Re-exported from `@tanstack/ai-utils` so existing callers keep working
+// while the implementation stays deduped across provider packages.
+export const generateId = sharedGenerateId
 
 /**
  * Convert an ArrayBuffer to base64 in a cross-runtime way.

packages/typescript/ai-openai/src/adapters/transcription.ts

@@ -35,7 +35,10 @@ export class OpenAITranscriptionAdapter<
   }
 
   protected override shouldDefaultToVerbose(model: string): boolean {
-    return model !== 'whisper-1'
+    // Only Whisper supports `verbose_json`. The gpt-4o-* transcribe models
+    // accept only `json` and `text` and reject `verbose_json` with HTTP 400,
+    // so they must NOT default to verbose. The previous logic was inverted.
+    return model === 'whisper-1'
   }
 }
 

packages/typescript/ai-openai/src/tools/computer-use-tool.ts

@@ -7,6 +7,12 @@ export {
   convertComputerUseToolToAdapterFormat,
 } from '@tanstack/openai-base'
 
+// The brand discriminator (`computer_use`) intentionally differs from the
+// runtime tool name (`computer_use_preview`). The brand matches the model-meta
+// tool-capability union (`tools: ['computer_use', ...]`) used to gate which
+// models can construct this tool at compile time, while the runtime name
+// matches the OpenAI SDK's literal `'computer_use_preview'` that the
+// special-tool dispatcher in `convertToolsToProviderFormat` switches on.
 export type OpenAIComputerUseTool = ProviderTool<'openai', 'computer_use'>
 
 /**

packages/typescript/ai-openai/src/tools/file-search-tool.ts

@@ -1,3 +1,4 @@
+import { validateMaxNumResults } from '@tanstack/openai-base'
 import type { ProviderTool } from '@tanstack/ai'
 import type { FileSearchToolConfig } from '@tanstack/openai-base'
 
@@ -7,12 +8,6 @@ export {
   convertFileSearchToolToAdapterFormat,
 } from '@tanstack/openai-base'
 
-const validateMaxNumResults = (maxNumResults: number | undefined) => {
-  if (maxNumResults && (maxNumResults < 1 || maxNumResults > 50)) {
-    throw new Error('max_num_results must be between 1 and 50.')
-  }
-}
-
 export type OpenAIFileSearchTool = ProviderTool<'openai', 'file_search'>
 
 /**

packages/typescript/ai-openai/src/tools/image-generation-tool.ts

@@ -1,3 +1,4 @@
+import { validatePartialImages } from '@tanstack/openai-base'
 import type { ProviderTool } from '@tanstack/ai'
 import type { ImageGenerationToolConfig } from '@tanstack/openai-base'
 
@@ -12,12 +13,6 @@ export type OpenAIImageGenerationTool = ProviderTool<
   'image_generation'
 >
 
-const validatePartialImages = (value: number | undefined) => {
-  if (value !== undefined && (value < 0 || value > 3)) {
-    throw new Error('partial_images must be between 0 and 3')
-  }
-}
-
 /**
  * Creates a standard Tool from ImageGenerationTool parameters, branded as an
  * OpenAI provider tool.

packages/typescript/ai-openrouter/package.json

@@ -44,15 +44,15 @@
   ],
   "dependencies": {
     "@openrouter/sdk": "0.12.14",
-    "@tanstack/ai": "workspace:*",
     "@tanstack/ai-utils": "workspace:*"
   },
   "devDependencies": {
+    "@tanstack/ai": "workspace:*",
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.2.7",
     "zod": "^4.2.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "workspace:*"
+    "@tanstack/ai": "workspace:^"
   }
 }

packages/typescript/ai-utils/src/transforms.ts

@@ -1,8 +1,22 @@
 /**
- * Recursively converts null values to undefined in an object.
- * Used after receiving structured output from OpenAI-compatible providers,
- * which return null for optional fields that were made nullable in the
- * JSON Schema strict mode transformation.
+ * Recursively strip `null` values from a JSON-shaped value so optional fields
+ * present as `null` in OpenAI-compatible structured output round-trip cleanly
+ * through Zod schemas that expect `undefined` (or absence) instead of `null`.
+ *
+ * Behaviour:
+ * - Top-level `null` becomes `undefined`.
+ * - Object properties whose value is `null` are removed entirely (so
+ *   `'key' in result` is `false`). Zod's `.optional()` treats absent keys
+ *   the same as `undefined`, which is the round-trip we want; setting the
+ *   key to `undefined` would still register the property in `Object.keys`
+ *   and break some `.strict()`/`Object.keys`-based callers.
+ * - Arrays recurse element-wise; `null` array elements stay `null` (an
+ *   array element is positional and removing it would shift indices).
+ *
+ * Scope: designed for `JSON.parse` output (plain objects, arrays, strings,
+ * numbers, booleans, null). Class instances, `Date`, `Map`, `Set`, etc. are
+ * NOT preserved — they are returned as fresh empty objects because the
+ * function recurses via `Object.entries`. Don't pass non-JSON values.
  */
 export function transformNullsToUndefined<T>(obj: T): T {
   if (obj === null) {

packages/typescript/openai-base/src/adapters/chat-completions-text.ts

@@ -242,16 +242,19 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
     let accumulatedContent = ''
     const timestamp = aguiState.timestamp
     let hasEmittedTextMessageStart = false
+    let lastModel: string | undefined
     // Track usage from any chunk that carries it. With
     // `stream_options: { include_usage: true }` OpenAI emits a terminal chunk
     // whose `choices` is `[]` and only the `usage` field is populated; the
-    // earlier `finish_reason` chunk does not include token counts. We capture
-    // usage here so RUN_FINISHED can be emitted with accurate numbers
-    // regardless of which chunk delivered them.
+    // earlier `finish_reason` chunk does NOT include token counts. We must
+    // therefore defer RUN_FINISHED until the iterator is exhausted so we can
+    // pick up usage from the trailing chunk regardless of arrival order.
     let lastUsage:
       | OpenAI_SDK.Chat.Completions.ChatCompletionChunk['usage']
       | undefined
-    let runFinishedEmitted = false
+    let pendingFinishReason:
+      | OpenAI_SDK.Chat.Completions.ChatCompletionChunk.Choice['finish_reason']
+      | undefined
 
     // Track tool calls being streamed (arguments come in chunks)
     const toolCallsInProgress = new Map<
@@ -271,6 +274,9 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         if (chunk.usage) {
           lastUsage = chunk.usage
         }
+        if (chunk.model) {
+          lastModel = chunk.model
+        }
 
         const choice = chunk.choices[0]
 
@@ -373,22 +379,42 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
           }
         }
 
-        // Handle finish reason
+        // Handle finish reason. We DO emit TOOL_CALL_END and TEXT_MESSAGE_END
+        // here because the corresponding _START events have already fired,
+        // and tool execution downstream wants to begin as soon as possible.
+        // RUN_FINISHED is deferred until the iterator is fully exhausted so
+        // we can capture the trailing usage chunk that arrives AFTER this
+        // chunk when stream_options.include_usage is on.
         if (choice.finish_reason) {
           // Emit all completed tool calls
           if (
             choice.finish_reason === 'tool_calls' ||
             toolCallsInProgress.size > 0
           ) {
             for (const [, toolCall] of toolCallsInProgress) {
-              // Parse arguments for TOOL_CALL_END
+              // Parse arguments for TOOL_CALL_END. Surface parse failures via
+              // the logger so a model emitting malformed JSON for tool args
+              // is debuggable instead of silently invoking the tool with {}.
               let parsedInput: unknown = {}
-              try {
-                parsedInput = toolCall.arguments
-                  ? JSON.parse(toolCall.arguments)
-                  : {}
-              } catch {
-                parsedInput = {}
+              if (toolCall.arguments) {
+                try {
+                  parsedInput = JSON.parse(toolCall.arguments)
+                } catch (parseError) {
+                  options.logger.errors(
+                    `${this.name}.processStreamChunks tool-args JSON parse failed`,
+                    {
+                      error: toRunErrorPayload(
+                        parseError,
+                        `tool ${toolCall.name} (${toolCall.id}) returned malformed JSON arguments`,
+                      ),
+                      source: `${this.name}.processStreamChunks`,
+                      toolCallId: toolCall.id,
+                      toolName: toolCall.name,
+                      rawArguments: toolCall.arguments,
+                    },
+                  )
+                  parsedInput = {}
+                }
               }
 
               // Emit AG-UI TOOL_CALL_END
@@ -404,12 +430,6 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
             }
           }
 
-          const computedFinishReason =
-            choice.finish_reason === 'tool_calls' ||
-            toolCallsInProgress.size > 0
-              ? 'tool_calls'
-              : 'stop'
-
           // Emit TEXT_MESSAGE_END if we had text content
           if (hasEmittedTextMessageStart) {
             yield asChunk({
@@ -418,49 +438,45 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
               model: chunk.model || options.model,
               timestamp,
             })
+            hasEmittedTextMessageStart = false
           }
 
-          // Capture usage from this chunk if present. The terminal usage-only
-          // chunk (when stream_options.include_usage is on) typically arrives
-          // AFTER this finish_reason chunk, so prefer the later one when both
-          // are available; here we just merge what we have so far.
-          const usage = chunk.usage ?? lastUsage
-
-          // Emit AG-UI RUN_FINISHED
-          yield asChunk({
-            type: 'RUN_FINISHED',
-            runId: aguiState.runId,
-            model: chunk.model || options.model,
-            timestamp,
-            usage: usage
-              ? {
-                  promptTokens: usage.prompt_tokens || 0,
-                  completionTokens: usage.completion_tokens || 0,
-                  totalTokens: usage.total_tokens || 0,
-                }
-              : undefined,
-            finishReason: computedFinishReason,
-          })
-          runFinishedEmitted = true
+          // Remember the upstream finish_reason; RUN_FINISHED is emitted at
+          // end-of-stream so we pick up the trailing usage-only chunk too.
+          pendingFinishReason = choice.finish_reason
         }
       }
 
-      // If the stream ended without a `finish_reason` chunk (e.g. an aborted
-      // stream that still managed to deliver the terminal usage chunk), emit
-      // a synthetic RUN_FINISHED so callers always see a terminal event.
-      if (!runFinishedEmitted && aguiState.hasEmittedRunStarted) {
+      // Emit a single terminal RUN_FINISHED after the iterator is exhausted.
+      // This both delivers accurate token counts (the trailing usage chunk
+      // may arrive AFTER the finish_reason chunk) and gives consumers a
+      // guaranteed terminal event even when the upstream cuts off mid-stream
+      // (no finish_reason chunk ever arrives).
+      if (aguiState.hasEmittedRunStarted) {
+        // Make sure the text message lifecycle is closed even on early
+        // termination paths where finish_reason never arrives.
         if (hasEmittedTextMessageStart) {
           yield asChunk({
             type: 'TEXT_MESSAGE_END',
             messageId: aguiState.messageId,
-            model: options.model,
+            model: lastModel || options.model,
             timestamp,
           })
         }
+
+        // Map upstream finish_reason to AG-UI's narrower vocabulary while
+        // preserving the upstream value when it falls outside the AG-UI set.
+        // Collapsing length / content_filter to 'stop' would hide why the
+        // run terminated — surface it instead.
+        const finishReason: string =
+          pendingFinishReason === 'tool_calls' || toolCallsInProgress.size > 0
+            ? 'tool_calls'
+            : (pendingFinishReason ?? 'stop')
+
         yield asChunk({
           type: 'RUN_FINISHED',
           runId: aguiState.runId,
-          model: options.model,
+          model: lastModel || options.model,
           timestamp,
           usage: lastUsage
             ? {
@@ -469,7 +485,7 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
                 totalTokens: lastUsage.total_tokens || 0,
               }
             : undefined,
-          finishReason: toolCallsInProgress.size > 0 ? 'tool_calls' : 'stop',
+          finishReason,
         })
       }
     } catch (error: unknown) {
@@ -528,13 +544,22 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
 
     const modelOptions = options.modelOptions
 
+    // Build the request so explicit top-level options win over modelOptions
+    // when set, but `undefined` top-level options do NOT clobber values the
+    // caller put in modelOptions. Keeping the merge nullish-aware fixes the
+    // silent regression where a `modelOptions: { temperature: 0.7 }` setting
+    // was overwritten with `temperature: undefined`.
     return {
       ...modelOptions,
       model: options.model,
       messages,
-      temperature: options.temperature,
-      max_tokens: options.maxTokens,
-      top_p: options.topP,
+      ...(options.temperature !== undefined && {
+        temperature: options.temperature,
+      }),
+      ...(options.maxTokens !== undefined && {
+        max_tokens: options.maxTokens,
+      }),
+      ...(options.topP !== undefined && { top_p: options.topP }),
       tools: tools as Array<OpenAI_SDK.Chat.Completions.ChatCompletionTool>,
       stream: true,
     }
@@ -609,9 +634,20 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
       parts.push(converted)
     }
 
+    if (parts.length === 0) {
+      // The original message had no content parts at all (e.g. content was
+      // explicitly null or []). Sending an empty user message to OpenAI
+      // produces a paid request with no signal — fail loud instead.
+      throw new Error(
+        `User message for ${this.name} has no content parts. ` +
+          `Empty user messages would produce a paid request with no input; ` +
+          `provide at least one text/image/audio part or omit the message.`,
+      )
+    }
+
     return {
       role: 'user',
-      content: parts.length > 0 ? parts : '',
+      content: parts,
     }
   }