@tanstack/ai 0.12.0 → 0.14.0

package/src/activities/generateTranscription/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 { TranscriptionAdapter } from './adapter'
 import type { StreamChunk, TranscriptionResult } from '../../types'
 
@@ -41,7 +44,10 @@ export type TranscriptionProviderOptions<TAdapter> =
  * @template TStream - Whether to stream the output
  */
 export interface TranscriptionActivityOptions<
-  TAdapter extends TranscriptionAdapter<string, object>,
+  TAdapter extends TranscriptionAdapter<
+    string,
+    TranscriptionProviderOptions<TAdapter>
+  >,
   TStream extends boolean = false,
 > {
   /** The transcription adapter to use (must be created with a model) */
@@ -64,6 +70,12 @@ export interface TranscriptionActivityOptions<
    * @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
 }
 
 // ===========================
@@ -132,7 +144,10 @@ function createId(prefix: string): string {
  * ```
  */
 export function generateTranscription<
-  TAdapter extends TranscriptionAdapter<string, object>,
+  TAdapter extends TranscriptionAdapter<
+    string,
+    TranscriptionProviderOptions<TAdapter>
+  >,
   TStream extends boolean = false,
 >(
   options: TranscriptionActivityOptions<TAdapter, TStream>,
@@ -152,14 +167,22 @@ export function generateTranscription<
  * Run non-streaming transcription
  */
 async function runGenerateTranscription<
-  TAdapter extends TranscriptionAdapter<string, object>,
+  TAdapter extends TranscriptionAdapter<
+    string,
+    TranscriptionProviderOptions<TAdapter>
+  >,
 >(
   options: TranscriptionActivityOptions<TAdapter, boolean>,
 ): Promise<TranscriptionResult> {
-  const { adapter, stream: _stream, ...rest } = options
+  const { adapter, stream: _stream, debug: _debug, ...rest } = options
   const model = adapter.model
   const requestId = createId('transcription')
   const startTime = Date.now()
+  const logger: InternalLogger = resolveDebugOption(options.debug)
+  const providerName =
+    (adapter as { name?: string; provider?: string }).provider ??
+    (adapter as { name?: string }).name ??
+    'unknown'
 
   aiEventClient.emit('transcription:request:started', {
     requestId,
@@ -172,21 +195,50 @@ async function runGenerateTranscription<
     timestamp: startTime,
   })
 
-  const result = await adapter.transcribe({ ...rest, model })
-  const duration = Date.now() - startTime
-
-  aiEventClient.emit('transcription:request:completed', {
-    requestId,
-    provider: adapter.name,
+  logger.request(`activity=generateTranscription provider=${providerName}`, {
+    provider: providerName,
     model,
-    text: result.text,
-    language: result.language,
-    duration,
-    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
-    timestamp: Date.now(),
   })
 
-  return result
+  try {
+    const result = await adapter.transcribe({ ...rest, model, logger })
+    const duration = Date.now() - startTime
+
+    aiEventClient.emit('transcription:request:completed', {
+      requestId,
+      provider: adapter.name,
+      model,
+      text: result.text,
+      language: result.language,
+      duration,
+      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+      timestamp: Date.now(),
+    })
+
+    logger.output(
+      `activity=generateTranscription length=${result.text.length}`,
+      { hasText: !!result.text },
+    )
+
+    return result
+  } catch (error) {
+    const duration = Date.now() - startTime
+    const err = error as Error
+    aiEventClient.emit('transcription:request:error', {
+      requestId,
+      provider: adapter.name,
+      model,
+      error: { message: err.message, name: err.name },
+      duration,
+      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+      timestamp: Date.now(),
+    })
+    logger.errors('generateTranscription activity failed', {
+      error,
+      source: 'generateTranscription',
+    })
+    throw error
+  }
 }
 
 // ===========================
@@ -197,7 +249,10 @@ async function runGenerateTranscription<
  * Create typed options for the generateTranscription() function without executing.
  */
 export function createTranscriptionOptions<
-  TAdapter extends TranscriptionAdapter<string, object>,
+  TAdapter extends TranscriptionAdapter<
+    string,
+    TranscriptionProviderOptions<TAdapter>
+  >,
   TStream extends boolean = false,
 >(
   options: TranscriptionActivityOptions<TAdapter, TStream>,

package/src/activities/generateVideo/index.ts

@@ -8,6 +8,10 @@
  */
 
 import { aiEventClient } from '@tanstack/ai-event-client'
+import { toRunErrorPayload } from '../error-payload'
+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 +104,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 +251,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 +301,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 +316,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 +332,7 @@ async function* runStreamingVideoGeneration<
       size,
       duration,
       modelOptions,
+      logger,
     })
 
     yield {
@@ -316,6 +364,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',
@@ -344,17 +400,20 @@ async function* runStreamingVideoGeneration<
     }
 
     throw new Error('Video generation timed out')
-  } catch (error: any) {
+  } catch (error: unknown) {
+    const payload = toRunErrorPayload(error, 'Video generation failed')
+    logger.errors('generateVideo activity failed', {
+      message: payload.message,
+      code: payload.code,
+      source: 'generateVideo',
+    })
     yield {
       type: 'RUN_ERROR',
       runId,
       threadId,
-      message: error.message || 'Video generation failed',
-      code: error.code,
-      error: {
-        message: error.message || 'Video generation failed',
-        code: error.code,
-      },
+      message: payload.message,
+      code: payload.code,
+      error: payload,
       timestamp: Date.now(),
     } as StreamChunk
   }

package/src/activities/index.ts

@@ -17,6 +17,7 @@
 import type { AnyTextAdapter } from './chat/adapter'
 import type { AnySummarizeAdapter } from './summarize/adapter'
 import type { AnyImageAdapter } from './generateImage/adapter'
+import type { AnyAudioAdapter } from './generateAudio/adapter'
 import type { AnyVideoAdapter } from './generateVideo/adapter'
 import type { AnyTTSAdapter } from './generateSpeech/adapter'
 import type { AnyTranscriptionAdapter } from './generateTranscription/adapter'
@@ -80,6 +81,25 @@ export {
   type AnyImageAdapter,
 } from './generateImage/adapter'
 
+// ===========================
+// Audio Activity
+// ===========================
+
+export {
+  kind as audioKind,
+  generateAudio,
+  type AudioActivityOptions,
+  type AudioActivityResult,
+  type AudioProviderOptions,
+} from './generateAudio/index'
+
+export {
+  BaseAudioAdapter,
+  type AudioAdapter,
+  type AudioAdapterConfig,
+  type AnyAudioAdapter,
+} from './generateAudio/adapter'
+
 // ===========================
 // Video Activity (Experimental)
 // ===========================
@@ -150,6 +170,7 @@ export type AIAdapter =
   | AnyTextAdapter
   | AnySummarizeAdapter
   | AnyImageAdapter
+  | AnyAudioAdapter
   | AnyVideoAdapter
   | AnyTTSAdapter
   | AnyTranscriptionAdapter
@@ -159,6 +180,7 @@ export type AdapterKind =
   | 'text'
   | 'summarize'
   | 'image'
+  | 'audio'
   | 'video'
   | 'tts'
   | 'transcription'

package/src/activities/stream-generation-result.ts

@@ -5,6 +5,7 @@
  */
 
 import { EventType } from '@ag-ui/core'
+import { toRunErrorPayload } from './error-payload'
 import type { StreamChunk } from '../types'
 
 function createId(prefix: string): string {
@@ -52,18 +53,16 @@ export async function* streamGenerationResult<TResult>(
       finishReason: 'stop',
       timestamp: Date.now(),
     } as StreamChunk
-  } catch (error: any) {
+  } catch (error: unknown) {
+    const payload = toRunErrorPayload(error, 'Generation failed')
     yield {
       type: EventType.RUN_ERROR,
       runId,
       threadId,
-      message: error.message || 'Generation failed',
-      code: error.code,
+      message: payload.message,
+      code: payload.code,
       // Deprecated nested form for backward compatibility
-      error: {
-        message: error.message || 'Generation failed',
-        code: error.code,
-      },
+      error: payload,
       timestamp: Date.now(),
     } as StreamChunk
   }

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,8 @@
+// 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'
+export { toRunErrorPayload } from './activities/error-payload'

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   chat,
   summarize,
   generateImage,
+  generateAudio,
   generateVideo,
   getVideoJobStatus,
   generateSpeech,
@@ -13,6 +14,7 @@ export {
 export { createChatOptions } from './activities/chat/index'
 export { createSummarizeOptions } from './activities/summarize/index'
 export { createImageOptions } from './activities/generateImage/index'
+export { createAudioOptions } from './activities/generateAudio/index'
 export { createVideoOptions } from './activities/generateVideo/index'
 export { createSpeechOptions } from './activities/generateSpeech/index'
 export { createTranscriptionOptions } from './activities/generateTranscription/index'
@@ -26,6 +28,8 @@ export type {
   AnyTextAdapter,
   AnySummarizeAdapter,
   SummarizeAdapter,
+  AnyAudioAdapter,
+  AudioAdapter,
   AnyTTSAdapter,
   TTSAdapter,
   AnyTranscriptionAdapter,
@@ -167,3 +171,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)
+  }
+}