@tanstack/ai-bedrock 0.0.1

package/src/adapters/text.ts

@@ -0,0 +1,97 @@
+import OpenAI from 'openai'
+import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import { withBedrockDefaults } from '../utils/client'
+import type { Modality } from '@tanstack/ai'
+import type { BedrockClientConfig } from '../utils/client'
+import type { BedrockMessageMetadataByModality } from '../message-types'
+import type {
+  BedrockChatModelToolCapabilitiesByName,
+  BedrockChatModels,
+  ResolveInputModalities,
+  ResolveProviderOptions,
+} from '../model-meta'
+
+export interface BedrockTextConfig extends BedrockClientConfig {}
+
+export type { ExternalTextProviderOptions as BedrockTextProviderOptions } from '../text/text-provider-options'
+
+type ResolveToolCapabilities<TModel extends string> =
+  TModel extends keyof BedrockChatModelToolCapabilitiesByName
+    ? NonNullable<BedrockChatModelToolCapabilitiesByName[TModel]>
+    : readonly []
+
+/**
+ * Bedrock Chat Completions adapter. Drives Bedrock's OpenAI-compatible
+ * `/chat/completions` endpoint via the OpenAI SDK with a baseURL override
+ * (same pattern as ai-groq). Tool conversion, streaming, structured output,
+ * and the agent loop come from the base.
+ */
+export class BedrockTextAdapter<
+  TModel extends BedrockChatModels,
+  // Constraint mirrors ai-groq and the base, which parameterises
+  // `TProviderOptions extends Record<string, any>`. Our default
+  // `ResolveProviderOptions<TModel>` resolves to the `BedrockTextProviderOptions`
+  // interface, which (lacking an implicit index signature) `Record<string,
+  // unknown>` would reject but `Record<string, any>` accepts. This `any` is
+  // confined to the generic constraint (the established ai-groq pattern) — no
+  // value/shape `as` cast is introduced.
+  TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
+  TInputModalities extends ReadonlyArray<Modality> =
+    ResolveInputModalities<TModel>,
+  TToolCapabilities extends ReadonlyArray<string> =
+    ResolveToolCapabilities<TModel>,
+> extends OpenAIBaseChatCompletionsTextAdapter<
+  TModel,
+  TProviderOptions,
+  TInputModalities,
+  BedrockMessageMetadataByModality,
+  TToolCapabilities
+> {
+  override readonly kind = 'text' as const
+  override readonly name = 'bedrock' as const
+
+  constructor(config: BedrockTextConfig, model: TModel) {
+    // No `forced` -> honors config.endpoint ('runtime' default, 'mantle' allowed).
+    super(model, 'bedrock', new OpenAI(withBedrockDefaults(config)))
+  }
+
+  /**
+   * Surface reasoning deltas (gpt-oss / Claude reasoning) the OpenAI-compatible
+   * way. Base types the chunk as `unknown`; narrow with runtime guards — no
+   * `as` casts, no `any`.
+   */
+  protected override extractReasoning(
+    chunk: unknown,
+  ): { text: string } | undefined {
+    return readDeltaReasoning(chunk)
+  }
+}
+
+/** Cast-free narrowing of a Chat Completions chunk's reasoning delta. */
+function readDeltaReasoning(chunk: unknown): { text: string } | undefined {
+  if (typeof chunk !== 'object' || chunk === null || !('choices' in chunk))
+    return undefined
+  if (!Array.isArray(chunk.choices)) return undefined
+  const choice: unknown = chunk.choices[0]
+  if (typeof choice !== 'object' || choice === null || !('delta' in choice))
+    return undefined
+  const delta = choice.delta
+  if (typeof delta !== 'object' || delta === null) return undefined
+  const raw =
+    'reasoning' in delta && typeof delta.reasoning === 'string'
+      ? delta.reasoning
+      : 'reasoning_content' in delta &&
+          typeof delta.reasoning_content === 'string'
+        ? delta.reasoning_content
+        : undefined
+  return raw && raw.length > 0 ? { text: raw } : undefined
+}
+
+/** Chat adapter with an explicit API key (low-level; the public branching factory delegates here). */
+export function createBedrockChat<TModel extends BedrockChatModels>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<BedrockTextConfig, 'apiKey'>,
+): BedrockTextAdapter<TModel> {
+  return new BedrockTextAdapter({ ...config, apiKey }, model)
+}

package/src/converse/message-converter.ts

@@ -0,0 +1,268 @@
+import { normalizeSystemPrompts } from '@tanstack/ai'
+import type {
+  ContentPart,
+  ContentPartDataSource,
+  DocumentPart,
+  ImagePart,
+  ModelMessage,
+  SystemPrompt,
+  TextPart,
+} from '@tanstack/ai'
+import type {
+  ContentBlock,
+  Message,
+  SystemContentBlock,
+  ToolResultContentBlock,
+} from '@aws-sdk/client-bedrock-runtime'
+import type { DocumentType } from '@smithy/types'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function base64ToBytes(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, 'base64'))
+}
+
+function imageFormat(mime: string): 'png' | 'jpeg' | 'gif' | 'webp' {
+  switch (mime) {
+    case 'image/png':
+      return 'png'
+    case 'image/jpeg':
+    case 'image/jpg':
+      return 'jpeg'
+    case 'image/gif':
+      return 'gif'
+    case 'image/webp':
+      return 'webp'
+    default:
+      throw new Error(
+        `Bedrock Converse: unsupported image MIME type "${mime}". Supported types: image/png, image/jpeg, image/gif, image/webp.`,
+      )
+  }
+}
+
+function documentFormat(
+  mime: string,
+): 'pdf' | 'csv' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'html' | 'txt' | 'md' {
+  switch (mime) {
+    case 'application/pdf':
+      return 'pdf'
+    case 'text/csv':
+      return 'csv'
+    case 'application/msword':
+      return 'doc'
+    case 'application/vnd.openxmlformats-officedocument.wordprocessingml.document':
+      return 'docx'
+    case 'application/vnd.ms-excel':
+      return 'xls'
+    case 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
+      return 'xlsx'
+    case 'text/html':
+      return 'html'
+    case 'text/plain':
+      return 'txt'
+    case 'text/markdown':
+    case 'text/x-markdown':
+      return 'md'
+    default:
+      throw new Error(
+        `Bedrock Converse: unsupported document MIME type "${mime}". Supported types: pdf, csv, doc, docx, xls, xlsx, html, txt, md.`,
+      )
+  }
+}
+
+function stringContent(content: string | null | Array<ContentPart>): string {
+  if (content === null) return ''
+  if (typeof content === 'string') return content
+  return content
+    .filter((p): p is TextPart => p.type === 'text')
+    .map((p) => p.content)
+    .join('')
+}
+
+function isTextPart(p: ContentPart): p is TextPart {
+  return p.type === 'text'
+}
+
+function isImagePart(p: ContentPart): p is ImagePart {
+  return p.type === 'image'
+}
+
+function isDocumentPart(p: ContentPart): p is DocumentPart {
+  return p.type === 'document'
+}
+
+function isDataSource(
+  source: ImagePart['source'] | DocumentPart['source'],
+): source is ContentPartDataSource {
+  return source.type === 'data'
+}
+
+function contentPartToBlock(part: ContentPart, docIndex: number): ContentBlock {
+  if (isTextPart(part)) {
+    return { text: part.content }
+  }
+
+  if (isImagePart(part)) {
+    const { source } = part
+    if (!isDataSource(source)) {
+      throw new Error(
+        'Bedrock Converse requires inline image bytes; URL image sources are not supported.',
+      )
+    }
+    return {
+      image: {
+        format: imageFormat(source.mimeType),
+        source: { bytes: base64ToBytes(source.value) },
+      },
+    }
+  }
+
+  if (isDocumentPart(part)) {
+    const { source } = part
+    if (!isDataSource(source)) {
+      throw new Error(
+        'Bedrock Converse requires inline document bytes; URL document sources are not supported.',
+      )
+    }
+    return {
+      document: {
+        format: documentFormat(source.mimeType),
+        name: `document-${docIndex}`,
+        source: { bytes: base64ToBytes(source.value) },
+      },
+    }
+  }
+
+  // Fail loud for unsupported part types (audio, video, etc.)
+  throw new Error(
+    `Bedrock Converse does not support content part type "${String(part.type)}".`,
+  )
+}
+
+function messageToBlocks(
+  msg: ModelMessage,
+  docCounter: { value: number },
+): Array<ContentBlock> {
+  const blocks: Array<ContentBlock> = []
+
+  if (msg.role === 'tool') {
+    if (!msg.toolCallId) {
+      throw new Error(
+        'Bedrock Converse: tool message is missing toolCallId. Every tool result must reference the tool use ID it is responding to.',
+      )
+    }
+    const textContent = stringContent(msg.content)
+    const toolResult: ToolResultContentBlock = { text: textContent }
+    blocks.push({
+      toolResult: {
+        toolUseId: msg.toolCallId,
+        content: [toolResult],
+        status: 'success',
+      },
+    })
+    return blocks
+  }
+
+  // Map content field to text/image/document blocks
+  if (typeof msg.content === 'string') {
+    if (msg.content !== '') {
+      blocks.push({ text: msg.content })
+    }
+  } else if (Array.isArray(msg.content)) {
+    for (const part of msg.content) {
+      const docIndex = isDocumentPart(part) ? ++docCounter.value : 0
+      blocks.push(contentPartToBlock(part, docIndex))
+    }
+  }
+  // null → no text blocks
+
+  // Append toolUse blocks for assistant tool calls. Malformed or non-object
+  // arguments come from a prior assistant turn the engine already accepted, so
+  // they signal a real upstream problem — throw rather than silently coercing to
+  // `{}` and forwarding a corrupted tool call (the adapter's catch surfaces it
+  // as a RUN_ERROR).
+  if (msg.role === 'assistant' && msg.toolCalls) {
+    for (const call of msg.toolCalls) {
+      const rawArguments = call.function.arguments || '{}'
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(rawArguments)
+      } catch (error: unknown) {
+        throw new Error(
+          `Bedrock Converse: tool call "${call.function.name}" has malformed JSON arguments (${String(error)}). Raw: ${rawArguments}`,
+        )
+      }
+      if (
+        parsed === null ||
+        typeof parsed !== 'object' ||
+        Array.isArray(parsed)
+      ) {
+        throw new Error(
+          `Bedrock Converse: tool call "${call.function.name}" arguments must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}.`,
+        )
+      }
+      blocks.push({
+        toolUse: {
+          toolUseId: call.id,
+          name: call.function.name,
+          input: parsed as DocumentType,
+        },
+      })
+    }
+  }
+
+  return blocks
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert TanStack AI messages + system prompts into the Converse API format.
+ *
+ * - System prompts are lifted into `SystemContentBlock[]`.
+ * - `tool` role messages are remapped to `user` role `toolResult` blocks.
+ * - Consecutive messages with the same Converse role are merged (Converse
+ *   requires strict user/assistant alternation).
+ */
+export function toConverseMessages(
+  messages: Array<ModelMessage>,
+  systemPrompts?: Array<SystemPrompt>,
+): { system: Array<SystemContentBlock>; messages: Array<Message> } {
+  // Build system blocks (uses normalizeSystemPrompts for runtime validation)
+  const system: Array<SystemContentBlock> = normalizeSystemPrompts(
+    systemPrompts,
+  ).map((p) => ({ text: p.content }))
+
+  // Convert each ModelMessage to a Converse Message, merging same-role pairs
+  const converseMessages: Array<Message> = []
+  // Global document counter: ensures every document block across all messages
+  // gets a unique name, preventing Bedrock ValidationException for duplicate names.
+  const docCounter = { value: 0 }
+
+  for (const msg of messages) {
+    // Map TanStack roles to Converse roles
+    const converseRole: 'user' | 'assistant' =
+      msg.role === 'assistant' ? 'assistant' : 'user'
+
+    const blocks = messageToBlocks(msg, docCounter)
+
+    // Skip messages that produce no content blocks (e.g. assistant with
+    // null content and no toolCalls). Pushing an empty-content message to
+    // Converse triggers a ValidationException.
+    if (blocks.length === 0) continue
+
+    const last = converseMessages[converseMessages.length - 1]
+    if (last && last.role === converseRole) {
+      // Merge into the previous message's content array
+      last.content = [...(last.content ?? []), ...blocks]
+    } else {
+      converseMessages.push({ role: converseRole, content: blocks })
+    }
+  }
+
+  return { system, messages: converseMessages }
+}

package/src/converse/provider-options.ts

@@ -0,0 +1,19 @@
+/**
+ * Provider options honored by the Bedrock **Converse** path. Deliberately
+ * narrower than the OpenAI-compatible `BedrockTextProviderOptions`: the Converse
+ * API only accepts these sampling knobs (mapped into `inferenceConfig`), so
+ * advertising the full Chat Completions option set would promise fields —
+ * `frequency_penalty`, `seed`, `logit_bias`, `tool_choice`, `reasoning_effort`,
+ * etc. — that Converse silently ignores. Field names mirror the Chat
+ * Completions shape so callers have one mental model across the three APIs.
+ */
+export interface BedrockConverseProviderOptions {
+  /** Forwarded to Converse `inferenceConfig.temperature`. */
+  temperature?: number | null
+  /** Forwarded to Converse `inferenceConfig.topP`. */
+  top_p?: number | null
+  /** Forwarded to Converse `inferenceConfig.maxTokens`. */
+  max_completion_tokens?: number | null
+  /** Forwarded to Converse `inferenceConfig.stopSequences`. */
+  stop?: string | Array<string> | null
+}

package/src/converse/stream-processor.ts

@@ -0,0 +1,309 @@
+import { EventType } from '@tanstack/ai'
+import type { RunFinishedEvent, StreamChunk } from '@tanstack/ai'
+import type { ConverseStreamOutput } from '@aws-sdk/client-bedrock-runtime'
+
+/**
+ * Converse delivers server-side failures — throttling, request validation,
+ * mid-stream model faults, and service-unavailable — as in-band stream events
+ * rather than thrown exceptions. If they were ignored the iterator would simply
+ * end and the run would look like a clean, truncated success. Throw the
+ * underlying exception (these SDK members extend `Error`) so the adapter's
+ * `chatStream` / `structuredOutputStream` catch converts it into a `RUN_ERROR`.
+ */
+export function throwIfConverseStreamError(ev: ConverseStreamOutput): void {
+  if ('internalServerException' in ev && ev.internalServerException) {
+    throw ev.internalServerException
+  }
+  if ('modelStreamErrorException' in ev && ev.modelStreamErrorException) {
+    throw ev.modelStreamErrorException
+  }
+  if ('validationException' in ev && ev.validationException) {
+    throw ev.validationException
+  }
+  if ('throttlingException' in ev && ev.throttlingException) {
+    throw ev.throttlingException
+  }
+  if ('serviceUnavailableException' in ev && ev.serviceUnavailableException) {
+    throw ev.serviceUnavailableException
+  }
+}
+
+/**
+ * Maps a Bedrock Converse `ConverseStreamOutput` event stream to the TanStack
+ * AG-UI `StreamChunk` lifecycle, following `openai-base`'s `processStreamChunks`
+ * lifecycle shape so the activity layer / agent loop behave identically across
+ * providers. (Reasoning surfaces only the message-level events —
+ * `REASONING_MESSAGE_START/CONTENT/END` — which is all the core accumulator
+ * consumes; the `REASONING_START`/`REASONING_END`/`STEP_*` boundary events
+ * openai-base also emits are no-ops in the engine and are not reproduced here.)
+ *
+ * Lifecycle ownership matches openai-base: this processor emits the full
+ * success-path lifecycle itself — `RUN_STARTED` lazily before the first event,
+ * `TEXT_MESSAGE_*` / `TOOL_CALL_*` / `REASONING_MESSAGE_*` for content, and a
+ * single terminal `RUN_FINISHED` once the iterator is exhausted (so the trailing
+ * `metadata` usage event is folded into the finish event regardless of arrival
+ * order). The calling adapter only owns the catch/`RUN_ERROR` path — so any
+ * in-band Converse error event (see `throwIfConverseStreamError`) is thrown to
+ * surface there rather than ending the stream as a clean truncated success.
+ *
+ * Converse streams tool-call arguments as partial-JSON string fragments inside
+ * `contentBlockDelta.delta.toolUse.input`; each fragment is emitted as a
+ * `TOOL_CALL_ARGS` `delta`, mirroring OpenAI's `function.arguments` deltas.
+ *
+ * @param stream - The Converse event stream from `ConverseStreamCommand`.
+ * @param newMessageId - Factory for fresh ids — run, thread, message, and
+ *   tool-call ids (the adapter passes `() => this.generateId()`).
+ * @param lifecycle - Incoming run lifecycle ids, threaded onto the emitted
+ *   `RUN_STARTED`/`RUN_FINISHED` so the chat path matches every sibling adapter
+ *   (openai-base reuses `options.threadId`/`parentRunId`). Defaults preserve the
+ *   previous behaviour (fresh `threadId`, no `parentRunId`).
+ */
+export async function* processConverseStream(
+  stream: AsyncIterable<ConverseStreamOutput>,
+  newMessageId: () => string,
+  lifecycle: { threadId?: string; parentRunId?: string; model?: string } = {},
+): AsyncIterable<StreamChunk> {
+  const runId = newMessageId()
+  const threadId = lifecycle.threadId ?? newMessageId()
+  const { parentRunId, model } = lifecycle
+  const messageId = newMessageId()
+
+  let hasEmittedRunStarted = false
+
+  // Text lifecycle
+  let accumulatedContent = ''
+  let hasEmittedTextMessageStart = false
+
+  // Reasoning lifecycle
+  let reasoningMessageId: string | undefined
+  let hasClosedReasoning = false
+
+  // Tool-call lifecycle, keyed by Converse contentBlockIndex. Converse opens a
+  // tool-use block with `contentBlockStart`, streams arg fragments via
+  // `contentBlockDelta`, and closes it with `contentBlockStop`.
+  const toolCallsByIndex = new Map<
+    number,
+    { id: string; name: string; started: boolean }
+  >()
+
+  // Usage + finish-reason are captured during iteration and folded into the
+  // single terminal RUN_FINISHED, matching openai-base's deferred-finish
+  // contract (usage may arrive after the finish signal).
+  let usage:
+    | { promptTokens: number; completionTokens: number; totalTokens: number }
+    | undefined
+  let finishReason: NonNullable<RunFinishedEvent['finishReason']> | undefined
+
+  // Lazily emit RUN_STARTED exactly once, before the first content event.
+  function* ensureRunStarted(): Generator<StreamChunk> {
+    if (hasEmittedRunStarted) return
+    hasEmittedRunStarted = true
+    yield {
+      type: EventType.RUN_STARTED,
+      runId,
+      threadId,
+      parentRunId,
+      ...(model && { model }),
+      timestamp: Date.now(),
+    }
+  }
+
+  // Close an open reasoning message before text/tool content begins, mirroring
+  // openai-base which always emits REASONING_MESSAGE_END before TEXT_MESSAGE_START.
+  function* closeReasoning(): Generator<StreamChunk> {
+    if (reasoningMessageId && !hasClosedReasoning) {
+      hasClosedReasoning = true
+      yield {
+        type: EventType.REASONING_MESSAGE_END,
+        messageId: reasoningMessageId,
+        timestamp: Date.now(),
+      }
+    }
+  }
+
+  for await (const ev of stream) {
+    yield* ensureRunStarted()
+
+    // Surface in-band server/throttle/validation errors instead of dropping them.
+    throwIfConverseStreamError(ev)
+
+    // messageStart carries only the role; no AG-UI event maps to it.
+    if ('messageStart' in ev) continue
+
+    if ('contentBlockStart' in ev) {
+      const start = ev.contentBlockStart
+      const toolUse = start?.start?.toolUse
+      if (start && toolUse) {
+        yield* closeReasoning()
+        const id = toolUse.toolUseId ?? newMessageId()
+        const name = toolUse.name ?? ''
+        const index = start.contentBlockIndex ?? 0
+        toolCallsByIndex.set(index, {
+          id,
+          name,
+          started: true,
+        })
+        yield {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: id,
+          toolCallName: name,
+          toolName: name,
+          timestamp: Date.now(),
+          index,
+        }
+      }
+      continue
+    }
+
+    if ('contentBlockDelta' in ev) {
+      const block = ev.contentBlockDelta
+      const delta = block?.delta
+      const index = block?.contentBlockIndex ?? 0
+
+      // Tool-call argument fragments (partial JSON).
+      if (delta && 'toolUse' in delta && delta.toolUse?.input !== undefined) {
+        const toolCall = toolCallsByIndex.get(index)
+        if (toolCall?.started) {
+          yield {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: toolCall.id,
+            timestamp: Date.now(),
+            delta: delta.toolUse.input,
+          }
+        }
+        continue
+      }
+
+      // Reasoning content.
+      if (
+        delta &&
+        'reasoningContent' in delta &&
+        delta.reasoningContent &&
+        'text' in delta.reasoningContent &&
+        delta.reasoningContent.text !== undefined
+      ) {
+        if (!reasoningMessageId) {
+          reasoningMessageId = newMessageId()
+          yield {
+            type: EventType.REASONING_MESSAGE_START,
+            messageId: reasoningMessageId,
+            role: 'reasoning',
+            timestamp: Date.now(),
+          }
+        }
+        yield {
+          type: EventType.REASONING_MESSAGE_CONTENT,
+          messageId: reasoningMessageId,
+          delta: delta.reasoningContent.text,
+          timestamp: Date.now(),
+        }
+        continue
+      }
+
+      // Text content.
+      if (delta && 'text' in delta && delta.text !== undefined) {
+        yield* closeReasoning()
+        if (!hasEmittedTextMessageStart) {
+          hasEmittedTextMessageStart = true
+          yield {
+            type: EventType.TEXT_MESSAGE_START,
+            messageId,
+            role: 'assistant',
+            timestamp: Date.now(),
+          }
+        }
+        accumulatedContent += delta.text
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta: delta.text,
+          content: accumulatedContent,
+          timestamp: Date.now(),
+        }
+      }
+      continue
+    }
+
+    if ('contentBlockStop' in ev) {
+      const stopIndex = ev.contentBlockStop?.contentBlockIndex ?? 0
+      const toolCall = toolCallsByIndex.get(stopIndex)
+      if (toolCall?.started) {
+        yield {
+          type: EventType.TOOL_CALL_END,
+          toolCallId: toolCall.id,
+          toolCallName: toolCall.name,
+          toolName: toolCall.name,
+          timestamp: Date.now(),
+        }
+        toolCallsByIndex.delete(stopIndex)
+      }
+      continue
+    }
+
+    if ('messageStop' in ev) {
+      const stopReason = ev.messageStop?.stopReason
+      // Map Converse stopReason to AG-UI's narrower finishReason vocabulary.
+      finishReason =
+        stopReason === 'tool_use'
+          ? 'tool_calls'
+          : stopReason === 'max_tokens'
+            ? 'length'
+            : stopReason === 'content_filtered'
+              ? 'content_filter'
+              : 'stop'
+      continue
+    }
+
+    if ('metadata' in ev) {
+      const u = ev.metadata?.usage
+      if (u) {
+        usage = {
+          promptTokens: u.inputTokens ?? 0,
+          completionTokens: u.outputTokens ?? 0,
+          totalTokens: u.totalTokens ?? 0,
+        }
+      }
+      continue
+    }
+  }
+
+  // Stream ended (possibly without any content) — still emit RUN_STARTED so
+  // consumers always see a run lifecycle.
+  yield* ensureRunStarted()
+
+  // Drain any tool call that opened but never received contentBlockStop.
+  for (const [index, toolCall] of toolCallsByIndex) {
+    if (!toolCall.started) continue
+    yield {
+      type: EventType.TOOL_CALL_END,
+      toolCallId: toolCall.id,
+      toolCallName: toolCall.name,
+      toolName: toolCall.name,
+      timestamp: Date.now(),
+    }
+    toolCallsByIndex.delete(index)
+  }
+
+  // Close the text message lifecycle if it was opened.
+  if (hasEmittedTextMessageStart) {
+    yield {
+      type: EventType.TEXT_MESSAGE_END,
+      messageId,
+      timestamp: Date.now(),
+    }
+  }
+
+  // Close any reasoning lifecycle that text never closed.
+  yield* closeReasoning()
+
+  // Single terminal RUN_FINISHED. Conditional `usage` spread keeps the wire
+  // shape spec-compliant (AG-UI's `usage` is optional with no `| undefined`).
+  yield {
+    type: EventType.RUN_FINISHED,
+    runId,
+    threadId,
+    timestamp: Date.now(),
+    finishReason: finishReason ?? 'stop',
+    ...(usage && { usage }),
+  }
+}