@tanstack/ai 0.28.0 → 0.29.0

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
@@ -1656,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
 }
 
 // ============================================================================