@tanstack/ai 0.36.0 → 0.38.0

package/dist/esm/index.js

@@ -0,0 +1,109 @@
+import { chat, createChatOptions } from "./activities/chat/index.js";
+import { createSummarizeOptions, summarize } from "./activities/summarize/index.js";
+import { createImageOptions, generateImage } from "./activities/generateImage/index.js";
+import { createAudioOptions, generateAudio } from "./activities/generateAudio/index.js";
+import { createVideoOptions, generateVideo, getVideoJobStatus } from "./activities/generateVideo/index.js";
+import { createSpeechOptions, generateSpeech } from "./activities/generateSpeech/index.js";
+import { createTranscriptionOptions, generateTranscription } from "./activities/generateTranscription/index.js";
+import { toolDefinition } from "./activities/chat/tools/tool-definition.js";
+import { MCPDuplicateToolNameError } from "./activities/chat/mcp/manager.js";
+import { StandardSchemaValidationError, convertSchemaToJsonSchema, isStandardSchema, parseWithStandardSchema } from "./activities/chat/tools/schema-converter.js";
+import { streamToText, toHttpResponse, toHttpStream, toServerSentEventsResponse, toServerSentEventsStream } from "./stream-to-response.js";
+import { ToolCallManager } from "./activities/chat/tools/tool-calls.js";
+import { DISCOVERY_TOOL_NAME } from "./activities/chat/tools/lazy-tool-manager.js";
+import { brandProviderTool } from "./tools/provider-tool.js";
+import { combineStrategies, maxIterations, untilFinishReason } from "./activities/chat/agent-loop-strategies.js";
+import { createFrozenRegistry, createToolRegistry } from "./tool-registry.js";
+import { firstSentence, renderLazyCatalogEntry } from "./activities/chat/tools/lazy-tools.js";
+import { buildBaseUsage } from "./utilities/usage.js";
+import { resolveMediaPrompt } from "./utilities/media-prompt.js";
+import { normalizeSystemPrompts } from "./system-prompts.js";
+import { detectImageMimeType } from "./utils.js";
+import { realtimeToken } from "./realtime/index.js";
+import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, uiMessageToModelMessages } from "./activities/chat/messages.js";
+import { chatParamsFromRequest, chatParamsFromRequestBody, mergeAgentTools } from "./utilities/chat-params.js";
+import { uiMessagesToWire } from "./utilities/ag-ui-wire.js";
+import { isContentPart, isContentPartArray, normalizeToolResult } from "./utilities/tool-result.js";
+import { createModel, extendAdapter } from "./extend-adapter.js";
+import { ConsoleLogger } from "./logger/console-logger.js";
+import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PunctuationStrategy, WordBoundaryStrategy } from "./activities/chat/stream/strategies.js";
+import { EventType } from "@ag-ui/core";
+import { PartialJSONParser, defaultJSONParser, parsePartialJSON } from "./activities/chat/stream/json-parser.js";
+import { StreamProcessor, createReplayStream } from "./activities/chat/stream/processor.js";
+import { createCapability } from "./activities/chat/middleware/capabilities.js";
+import { createChatMiddleware } from "./activities/chat/middleware/builder.js";
+import { defineChatMiddleware } from "./activities/chat/middleware/define.js";
+export {
+  BatchStrategy,
+  CompositeStrategy,
+  ConsoleLogger,
+  DISCOVERY_TOOL_NAME,
+  EventType,
+  ImmediateStrategy,
+  MCPDuplicateToolNameError,
+  PartialJSONParser,
+  PunctuationStrategy,
+  StandardSchemaValidationError,
+  StreamProcessor,
+  ToolCallManager,
+  WordBoundaryStrategy,
+  brandProviderTool,
+  buildBaseUsage,
+  chat,
+  chatParamsFromRequest,
+  chatParamsFromRequestBody,
+  combineStrategies,
+  convertMessagesToModelMessages,
+  convertSchemaToJsonSchema,
+  createAudioOptions,
+  createCapability,
+  createChatMiddleware,
+  createChatOptions,
+  createFrozenRegistry,
+  createImageOptions,
+  createModel,
+  createReplayStream,
+  createSpeechOptions,
+  createSummarizeOptions,
+  createToolRegistry,
+  createTranscriptionOptions,
+  createVideoOptions,
+  defaultJSONParser,
+  defineChatMiddleware,
+  detectImageMimeType,
+  extendAdapter,
+  firstSentence,
+  generateAudio,
+  generateImage,
+  generateMessageId,
+  generateSpeech,
+  generateTranscription,
+  generateVideo,
+  getVideoJobStatus,
+  isContentPart,
+  isContentPartArray,
+  isStandardSchema,
+  maxIterations,
+  mergeAgentTools,
+  modelMessageToUIMessage,
+  modelMessagesToUIMessages,
+  normalizeSystemPrompts,
+  normalizeToUIMessage,
+  normalizeToolResult,
+  parsePartialJSON,
+  parseWithStandardSchema,
+  realtimeToken,
+  renderLazyCatalogEntry,
+  resolveMediaPrompt,
+  streamToText,
+  summarize,
+  toHttpResponse,
+  toHttpStream,
+  toServerSentEventsResponse,
+  toServerSentEventsStream,
+  toolDefinition,
+  uiMessageToModelMessages,
+  uiMessagesToWire,
+  untilFinishReason
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/logger/console-logger.d.ts

@@ -0,0 +1,29 @@
+import { Logger } from './types.js';
+/**
+ * Default `Logger` implementation that routes each level to the matching
+ * `console` method:
+ *
+ * - `debug` → `console.debug`
+ * - `info` → `console.info`
+ * - `warn` → `console.warn`
+ * - `error` → `console.error`
+ *
+ * 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 }`.
+ */
+export declare class ConsoleLogger implements Logger {
+    /** Log a debug-level message; forwards to `console.debug`. */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /** Log an info-level message; forwards to `console.info`. */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /** Log a warning-level message; forwards to `console.warn`. */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /** Log an error-level message; forwards to `console.error`. */
+    error(message: string, meta?: Record<string, unknown>): void;
+    private emit;
+}

package/dist/esm/logger/console-logger.js

@@ -0,0 +1,83 @@
+const DIR_OPTIONS = { depth: null, colors: true };
+function resolveMetaStrategy() {
+  try {
+    if (globalThis.navigator?.userAgent === "Cloudflare-Workers") return "json";
+  } catch {
+  }
+  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";
+}
+function stringifyMetaSafely(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  try {
+    return JSON.stringify(
+      value,
+      (_key, entry) => {
+        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]";
+    }
+  }
+}
+class ConsoleLogger {
+  /** Log a debug-level message; forwards to `console.debug`. */
+  debug(message, meta) {
+    this.emit("debug", message, meta);
+  }
+  /** Log an info-level message; forwards to `console.info`. */
+  info(message, meta) {
+    this.emit("info", message, meta);
+  }
+  /** Log a warning-level message; forwards to `console.warn`. */
+  warn(message, meta) {
+    this.emit("warn", message, meta);
+  }
+  /** Log an error-level message; forwards to `console.error`. */
+  error(message, meta) {
+    this.emit("error", message, meta);
+  }
+  emit(level, message, meta) {
+    if (meta === void 0) {
+      console[level](message);
+      return;
+    }
+    switch (resolveMetaStrategy()) {
+      case "dir":
+        console[level](message);
+        console.dir(meta, DIR_OPTIONS);
+        break;
+      case "json":
+        console[level](`${message}
+${stringifyMetaSafely(meta)}`);
+        break;
+      case "arg":
+        console[level](message, meta);
+        break;
+    }
+  }
+}
+export {
+  ConsoleLogger
+};
+//# sourceMappingURL=console-logger.js.map

package/dist/esm/logger/console-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-logger.js","sources":["../../../src/logger/console-logger.ts"],"sourcesContent":["import type { Logger } from './types'\n\n/**\n * `util.inspect` options used with `console.dir` on Node so deeply nested\n * structures (e.g. provider chunk payloads with `usage`, `output`,\n * `reasoning`, `tools`) render in full instead of truncating to\n * `[Object]` / `[Array]`.\n */\nconst DIR_OPTIONS = { depth: null, colors: true } as const\n\n/**\n * How `meta` should be rendered on the current runtime:\n *\n * - `dir` — Node. `console.dir(meta, { depth: null, colors: true })` gives a\n *   depth-unlimited, colored inspect dump.\n * - `json` — Cloudflare Workers / workerd. workerd never forwards\n *   `console.dir` output to the terminal (with or without options), and its\n *   own inspect of extra console arguments truncates nested objects, so the\n *   payload is appended as circular-safe pretty-printed JSON instead.\n * - `arg` — everything else (browsers, Deno, Bun). `meta` is passed as an\n *   extra console argument: devtools keep collapsible object trees and the\n *   runtime's inspect handles circular references natively.\n */\ntype MetaStrategy = 'dir' | 'json' | 'arg'\n\nfunction resolveMetaStrategy(): MetaStrategy {\n  // workerd must be detected before the Node check: under the `nodejs_compat`\n  // flag it emulates `process.versions.node`, but still drops `console.dir`.\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- navigator is missing on Node < 21 despite the DOM lib typing it as always present\n    if (globalThis.navigator?.userAgent === 'Cloudflare-Workers') return 'json'\n  } catch {\n    // A locked-down runtime with a throwing `userAgent` getter is not workerd;\n    // fall through to the remaining checks rather than crash the log call.\n  }\n  if (\n    typeof process !== 'undefined' &&\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- a partial process global (bundler shims) may lack versions\n    typeof process.versions?.node === 'string'\n  ) {\n    return 'dir'\n  }\n  return 'arg'\n}\n\n/**\n * `JSON.stringify` hardened for debug payloads: circular references collapse\n * to `\"[Circular]\"`, `Error` instances expand to `name`/`message`/`stack`\n * (they would otherwise stringify to `{}`), and `bigint` values become\n * strings (they would otherwise throw). Never throws — falls back to\n * `String(value)` and, if even that coercion throws, a placeholder.\n */\nfunction stringifyMetaSafely(value: unknown): string {\n  const seen = new WeakSet<object>()\n  try {\n    return JSON.stringify(\n      value,\n      (_key, entry: unknown) => {\n        if (typeof entry === 'bigint') return entry.toString()\n        if (entry instanceof Error) {\n          return {\n            name: entry.name,\n            message: entry.message,\n            stack: entry.stack,\n          }\n        }\n        if (typeof entry === 'object' && entry !== null) {\n          if (seen.has(entry)) return '[Circular]'\n          seen.add(entry)\n        }\n        return entry\n      },\n      2,\n    )\n  } catch {\n    try {\n      return String(value)\n    } catch {\n      return '[Unserializable meta]'\n    }\n  }\n}\n\n/**\n * Default `Logger` implementation that routes each level to the matching\n * `console` method:\n *\n * - `debug` → `console.debug`\n * - `info` → `console.info`\n * - `warn` → `console.warn`\n * - `error` → `console.error`\n *\n * When a `meta` object is supplied it is rendered with the strategy that\n * actually surfaces it on the current runtime (see {@link MetaStrategy}):\n * depth-unlimited `console.dir` on Node, circular-safe JSON on Cloudflare\n * Workers, and an extra console argument everywhere else.\n *\n * This is the logger used when `debug` is enabled on any activity and no\n * custom `logger` is supplied via `debug: { logger }`.\n */\nexport class ConsoleLogger implements Logger {\n  /** Log a debug-level message; forwards to `console.debug`. */\n  debug(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', message, meta)\n  }\n\n  /** Log an info-level message; forwards to `console.info`. */\n  info(message: string, meta?: Record<string, unknown>): void {\n    this.emit('info', message, meta)\n  }\n\n  /** Log a warning-level message; forwards to `console.warn`. */\n  warn(message: string, meta?: Record<string, unknown>): void {\n    this.emit('warn', message, meta)\n  }\n\n  /** Log an error-level message; forwards to `console.error`. */\n  error(message: string, meta?: Record<string, unknown>): void {\n    this.emit('error', message, meta)\n  }\n\n  private emit(\n    level: 'debug' | 'info' | 'warn' | 'error',\n    message: string,\n    meta?: Record<string, unknown>,\n  ): void {\n    if (meta === undefined) {\n      console[level](message)\n      return\n    }\n    switch (resolveMetaStrategy()) {\n      case 'dir':\n        console[level](message)\n        console.dir(meta, DIR_OPTIONS)\n        break\n      case 'json':\n        console[level](`${message}\\n${stringifyMetaSafely(meta)}`)\n        break\n      case 'arg':\n        console[level](message, meta)\n        break\n    }\n  }\n}\n"],"names":[],"mappings":"AAQA,MAAM,cAAc,EAAE,OAAO,MAAM,QAAQ,KAAA;AAiB3C,SAAS,sBAAoC;AAG3C,MAAI;AAEF,QAAI,WAAW,WAAW,cAAc,qBAAsB,QAAO;AAAA,EACvE,QAAQ;AAAA,EAGR;AACA,MACE,OAAO,YAAY;AAAA,EAEnB,OAAO,QAAQ,UAAU,SAAS,UAClC;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AASA,SAAS,oBAAoB,OAAwB;AACnD,QAAM,2BAAW,QAAA;AACjB,MAAI;AACF,WAAO,KAAK;AAAA,MACV;AAAA,MACA,CAAC,MAAM,UAAmB;AACxB,YAAI,OAAO,UAAU,SAAU,QAAO,MAAM,SAAA;AAC5C,YAAI,iBAAiB,OAAO;AAC1B,iBAAO;AAAA,YACL,MAAM,MAAM;AAAA,YACZ,SAAS,MAAM;AAAA,YACf,OAAO,MAAM;AAAA,UAAA;AAAA,QAEjB;AACA,YAAI,OAAO,UAAU,YAAY,UAAU,MAAM;AAC/C,cAAI,KAAK,IAAI,KAAK,EAAG,QAAO;AAC5B,eAAK,IAAI,KAAK;AAAA,QAChB;AACA,eAAO;AAAA,MACT;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ,QAAQ;AACN,QAAI;AACF,aAAO,OAAO,KAAK;AAAA,IACrB,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAmBO,MAAM,cAAgC;AAAA;AAAA,EAE3C,MAAM,SAAiB,MAAsC;AAC3D,SAAK,KAAK,SAAS,SAAS,IAAI;AAAA,EAClC;AAAA;AAAA,EAGA,KAAK,SAAiB,MAAsC;AAC1D,SAAK,KAAK,QAAQ,SAAS,IAAI;AAAA,EACjC;AAAA;AAAA,EAGA,KAAK,SAAiB,MAAsC;AAC1D,SAAK,KAAK,QAAQ,SAAS,IAAI;AAAA,EACjC;AAAA;AAAA,EAGA,MAAM,SAAiB,MAAsC;AAC3D,SAAK,KAAK,SAAS,SAAS,IAAI;AAAA,EAClC;AAAA,EAEQ,KACN,OACA,SACA,MACM;AACN,QAAI,SAAS,QAAW;AACtB,cAAQ,KAAK,EAAE,OAAO;AACtB;AAAA,IACF;AACA,YAAQ,uBAAoB;AAAA,MAC1B,KAAK;AACH,gBAAQ,KAAK,EAAE,OAAO;AACtB,gBAAQ,IAAI,MAAM,WAAW;AAC7B;AAAA,MACF,KAAK;AACH,gBAAQ,KAAK,EAAE,GAAG,OAAO;AAAA,EAAK,oBAAoB,IAAI,CAAC,EAAE;AACzD;AAAA,MACF,KAAK;AACH,gBAAQ,KAAK,EAAE,SAAS,IAAI;AAC5B;AAAA,IAAA;AAAA,EAEN;AACF;"}

package/dist/esm/logger/internal-logger.d.ts

@@ -0,0 +1,41 @@
+import { DebugCategories, Logger } from './types.js';
+/**
+ * Fully-resolved categories map. Every flag is a definite boolean (never
+ * undefined), produced by `resolveDebugOption` from a `DebugOption`.
+ */
+export type ResolvedCategories = Required<DebugCategories>;
+export declare class InternalLogger {
+    private readonly logger;
+    private readonly categories;
+    constructor(logger: Logger, categories: ResolvedCategories);
+    /** Whether a category is enabled. Cheap, safe to call on hot paths. */
+    isEnabled(category: keyof ResolvedCategories): boolean;
+    private emit;
+    /** Log a raw chunk/frame received from a provider SDK. */
+    provider(message: string, meta?: Record<string, unknown>): void;
+    /** Log a chunk/result yielded to the consumer after middleware. */
+    output(message: string, meta?: Record<string, unknown>): void;
+    /** Log inputs/outputs around a middleware hook invocation. Chat-only. */
+    middleware(message: string, meta?: Record<string, unknown>): void;
+    /** Log before/after a tool-call execution. Chat-only. */
+    tools(message: string, meta?: Record<string, unknown>): void;
+    /** Log an agent-loop iteration marker or phase transition. Chat-only. */
+    agentLoop(message: string, meta?: Record<string, unknown>): void;
+    /** Log a config transform returned by a middleware `onConfig` hook. Chat-only. */
+    config(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log a caught error. Defaults to on even when `debug` is unspecified.
+     * Uses the underlying logger's `error` level.
+     */
+    errors(message: string, meta?: Record<string, unknown>): void;
+    /** Log outgoing request metadata before an adapter SDK call. */
+    request(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log a non-fatal misconfiguration or recoverable anomaly. Gated by the
+     * `errors` category — on by default (and when `debug` is unspecified), so
+     * silent-drop conditions surface, but still silenced by `debug: false`,
+     * which honors the "disable everything including errors" contract. Routes to
+     * the underlying logger's `warn` level.
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+}

package/dist/esm/logger/internal-logger.js

@@ -0,0 +1,86 @@
+const CATEGORY_EMOJI = {
+  request: "📤",
+  provider: "📥",
+  output: "📨",
+  middleware: "🧩",
+  tools: "🔧",
+  agentLoop: "🔁",
+  config: "⚙️",
+  errors: "❌"
+};
+class InternalLogger {
+  constructor(logger, categories) {
+    this.logger = logger;
+    this.categories = categories;
+  }
+  logger;
+  categories;
+  /** Whether a category is enabled. Cheap, safe to call on hot paths. */
+  isEnabled(category) {
+    return this.categories[category];
+  }
+  emit(level, category, message, meta) {
+    if (!this.categories[category]) return;
+    const emoji = CATEGORY_EMOJI[category];
+    const prefixed = `${emoji} [tanstack-ai:${category}] ${emoji} ${message}`;
+    try {
+      if (level === "error") this.logger.error(prefixed, meta);
+      else this.logger.debug(prefixed, meta);
+    } catch {
+    }
+  }
+  /** Log a raw chunk/frame received from a provider SDK. */
+  provider(message, meta) {
+    this.emit("debug", "provider", message, meta);
+  }
+  /** Log a chunk/result yielded to the consumer after middleware. */
+  output(message, meta) {
+    this.emit("debug", "output", message, meta);
+  }
+  /** Log inputs/outputs around a middleware hook invocation. Chat-only. */
+  middleware(message, meta) {
+    this.emit("debug", "middleware", message, meta);
+  }
+  /** Log before/after a tool-call execution. Chat-only. */
+  tools(message, meta) {
+    this.emit("debug", "tools", message, meta);
+  }
+  /** Log an agent-loop iteration marker or phase transition. Chat-only. */
+  agentLoop(message, meta) {
+    this.emit("debug", "agentLoop", message, meta);
+  }
+  /** Log a config transform returned by a middleware `onConfig` hook. Chat-only. */
+  config(message, meta) {
+    this.emit("debug", "config", message, meta);
+  }
+  /**
+   * Log a caught error. Defaults to on even when `debug` is unspecified.
+   * Uses the underlying logger's `error` level.
+   */
+  errors(message, meta) {
+    this.emit("error", "errors", message, meta);
+  }
+  /** Log outgoing request metadata before an adapter SDK call. */
+  request(message, meta) {
+    this.emit("debug", "request", message, meta);
+  }
+  /**
+   * Log a non-fatal misconfiguration or recoverable anomaly. Gated by the
+   * `errors` category — on by default (and when `debug` is unspecified), so
+   * silent-drop conditions surface, but still silenced by `debug: false`,
+   * which honors the "disable everything including errors" contract. Routes to
+   * the underlying logger's `warn` level.
+   */
+  warn(message, meta) {
+    if (!this.categories.errors) return;
+    const prefixed = `⚠️ [tanstack-ai:warn] ⚠️ ${message}`;
+    try {
+      this.logger.warn(prefixed, meta);
+    } catch {
+    }
+  }
+}
+export {
+  InternalLogger
+};
+//# sourceMappingURL=internal-logger.js.map

package/dist/esm/logger/internal-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-logger.js","sources":["../../../src/logger/internal-logger.ts"],"sourcesContent":["import type { DebugCategories, Logger } from './types'\n\n/**\n * Fully-resolved categories map. Every flag is a definite boolean (never\n * undefined), produced by `resolveDebugOption` from a `DebugOption`.\n */\nexport type ResolvedCategories = Required<DebugCategories>\n\n/**\n * Package-internal logger wrapper used by every activity and adapter in\n * `@tanstack/ai`. Wraps a user-supplied (or default `ConsoleLogger`) `Logger`\n * plus a fully-resolved per-category map. Each category has a dedicated\n * method that no-ops when its flag is `false`, or prepends a\n * `[tanstack-ai:<category>] ` prefix and calls the underlying logger's\n * `error` (for the `errors` category) or `debug` (for everything else).\n *\n * Not exported from the package root. Adapter packages consume it via the\n * `@tanstack/ai/adapter-internals` subpath export.\n */\n/**\n * Emoji marker per category — bracketing the `[tanstack-ai:<cat>]` tag on\n * both sides makes it trivial to visually pick out a category when scanning\n * dense streaming logs.\n */\nconst CATEGORY_EMOJI: Record<keyof ResolvedCategories, string> = {\n  request: '📤',\n  provider: '📥',\n  output: '📨',\n  middleware: '🧩',\n  tools: '🔧',\n  agentLoop: '🔁',\n  config: '⚙️',\n  errors: '❌',\n}\n\nexport class InternalLogger {\n  constructor(\n    private readonly logger: Logger,\n    private readonly categories: ResolvedCategories,\n  ) {}\n\n  /** Whether a category is enabled. Cheap, safe to call on hot paths. */\n  isEnabled(category: keyof ResolvedCategories): boolean {\n    return this.categories[category]\n  }\n\n  private emit(\n    level: 'debug' | 'error',\n    category: keyof ResolvedCategories,\n    message: string,\n    meta?: Record<string, unknown>,\n  ): void {\n    if (!this.categories[category]) return\n    const emoji = CATEGORY_EMOJI[category]\n    const prefixed = `${emoji} [tanstack-ai:${category}] ${emoji} ${message}`\n    try {\n      if (level === 'error') this.logger.error(prefixed, meta)\n      else this.logger.debug(prefixed, meta)\n    } catch {\n      // User-supplied logger threw; swallow so we never mask the original\n      // error that triggered this log call.\n    }\n  }\n\n  /** Log a raw chunk/frame received from a provider SDK. */\n  provider(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'provider', message, meta)\n  }\n\n  /** Log a chunk/result yielded to the consumer after middleware. */\n  output(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'output', message, meta)\n  }\n\n  /** Log inputs/outputs around a middleware hook invocation. Chat-only. */\n  middleware(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'middleware', message, meta)\n  }\n\n  /** Log before/after a tool-call execution. Chat-only. */\n  tools(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'tools', message, meta)\n  }\n\n  /** Log an agent-loop iteration marker or phase transition. Chat-only. */\n  agentLoop(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'agentLoop', message, meta)\n  }\n\n  /** Log a config transform returned by a middleware `onConfig` hook. Chat-only. */\n  config(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'config', message, meta)\n  }\n\n  /**\n   * Log a caught error. Defaults to on even when `debug` is unspecified.\n   * Uses the underlying logger's `error` level.\n   */\n  errors(message: string, meta?: Record<string, unknown>): void {\n    this.emit('error', 'errors', message, meta)\n  }\n\n  /** Log outgoing request metadata before an adapter SDK call. */\n  request(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'request', message, meta)\n  }\n\n  /**\n   * Log a non-fatal misconfiguration or recoverable anomaly. Gated by the\n   * `errors` category — on by default (and when `debug` is unspecified), so\n   * silent-drop conditions surface, but still silenced by `debug: false`,\n   * which honors the \"disable everything including errors\" contract. Routes to\n   * the underlying logger's `warn` level.\n   */\n  warn(message: string, meta?: Record<string, unknown>): void {\n    if (!this.categories.errors) return\n    const prefixed = `⚠️ [tanstack-ai:warn] ⚠️ ${message}`\n    try {\n      this.logger.warn(prefixed, meta)\n    } catch {\n      // User-supplied logger threw; swallow so a broken logger never masks the\n      // condition we were trying to surface.\n    }\n  }\n}\n"],"names":[],"mappings":"AAwBA,MAAM,iBAA2D;AAAA,EAC/D,SAAS;AAAA,EACT,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AACV;AAEO,MAAM,eAAe;AAAA,EAC1B,YACmB,QACA,YACjB;AAFiB,SAAA,SAAA;AACA,SAAA,aAAA;AAAA,EAChB;AAAA,EAFgB;AAAA,EACA;AAAA;AAAA,EAInB,UAAU,UAA6C;AACrD,WAAO,KAAK,WAAW,QAAQ;AAAA,EACjC;AAAA,EAEQ,KACN,OACA,UACA,SACA,MACM;AACN,QAAI,CAAC,KAAK,WAAW,QAAQ,EAAG;AAChC,UAAM,QAAQ,eAAe,QAAQ;AACrC,UAAM,WAAW,GAAG,KAAK,iBAAiB,QAAQ,KAAK,KAAK,IAAI,OAAO;AACvE,QAAI;AACF,UAAI,UAAU,QAAS,MAAK,OAAO,MAAM,UAAU,IAAI;AAAA,UAClD,MAAK,OAAO,MAAM,UAAU,IAAI;AAAA,IACvC,QAAQ;AAAA,IAGR;AAAA,EACF;AAAA;AAAA,EAGA,SAAS,SAAiB,MAAsC;AAC9D,SAAK,KAAK,SAAS,YAAY,SAAS,IAAI;AAAA,EAC9C;AAAA;AAAA,EAGA,OAAO,SAAiB,MAAsC;AAC5D,SAAK,KAAK,SAAS,UAAU,SAAS,IAAI;AAAA,EAC5C;AAAA;AAAA,EAGA,WAAW,SAAiB,MAAsC;AAChE,SAAK,KAAK,SAAS,cAAc,SAAS,IAAI;AAAA,EAChD;AAAA;AAAA,EAGA,MAAM,SAAiB,MAAsC;AAC3D,SAAK,KAAK,SAAS,SAAS,SAAS,IAAI;AAAA,EAC3C;AAAA;AAAA,EAGA,UAAU,SAAiB,MAAsC;AAC/D,SAAK,KAAK,SAAS,aAAa,SAAS,IAAI;AAAA,EAC/C;AAAA;AAAA,EAGA,OAAO,SAAiB,MAAsC;AAC5D,SAAK,KAAK,SAAS,UAAU,SAAS,IAAI;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,SAAiB,MAAsC;AAC5D,SAAK,KAAK,SAAS,UAAU,SAAS,IAAI;AAAA,EAC5C;AAAA;AAAA,EAGA,QAAQ,SAAiB,MAAsC;AAC7D,SAAK,KAAK,SAAS,WAAW,SAAS,IAAI;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,KAAK,SAAiB,MAAsC;AAC1D,QAAI,CAAC,KAAK,WAAW,OAAQ;AAC7B,UAAM,WAAW,4BAA4B,OAAO;AACpD,QAAI;AACF,WAAK,OAAO,KAAK,UAAU,IAAI;AAAA,IACjC,QAAQ;AAAA,IAGR;AAAA,EACF;AACF;"}

package/dist/esm/logger/resolve.d.ts

@@ -0,0 +1,14 @@
+import { InternalLogger } from './internal-logger.js';
+import { DebugOption } from './types.js';
+/**
+ * Normalize a `DebugOption` into an `InternalLogger` ready to be threaded
+ * through the library's activities and adapters. See the `DebugOption`
+ * resolution table in the spec for the complete rules.
+ *
+ * - `undefined`: only the `errors` category is enabled; default `ConsoleLogger`.
+ * - `true`: all categories enabled; default `ConsoleLogger`.
+ * - `false`: all categories disabled (including `errors`); default `ConsoleLogger`.
+ * - `DebugConfig`: each unspecified category defaults to `true`; an optional
+ *   `logger` replaces the default `ConsoleLogger`.
+ */
+export declare function resolveDebugOption(debug: DebugOption | undefined): InternalLogger;

package/dist/esm/logger/resolve.js

@@ -0,0 +1,54 @@
+import { ConsoleLogger } from "./console-logger.js";
+import { InternalLogger } from "./internal-logger.js";
+const ALL_OFF = {
+  provider: false,
+  output: false,
+  middleware: false,
+  tools: false,
+  agentLoop: false,
+  config: false,
+  errors: false,
+  request: false
+};
+const ALL_ON = {
+  provider: true,
+  output: true,
+  middleware: true,
+  tools: true,
+  agentLoop: true,
+  config: true,
+  errors: true,
+  request: true
+};
+const errorsOnlyCategories = () => ({
+  ...ALL_OFF,
+  errors: true
+});
+const resolveCategoriesFromPartial = (partial) => ({
+  provider: partial.provider ?? true,
+  output: partial.output ?? true,
+  middleware: partial.middleware ?? true,
+  tools: partial.tools ?? true,
+  agentLoop: partial.agentLoop ?? true,
+  config: partial.config ?? true,
+  errors: partial.errors ?? true,
+  request: partial.request ?? true
+});
+function resolveDebugOption(debug) {
+  if (debug === void 0) {
+    return new InternalLogger(new ConsoleLogger(), errorsOnlyCategories());
+  }
+  if (debug === true) {
+    return new InternalLogger(new ConsoleLogger(), ALL_ON);
+  }
+  if (debug === false) {
+    return new InternalLogger(new ConsoleLogger(), ALL_OFF);
+  }
+  const { logger, ...cats } = debug;
+  const userLogger = logger ?? new ConsoleLogger();
+  return new InternalLogger(userLogger, resolveCategoriesFromPartial(cats));
+}
+export {
+  resolveDebugOption
+};
+//# sourceMappingURL=resolve.js.map

package/dist/esm/logger/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sources":["../../../src/logger/resolve.ts"],"sourcesContent":["import { ConsoleLogger } from './console-logger'\nimport { InternalLogger } from './internal-logger'\nimport type { ResolvedCategories } from './internal-logger'\nimport type { DebugCategories, DebugConfig, DebugOption, Logger } from './types'\n\nconst ALL_OFF: ResolvedCategories = {\n  provider: false,\n  output: false,\n  middleware: false,\n  tools: false,\n  agentLoop: false,\n  config: false,\n  errors: false,\n  request: false,\n}\n\nconst ALL_ON: ResolvedCategories = {\n  provider: true,\n  output: true,\n  middleware: true,\n  tools: true,\n  agentLoop: true,\n  config: true,\n  errors: true,\n  request: true,\n}\n\nconst errorsOnlyCategories = (): ResolvedCategories => ({\n  ...ALL_OFF,\n  errors: true,\n})\n\nconst resolveCategoriesFromPartial = (\n  partial: DebugCategories,\n): ResolvedCategories => ({\n  provider: partial.provider ?? true,\n  output: partial.output ?? true,\n  middleware: partial.middleware ?? true,\n  tools: partial.tools ?? true,\n  agentLoop: partial.agentLoop ?? true,\n  config: partial.config ?? true,\n  errors: partial.errors ?? true,\n  request: partial.request ?? true,\n})\n\n/**\n * Normalize a `DebugOption` into an `InternalLogger` ready to be threaded\n * through the library's activities and adapters. See the `DebugOption`\n * resolution table in the spec for the complete rules.\n *\n * - `undefined`: only the `errors` category is enabled; default `ConsoleLogger`.\n * - `true`: all categories enabled; default `ConsoleLogger`.\n * - `false`: all categories disabled (including `errors`); default `ConsoleLogger`.\n * - `DebugConfig`: each unspecified category defaults to `true`; an optional\n *   `logger` replaces the default `ConsoleLogger`.\n */\nexport function resolveDebugOption(\n  debug: DebugOption | undefined,\n): InternalLogger {\n  if (debug === undefined) {\n    return new InternalLogger(new ConsoleLogger(), errorsOnlyCategories())\n  }\n  if (debug === true) {\n    return new InternalLogger(new ConsoleLogger(), ALL_ON)\n  }\n  if (debug === false) {\n    return new InternalLogger(new ConsoleLogger(), ALL_OFF)\n  }\n  const { logger, ...cats }: DebugConfig = debug\n  const userLogger: Logger = logger ?? new ConsoleLogger()\n  return new InternalLogger(userLogger, resolveCategoriesFromPartial(cats))\n}\n"],"names":[],"mappings":";;AAKA,MAAM,UAA8B;AAAA,EAClC,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AACX;AAEA,MAAM,SAA6B;AAAA,EACjC,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AACX;AAEA,MAAM,uBAAuB,OAA2B;AAAA,EACtD,GAAG;AAAA,EACH,QAAQ;AACV;AAEA,MAAM,+BAA+B,CACnC,aACwB;AAAA,EACxB,UAAU,QAAQ,YAAY;AAAA,EAC9B,QAAQ,QAAQ,UAAU;AAAA,EAC1B,YAAY,QAAQ,cAAc;AAAA,EAClC,OAAO,QAAQ,SAAS;AAAA,EACxB,WAAW,QAAQ,aAAa;AAAA,EAChC,QAAQ,QAAQ,UAAU;AAAA,EAC1B,QAAQ,QAAQ,UAAU;AAAA,EAC1B,SAAS,QAAQ,WAAW;AAC9B;AAaO,SAAS,mBACd,OACgB;AAChB,MAAI,UAAU,QAAW;AACvB,WAAO,IAAI,eAAe,IAAI,cAAA,GAAiB,sBAAsB;AAAA,EACvE;AACA,MAAI,UAAU,MAAM;AAClB,WAAO,IAAI,eAAe,IAAI,cAAA,GAAiB,MAAM;AAAA,EACvD;AACA,MAAI,UAAU,OAAO;AACnB,WAAO,IAAI,eAAe,IAAI,cAAA,GAAiB,OAAO;AAAA,EACxD;AACA,QAAM,EAAE,QAAQ,GAAG,KAAA,IAAsB;AACzC,QAAM,aAAqB,UAAU,IAAI,cAAA;AACzC,SAAO,IAAI,eAAe,YAAY,6BAA6B,IAAI,CAAC;AAC1E;"}

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; 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; 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; 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; 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;
+}
+/**
+ * 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/middlewares/content-guard.d.ts

@@ -0,0 +1,77 @@
+import { ChatMiddleware } from '../activities/chat/middleware/types.js';
+/**
+ * A content guard rule — either a regex pattern with replacement, or a transform function.
+ */
+export type ContentGuardRule = {
+    pattern: RegExp;
+    replacement: string;
+} | {
+    fn: (text: string) => string;
+};
+/**
+ * Information passed to the onFiltered callback.
+ */
+export interface ContentFilteredInfo {
+    /** The message ID being filtered */
+    messageId: string;
+    /** The original text before filtering */
+    original: string;
+    /** The filtered text after rules applied */
+    filtered: string;
+    /** Which strategy was used */
+    strategy: 'delta' | 'buffered';
+}
+/**
+ * Options for the content guard middleware.
+ */
+export interface ContentGuardMiddlewareOptions {
+    /**
+     * Rules to apply to text content. Each rule is either a regex pattern
+     * with a replacement string, or a custom transform function.
+     * Rules are applied in order. Each rule receives the output of the previous.
+     */
+    rules: Array<ContentGuardRule>;
+    /**
+     * Matching strategy:
+     * - 'delta': Apply rules to each delta as it arrives. Fast, real-time,
+     *   but patterns spanning chunk boundaries may be missed.
+     * - 'buffered': Accumulate content and apply rules to settled portions,
+     *   holding back a look-behind buffer to catch cross-boundary patterns.
+     *
+     * @default 'buffered'
+     */
+    strategy?: 'delta' | 'buffered';
+    /**
+     * Number of characters to hold back before emitting (buffered strategy only).
+     * Should be at least as long as the longest pattern you expect to match.
+     * Buffer is flushed when the stream ends.
+     *
+     * @default 50
+     */
+    bufferSize?: number;
+    /**
+     * If true, drop the entire chunk when any rule changes the content.
+     * @default false
+     */
+    blockOnMatch?: boolean;
+    /**
+     * Callback when content is filtered by any rule.
+     */
+    onFiltered?: (info: ContentFilteredInfo) => void;
+}
+/**
+ * Creates a middleware that filters or transforms streamed text content.
+ *
+ * @example
+ * ```ts
+ * import { contentGuardMiddleware } from '@tanstack/ai/middlewares'
+ *
+ * const guard = contentGuardMiddleware({
+ *   rules: [
+ *     { pattern: /\b\d{3}-\d{2}-\d{4}\b/g, replacement: '[SSN REDACTED]' },
+ *   ],
+ *   strategy: 'buffered',
+ * })
+ * ```
+ */
+export declare function contentGuardMiddleware(options: ContentGuardMiddlewareOptions): ChatMiddleware;