@tanstack/ai 0.42.0 → 0.43.0

package/README.md

@@ -1,5 +1,19 @@
 <div align="center">
-  <img src="https://raw.githubusercontent.com/TanStack/ai/main/media/header_ai.png" alt="TanStack AI" />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
 </div>
 
 <br />

package/dist/esm/activities/chat/adapter.js

@@ -1,17 +1,24 @@
-class BaseTextAdapter {
-  kind = "text";
-  model;
-  requires = void 0;
-  config;
-  constructor(config = {}, model) {
-    this.config = config;
-    this.model = model;
-  }
-  generateId() {
-    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-  }
-}
-export {
-  BaseTextAdapter
+//#region src/activities/chat/adapter.ts
+/**
+* Abstract base class for text adapters.
+* Extend this class to implement a text adapter for a specific provider.
+*
+* Generic parameters match TextAdapter - all pre-resolved by the provider function.
+*/
+var BaseTextAdapter = class {
+	kind = "text";
+	model;
+	requires = void 0;
+	config;
+	constructor(config = {}, model) {
+		this.config = config;
+		this.model = model;
+	}
+	generateId() {
+		return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+	}
 };
-//# sourceMappingURL=adapter.js.map
+//#endregion
+export { BaseTextAdapter };
+
+//# sourceMappingURL=adapter.js.map

package/dist/esm/activities/chat/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\nimport type { CapabilityHandle } from './middleware/capabilities'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n  /** Token usage information (if provided by the adapter) */\n  usage?: TokenUsage\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * Capabilities this adapter requires at runtime. `chat()` validates that the\n   * configured middleware provides each one. Model adapters omit this; harness\n   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.\n   * Runtime access to capabilities from inside the adapter is not yet wired —\n   * this is the declaration/validation surface only.\n   */\n  readonly requires?: ReadonlyArray<CapabilityHandle>\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n  readonly requires?: ReadonlyArray<CapabilityHandle> = undefined\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AA+KO,MAAe,gBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EACA,WAA6C;AAAA,EAY5C;AAAA,EAEV,YAAY,SAA4B,CAAA,GAAI,OAAe;AACzD,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAcU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}
+{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\nimport type { CapabilityHandle } from './middleware/capabilities'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n  /** Token usage information (if provided by the adapter) */\n  usage?: TokenUsage\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * Capabilities this adapter requires at runtime. `chat()` validates that the\n   * configured middleware provides each one. Model adapters omit this; harness\n   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.\n   * Runtime access to capabilities from inside the adapter is not yet wired —\n   * this is the declaration/validation surface only.\n   */\n  readonly requires?: ReadonlyArray<CapabilityHandle>\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n  readonly requires?: ReadonlyArray<CapabilityHandle> = undefined\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AA+KA,IAAsB,kBAAtB,MAgBE;CACA,OAAgB;CAEhB;CACA,WAAsD,KAAA;CAYtD;CAEA,YAAY,SAA4B,CAAC,GAAG,OAAe;EACzD,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAcA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}

package/dist/esm/activities/chat/agent-loop-strategies.d.ts

@@ -3,9 +3,10 @@ import { AgentLoopStrategy } from '../../types.js';
  * Creates a strategy that continues for a maximum number of **model turns**
  * (iterations), not tool calls.
  *
- * One iteration can still emit many parallel tool calls. Prefer
- * {@link maxToolCalls} (and optionally `maxToolCallsPerTurn` on `chat()`)
- * when you need a tool-call budget.
+ * One iteration can still emit many parallel tool calls. For a tool-call
+ * budget, use middleware with `onBeforeToolCall` (per-turn cap) and
+ * `onShouldContinue` (cumulative run budget) — see the docs recipe under
+ * Agentic Cycle.
  *
  * @param max - Maximum number of model turns to allow
  * @returns AgentLoopStrategy that stops after max iterations
@@ -22,37 +23,6 @@ import { AgentLoopStrategy } from '../../types.js';
  * ```
  */
 export declare function maxIterations(max: number): AgentLoopStrategy;
-/**
- * Creates a strategy that continues while `toolCallCount < max`.
- *
- * Unlike {@link maxIterations} (which counts model turns), this bounds
- * **emitted** tool calls counted during the run (including ones skipped by
- * `maxToolCallsPerTurn`). Strategies only run between turns, so the turn that
- * crosses `max` is not truncated — the final count (and executions, unless
- * `maxToolCallsPerTurn` is set) may exceed `max`. Pair with
- * `chat({ maxToolCallsPerTurn })` to also cap parallel fan-out inside a single
- * turn.
- *
- * @param max - Maximum cumulative emitted tool calls before stopping further turns
- * @returns AgentLoopStrategy that returns true while `toolCallCount < max`
- *
- * @example
- * ```typescript
- * import { chat, combineStrategies, maxIterations, maxToolCalls } from '@tanstack/ai'
- *
- * const stream = chat({
- *   adapter: openaiText('gpt-4o'),
- *   messages: [...],
- *   tools: [weatherTool],
- *   maxToolCallsPerTurn: 10,
- *   agentLoopStrategy: combineStrategies([
- *     maxIterations(20),
- *     maxToolCalls(20),
- *   ]),
- * })
- * ```
- */
-export declare function maxToolCalls(max: number): AgentLoopStrategy;
 /**
  * Creates a strategy that continues until a specific finish reason is encountered
  *
@@ -76,7 +46,7 @@ export declare function untilFinishReason(stopReasons: Array<string>): AgentLoop
  * All strategies must return true to continue
  *
  * @param strategies - Array of strategies to combine
- * @returns AgentLoopStrategy that continues only if all strategies return true
+ * @returns AgentLoopStrategy that continues only if all strategies agree
  *
  * @example
  * ```typescript
@@ -87,7 +57,6 @@ export declare function untilFinishReason(stopReasons: Array<string>): AgentLoop
  *   tools: [weatherTool],
  *   agentLoopStrategy: combineStrategies([
  *     maxIterations(10),
- *     maxToolCalls(20),
  *     ({ messages }) => messages.length < 100,
  *   ]),
  * });

package/dist/esm/activities/chat/agent-loop-strategies.js

@@ -1,27 +1,81 @@
+//#region src/activities/chat/agent-loop-strategies.ts
+/**
+* Creates a strategy that continues for a maximum number of **model turns**
+* (iterations), not tool calls.
+*
+* One iteration can still emit many parallel tool calls. For a tool-call
+* budget, use middleware with `onBeforeToolCall` (per-turn cap) and
+* `onShouldContinue` (cumulative run budget) — see the docs recipe under
+* Agentic Cycle.
+*
+* @param max - Maximum number of model turns to allow
+* @returns AgentLoopStrategy that stops after max iterations
+*
+* @example
+* ```typescript
+* const stream = chat({
+*   adapter: openaiText(),
+*   model: "gpt-4o",
+*   messages: [...],
+*   tools: [weatherTool],
+*   agentLoopStrategy: maxIterations(3), // Max 3 model turns
+* });
+* ```
+*/
 function maxIterations(max) {
-  return ({ iterationCount }) => iterationCount < max;
-}
-function maxToolCalls(max) {
-  return ({ toolCallCount }) => toolCallCount < max;
+	return ({ iterationCount }) => iterationCount < max;
 }
+/**
+* Creates a strategy that continues until a specific finish reason is encountered
+*
+* @param stopReasons - Finish reasons that should stop the loop
+* @returns AgentLoopStrategy that stops on specific finish reasons
+*
+* @example
+* ```typescript
+* const stream = chat({
+*   adapter: openaiText(),
+*   model: "gpt-4o",
+*   messages: [...],
+*   tools: [weatherTool],
+*   agentLoopStrategy: untilFinishReason(["stop", "length"]),
+* });
+* ```
+*/
 function untilFinishReason(stopReasons) {
-  return ({ finishReason, iterationCount }) => {
-    if (iterationCount === 0) return true;
-    if (finishReason && stopReasons.includes(finishReason)) {
-      return false;
-    }
-    return true;
-  };
+	return ({ finishReason, iterationCount }) => {
+		if (iterationCount === 0) return true;
+		if (finishReason && stopReasons.includes(finishReason)) return false;
+		return true;
+	};
 }
+/**
+* Creates a strategy that combines multiple strategies with AND logic
+* All strategies must return true to continue
+*
+* @param strategies - Array of strategies to combine
+* @returns AgentLoopStrategy that continues only if all strategies agree
+*
+* @example
+* ```typescript
+* const stream = chat({
+*   adapter: openaiText(),
+*   model: "gpt-4o",
+*   messages: [...],
+*   tools: [weatherTool],
+*   agentLoopStrategy: combineStrategies([
+*     maxIterations(10),
+*     ({ messages }) => messages.length < 100,
+*   ]),
+* });
+* ```
+*/
 function combineStrategies(strategies) {
-  return (state) => {
-    return strategies.every((strategy) => strategy(state));
-  };
+	return (state) => {
+		return strategies.every((strategy) => strategy(state));
+	};
 }
-export {
-  combineStrategies,
-  maxIterations,
-  maxToolCalls,
-  untilFinishReason
-};
-//# sourceMappingURL=agent-loop-strategies.js.map
+//#endregion
+export { combineStrategies, maxIterations, untilFinishReason };
+
+//# sourceMappingURL=agent-loop-strategies.js.map

package/dist/esm/activities/chat/agent-loop-strategies.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop-strategies.js","sources":["../../../../src/activities/chat/agent-loop-strategies.ts"],"sourcesContent":["import type { AgentLoopStrategy } from '../../types'\n\n/**\n * Creates a strategy that continues for a maximum number of **model turns**\n * (iterations), not tool calls.\n *\n * One iteration can still emit many parallel tool calls. Prefer\n * {@link maxToolCalls} (and optionally `maxToolCallsPerTurn` on `chat()`)\n * when you need a tool-call budget.\n *\n * @param max - Maximum number of model turns to allow\n * @returns AgentLoopStrategy that stops after max iterations\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: maxIterations(3), // Max 3 model turns\n * });\n * ```\n */\nexport function maxIterations(max: number): AgentLoopStrategy {\n  return ({ iterationCount }) => iterationCount < max\n}\n\n/**\n * Creates a strategy that continues while `toolCallCount < max`.\n *\n * Unlike {@link maxIterations} (which counts model turns), this bounds\n * **emitted** tool calls counted during the run (including ones skipped by\n * `maxToolCallsPerTurn`). Strategies only run between turns, so the turn that\n * crosses `max` is not truncated — the final count (and executions, unless\n * `maxToolCallsPerTurn` is set) may exceed `max`. Pair with\n * `chat({ maxToolCallsPerTurn })` to also cap parallel fan-out inside a single\n * turn.\n *\n * @param max - Maximum cumulative emitted tool calls before stopping further turns\n * @returns AgentLoopStrategy that returns true while `toolCallCount < max`\n *\n * @example\n * ```typescript\n * import { chat, combineStrategies, maxIterations, maxToolCalls } from '@tanstack/ai'\n *\n * const stream = chat({\n *   adapter: openaiText('gpt-4o'),\n *   messages: [...],\n *   tools: [weatherTool],\n *   maxToolCallsPerTurn: 10,\n *   agentLoopStrategy: combineStrategies([\n *     maxIterations(20),\n *     maxToolCalls(20),\n *   ]),\n * })\n * ```\n */\nexport function maxToolCalls(max: number): AgentLoopStrategy {\n  return ({ toolCallCount }) => toolCallCount < max\n}\n\n/**\n * Creates a strategy that continues until a specific finish reason is encountered\n *\n * @param stopReasons - Finish reasons that should stop the loop\n * @returns AgentLoopStrategy that stops on specific finish reasons\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: untilFinishReason([\"stop\", \"length\"]),\n * });\n * ```\n */\nexport function untilFinishReason(\n  stopReasons: Array<string>,\n): AgentLoopStrategy {\n  return ({ finishReason, iterationCount }) => {\n    // Always allow at least one iteration\n    if (iterationCount === 0) return true\n\n    // Stop if we hit a stop reason\n    if (finishReason && stopReasons.includes(finishReason)) {\n      return false\n    }\n\n    // Otherwise continue\n    return true\n  }\n}\n\n/**\n * Creates a strategy that combines multiple strategies with AND logic\n * All strategies must return true to continue\n *\n * @param strategies - Array of strategies to combine\n * @returns AgentLoopStrategy that continues only if all strategies return true\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: combineStrategies([\n *     maxIterations(10),\n *     maxToolCalls(20),\n *     ({ messages }) => messages.length < 100,\n *   ]),\n * });\n * ```\n */\nexport function combineStrategies(\n  strategies: Array<AgentLoopStrategy>,\n): AgentLoopStrategy {\n  return (state) => {\n    return strategies.every((strategy) => strategy(state))\n  }\n}\n"],"names":[],"mappings":"AAwBO,SAAS,cAAc,KAAgC;AAC5D,SAAO,CAAC,EAAE,qBAAqB,iBAAiB;AAClD;AAgCO,SAAS,aAAa,KAAgC;AAC3D,SAAO,CAAC,EAAE,oBAAoB,gBAAgB;AAChD;AAmBO,SAAS,kBACd,aACmB;AACnB,SAAO,CAAC,EAAE,cAAc,qBAAqB;AAE3C,QAAI,mBAAmB,EAAG,QAAO;AAGjC,QAAI,gBAAgB,YAAY,SAAS,YAAY,GAAG;AACtD,aAAO;AAAA,IACT;AAGA,WAAO;AAAA,EACT;AACF;AAwBO,SAAS,kBACd,YACmB;AACnB,SAAO,CAAC,UAAU;AAChB,WAAO,WAAW,MAAM,CAAC,aAAa,SAAS,KAAK,CAAC;AAAA,EACvD;AACF;"}
+{"version":3,"file":"agent-loop-strategies.js","names":[],"sources":["../../../../src/activities/chat/agent-loop-strategies.ts"],"sourcesContent":["import type { AgentLoopStrategy } from '../../types'\n\n/**\n * Creates a strategy that continues for a maximum number of **model turns**\n * (iterations), not tool calls.\n *\n * One iteration can still emit many parallel tool calls. For a tool-call\n * budget, use middleware with `onBeforeToolCall` (per-turn cap) and\n * `onShouldContinue` (cumulative run budget) — see the docs recipe under\n * Agentic Cycle.\n *\n * @param max - Maximum number of model turns to allow\n * @returns AgentLoopStrategy that stops after max iterations\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: maxIterations(3), // Max 3 model turns\n * });\n * ```\n */\nexport function maxIterations(max: number): AgentLoopStrategy {\n  return ({ iterationCount }) => iterationCount < max\n}\n\n/**\n * Creates a strategy that continues until a specific finish reason is encountered\n *\n * @param stopReasons - Finish reasons that should stop the loop\n * @returns AgentLoopStrategy that stops on specific finish reasons\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: untilFinishReason([\"stop\", \"length\"]),\n * });\n * ```\n */\nexport function untilFinishReason(\n  stopReasons: Array<string>,\n): AgentLoopStrategy {\n  return ({ finishReason, iterationCount }) => {\n    // Always allow at least one iteration\n    if (iterationCount === 0) return true\n\n    // Stop if we hit a stop reason\n    if (finishReason && stopReasons.includes(finishReason)) {\n      return false\n    }\n\n    // Otherwise continue\n    return true\n  }\n}\n\n/**\n * Creates a strategy that combines multiple strategies with AND logic\n * All strategies must return true to continue\n *\n * @param strategies - Array of strategies to combine\n * @returns AgentLoopStrategy that continues only if all strategies agree\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: combineStrategies([\n *     maxIterations(10),\n *     ({ messages }) => messages.length < 100,\n *   ]),\n * });\n * ```\n */\nexport function combineStrategies(\n  strategies: Array<AgentLoopStrategy>,\n): AgentLoopStrategy {\n  return (state) => {\n    return strategies.every((strategy) => strategy(state))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,cAAc,KAAgC;CAC5D,QAAQ,EAAE,qBAAqB,iBAAiB;AAClD;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,kBACd,aACmB;CACnB,QAAQ,EAAE,cAAc,qBAAqB;EAE3C,IAAI,mBAAmB,GAAG,OAAO;EAGjC,IAAI,gBAAgB,YAAY,SAAS,YAAY,GACnD,OAAO;EAIT,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,kBACd,YACmB;CACnB,QAAQ,UAAU;EAChB,OAAO,WAAW,OAAO,aAAa,SAAS,KAAK,CAAC;CACvD;AACF"}

package/dist/esm/activities/chat/cancel.d.ts

@@ -0,0 +1,40 @@
+import { RunStore } from './middleware/run-store.js';
+/**
+ * Abort reason that marks an abort as an explicit cancellation.
+ *
+ * Namespaced so an application's own reason string cannot collide with it by
+ * accident, and matched with `===` (never a substring test) so an arbitrary
+ * provider error message can never be read as a deliberate cancel.
+ */
+export declare const RUN_CANCEL_REASON = "tanstack-ai:cancel-requested";
+/** Whether an abort reason means "the user explicitly cancelled this run". */
+export declare function isCancelRequestedReason(reason: string | undefined): boolean;
+/**
+ * Record an explicit cancel on the run record.
+ *
+ * Deliberately does NOT set a status. The driver is the only actor that knows
+ * when the agent has actually stopped and the sandbox has been torn down, so it
+ * owns the transition to `'aborted'`. Writing a terminal status here would tell
+ * every reader the run is over while the agent is still burning tokens.
+ *
+ * A no-op for an unknown `runId`, inheriting `RunStore.update`'s documented
+ * invariant.
+ */
+export declare function requestRunCancel(runs: RunStore, runId: string): Promise<void>;
+/**
+ * Whether an explicit cancel has been recorded for `runId`.
+ *
+ * Answers `false` rather than throwing when the store cannot be read. Callers
+ * are middleware abort hooks, which are already on a teardown path, and a
+ * store failure there must not replace the caller's own reason for tearing
+ * down with a store error. The cost of a false negative is that a cancel
+ * degrades into a detach — the run record gains `detachedSince`/`sandboxKey`
+ * instead of transitioning to `'aborted'`. `@tanstack/ai-sandbox`'s
+ * `reapDetachedRuns` recovers that run once the `detachedRunTtlMs` the
+ * application passes to that sweep has elapsed — nothing derives it from
+ * `withSandbox`, which has no TTL option — so the cost is a delayed teardown
+ * rather than a lost one, provided the application actually schedules the
+ * sweep, which is its job and not the framework's. Still strictly better than
+ * failing the teardown.
+ */
+export declare function wasCancelRequested(runs: RunStore, runId: string): Promise<boolean>;

package/dist/esm/activities/chat/cancel.js

@@ -0,0 +1,54 @@
+//#region src/activities/chat/cancel.ts
+/**
+* Abort reason that marks an abort as an explicit cancellation.
+*
+* Namespaced so an application's own reason string cannot collide with it by
+* accident, and matched with `===` (never a substring test) so an arbitrary
+* provider error message can never be read as a deliberate cancel.
+*/
+var RUN_CANCEL_REASON = "tanstack-ai:cancel-requested";
+/** Whether an abort reason means "the user explicitly cancelled this run". */
+function isCancelRequestedReason(reason) {
+	return reason === RUN_CANCEL_REASON;
+}
+/**
+* Record an explicit cancel on the run record.
+*
+* Deliberately does NOT set a status. The driver is the only actor that knows
+* when the agent has actually stopped and the sandbox has been torn down, so it
+* owns the transition to `'aborted'`. Writing a terminal status here would tell
+* every reader the run is over while the agent is still burning tokens.
+*
+* A no-op for an unknown `runId`, inheriting `RunStore.update`'s documented
+* invariant.
+*/
+async function requestRunCancel(runs, runId) {
+	await runs.update(runId, { cancelRequested: true });
+}
+/**
+* Whether an explicit cancel has been recorded for `runId`.
+*
+* Answers `false` rather than throwing when the store cannot be read. Callers
+* are middleware abort hooks, which are already on a teardown path, and a
+* store failure there must not replace the caller's own reason for tearing
+* down with a store error. The cost of a false negative is that a cancel
+* degrades into a detach — the run record gains `detachedSince`/`sandboxKey`
+* instead of transitioning to `'aborted'`. `@tanstack/ai-sandbox`'s
+* `reapDetachedRuns` recovers that run once the `detachedRunTtlMs` the
+* application passes to that sweep has elapsed — nothing derives it from
+* `withSandbox`, which has no TTL option — so the cost is a delayed teardown
+* rather than a lost one, provided the application actually schedules the
+* sweep, which is its job and not the framework's. Still strictly better than
+* failing the teardown.
+*/
+async function wasCancelRequested(runs, runId) {
+	try {
+		return (await runs.get(runId))?.cancelRequested === true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { RUN_CANCEL_REASON, isCancelRequestedReason, requestRunCancel, wasCancelRequested };
+
+//# sourceMappingURL=cancel.js.map

package/dist/esm/activities/chat/cancel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.js","names":[],"sources":["../../../../src/activities/chat/cancel.ts"],"sourcesContent":["/**\n * Out-of-band run cancellation.\n *\n * `ChatClient.stop()` only aborts a local `AbortController`; it sends nothing to\n * the server. A user pressing Stop and a user refreshing the page produce the\n * IDENTICAL TCP close, so intent is **not inferable** from a disconnect. It has\n * to arrive out of band, and there are exactly two bands:\n *\n * 1. **Durable** — {@link requestRunCancel} records the intent on the run's\n *    `RunRecord`. This is the only channel that works when the run is being\n *    driven by a DIFFERENT host than the one the cancel request reached, which\n *    is the normal case for a detached run.\n * 2. **In-process** — abort the run's signal with {@link RUN_CANCEL_REASON}.\n *    Core reads the reason back when it builds `AbortInfo`, so\n *    `AbortInfo.cancelRequested` is `true` for that abort and `false` for a\n *    disconnect. This is the fast path when the cancel reaches the driving host.\n *\n * A cancel endpoint SHOULD do both: record it (so a remote driver observes it)\n * and abort locally (so a co-located driver stops immediately).\n */\nimport type { RunStore } from './middleware/run-store'\n\n/**\n * Abort reason that marks an abort as an explicit cancellation.\n *\n * Namespaced so an application's own reason string cannot collide with it by\n * accident, and matched with `===` (never a substring test) so an arbitrary\n * provider error message can never be read as a deliberate cancel.\n */\nexport const RUN_CANCEL_REASON = 'tanstack-ai:cancel-requested'\n\n/** Whether an abort reason means \"the user explicitly cancelled this run\". */\nexport function isCancelRequestedReason(reason: string | undefined): boolean {\n  return reason === RUN_CANCEL_REASON\n}\n\n/**\n * Record an explicit cancel on the run record.\n *\n * Deliberately does NOT set a status. The driver is the only actor that knows\n * when the agent has actually stopped and the sandbox has been torn down, so it\n * owns the transition to `'aborted'`. Writing a terminal status here would tell\n * every reader the run is over while the agent is still burning tokens.\n *\n * A no-op for an unknown `runId`, inheriting `RunStore.update`'s documented\n * invariant.\n */\nexport async function requestRunCancel(\n  runs: RunStore,\n  runId: string,\n): Promise<void> {\n  await runs.update(runId, { cancelRequested: true })\n}\n\n/**\n * Whether an explicit cancel has been recorded for `runId`.\n *\n * Answers `false` rather than throwing when the store cannot be read. Callers\n * are middleware abort hooks, which are already on a teardown path, and a\n * store failure there must not replace the caller's own reason for tearing\n * down with a store error. The cost of a false negative is that a cancel\n * degrades into a detach — the run record gains `detachedSince`/`sandboxKey`\n * instead of transitioning to `'aborted'`. `@tanstack/ai-sandbox`'s\n * `reapDetachedRuns` recovers that run once the `detachedRunTtlMs` the\n * application passes to that sweep has elapsed — nothing derives it from\n * `withSandbox`, which has no TTL option — so the cost is a delayed teardown\n * rather than a lost one, provided the application actually schedules the\n * sweep, which is its job and not the framework's. Still strictly better than\n * failing the teardown.\n */\nexport async function wasCancelRequested(\n  runs: RunStore,\n  runId: string,\n): Promise<boolean> {\n  try {\n    const record = await runs.get(runId)\n    return record?.cancelRequested === true\n  } catch {\n    return false\n  }\n}\n"],"mappings":";;;;;;;;AA6BA,IAAa,oBAAoB;;AAGjC,SAAgB,wBAAwB,QAAqC;CAC3E,OAAO,WAAW;AACpB;;;;;;;;;;;;AAaA,eAAsB,iBACpB,MACA,OACe;CACf,MAAM,KAAK,OAAO,OAAO,EAAE,iBAAiB,KAAK,CAAC;AACpD;;;;;;;;;;;;;;;;;AAkBA,eAAsB,mBACpB,MACA,OACkB;CAClB,IAAI;EAEF,QAAO,MADc,KAAK,IAAI,KAAK,EAAA,EACpB,oBAAoB;CACrC,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/esm/activities/chat/index.d.ts

@@ -1,10 +1,9 @@
 import { AnyTextAdapter } from './adapter.js';
-import { AnyTool, ChatStream, ConstrainedModelMessage, InferSchemaType, LazyToolsConfig, ModelMessage, SchemaInput, StructuredOutputStream, TextOptions, UIMessage } from '../../types.js';
+import { AnyTool, ConstrainedModelMessage, InferSchemaType, LazyToolsConfig, ModelMessage, ProviderTool, SchemaInput, StructuredOutputStream, TextOptions, TypedStreamChunk, UIMessage } from '../../types.js';
 import { AnyChatMiddleware, ChatMiddleware } from './middleware/types.js';
 import { CheckCoverage } from './middleware/builder.js';
 import { SystemPrompt } from '../../system-prompts.js';
 import { DebugOption } from '../../logger/types.js';
-import { ProviderTool } from '../../tools/provider-tool.js';
 import { ContextFromMiddleware, ContextFromTool, DefinedContext, MergeContext, UnionToIntersection } from './runtime-context-types.js';
 import { ChatMCPOptions } from './mcp/types.js';
 /** The adapter kind this activity handles */
@@ -40,9 +39,10 @@ type TextActivityOptionsWithContext<TAdapter extends AnyTextAdapter, TSchema ext
  * @template TAdapter - The text adapter type (created by a provider function)
  * @template TSchema - Optional Standard Schema for structured output
  * @template TStream - Whether to stream the output (default: true)
+ * @template TContext - Runtime context value threaded to middleware hooks and server tools
  */
 export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TContext = unknown> {
-    /** The text adapter to use (created by a provider function like openaiText('gpt-4o')) */
+    /** The text adapter to use (created by a provider function like openaiText('gpt-5.5')) */
     adapter: TAdapter;
     /**
      * Conversation messages. Accepts:
@@ -76,7 +76,7 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
      *    `supports.tools` list. Passing an unsupported tool produces a
      *    compile-time error on the array element.
      */
-    tools?: Array<(AnyRuntimeTool & {
+    tools?: ReadonlyArray<(AnyRuntimeTool & {
         readonly '~toolKind'?: never;
     }) | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>> | undefined;
     /**
@@ -93,11 +93,6 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
     abortController?: TextOptions['abortController'];
     /** Strategy for controlling the agent loop */
     agentLoopStrategy?: TextOptions['agentLoopStrategy'];
-    /**
-     * Cap how many tool calls from a single model turn are executed.
-     * Excess calls receive error results. See {@link TextOptions.maxToolCallsPerTurn}.
-     */
-    maxToolCallsPerTurn?: TextOptions['maxToolCallsPerTurn'];
     /**
      * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
      * Tunes how much of each lazy tool's description appears in the discovery
@@ -112,6 +107,13 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
     runId?: TextOptions['runId'];
     /** Parent run ID for AG-UI protocol nested run correlation. */
     parentRunId?: TextOptions['parentRunId'];
+    /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
+    state?: TextOptions['state'];
+    /**
+     * AG-UI interrupt resume responses. Persistence middleware validates these
+     * before accepting new input on a thread with pending interrupts.
+     */
+    resume?: TextOptions['resume'];
     /**
      * Optional Standard Schema for structured output.
      * When provided, the activity will:
@@ -123,7 +125,7 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
      * @example
      * ```ts
      * const result = await chat({
-     *   adapter: openaiText('gpt-4o'),
+     *   adapter: openaiText('gpt-5.5'),
      *   messages: [{ role: 'user', content: 'Generate a person' }],
      *   outputSchema: z.object({ name: z.string(), age: z.number() })
      * })
@@ -133,7 +135,7 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
     outputSchema?: TSchema;
     /**
      * Whether to stream the text result.
-     * When true (default), returns an AsyncIterable<StreamChunk> for streaming output.
+     * When true (default), returns an AsyncIterable<TypedStreamChunk<TTools>> for streaming output.
      * When false, returns a Promise<string> with the collected text content.
      *
      * Note: If outputSchema is provided, this option is ignored and the result
@@ -144,7 +146,7 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
      * @example Non-streaming text
      * ```ts
      * const text = await chat({
-     *   adapter: openaiText('gpt-4o'),
+     *   adapter: openaiText('gpt-5.5'),
      *   messages: [{ role: 'user', content: 'Hello!' }],
      *   stream: false
      * })
@@ -159,7 +161,7 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
      * @example
      * ```ts
      * const stream = chat({
-     *   adapter: openaiText('gpt-4o'),
+     *   adapter: openaiText('gpt-5.5'),
      *   messages: [...],
      *   middleware: [loggingMiddleware, redactionMiddleware],
      * })
@@ -191,7 +193,9 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
  * const stream = chat({ ...chatOptions, messages })
  * ```
  */
-export declare function createChatOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = true, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TMiddleware extends TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware']>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TMiddleware>): TextActivityOptions<TAdapter, TSchema, TStream, InferredContext<TTools, TMiddleware>>;
+export declare function createChatOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = true, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TMiddleware extends TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware']>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TMiddleware>): Omit<TextActivityOptions<TAdapter, TSchema, TStream, InferredContext<TTools, TMiddleware>>, 'tools'> & {
+    tools?: TTools;
+};
 /**
  * Result type for the text activity.
  * - If outputSchema is provided AND stream is explicitly true:
@@ -201,14 +205,17 @@ export declare function createChatOptions<TAdapter extends AnyTextAdapter, TSche
  * - If outputSchema is provided without explicit stream:true:
  *   Promise<InferSchemaType<TSchema>>.
  * - If stream is explicitly false (no schema): Promise<string>.
- * - Otherwise (default): AsyncIterable<StreamChunk>.
+ * - Otherwise (default): AsyncIterable<TypedStreamChunk<TTools>>.
+ *
+ * When tools with typed schemas are provided, the stream chunks include
+ * type-safe `toolName` and `input` fields on tool call events.
  *
  * `[TStream] extends [true]` is used (not `TStream extends true`) so that the
  * default `boolean` value of `TStream` does *not* match the streaming branch.
  * Without this, plain `chat({ outputSchema })` would type as a stream while
  * the runtime returns a Promise — see issue #526.
  */
-export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream extends boolean = boolean> = TSchema extends SchemaInput ? [TStream] extends [true] ? StructuredOutputStream<InferSchemaType<TSchema>> : Promise<InferSchemaType<TSchema>> : [TStream] extends [false] ? Promise<string> : ChatStream;
+export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream extends boolean = boolean, TTools = ReadonlyArray<AnyTool>> = TSchema extends SchemaInput ? [TStream] extends [true] ? StructuredOutputStream<InferSchemaType<TSchema>> : Promise<InferSchemaType<TSchema>> : [TStream] extends [false] ? Promise<string> : AsyncIterable<TypedStreamChunk<TTools extends ReadonlyArray<AnyTool> ? TTools : ReadonlyArray<AnyTool>>>;
 /**
  * Text activity - handles agentic text generation, one-shot text generation, and agentic structured output.
  *
@@ -224,7 +231,7 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * import { openaiText } from '@tanstack/ai-openai'
  *
  * for await (const chunk of chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'What is the weather?' }],
  *   tools: [weatherTool]
  * })) {
@@ -237,7 +244,7 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * @example One-shot text (streaming without tools)
  * ```ts
  * for await (const chunk of chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * })) {
  *   console.log(chunk)
@@ -247,7 +254,7 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * @example Non-streaming text (stream: false)
  * ```ts
  * const text = await chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'Hello!' }],
  *   stream: false
  * })
@@ -259,7 +266,7 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * import { z } from 'zod'
  *
  * const result = await chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'Research and summarize the topic' }],
  *   tools: [researchTool, analyzeTool],
  *   outputSchema: z.object({
@@ -270,6 +277,6 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * // result is { summary: string, keyPoints: string[] }
  * ```
  */
-export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TMiddleware extends TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware']>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TMiddleware>): TextActivityResult<TSchema, TStream>;
+export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TMiddleware extends TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware']>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TMiddleware>): TextActivityResult<TSchema, TStream, TTools>;
 export type { TextAdapter, TextAdapterConfig, StructuredOutputOptions, StructuredOutputResult, } from './adapter.js';
 export { BaseTextAdapter } from './adapter.js';