fix: address Round 3 cr-loop findings (lifecycle + edge cases)

Round 3 confirmation surfaced subtler tool-call lifecycle and
terminal-event idempotency gaps that earlier rounds missed.

openai-base/adapters/chat-completions-text.ts
- Move RUN_STARTED emission BEFORE the `if (!choice) continue` guard so
  a stream that arrives entirely as usage-only chunks (no choices) still
  emits RUN_STARTED. Without this the post-loop synthetic terminal block
  (which gates on hasEmittedRunStarted) skipped emission entirely,
  producing zero events for the run.
- Skip non-started entries in the finish_reason TOOL_CALL_END loop and
  in the post-loop synthetic close. A delta with index but no id/name
  populates toolCallsInProgress without ever emitting TOOL_CALL_START;
  emitting TOOL_CALL_END for those entries violated AG-UI lifecycle
  (END without matching START) and produced empty toolCallId payloads
  consumers couldn't pair.
- Clear toolCallsInProgress after emitting TOOL_CALL_END, and gate the
  synthetic finishReason on a separate pendingToolCount counter rather
  than `toolCallsInProgress.size > 0`. Previously, a tool-then-clean-stop
  run reported finishReason: 'tool_calls' because the map was never
  cleared after the in-loop emission.
- parsedInput now coerces non-object JSON to {} (parallel to the
  Responses adapter's existing guard). A bare string/number/null in the
  arguments wire would otherwise propagate to tool execution as the
  TOOL_CALL_END.input.
- Close any started tool calls in the post-loop synthetic block on
  truncated streams (no finish_reason ever arrives) so consumers see a
  matching TOOL_CALL_END for every TOOL_CALL_START.
- convertMessage: throw on a single-text user message whose content is
  empty (paid request with no input). Previously the early-return
  bypassed the multipart fail-loud guard.
- convertMessage: assistant tool-only messages now use `content: null`
  instead of `content: ''`, matching the OpenAI Chat Completions
  contract; empty-string content interacts oddly with tokenization on
  some backends.
- convertContentPart image branch defaults the data-URI MIME to
  `application/octet-stream` when source.mimeType is undefined, instead
  of interpolating literal "undefined" into the URI.

openai-base/adapters/responses-text.ts
- response.failed / response.incomplete now ALWAYS emit RUN_ERROR (even
  when both `error` and `incomplete_details` are missing) and `return`
  out of the loop. Previously, an incomplete event with no detail
  silently coerced the run to RUN_FINISHED { finishReason: 'stop' } via
  the post-loop synthetic block, masking the failure. The early return
  also stops further chunks from being processed after a terminal event.
- response.output_item.added: emit TOOL_CALL_START only when the
  metadata's started flag is false. A duplicate output_item.added for
  the same item id (retried streams / replay) no longer emits a second
  TOOL_CALL_START.
- response.function_call_arguments.delta: drop the `args` field. Its
  `metadata ? undefined : chunk.delta` polarity was inverted (populated
  only on orphan-tool-call paths), the chat-completions adapter never
  emitted it, and consumers should accumulate `delta` themselves.
- response.function_call_arguments.done: skip TOOL_CALL_END (and log)
  when the metadata's started flag is false, mirroring the chat-
  completions adapter's started-guard. Emitting END without a matching
  START broke AG-UI consumers' lifecycle pairing.
- handleContentPart RUN_ERROR is now treated as terminal: set
  runFinishedEmitted = true and `return` out of the loop. Previously
  the loop kept processing and the synthetic terminal block could emit
  a second RUN_FINISHED after a refusal.
- Mark hasStreamedContentDeltas / hasStreamedReasoningDeltas in the
  content_part.added handler so a subsequent matching content_part.done
  doesn't re-emit the same text (the existing skip guard for done
  events depended on these flags being true).
- handleContentPart's reasoning_text branch caches the fallback stepId
  (`if (!stepId) stepId = generateId(...)`) instead of generating a
  fresh id on each call. Multiple reasoning content parts arriving
  without a preceding STEP_STARTED no longer emit different stepIds.
- convertContentPartToInput image and audio: default the data-URI MIME
  to application/octet-stream when source.mimeType is undefined.

openai-base/adapters/{chat-completions,responses}-tool-converter.ts
- Shallow-copy the schemaConverter result before mutating
  additionalProperties. A subclass-supplied passthrough converter
  could otherwise have its caller's schema mutated by the
  `jsonSchema.additionalProperties = false` assignment.

openai-base/adapters/video.ts
- getVideoUrl SDK fall-through (content/getContent/download): convert
  the binary response to a data URL like the downloadContent path
  already does. Previously the bottom `return { url: response.url }`
  returned the API endpoint URL (or undefined for non-Response shapes)
  in place of a usable video URL.

openai-base/package.json
- Drop `zod` from peerDependencies and devDependencies. Grep confirms
  no zod imports anywhere in the package; the peer dep produced a
  spurious peer-warning on every consumer.

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

Deferred bucket (b/c) follow-ups (not in this commit):
- Include tests/ in ai-utils + openai-base tsconfig.json (requires
  fixing ~20 pre-existing test-file TS issues: EventType enum literals
  vs string literals, possibly-undefined narrowing, mock typing).
- ai-fal peer-dep workspace:* → workspace:^ (pre-existing on main).
- defineModelMeta gaps (output.cached, NaN, integer context_window).
- transformNullsToUndefined runtime guard for non-plain objects.

Author: AlemTuzlak

packages/typescript/openai-base/package.json

@@ -44,13 +44,11 @@
     "openai": "^6.9.1"
   },
   "peerDependencies": {
-    "@tanstack/ai": "workspace:^",
-    "zod": "^4.0.0"
+    "@tanstack/ai": "workspace:^"
   },
   "devDependencies": {
     "@tanstack/ai": "workspace:*",
     "@vitest/coverage-v8": "4.0.14",
-    "vite": "^7.2.7",
-    "zod": "^4.2.0"
+    "vite": "^7.2.7"
   }
 }

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

@@ -278,11 +278,12 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
           lastModel = chunk.model
         }
 
-        const choice = chunk.choices[0]
-
-        if (!choice) continue
-
-        // Emit RUN_STARTED on first chunk
+        // Emit RUN_STARTED on the first chunk of any kind so callers see a
+        // run lifecycle even on streams that arrive entirely as usage-only
+        // (no choices). Without this, a usage-first stream would skip
+        // RUN_STARTED via `if (!choice) continue` below and the post-loop
+        // synthetic block would also skip RUN_FINISHED (it gates on
+        // `hasEmittedRunStarted`).
         if (!aguiState.hasEmittedRunStarted) {
           aguiState.hasEmittedRunStarted = true
           yield asChunk({
@@ -293,6 +294,10 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
           })
         }
 
+        const choice = chunk.choices[0]
+
+        if (!choice) continue
+
         const delta = choice.delta
         const deltaContent = delta.content
         const deltaToolCalls = delta.tool_calls
@@ -386,19 +391,34 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         // 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
+          // Track whether ANY tool call actually got a start event so we can
+          // distinguish "tool-using run" from "stream had partial deltas but
+          // never completed a tool call" — the latter must NOT report
+          // tool_calls and must NOT emit TOOL_CALL_END for unstarted entries.
+          let emittedAnyToolCallEnd = false
           if (
             choice.finish_reason === 'tool_calls' ||
             toolCallsInProgress.size > 0
           ) {
             for (const [, toolCall] of toolCallsInProgress) {
+              // Skip tool calls that never emitted TOOL_CALL_START — emitting
+              // a stray TOOL_CALL_END here would violate AG-UI lifecycle
+              // (END without matching START) for partial deltas where the
+              // upstream never sent both id and name.
+              if (!toolCall.started) continue
+
               // 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 {}.
+              // Non-object JSON (e.g. a bare string or number) is also coerced
+              // to {} so downstream tool execution doesn't receive a primitive
+              // input, mirroring the Responses adapter's guard.
               let parsedInput: unknown = {}
               if (toolCall.arguments) {
                 try {
-                  parsedInput = JSON.parse(toolCall.arguments)
+                  const parsed: unknown = JSON.parse(toolCall.arguments)
+                  parsedInput =
+                    parsed && typeof parsed === 'object' ? parsed : {}
                 } catch (parseError) {
                   options.logger.errors(
                     `${this.name}.processStreamChunks tool-args JSON parse failed`,
@@ -427,8 +447,14 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
                 timestamp,
                 input: parsedInput,
               })
+              emittedAnyToolCallEnd = true
             }
+            // Clear tool-call state after emission so a subsequent
+            // `finish_reason: 'stop'` chunk (or the post-loop synthetic
+            // block) doesn't see lingering entries and misreport the finish.
+            toolCallsInProgress.clear()
           }
+          void emittedAnyToolCallEnd
 
           // Emit TEXT_MESSAGE_END if we had text content
           if (hasEmittedTextMessageStart) {
@@ -453,6 +479,35 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
       // guaranteed terminal event even when the upstream cuts off mid-stream
       // (no finish_reason chunk ever arrives).
       if (aguiState.hasEmittedRunStarted) {
+        // Close any started tool calls that never got finish_reason. A
+        // truncated stream that emitted TOOL_CALL_START but never reached
+        // finish_reason would otherwise leave consumers with an unbalanced
+        // start. Skip non-started entries (no matching START to close).
+        let pendingToolCount = 0
+        for (const [, toolCall] of toolCallsInProgress) {
+          if (!toolCall.started) continue
+          let parsedInput: unknown = {}
+          if (toolCall.arguments) {
+            try {
+              const parsed: unknown = JSON.parse(toolCall.arguments)
+              parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
+            } catch {
+              parsedInput = {}
+            }
+          }
+          yield asChunk({
+            type: 'TOOL_CALL_END',
+            toolCallId: toolCall.id,
+            toolCallName: toolCall.name,
+            toolName: toolCall.name,
+            model: lastModel || options.model,
+            timestamp,
+            input: parsedInput,
+          })
+          pendingToolCount += 1
+        }
+        toolCallsInProgress.clear()
+
         // Make sure the text message lifecycle is closed even on early
         // termination paths where finish_reason never arrives.
         if (hasEmittedTextMessageStart) {
@@ -467,9 +522,12 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         // 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.
+        // run terminated — surface it instead. Use `tool_calls` only when
+        // the upstream actually said so OR when we just closed pending tool
+        // calls (truncated stream); a clean `stop` with no started tool
+        // calls must NOT be remapped to `tool_calls`.
         const finishReason: string =
-          pendingFinishReason === 'tool_calls' || toolCallsInProgress.size > 0
+          pendingFinishReason === 'tool_calls' || pendingToolCount > 0
             ? 'tool_calls'
             : (pendingFinishReason ?? 'stop')
 
@@ -602,11 +660,17 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
               : JSON.stringify(tc.function.arguments),
         },
       }))
+      const hasToolCalls = !!toolCalls && toolCalls.length > 0
+      const textContent = this.extractTextContent(message.content)
 
+      // Per the OpenAI Chat Completions contract, an assistant message that
+      // only carries tool_calls should have `content: null` (or omit content)
+      // rather than `content: ''`. Empty-string content interacts oddly with
+      // tokenization on some backends; null is the documented shape.
       return {
         role: 'assistant',
-        content: this.extractTextContent(message.content),
-        ...(toolCalls && toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+        content: hasToolCalls && !textContent ? null : textContent,
+        ...(hasToolCalls ? { tool_calls: toolCalls } : {}),
       }
     }
 
@@ -615,9 +679,20 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
 
     // If only text, use simple string format
     if (contentParts.length === 1 && contentParts[0]?.type === 'text') {
+      const text = contentParts[0].content
+      if (text.length === 0) {
+        // Single empty text part is the same fail-loud condition as below —
+        // an empty paid request mask a real intent (caller passed `null`/'',
+        // or an upstream step normalised everything to an empty string).
+        throw new Error(
+          `User message for ${this.name} has empty text content. ` +
+            `Empty user messages would produce a paid request with no input; ` +
+            `provide non-empty content or omit the message.`,
+        )
+      }
       return {
         role: 'user',
-        content: contentParts[0].content,
+        content: text,
       }
     }
 
@@ -672,11 +747,15 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         | { detail?: 'auto' | 'low' | 'high' }
         | undefined
 
-      // For base64 data, construct a data URI using the mimeType from source
+      // For base64 data, construct a data URI using the mimeType from source.
+      // Default to a generic octet-stream MIME if the source didn't provide
+      // one — interpolating `undefined` into the URI ("data:undefined;base64,
+      // ...") would produce an invalid URI the API rejects.
       const imageValue = part.source.value
+      const imageMime = part.source.mimeType || 'application/octet-stream'
       const imageUrl =
         part.source.type === 'data' && !imageValue.startsWith('data:')
-          ? `data:${part.source.mimeType};base64,${imageValue}`
+          ? `data:${imageMime};base64,${imageValue}`
           : imageValue
 
       return {

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

@@ -33,9 +33,13 @@ export function convertFunctionToolToChatCompletionsFormat(
     required: [],
   }) as JSONSchema
 
-  const jsonSchema = schemaConverter(inputSchema, inputSchema.required || [])
-
-  // Ensure additionalProperties is false for strict mode
+  // Shallow-copy the converter's result before mutating: a subclass-supplied
+  // schemaConverter has no contract requirement to return a fresh object,
+  // and a passthrough `(s) => s` would otherwise have its caller's schema
+  // mutated by the `additionalProperties = false` assignment below.
+  const jsonSchema = {
+    ...schemaConverter(inputSchema, inputSchema.required || []),
+  }
   jsonSchema.additionalProperties = false
 
   return {