@tanstack/ai 0.38.0 → 0.39.1

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

@@ -1 +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;"}
+{"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  sandbox: '📦',\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 sandbox internals (watcher, file events, hook dispatch). Chat-only. */\n  sandbox(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', 'sandbox', 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;AAAA,EACR,SAAS;AACX;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,QAAQ,SAAiB,MAAsC;AAC7D,SAAK,KAAK,SAAS,WAAW,SAAS,IAAI;AAAA,EAC7C;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.js

@@ -8,7 +8,8 @@ const ALL_OFF = {
   agentLoop: false,
   config: false,
   errors: false,
-  request: false
+  request: false,
+  sandbox: false
 };
 const ALL_ON = {
   provider: true,
@@ -18,7 +19,8 @@ const ALL_ON = {
   agentLoop: true,
   config: true,
   errors: true,
-  request: true
+  request: true,
+  sandbox: true
 };
 const errorsOnlyCategories = () => ({
   ...ALL_OFF,
@@ -32,7 +34,8 @@ const resolveCategoriesFromPartial = (partial) => ({
   agentLoop: partial.agentLoop ?? true,
   config: partial.config ?? true,
   errors: partial.errors ?? true,
-  request: partial.request ?? true
+  request: partial.request ?? true,
+  sandbox: partial.sandbox ?? true
 });
 function resolveDebugOption(debug) {
   if (debug === void 0) {

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

@@ -1 +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;"}
+{"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  sandbox: 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  sandbox: 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  sandbox: partial.sandbox ?? 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;AAAA,EACT,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;AAAA,EACT,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;AAAA,EAC5B,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

@@ -59,6 +59,11 @@ export interface DebugCategories {
      * Outgoing call metadata (provider, model, message/tool counts) emitted before each adapter SDK call.
      */
     request?: boolean;
+    /**
+     * Sandbox internals: watcher start/stop + mechanism, file events, sandbox
+     * hook dispatch, ensure/bootstrap and lifecycle transitions. Chat-only.
+     */
+    sandbox?: boolean;
 }
 /**
  * Granular debug configuration combining per-category toggles with an optional custom logger. Any unspecified category flag defaults to `true`.

package/dist/esm/types.d.ts

@@ -1,6 +1,7 @@
 import { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
 import { InternalLogger } from './logger/internal-logger.js';
 import { SystemPrompt } from './system-prompts.js';
+import { CapabilityContext } from './activities/chat/middleware/capabilities.js';
 import { CompletionTokensDetails, PromptTokensDetails, ProviderUsageDetails, TokenUsage, UsageCostBreakdown } from '@tanstack/ai-event-client';
 import { BaseEvent as AGUIBaseEvent, CustomEvent as AGUICustomEvent, MessagesSnapshotEvent as AGUIMessagesSnapshotEvent, ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent, ReasoningEndEvent as AGUIReasoningEndEvent, ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent, ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent, ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent, ReasoningStartEvent as AGUIReasoningStartEvent, RunErrorEvent as AGUIRunErrorEvent, RunFinishedEvent as AGUIRunFinishedEvent, RunStartedEvent as AGUIRunStartedEvent, StateDeltaEvent as AGUIStateDeltaEvent, StateSnapshotEvent as AGUIStateSnapshotEvent, StepFinishedEvent as AGUIStepFinishedEvent, StepStartedEvent as AGUIStepStartedEvent, TextMessageContentEvent as AGUITextMessageContentEvent, TextMessageEndEvent as AGUITextMessageEndEvent, TextMessageStartEvent as AGUITextMessageStartEvent, ToolCallArgsEvent as AGUIToolCallArgsEvent, ToolCallEndEvent as AGUIToolCallEndEvent, ToolCallResultEvent as AGUIToolCallResultEvent, ToolCallStartEvent as AGUIToolCallStartEvent, EventType } from '@ag-ui/core';
 /**
@@ -95,6 +96,25 @@ export interface ToolCall<TMetadata = unknown> {
      * `@tanstack/ai-gemini` sets this to `{ thoughtSignature?: string }`. */
     metadata?: TMetadata;
 }
+/**
+ * Convention for tool-call `metadata` that marks a call as **provider-executed**
+ * — run by the provider's own infrastructure (e.g. Anthropic `web_search` /
+ * `web_fetch` server tools) rather than by the agent loop. Adapters set
+ * `providerExecuted: true` so that:
+ *
+ * 1. The agent loop never tries to execute the call client-side (see
+ *    {@link isProviderExecutedToolCall} usage in the chat engine), and
+ * 2. The adapter can stash the raw provider result alongside it so the call —
+ *    and its evidence — round-trips into the next turn's request.
+ *
+ * Provider-specific payloads live under a namespaced key (e.g. `anthropic`),
+ * keeping this convention opaque to the framework core. The index signature
+ * preserves those per-adapter fields.
+ */
+export interface ProviderExecutedToolMetadata {
+    providerExecuted?: boolean;
+    [key: string]: unknown;
+}
 /**
  * Supported input modality types for multimodal content.
  * - 'text': Plain text content
@@ -251,7 +271,9 @@ export interface ToolCallPart<TMetadata = unknown> {
     /** Tool execution output (for client tools or after approval) */
     output?: any;
     /** Provider-specific metadata that round-trips with the tool call.
-     * Typed per-adapter via `TToolCallMetadata`. */
+     * Typed per-adapter via `TToolCallMetadata`. May follow the
+     * {@link ProviderExecutedToolMetadata} convention to mark provider-executed
+     * server tools (e.g. Anthropic `web_search`). */
     metadata?: TMetadata;
 }
 export interface ToolResultPart {
@@ -761,6 +783,23 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      * Surfaced for observability/middleware; not consumed by the LLM call.
      */
     parentRunId?: string;
+    /**
+     * Middleware capability context for this run. The engine populates it with
+     * the live middleware context so harness adapters that declare
+     * `requires: [SomeCapability]` can read provided capabilities from inside
+     * `chatStream` — e.g. `getSandbox(options.capabilities)`. Capabilities are
+     * provisioned by middleware `setup` before the adapter runs. Undefined for
+     * direct adapter usage outside the chat engine.
+     */
+    capabilities?: CapabilityContext;
+    /**
+     * Client approval decisions for this run, keyed by approval id. The engine
+     * populates this from approvals carried on the incoming messages. Harness
+     * adapters consult it to resolve `ask`-policy permission requests (the agent
+     * pauses on a risky action; the client re-runs with a decision recorded
+     * here). Undefined for direct adapter usage outside the chat engine.
+     */
+    approvals?: ReadonlyMap<string, boolean>;
 }
 /**
  * Re-export EventType enum from @ag-ui/core for use in event creation.

package/dist/esm/utilities/provider-executed.d.ts

@@ -0,0 +1,18 @@
+import { ProviderExecutedToolMetadata } from '../types.js';
+/**
+ * Narrow a tool call's opaque `metadata` to the provider-executed convention.
+ * Returns the typed metadata when the call is provider-executed, else `null`.
+ *
+ * @see ProviderExecutedToolMetadata
+ */
+export declare function getProviderExecutedMetadata(toolCall: {
+    metadata?: unknown;
+} | null | undefined): ProviderExecutedToolMetadata | null;
+/**
+ * True when a tool call was executed by the provider (e.g. Anthropic
+ * `web_search` / `web_fetch` server tools) rather than the agent loop. Such
+ * calls must not be routed to client-side execution and are already "complete".
+ */
+export declare function isProviderExecutedToolCall(toolCall: {
+    metadata?: unknown;
+} | null | undefined): boolean;

package/dist/esm/utilities/provider-executed.js

@@ -0,0 +1,15 @@
+function getProviderExecutedMetadata(toolCall) {
+  const metadata = toolCall?.metadata;
+  if (typeof metadata === "object" && metadata !== null && metadata.providerExecuted === true) {
+    return metadata;
+  }
+  return null;
+}
+function isProviderExecutedToolCall(toolCall) {
+  return getProviderExecutedMetadata(toolCall) !== null;
+}
+export {
+  getProviderExecutedMetadata,
+  isProviderExecutedToolCall
+};
+//# sourceMappingURL=provider-executed.js.map

package/dist/esm/utilities/provider-executed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-executed.js","sources":["../../../src/utilities/provider-executed.ts"],"sourcesContent":["import type { ProviderExecutedToolMetadata } from '../types'\n\n/**\n * Narrow a tool call's opaque `metadata` to the provider-executed convention.\n * Returns the typed metadata when the call is provider-executed, else `null`.\n *\n * @see ProviderExecutedToolMetadata\n */\nexport function getProviderExecutedMetadata(\n  toolCall: { metadata?: unknown } | null | undefined,\n): ProviderExecutedToolMetadata | null {\n  const metadata = toolCall?.metadata\n  if (\n    typeof metadata === 'object' &&\n    metadata !== null &&\n    (metadata as ProviderExecutedToolMetadata).providerExecuted === true\n  ) {\n    return metadata as ProviderExecutedToolMetadata\n  }\n  return null\n}\n\n/**\n * True when a tool call was executed by the provider (e.g. Anthropic\n * `web_search` / `web_fetch` server tools) rather than the agent loop. Such\n * calls must not be routed to client-side execution and are already \"complete\".\n */\nexport function isProviderExecutedToolCall(\n  toolCall: { metadata?: unknown } | null | undefined,\n): boolean {\n  return getProviderExecutedMetadata(toolCall) !== null\n}\n"],"names":[],"mappings":"AAQO,SAAS,4BACd,UACqC;AACrC,QAAM,WAAW,UAAU;AAC3B,MACE,OAAO,aAAa,YACpB,aAAa,QACZ,SAA0C,qBAAqB,MAChE;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAOO,SAAS,2BACd,UACS;AACT,SAAO,4BAA4B,QAAQ,MAAM;AACnD;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.38.0",
+  "version": "0.39.1",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -2,13 +2,14 @@
 name: ai-core/adapter-configuration
 description: >
   Provider adapter selection and configuration: openaiText, anthropicText,
-  geminiText, ollamaText, grokText, groqText, openRouterText, openaiCompatible. Per-model
-  type safety with modelOptions, reasoning/thinking configuration,
+  geminiText, ollamaText, grokText, groqText, openRouterText, bedrockText,
+  openaiCompatible. Per-model type safety with modelOptions, reasoning/thinking configuration,
   runtime adapter switching, extendAdapter() for custom models, createModel().
   Generic OpenAI-compatible providers (DeepSeek, Together, Fireworks, etc.) via
   openaiCompatible({ baseURL, apiKey, models }) from @tanstack/ai-openai/compatible.
   API key env vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY,
-  XAI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, OLLAMA_HOST.
+  XAI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, OLLAMA_HOST,
+  BEDROCK_API_KEY (or AWS_BEARER_TOKEN_BEDROCK).
 type: sub-skill
 library: tanstack-ai
 library_version: '0.10.0'
@@ -78,6 +79,7 @@ The text adapter is the primary one for chat/completions:
 | Groq              | `@tanstack/ai-groq`              | `groqText`                                  | `GROQ_API_KEY`                                    |
 | OpenRouter        | `@tanstack/ai-openrouter`        | `openRouterText`                            | `OPENROUTER_API_KEY`                              |
 | Ollama            | `@tanstack/ai-ollama`            | `ollamaText`                                | `OLLAMA_HOST` (default: `http://localhost:11434`) |
+| Bedrock           | `@tanstack/ai-bedrock`           | `bedrockText`                               | `BEDROCK_API_KEY` or `AWS_BEARER_TOKEN_BEDROCK`   |
 | OpenAI-compatible | `@tanstack/ai-openai/compatible` | `openaiCompatible` / `openaiCompatibleText` | provider-specific (passed via `apiKey`)           |
 
 ```typescript
@@ -89,6 +91,7 @@ import { grokText } from '@tanstack/ai-grok'
 import { groqText } from '@tanstack/ai-groq'
 import { openRouterText } from '@tanstack/ai-openrouter'
 import { ollamaText } from '@tanstack/ai-ollama'
+import { bedrockText } from '@tanstack/ai-bedrock'
 
 // Model string is passed to the factory, NOT to chat()
 const adapter = openaiText('gpt-5.2')
@@ -98,6 +101,7 @@ const adapter4 = grokText('grok-4')
 const adapter5 = groqText('llama-3.3-70b-versatile')
 const adapter6 = openRouterText('anthropic/claude-sonnet-4')
 const adapter7 = ollamaText('llama3.3')
+const adapter8 = bedrockText('us.anthropic.claude-3-7-sonnet-20250219-v1:0')
 
 // Optional: pass explicit API key
 const adapterWithKey = openaiText('gpt-5.2', {
@@ -105,6 +109,14 @@ const adapterWithKey = openaiText('gpt-5.2', {
 })
 ```
 
+`@tanstack/ai-bedrock` (Amazon Bedrock) branches on `config.api`:
+
+- `bedrockText(model)` or `bedrockText(model, { api: 'converse' })` (the default) — Bedrock's native Converse API via `@aws-sdk/client-bedrock-runtime` (adapter name `bedrock-converse`). Reaches the broad catalog: Claude, Nova, Llama, Mistral, DeepSeek, and more.
+- `bedrockText(model, { api: 'chat' })` — OpenAI-compatible Chat Completions endpoint (adapter name `bedrock`). Open-weight models only (gpt-oss, DeepSeek V3.x, Gemma, Qwen, etc.). Does NOT reach Claude, Nova, or Llama.
+- `bedrockText(model, { api: 'responses' })` — OpenAI-compatible Responses API, mantle-only (adapter name `bedrock-responses`). Currently gpt-oss family.
+
+Use `createBedrockText(model, apiKey, config?)` to pass the key explicitly. Auth resolves from `BEDROCK_API_KEY` / `AWS_BEARER_TOKEN_BEDROCK`, or SigV4 via the standard AWS credential chain (no extra packages needed — handled by `@aws-sdk/client-bedrock-runtime`).
+
 ### 2. Runtime Adapter Switching
 
 Use an adapter factory map to switch providers dynamically based on user
@@ -397,15 +409,16 @@ Source: docs/migration/migration.md
 Each provider uses a specific env var name. Using the wrong one causes a
 runtime error:
 
-| Provider   | Correct Env Var                      | Common Mistake                                                           |
-| ---------- | ------------------------------------ | ------------------------------------------------------------------------ |
-| OpenAI     | `OPENAI_API_KEY`                     |                                                                          |
-| Anthropic  | `ANTHROPIC_API_KEY`                  |                                                                          |
-| Gemini     | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `GOOGLE_GENAI_API_KEY` (does not work)                                   |
-| Grok (xAI) | `XAI_API_KEY`                        | `GROK_API_KEY` (does not work)                                           |
-| Groq       | `GROQ_API_KEY`                       |                                                                          |
-| OpenRouter | `OPENROUTER_API_KEY`                 |                                                                          |
-| Ollama     | `OLLAMA_HOST`                        | No API key needed, just the host URL (default: `http://localhost:11434`) |
+| Provider   | Correct Env Var                                | Common Mistake                                                           |
+| ---------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
+| OpenAI     | `OPENAI_API_KEY`                               |                                                                          |
+| Anthropic  | `ANTHROPIC_API_KEY`                            |                                                                          |
+| Gemini     | `GOOGLE_API_KEY` or `GEMINI_API_KEY`           | `GOOGLE_GENAI_API_KEY` (does not work)                                   |
+| Grok (xAI) | `XAI_API_KEY`                                  | `GROK_API_KEY` (does not work)                                           |
+| Groq       | `GROQ_API_KEY`                                 |                                                                          |
+| OpenRouter | `OPENROUTER_API_KEY`                           |                                                                          |
+| Ollama     | `OLLAMA_HOST`                                  | No API key needed, just the host URL (default: `http://localhost:11434`) |
+| Bedrock    | `BEDROCK_API_KEY` / `AWS_BEARER_TOKEN_BEDROCK` | Falls back to SigV4 credentials when no API key is set                   |
 
 Source: adapter source code (`utils/client.ts` in each adapter package).
 

package/skills/ai-core/adapter-configuration/references/anthropic-adapter.md

@@ -21,17 +21,23 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 
 ## Key Chat Models
 
-| Model               | Context Window | Max Output | Notes                           |
-| ------------------- | -------------- | ---------- | ------------------------------- |
-| `claude-opus-4-6`   | 200K           | 128K       | Most capable, adaptive thinking |
-| `claude-sonnet-4-6` | 1M             | 64K        | Best balance, adaptive thinking |
-| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced           |
-| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable       |
-| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable             |
-| `claude-sonnet-4`   | 200K           | 64K        | Older balanced model            |
-| `claude-opus-4`     | 200K           | 32K        | Older most capable              |
-
-Note: Model IDs use the format `claude-opus-4-6`, `claude-sonnet-4-6`, etc.
+| Model               | Context Window | Max Output | Notes                                       |
+| ------------------- | -------------- | ---------- | ------------------------------------------- |
+| `claude-fable-5`    | 1M             | 128K       | Most capable; thinking always on (adaptive) |
+| `claude-sonnet-5`   | 1M             | 128K       | Best balance; adaptive thinking by default  |
+| `claude-opus-4-8`   | 1M             | 128K       | Opus tier; adaptive thinking, no sampling   |
+| `claude-opus-4-7`   | 1M             | 128K       | Older Opus; adaptive thinking, no sampling  |
+| `claude-opus-4-6`   | 200K           | 128K       | Older Opus, adaptive + budget thinking      |
+| `claude-sonnet-4-6` | 1M             | 64K        | Previous gen balanced, adaptive + budget    |
+| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced                       |
+| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable                   |
+| `claude-opus-4-1`   | 200K           | 64K        | Deprecated (retires 2026-08-05)             |
+| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable                         |
+
+Note: Model IDs use the format `claude-sonnet-5`, `claude-opus-4-8`, etc.
+Retired models (Claude 3.x, Sonnet 3.7, Opus 4 / Sonnet 4) and the `-fast`
+variant ids were removed — every registered id resolves against the
+first-party Anthropic API.
 
 ## Provider-Specific modelOptions
 
@@ -90,11 +96,36 @@ chat({
 ANTHROPIC_API_KEY
 ```
 
+## Adaptive-era modelOptions (Sonnet 5, Fable 5, Opus 4.7/4.8)
+
+The per-model types restrict `modelOptions` on the newest models:
+
+```typescript
+chat({
+  adapter: anthropicText('claude-sonnet-5'), // or 'claude-fable-5', 'claude-opus-4-8'
+  messages,
+  modelOptions: {
+    // Adaptive thinking only — budget_tokens is rejected (400).
+    // On claude-fable-5, { type: 'disabled' } is also rejected;
+    // elsewhere it opts out of thinking.
+    thinking: { type: 'adaptive', display: 'summarized' },
+    // Effort lives under output_config; 'xhigh' is available on
+    // Opus 4.7+, Sonnet 5, and Fable 5.
+    output_config: { effort: 'xhigh' },
+    max_tokens: 64_000,
+    // NO temperature / top_p / top_k — the API rejects them on these models
+  },
+})
+```
+
 ## Gotchas
 
 - `thinking.budget_tokens` must be >= 1024 AND less than `modelOptions.max_tokens`.
   Failing either check throws a validation error.
 - Cannot set both `top_p` and `temperature` at the same time (throws error).
-- `claude-3-5-haiku` and `claude-3-haiku` do NOT support extended thinking.
+- `claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8`, and
+  `claude-opus-4-7` do NOT accept `temperature`, `top_p`, `top_k`, or
+  `thinking: { type: 'enabled', budget_tokens }` — adaptive thinking +
+  `output_config.effort` replace them (typed per model).
 - System prompts support prompt caching via `cache_control` on `TextBlockParam[]`.
 - All Claude models accept `text`, `image`, and `document` (PDF) input.

package/skills/ai-core/media-generation/SKILL.md

@@ -151,7 +151,7 @@ function ImageGenerator() {
 
 Supported adapters: `openaiImage` (dall-e-2, dall-e-3, gpt-image-1,
 gpt-image-1-mini, gpt-image-2) and `geminiImage` (gemini-3.1-flash-image-preview,
-imagen-4.0-generate-001, etc.).
+gemini-3.1-flash-lite-image, imagen-4.0-generate-001, etc.).
 
 ```typescript
 import { generateImage } from '@tanstack/ai'

package/src/activities/chat/index.ts

@@ -12,6 +12,7 @@ import { streamToText } from '../../stream-to-response.js'
 import { resolveDebugOption } from '../../logger/resolve'
 import { EventType } from '../../types'
 import { normalizeToolResult } from '../../utilities/tool-result'
+import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import {
   MiddlewareAbortError,
@@ -27,6 +28,7 @@ import {
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
+import { provideSandboxRuntime } from './middleware/sandbox-runtime'
 import { CapabilityRegistry } from './middleware/capabilities'
 import { validateCapabilities } from './middleware/validate'
 import { MCPManager } from './mcp/manager'
@@ -67,6 +69,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
+  SandboxFileEvent,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
 import type { CheckCoverage } from './middleware/builder'
@@ -542,6 +545,7 @@ class TextEngine<
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner<TContext>
   private readonly middlewareCtx: ChatMiddlewareContext<TContext>
+  private readonly sandboxFileQueue: Array<StreamChunk> = []
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
   private readonly middlewareAbortController?: AbortController
@@ -701,6 +705,21 @@ class TextEngine<
         capability[0](this.middlewareCtx, { optional: true }),
       provide: (capability, value) => capability[1](this.middlewareCtx, value),
     }
+
+    // Provide the internal SandboxRuntime capability so harness adapters and
+    // sandbox middleware can emit file events. The sink logs, fans the event
+    // out through the middleware `onFile*` hooks (fire-and-forget), and queues
+    // a `sandbox.file` custom chunk to be drained into the public stream.
+    provideSandboxRuntime(this.middlewareCtx, {
+      logger: this.logger,
+      emit: (event: SandboxFileEvent) => {
+        this.logger.sandbox(`file ${event.type} ${event.path}`, { event })
+        void this.middlewareRunner.runSandboxFile(this.middlewareCtx, event)
+        this.sandboxFileQueue.push(
+          this.createCustomEventChunk('sandbox.file', { ...event }),
+        )
+      },
+    })
   }
 
   /** Get the accumulated content after the chat loop completes */
@@ -1021,6 +1040,10 @@ class TextEngine<
       threadId: this.threadId,
       runId: this.runIdOverride,
       parentRunId: this.parentRunIdOverride,
+      // Expose provided capabilities (e.g. sandbox) to harness adapters.
+      capabilities: this.middlewareCtx,
+      // Client approval decisions, for harness interactive-approval resolution.
+      approvals: this.initialApprovals,
       ...(combinedSchema ? { outputSchema: combinedSchema } : {}),
     })) {
       if (this.isCancelled()) {
@@ -1105,10 +1128,16 @@ class TextEngine<
         await this.middlewareRunner.runOnUsage(this.middlewareCtx, chunk.usage)
       }
 
+      // Drain any sandbox.file events emitted while processing this chunk.
+      yield* this.drainSandboxFileQueue()
+
       if (this.earlyTermination) {
         break
       }
     }
+
+    // Drain any remaining sandbox.file events emitted after the stream ended.
+    yield* this.drainSandboxFileQueue()
   }
 
   private handleStreamChunk(chunk: StreamChunk): void {
@@ -1856,6 +1885,13 @@ class TextEngine<
     for (const message of this.messages) {
       if (message.role === 'assistant' && message.toolCalls) {
         for (const toolCall of message.toolCalls) {
+          // Provider-executed tool calls (e.g. Anthropic `web_search`) were
+          // already run by the provider; they carry no client result, so they
+          // would otherwise look "pending" forever and the loop would try (and
+          // fail) to execute them client-side. Skip them.
+          if (isProviderExecutedToolCall(toolCall)) {
+            continue
+          }
           if (!completedToolIds.has(toolCall.id)) {
             pending.push(toolCall)
           }
@@ -2502,6 +2538,17 @@ class TextEngine<
     }
   }
 
+  /**
+   * Drain queued `sandbox.file` chunks (emitted via the SandboxRuntime sink)
+   * through the middleware pipeline and into the public stream.
+   */
+  private async *drainSandboxFileQueue(): AsyncGenerator<StreamChunk> {
+    while (this.sandboxFileQueue.length > 0) {
+      const chunk = this.sandboxFileQueue.shift()
+      if (chunk) yield* this.pipeThroughMiddleware(chunk)
+    }
+  }
+
   /**
    * Drain an executeToolCalls async generator, yielding any CustomEvent chunks
    * through the middleware pipeline and returning the final ExecuteToolCallsResult.

package/src/activities/chat/middleware/compose.ts

@@ -11,6 +11,7 @@ import type {
   ErrorInfo,
   FinishInfo,
   IterationInfo,
+  SandboxFileEvent,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   ToolPhaseCompleteInfo,
@@ -344,6 +345,39 @@ export class MiddlewareRunner<TContext = unknown> {
     return chunks
   }
 
+  /**
+   * Dispatch a sandbox file event to every middleware's `sandbox` hooks, in
+   * array order: the catch-all `onFile` then the type-specific hook. Errors are
+   * logged and swallowed so one bad hook can't break the run.
+   */
+  async runSandboxFile(
+    ctx: ChatMiddlewareContext<TContext>,
+    event: SandboxFileEvent,
+  ): Promise<void> {
+    const typed = (
+      {
+        create: 'onFileCreate',
+        change: 'onFileChange',
+        delete: 'onFileDelete',
+      } as const
+    )[event.type]
+    for (const mw of this.middlewares) {
+      const hooks = mw.sandbox
+      if (!hooks) continue
+      for (const fn of [hooks.onFile, hooks[typed]]) {
+        if (!fn) continue
+        try {
+          await fn(ctx, event)
+        } catch (error) {
+          this.logger.sandbox(
+            `hook=${typed} middleware=${mw.name ?? 'unnamed'} threw`,
+            { middleware: mw.name ?? 'unnamed', error },
+          )
+        }
+      }
+    }
+  }
+
   /**
    * Run onBeforeToolCall through middleware in order.
    * Returns the first non-void decision, or undefined to continue normally.

package/src/activities/chat/middleware/index.ts

@@ -13,6 +13,8 @@ export type {
   FinishInfo,
   AbortInfo,
   ErrorInfo,
+  SandboxFileEvent,
+  ChatSandboxHooks,
 } from './types'
 
 export { MiddlewareRunner } from './compose'

package/src/activities/chat/middleware/sandbox-runtime.ts

@@ -0,0 +1,21 @@
+/**
+ * Internal runtime seam the chat engine PROVIDES so the sandbox middleware can
+ * surface file events without a public ctx method. `emit` runs every
+ * middleware's `sandbox` hooks AND emits a CUSTOM `sandbox.file` chunk into the
+ * stream; `logger` lets the sandbox layer log under the `sandbox` debug
+ * category. Consumed (optionally) by `withSandbox` in `@tanstack/ai-sandbox`.
+ */
+import { createCapability } from './capabilities'
+import type { InternalLogger } from '../../../logger/internal-logger'
+import type { SandboxFileEvent } from './types'
+
+export interface SandboxRuntime {
+  emit: (event: SandboxFileEvent) => void
+  logger: InternalLogger
+}
+
+export const SandboxRuntimeCapability =
+  createCapability<SandboxRuntime>()('sandbox-runtime')
+
+export const [getSandboxRuntime, provideSandboxRuntime] =
+  SandboxRuntimeCapability

package/src/activities/chat/middleware/types.ts

@@ -13,6 +13,37 @@ import type {
   CapabilityRegistry,
 } from './capabilities'
 
+/** A file change observed inside a sandbox during a chat run. */
+export interface SandboxFileEvent {
+  type: 'create' | 'change' | 'delete'
+  /** Absolute path inside the sandbox (under the workspace root). */
+  path: string
+  timestamp: number
+}
+
+/**
+ * Sandbox file-event hooks a chat middleware can declare. Fire server-side for
+ * every file create/change/delete observed in the sandbox during the run.
+ */
+export interface ChatSandboxHooks<TContext = unknown> {
+  onFile?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileCreate?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileChange?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileDelete?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+}
+
 // ===========================
 // Middleware Context
 // ===========================
@@ -539,6 +570,12 @@ export interface ChatMiddleware<TContext = unknown> {
     ctx: ChatMiddlewareContext<TContext>,
     info: ErrorInfo,
   ) => void | Promise<void>
+
+  /**
+   * Sandbox file-event hooks. Fire when a sandbox provided by `withSandbox` is
+   * active during the run and a file is created/changed/deleted. Server-side.
+   */
+  sandbox?: ChatSandboxHooks<TContext>
 }
 
 /** A `ChatMiddleware` with a permissive context — for use as a constraint. */