@tanstack/ai 0.13.0 → 0.15.0

package/dist/esm/middlewares/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sources":["../../../src/middlewares/otel.ts"],"sourcesContent":["import {\n  SpanKind,\n  SpanStatusCode,\n  context as otelContext,\n  trace as otelTrace,\n} from '@opentelemetry/api'\nimport type {\n  AttributeValue,\n  Exception,\n  Meter,\n  Span,\n  SpanOptions,\n  Tracer,\n} from '@opentelemetry/api'\nimport type {\n  ChatMiddleware,\n  ChatMiddlewareContext,\n} from '../activities/chat/middleware/types'\n\n/**\n * Scope (role) of an OTel span emitted by this middleware.\n *\n * - `chat` — the root span for a single `chat()` call\n * - `iteration` — one per agent-loop iteration (one model call)\n * - `tool` — one per tool execution inside an iteration\n */\nexport type OtelSpanScope = 'chat' | 'iteration' | 'tool'\n\n/**\n * Alias retained for backwards compatibility. Prefer {@link OtelSpanScope}.\n *\n * @deprecated Use `OtelSpanScope` instead — the name shadows OTel's built-in\n * `SpanKind` which is also imported by integrations of this middleware.\n */\nexport type OtelSpanKind = OtelSpanScope\n\n/**\n * Span metadata passed to `spanNameFormatter`, `attributeEnricher`,\n * `onBeforeSpanStart`, and `onSpanEnd`. Discriminated by `kind` so that\n * tool-only fields narrow automatically inside callback bodies.\n */\nexport type OtelSpanInfo<TScope extends OtelSpanScope = OtelSpanScope> =\n  TScope extends 'chat'\n    ? { kind: 'chat'; ctx: ChatMiddlewareContext }\n    : TScope extends 'iteration'\n      ? { kind: 'iteration'; ctx: ChatMiddlewareContext; iteration: number }\n      : TScope extends 'tool'\n        ? {\n            kind: 'tool'\n            ctx: ChatMiddlewareContext\n            iteration: number\n            toolName: string\n            toolCallId: string\n          }\n        : never\n\nexport interface OtelMiddlewareOptions {\n  /** OTel `Tracer` used to start root, iteration, and tool spans. */\n  tracer: Tracer\n  /**\n   * Optional OTel `Meter`. When provided, the middleware records\n   * `gen_ai.client.operation.duration` and `gen_ai.client.token.usage`\n   * histograms. Omit to disable metrics without disabling tracing.\n   */\n  meter?: Meter\n  /**\n   * When `true`, prompt and completion content is attached to iteration spans\n   * as `gen_ai.*.message` / `gen_ai.choice` events. Defaults to `false` so\n   * that PII never lands on a span by accident.\n   */\n  captureContent?: boolean\n  /**\n   * Invoked on every captured content string before it lands on a span.\n   * Return a redacted version. If this function throws, the middleware emits\n   * the literal sentinel `\"[redaction_failed]\"` instead of the original text\n   * — it never falls back to raw content.\n   */\n  redact?: (text: string) => string\n  /**\n   * Maximum characters kept in the per-iteration assistant text buffer used\n   * to emit `gen_ai.choice` events. Extra characters are truncated with a\n   * trailing `\"…\"` marker. Defaults to 100 000. Set to `0` to disable the\n   * cap. Exporters typically truncate long attribute values anyway.\n   */\n  maxContentLength?: number\n  /** Override the default span name for each `kind`. */\n  spanNameFormatter?: (info: OtelSpanInfo) => string\n  /** Add extra attributes to each span. */\n  attributeEnricher?: (info: OtelSpanInfo) => Record<string, AttributeValue>\n  /** Mutate `SpanOptions` immediately before `tracer.startSpan(...)`. */\n  onBeforeSpanStart?: (info: OtelSpanInfo, options: SpanOptions) => SpanOptions\n  /** Fires just before every `span.end()`. */\n  onSpanEnd?: (info: OtelSpanInfo, span: Span) => void\n}\n\ninterface RequestState {\n  rootSpan: Span\n  currentIterationSpan: Span | null\n  toolSpans: Map<string, { span: Span; toolName: string }>\n  iterationCount: number\n  assistantTextBuffer: string\n  assistantTextBufferTruncated: boolean\n  startTime: number\n}\n\nconst stateByCtx = new WeakMap<ChatMiddlewareContext, RequestState>()\n\nconst DEFAULT_MAX_CONTENT_LENGTH = 100_000\nconst REDACTION_FAILED_SENTINEL = '[redaction_failed]'\n\nfunction serializeContent(content: unknown): string {\n  if (typeof content === 'string') return content\n  if (!Array.isArray(content)) return ''\n  const parts: Array<string> = []\n  for (const part of content) {\n    if (!part || typeof part !== 'object') continue\n    const type = (part as { type?: string }).type\n    switch (type) {\n      case 'text':\n        parts.push(\n          (\n            (part as { text?: string }).text ??\n            (part as { content?: string }).content ??\n            ''\n          ).toString(),\n        )\n        break\n      case 'image':\n        parts.push('[image]')\n        break\n      case 'audio':\n        parts.push('[audio]')\n        break\n      case 'video':\n        parts.push('[video]')\n        break\n      case 'document':\n        parts.push('[document]')\n        break\n      default:\n        parts.push(`[${type ?? 'unknown'}]`)\n    }\n  }\n  return parts.join(' ')\n}\n\nfunction messageEventName(role: string): string {\n  switch (role) {\n    case 'user':\n      return 'gen_ai.user.message'\n    case 'assistant':\n      return 'gen_ai.assistant.message'\n    case 'tool':\n      return 'gen_ai.tool.message'\n    case 'system':\n      return 'gen_ai.system.message'\n    default:\n      return `gen_ai.${role}.message`\n  }\n}\n\nfunction errorMessage(err: unknown): string | undefined {\n  if (err instanceof Error) return err.message\n  if (typeof err === 'string') return err\n  if (err && typeof err === 'object' && 'message' in err) {\n    const m = (err as { message?: unknown }).message\n    if (typeof m === 'string') return m\n  }\n  return undefined\n}\n\nfunction errorTypeName(err: unknown): string {\n  if (err instanceof Error) return err.name || 'Error'\n  if (err && typeof err === 'object' && 'name' in err) {\n    const n = (err as { name?: unknown }).name\n    if (typeof n === 'string') return n\n  }\n  return 'Error'\n}\n\nfunction safeCall<T>(label: string, fn: () => T): T | undefined {\n  try {\n    return fn()\n  } catch (err) {\n    // Keep middleware non-fatal, but surface callback failures so that broken\n    // extension points (attributeEnricher, spanNameFormatter, onSpanEnd, ...)\n    // are observable. Matches the guarantee documented in docs/advanced/otel.md.\n    console.warn(`[otelMiddleware] ${label} failed`, err)\n    return undefined\n  }\n}\n\nexport function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {\n  const {\n    tracer,\n    meter,\n    captureContent = false,\n    redact = (s) => s,\n    maxContentLength = DEFAULT_MAX_CONTENT_LENGTH,\n    spanNameFormatter,\n    attributeEnricher,\n    onBeforeSpanStart,\n    onSpanEnd,\n  } = options\n\n  const durationHistogram = meter?.createHistogram(\n    'gen_ai.client.operation.duration',\n    {\n      description: 'GenAI client operation duration',\n      unit: 's',\n    },\n  )\n  const tokenHistogram = meter?.createHistogram('gen_ai.client.token.usage', {\n    description: 'GenAI client token usage',\n    unit: '{token}',\n  })\n\n  // Redact user content, failing closed to a sentinel string instead of ever\n  // letting raw text through. Callers that pass `captureContent: true` with a\n  // third-party PII redactor depend on this invariant.\n  const redactContent = (text: string): string => {\n    try {\n      return redact(text)\n    } catch (err) {\n      console.warn('[otelMiddleware] otel.redact failed', err)\n      return REDACTION_FAILED_SENTINEL\n    }\n  }\n\n  const appendAssistantText = (state: RequestState, delta: string): void => {\n    if (maxContentLength > 0) {\n      if (state.assistantTextBufferTruncated) return\n      const remaining = maxContentLength - state.assistantTextBuffer.length\n      if (remaining <= 0) {\n        state.assistantTextBufferTruncated = true\n        state.assistantTextBuffer += '…'\n        return\n      }\n      if (delta.length > remaining) {\n        state.assistantTextBuffer += delta.slice(0, remaining) + '…'\n        state.assistantTextBufferTruncated = true\n        return\n      }\n    }\n    state.assistantTextBuffer += delta\n  }\n\n  const closeIterationSpan = (\n    state: RequestState,\n    ctx: ChatMiddlewareContext,\n  ): void => {\n    if (!state.currentIterationSpan) return\n    const span = state.currentIterationSpan\n    const iteration = state.iterationCount - 1\n    safeCall('otel.onSpanEnd', () =>\n      onSpanEnd?.(\n        { kind: 'iteration', ctx, iteration } as OtelSpanInfo<'iteration'>,\n        span,\n      ),\n    )\n    span.end()\n    state.currentIterationSpan = null\n  }\n\n  return {\n    name: 'otel',\n\n    onStart(ctx) {\n      safeCall('otel.onStart', () => {\n        const info: OtelSpanInfo<'chat'> = { kind: 'chat', ctx }\n        const name =\n          safeCall('otel.spanNameFormatter', () => spanNameFormatter?.(info)) ??\n          `chat ${ctx.model}`\n        const baseOptions: SpanOptions = {\n          kind: SpanKind.INTERNAL,\n          attributes: {\n            'gen_ai.system': ctx.provider,\n            'gen_ai.request.model': ctx.model,\n            // NOTE: `gen_ai.operation.name` is deliberately NOT set on the\n            // root span. The root represents a `chat()` invocation that may\n            // span multiple model calls; only iteration spans correspond to\n            // a single chat operation. Backends that map `operation.name=chat`\n            // to a \"generation\" event (e.g. PostHog LLM Analytics) would\n            // otherwise emit a duplicate generation for the wrapper span.\n          },\n        }\n        const spanOptions =\n          safeCall('otel.onBeforeSpanStart', () =>\n            onBeforeSpanStart?.(info, baseOptions),\n          ) ?? baseOptions\n        const rootSpan = tracer.startSpan(name, spanOptions)\n\n        const enriched = safeCall('otel.attributeEnricher', () =>\n          attributeEnricher?.(info),\n        )\n        if (enriched) rootSpan.setAttributes(enriched)\n\n        stateByCtx.set(ctx, {\n          rootSpan,\n          currentIterationSpan: null,\n          toolSpans: new Map(),\n          iterationCount: 0,\n          assistantTextBuffer: '',\n          assistantTextBufferTruncated: false,\n          startTime: Date.now(),\n        })\n      })\n    },\n\n    onConfig(ctx, config) {\n      if (ctx.phase !== 'beforeModel') return\n      safeCall('otel.onConfig', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n\n        // The previous iteration's span stays open through tool execution and\n        // onUsage so that tool spans nest under it and token attributes land\n        // on it. Close it here, just before opening the next iteration.\n        closeIterationSpan(state, ctx)\n\n        const info: OtelSpanInfo<'iteration'> = {\n          kind: 'iteration',\n          ctx,\n          iteration: ctx.iteration,\n        }\n        const name =\n          safeCall('otel.spanNameFormatter', () => spanNameFormatter?.(info)) ??\n          `chat ${ctx.model} #${ctx.iteration}`\n\n        const baseAttrs: Record<string, AttributeValue> = {\n          'gen_ai.system': ctx.provider,\n          'gen_ai.operation.name': 'chat',\n          'gen_ai.request.model': ctx.model,\n          'tanstack.ai.iteration': ctx.iteration,\n        }\n        if (config.temperature !== undefined)\n          baseAttrs['gen_ai.request.temperature'] = config.temperature\n        if (config.topP !== undefined)\n          baseAttrs['gen_ai.request.top_p'] = config.topP\n        if (config.maxTokens !== undefined)\n          baseAttrs['gen_ai.request.max_tokens'] = config.maxTokens\n\n        const baseOptions: SpanOptions = {\n          kind: SpanKind.CLIENT,\n          attributes: baseAttrs,\n        }\n        const spanOptions =\n          safeCall('otel.onBeforeSpanStart', () =>\n            onBeforeSpanStart?.(info, baseOptions),\n          ) ?? baseOptions\n\n        const parentCtx = otelTrace.setSpan(\n          otelContext.active(),\n          state.rootSpan,\n        )\n        let iterSpan!: Span\n        otelContext.with(parentCtx, () => {\n          // Pass the parent context explicitly as the 3rd arg — this is a\n          // real-OTel-compatible way to ensure the span is parented to\n          // `rootSpan` even when the host app has not registered a context\n          // manager (e.g. in tests or minimal setups).\n          iterSpan = tracer.startSpan(name, spanOptions, parentCtx)\n        })\n\n        const enriched = safeCall('otel.attributeEnricher', () =>\n          attributeEnricher?.(info),\n        )\n        if (enriched) iterSpan.setAttributes(enriched)\n\n        state.currentIterationSpan = iterSpan\n        state.assistantTextBuffer = ''\n        state.assistantTextBufferTruncated = false\n\n        if (captureContent) {\n          // Span events follow the original GenAI semconv (one event per\n          // message). Backends that read events get content this way.\n          for (const sys of config.systemPrompts) {\n            iterSpan.addEvent('gen_ai.system.message', {\n              content: redactContent(sys),\n            })\n          }\n          for (const m of config.messages) {\n            const body = serializeContent(m.content)\n            if (body.length === 0) continue\n            iterSpan.addEvent(messageEventName(m.role), {\n              content: redactContent(body),\n            })\n          }\n\n          // Also emit the current GenAI-semconv attribute form\n          // (`gen_ai.input.messages`) — backends like PostHog read prompt\n          // content from this attribute, not from span events.\n          const inputMessages: Array<{ role: string; content: string }> = []\n          for (const sys of config.systemPrompts) {\n            inputMessages.push({\n              role: 'system',\n              content: redactContent(sys),\n            })\n          }\n          for (const m of config.messages) {\n            const body = serializeContent(m.content)\n            if (body.length === 0) continue\n            inputMessages.push({\n              role: m.role,\n              content: redactContent(body),\n            })\n          }\n          if (inputMessages.length > 0) {\n            const inputJson = JSON.stringify(inputMessages)\n            // Current OTel GenAI semconv — Sentry / PostHog / Datadog read\n            // prompt content from this attribute.\n            iterSpan.setAttribute('gen_ai.input.messages', inputJson)\n            // Langfuse-native attribute. Highest priority in Langfuse's OTLP\n            // ingestion (checked before events and gen_ai.input.messages) so\n            // the Input panel populates reliably. Harmless to other backends —\n            // the attribute is namespaced and unrecognised keys are ignored.\n            iterSpan.setAttribute('langfuse.observation.input', inputJson)\n\n            // Mirror the first iteration's input onto the root span and at\n            // trace level so Langfuse fills Input on the trace card and the\n            // chat-level observation. Later iterations append tool-call /\n            // assistant messages that are useful per-iteration but noise at\n            // the chat / trace level.\n            if (state.iterationCount === 0) {\n              state.rootSpan.setAttribute(\n                'langfuse.observation.input',\n                inputJson,\n              )\n              state.rootSpan.setAttribute('langfuse.trace.input', inputJson)\n            }\n          }\n        }\n\n        state.iterationCount += 1\n      })\n      return undefined\n    },\n\n    onChunk(ctx, chunk) {\n      safeCall('otel.onChunk', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n\n        if (captureContent && chunk.type === 'TEXT_MESSAGE_CONTENT') {\n          appendAssistantText(state, chunk.delta)\n        }\n\n        if (chunk.type !== 'RUN_FINISHED') return\n        const span = state.currentIterationSpan\n        if (!span) return\n\n        if (chunk.finishReason) {\n          span.setAttribute('gen_ai.response.finish_reasons', [\n            chunk.finishReason,\n          ])\n        }\n        if (chunk.model) span.setAttribute('gen_ai.response.model', chunk.model)\n\n        // Set usage attributes on the iteration span directly from the chunk\n        // so they're available before `onUsage` fires. Histogram recording is\n        // deliberately NOT done here — the chat runner always invokes\n        // `runOnUsage` when `chunk.usage` is present, and `onUsage` is the\n        // canonical place for the metric. Recording in both would double-count.\n        if (chunk.usage) {\n          span.setAttributes({\n            'gen_ai.usage.input_tokens': chunk.usage.promptTokens,\n            'gen_ai.usage.output_tokens': chunk.usage.completionTokens,\n          })\n        }\n\n        if (captureContent && state.assistantTextBuffer.length > 0) {\n          const completion = redactContent(state.assistantTextBuffer)\n          const outputJson = JSON.stringify([\n            { role: 'assistant', content: completion },\n          ])\n          // Event form (older semconv) — kept for backends that consume it.\n          span.addEvent('gen_ai.choice', { content: completion })\n          // Attribute form (current semconv) — required by backends like\n          // PostHog that read completion content from `gen_ai.output.messages`.\n          span.setAttribute('gen_ai.output.messages', outputJson)\n          // Langfuse-native attribute (highest priority in Langfuse mapping).\n          span.setAttribute('langfuse.observation.output', outputJson)\n          // Mirror to the root span and trace card. Each iteration overwrites,\n          // so the final iteration's completion lands on the root — which is\n          // the final answer the user saw, not an intermediate tool-call turn.\n          state.rootSpan.setAttribute('langfuse.observation.output', outputJson)\n          state.rootSpan.setAttribute('langfuse.trace.output', outputJson)\n          state.assistantTextBuffer = ''\n          state.assistantTextBufferTruncated = false\n        }\n\n        // Intentionally leave the iteration span open: tool spans started\n        // after `RUN_FINISHED` (tool_calls finishReason) must nest under it,\n        // and `onUsage` may still fire. The span is closed in `onConfig` when\n        // the next iteration starts, or in `onFinish` / `onError` / `onAbort`.\n      })\n      return undefined\n    },\n\n    onUsage(ctx, usage) {\n      safeCall('otel.onUsage', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n\n        // Always record the token histogram — metrics don't depend on having\n        // an iteration span, and skipping here would drop metric data if an\n        // adapter emits `onUsage` outside the iteration window.\n        if (tokenHistogram) {\n          const metricAttrs = {\n            'gen_ai.system': ctx.provider,\n            'gen_ai.operation.name': 'chat',\n            'gen_ai.request.model': ctx.model,\n          }\n          tokenHistogram.record(usage.promptTokens, {\n            ...metricAttrs,\n            'gen_ai.token.type': 'input',\n          })\n          tokenHistogram.record(usage.completionTokens, {\n            ...metricAttrs,\n            'gen_ai.token.type': 'output',\n          })\n        }\n\n        const span = state.currentIterationSpan ?? state.rootSpan\n        span.setAttributes({\n          'gen_ai.usage.input_tokens': usage.promptTokens,\n          'gen_ai.usage.output_tokens': usage.completionTokens,\n        })\n      })\n    },\n\n    onBeforeToolCall(ctx, hookCtx) {\n      safeCall('otel.onBeforeToolCall', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n        const parent = state.currentIterationSpan ?? state.rootSpan\n\n        const info: OtelSpanInfo<'tool'> = {\n          kind: 'tool',\n          ctx,\n          toolName: hookCtx.toolName,\n          toolCallId: hookCtx.toolCallId,\n          iteration: state.iterationCount - 1,\n        }\n        const name =\n          safeCall('otel.spanNameFormatter', () => spanNameFormatter?.(info)) ??\n          `execute_tool ${hookCtx.toolName}`\n\n        const baseAttrs: Record<string, AttributeValue> = {\n          'gen_ai.tool.name': hookCtx.toolName,\n          'gen_ai.tool.call.id': hookCtx.toolCallId,\n          'gen_ai.tool.type': 'function',\n        }\n        const baseOptions: SpanOptions = {\n          kind: SpanKind.INTERNAL,\n          attributes: baseAttrs,\n        }\n        const spanOptions =\n          safeCall('otel.onBeforeSpanStart', () =>\n            onBeforeSpanStart?.(info, baseOptions),\n          ) ?? baseOptions\n\n        const parentCtx = otelTrace.setSpan(otelContext.active(), parent)\n        let toolSpan!: Span\n        otelContext.with(parentCtx, () => {\n          toolSpan = tracer.startSpan(name, spanOptions, parentCtx)\n        })\n\n        const enriched = safeCall('otel.attributeEnricher', () =>\n          attributeEnricher?.(info),\n        )\n        if (enriched) toolSpan.setAttributes(enriched)\n\n        // Stamp the tool args onto the tool span so backends that render an\n        // input panel per span (e.g. PostHog) have something to show.\n        if (captureContent) {\n          const argsBody =\n            typeof hookCtx.args === 'string'\n              ? hookCtx.args\n              : (safeCall('otel.serializeToolArgs', () =>\n                  JSON.stringify(hookCtx.args ?? null),\n                ) ?? '[unserializable_tool_args]')\n          const redactedArgs = redactContent(argsBody)\n          const toolInputJson = JSON.stringify([\n            { role: 'tool', content: redactedArgs },\n          ])\n          toolSpan.setAttribute('gen_ai.input.messages', toolInputJson)\n          // Langfuse-native (highest priority in Langfuse mapping).\n          toolSpan.setAttribute('langfuse.observation.input', toolInputJson)\n        }\n\n        state.toolSpans.set(hookCtx.toolCallId, {\n          span: toolSpan,\n          toolName: hookCtx.toolName,\n        })\n      })\n      return undefined\n    },\n\n    onAfterToolCall(ctx, info) {\n      safeCall('otel.onAfterToolCall', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n        const entry = state.toolSpans.get(info.toolCallId)\n        if (!entry) return\n        const { span: toolSpan } = entry\n\n        const outcome = info.ok ? 'success' : 'error'\n        toolSpan.setAttribute('tanstack.ai.tool.outcome', outcome)\n\n        if (!info.ok && info.error !== undefined) {\n          toolSpan.recordException(info.error as Exception)\n          toolSpan.setStatus({\n            code: SpanStatusCode.ERROR,\n            message: errorMessage(info.error),\n          })\n        }\n\n        if (captureContent) {\n          // Serialization can throw on circular refs or `BigInt` values. If it\n          // does, fall back to a sentinel so the rest of this handler (span\n          // end, onSpanEnd, toolSpans cleanup) still runs — otherwise the tool\n          // span would dangle until the onFinish/onError sweep.\n          const body =\n            typeof info.result === 'string'\n              ? info.result\n              : (safeCall('otel.serializeToolResult', () =>\n                  JSON.stringify(info.result ?? null),\n                ) ?? '[unserializable_tool_result]')\n          const redactedBody = redactContent(body)\n          if (state.currentIterationSpan) {\n            state.currentIterationSpan.addEvent('gen_ai.tool.message', {\n              content: redactedBody,\n              tool_call_id: info.toolCallId,\n            })\n          }\n          // Output panel of the tool span itself — `gen_ai.output.messages` is\n          // what current GenAI semconv consumers (e.g. PostHog) read.\n          const toolOutputJson = JSON.stringify([\n            { role: 'tool', content: redactedBody },\n          ])\n          toolSpan.setAttribute('gen_ai.output.messages', toolOutputJson)\n          // Langfuse-native (highest priority in Langfuse mapping).\n          toolSpan.setAttribute('langfuse.observation.output', toolOutputJson)\n        }\n\n        safeCall('otel.onSpanEnd', () =>\n          onSpanEnd?.(\n            {\n              kind: 'tool',\n              ctx,\n              toolName: info.toolName,\n              toolCallId: info.toolCallId,\n              iteration: state.iterationCount - 1,\n            } as OtelSpanInfo<'tool'>,\n            toolSpan,\n          ),\n        )\n        toolSpan.end()\n        state.toolSpans.delete(info.toolCallId)\n      })\n    },\n\n    onError(ctx, info) {\n      safeCall('otel.onError', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n\n        const errType = errorTypeName(info.error)\n        const message = errorMessage(info.error)\n        const exception = info.error as Exception\n\n        if (state.currentIterationSpan) {\n          state.currentIterationSpan.recordException(exception)\n          state.currentIterationSpan.setStatus({\n            code: SpanStatusCode.ERROR,\n            message,\n          })\n          safeCall('otel.onSpanEnd', () =>\n            onSpanEnd?.(\n              {\n                kind: 'iteration',\n                ctx,\n                iteration: state.iterationCount - 1,\n              } as OtelSpanInfo<'iteration'>,\n              state.currentIterationSpan!,\n            ),\n          )\n          state.currentIterationSpan.end()\n          state.currentIterationSpan = null\n        }\n\n        for (const [id, entry] of state.toolSpans) {\n          const { span, toolName } = entry\n          span.recordException(exception)\n          span.setStatus({ code: SpanStatusCode.ERROR, message })\n          safeCall('otel.onSpanEnd', () =>\n            onSpanEnd?.(\n              {\n                kind: 'tool',\n                ctx,\n                toolCallId: id,\n                toolName,\n                iteration: state.iterationCount - 1,\n              } as OtelSpanInfo<'tool'>,\n              span,\n            ),\n          )\n          span.end()\n          state.toolSpans.delete(id)\n        }\n\n        state.rootSpan.recordException(exception)\n        state.rootSpan.setStatus({ code: SpanStatusCode.ERROR, message })\n\n        if (durationHistogram) {\n          durationHistogram.record(info.duration / 1000, {\n            'gen_ai.system': ctx.provider,\n            'gen_ai.operation.name': 'chat',\n            'gen_ai.request.model': ctx.model,\n            'error.type': errType,\n          })\n        }\n\n        safeCall('otel.onSpanEnd', () =>\n          onSpanEnd?.({ kind: 'chat', ctx }, state.rootSpan),\n        )\n        state.rootSpan.end()\n        stateByCtx.delete(ctx)\n      })\n    },\n\n    onAbort(ctx, info) {\n      safeCall('otel.onAbort', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n\n        const closeCancelled = (span: Span): void => {\n          // `gen_ai.completion.reason` is not part of the GenAI semconv; use a\n          // TanStack-namespaced attribute so downstream exporters don't treat\n          // it as standard. The span status still carries the error code.\n          span.setAttribute('tanstack.ai.completion.reason', 'cancelled')\n          span.setStatus({ code: SpanStatusCode.ERROR, message: 'cancelled' })\n        }\n\n        if (state.currentIterationSpan) {\n          closeCancelled(state.currentIterationSpan)\n          safeCall('otel.onSpanEnd', () =>\n            onSpanEnd?.(\n              {\n                kind: 'iteration',\n                ctx,\n                iteration: state.iterationCount - 1,\n              } as OtelSpanInfo<'iteration'>,\n              state.currentIterationSpan!,\n            ),\n          )\n          state.currentIterationSpan.end()\n          state.currentIterationSpan = null\n        }\n        for (const [id, entry] of state.toolSpans) {\n          const { span, toolName } = entry\n          closeCancelled(span)\n          safeCall('otel.onSpanEnd', () =>\n            onSpanEnd?.(\n              {\n                kind: 'tool',\n                ctx,\n                toolCallId: id,\n                toolName,\n                iteration: state.iterationCount - 1,\n              } as OtelSpanInfo<'tool'>,\n              span,\n            ),\n          )\n          span.end()\n          state.toolSpans.delete(id)\n        }\n        closeCancelled(state.rootSpan)\n\n        if (durationHistogram) {\n          durationHistogram.record(info.duration / 1000, {\n            'gen_ai.system': ctx.provider,\n            'gen_ai.operation.name': 'chat',\n            'gen_ai.request.model': ctx.model,\n            'error.type': 'cancelled',\n          })\n        }\n\n        safeCall('otel.onSpanEnd', () =>\n          onSpanEnd?.({ kind: 'chat', ctx }, state.rootSpan),\n        )\n        state.rootSpan.end()\n        stateByCtx.delete(ctx)\n      })\n    },\n\n    onFinish(ctx, info) {\n      safeCall('otel.onFinish', () => {\n        const state = stateByCtx.get(ctx)\n        if (!state) return\n\n        // Close any tool spans that never received `onAfterToolCall` (adapter\n        // quirk). Done before the iteration span so the hierarchy is closed\n        // in depth-first order.\n        for (const [id, entry] of state.toolSpans) {\n          const { span, toolName } = entry\n          span.setAttribute('tanstack.ai.tool.outcome', 'unknown')\n          safeCall('otel.onSpanEnd', () =>\n            onSpanEnd?.(\n              {\n                kind: 'tool',\n                ctx,\n                toolCallId: id,\n                toolName,\n                iteration: state.iterationCount - 1,\n              } as OtelSpanInfo<'tool'>,\n              span,\n            ),\n          )\n          span.end()\n          state.toolSpans.delete(id)\n        }\n\n        // The final iteration's span is still open because we keep it open\n        // through tool execution and `onUsage`. Close it now.\n        closeIterationSpan(state, ctx)\n\n        if (durationHistogram) {\n          durationHistogram.record(info.duration / 1000, {\n            'gen_ai.system': ctx.provider,\n            'gen_ai.operation.name': 'chat',\n            'gen_ai.request.model': ctx.model,\n          })\n        }\n\n        if (info.usage) {\n          state.rootSpan.setAttributes({\n            'gen_ai.usage.input_tokens': info.usage.promptTokens,\n            'gen_ai.usage.output_tokens': info.usage.completionTokens,\n          })\n        }\n        if (info.finishReason) {\n          state.rootSpan.setAttribute('gen_ai.response.finish_reasons', [\n            info.finishReason,\n          ])\n        }\n        state.rootSpan.setAttribute(\n          'tanstack.ai.iterations',\n          state.iterationCount,\n        )\n\n        safeCall('otel.onSpanEnd', () =>\n          onSpanEnd?.({ kind: 'chat', ctx }, state.rootSpan),\n        )\n        state.rootSpan.end()\n        stateByCtx.delete(ctx)\n      })\n    },\n  }\n}\n"],"names":["otelTrace","otelContext"],"mappings":"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"}

package/dist/esm/stream-to-response.js

@@ -1,3 +1,4 @@
+import { toRunErrorPayload } from "./activities/error-payload.js";
 async function streamToText(stream) {
   let accumulatedContent = "";
   for await (const chunk of stream) {
@@ -33,10 +34,7 @@ function toServerSentEventsStream(stream, abortController) {
             `data: ${JSON.stringify({
               type: "RUN_ERROR",
               timestamp: Date.now(),
-              error: {
-                message: error.message || "Unknown error occurred",
-                code: error.code
-              }
+              error: toRunErrorPayload(error)
             })}
 
 `
@@ -93,10 +91,7 @@ function toHttpStream(stream, abortController) {
             `${JSON.stringify({
               type: "RUN_ERROR",
               timestamp: Date.now(),
-              error: {
-                message: error.message || "Unknown error occurred",
-                code: error.code
-              }
+              error: toRunErrorPayload(error)
             })}
 `
           )

package/dist/esm/stream-to-response.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-to-response.js","sources":["../../src/stream-to-response.ts"],"sourcesContent":["import type { StreamChunk } from './types'\n\n/**\n * Collect all text content from a StreamChunk async iterable and return as a string.\n *\n * This function consumes the entire stream, accumulating content from TEXT_MESSAGE_CONTENT events,\n * and returns the final concatenated text.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @returns Promise<string> - The accumulated text content\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: 'gpt-4o',\n *   messages: [{ role: 'user', content: 'Hello!' }]\n * });\n * const text = await streamToText(stream);\n * console.log(text); // \"Hello! How can I help you today?\"\n * ```\n */\nexport async function streamToText(\n  stream: AsyncIterable<StreamChunk>,\n): Promise<string> {\n  let accumulatedContent = ''\n\n  for await (const chunk of stream) {\n    if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {\n      accumulatedContent += chunk.delta\n    }\n  }\n\n  return accumulatedContent\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format\n *\n * This creates a ReadableStream that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in Server-Sent Events format\n */\nexport function toServerSentEventsStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as Server-Sent Events format\n          controller.enqueue(\n            encoder.encode(`data: ${JSON.stringify(chunk)}\\n\\n`),\n          )\n        }\n\n        controller.close()\n      } catch (error: any) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `data: ${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: {\n                message: error.message || 'Unknown error occurred',\n                code: error.code,\n              },\n            })}\\n\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in Server-Sent Events format\n *\n * This creates a Response that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in Server-Sent Events format\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toServerSentEventsResponse(stream, { abortController });\n * ```\n */\nexport function toServerSentEventsResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  const { headers, abortController, ...responseInit } = init ?? {}\n\n  // Start with default SSE headers\n  const mergedHeaders = new Headers({\n    'Content-Type': 'text/event-stream',\n    'Cache-Control': 'no-cache',\n    Connection: 'keep-alive',\n  })\n\n  // Override with user headers if provided, handling all HeadersInit forms:\n  // Headers instance, string[][], or plain object\n  if (headers) {\n    const userHeaders = new Headers(headers)\n    userHeaders.forEach((value, key) => {\n      mergedHeaders.set(key, value)\n    })\n  }\n\n  return new Response(toServerSentEventsStream(stream, abortController), {\n    ...responseInit,\n    headers: mergedHeaders,\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * This creates a ReadableStream that emits chunks as newline-delimited JSON:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * const readableStream = toHttpStream(stream);\n * // Use with Response for HTTP streaming (not SSE)\n * return new Response(readableStream, {\n *   headers: { 'Content-Type': 'application/x-ndjson' }\n * });\n * ```\n */\nexport function toHttpStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as newline-delimited JSON\n          controller.enqueue(encoder.encode(`${JSON.stringify(chunk)}\\n`))\n        }\n\n        controller.close()\n      } catch (error: any) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: {\n                message: error.message || 'Unknown error occurred',\n                code: error.code,\n              },\n            })}\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in HTTP stream format (newline-delimited JSON)\n *\n * This creates a Response that emits chunks in HTTP stream format:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toHttpResponse(stream, { abortController });\n * ```\n */\nexport function toHttpResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  return new Response(toHttpStream(stream, init?.abortController), {\n    ...init,\n  })\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"stream-to-response.js","sources":["../../src/stream-to-response.ts"],"sourcesContent":["import { toRunErrorPayload } from './activities/error-payload'\nimport type { StreamChunk } from './types'\n\n/**\n * Collect all text content from a StreamChunk async iterable and return as a string.\n *\n * This function consumes the entire stream, accumulating content from TEXT_MESSAGE_CONTENT events,\n * and returns the final concatenated text.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @returns Promise<string> - The accumulated text content\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: 'gpt-4o',\n *   messages: [{ role: 'user', content: 'Hello!' }]\n * });\n * const text = await streamToText(stream);\n * console.log(text); // \"Hello! How can I help you today?\"\n * ```\n */\nexport async function streamToText(\n  stream: AsyncIterable<StreamChunk>,\n): Promise<string> {\n  let accumulatedContent = ''\n\n  for await (const chunk of stream) {\n    if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {\n      accumulatedContent += chunk.delta\n    }\n  }\n\n  return accumulatedContent\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format\n *\n * This creates a ReadableStream that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in Server-Sent Events format\n */\nexport function toServerSentEventsStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as Server-Sent Events format\n          controller.enqueue(\n            encoder.encode(`data: ${JSON.stringify(chunk)}\\n\\n`),\n          )\n        }\n\n        controller.close()\n      } catch (error: unknown) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `data: ${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: toRunErrorPayload(error),\n            })}\\n\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in Server-Sent Events format\n *\n * This creates a Response that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in Server-Sent Events format\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toServerSentEventsResponse(stream, { abortController });\n * ```\n */\nexport function toServerSentEventsResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  const { headers, abortController, ...responseInit } = init ?? {}\n\n  // Start with default SSE headers\n  const mergedHeaders = new Headers({\n    'Content-Type': 'text/event-stream',\n    'Cache-Control': 'no-cache',\n    Connection: 'keep-alive',\n  })\n\n  // Override with user headers if provided, handling all HeadersInit forms:\n  // Headers instance, string[][], or plain object\n  if (headers) {\n    const userHeaders = new Headers(headers)\n    userHeaders.forEach((value, key) => {\n      mergedHeaders.set(key, value)\n    })\n  }\n\n  return new Response(toServerSentEventsStream(stream, abortController), {\n    ...responseInit,\n    headers: mergedHeaders,\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * This creates a ReadableStream that emits chunks as newline-delimited JSON:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * const readableStream = toHttpStream(stream);\n * // Use with Response for HTTP streaming (not SSE)\n * return new Response(readableStream, {\n *   headers: { 'Content-Type': 'application/x-ndjson' }\n * });\n * ```\n */\nexport function toHttpStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as newline-delimited JSON\n          controller.enqueue(encoder.encode(`${JSON.stringify(chunk)}\\n`))\n        }\n\n        controller.close()\n      } catch (error: unknown) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: toRunErrorPayload(error),\n            })}\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in HTTP stream format (newline-delimited JSON)\n *\n * This creates a Response that emits chunks in HTTP stream format:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toHttpResponse(stream, { abortController });\n * ```\n */\nexport function toHttpResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  return new Response(toHttpStream(stream, init?.abortController), {\n    ...init,\n  })\n}\n"],"names":[],"mappings":";AAuBA,eAAsB,aACpB,QACiB;AACjB,MAAI,qBAAqB;AAEzB,mBAAiB,SAAS,QAAQ;AAChC,QAAI,MAAM,SAAS,0BAA0B,MAAM,OAAO;AACxD,4BAAsB,MAAM;AAAA,IAC9B;AAAA,EACF;AAEA,SAAO;AACT;AAcO,SAAS,yBACd,QACA,iBAC4B;AAC5B,QAAM,UAAU,IAAI,YAAA;AAEpB,SAAO,IAAI,eAAe;AAAA,IACxB,MAAM,MAAM,YAAY;AACtB,UAAI;AACF,yBAAiB,SAAS,QAAQ;AAEhC,cAAI,iBAAiB,OAAO,SAAS;AACnC;AAAA,UACF;AAGA,qBAAW;AAAA,YACT,QAAQ,OAAO,SAAS,KAAK,UAAU,KAAK,CAAC;AAAA;AAAA,CAAM;AAAA,UAAA;AAAA,QAEvD;AAEA,mBAAW,MAAA;AAAA,MACb,SAAS,OAAgB;AAEvB,YAAI,iBAAiB,OAAO,SAAS;AACnC,qBAAW,MAAA;AACX;AAAA,QACF;AAGA,mBAAW;AAAA,UACT,QAAQ;AAAA,YACN,SAAS,KAAK,UAAU;AAAA,cACtB,MAAM;AAAA,cACN,WAAW,KAAK,IAAA;AAAA,cAChB,OAAO,kBAAkB,KAAK;AAAA,YAAA,CAC/B,CAAC;AAAA;AAAA;AAAA,UAAA;AAAA,QACJ;AAEF,mBAAW,MAAA;AAAA,MACb;AAAA,IACF;AAAA,IACA,SAAS;AAGP,UAAI,iBAAiB;AACnB,wBAAgB,MAAA;AAAA,MAClB;AAAA,IACF;AAAA,EAAA,CACD;AACH;AAoBO,SAAS,2BACd,QACA,MACU;AACV,QAAM,EAAE,SAAS,iBAAiB,GAAG,aAAA,IAAiB,QAAQ,CAAA;AAG9D,QAAM,gBAAgB,IAAI,QAAQ;AAAA,IAChC,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,IACjB,YAAY;AAAA,EAAA,CACb;AAID,MAAI,SAAS;AACX,UAAM,cAAc,IAAI,QAAQ,OAAO;AACvC,gBAAY,QAAQ,CAAC,OAAO,QAAQ;AAClC,oBAAc,IAAI,KAAK,KAAK;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,SAAO,IAAI,SAAS,yBAAyB,QAAQ,eAAe,GAAG;AAAA,IACrE,GAAG;AAAA,IACH,SAAS;AAAA,EAAA,CACV;AACH;AAyBO,SAAS,aACd,QACA,iBAC4B;AAC5B,QAAM,UAAU,IAAI,YAAA;AAEpB,SAAO,IAAI,eAAe;AAAA,IACxB,MAAM,MAAM,YAAY;AACtB,UAAI;AACF,yBAAiB,SAAS,QAAQ;AAEhC,cAAI,iBAAiB,OAAO,SAAS;AACnC;AAAA,UACF;AAGA,qBAAW,QAAQ,QAAQ,OAAO,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,CAAI,CAAC;AAAA,QACjE;AAEA,mBAAW,MAAA;AAAA,MACb,SAAS,OAAgB;AAEvB,YAAI,iBAAiB,OAAO,SAAS;AACnC,qBAAW,MAAA;AACX;AAAA,QACF;AAGA,mBAAW;AAAA,UACT,QAAQ;AAAA,YACN,GAAG,KAAK,UAAU;AAAA,cAChB,MAAM;AAAA,cACN,WAAW,KAAK,IAAA;AAAA,cAChB,OAAO,kBAAkB,KAAK;AAAA,YAAA,CAC/B,CAAC;AAAA;AAAA,UAAA;AAAA,QACJ;AAEF,mBAAW,MAAA;AAAA,MACb;AAAA,IACF;AAAA,IACA,SAAS;AAGP,UAAI,iBAAiB;AACnB,wBAAgB,MAAA;AAAA,MAClB;AAAA,IACF;AAAA,EAAA,CACD;AACH;AAqBO,SAAS,eACd,QACA,MACU;AACV,SAAO,IAAI,SAAS,aAAa,QAAQ,MAAM,eAAe,GAAG;AAAA,IAC/D,GAAG;AAAA,EAAA,CACJ;AACH;"}

package/dist/esm/types.d.ts

@@ -208,6 +208,10 @@ export interface ModelMessage<TContent extends string | null | Array<ContentPart
     name?: string;
     toolCalls?: Array<ToolCall>;
     toolCallId?: string;
+    thinking?: Array<{
+        content: string;
+        signature?: string;
+    }>;
 }
 /**
  * Message parts - building blocks of UIMessage
@@ -242,6 +246,8 @@ export interface ToolResultPart {
 export interface ThinkingPart {
     type: 'thinking';
     content: string;
+    stepId?: string;
+    signature?: string;
 }
 export type MessagePart = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart | ToolResultPart | ThinkingPart;
 /**
@@ -827,6 +833,8 @@ export interface StepFinishedEvent extends AGUIStepFinishedEvent {
     delta?: string;
     /** Full accumulated thinking content (TanStack AI internal) */
     content?: string;
+    /** Provider signature for the thinking block */
+    signature?: string;
 }
 /**
  * Emitted to provide a snapshot of all messages in a conversation.
@@ -1003,17 +1011,28 @@ export interface ImageGenerationOptions<TProviderOptions extends object = object
      */
     logger: InternalLogger;
 }
+/**
+ * Source of a generated media asset. Exactly one of `url` or `b64Json` is
+ * present; the other is absent. Modeled as a mutually-exclusive union so the
+ * type rejects `{}` and `{ url, b64Json }` together at compile time while
+ * preserving the flat `.url` / `.b64Json` access patterns.
+ */
+export type GeneratedMediaSource = {
+    /** URL to the generated asset (may be temporary) */
+    url: string;
+    b64Json?: never;
+} | {
+    /** Base64-encoded asset data */
+    b64Json: string;
+    url?: never;
+};
 /**
  * A single generated image
  */
-export interface GeneratedImage {
-    /** Base64-encoded image data */
-    b64Json?: string;
-    /** URL to the generated image (may be temporary) */
-    url?: string;
+export type GeneratedImage = GeneratedMediaSource & {
     /** Revised prompt used by the model (if applicable) */
     revisedPrompt?: string;
-}
+};
 /**
  * Result of image generation
  */
@@ -1031,6 +1050,52 @@ export interface ImageGenerationResult {
         totalTokens?: number;
     };
 }
+/**
+ * Options for audio generation (music, sound effects, etc.).
+ * These are the common options supported across providers.
+ */
+export interface AudioGenerationOptions<TProviderOptions extends object = object> {
+    /** The model to use for audio generation */
+    model: string;
+    /** Text description of the desired audio */
+    prompt: string;
+    /** Desired duration in seconds */
+    duration?: number;
+    /** Model-specific options for audio generation */
+    modelOptions?: TProviderOptions;
+    /**
+     * Internal logger threaded from the generateAudio() entry point. Adapters
+     * must call logger.request() before the SDK call and logger.errors() in
+     * catch blocks.
+     */
+    logger: InternalLogger;
+}
+/**
+ * A single generated audio output
+ */
+export type GeneratedAudio = GeneratedMediaSource & {
+    /** Content type of the audio (e.g., 'audio/wav', 'audio/mp3') */
+    contentType?: string;
+    /** Duration of the generated audio in seconds */
+    duration?: number;
+};
+/**
+ * Result of audio generation
+ */
+export interface AudioGenerationResult {
+    /** Unique identifier for the generation */
+    id: string;
+    /** Model used for generation */
+    model: string;
+    /** The generated audio */
+    audio: GeneratedAudio;
+    /** Token usage information (if available) */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+}
 /**
  * Options for video generation.
  * These are the common options supported across providers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -25,6 +25,10 @@
       "types": "./dist/esm/middlewares/index.d.ts",
       "import": "./dist/esm/middlewares/index.js"
     },
+    "./middlewares/otel": {
+      "types": "./dist/esm/middlewares/otel.d.ts",
+      "import": "./dist/esm/middlewares/otel.js"
+    },
     "./adapter-internals": {
       "types": "./dist/esm/adapter-internals.d.ts",
       "import": "./dist/esm/adapter-internals.js"
@@ -51,9 +55,18 @@
   "dependencies": {
     "@ag-ui/core": "0.0.49",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.2.7"
+    "@tanstack/ai-event-client": "0.2.9"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@standard-schema/spec": "^1.1.0",
     "@vitest/coverage-v8": "4.0.14",
     "zod": "^4.2.0"

package/skills/ai-core/media-generation/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: ai-core/media-generation
 description: >
-  Image, video, speech (TTS), and transcription generation using
+  Image, audio, video, speech (TTS), and transcription generation using
   activity-specific adapters: generateImage() with openaiImage/geminiImage,
-  generateVideo() with async polling, generateSpeech() with openaiSpeech,
-  generateTranscription() with openaiTranscription. React hooks:
-  useGenerateImage, useGenerateSpeech, useTranscription, useGenerateVideo.
+  generateAudio() with geminiAudio/falAudio, generateVideo() with async
+  polling, generateSpeech() with openaiSpeech, generateTranscription() with
+  openaiTranscription. React hooks: useGenerateImage, useGenerateAudio,
+  useGenerateSpeech, useTranscription, useGenerateVideo.
   TanStack Start server function integration with toServerSentEventsResponse.
 type: sub-skill
 library: tanstack-ai
@@ -14,9 +15,11 @@ sources:
   - 'TanStack/ai:docs/media/generations.md'
   - 'TanStack/ai:docs/media/generation-hooks.md'
   - 'TanStack/ai:docs/media/image-generation.md'
+  - 'TanStack/ai:docs/media/audio-generation.md'
   - 'TanStack/ai:docs/media/video-generation.md'
   - 'TanStack/ai:docs/media/text-to-speech.md'
   - 'TanStack/ai:docs/media/transcription.md'
+  - 'TanStack/ai:docs/advanced/debug-logging.md'
 ---
 
 # Media Generation
@@ -186,7 +189,40 @@ Result shape: `ImageGenerationResult` with `images` array where each entry
 has `b64Json?`, `url?`, and `revisedPrompt?`. OpenAI image URLs expire
 after 1 hour -- download or display immediately.
 
-### 2. Text-to-Speech
+### 2. Audio Generation (Music, Sound Effects)
+
+Distinct from TTS — `generateAudio()` produces non-speech audio content.
+Supported adapters: `geminiAudio` (Lyria 3 Pro / Lyria 3 Clip) and
+`falAudio` (MiniMax Music, DiffRhythm, Stable Audio, ElevenLabs SFX, etc.).
+
+```typescript
+import { generateAudio } from '@tanstack/ai'
+import { falAudio } from '@tanstack/ai-fal'
+
+const result = await generateAudio({
+  adapter: falAudio('fal-ai/diffrhythm'),
+  prompt: 'An upbeat electronic track with synths',
+  duration: 10,
+})
+
+// result.audio.url or result.audio.b64Json (provider-dependent)
+// result.audio.contentType e.g. "audio/mpeg"
+```
+
+Client hook:
+
+```tsx
+import { useGenerateAudio, fetchServerSentEvents } from '@tanstack/ai-react'
+
+const { generate, result, isLoading } = useGenerateAudio({
+  connection: fetchServerSentEvents('/api/generate/audio'),
+})
+
+// Trigger: generate({ prompt: 'Upbeat synths', duration: 10 })
+// Play:    <audio src={result.audio.url} controls />
+```
+
+### 3. Text-to-Speech
 
 Adapter: `openaiSpeech` (tts-1, tts-1-hd, gpt-4o-audio-preview).
 
@@ -220,7 +256,7 @@ const { generate, result, isLoading } = useGenerateSpeech({
 // Play:   <audio src={`data:audio/${result.format};base64,${result.audio}`} controls />
 ```
 
-### 3. Audio Transcription
+### 4. Audio Transcription
 
 Adapter: `openaiTranscription` (whisper-1, gpt-4o-transcribe,
 gpt-4o-mini-transcribe).
@@ -257,7 +293,7 @@ const { generate, result, isLoading } = useTranscription({
 // Trigger: generate({ audio: dataUrl, language: 'en' })
 ```
 
-### 4. Video Generation (Experimental -- async polling)
+### 5. Video Generation (Experimental -- async polling)
 
 Video generation uses a jobs/polling architecture. The server creates a job,
 polls for status, and streams updates to the client.
@@ -454,12 +490,116 @@ for (const img of result.images) {
 Not all generation activities support streaming. Passing `stream: true` to
 an activity that does not support it may hang or produce unexpected results.
 Check the activity documentation before enabling streaming. All built-in
-activities (`generateImage`, `generateSpeech`, `generateTranscription`,
-`generateVideo`, `summarize`) support `stream: true`, but custom
-`useGeneration` setups may not.
+activities (`generateImage`, `generateAudio`, `generateSpeech`,
+`generateTranscription`, `generateVideo`, `summarize`) support `stream: true`,
+but custom `useGeneration` setups may not.
 
 > Source: docs/media/generations.md.
 
+### e. HIGH: Passing `responseMimeType` or `negativePrompt` to Gemini Lyria
+
+Gemini's `GenerateContentConfig` (used by Lyria 3 Pro / Lyria 3 Clip) does
+**not** support `responseMimeType` or `negativePrompt`. Lyria 3 Clip always
+returns 30-second `audio/mp3`; Lyria 3 Pro returns `audio/mp3`. These fields
+are not in `GeminiAudioProviderOptions` — don't reach for them via `as any`.
+
+```typescript
+// WRONG — both fields are silently ignored or rejected by the SDK
+generateAudio({
+  adapter: geminiAudio('lyria-3-pro-preview'),
+  prompt: 'ambient piano',
+  modelOptions: {
+    responseMimeType: 'audio/wav', // unsupported
+    negativePrompt: 'vocals', // unsupported
+  } as any,
+})
+
+// CORRECT — shape the prompt itself for what you want
+generateAudio({
+  adapter: geminiAudio('lyria-3-pro-preview'),
+  prompt: 'ambient piano, no vocals',
+})
+```
+
+> Source: Gemini API `GenerateContentConfig` type; docs/media/audio-generation.md.
+
+### f. MEDIUM: Passing `duration` to Lyria expecting it to control length
+
+Lyria 3 Clip is fixed at 30 seconds — the `duration` option is ignored on
+that model. Lyria 3 Pro accepts duration via natural-language in the
+**prompt** ("2-minute ambient track with a 30-second build"), not via the
+`duration` field. `duration` works for fal audio models (mapped to each
+model's native field like `music_length_ms` or `seconds_total`), but not
+for Lyria.
+
+```typescript
+// For Lyria: put length guidance in the prompt
+generateAudio({
+  adapter: geminiAudio('lyria-3-pro-preview'),
+  prompt: 'A 2-minute ambient piano piece with gentle strings',
+  // duration: 120  // ← does nothing; rely on the prompt
+})
+
+// For fal: duration works and is translated per-model
+generateAudio({
+  adapter: falAudio('fal-ai/minimax-music/v2'),
+  prompt: 'upbeat synth melody',
+  duration: 60, // → music_length_ms: 60_000
+})
+```
+
+> Source: Google Lyria 3 docs; docs/media/audio-generation.md.
+
+### g. MEDIUM: Gemini TTS multi-speaker with 0 or 3+ speakers
+
+`multiSpeakerVoiceConfig.speakerVoiceConfigs` is validated to be length 1 or 2. Passing an empty array or three+ entries throws at the adapter boundary
+(not at Gemini's API) with a clear error. Don't try to work around it with
+`as any`.
+
+```typescript
+generateSpeech({
+  adapter: geminiSpeech('gemini-2.5-pro-preview-tts'),
+  text: '[Alice] Hi. [Bob] Hello!',
+  modelOptions: {
+    multiSpeakerVoiceConfig: {
+      speakerVoiceConfigs: [
+        {
+          speaker: 'Alice',
+          voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Kore' } },
+        },
+        {
+          speaker: 'Bob',
+          voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Puck' } },
+        },
+      ],
+    },
+  },
+})
+```
+
+> Source: Gemini TTS adapter validation; CodeRabbit review of PR #463.
+
+### h. LOW: Writing a logging middleware to see media chunks flow through
+
+Every media activity — `generateAudio`, `generateSpeech`,
+`generateTranscription`, `generateImage`, `generateVideo` — accepts the
+same `debug?: DebugOption` option that `chat()` does. Reach for `debug`
+instead of wiring up logging middleware.
+
+```typescript
+// When a speech generation sounds wrong or a transcription returns garbage
+generateSpeech({
+  adapter: openaiSpeech('tts-1'),
+  text: 'Hello',
+  debug: { provider: true, output: true }, // raw SDK chunks + yielded chunks
+})
+```
+
+See the `ai-core/debug-logging` sub-skill for full details on categories
+and piping into a custom logger.
+
+> Source: docs/advanced/debug-logging.md.
+
 ---
 
 ## Cross-References
@@ -469,3 +609,7 @@ activities (`generateImage`, `generateSpeech`, `generateTranscription`,
   images, `openaiSpeech` for speech, `openaiTranscription` for transcription,
   `openaiVideo` for video). The adapter-configuration skill covers provider
   setup, API keys, and model selection.
+- See also: **ai-core/debug-logging/SKILL.md** -- When a media request
+  returns unexpected output or fails mid-stream, toggle `debug: true` on
+  any `generate*()` call to see request metadata, raw provider chunks, and
+  errors. Covers per-category toggling and piping into pino/winston.