@tanstack/ai 0.12.0 → 0.13.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/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,6 +997,11 @@ 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;
 }
 /**
  * A single generated image
@@ -1031,6 +1048,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 +1110,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 +1151,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.13.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.7"
   },
   "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.

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 */