@tanstack/ai 0.11.1 → 0.13.0

package/src/logger/types.ts

@@ -0,0 +1,78 @@
+/**
+ * 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/src/tools/provider-tool.ts

@@ -0,0 +1,25 @@
+import type { Tool } from '../types'
+
+/**
+ * A provider-specific tool produced by an adapter-package factory
+ * (e.g. `webSearchTool` from `@tanstack/ai-anthropic/tools`).
+ *
+ * The two `~`-prefixed fields are type-only phantom brands — they are never
+ * assigned at runtime. They allow the core type system to match a factory's
+ * output against the selected model's `supports.tools` list and surface a
+ * compile-time error when the combination is unsupported.
+ *
+ * User-defined tools (via `toolDefinition()`) remain plain `Tool` and stay
+ * assignable to any model.
+ *
+ * @template TProvider - Provider identifier (e.g. `'anthropic'`, `'openai'`).
+ * @template TKind - Canonical tool-kind string matching the provider's
+ *   `supports.tools` entries (e.g. `'web_search'`, `'code_execution'`).
+ */
+export interface ProviderTool<
+  TProvider extends string,
+  TKind extends string,
+> extends Tool {
+  readonly '~provider': TProvider
+  readonly '~toolKind': TKind
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type { InternalLogger } from './logger/internal-logger'
 import type {
   BaseEvent as AGUIBaseEvent,
   CustomEvent as AGUICustomEvent,
@@ -738,6 +739,14 @@ export interface TextOptions<
    * @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.
@@ -1163,6 +1172,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 {
@@ -1198,6 +1212,11 @@ export interface ImageGenerationOptions<
   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
 }
 
 /**
@@ -1254,6 +1273,11 @@ export interface VideoGenerationOptions<
   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
 }
 
 /**
@@ -1319,6 +1343,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
 }
 
 /**
@@ -1362,6 +1392,12 @@ export interface TranscriptionOptions<
   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
 }
 
 /**