@tanstack/ai 0.12.0 → 0.14.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.

package/src/activities/chat/adapter.ts

@@ -18,7 +18,12 @@ export interface TextAdapterConfig {
 }
 
 /**
- * Options for structured output generation
+ * Options for structured output generation.
+ *
+ * The internal logger is threaded through `chatOptions.logger` (inherited from
+ * `TextOptions`). Adapter implementations must call `logger.request()` before
+ * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`
+ * in catch blocks.
  */
 export interface StructuredOutputOptions<TProviderOptions extends object> {
   /** Text options for the request */

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,8 @@ 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'
 
 // ===========================
@@ -181,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
 }
 
 // ===========================
@@ -293,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 || []
@@ -341,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,
@@ -393,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)
@@ -417,6 +436,10 @@ class TextEngine<
           return
         }
 
+        this.logger.agentLoop(`iteration=${this.middlewareCtx.iteration}`, {
+          iteration: this.middlewareCtx.iteration,
+        })
+
         await this.beginCycle()
 
         if (this.cyclePhase === 'processText') {
@@ -438,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
@@ -460,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,
@@ -555,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,
@@ -566,6 +609,7 @@ class TextEngine<
       request: this.effectiveRequest,
       modelOptions,
       systemPrompts: this.systemPrompts,
+      logger: this.logger,
       threadId: this.threadId,
       runId: this.runIdOverride,
     })) {
@@ -585,6 +629,7 @@ class TextEngine<
         chunk,
       )
       for (const outputChunk of outputChunks) {
+        this.logger.output(`type=${outputChunk.type}`, { chunk: outputChunk })
         yield outputChunk
         this.middlewareCtx.chunkIndex++
       }
@@ -741,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,
@@ -754,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,
@@ -894,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,
@@ -907,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,
@@ -1491,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
@@ -1533,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()) {
@@ -1573,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({
@@ -1580,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',