@tanstack/ai 0.28.0 → 0.31.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/middlewares/otel.ts

@@ -20,6 +20,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareContext,
 } from '../activities/chat/middleware/types'
+import type { TokenUsage } from '../types'
 
 /**
  * Scope (role) of an OTel span emitted by this middleware.
@@ -179,6 +180,59 @@ function firstNumber(...candidates: Array<unknown>): number | undefined {
   return undefined
 }
 
+/**
+ * Build the full set of `gen_ai.usage.*` span attributes from a `TokenUsage`.
+ *
+ * Beyond input/output tokens, this emits provider-reported cost, total tokens,
+ * cache and reasoning breakdowns, and duration-based billing — every field is
+ * guarded so spans stay clean when a provider doesn't report it. Cache and
+ * reasoning use the official GenAI semconv names; `gen_ai.usage.cost` and
+ * `gen_ai.usage.total_tokens` are de-facto extensions consumed by backends
+ * like PostHog (which otherwise re-derive cost from their own price tables,
+ * losing cache discounts and gateway markup). Fields with no semconv or
+ * de-facto convention (`costDetails`, `durationSeconds`) are
+ * TanStack-namespaced. Deliberately not emitted: `unitsBilled`,
+ * `providerUsageDetails`, and the per-modality token breakdowns — those are
+ * media-oriented; media-activity observability is tracked in #720.
+ */
+function usageAttributes(usage: TokenUsage): Record<string, AttributeValue> {
+  const attrs: Record<string, AttributeValue> = {
+    'gen_ai.usage.input_tokens': usage.promptTokens,
+    'gen_ai.usage.output_tokens': usage.completionTokens,
+  }
+  const optional: Array<[key: string, value: unknown]> = [
+    ['gen_ai.usage.total_tokens', usage.totalTokens],
+    ['gen_ai.usage.cost', usage.cost],
+    [
+      'gen_ai.usage.cache_read.input_tokens',
+      usage.promptTokensDetails?.cachedTokens,
+    ],
+    [
+      'gen_ai.usage.cache_creation.input_tokens',
+      usage.promptTokensDetails?.cacheWriteTokens,
+    ],
+    [
+      'gen_ai.usage.reasoning.output_tokens',
+      usage.completionTokensDetails?.reasoningTokens,
+    ],
+    ['tanstack.ai.usage.duration_seconds', usage.durationSeconds],
+    ['tanstack.ai.usage.upstream_cost', usage.costDetails?.upstreamCost],
+    [
+      'tanstack.ai.usage.upstream_input_cost',
+      usage.costDetails?.upstreamInputCost,
+    ],
+    [
+      'tanstack.ai.usage.upstream_output_cost',
+      usage.costDetails?.upstreamOutputCost,
+    ],
+  ]
+  for (const [key, value] of optional) {
+    const num = firstNumber(value)
+    if (num !== undefined) attrs[key] = num
+  }
+  return attrs
+}
+
 function errorMessage(err: unknown): string | undefined {
   if (err instanceof Error) return err.message
   if (typeof err === 'string') return err
@@ -524,10 +578,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
         // `runOnUsage` when `chunk.usage` is present, and `onUsage` is the
         // canonical place for the metric. Recording in both would double-count.
         if (chunk.usage) {
-          span.setAttributes({
-            'gen_ai.usage.input_tokens': chunk.usage.promptTokens,
-            'gen_ai.usage.output_tokens': chunk.usage.completionTokens,
-          })
+          span.setAttributes(usageAttributes(chunk.usage))
         }
 
         if (captureContent && state.assistantTextBuffer.length > 0) {
@@ -584,10 +635,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
         }
 
         const span = state.currentIterationSpan ?? state.rootSpan
-        span.setAttributes({
-          'gen_ai.usage.input_tokens': usage.promptTokens,
-          'gen_ai.usage.output_tokens': usage.completionTokens,
-        })
+        span.setAttributes(usageAttributes(usage))
       })
     },
 
@@ -905,10 +953,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
         }
 
         if (info.usage) {
-          state.rootSpan.setAttributes({
-            'gen_ai.usage.input_tokens': info.usage.promptTokens,
-            'gen_ai.usage.output_tokens': info.usage.completionTokens,
-          })
+          state.rootSpan.setAttributes(usageAttributes(info.usage))
         }
         if (info.finishReason) {
           state.rootSpan.setAttribute('gen_ai.response.finish_reasons', [

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
 }
 
 // ============================================================================