@tanstack/ai 0.11.1 → 0.13.0

package/src/activities/chat/index.ts

@@ -8,6 +8,7 @@
 import { devtoolsMiddleware } from '@tanstack/ai-event-client'
 import { stripToSpecMiddleware } from '../../strip-to-spec-middleware'
 import { streamToText } from '../../stream-to-response.js'
+import { resolveDebugOption } from '../../logger/resolve'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import {
   MiddlewareAbortError,
@@ -51,6 +52,9 @@ import type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
 } from './middleware/types'
+import type { InternalLogger } from '../../logger/internal-logger'
+import type { DebugOption } from '../../logger/types'
+import type { ProviderTool } from '../../tools/provider-tool'
 
 // ===========================
 // Activity Kind
@@ -87,8 +91,20 @@ export interface TextActivityOptions<
   >
   /** System prompts to prepend to the conversation */
   systemPrompts?: TextOptions['systemPrompts']
-  /** Tools for function calling (auto-executed when called) */
-  tools?: TextOptions['tools']
+  /**
+   * Tools for function calling (auto-executed when called).
+   *
+   * Accepts two shapes:
+   *  - User-defined tools via `toolDefinition()` — plain `Tool`, always assignable.
+   *  - Provider tools from `@tanstack/ai-<provider>/tools` (e.g. `webSearchTool`)
+   *    — branded and type-checked against the selected model's
+   *    `supports.tools` list. Passing an unsupported tool produces a
+   *    compile-time error on the array element.
+   */
+  tools?: Array<
+    | (Tool & { readonly '~toolKind'?: never })
+    | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>
+  >
   /** Controls the randomness of the output. Higher values make output more random. Range: [0.0, 2.0] */
   temperature?: TextOptions['temperature']
   /** Nucleus sampling parameter. The model considers tokens with topP probability mass. */
@@ -168,6 +184,13 @@ export interface TextActivityOptions<
    * Can be used to pass request-scoped data (e.g., user ID, request context).
    */
   context?: unknown
+  /**
+   * Enable debug logging. Pass `true` to enable all categories with the default
+   * console logger, `false` to silence everything, or a `DebugConfig` object for
+   * granular control and/or a custom `Logger`. Defaults to `undefined`, which
+   * means only the `errors` category is active.
+   */
+  debug?: DebugOption
 }
 
 // ===========================
@@ -280,7 +303,13 @@ class TextEngine<
   private middlewareAbortController?: AbortController
   private terminalHookCalled = false
 
-  constructor(config: TextEngineConfig<TAdapter, TParams>) {
+  private readonly logger: InternalLogger
+
+  constructor(
+    config: TextEngineConfig<TAdapter, TParams>,
+    logger: InternalLogger,
+  ) {
+    this.logger = logger
     this.adapter = config.adapter
     this.params = config.params
     this.systemPrompts = config.params.systemPrompts || []
@@ -328,7 +357,7 @@ class TextEngine<
       ...(config.middleware || []),
       stripToSpecMiddleware(),
     ]
-    this.middlewareRunner = new MiddlewareRunner(allMiddleware)
+    this.middlewareRunner = new MiddlewareRunner(allMiddleware, logger)
     this.middlewareAbortController = new AbortController()
     this.middlewareCtx = {
       requestId: this.requestId,
@@ -380,6 +409,9 @@ class TextEngine<
 
   async *run(): AsyncGenerator<StreamChunk> {
     this.beforeRun()
+    this.logger.agentLoop('run started', {
+      conversationId: this.middlewareCtx.conversationId,
+    })
 
     try {
       // Run initial onConfig (phase = init)
@@ -404,6 +436,10 @@ class TextEngine<
           return
         }
 
+        this.logger.agentLoop(`iteration=${this.middlewareCtx.iteration}`, {
+          iteration: this.middlewareCtx.iteration,
+        })
+
         await this.beginCycle()
 
         if (this.cyclePhase === 'processText') {
@@ -425,6 +461,10 @@ class TextEngine<
         this.endCycle()
       } while (this.shouldContinue())
 
+      this.logger.agentLoop('run finished', {
+        finishReason: this.lastFinishReason,
+      })
+
       // Call terminal onFinish hook (skip when waiting for client — stream is paused, not finished)
       if (!this.terminalHookCalled && this.toolPhase !== 'wait') {
         this.terminalHookCalled = true
@@ -447,6 +487,10 @@ class TextEngine<
           })
         } else {
           // Genuine error — call onError
+          this.logger.errors('chat run failed', {
+            error,
+            conversationId: this.middlewareCtx.conversationId,
+          })
           await this.middlewareRunner.runOnError(this.middlewareCtx, {
             error,
             duration: Date.now() - this.streamStartTime,
@@ -542,6 +586,18 @@ class TextEngine<
 
     this.middlewareCtx.phase = 'modelStream'
 
+    const providerName =
+      (this.adapter as { provider?: string }).provider ?? this.adapter.name
+    this.logger.request(
+      `activity=chat provider=${providerName} model=${this.params.model} messages=${this.messages.length} tools=${this.tools.length} stream=true`,
+      {
+        provider: providerName,
+        model: this.params.model,
+        messageCount: this.messages.length,
+        toolCount: this.tools.length,
+      },
+    )
+
     for await (const chunk of this.adapter.chatStream({
       model: this.params.model,
       messages: this.messages,
@@ -553,6 +609,7 @@ class TextEngine<
       request: this.effectiveRequest,
       modelOptions,
       systemPrompts: this.systemPrompts,
+      logger: this.logger,
       threadId: this.threadId,
       runId: this.runIdOverride,
     })) {
@@ -572,6 +629,7 @@ class TextEngine<
         chunk,
       )
       for (const outputChunk of outputChunks) {
+        this.logger.output(`type=${outputChunk.type}`, { chunk: outputChunk })
         yield outputChunk
         this.middlewareCtx.chunkIndex++
       }
@@ -728,6 +786,10 @@ class TextEngine<
       (eventName, data) => this.createCustomEventChunk(eventName, data),
       {
         onBeforeToolCall: async (toolCall, tool, args) => {
+          this.logger.tools(`phase=before name=${toolCall.function.name}`, {
+            name: toolCall.function.name,
+            args,
+          })
           const hookCtx = {
             toolCall,
             tool,
@@ -741,6 +803,10 @@ class TextEngine<
           )
         },
         onAfterToolCall: async (info) => {
+          this.logger.tools(`phase=after name=${info.toolName}`, {
+            name: info.toolName,
+            result: info.result,
+          })
           await this.middlewareRunner.runOnAfterToolCall(
             this.middlewareCtx,
             info,
@@ -881,6 +947,10 @@ class TextEngine<
       (eventName, data) => this.createCustomEventChunk(eventName, data),
       {
         onBeforeToolCall: async (toolCall, tool, args) => {
+          this.logger.tools(`phase=before name=${toolCall.function.name}`, {
+            name: toolCall.function.name,
+            args,
+          })
           const hookCtx = {
             toolCall,
             tool,
@@ -894,6 +964,10 @@ class TextEngine<
           )
         },
         onAfterToolCall: async (info) => {
+          this.logger.tools(`phase=after name=${info.toolName}`, {
+            name: info.toolName,
+            result: info.result,
+          })
           await this.middlewareRunner.runOnAfterToolCall(
             this.middlewareCtx,
             info,
@@ -1478,18 +1552,22 @@ export function chat<
 async function* runStreamingText(
   options: TextActivityOptions<AnyTextAdapter, undefined, true>,
 ): AsyncIterable<StreamChunk> {
-  const { adapter, middleware, context, ...textOptions } = options
+  const { adapter, middleware, context, debug, ...textOptions } = options
   const model = adapter.model
+  const logger = resolveDebugOption(debug)
 
-  const engine = new TextEngine({
-    adapter,
-    params: { ...textOptions, model } as TextOptions<
-      Record<string, any>,
-      Record<string, any>
-    >,
-    middleware,
-    context,
-  })
+  const engine = new TextEngine(
+    {
+      adapter,
+      params: { ...textOptions, model, logger } as TextOptions<
+        Record<string, any>,
+        Record<string, any>
+      >,
+      middleware,
+      context,
+    },
+    logger,
+  )
 
   for await (const chunk of engine.run()) {
     yield chunk
@@ -1520,23 +1598,28 @@ function runNonStreamingText(
 async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
   options: TextActivityOptions<AnyTextAdapter, TSchema, boolean>,
 ): Promise<InferSchemaType<TSchema>> {
-  const { adapter, outputSchema, middleware, context, ...textOptions } = options
+  const { adapter, outputSchema, middleware, context, debug, ...textOptions } =
+    options
   const model = adapter.model
+  const logger = resolveDebugOption(debug)
 
   if (!outputSchema) {
     throw new Error('outputSchema is required for structured output')
   }
 
   // Create the engine and run the agentic loop
-  const engine = new TextEngine({
-    adapter,
-    params: { ...textOptions, model } as TextOptions<
-      Record<string, unknown>,
-      Record<string, unknown>
-    >,
-    middleware,
-    context,
-  })
+  const engine = new TextEngine(
+    {
+      adapter,
+      params: { ...textOptions, model, logger } as TextOptions<
+        Record<string, unknown>,
+        Record<string, unknown>
+      >,
+      middleware,
+      context,
+    },
+    logger,
+  )
 
   // Consume the stream to run the agentic loop
   for await (const _chunk of engine.run()) {
@@ -1560,6 +1643,17 @@ async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
     throw new Error('Failed to convert output schema to JSON Schema')
   }
 
+  const providerName =
+    (adapter as { provider?: string }).provider ?? adapter.name
+  logger.request(
+    `activity=chat-structured provider=${providerName} model=${model} messages=${finalMessages.length}`,
+    {
+      provider: providerName,
+      model,
+      messageCount: finalMessages.length,
+    },
+  )
+
   // Call the adapter's structured output method with the conversation context
   // The adapter receives JSON Schema and can apply vendor-specific patches
   const result = await adapter.structuredOutput({
@@ -1567,6 +1661,7 @@ async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
       ...structuredTextOptions,
       model,
       messages: finalMessages,
+      logger,
     },
     outputSchema: jsonSchema,
   })

package/src/activities/chat/middleware/compose.ts

@@ -1,5 +1,6 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import type { StreamChunk } from '../../../types'
+import type { InternalLogger } from '../../../logger/internal-logger'
 import type {
   AbortInfo,
   AfterToolCallInfo,
@@ -36,9 +37,14 @@ function instrumentCtx(ctx: ChatMiddlewareContext) {
  */
 export class MiddlewareRunner {
   private readonly middlewares: ReadonlyArray<ChatMiddleware>
+  private readonly logger: InternalLogger
 
-  constructor(middlewares: ReadonlyArray<ChatMiddleware>) {
+  constructor(
+    middlewares: ReadonlyArray<ChatMiddleware>,
+    logger: InternalLogger,
+  ) {
     this.middlewares = middlewares
+    this.logger = logger
   }
 
   get hasMiddleware(): boolean {
@@ -63,6 +69,15 @@ export class MiddlewareRunner {
         const hasTransform = result !== undefined && result !== null
         if (hasTransform) {
           current = { ...current, ...result }
+          if (!skip) {
+            this.logger.config(
+              `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result as object).join(',')}`,
+              {
+                middleware: mw.name ?? 'unnamed',
+                changes: result,
+              },
+            )
+          }
         }
         if (!skip) {
           const base = instrumentCtx(ctx)
@@ -98,6 +113,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onStart(ctx)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onStart middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onStart' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -134,10 +153,24 @@ export class MiddlewareRunner {
       for (const c of chunks) {
         // Cast: @ag-ui/core Zod passthrough types prevent direct `.type` access
         const chunkType = (c as StreamChunk & { type: string }).type
+        if (!skip) {
+          this.logger.middleware(
+            `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onChunk', in: c },
+          )
+        }
         const result = await mw.onChunk(ctx, c)
         if (result === null) {
           // Drop this chunk
           if (!skip) {
+            this.logger.middleware(
+              `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType} out=<dropped>`,
+              {
+                middleware: mw.name ?? 'unnamed',
+                hook: 'onChunk',
+                dropped: true,
+              },
+            )
             aiEventClient.emit('middleware:chunk:transformed', {
               ...instrumentCtx(ctx),
               middlewareName: mw.name || 'unnamed',
@@ -154,6 +187,15 @@ export class MiddlewareRunner {
           // Expand
           nextChunks.push(...result)
           if (!skip) {
+            this.logger.middleware(
+              `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType} out=[${result.map((r: StreamChunk) => (r as StreamChunk & { type: string }).type).join(',')}]`,
+              {
+                middleware: mw.name ?? 'unnamed',
+                hook: 'onChunk',
+                in: c,
+                out: result,
+              },
+            )
             aiEventClient.emit('middleware:chunk:transformed', {
               ...instrumentCtx(ctx),
               middlewareName: mw.name || 'unnamed',
@@ -166,6 +208,15 @@ export class MiddlewareRunner {
           // Replace
           nextChunks.push(result)
           if (!skip) {
+            this.logger.middleware(
+              `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType} out=${(result as StreamChunk & { type: string }).type}`,
+              {
+                middleware: mw.name ?? 'unnamed',
+                hook: 'onChunk',
+                in: c,
+                out: result,
+              },
+            )
             aiEventClient.emit('middleware:chunk:transformed', {
               ...instrumentCtx(ctx),
               middlewareName: mw.name || 'unnamed',
@@ -197,6 +248,10 @@ export class MiddlewareRunner {
         const decision = await mw.onBeforeToolCall(ctx, hookCtx)
         const hasTransform = decision !== undefined && decision !== null
         if (!skip) {
+          this.logger.middleware(
+            `hook=onBeforeToolCall middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onBeforeToolCall' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -227,6 +282,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onAfterToolCall(ctx, info)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onAfterToolCall middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onAfterToolCall' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -253,6 +312,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onUsage(ctx, usage)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onUsage middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onUsage' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -279,6 +342,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onFinish(ctx, info)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onFinish middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onFinish' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -302,6 +369,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onAbort(ctx, info)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onAbort middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onAbort' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -325,6 +396,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onError(ctx, info)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onError middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onError' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -352,6 +427,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onIteration(ctx, info)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onIteration middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onIteration' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',
@@ -379,6 +458,10 @@ export class MiddlewareRunner {
         const start = Date.now()
         await mw.onToolPhaseComplete(ctx, info)
         if (!skip) {
+          this.logger.middleware(
+            `hook=onToolPhaseComplete middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'onToolPhaseComplete' },
+          )
           aiEventClient.emit('middleware:hook:executed', {
             ...instrumentCtx(ctx),
             middlewareName: mw.name || 'unnamed',

package/src/activities/generateImage/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 { ImageAdapter } from './adapter'
 import type { ImageGenerationResult, StreamChunk } from '../../types'
 
@@ -83,6 +86,12 @@ export type ImageActivityOptions<
    * @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
 } & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
   ? {
       /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<
@@ -188,10 +197,11 @@ async function runGenerateImage<
 >(
   options: ImageActivityOptions<TAdapter, boolean>,
 ): Promise<ImageGenerationResult> {
-  const { adapter, stream: _stream, ...rest } = options
+  const { adapter, stream: _stream, debug: _debug, ...rest } = options
   const model = adapter.model
   const requestId = createId('image')
   const startTime = Date.now()
+  const logger: InternalLogger = resolveDebugOption(options.debug)
 
   aiEventClient.emit('image:request:started', {
     requestId,
@@ -204,7 +214,13 @@ async function runGenerateImage<
     timestamp: startTime,
   })
 
-  return adapter.generateImages({ ...rest, model }).then((result) => {
+  logger.request(`activity=generateImage provider=${adapter.name}`, {
+    provider: adapter.name,
+    model,
+  })
+
+  try {
+    const result = await adapter.generateImages({ ...rest, model, logger })
     const duration = Date.now() - startTime
 
     aiEventClient.emit('image:request:completed', {
@@ -230,8 +246,18 @@ async function runGenerateImage<
       })
     }
 
+    logger.output(`activity=generateImage count=${result.images.length}`, {
+      count: result.images.length,
+    })
+
     return result
-  })
+  } catch (error) {
+    logger.errors('generateImage activity failed', {
+      error,
+      source: 'generateImage',
+    })
+    throw error
+  }
 }
 
 // ===========================

package/src/activities/generateSpeech/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 { TTSAdapter } from './adapter'
 import type { StreamChunk, TTSResult } from '../../types'
 
@@ -64,6 +67,12 @@ export interface TTSActivityOptions<
    * @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
 }
 
 // ===========================
@@ -134,10 +143,15 @@ export function generateSpeech<
 async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
   options: TTSActivityOptions<TAdapter, boolean>,
 ): Promise<TTSResult> {
-  const { adapter, stream: _stream, ...rest } = options
+  const { adapter, stream: _stream, debug: _debug, ...rest } = options
   const model = adapter.model
   const requestId = createId('speech')
   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('speech:request:started', {
     requestId,
@@ -151,7 +165,14 @@ async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
     timestamp: startTime,
   })
 
-  return adapter.generateSpeech({ ...rest, model }).then((result) => {
+  logger.request(`activity=generateSpeech provider=${providerName}`, {
+    provider: providerName,
+    model,
+  })
+
+  try {
+    const result = await adapter.generateSpeech({ ...rest, model, logger })
+
     const duration = Date.now() - startTime
 
     aiEventClient.emit('speech:request:completed', {
@@ -167,8 +188,19 @@ async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
       timestamp: Date.now(),
     })
 
+    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {
+      bytes: result.audio.length,
+      contentType: result.contentType,
+    })
+
     return result
-  })
+  } catch (error) {
+    logger.errors('generateSpeech activity failed', {
+      error,
+      source: 'generateSpeech',
+    })
+    throw error
+  }
 }
 
 // ===========================