@tanstack/ai 0.12.0 → 0.14.0

package/src/logger/internal-logger.ts

@@ -0,0 +1,107 @@
+import type { DebugCategories, Logger } from './types'
+
+/**
+ * Fully-resolved categories map. Every flag is a definite boolean (never
+ * undefined), produced by `resolveDebugOption` from a `DebugOption`.
+ */
+export type ResolvedCategories = Required<DebugCategories>
+
+/**
+ * Package-internal logger wrapper used by every activity and adapter in
+ * `@tanstack/ai`. Wraps a user-supplied (or default `ConsoleLogger`) `Logger`
+ * plus a fully-resolved per-category map. Each category has a dedicated
+ * method that no-ops when its flag is `false`, or prepends a
+ * `[tanstack-ai:<category>] ` prefix and calls the underlying logger's
+ * `error` (for the `errors` category) or `debug` (for everything else).
+ *
+ * Not exported from the package root. Adapter packages consume it via the
+ * `@tanstack/ai/adapter-internals` subpath export.
+ */
+/**
+ * Emoji marker per category — bracketing the `[tanstack-ai:<cat>]` tag on
+ * both sides makes it trivial to visually pick out a category when scanning
+ * dense streaming logs.
+ */
+const CATEGORY_EMOJI: Record<keyof ResolvedCategories, string> = {
+  request: '📤',
+  provider: '📥',
+  output: '📨',
+  middleware: '🧩',
+  tools: '🔧',
+  agentLoop: '🔁',
+  config: '⚙️',
+  errors: '❌',
+}
+
+export class InternalLogger {
+  constructor(
+    private readonly logger: Logger,
+    private readonly categories: ResolvedCategories,
+  ) {}
+
+  /** Whether a category is enabled. Cheap, safe to call on hot paths. */
+  isEnabled(category: keyof ResolvedCategories): boolean {
+    return this.categories[category]
+  }
+
+  private emit(
+    level: 'debug' | 'error',
+    category: keyof ResolvedCategories,
+    message: string,
+    meta?: Record<string, unknown>,
+  ): void {
+    if (!this.categories[category]) return
+    const emoji = CATEGORY_EMOJI[category]
+    const prefixed = `${emoji} [tanstack-ai:${category}] ${emoji} ${message}`
+    try {
+      if (level === 'error') this.logger.error(prefixed, meta)
+      else this.logger.debug(prefixed, meta)
+    } catch {
+      // User-supplied logger threw; swallow so we never mask the original
+      // error that triggered this log call.
+    }
+  }
+
+  /** Log a raw chunk/frame received from a provider SDK. */
+  provider(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'provider', message, meta)
+  }
+
+  /** Log a chunk/result yielded to the consumer after middleware. */
+  output(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'output', message, meta)
+  }
+
+  /** Log inputs/outputs around a middleware hook invocation. Chat-only. */
+  middleware(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'middleware', message, meta)
+  }
+
+  /** Log before/after a tool-call execution. Chat-only. */
+  tools(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'tools', message, meta)
+  }
+
+  /** Log an agent-loop iteration marker or phase transition. Chat-only. */
+  agentLoop(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'agentLoop', message, meta)
+  }
+
+  /** Log a config transform returned by a middleware `onConfig` hook. Chat-only. */
+  config(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'config', message, meta)
+  }
+
+  /**
+   * Log a caught error. Defaults to on even when `debug` is unspecified.
+   * Uses the underlying logger's `error` level.
+   */
+  errors(message: string, meta?: Record<string, unknown>): void {
+    this.emit('error', 'errors', message, meta)
+  }
+
+  /** Log outgoing request metadata before an adapter SDK call. */
+  request(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'request', message, meta)
+  }
+}

package/src/logger/resolve.ts

@@ -0,0 +1,72 @@
+import { ConsoleLogger } from './console-logger'
+import { InternalLogger } from './internal-logger'
+import type { ResolvedCategories } from './internal-logger'
+import type { DebugCategories, DebugConfig, DebugOption, Logger } from './types'
+
+const ALL_OFF: ResolvedCategories = {
+  provider: false,
+  output: false,
+  middleware: false,
+  tools: false,
+  agentLoop: false,
+  config: false,
+  errors: false,
+  request: false,
+}
+
+const ALL_ON: ResolvedCategories = {
+  provider: true,
+  output: true,
+  middleware: true,
+  tools: true,
+  agentLoop: true,
+  config: true,
+  errors: true,
+  request: true,
+}
+
+const errorsOnlyCategories = (): ResolvedCategories => ({
+  ...ALL_OFF,
+  errors: true,
+})
+
+const resolveCategoriesFromPartial = (
+  partial: DebugCategories,
+): ResolvedCategories => ({
+  provider: partial.provider ?? true,
+  output: partial.output ?? true,
+  middleware: partial.middleware ?? true,
+  tools: partial.tools ?? true,
+  agentLoop: partial.agentLoop ?? true,
+  config: partial.config ?? true,
+  errors: partial.errors ?? true,
+  request: partial.request ?? true,
+})
+
+/**
+ * Normalize a `DebugOption` into an `InternalLogger` ready to be threaded
+ * through the library's activities and adapters. See the `DebugOption`
+ * resolution table in the spec for the complete rules.
+ *
+ * - `undefined`: only the `errors` category is enabled; default `ConsoleLogger`.
+ * - `true`: all categories enabled; default `ConsoleLogger`.
+ * - `false`: all categories disabled (including `errors`); default `ConsoleLogger`.
+ * - `DebugConfig`: each unspecified category defaults to `true`; an optional
+ *   `logger` replaces the default `ConsoleLogger`.
+ */
+export function resolveDebugOption(
+  debug: DebugOption | undefined,
+): InternalLogger {
+  if (debug === undefined) {
+    return new InternalLogger(new ConsoleLogger(), errorsOnlyCategories())
+  }
+  if (debug === true) {
+    return new InternalLogger(new ConsoleLogger(), ALL_ON)
+  }
+  if (debug === false) {
+    return new InternalLogger(new ConsoleLogger(), ALL_OFF)
+  }
+  const { logger, ...cats }: DebugConfig = debug
+  const userLogger: Logger = logger ?? new ConsoleLogger()
+  return new InternalLogger(userLogger, resolveCategoriesFromPartial(cats))
+}

package/src/logger/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Pluggable logger interface consumed by every `@tanstack/ai` activity when `debug` is enabled. Supply a custom implementation via `debug: { logger }` on `chat()`, `summarize()`, `generateImage()`, etc. The four methods correspond to log levels: use `debug` for chunk-level diagnostic output, `info`/`warn` for notable events, `error` for caught exceptions.
+ */
+export interface Logger {
+  /**
+   * Called for chunk-level diagnostic output (raw provider chunks, per-chunk output, agent-loop iteration markers).
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+   */
+  debug: (message: string, meta?: Record<string, unknown>) => void
+  /**
+   * Called for notable informational events (outgoing requests, tool invocations, middleware transitions).
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+   */
+  info: (message: string, meta?: Record<string, unknown>) => void
+  /**
+   * Called for notable warnings that don't halt execution (deprecations, recoverable anomalies).
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+   */
+  warn: (message: string, meta?: Record<string, unknown>) => void
+  /**
+   * Called for caught exceptions throughout the pipeline.
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+   */
+  error: (message: string, meta?: Record<string, unknown>) => void
+}
+
+/**
+ * Per-category toggles for debug logging. Each flag enables or disables one class of log message. Unspecified flags default to `true` when `DebugConfig` is partially specified; `undefined` on the `debug` option defaults all flags to `false` except `errors`.
+ */
+export interface DebugCategories {
+  /**
+   * Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollama, Grok, Groq, OpenRouter, fal, ElevenLabs). Emitted inside every streaming adapter's chunk loop.
+   */
+  provider?: boolean
+  /**
+   * Chunks/results yielded to the consumer after all middleware. For streaming activities this fires per chunk; for non-streaming activities it fires once per result.
+   */
+  output?: boolean
+  /**
+   * Inputs and outputs around each middleware hook invocation. Chat-only.
+   */
+  middleware?: boolean
+  /**
+   * Before/after tool-call execution in the chat agent loop. Chat-only.
+   */
+  tools?: boolean
+  /**
+   * Iteration markers and phase transitions in the chat agent loop. Chat-only.
+   */
+  agentLoop?: boolean
+  /**
+   * Config transforms returned by middleware `onConfig` hooks. Chat-only.
+   */
+  config?: boolean
+  /**
+   * Caught errors throughout the pipeline. Unlike other categories, defaults to `true` even when `debug` is unspecified. Explicitly set `errors: false` or `debug: false` to silence.
+   */
+  errors?: boolean
+  /**
+   * Outgoing call metadata (provider, model, message/tool counts) emitted before each adapter SDK call.
+   */
+  request?: boolean
+}
+
+/**
+ * Granular debug configuration combining per-category toggles with an optional custom logger. Any unspecified category flag defaults to `true`.
+ */
+export interface DebugConfig extends DebugCategories {
+  /**
+   * Custom `Logger` implementation. When omitted, a default `ConsoleLogger` routes output to `console.debug`/`info`/`warn`/`error`.
+   */
+  logger?: Logger
+}
+
+/**
+ * The shape accepted by the `debug` option on every `@tanstack/ai` activity. Pass `true` to enable all categories with the default console logger; `false` to silence everything including errors; an object for granular control.
+ */
+export type DebugOption = boolean | DebugConfig

package/src/stream-to-response.ts

@@ -1,3 +1,4 @@
+import { toRunErrorPayload } from './activities/error-payload'
 import type { StreamChunk } from './types'
 
 /**
@@ -68,7 +69,7 @@ export function toServerSentEventsStream(
         }
 
         controller.close()
-      } catch (error: any) {
+      } catch (error: unknown) {
         // Don't send error if aborted
         if (abortController?.signal.aborted) {
           controller.close()
@@ -81,10 +82,7 @@ export function toServerSentEventsStream(
             `data: ${JSON.stringify({
               type: 'RUN_ERROR',
               timestamp: Date.now(),
-              error: {
-                message: error.message || 'Unknown error occurred',
-                code: error.code,
-              },
+              error: toRunErrorPayload(error),
             })}\n\n`,
           ),
         )
@@ -190,7 +188,7 @@ export function toHttpStream(
         }
 
         controller.close()
-      } catch (error: any) {
+      } catch (error: unknown) {
         // Don't send error if aborted
         if (abortController?.signal.aborted) {
           controller.close()
@@ -203,10 +201,7 @@ export function toHttpStream(
             `${JSON.stringify({
               type: 'RUN_ERROR',
               timestamp: Date.now(),
-              error: {
-                message: error.message || 'Unknown error occurred',
-                code: error.code,
-              },
+              error: toRunErrorPayload(error),
             })}\n`,
           ),
         )

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type { InternalLogger } from './logger/internal-logger'
 import type {
   BaseEvent as AGUIBaseEvent,
   CustomEvent as AGUICustomEvent,
@@ -738,6 +739,14 @@ export interface TextOptions<
    * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController
    */
   abortController?: AbortController
+
+  /**
+   * Internal logger threaded from the chat entry point. Adapter implementations
+   * must call `logger.request()` before SDK calls, `logger.provider()` for each
+   * chunk received, and `logger.errors()` in catch blocks.
+   */
+  logger: InternalLogger
+
   /**
    * Thread ID for AG-UI protocol run correlation.
    * When provided, this will be used in RunStartedEvent and RunFinishedEvent.
@@ -1163,6 +1172,11 @@ export interface SummarizationOptions {
   maxLength?: number
   style?: 'bullet-points' | 'paragraph' | 'concise'
   focus?: Array<string>
+  /**
+   * Internal logger threaded from the summarize() entry point. Adapters must
+   * call logger.request() before the SDK call and logger.errors() in catch blocks.
+   */
+  logger: InternalLogger
 }
 
 export interface SummarizationResult {
@@ -1198,16 +1212,35 @@ export interface ImageGenerationOptions<
   size?: TSize
   /** Model-specific options for image generation */
   modelOptions?: TProviderOptions
+  /**
+   * Internal logger threaded from the generateImage() entry point. Adapters must
+   * call logger.request() before the SDK call and logger.errors() in catch blocks.
+   */
+  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
 }
@@ -1230,6 +1263,61 @@ export interface ImageGenerationResult {
   }
 }
 
+// ============================================================================
+// Audio Generation Types
+// ============================================================================
+
+/**
+ * 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
+  }
+}
+
 // ============================================================================
 // Video Generation Types (Experimental)
 // ============================================================================
@@ -1254,6 +1342,11 @@ export interface VideoGenerationOptions<
   duration?: number
   /** Model-specific options for video generation */
   modelOptions?: TProviderOptions
+  /**
+   * Internal logger threaded from the generateVideo() entry point. Adapters must
+   * call logger.request() before the SDK call and logger.errors() in catch blocks.
+   */
+  logger: InternalLogger
 }
 
 /**
@@ -1319,6 +1412,12 @@ export interface TTSOptions<TProviderOptions extends object = object> {
   speed?: number
   /** Model-specific options for TTS generation */
   modelOptions?: TProviderOptions
+  /**
+   * Internal logger threaded from the generateSpeech() entry point. Adapters
+   * must call logger.request() before the SDK call and logger.errors() in
+   * catch blocks.
+   */
+  logger: InternalLogger
 }
 
 /**
@@ -1362,6 +1461,12 @@ export interface TranscriptionOptions<
   responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
   /** Model-specific options for transcription */
   modelOptions?: TProviderOptions
+  /**
+   * Internal logger threaded from the generateTranscription() entry point.
+   * Adapters must call logger.request() before the SDK call and logger.errors()
+   * in catch blocks.
+   */
+  logger: InternalLogger
 }
 
 /**