@tanstack/ai 0.23.1 → 0.25.0

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

@@ -1,4 +1,4 @@
-import { DefaultMessageMetadataByModality, JSONSchema, Modality, StreamChunk, TextOptions } from '../../types.js';
+import { DefaultMessageMetadataByModality, JSONSchema, Modality, StreamChunk, TextOptions, TokenUsage } from '../../types.js';
 /**
  * Configuration for adapter instances
  */
@@ -31,6 +31,8 @@ export interface StructuredOutputResult<T = unknown> {
     data: T;
     /** The raw text response from the model before parsing */
     rawText: string;
+    /** Token usage information (if provided by the adapter) */
+    usage?: TokenUsage;
 }
 /**
  * Text adapter interface with pre-resolved generics.

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} from '../../types'\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}\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   * @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\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":"AAkKO,MAAe,gBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAYC;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","sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\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   * @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\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":"AAqKO,MAAe,gBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAYC;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;"}

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

@@ -1,11 +1,36 @@
 import { AnyTextAdapter } from './adapter.js';
-import { ConstrainedModelMessage, InferSchemaType, ModelMessage, SchemaInput, StreamChunk, StructuredOutputStream, TextOptions, Tool, UIMessage } from '../../types.js';
+import { AnyTool, ConstrainedModelMessage, InferSchemaType, ModelMessage, SchemaInput, StreamChunk, StructuredOutputStream, TextOptions, UIMessage } from '../../types.js';
 import { ChatMiddleware } from './middleware/types.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';
 /** The adapter kind this activity handles */
 export declare const kind: "text";
+type AnyRuntimeTool = AnyTool;
+type ContextFromConsumer<T> = ContextFromTool<T> | ContextFromMiddleware<T>;
+type RequiredContextFromConsumerUnion<T> = T extends unknown ? undefined extends ContextFromConsumer<T> ? never : ContextFromConsumer<T> : never;
+type ContextFromConsumerUnion<T> = [
+    UnionToIntersection<DefinedContext<ContextFromConsumer<T>>>
+] extends [never] ? never : [RequiredContextFromConsumerUnion<T>] extends [never] ? UnionToIntersection<DefinedContext<ContextFromConsumer<T>>> | undefined : UnionToIntersection<DefinedContext<ContextFromConsumer<T>>>;
+type ContextFromArray<T> = T extends readonly [infer THead, ...infer TTail] ? MergeContext<ContextFromConsumer<THead>, ContextFromArray<TTail>> : T extends ReadonlyArray<infer TItem> ? ContextFromConsumerUnion<TItem> : never;
+type ContextFromInputs<TTools, TMiddleware> = MergeContext<ContextFromArray<NonNullable<TTools>>, ContextFromArray<NonNullable<TMiddleware>>>;
+type InferredContext<TTools, TMiddleware> = [
+    ContextFromInputs<TTools, TMiddleware>
+] extends [never] ? unknown : ContextFromInputs<TTools, TMiddleware>;
+type RequiredContextFromInputs<TTools, TMiddleware> = [
+    ContextFromInputs<TTools, TMiddleware>
+] extends [never] ? {
+    context?: unknown;
+} : undefined extends ContextFromInputs<TTools, TMiddleware> ? {
+    context?: ContextFromInputs<TTools, TMiddleware>;
+} : {
+    context: ContextFromInputs<TTools, TMiddleware>;
+};
+type TextActivityOptionsWithContext<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], TMiddleware extends TextActivityOptions<TAdapter, TSchema, TStream, any>['middleware']> = Omit<TextActivityOptions<TAdapter, TSchema, TStream, any>, 'tools' | 'middleware' | 'context'> & {
+    tools?: TTools;
+    middleware?: TMiddleware;
+} & RequiredContextFromInputs<TTools, TMiddleware>;
 /**
  * Options for the text activity.
  * Types are extracted directly from the adapter (which has pre-resolved generics).
@@ -14,7 +39,7 @@ export declare const kind: "text";
  * @template TSchema - Optional Standard Schema for structured output
  * @template TStream - Whether to stream the output (default: true)
  */
-export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean> {
+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')) */
     adapter: TAdapter;
     /**
@@ -49,7 +74,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<(Tool & {
+    tools?: Array<(AnyRuntimeTool & {
         readonly '~toolKind'?: never;
     }) | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>> | undefined;
     /** Controls the randomness of the output. Higher values make output more random. Range: [0.0, 2.0] */
@@ -127,12 +152,11 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
      * })
      * ```
      */
-    middleware?: Array<ChatMiddleware>;
+    middleware?: Array<ChatMiddleware<TContext>>;
     /**
-     * Opaque user-provided context value passed to middleware hooks.
-     * Can be used to pass request-scoped data (e.g., user ID, request context).
+     * Runtime context value passed to middleware hooks and server tools.
      */
-    context?: unknown;
+    context?: TContext;
     /**
      * Enable debug logging. Pass `true` to enable all categories with the default
      * console logger, `false` to silence everything, or a `DebugConfig` object for
@@ -154,7 +178,7 @@ 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>(options: TextActivityOptions<TAdapter, TSchema, TStream>): TextActivityOptions<TAdapter, TSchema, TStream>;
+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>>;
 /**
  * Result type for the text activity.
  * - If outputSchema is provided AND stream is explicitly true:
@@ -233,6 +257,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>(options: TextActivityOptions<TAdapter, TSchema, TStream>): 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>;
 export type { TextAdapter, TextAdapterConfig, StructuredOutputOptions, StructuredOutputResult, } from './adapter.js';
 export { BaseTextAdapter } from './adapter.js';

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

@@ -2,6 +2,7 @@ import { devtoolsMiddleware } from "@tanstack/ai-event-client";
 import { stripToSpecMiddleware } from "../../strip-to-spec-middleware.js";
 import { streamToText } from "../../stream-to-response.js";
 import { resolveDebugOption } from "../../logger/resolve.js";
+import { normalizeToolResult } from "../../utilities/tool-result.js";
 import { LazyToolManager } from "./tools/lazy-tool-manager.js";
 import { ToolCallManager, MiddlewareAbortError, executeToolCalls } from "./tools/tool-calls.js";
 import { convertSchemaToJsonSchema, isStandardSchema, parseWithStandardSchema } from "./tools/schema-converter.js";
@@ -567,7 +568,8 @@ class TextEngine {
             info
           );
         }
-      }
+      },
+      this.middlewareCtx.context
     );
     const executionResult = yield* this.drainToolCallGenerator(generator);
     if (this.isMiddlewareAborted()) {
@@ -697,7 +699,8 @@ class TextEngine {
             info
           );
         }
-      }
+      },
+      this.middlewareCtx.context
     );
     const executionResult = yield* this.drainToolCallGenerator(generator);
     this.middlewareCtx.phase = "afterTools";
@@ -798,10 +801,14 @@ class TextEngine {
     for (const message of this.messages) {
       if (message.role === "tool" && message.toolCallId) {
         let output;
-        try {
-          output = JSON.parse(message.content);
-        } catch {
+        if (Array.isArray(message.content)) {
           output = message.content;
+        } else {
+          try {
+            output = JSON.parse(message.content);
+          } catch {
+            output = message.content;
+          }
         }
         if (output && typeof output === "object" && output.pendingExecution === true) {
           continue;
@@ -852,7 +859,8 @@ class TextEngine {
   buildToolResultChunks(results, finishEvent, argsMap) {
     const chunks = [];
     for (const result of results) {
-      const content = JSON.stringify(result.result);
+      const content = normalizeToolResult(result.result);
+      const wireContent = typeof content === "string" ? content : JSON.stringify(content);
       if (argsMap) {
         chunks.push({
           type: "TOOL_CALL_START",
@@ -879,7 +887,8 @@ class TextEngine {
         toolCallId: result.toolCallId,
         toolCallName: result.toolName,
         toolName: result.toolName,
-        result: content
+        result: wireContent,
+        ...result.state !== void 0 && { state: result.state }
       });
       chunks.push({
         type: "TOOL_CALL_RESULT",
@@ -887,8 +896,9 @@ class TextEngine {
         model: finishEvent.model,
         messageId: this.createId("tool-result"),
         toolCallId: result.toolCallId,
-        content,
-        role: "tool"
+        content: wireContent,
+        role: "tool",
+        ...result.state !== void 0 && { state: result.state }
       });
       const placeholderIdx = this.messages.findIndex((m) => {
         if (m.role !== "tool" || m.toolCallId !== result.toolCallId) {