@tanstack/ai 0.12.0 → 0.14.0

package/dist/esm/logger/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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/dist/esm/stream-to-response.js

@@ -1,3 +1,4 @@
+import { toRunErrorPayload } from "./activities/error-payload.js";
 async function streamToText(stream) {
   let accumulatedContent = "";
   for await (const chunk of stream) {
@@ -33,10 +34,7 @@ function toServerSentEventsStream(stream, abortController) {
             `data: ${JSON.stringify({
               type: "RUN_ERROR",
               timestamp: Date.now(),
-              error: {
-                message: error.message || "Unknown error occurred",
-                code: error.code
-              }
+              error: toRunErrorPayload(error)
             })}
 
 `
@@ -93,10 +91,7 @@ function toHttpStream(stream, abortController) {
             `${JSON.stringify({
               type: "RUN_ERROR",
               timestamp: Date.now(),
-              error: {
-                message: error.message || "Unknown error occurred",
-                code: error.code
-              }
+              error: toRunErrorPayload(error)
             })}
 `
           )

package/dist/esm/stream-to-response.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-to-response.js","sources":["../../src/stream-to-response.ts"],"sourcesContent":["import type { StreamChunk } from './types'\n\n/**\n * Collect all text content from a StreamChunk async iterable and return as a string.\n *\n * This function consumes the entire stream, accumulating content from TEXT_MESSAGE_CONTENT events,\n * and returns the final concatenated text.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @returns Promise<string> - The accumulated text content\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: 'gpt-4o',\n *   messages: [{ role: 'user', content: 'Hello!' }]\n * });\n * const text = await streamToText(stream);\n * console.log(text); // \"Hello! How can I help you today?\"\n * ```\n */\nexport async function streamToText(\n  stream: AsyncIterable<StreamChunk>,\n): Promise<string> {\n  let accumulatedContent = ''\n\n  for await (const chunk of stream) {\n    if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {\n      accumulatedContent += chunk.delta\n    }\n  }\n\n  return accumulatedContent\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format\n *\n * This creates a ReadableStream that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in Server-Sent Events format\n */\nexport function toServerSentEventsStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as Server-Sent Events format\n          controller.enqueue(\n            encoder.encode(`data: ${JSON.stringify(chunk)}\\n\\n`),\n          )\n        }\n\n        controller.close()\n      } catch (error: any) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `data: ${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: {\n                message: error.message || 'Unknown error occurred',\n                code: error.code,\n              },\n            })}\\n\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in Server-Sent Events format\n *\n * This creates a Response that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in Server-Sent Events format\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toServerSentEventsResponse(stream, { abortController });\n * ```\n */\nexport function toServerSentEventsResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  const { headers, abortController, ...responseInit } = init ?? {}\n\n  // Start with default SSE headers\n  const mergedHeaders = new Headers({\n    'Content-Type': 'text/event-stream',\n    'Cache-Control': 'no-cache',\n    Connection: 'keep-alive',\n  })\n\n  // Override with user headers if provided, handling all HeadersInit forms:\n  // Headers instance, string[][], or plain object\n  if (headers) {\n    const userHeaders = new Headers(headers)\n    userHeaders.forEach((value, key) => {\n      mergedHeaders.set(key, value)\n    })\n  }\n\n  return new Response(toServerSentEventsStream(stream, abortController), {\n    ...responseInit,\n    headers: mergedHeaders,\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * This creates a ReadableStream that emits chunks as newline-delimited JSON:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * const readableStream = toHttpStream(stream);\n * // Use with Response for HTTP streaming (not SSE)\n * return new Response(readableStream, {\n *   headers: { 'Content-Type': 'application/x-ndjson' }\n * });\n * ```\n */\nexport function toHttpStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as newline-delimited JSON\n          controller.enqueue(encoder.encode(`${JSON.stringify(chunk)}\\n`))\n        }\n\n        controller.close()\n      } catch (error: any) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: {\n                message: error.message || 'Unknown error occurred',\n                code: error.code,\n              },\n            })}\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in HTTP stream format (newline-delimited JSON)\n *\n * This creates a Response that emits chunks in HTTP stream format:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toHttpResponse(stream, { abortController });\n * ```\n */\nexport function toHttpResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  return new Response(toHttpStream(stream, init?.abortController), {\n    ...init,\n  })\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"stream-to-response.js","sources":["../../src/stream-to-response.ts"],"sourcesContent":["import { toRunErrorPayload } from './activities/error-payload'\nimport type { StreamChunk } from './types'\n\n/**\n * Collect all text content from a StreamChunk async iterable and return as a string.\n *\n * This function consumes the entire stream, accumulating content from TEXT_MESSAGE_CONTENT events,\n * and returns the final concatenated text.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @returns Promise<string> - The accumulated text content\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: 'gpt-4o',\n *   messages: [{ role: 'user', content: 'Hello!' }]\n * });\n * const text = await streamToText(stream);\n * console.log(text); // \"Hello! How can I help you today?\"\n * ```\n */\nexport async function streamToText(\n  stream: AsyncIterable<StreamChunk>,\n): Promise<string> {\n  let accumulatedContent = ''\n\n  for await (const chunk of stream) {\n    if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {\n      accumulatedContent += chunk.delta\n    }\n  }\n\n  return accumulatedContent\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format\n *\n * This creates a ReadableStream that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in Server-Sent Events format\n */\nexport function toServerSentEventsStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as Server-Sent Events format\n          controller.enqueue(\n            encoder.encode(`data: ${JSON.stringify(chunk)}\\n\\n`),\n          )\n        }\n\n        controller.close()\n      } catch (error: unknown) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `data: ${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: toRunErrorPayload(error),\n            })}\\n\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in Server-Sent Events format\n *\n * This creates a Response that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in Server-Sent Events format\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toServerSentEventsResponse(stream, { abortController });\n * ```\n */\nexport function toServerSentEventsResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  const { headers, abortController, ...responseInit } = init ?? {}\n\n  // Start with default SSE headers\n  const mergedHeaders = new Headers({\n    'Content-Type': 'text/event-stream',\n    'Cache-Control': 'no-cache',\n    Connection: 'keep-alive',\n  })\n\n  // Override with user headers if provided, handling all HeadersInit forms:\n  // Headers instance, string[][], or plain object\n  if (headers) {\n    const userHeaders = new Headers(headers)\n    userHeaders.forEach((value, key) => {\n      mergedHeaders.set(key, value)\n    })\n  }\n\n  return new Response(toServerSentEventsStream(stream, abortController), {\n    ...responseInit,\n    headers: mergedHeaders,\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * This creates a ReadableStream that emits chunks as newline-delimited JSON:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * const readableStream = toHttpStream(stream);\n * // Use with Response for HTTP streaming (not SSE)\n * return new Response(readableStream, {\n *   headers: { 'Content-Type': 'application/x-ndjson' }\n * });\n * ```\n */\nexport function toHttpStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as newline-delimited JSON\n          controller.enqueue(encoder.encode(`${JSON.stringify(chunk)}\\n`))\n        }\n\n        controller.close()\n      } catch (error: unknown) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error event (AG-UI RUN_ERROR)\n        controller.enqueue(\n          encoder.encode(\n            `${JSON.stringify({\n              type: 'RUN_ERROR',\n              timestamp: Date.now(),\n              error: toRunErrorPayload(error),\n            })}\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Convert a StreamChunk async iterable to a Response in HTTP stream format (newline-delimited JSON)\n *\n * This creates a Response that emits chunks in HTTP stream format:\n * - Each chunk is JSON.stringify'd and followed by \"\\n\"\n * - No SSE formatting (no \"data: \" prefix)\n *\n * This format is compatible with `fetchHttpStream` connection adapter.\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options (including `abortController`)\n * @returns Response in HTTP stream format (newline-delimited JSON)\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openaiText(), model: \"gpt-4o\", messages: [...] });\n * return toHttpResponse(stream, { abortController });\n * ```\n */\nexport function toHttpResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  return new Response(toHttpStream(stream, init?.abortController), {\n    ...init,\n  })\n}\n"],"names":[],"mappings":";AAuBA,eAAsB,aACpB,QACiB;AACjB,MAAI,qBAAqB;AAEzB,mBAAiB,SAAS,QAAQ;AAChC,QAAI,MAAM,SAAS,0BAA0B,MAAM,OAAO;AACxD,4BAAsB,MAAM;AAAA,IAC9B;AAAA,EACF;AAEA,SAAO;AACT;AAcO,SAAS,yBACd,QACA,iBAC4B;AAC5B,QAAM,UAAU,IAAI,YAAA;AAEpB,SAAO,IAAI,eAAe;AAAA,IACxB,MAAM,MAAM,YAAY;AACtB,UAAI;AACF,yBAAiB,SAAS,QAAQ;AAEhC,cAAI,iBAAiB,OAAO,SAAS;AACnC;AAAA,UACF;AAGA,qBAAW;AAAA,YACT,QAAQ,OAAO,SAAS,KAAK,UAAU,KAAK,CAAC;AAAA;AAAA,CAAM;AAAA,UAAA;AAAA,QAEvD;AAEA,mBAAW,MAAA;AAAA,MACb,SAAS,OAAgB;AAEvB,YAAI,iBAAiB,OAAO,SAAS;AACnC,qBAAW,MAAA;AACX;AAAA,QACF;AAGA,mBAAW;AAAA,UACT,QAAQ;AAAA,YACN,SAAS,KAAK,UAAU;AAAA,cACtB,MAAM;AAAA,cACN,WAAW,KAAK,IAAA;AAAA,cAChB,OAAO,kBAAkB,KAAK;AAAA,YAAA,CAC/B,CAAC;AAAA;AAAA;AAAA,UAAA;AAAA,QACJ;AAEF,mBAAW,MAAA;AAAA,MACb;AAAA,IACF;AAAA,IACA,SAAS;AAGP,UAAI,iBAAiB;AACnB,wBAAgB,MAAA;AAAA,MAClB;AAAA,IACF;AAAA,EAAA,CACD;AACH;AAoBO,SAAS,2BACd,QACA,MACU;AACV,QAAM,EAAE,SAAS,iBAAiB,GAAG,aAAA,IAAiB,QAAQ,CAAA;AAG9D,QAAM,gBAAgB,IAAI,QAAQ;AAAA,IAChC,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,IACjB,YAAY;AAAA,EAAA,CACb;AAID,MAAI,SAAS;AACX,UAAM,cAAc,IAAI,QAAQ,OAAO;AACvC,gBAAY,QAAQ,CAAC,OAAO,QAAQ;AAClC,oBAAc,IAAI,KAAK,KAAK;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,SAAO,IAAI,SAAS,yBAAyB,QAAQ,eAAe,GAAG;AAAA,IACrE,GAAG;AAAA,IACH,SAAS;AAAA,EAAA,CACV;AACH;AAyBO,SAAS,aACd,QACA,iBAC4B;AAC5B,QAAM,UAAU,IAAI,YAAA;AAEpB,SAAO,IAAI,eAAe;AAAA,IACxB,MAAM,MAAM,YAAY;AACtB,UAAI;AACF,yBAAiB,SAAS,QAAQ;AAEhC,cAAI,iBAAiB,OAAO,SAAS;AACnC;AAAA,UACF;AAGA,qBAAW,QAAQ,QAAQ,OAAO,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,CAAI,CAAC;AAAA,QACjE;AAEA,mBAAW,MAAA;AAAA,MACb,SAAS,OAAgB;AAEvB,YAAI,iBAAiB,OAAO,SAAS;AACnC,qBAAW,MAAA;AACX;AAAA,QACF;AAGA,mBAAW;AAAA,UACT,QAAQ;AAAA,YACN,GAAG,KAAK,UAAU;AAAA,cAChB,MAAM;AAAA,cACN,WAAW,KAAK,IAAA;AAAA,cAChB,OAAO,kBAAkB,KAAK;AAAA,YAAA,CAC/B,CAAC;AAAA;AAAA,UAAA;AAAA,QACJ;AAEF,mBAAW,MAAA;AAAA,MACb;AAAA,IACF;AAAA,IACA,SAAS;AAGP,UAAI,iBAAiB;AACnB,wBAAgB,MAAA;AAAA,MAClB;AAAA,IACF;AAAA,EAAA,CACD;AACH;AAqBO,SAAS,eACd,QACA,MACU;AACV,SAAO,IAAI,SAAS,aAAa,QAAQ,MAAM,eAAe,GAAG;AAAA,IAC/D,GAAG;AAAA,EAAA,CACJ;AACH;"}

package/dist/esm/types.d.ts

@@ -1,4 +1,5 @@
 import { StandardJSONSchemaV1 } from '@standard-schema/spec';
+import { InternalLogger } from './logger/internal-logger.js';
 import { BaseEvent as AGUIBaseEvent, CustomEvent as AGUICustomEvent, MessagesSnapshotEvent as AGUIMessagesSnapshotEvent, ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent, ReasoningEndEvent as AGUIReasoningEndEvent, ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent, ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent, ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent, ReasoningStartEvent as AGUIReasoningStartEvent, RunErrorEvent as AGUIRunErrorEvent, RunFinishedEvent as AGUIRunFinishedEvent, RunStartedEvent as AGUIRunStartedEvent, StateDeltaEvent as AGUIStateDeltaEvent, StateSnapshotEvent as AGUIStateSnapshotEvent, StepFinishedEvent as AGUIStepFinishedEvent, StepStartedEvent as AGUIStepStartedEvent, TextMessageContentEvent as AGUITextMessageContentEvent, TextMessageEndEvent as AGUITextMessageEndEvent, TextMessageStartEvent as AGUITextMessageStartEvent, ToolCallArgsEvent as AGUIToolCallArgsEvent, ToolCallEndEvent as AGUIToolCallEndEvent, ToolCallResultEvent as AGUIToolCallResultEvent, ToolCallStartEvent as AGUIToolCallStartEvent, EventType } from '@ag-ui/core';
 /**
  * Tool call states - track the lifecycle of a tool call
@@ -604,6 +605,12 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      * @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.
@@ -959,6 +966,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 {
     id: string;
@@ -985,18 +997,34 @@ export interface ImageGenerationOptions<TProviderOptions extends object = object
     size?: TSize;
     /** Model-specific options for image generation */
     modelOptions?: TProviderOptions;
+    /**
+     * Internal logger threaded from the generateImage() entry point. Adapters must
+     * call logger.request() before the SDK call and logger.errors() in catch blocks.
+     */
+    logger: InternalLogger;
 }
+/**
+ * Source of a generated media asset. Exactly one of `url` or `b64Json` is
+ * present; the other is absent. Modeled as a mutually-exclusive union so the
+ * type rejects `{}` and `{ url, b64Json }` together at compile time while
+ * preserving the flat `.url` / `.b64Json` access patterns.
+ */
+export type GeneratedMediaSource = {
+    /** URL to the generated asset (may be temporary) */
+    url: string;
+    b64Json?: never;
+} | {
+    /** Base64-encoded asset data */
+    b64Json: string;
+    url?: never;
+};
 /**
  * A single generated image
  */
-export interface GeneratedImage {
-    /** Base64-encoded image data */
-    b64Json?: string;
-    /** URL to the generated image (may be temporary) */
-    url?: string;
+export type GeneratedImage = GeneratedMediaSource & {
     /** Revised prompt used by the model (if applicable) */
     revisedPrompt?: string;
-}
+};
 /**
  * Result of image generation
  */
@@ -1014,6 +1042,52 @@ export interface ImageGenerationResult {
         totalTokens?: number;
     };
 }
+/**
+ * Options for audio generation (music, sound effects, etc.).
+ * These are the common options supported across providers.
+ */
+export interface AudioGenerationOptions<TProviderOptions extends object = object> {
+    /** The model to use for audio generation */
+    model: string;
+    /** Text description of the desired audio */
+    prompt: string;
+    /** Desired duration in seconds */
+    duration?: number;
+    /** Model-specific options for audio generation */
+    modelOptions?: TProviderOptions;
+    /**
+     * Internal logger threaded from the generateAudio() entry point. Adapters
+     * must call logger.request() before the SDK call and logger.errors() in
+     * catch blocks.
+     */
+    logger: InternalLogger;
+}
+/**
+ * A single generated audio output
+ */
+export type GeneratedAudio = GeneratedMediaSource & {
+    /** Content type of the audio (e.g., 'audio/wav', 'audio/mp3') */
+    contentType?: string;
+    /** Duration of the generated audio in seconds */
+    duration?: number;
+};
+/**
+ * Result of audio generation
+ */
+export interface AudioGenerationResult {
+    /** Unique identifier for the generation */
+    id: string;
+    /** Model used for generation */
+    model: string;
+    /** The generated audio */
+    audio: GeneratedAudio;
+    /** Token usage information (if available) */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+}
 /**
  * Options for video generation.
  * These are the common options supported across providers.
@@ -1031,6 +1105,11 @@ export interface VideoGenerationOptions<TProviderOptions extends object = object
     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;
 }
 /**
  * Result of creating a video generation job.
@@ -1088,6 +1167,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;
 }
 /**
  * Result of text-to-speech generation.
@@ -1123,6 +1208,12 @@ export interface TranscriptionOptions<TProviderOptions extends object = object>
     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;
 }
 /**
  * A single segment of transcribed audio with timing information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -24,6 +24,10 @@
     "./middlewares": {
       "types": "./dist/esm/middlewares/index.d.ts",
       "import": "./dist/esm/middlewares/index.js"
+    },
+    "./adapter-internals": {
+      "types": "./dist/esm/adapter-internals.d.ts",
+      "import": "./dist/esm/adapter-internals.js"
     }
   },
   "sideEffects": false,
@@ -47,7 +51,7 @@
   "dependencies": {
     "@ag-ui/core": "0.0.49",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.2.6"
+    "@tanstack/ai-event-client": "0.2.8"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",

package/skills/ai-core/SKILL.md

@@ -3,9 +3,9 @@ name: ai-core
 description: >
   Entry point for TanStack AI skills. Routes to chat-experience, tool-calling,
   media-generation, structured-outputs, adapter-configuration, ag-ui-protocol,
-  middleware, and custom-backend-integration. Use chat() not streamText(),
-  openaiText() not createOpenAI(), toServerSentEventsResponse() not manual SSE,
-  middleware hooks not onEnd callbacks.
+  middleware, custom-backend-integration, and debug-logging. Use chat() not
+  streamText(), openaiText() not createOpenAI(), toServerSentEventsResponse()
+  not manual SSE, middleware hooks not onEnd callbacks.
 type: core
 library: tanstack-ai
 library_version: '0.10.0'
@@ -31,6 +31,7 @@ Always import from the framework package on the client — never from
 | Implement AG-UI streaming protocol server-side    | ai-core/ag-ui-protocol/SKILL.md             |
 | Add analytics, logging, or lifecycle hooks        | ai-core/middleware/SKILL.md                 |
 | Connect to a non-TanStack-AI backend              | ai-core/custom-backend-integration/SKILL.md |
+| Turn on/off debug logging, pipe into pino/winston | ai-core/debug-logging/SKILL.md              |
 | Set up Code Mode (LLM code execution)             | See `@tanstack/ai-code-mode` package skills |
 
 ## Quick Decision Tree
@@ -43,6 +44,7 @@ Always import from the framework package on the client — never from
 - Building a server-only AG-UI backend? → ai-core/ag-ui-protocol
 - Adding analytics or post-stream events? → ai-core/middleware
 - Connecting to a custom backend? → ai-core/custom-backend-integration
+- Turning on debug logging to trace chunks/tools/middleware? → ai-core/debug-logging
 - Debugging mistakes? → Check Common Mistakes in the relevant sub-skill
 
 ## Critical Rules

package/skills/ai-core/debug-logging/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: ai-core/debug-logging
+description: >
+  Pluggable, category-toggleable debug logging for TanStack AI activities.
+  Toggle with `debug: true | false | DebugConfig` on chat(), summarize(),
+  generateImage(), generateSpeech(), generateTranscription(), generateVideo().
+  Categories: request, provider, output, middleware, tools, agentLoop,
+  config, errors. Pipe into pino/winston/etc via `debug: { logger }`. Errors
+  log by default even when `debug` is omitted; silence with `debug: false`.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.10.0'
+sources:
+  - 'TanStack/ai:docs/advanced/debug-logging.md'
+---
+
+# Debug Logging
+
+> **Dependency note:** This skill builds on ai-core. Read it first for critical rules.
+
+Use this skill when you need to turn debug logging on or off, narrow what's
+printed, or pipe logs into a custom logger (pino, winston, etc.). The same
+`debug` option works on every activity — `chat()`, `summarize()`,
+`generateImage()`, `generateSpeech()`, `generateTranscription()`,
+`generateVideo()`.
+
+## Turn it on
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  debug: true, // all categories on, prints to console
+})
+```
+
+Each log line is prefixed with an emoji and `[tanstack-ai:<category>]`:
+
+```
+📤 [tanstack-ai:request] 📤 activity=chat provider=openai model=gpt-5.2 messages=1 tools=0 stream=true
+🔁 [tanstack-ai:agentLoop] 🔁 run started
+📥 [tanstack-ai:provider] 📥 provider=openai type=response.output_text.delta
+📨 [tanstack-ai:output] 📨 type=TEXT_MESSAGE_CONTENT
+```
+
+## Turn it off
+
+```typescript
+chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  debug: false, // silence everything, including errors
+})
+```
+
+Omitting `debug` is **not** the same as `debug: false`. When omitted, the
+`errors` category is still on (errors are cheap and important). Use
+`debug: false` or `debug: { errors: false }` for true silence.
+
+## `DebugOption` — the accepted shapes
+
+```typescript
+type DebugOption = boolean | DebugConfig
+
+interface DebugConfig {
+  // Per-category flags. Any flag omitted from a DebugConfig defaults to true.
+  request?: boolean
+  provider?: boolean
+  output?: boolean
+  middleware?: boolean
+  tools?: boolean
+  agentLoop?: boolean
+  config?: boolean
+  errors?: boolean
+  // Optional custom logger. Defaults to ConsoleLogger.
+  logger?: Logger
+}
+```
+
+Resolution rules for the `debug?: DebugOption` field on every activity:
+
+| `debug` value         | Effect                                                                       |
+| --------------------- | ---------------------------------------------------------------------------- |
+| omitted (`undefined`) | Only `errors` is active; default `ConsoleLogger`.                            |
+| `true`                | All categories on; default `ConsoleLogger`.                                  |
+| `false`               | All categories off (including `errors`); default `ConsoleLogger`.            |
+| `DebugConfig` object  | Each unspecified flag defaults to `true`; `logger` replaces `ConsoleLogger`. |
+
+## Narrow what's printed
+
+Pass a `DebugConfig` object. Unspecified categories default to `true`, so it's
+easiest to toggle by setting specific flags to `false`:
+
+```typescript
+chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  debug: { middleware: false }, // everything except middleware
+})
+```
+
+To print only a specific set, set the rest to `false` explicitly:
+
+```typescript
+chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  debug: {
+    provider: true,
+    output: true,
+    middleware: false,
+    tools: false,
+    agentLoop: false,
+    config: false,
+    errors: true, // keep errors on — they're cheap and important
+    request: false,
+  },
+})
+```
+
+## Pipe into your own logger
+
+```typescript
+import type { Logger } from '@tanstack/ai'
+import pino from 'pino'
+
+const pinoLogger = pino()
+const logger: Logger = {
+  debug: (msg, meta) => pinoLogger.debug(meta, msg),
+  info: (msg, meta) => pinoLogger.info(meta, msg),
+  warn: (msg, meta) => pinoLogger.warn(meta, msg),
+  error: (msg, meta) => pinoLogger.error(meta, msg),
+}
+
+chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  debug: { logger }, // all categories on, piped to pino
+})
+```
+
+The default console logger is exported as `ConsoleLogger` if you want to wrap
+it:
+
+```typescript
+import { ConsoleLogger } from '@tanstack/ai'
+```
+
+## Categories
+
+| Category     | Logs                                                           | Applies to                            |
+| ------------ | -------------------------------------------------------------- | ------------------------------------- |
+| `request`    | Outgoing call to a provider (model, message count, tool count) | All activities                        |
+| `provider`   | Every raw chunk/frame received from a provider SDK             | Streaming activities (chat, realtime) |
+| `output`     | Every chunk or result yielded to the caller                    | All activities                        |
+| `middleware` | Inputs and outputs around every middleware hook                | `chat()` only                         |
+| `tools`      | Before/after tool call execution                               | `chat()` only                         |
+| `agentLoop`  | Agent-loop iterations and phase transitions                    | `chat()` only                         |
+| `config`     | Config transforms returned by middleware `onConfig` hooks      | `chat()` only                         |
+| `errors`     | Every caught error anywhere in the pipeline                    | All activities                        |
+
+Chat-only categories simply never fire for non-chat activities — those
+concepts don't exist in their pipelines.
+
+## Non-chat activities
+
+Same `debug` option everywhere:
+
+```typescript
+summarize({ adapter, text, debug: true })
+generateImage({ adapter, prompt: 'a cat', debug: { logger } })
+generateSpeech({ adapter, text, debug: { request: true } })
+generateTranscription({ adapter, audio, debug: false })
+generateVideo({ adapter, prompt: 'a wave', debug: { output: true } })
+```
+
+Realtime session adapters in provider packages (e.g. `openaiRealtime`,
+`elevenlabsRealtime`) accept the same `debug?: DebugOption` on their session
+options. They emit `request`, `provider`, and `errors` lines; the chat-only
+categories don't apply.
+
+## Common Mistakes
+
+### a. HIGH: Treating omitted `debug` as silent
+
+```typescript
+// WRONG — expecting this to be completely silent
+chat({ adapter, messages })
+// Errors still print via [tanstack-ai:errors] ... on failure.
+
+// CORRECT — explicit silence
+chat({ adapter, messages, debug: false })
+chat({ adapter, messages, debug: { errors: false } })
+```
+
+`debug` undefined means "only errors"; `debug: false` means "nothing at all".
+
+Source: docs/advanced/debug-logging.md
+
+### b. MEDIUM: Reaching for middleware when `debug` would do
+
+```typescript
+// WRONG — writing logging middleware to see chunks flow
+const chunkLogger: ChatMiddleware = {
+  name: 'chunk-logger',
+  onChunk: (ctx, chunk) => {
+    console.log(chunk.type, chunk)
+  },
+}
+chat({ adapter, messages, middleware: [chunkLogger] })
+
+// CORRECT — just turn on the relevant categories
+chat({
+  adapter,
+  messages,
+  debug: { provider: true, output: true },
+})
+```
+
+For observing the built-in pipeline, the `debug` option is strictly faster
+than writing logging middleware. Reach for middleware when you need to
+_transform_ chunks, not just see them.
+
+Source: docs/advanced/debug-logging.md
+
+### c. LOW: Logger implementation that can throw
+
+A user-supplied `Logger` that throws will have its exception swallowed by the
+SDK so it never masks the real error that triggered the log call. Still,
+prefer implementations that don't throw — silenced exceptions are harder to
+debug than loud ones.
+
+```typescript
+// WRONG — a logger that can throw on serialization
+const fragile: Logger = {
+  debug: (msg, meta) => console.debug(msg, JSON.stringify(meta)), // cyclic meta → throws
+  /* ... */
+}
+
+// CORRECT — guard serialization in the logger itself
+const safe: Logger = {
+  debug: (msg, meta) => {
+    try {
+      console.debug(msg, meta)
+    } catch {
+      console.debug(msg)
+    }
+  },
+  /* ... */
+}
+```
+
+Source: packages/typescript/ai/src/logger/internal-logger.ts
+
+## Cross-References
+
+- See also: **ai-core/middleware/SKILL.md** — if you need to transform
+  chunks/config, not just observe them.
+- See also: **Observability** (`docs/advanced/observability.md`) — the
+  programmatic event client for a richer, structured feed beyond log lines.