@tanstack/openai-base 0.2.1 → 0.3.1

package/src/adapters/chat-completions-text.ts

@@ -1,46 +1,40 @@
+import { EventType } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { generateId, transformNullsToUndefined } from '@tanstack/ai-utils'
-import { createOpenAICompatibleClient } from '../utils/client'
 import { extractRequestOptions } from '../utils/request-options'
 import { makeStructuredOutputCompatible } from '../utils/schema-converter'
 import { convertToolsToChatCompletionsFormat } from './chat-completions-tool-converter'
+import type OpenAI from 'openai'
 import type {
   StructuredOutputOptions,
   StructuredOutputResult,
 } from '@tanstack/ai/adapters'
-import type OpenAI_SDK from 'openai'
+import type {
+  ChatCompletionChunk,
+  ChatCompletionContentPart,
+  ChatCompletionCreateParamsStreaming,
+  ChatCompletionMessageParam,
+} from 'openai/resources/chat/completions/completions'
 import type {
   ContentPart,
   DefaultMessageMetadataByModality,
   Modality,
   ModelMessage,
+  RunFinishedEvent,
   StreamChunk,
   TextOptions,
 } from '@tanstack/ai'
-import type { OpenAICompatibleClientConfig } from '../types/config'
-
-/** Cast an event object to StreamChunk. Adapters construct events with string
- *  literal types which are structurally compatible with the EventType enum. */
-const asChunk = (chunk: Record<string, unknown>) =>
-  chunk as unknown as StreamChunk
 
 /**
- * OpenAI-compatible Chat Completions Text Adapter
- *
- * A generalized base class for providers that use the OpenAI Chat Completions API
- * (`/v1/chat/completions`). Providers like Grok, Groq, OpenRouter, and others can
- * extend this class and only need to:
- * - Set `baseURL` in the config
- * - Lock the generic type parameters to provider-specific types
- * - Override specific methods for quirks
- *
- * All methods that build requests or process responses are `protected` so subclasses
- * can override them.
+ * Shared implementation of the OpenAI Chat Completions API. Holds the
+ * stream-accumulator + AG-UI lifecycle logic and calls the OpenAI SDK
+ * directly. Subclasses (ai-openai, ai-grok, ai-groq) construct an OpenAI
+ * client with their provider-specific `baseURL` / headers and pass it in.
  */
-export class OpenAICompatibleChatCompletionsTextAdapter<
+export abstract class OpenAIBaseChatCompletionsTextAdapter<
   TModel extends string,
-  TProviderOptions extends Record<string, any> = Record<string, any>,
+  TProviderOptions extends Record<string, unknown> = Record<string, unknown>,
   TInputModalities extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
   TMessageMetadata extends DefaultMessageMetadataByModality =
     DefaultMessageMetadataByModality,
@@ -54,34 +48,33 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
 > {
   readonly kind = 'text' as const
   readonly name: string
+  protected client: OpenAI
 
-  protected client: OpenAI_SDK
-
-  constructor(
-    config: OpenAICompatibleClientConfig,
-    model: TModel,
-    name: string = 'openai-compatible',
-  ) {
+  constructor(model: TModel, name: string, client: OpenAI) {
     super({}, model)
     this.name = name
-    this.client = createOpenAICompatibleClient(config)
+    this.client = client
   }
 
   async *chatStream(
     options: TextOptions<TProviderOptions>,
   ): AsyncIterable<StreamChunk> {
-    const requestParams = this.mapOptionsToRequest(options)
-    const timestamp = Date.now()
-
     // AG-UI lifecycle tracking (mutable state object for ESLint compatibility)
     const aguiState = {
       runId: generateId(this.name),
+      threadId: options.threadId ?? generateId(this.name),
       messageId: generateId(this.name),
-      timestamp,
       hasEmittedRunStarted: false,
     }
 
     try {
+      // mapOptionsToRequest can throw (e.g. fail-loud guards in convertMessage
+      // for empty content or unsupported parts). Keep it inside the try so
+      // those failures surface as a single RUN_ERROR event, matching every
+      // other failure mode here — callers iterating chatStream then only need
+      // one error-handling path instead of both a try/catch around iteration
+      // and a RUN_ERROR handler.
+      const requestParams = this.mapOptionsToRequest(options)
       options.logger.request(
         `activity=chat provider=${this.name} model=${this.model} messages=${options.messages.length} tools=${options.tools?.length ?? 0} stream=true`,
         { provider: this.name, model: this.model },
@@ -107,22 +100,25 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
       // Emit RUN_STARTED if not yet emitted
       if (!aguiState.hasEmittedRunStarted) {
         aguiState.hasEmittedRunStarted = true
-        yield asChunk({
-          type: 'RUN_STARTED',
+        yield {
+          type: EventType.RUN_STARTED,
           runId: aguiState.runId,
+          threadId: aguiState.threadId,
           model: options.model,
-          timestamp,
-        })
+          timestamp: Date.now(),
+          parentRunId: options.parentRunId,
+        }
       }
 
       // Emit AG-UI RUN_ERROR
-      yield asChunk({
-        type: 'RUN_ERROR',
-        runId: aguiState.runId,
+      yield {
+        type: EventType.RUN_ERROR,
         model: options.model,
-        timestamp,
+        timestamp: Date.now(),
+        message: errorPayload.message,
+        code: errorPayload.code,
         error: errorPayload,
-      })
+      }
 
       options.logger.errors(`${this.name}.chatStream fatal`, {
         error: errorPayload,
@@ -181,8 +177,16 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         extractRequestOptions(chatOptions.request),
       )
 
-      // Extract text content from the response
-      const rawText = response.choices[0]?.message.content || ''
+      // Extract text content from the response. Fail loud on empty content
+      // rather than letting it cascade into a JSON-parse error on '' — the
+      // root cause (the model returned no content for the structured request)
+      // is then visible in logs.
+      const rawText = response.choices[0]?.message.content
+      if (typeof rawText !== 'string' || rawText.length === 0) {
+        throw new Error(
+          `${this.name}.structuredOutput: response contained no content`,
+        )
+      }
 
       // Parse the JSON response
       let parsed: unknown
@@ -195,8 +199,10 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
       }
 
       // Transform null values to undefined to match original Zod schema expectations
-      // Provider returns null for optional fields we made nullable in the schema
-      const transformed = transformNullsToUndefined(parsed)
+      // Provider returns null for optional fields we made nullable in the schema.
+      // Subclasses can override `transformStructuredOutput` to skip this — e.g.
+      // OpenRouter historically passed nulls through unchanged.
+      const transformed = this.transformStructuredOutput(parsed)
 
       return {
         data: transformed,
@@ -213,6 +219,338 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
     }
   }
 
+  /**
+   * Stream structured output. Single Chat Completions request with
+   * `response_format: json_schema` + `stream: true`. Emits the standard
+   * AG-UI lifecycle (`RUN_STARTED` → `REASONING_*?` → `TEXT_MESSAGE_*`
+   * carrying raw JSON deltas → terminal `CUSTOM 'structured-output.complete'`
+   * → `RUN_FINISHED`). Subclasses use the same SDK-call / reasoning /
+   * structured-output-transform hooks as `chatStream` / `structuredOutput` —
+   * no per-subclass override should be needed.
+   */
+  async *structuredOutputStream(
+    options: StructuredOutputOptions<TProviderOptions>,
+  ): AsyncIterable<StreamChunk> {
+    const { chatOptions, outputSchema } = options
+    const requestParams = this.mapOptionsToRequest(chatOptions)
+
+    const jsonSchema = this.makeStructuredOutputCompatible(
+      outputSchema,
+      outputSchema.required,
+    )
+
+    const timestamp = Date.now()
+    const aguiState = {
+      runId: generateId(this.name),
+      threadId: chatOptions.threadId ?? generateId(this.name),
+      messageId: generateId(this.name),
+      timestamp,
+      hasEmittedRunStarted: false,
+    }
+
+    let accumulatedContent = ''
+    let accumulatedReasoning = ''
+    let hasEmittedTextMessageStart = false
+    let reasoningMessageId: string | undefined
+    let hasClosedReasoning = false
+    let stepId: string | undefined
+    let lastModel: string | undefined
+    let lastUsage:
+      | OpenAI.Chat.Completions.ChatCompletionChunk['usage']
+      | undefined
+
+    const closeReasoningLifecycle = function* (this: {
+      name: string
+    }): Generator<StreamChunk> {
+      if (reasoningMessageId && !hasClosedReasoning) {
+        hasClosedReasoning = true
+        yield {
+          type: EventType.REASONING_MESSAGE_END,
+          messageId: reasoningMessageId,
+          model: lastModel || chatOptions.model,
+          timestamp,
+        }
+        yield {
+          type: EventType.REASONING_END,
+          messageId: reasoningMessageId,
+          model: lastModel || chatOptions.model,
+          timestamp,
+        }
+        if (stepId) {
+          yield {
+            type: EventType.STEP_FINISHED,
+            stepName: stepId,
+            stepId,
+            model: lastModel || chatOptions.model,
+            timestamp,
+            content: accumulatedReasoning,
+          }
+        }
+      }
+    }.bind(this)
+
+    try {
+      // Strip stream_options + tools from the base request. Structured output
+      // sends `response_format: json_schema` and doesn't carry tools — keeping
+      // them in the request can confuse strict-mode validation upstream.
+      const {
+        stream_options: _so,
+        stream: _s,
+        tools: _t,
+        ...cleanParams
+      } = requestParams
+
+      chatOptions.logger.request(
+        `activity=structuredOutputStream provider=${this.name} model=${this.model} messages=${chatOptions.messages.length}`,
+        { provider: this.name, model: this.model },
+      )
+
+      const stream = await this.client.chat.completions.create(
+        {
+          ...cleanParams,
+          stream: true,
+          stream_options: { include_usage: true },
+          response_format: {
+            type: 'json_schema',
+            json_schema: {
+              name: 'structured_output',
+              schema: jsonSchema,
+              strict: true,
+            },
+          },
+        },
+        extractRequestOptions(chatOptions.request),
+      )
+
+      for await (const chunk of stream) {
+        const choiceForLog = chunk.choices[0]
+        chatOptions.logger.provider(
+          `provider=${this.name} finish_reason=${choiceForLog?.finish_reason ?? 'none'} hasContent=${!!choiceForLog?.delta.content} hasUsage=${!!chunk.usage}`,
+          { provider: this.name, model: chunk.model },
+        )
+
+        if (chunk.model) lastModel = chunk.model
+
+        // Usage may arrive on a chunk with empty `choices` (OpenAI's
+        // include_usage terminal chunk) or piggybacked on a finish chunk
+        // (`x_groq.usage` on Groq). Capture from either independent of
+        // choices[0].
+        const usage =
+          chunk.usage ??
+          (chunk as { x_groq?: { usage?: typeof chunk.usage } }).x_groq?.usage
+        if (usage) lastUsage = usage
+
+        if (!aguiState.hasEmittedRunStarted) {
+          aguiState.hasEmittedRunStarted = true
+          yield {
+            type: EventType.RUN_STARTED,
+            runId: aguiState.runId,
+            threadId: aguiState.threadId,
+            model: chunk.model || chatOptions.model,
+            timestamp,
+            parentRunId: chatOptions.parentRunId,
+          }
+        }
+
+        // Reasoning (via the extractReasoning hook — same hook as chatStream).
+        const reasoning = this.extractReasoning(chunk)
+        if (reasoning && reasoning.text) {
+          if (!reasoningMessageId) {
+            reasoningMessageId = generateId(this.name)
+            stepId = generateId(this.name)
+            yield {
+              type: EventType.REASONING_START,
+              messageId: reasoningMessageId,
+              model: chunk.model || chatOptions.model,
+              timestamp,
+            }
+            yield {
+              type: EventType.REASONING_MESSAGE_START,
+              messageId: reasoningMessageId,
+              role: 'reasoning' as const,
+              model: chunk.model || chatOptions.model,
+              timestamp,
+            }
+            yield {
+              type: EventType.STEP_STARTED,
+              stepName: stepId,
+              stepId,
+              model: chunk.model || chatOptions.model,
+              timestamp,
+              stepType: 'thinking',
+            }
+          }
+          accumulatedReasoning += reasoning.text
+          yield {
+            type: EventType.REASONING_MESSAGE_CONTENT,
+            messageId: reasoningMessageId,
+            delta: reasoning.text,
+            model: chunk.model || chatOptions.model,
+            timestamp,
+          }
+        }
+
+        const choice = chunk.choices[0]
+        if (!choice) continue
+
+        const deltaContent = choice.delta.content
+        if (deltaContent) {
+          yield* closeReasoningLifecycle()
+
+          if (!hasEmittedTextMessageStart) {
+            hasEmittedTextMessageStart = true
+            yield {
+              type: EventType.TEXT_MESSAGE_START,
+              messageId: aguiState.messageId,
+              model: chunk.model || chatOptions.model,
+              timestamp,
+              role: 'assistant',
+            }
+          }
+
+          accumulatedContent += deltaContent
+
+          yield {
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId: aguiState.messageId,
+            model: chunk.model || chatOptions.model,
+            timestamp,
+            delta: deltaContent,
+            content: accumulatedContent,
+          }
+        }
+      }
+
+      // Finalisation: close any open lifecycle, parse + validate, emit
+      // terminal events. This block always runs unless the loop threw — abort
+      // and SDK errors land in the catch block below.
+      yield* closeReasoningLifecycle()
+
+      if (hasEmittedTextMessageStart) {
+        yield {
+          type: EventType.TEXT_MESSAGE_END,
+          messageId: aguiState.messageId,
+          model: lastModel || chatOptions.model,
+          timestamp,
+        }
+      }
+
+      if (accumulatedContent.length === 0) {
+        yield {
+          type: EventType.RUN_ERROR,
+          runId: aguiState.runId,
+          model: lastModel || chatOptions.model,
+          timestamp,
+          message: `${this.name}.structuredOutputStream: response contained no content`,
+          code: 'empty-response',
+          error: {
+            message: `${this.name}.structuredOutputStream: response contained no content`,
+            code: 'empty-response',
+          },
+        }
+        return
+      }
+
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(accumulatedContent)
+      } catch {
+        yield {
+          type: EventType.RUN_ERROR,
+          runId: aguiState.runId,
+          model: lastModel || chatOptions.model,
+          timestamp,
+          message: `Failed to parse structured output as JSON. Content: ${accumulatedContent.slice(0, 200)}${accumulatedContent.length > 200 ? '...' : ''}`,
+          code: 'parse-error',
+          error: {
+            message: 'Failed to parse structured output as JSON',
+            code: 'parse-error',
+          },
+        }
+        return
+      }
+
+      const transformed = this.transformStructuredOutput(parsed)
+
+      yield {
+        type: EventType.CUSTOM,
+        name: 'structured-output.complete',
+        value: {
+          object: transformed,
+          raw: accumulatedContent,
+          ...(accumulatedReasoning ? { reasoning: accumulatedReasoning } : {}),
+        },
+        model: lastModel || chatOptions.model,
+        timestamp,
+      }
+
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: aguiState.runId,
+        threadId: aguiState.threadId,
+        model: lastModel || chatOptions.model,
+        timestamp,
+        finishReason: 'stop',
+        ...(lastUsage && {
+          usage: {
+            promptTokens: lastUsage.prompt_tokens,
+            completionTokens: lastUsage.completion_tokens,
+            totalTokens: lastUsage.total_tokens,
+          },
+        }),
+      }
+    } catch (error: unknown) {
+      if (!aguiState.hasEmittedRunStarted) {
+        aguiState.hasEmittedRunStarted = true
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: aguiState.runId,
+          threadId: aguiState.threadId,
+          model: chatOptions.model,
+          timestamp,
+          parentRunId: chatOptions.parentRunId,
+        }
+      }
+
+      const isAbort = this.isAbortError(error)
+      const errorPayload = toRunErrorPayload(
+        error,
+        `${this.name}.structuredOutputStream failed`,
+      )
+
+      yield {
+        type: EventType.RUN_ERROR,
+        runId: aguiState.runId,
+        model: lastModel || chatOptions.model,
+        timestamp,
+        message: errorPayload.message,
+        code: isAbort ? 'aborted' : errorPayload.code,
+        error: { ...errorPayload, ...(isAbort && { code: 'aborted' }) },
+      }
+
+      chatOptions.logger.errors(`${this.name}.structuredOutputStream fatal`, {
+        error: errorPayload,
+        source: `${this.name}.structuredOutputStream`,
+      })
+    }
+  }
+
+  /**
+   * Cross-SDK abort detection for `structuredOutputStream`. Default duck-types
+   * on `name === 'APIUserAbortError'` (OpenAI SDK), `code === 'ERR_CANCELED'`,
+   * and standard `AbortError`s. Subclasses with proprietary error types (e.g.
+   * `@openrouter/sdk`'s `RequestAbortedError`) override to extend the check.
+   */
+  protected isAbortError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false
+    const e = error as { name?: unknown; code?: unknown }
+    return (
+      e.name === 'APIUserAbortError' ||
+      e.name === 'AbortError' ||
+      e.code === 'ERR_CANCELED'
+    )
+  }
+
   /**
    * Applies provider-specific transformations for structured output compatibility.
    * Override this in subclasses to handle provider-specific quirks.
@@ -224,22 +562,43 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
     return makeStructuredOutputCompatible(schema, originalRequired)
   }
 
+  /**
+   * Extract reasoning content from a stream chunk. Default returns
+   * `undefined` because the OpenAI Chat Completions chunk shape doesn't
+   * carry reasoning. The chunk param is typed `unknown` so an override can
+   * narrow to its own SDK chunk type without an `as` dance — the base only
+   * passes through `processStreamChunks`'s structurally-iterated chunk.
+   */
+  protected extractReasoning(_chunk: unknown): { text: string } | undefined {
+    return undefined
+  }
+
+  /**
+   * Final shaping pass applied to parsed structured-output JSON before it is
+   * returned to the caller. Default converts `null` values to `undefined` so
+   * the result aligns with the original Zod schema's optional-field
+   * semantics. Subclasses with different conventions (OpenRouter historically
+   * preserves nulls) can override.
+   */
+  protected transformStructuredOutput(parsed: unknown): unknown {
+    return transformNullsToUndefined(parsed)
+  }
+
   /**
    * Processes streamed chunks from the Chat Completions API and yields AG-UI events.
    * Override this in subclasses to handle provider-specific stream behavior.
    */
   protected async *processStreamChunks(
-    stream: AsyncIterable<OpenAI_SDK.Chat.Completions.ChatCompletionChunk>,
+    stream: AsyncIterable<ChatCompletionChunk>,
     options: TextOptions,
     aguiState: {
       runId: string
+      threadId: string
       messageId: string
-      timestamp: number
       hasEmittedRunStarted: boolean
     },
   ): AsyncIterable<StreamChunk> {
     let accumulatedContent = ''
-    const timestamp = aguiState.timestamp
     let hasEmittedTextMessageStart = false
     let lastModel: string | undefined
     // Track usage from any chunk that carries it. With
@@ -248,11 +607,9 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
     // 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 lastUsage: ChatCompletionChunk['usage'] | undefined
     let pendingFinishReason:
-      | OpenAI_SDK.Chat.Completions.ChatCompletionChunk.Choice['finish_reason']
+      | ChatCompletionChunk['choices'][number]['finish_reason']
       | undefined
 
     // Track tool calls being streamed (arguments come in chunks)
@@ -265,6 +622,17 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         started: boolean // Track if TOOL_CALL_START has been emitted
       }
     >()
+
+    // Reasoning lifecycle (driven by extractReasoning() hook — see method
+    // docs). The base wire format (OpenAI Chat Completions) has no reasoning,
+    // so these stay unused for openai/grok/groq. OpenRouter etc. opt in.
+    let reasoningMessageId: string | undefined
+    let hasClosedReasoning = false
+    // Legacy STEP_STARTED/STEP_FINISHED pair emitted alongside REASONING_*
+    // for back-compat with consumers (UI, devtools) that haven't migrated
+    // to the spec REASONING_* events yet.
+    let stepId: string | undefined
+    let accumulatedReasoning = ''
     // Track whether ANY tool call lifecycle was actually completed across the
     // entire stream. Lets us downgrade a `tool_calls` finish_reason to `stop`
     // when the upstream signalled tool calls but never produced a complete
@@ -298,12 +666,57 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         // `hasEmittedRunStarted`).
         if (!aguiState.hasEmittedRunStarted) {
           aguiState.hasEmittedRunStarted = true
-          yield asChunk({
-            type: 'RUN_STARTED',
+          yield {
+            type: EventType.RUN_STARTED,
             runId: aguiState.runId,
+            threadId: aguiState.threadId,
             model: chunk.model || options.model,
-            timestamp,
-          })
+            timestamp: Date.now(),
+            parentRunId: options.parentRunId,
+          }
+        }
+
+        // Reasoning content (extractReasoning() hook). Run before reading
+        // choice/delta so reasoning-only chunks (no `choices`) still drive
+        // the REASONING_* lifecycle on providers that send reasoning out of
+        // band. The base default returns undefined.
+        const reasoning = this.extractReasoning(chunk)
+        if (reasoning && reasoning.text) {
+          if (!reasoningMessageId) {
+            reasoningMessageId = generateId(this.name)
+            stepId = generateId(this.name)
+            yield {
+              type: EventType.REASONING_START,
+              messageId: reasoningMessageId,
+              model: chunk.model || options.model,
+              timestamp: Date.now(),
+            }
+            yield {
+              type: EventType.REASONING_MESSAGE_START,
+              messageId: reasoningMessageId,
+              role: 'reasoning' as const,
+              model: chunk.model || options.model,
+              timestamp: Date.now(),
+            }
+            // Legacy STEP_STARTED (single emission, paired with the
+            // STEP_FINISHED below when reasoning closes).
+            yield {
+              type: EventType.STEP_STARTED,
+              stepName: stepId,
+              stepId,
+              model: chunk.model || options.model,
+              timestamp: Date.now(),
+              stepType: 'thinking',
+            }
+          }
+          accumulatedReasoning += reasoning.text
+          yield {
+            type: EventType.REASONING_MESSAGE_CONTENT,
+            messageId: reasoningMessageId,
+            delta: reasoning.text,
+            model: chunk.model || options.model,
+            timestamp: Date.now(),
+          }
         }
 
         const choice = chunk.choices[0]
@@ -316,29 +729,57 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
 
         // Handle content delta
         if (deltaContent) {
+          // Close reasoning before text starts so consumers see a clean
+          // REASONING_END before any TEXT_MESSAGE_START.
+          if (reasoningMessageId && !hasClosedReasoning) {
+            hasClosedReasoning = true
+            yield {
+              type: EventType.REASONING_MESSAGE_END,
+              messageId: reasoningMessageId,
+              model: chunk.model || options.model,
+              timestamp: Date.now(),
+            }
+            yield {
+              type: EventType.REASONING_END,
+              messageId: reasoningMessageId,
+              model: chunk.model || options.model,
+              timestamp: Date.now(),
+            }
+            if (stepId) {
+              yield {
+                type: EventType.STEP_FINISHED,
+                stepName: stepId,
+                stepId,
+                model: chunk.model || options.model,
+                timestamp: Date.now(),
+                content: accumulatedReasoning,
+              }
+            }
+          }
+
           // Emit TEXT_MESSAGE_START on first text content
           if (!hasEmittedTextMessageStart) {
             hasEmittedTextMessageStart = true
-            yield asChunk({
-              type: 'TEXT_MESSAGE_START',
+            yield {
+              type: EventType.TEXT_MESSAGE_START,
               messageId: aguiState.messageId,
               model: chunk.model || options.model,
-              timestamp,
+              timestamp: Date.now(),
               role: 'assistant',
-            })
+            }
           }
 
           accumulatedContent += deltaContent
 
           // Emit AG-UI TEXT_MESSAGE_CONTENT
-          yield asChunk({
-            type: 'TEXT_MESSAGE_CONTENT',
+          yield {
+            type: EventType.TEXT_MESSAGE_CONTENT,
             messageId: aguiState.messageId,
             model: chunk.model || options.model,
-            timestamp,
+            timestamp: Date.now(),
             delta: deltaContent,
             content: accumulatedContent,
-          })
+          }
         }
 
         // Handle tool calls - they come in as deltas
@@ -372,26 +813,26 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
             // Emit TOOL_CALL_START when we have id and name
             if (toolCall.id && toolCall.name && !toolCall.started) {
               toolCall.started = true
-              yield asChunk({
-                type: 'TOOL_CALL_START',
+              yield {
+                type: EventType.TOOL_CALL_START,
                 toolCallId: toolCall.id,
                 toolCallName: toolCall.name,
                 toolName: toolCall.name,
                 model: chunk.model || options.model,
-                timestamp,
+                timestamp: Date.now(),
                 index,
-              })
+              }
             }
 
             // Emit TOOL_CALL_ARGS for argument deltas
             if (toolCallDelta.function?.arguments && toolCall.started) {
-              yield asChunk({
-                type: 'TOOL_CALL_ARGS',
+              yield {
+                type: EventType.TOOL_CALL_ARGS,
                 toolCallId: toolCall.id,
                 model: chunk.model || options.model,
-                timestamp,
+                timestamp: Date.now(),
                 delta: toolCallDelta.function.arguments,
-              })
+              }
             }
           }
         }
@@ -445,15 +886,15 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
               }
 
               // Emit AG-UI TOOL_CALL_END
-              yield asChunk({
-                type: 'TOOL_CALL_END',
+              yield {
+                type: EventType.TOOL_CALL_END,
                 toolCallId: toolCall.id,
                 toolCallName: toolCall.name,
                 toolName: toolCall.name,
                 model: chunk.model || options.model,
-                timestamp,
+                timestamp: Date.now(),
                 input: parsedInput,
-              })
+              }
               emittedAnyToolCallEnd = true
             }
             // Clear tool-call state after emission so a subsequent
@@ -464,12 +905,12 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
 
           // Emit TEXT_MESSAGE_END if we had text content
           if (hasEmittedTextMessageStart) {
-            yield asChunk({
-              type: 'TEXT_MESSAGE_END',
+            yield {
+              type: EventType.TEXT_MESSAGE_END,
               messageId: aguiState.messageId,
               model: chunk.model || options.model,
-              timestamp,
-            })
+              timestamp: Date.now(),
+            }
             hasEmittedTextMessageStart = false
           }
 
@@ -497,19 +938,36 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
             try {
               const parsed: unknown = JSON.parse(toolCall.arguments)
               parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
-            } catch {
+            } catch (parseError) {
+              // Mirror the finish_reason path's logger call — a truncated
+              // stream emitting malformed tool-call JSON would otherwise
+              // silently invoke the tool with `{}`, the exact failure the
+              // finish_reason logger was added to prevent.
+              options.logger.errors(
+                `${this.name}.processStreamChunks tool-args JSON parse failed (drain)`,
+                {
+                  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 = {}
             }
           }
-          yield asChunk({
-            type: 'TOOL_CALL_END',
+          yield {
+            type: EventType.TOOL_CALL_END,
             toolCallId: toolCall.id,
             toolCallName: toolCall.name,
             toolName: toolCall.name,
             model: lastModel || options.model,
-            timestamp,
+            timestamp: Date.now(),
             input: parsedInput,
-          })
+          }
           pendingToolCount += 1
           emittedAnyToolCallEnd = true
         }
@@ -518,33 +976,66 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
         // 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',
+          yield {
+            type: EventType.TEXT_MESSAGE_END,
             messageId: aguiState.messageId,
             model: lastModel || options.model,
-            timestamp,
-          })
+            timestamp: Date.now(),
+          }
         }
 
-        // Map upstream finish_reason to AG-UI's narrower vocabulary while
-        // preserving the upstream value when it falls outside the AG-UI set.
+        // Close any reasoning lifecycle that text never closed (no text
+        // content arrived, or the stream cut off before text started).
+        if (reasoningMessageId && !hasClosedReasoning) {
+          hasClosedReasoning = true
+          yield {
+            type: EventType.REASONING_MESSAGE_END,
+            messageId: reasoningMessageId,
+            model: lastModel || options.model,
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.REASONING_END,
+            messageId: reasoningMessageId,
+            model: lastModel || options.model,
+            timestamp: Date.now(),
+          }
+          if (stepId) {
+            yield {
+              type: EventType.STEP_FINISHED,
+              stepName: stepId,
+              stepId,
+              model: lastModel || options.model,
+              timestamp: Date.now(),
+              content: accumulatedReasoning,
+            }
+          }
+        }
+
+        // Map upstream finish_reason to AG-UI's narrower vocabulary.
         // Collapsing length / content_filter to 'stop' would hide why the
         // run terminated — surface it instead. Use `tool_calls` only when
         // a TOOL_CALL_END was actually emitted: an upstream that signalled
         // `tool_calls` but never produced a started/ended pair must NOT
         // surface `tool_calls` here, since downstream consumers wait for
-        // tool results that would never arrive.
-        const finishReason: string = emittedAnyToolCallEnd
-          ? 'tool_calls'
-          : pendingFinishReason === 'tool_calls'
-            ? 'stop'
-            : (pendingFinishReason ?? 'stop')
-
-        yield asChunk({
-          type: 'RUN_FINISHED',
+        // tool results that would never arrive. OpenAI's legacy
+        // `function_call` value (from the v1 function-calling API) is
+        // normalized to `tool_calls` — semantically the same termination.
+        const finishReason: NonNullable<RunFinishedEvent['finishReason']> =
+          emittedAnyToolCallEnd
+            ? 'tool_calls'
+            : pendingFinishReason === 'tool_calls'
+              ? 'stop'
+              : pendingFinishReason === 'function_call'
+                ? 'tool_calls'
+                : (pendingFinishReason ?? 'stop')
+
+        yield {
+          type: EventType.RUN_FINISHED,
           runId: aguiState.runId,
+          threadId: aguiState.threadId,
           model: lastModel || options.model,
-          timestamp,
+          timestamp: Date.now(),
           usage: lastUsage
             ? {
                 promptTokens: lastUsage.prompt_tokens || 0,
@@ -553,7 +1044,7 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
               }
             : undefined,
           finishReason,
-        })
+        }
       }
     } catch (error: unknown) {
       // Narrow before logging: raw SDK errors can carry request metadata
@@ -568,13 +1059,14 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
       })
 
       // Emit AG-UI RUN_ERROR
-      yield asChunk({
-        type: 'RUN_ERROR',
-        runId: aguiState.runId,
+      yield {
+        type: EventType.RUN_ERROR,
         model: options.model,
-        timestamp,
+        timestamp: Date.now(),
+        message: errorPayload.message,
+        code: errorPayload.code,
         error: errorPayload,
-      })
+      }
     }
   }
 
@@ -584,7 +1076,7 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
    */
   protected mapOptionsToRequest(
     options: TextOptions,
-  ): OpenAI_SDK.Chat.Completions.ChatCompletionCreateParamsStreaming {
+  ): ChatCompletionCreateParamsStreaming {
     const tools = options.tools
       ? convertToolsToChatCompletionsFormat(
           options.tools,
@@ -593,8 +1085,7 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
       : undefined
 
     // Build messages array with system prompts
-    const messages: Array<OpenAI_SDK.Chat.Completions.ChatCompletionMessageParam> =
-      []
+    const messages: Array<ChatCompletionMessageParam> = []
 
     // Add system prompts first
     if (options.systemPrompts && options.systemPrompts.length > 0) {
@@ -641,9 +1132,7 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
    * Converts a single ModelMessage to the Chat Completions API message format.
    * Override this in subclasses to handle provider-specific message formats.
    */
-  protected convertMessage(
-    message: ModelMessage,
-  ): OpenAI_SDK.Chat.Completions.ChatCompletionMessageParam {
+  protected convertMessage(message: ModelMessage): ChatCompletionMessageParam {
     // Handle tool messages
     if (message.role === 'tool') {
       return {
@@ -709,8 +1198,7 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
     // content parts rather than silently dropping them — a message of all
     // unsupported parts would otherwise turn into an empty user prompt and
     // mask a real capability mismatch.
-    const parts: Array<OpenAI_SDK.Chat.Completions.ChatCompletionContentPart> =
-      []
+    const parts: Array<ChatCompletionContentPart> = []
     for (const part of contentParts) {
       const converted = this.convertContentPart(part)
       if (!converted) {
@@ -746,7 +1234,7 @@ export class OpenAICompatibleChatCompletionsTextAdapter<
    */
   protected convertContentPart(
     part: ContentPart,
-  ): OpenAI_SDK.Chat.Completions.ChatCompletionContentPart | null {
+  ): ChatCompletionContentPart | null {
     if (part.type === 'text') {
       return { type: 'text', text: part.content }
     }