@tanstack/ai 0.27.0 → 0.29.0

package/src/extend-adapter.ts

@@ -144,6 +144,14 @@ type ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =
 // Factory Type Inference
 // ===========================
 
+/**
+ * The widest factory shape `extendAdapter` accepts: any function taking a
+ * model as its first parameter. Parameters are contravariant, so `never`
+ * params and an `unknown` return accept every factory without resorting
+ * to `any`.
+ */
+type AnyAdapterFactory = (model: never, ...args: Array<never>) => unknown
+
 /**
  * Infer the model parameter type from an adapter factory function.
  * For generic functions like `<T extends Union>(model: T)`, this gets `T` which
@@ -151,32 +159,44 @@ type ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =
  */
 type InferFactoryModels<TFactory> = TFactory extends (
   model: infer TModel,
-  ...args: Array<any>
-) => any
+  ...args: Array<never>
+) => unknown
   ? TModel extends string
     ? TModel
     : string
   : string
 
-/**
- * Infer the config parameter type from an adapter factory function.
- */
-type InferConfig<TFactory> = TFactory extends (
-  model: any,
-  config?: infer TConfig,
-) => any
-  ? TConfig
-  : undefined
-
 /**
  * Infer the adapter return type from a factory function.
  */
 type InferAdapterReturn<TFactory> = TFactory extends (
-  ...args: Array<any>
+  ...args: Array<never>
 ) => infer TReturn
   ? TReturn
   : never
 
+/**
+ * Extracts all parameter types after the model parameter from a factory,
+ * preserving labels and optionality (e.g. `[apiKey: string, config?: C]`).
+ * Note: overloaded factories resolve against their last overload (a
+ * `Parameters` limitation).
+ */
+type InferRestArgs<TFactory extends AnyAdapterFactory> =
+  Parameters<TFactory> extends [unknown?, ...infer TRest] ? TRest : []
+
+/**
+ * The factory signature produced by `extendAdapter`: accepts both original
+ * and custom model names while preserving all remaining parameters and the
+ * return type of the original factory.
+ */
+type ExtendedFactory<
+  TFactory extends AnyAdapterFactory,
+  TDefs extends ReadonlyArray<ExtendedModelDef>,
+> = (
+  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,
+  ...args: InferRestArgs<TFactory>
+) => InferAdapterReturn<TFactory>
+
 // ===========================
 // extendAdapter Function
 // ===========================
@@ -225,19 +245,17 @@ type InferAdapterReturn<TFactory> = TFactory extends (
  * ```
  */
 export function extendAdapter<
-  TFactory extends (...args: Array<any>) => any,
+  TFactory extends AnyAdapterFactory,
   const TDefs extends ReadonlyArray<ExtendedModelDef>,
->(
-  factory: TFactory,
-  _customModels: TDefs,
-): (
-  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,
-  ...args: InferConfig<TFactory> extends undefined
-    ? []
-    : [config?: InferConfig<TFactory>]
-) => InferAdapterReturn<TFactory> {
+>(factory: TFactory, _customModels: TDefs): ExtendedFactory<TFactory, TDefs>
+// The implementation signature stays at the honest `AnyAdapterFactory` width;
+// the overload above performs the deliberate model-union widening.
+export function extendAdapter(
+  factory: AnyAdapterFactory,
+  _customModels: ReadonlyArray<ExtendedModelDef>,
+): AnyAdapterFactory {
   // At runtime, we simply pass through to the original factory.
   // The _customModels parameter is only used for type inference.
   // No runtime validation - users are trusted to pass valid model names.
-  return factory as any
+  return factory
 }

package/src/index.ts

@@ -52,6 +52,16 @@ export {
   type InferToolOutput,
 } from './activities/chat/tools/tool-definition'
 
+// MCP chat option types
+export type {
+  MCPToolSource,
+  ChatMCPOptions,
+  MCPConnectionPolicy,
+} from './activities/chat/mcp/types'
+
+// MCP error classes (value exports — usable with instanceof)
+export { MCPDuplicateToolNameError } from './activities/chat/mcp/manager'
+
 // Schema conversion (Standard JSON Schema compliant)
 export {
   convertSchemaToJsonSchema,

package/src/logger/console-logger.ts

@@ -1,5 +1,86 @@
 import type { Logger } from './types'
 
+/**
+ * `util.inspect` options used with `console.dir` on Node so deeply nested
+ * structures (e.g. provider chunk payloads with `usage`, `output`,
+ * `reasoning`, `tools`) render in full instead of truncating to
+ * `[Object]` / `[Array]`.
+ */
+const DIR_OPTIONS = { depth: null, colors: true } as const
+
+/**
+ * How `meta` should be rendered on the current runtime:
+ *
+ * - `dir` — Node. `console.dir(meta, { depth: null, colors: true })` gives a
+ *   depth-unlimited, colored inspect dump.
+ * - `json` — Cloudflare Workers / workerd. workerd never forwards
+ *   `console.dir` output to the terminal (with or without options), and its
+ *   own inspect of extra console arguments truncates nested objects, so the
+ *   payload is appended as circular-safe pretty-printed JSON instead.
+ * - `arg` — everything else (browsers, Deno, Bun). `meta` is passed as an
+ *   extra console argument: devtools keep collapsible object trees and the
+ *   runtime's inspect handles circular references natively.
+ */
+type MetaStrategy = 'dir' | 'json' | 'arg'
+
+function resolveMetaStrategy(): MetaStrategy {
+  // workerd must be detected before the Node check: under the `nodejs_compat`
+  // flag it emulates `process.versions.node`, but still drops `console.dir`.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- navigator is missing on Node < 21 despite the DOM lib typing it as always present
+    if (globalThis.navigator?.userAgent === 'Cloudflare-Workers') return 'json'
+  } catch {
+    // A locked-down runtime with a throwing `userAgent` getter is not workerd;
+    // fall through to the remaining checks rather than crash the log call.
+  }
+  if (
+    typeof process !== 'undefined' &&
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- a partial process global (bundler shims) may lack versions
+    typeof process.versions?.node === 'string'
+  ) {
+    return 'dir'
+  }
+  return 'arg'
+}
+
+/**
+ * `JSON.stringify` hardened for debug payloads: circular references collapse
+ * to `"[Circular]"`, `Error` instances expand to `name`/`message`/`stack`
+ * (they would otherwise stringify to `{}`), and `bigint` values become
+ * strings (they would otherwise throw). Never throws — falls back to
+ * `String(value)` and, if even that coercion throws, a placeholder.
+ */
+function stringifyMetaSafely(value: unknown): string {
+  const seen = new WeakSet<object>()
+  try {
+    return JSON.stringify(
+      value,
+      (_key, entry: unknown) => {
+        if (typeof entry === 'bigint') return entry.toString()
+        if (entry instanceof Error) {
+          return {
+            name: entry.name,
+            message: entry.message,
+            stack: entry.stack,
+          }
+        }
+        if (typeof entry === 'object' && entry !== null) {
+          if (seen.has(entry)) return '[Circular]'
+          seen.add(entry)
+        }
+        return entry
+      },
+      2,
+    )
+  } catch {
+    try {
+      return String(value)
+    } catch {
+      return '[Unserializable meta]'
+    }
+  }
+}
+
 /**
  * Default `Logger` implementation that routes each level to the matching
  * `console` method:
@@ -9,41 +90,55 @@ import type { Logger } from './types'
  * - `warn` → `console.warn`
  * - `error` → `console.error`
  *
- * When a `meta` object is supplied, the message is logged first and the meta
- * object is then printed via `console.dir(meta, { depth: null, colors: true })`
- * so deeply nested structures (e.g. provider chunk payloads with `usage`,
- * `output`, `reasoning`, `tools`) render in full instead of truncating to
- * `[Object]` / `[Array]`. On Node this produces a depth-unlimited inspect
- * dump; browsers present the object as an interactive tree (extra options
- * are ignored).
+ * When a `meta` object is supplied it is rendered with the strategy that
+ * actually surfaces it on the current runtime (see {@link MetaStrategy}):
+ * depth-unlimited `console.dir` on Node, circular-safe JSON on Cloudflare
+ * Workers, and an extra console argument everywhere else.
  *
  * This is the logger used when `debug` is enabled on any activity and no
  * custom `logger` is supplied via `debug: { logger }`.
  */
-const DIR_OPTIONS = { depth: null, colors: true } as const
-
 export class ConsoleLogger implements Logger {
   /** Log a debug-level message; forwards to `console.debug`. */
   debug(message: string, meta?: Record<string, unknown>): void {
-    console.debug(message)
-    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+    this.emit('debug', message, meta)
   }
 
   /** Log an info-level message; forwards to `console.info`. */
   info(message: string, meta?: Record<string, unknown>): void {
-    console.info(message)
-    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+    this.emit('info', message, meta)
   }
 
   /** Log a warning-level message; forwards to `console.warn`. */
   warn(message: string, meta?: Record<string, unknown>): void {
-    console.warn(message)
-    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+    this.emit('warn', message, meta)
   }
 
   /** Log an error-level message; forwards to `console.error`. */
   error(message: string, meta?: Record<string, unknown>): void {
-    console.error(message)
-    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)
+    this.emit('error', message, meta)
+  }
+
+  private emit(
+    level: 'debug' | 'info' | 'warn' | 'error',
+    message: string,
+    meta?: Record<string, unknown>,
+  ): void {
+    if (meta === undefined) {
+      console[level](message)
+      return
+    }
+    switch (resolveMetaStrategy()) {
+      case 'dir':
+        console[level](message)
+        console.dir(meta, DIR_OPTIONS)
+        break
+      case 'json':
+        console[level](`${message}\n${stringifyMetaSafely(meta)}`)
+        break
+      case 'arg':
+        console[level](message, meta)
+        break
+    }
   }
 }

package/src/logger/types.ts

@@ -4,22 +4,22 @@
 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>`.
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
    */
   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>`.
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
    */
   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>`.
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
    */
   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>`.
+   * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
    */
   error: (message: string, meta?: Record<string, unknown>) => void
 }

package/src/realtime/index.ts

@@ -22,9 +22,7 @@ export type * from './types'
  *   .handler(async () => {
  *     return realtimeToken({
  *       adapter: openaiRealtimeToken({
- *         model: 'gpt-4o-realtime-preview',
- *         voice: 'alloy',
- *         instructions: 'You are a helpful assistant...',
+ *         model: 'gpt-realtime',
  *       }),
  *     })
  *   })

package/src/types.ts

@@ -51,6 +51,7 @@ export type ToolCallState =
   | 'approval-requested' // Waiting for user approval
   | 'approval-responded' // User has approved/denied
   | 'complete' // Result is complete
+  | 'error' // Tool execution failed (terminal)
 
 /**
  * Tool result states - track the lifecycle of a tool result
@@ -490,6 +491,12 @@ export type ToolExecutionContext<TContext = unknown> =
   RuntimeContextField<TContext> & {
     /** The ID of the tool call being executed */
     toolCallId?: string
+    /**
+     * Abort signal for the current chat run. Aborts when the run's
+     * `abortController` fires (or middleware aborts). Long-running tools —
+     * e.g. MCP `callTool` — should forward this to cancel in-flight work.
+     */
+    abortSignal?: AbortSignal
     /**
      * Emit a custom event during tool execution.
      * Events are streamed to the client in real-time as AG-UI CUSTOM events.
@@ -1650,6 +1657,12 @@ export interface VideoUrlResult {
   url: string
   /** When the URL expires, if applicable */
   expiresAt?: Date
+  /**
+   * Usage information for the completed generation, when the adapter can report
+   * it. For usage-based providers (e.g. fal) this carries `unitsBilled` — the
+   * real billed quantity — so consumers can compute exact cost.
+   */
+  usage?: TokenUsage
 }
 
 // ============================================================================