@tanstack/ai 0.12.0 → 0.13.0

package/src/activities/generateVideo/index.ts

@@ -8,6 +8,9 @@
  */
 
 import { aiEventClient } from '@tanstack/ai-event-client'
+import { resolveDebugOption } from '../../logger/resolve'
+import type { InternalLogger } from '../../logger/internal-logger'
+import type { DebugOption } from '../../logger/types'
 import type { VideoAdapter } from './adapter'
 import type {
   StreamChunk,
@@ -100,6 +103,12 @@ export type VideoCreateOptions<
   maxDuration?: number
   /** Custom run ID (stream mode only) */
   runId?: string
+  /**
+   * Enable debug logging. Pass `true` to enable all categories, `false` to
+   * silence everything including errors, or a `DebugConfig` object for granular
+   * control and/or a custom `Logger`.
+   */
+  debug?: DebugOption
 } & ({} extends VideoProviderOptions<TAdapter>
     ? {
         /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>
@@ -241,14 +250,38 @@ async function runCreateVideoJob<
 >(options: VideoCreateOptions<TAdapter, boolean>): Promise<VideoJobResult> {
   const { adapter, prompt, size, duration, modelOptions } = options
   const model = adapter.model
-
-  return adapter.createVideoJob({
+  const logger: InternalLogger = resolveDebugOption(options.debug)
+  const providerName =
+    (adapter as { name?: string; provider?: string }).provider ??
+    (adapter as { name?: string }).name ??
+    'unknown'
+
+  logger.request(`activity=generateVideo provider=${providerName}`, {
+    provider: providerName,
     model,
-    prompt,
-    size,
-    duration,
-    modelOptions,
   })
+
+  try {
+    const result = await adapter.createVideoJob({
+      model,
+      prompt,
+      size,
+      duration,
+      modelOptions,
+      logger,
+    })
+    logger.output(`activity=generateVideo jobId=${result.jobId}`, {
+      jobId: result.jobId,
+      model: result.model,
+    })
+    return result
+  } catch (error) {
+    logger.errors('generateVideo activity failed', {
+      error,
+      source: 'generateVideo',
+    })
+    throw error
+  }
 }
 
 function sleep(ms: number): Promise<void> {
@@ -267,6 +300,11 @@ async function* runStreamingVideoGeneration<
   const runId = options.runId ?? createId('run')
   const pollingInterval = options.pollingInterval ?? 2000
   const maxDuration = options.maxDuration ?? 600_000
+  const logger: InternalLogger = resolveDebugOption(options.debug)
+  const providerName =
+    (adapter as { name?: string; provider?: string }).provider ??
+    (adapter as { name?: string }).name ??
+    'unknown'
 
   const threadId = createId('thread')
 
@@ -277,6 +315,14 @@ async function* runStreamingVideoGeneration<
     timestamp: Date.now(),
   } as StreamChunk
 
+  logger.request(
+    `activity=generateVideo provider=${providerName} stream=true`,
+    {
+      provider: providerName,
+      model,
+    },
+  )
+
   try {
     // Create the video generation job
     const jobResult = await adapter.createVideoJob({
@@ -285,6 +331,7 @@ async function* runStreamingVideoGeneration<
       size,
       duration,
       modelOptions,
+      logger,
     })
 
     yield {
@@ -316,6 +363,14 @@ async function* runStreamingVideoGeneration<
       if (statusResult.status === 'completed') {
         const urlResult = await adapter.getVideoUrl(jobResult.jobId)
 
+        logger.output(
+          `activity=generateVideo jobId=${jobResult.jobId} status=completed`,
+          {
+            jobId: jobResult.jobId,
+            url: urlResult.url,
+          },
+        )
+
         yield {
           type: 'CUSTOM',
           name: 'generation:result',
@@ -345,6 +400,10 @@ async function* runStreamingVideoGeneration<
 
     throw new Error('Video generation timed out')
   } catch (error: any) {
+    logger.errors('generateVideo activity failed', {
+      error,
+      source: 'generateVideo',
+    })
     yield {
       type: 'RUN_ERROR',
       runId,

package/src/activities/summarize/index.ts

@@ -7,6 +7,9 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
+import { resolveDebugOption } from '../../logger/resolve'
+import type { InternalLogger } from '../../logger/internal-logger'
+import type { DebugOption } from '../../logger/types'
 import type { SummarizeAdapter } from './adapter'
 import type {
   StreamChunk,
@@ -66,6 +69,12 @@ export interface SummarizeActivityOptions<
    * @default false
    */
   stream?: TStream
+  /**
+   * Enable debug logging. Pass `true` to enable all categories, `false` to
+   * silence everything including errors, or a `DebugConfig` object for granular
+   * control and/or a custom `Logger`.
+   */
+  debug?: DebugOption
 }
 
 // ===========================
@@ -180,6 +189,7 @@ async function runSummarize(
   const requestId = createId('summarize')
   const inputLength = text.length
   const startTime = Date.now()
+  const logger: InternalLogger = resolveDebugOption(options.debug)
 
   aiEventClient.emit('summarize:request:started', {
     requestId,
@@ -189,30 +199,50 @@ async function runSummarize(
     timestamp: startTime,
   })
 
+  logger.request(`activity=summarize provider=${adapter.name}`, {
+    provider: adapter.name,
+    model,
+    inputLength,
+  })
+
   const summarizeOptions: SummarizationOptions = {
     model,
     text,
     maxLength,
     style,
     focus,
+    logger,
   }
 
-  const result = await adapter.summarize(summarizeOptions)
+  try {
+    const result = await adapter.summarize(summarizeOptions)
 
-  const duration = Date.now() - startTime
-  const outputLength = result.summary.length
+    const duration = Date.now() - startTime
+    const outputLength = result.summary.length
 
-  aiEventClient.emit('summarize:request:completed', {
-    requestId,
-    provider: adapter.name,
-    model,
-    inputLength,
-    outputLength,
-    duration,
-    timestamp: Date.now(),
-  })
+    aiEventClient.emit('summarize:request:completed', {
+      requestId,
+      provider: adapter.name,
+      model,
+      inputLength,
+      outputLength,
+      duration,
+      timestamp: Date.now(),
+    })
+
+    logger.output(`activity=summarize length=${outputLength}`, {
+      hasSummary: !!result.summary,
+      outputLength,
+    })
 
-  return result
+    return result
+  } catch (error) {
+    logger.errors('summarize activity failed', {
+      error,
+      source: 'summarize',
+    })
+    throw error
+  }
 }
 
 /**
@@ -225,6 +255,13 @@ async function* runStreamingSummarize(
 ): AsyncIterable<StreamChunk> {
   const { adapter, text, maxLength, style, focus } = options
   const model = adapter.model
+  const logger: InternalLogger = resolveDebugOption(options.debug)
+
+  logger.request(`activity=summarize provider=${adapter.name}`, {
+    provider: adapter.name,
+    model,
+    stream: true,
+  })
 
   const summarizeOptions: SummarizationOptions = {
     model,
@@ -232,16 +269,25 @@ async function* runStreamingSummarize(
     maxLength,
     style,
     focus,
+    logger,
   }
 
-  // Use real streaming if the adapter supports it
-  if (adapter.summarizeStream) {
-    yield* adapter.summarizeStream(summarizeOptions)
-    return
-  }
+  try {
+    // Use real streaming if the adapter supports it
+    if (adapter.summarizeStream) {
+      yield* adapter.summarizeStream(summarizeOptions)
+      return
+    }
 
-  // Fall back to non-streaming — wrap result with streamGenerationResult
-  yield* streamGenerationResult(() => adapter.summarize(summarizeOptions))
+    // Fall back to non-streaming — wrap result with streamGenerationResult
+    yield* streamGenerationResult(() => adapter.summarize(summarizeOptions))
+  } catch (error) {
+    logger.errors('summarize activity failed', {
+      error,
+      source: 'summarize',
+    })
+    throw error
+  }
 }
 
 // ===========================

package/src/adapter-internals.ts

@@ -0,0 +1,7 @@
+// NOTE: This module is exposed ONLY via the `@tanstack/ai/adapter-internals`
+// subpath export. It gives provider adapter packages access to the internal
+// logger plumbing without leaking those symbols to end users.
+
+export type { ResolvedCategories } from './logger/internal-logger'
+export { InternalLogger } from './logger/internal-logger'
+export { resolveDebugOption } from './logger/resolve'

package/src/index.ts

@@ -167,3 +167,12 @@ export type {
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
 export type { ExtendedModelDef } from './extend-adapter'
+
+// Logger
+export type {
+  Logger,
+  DebugCategories,
+  DebugConfig,
+  DebugOption,
+} from './logger/types'
+export { ConsoleLogger } from './logger/console-logger'

package/src/logger/console-logger.ts

@@ -0,0 +1,49 @@
+import type { Logger } from './types'
+
+/**
+ * Default `Logger` implementation that routes each level to the matching
+ * `console` method:
+ *
+ * - `debug` → `console.debug`
+ * - `info` → `console.info`
+ * - `warn` → `console.warn`
+ * - `error` → `console.error`
+ *
+ * When a `meta` object is supplied, the message is logged first and the meta
+ * object is then printed via `console.dir(meta, { depth: null, colors: true })`
+ * so deeply nested structures (e.g. provider chunk payloads with `usage`,
+ * `output`, `reasoning`, `tools`) render in full instead of truncating to
+ * `[Object]` / `[Array]`. On Node this produces a depth-unlimited inspect
+ * dump; browsers present the object as an interactive tree (extra options
+ * are ignored).
+ *
+ * This is the logger used when `debug` is enabled on any activity and no
+ * custom `logger` is supplied via `debug: { logger }`.
+ */
+const DIR_OPTIONS = { depth: null, colors: true } as const
+
+export class ConsoleLogger implements Logger {
+  /** Log a debug-level message; forwards to `console.debug`. */
+  debug(message: string, meta?: Record<string, unknown>): void {
+    console.debug(message)
+    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+  }
+
+  /** Log an info-level message; forwards to `console.info`. */
+  info(message: string, meta?: Record<string, unknown>): void {
+    console.info(message)
+    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+  }
+
+  /** Log a warning-level message; forwards to `console.warn`. */
+  warn(message: string, meta?: Record<string, unknown>): void {
+    console.warn(message)
+    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+  }
+
+  /** Log an error-level message; forwards to `console.error`. */
+  error(message: string, meta?: Record<string, unknown>): void {
+    console.error(message)
+    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+  }
+}

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/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,6 +1212,11 @@ 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
 }
 
 /**
@@ -1254,6 +1273,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 +1343,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 +1392,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
 }
 
 /**