@tanstack/ai 0.36.0 → 0.37.0

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

@@ -0,0 +1,163 @@
+import { DefaultMessageMetadataByModality, JSONSchema, Modality, StreamChunk, TextOptions, TokenUsage } from '../../types.js';
+import { CapabilityHandle } from './middleware/capabilities.js';
+/**
+ * Configuration for adapter instances
+ */
+export interface TextAdapterConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Options for structured output generation.
+ *
+ * The internal logger is threaded through `chatOptions.logger` (inherited from
+ * `TextOptions`). Adapter implementations must call `logger.request()` before
+ * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`
+ * in catch blocks.
+ */
+export interface StructuredOutputOptions<TProviderOptions extends object> {
+    /** Text options for the request */
+    chatOptions: TextOptions<TProviderOptions>;
+    /** JSON Schema for structured output - already converted from Zod in the ai layer */
+    outputSchema: JSONSchema;
+}
+/**
+ * Result from structured output generation
+ */
+export interface StructuredOutputResult<T = unknown> {
+    /** The parsed data conforming to the schema */
+    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.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'gpt-4o')
+ * - TProviderOptions: Provider-specific options for this model (already resolved)
+ * - TInputModalities: Supported input modalities for this model (already resolved)
+ * - TMessageMetadata: Metadata types for content parts (already resolved)
+ * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`
+ * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)
+ * - TSystemPromptMetadata: Provider-typed metadata accepted on each
+ *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to
+ *   `never` — adapters without per-prompt metadata reject the `metadata`
+ *   field at the call site.
+ */
+export interface TextAdapter<TModel extends string, TProviderOptions extends Record<string, any>, TInputModalities extends ReadonlyArray<Modality>, TMessageMetadataByModality extends DefaultMessageMetadataByModality, TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>, TToolCallMetadata = unknown, TSystemPromptMetadata = never> {
+    /** Discriminator for adapter kind */
+    readonly kind: 'text';
+    /** Provider name identifier (e.g., 'openai', 'anthropic') */
+    readonly name: string;
+    /** The model this adapter is configured for */
+    readonly model: TModel;
+    /**
+     * Capabilities this adapter requires at runtime. `chat()` validates that the
+     * configured middleware provides each one. Model adapters omit this; harness
+     * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.
+     * Runtime access to capabilities from inside the adapter is not yet wired —
+     * this is the declaration/validation surface only.
+     */
+    readonly requires?: ReadonlyArray<CapabilityHandle>;
+    /**
+     * @internal Type-only properties for inference. Not assigned at runtime.
+     */
+    '~types': {
+        providerOptions: TProviderOptions;
+        inputModalities: TInputModalities;
+        messageMetadataByModality: TMessageMetadataByModality;
+        toolCapabilities: TToolCapabilities;
+        toolCallMetadata: TToolCallMetadata;
+        systemPromptMetadata: TSystemPromptMetadata;
+    };
+    /**
+     * Stream text completions from the model
+     */
+    chatStream: (options: TextOptions<TProviderOptions>) => AsyncIterable<StreamChunk>;
+    /**
+     * Generate structured output using the provider's native structured output API.
+     * This method uses stream: false and sends the JSON schema to the provider
+     * to ensure the response conforms to the expected structure.
+     *
+     * @param options - Structured output options containing chat options and JSON schema
+     * @returns Promise with the raw data (validation is done in the chat function)
+     */
+    structuredOutput: (options: StructuredOutputOptions<TProviderOptions>) => Promise<StructuredOutputResult<unknown>>;
+    /**
+     * Stream structured output using the provider's native streaming structured
+     * output API (stream + response_format json_schema in a single request).
+     *
+     * Optional — adapters without native streaming JSON omit this method and the
+     * activity layer synthesizes a stream around the non-streaming
+     * `structuredOutput` call.
+     *
+     * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,
+     * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final
+     * `CUSTOM` event named `structured-output.complete` whose `value` is
+     * `{ object, raw, reasoning? }`.
+     */
+    structuredOutputStream?: (options: StructuredOutputOptions<TProviderOptions>) => AsyncIterable<StreamChunk>;
+    /**
+     * Declares whether the adapter supports combining `tools` and a
+     * schema-constrained final answer in a single streaming request.
+     *
+     * When `true`, the engine wires `outputSchema` into the regular
+     * `chatStream()` call and skips the separate `runStructuredFinalization`
+     * round-trip. The model's natural final turn carries the
+     * schema-constrained JSON text and the engine harvests it from the agent
+     * loop's accumulated content.
+     *
+     * When `false`, `undefined`, or the method is omitted, the engine runs
+     * the agent loop without `outputSchema` and then issues a separate
+     * `structuredOutput` / `structuredOutputStream` call against the JSON
+     * schema for finalization (the legacy path).
+     *
+     * The method receives the per-call `modelOptions` so providers whose
+     * support depends on the resolved upstream model (e.g. OpenRouter) can
+     * answer per-request. Most adapters can return a constant.
+     */
+    supportsCombinedToolsAndSchema?: (modelOptions?: TProviderOptions | undefined) => boolean;
+}
+/**
+ * A TextAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>;
+/**
+ * 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.
+ */
+export declare abstract class BaseTextAdapter<TModel extends string, TProviderOptions extends Record<string, any>, TInputModalities extends ReadonlyArray<Modality>, TMessageMetadataByModality extends DefaultMessageMetadataByModality, TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>, TToolCallMetadata = unknown, TSystemPromptMetadata = never> implements TextAdapter<TModel, TProviderOptions, TInputModalities, TMessageMetadataByModality, TToolCapabilities, TToolCallMetadata, TSystemPromptMetadata> {
+    readonly kind: "text";
+    abstract readonly name: string;
+    readonly model: TModel;
+    readonly requires?: ReadonlyArray<CapabilityHandle>;
+    '~types': {
+        providerOptions: TProviderOptions;
+        inputModalities: TInputModalities;
+        messageMetadataByModality: TMessageMetadataByModality;
+        toolCapabilities: TToolCapabilities;
+        toolCallMetadata: TToolCallMetadata;
+        systemPromptMetadata: TSystemPromptMetadata;
+    };
+    protected config: TextAdapterConfig;
+    constructor(config: TextAdapterConfig | undefined, model: TModel);
+    abstract chatStream(options: TextOptions<TProviderOptions>): AsyncIterable<StreamChunk>;
+    /**
+     * Generate structured output using the provider's native structured output API.
+     * Concrete implementations should override this to use provider-specific structured output.
+     */
+    abstract structuredOutput(options: StructuredOutputOptions<TProviderOptions>): Promise<StructuredOutputResult<unknown>>;
+    protected generateId(): string;
+}

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

@@ -0,0 +1,17 @@
+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
+};
+//# sourceMappingURL=adapter.js.map

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

@@ -0,0 +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;"}

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

@@ -0,0 +1,59 @@
+import { AgentLoopStrategy } from '../../types.js';
+/**
+ * Creates a strategy that continues for a maximum number of iterations
+ *
+ * @param max - Maximum number of iterations 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 iterations
+ * });
+ * ```
+ */
+export declare function maxIterations(max: number): AgentLoopStrategy;
+/**
+ * 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"]),
+ * });
+ * ```
+ */
+export declare function untilFinishReason(stopReasons: Array<string>): AgentLoopStrategy;
+/**
+ * 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 return true
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({
+ *   adapter: openaiText(),
+ *   model: "gpt-4o",
+ *   messages: [...],
+ *   tools: [weatherTool],
+ *   agentLoopStrategy: combineStrategies([
+ *     maxIterations(10),
+ *     ({ messages }) => messages.length < 100,
+ *   ]),
+ * });
+ * ```
+ */
+export declare function combineStrategies(strategies: Array<AgentLoopStrategy>): AgentLoopStrategy;

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

@@ -0,0 +1,23 @@
+function maxIterations(max) {
+  return ({ iterationCount }) => iterationCount < max;
+}
+function untilFinishReason(stopReasons) {
+  return ({ finishReason, iterationCount }) => {
+    if (iterationCount === 0) return true;
+    if (finishReason && stopReasons.includes(finishReason)) {
+      return false;
+    }
+    return true;
+  };
+}
+function combineStrategies(strategies) {
+  return (state) => {
+    return strategies.every((strategy) => strategy(state));
+  };
+}
+export {
+  combineStrategies,
+  maxIterations,
+  untilFinishReason
+};
+//# sourceMappingURL=agent-loop-strategies.js.map

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

@@ -0,0 +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 iterations\n *\n * @param max - Maximum number of iterations 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 iterations\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 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 *     ({ 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":"AAmBO,SAAS,cAAc,KAAgC;AAC5D,SAAO,CAAC,EAAE,qBAAqB,iBAAiB;AAClD;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;AAuBO,SAAS,kBACd,YACmB;AACnB,SAAO,CAAC,UAAU;AAChB,WAAO,WAAW,MAAM,CAAC,aAAa,SAAS,KAAK,CAAC;AAAA,EACvD;AACF;"}

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

@@ -0,0 +1,270 @@
+import { AnyTextAdapter } from './adapter.js';
+import { AnyTool, ConstrainedModelMessage, InferSchemaType, LazyToolsConfig, ModelMessage, SchemaInput, StreamChunk, StructuredOutputStream, TextOptions, 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 */
+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 & CheckCoverage<Extract<TMiddleware, ReadonlyArray<AnyChatMiddleware>>>;
+} & RequiredContextFromInputs<TTools, TMiddleware>;
+/**
+ * Options for the text activity.
+ * Types are extracted directly from the adapter (which has pre-resolved generics).
+ *
+ * @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)
+ */
+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;
+    /**
+     * Conversation messages. Accepts:
+     * - `ConstrainedModelMessage` — content types constrained by the adapter's input modalities.
+     * - `ModelMessage` — unconstrained model message (e.g., forwarded from an AG-UI wire payload).
+     * - `UIMessage` — parts-based UI representation; converted internally via `convertMessagesToModelMessages`.
+     *
+     * The three shapes can be mixed in a single array (e.g., when forwarding a wire payload that includes both anchor UIMessages and AG-UI fan-out ModelMessages).
+     */
+    messages?: Array<UIMessage | ModelMessage | ConstrainedModelMessage<{
+        inputModalities: TAdapter['~types']['inputModalities'];
+        messageMetadataByModality: TAdapter['~types']['messageMetadataByModality'];
+    }>> | undefined;
+    /**
+     * System prompts to prepend to the conversation.
+     *
+     * Accepts plain strings or `{ content, metadata }` objects. The `metadata`
+     * field is typed by the adapter — Anthropic narrows it to
+     * `AnthropicSystemPromptMetadata` (with `cache_control` for prompt
+     * caching), providers without per-prompt metadata reject the field
+     * entirely.
+     */
+    systemPrompts?: Array<SystemPrompt<TAdapter['~types']['systemPromptMetadata']>> | undefined;
+    /**
+     * Tools for function calling (auto-executed when called).
+     *
+     * Accepts two shapes:
+     *  - User-defined tools via `toolDefinition()` — plain `Tool`, always assignable.
+     *  - Provider tools from `@tanstack/ai-<provider>/tools` (e.g. `webSearchTool`)
+     *    — branded and type-checked against the selected model's
+     *    `supports.tools` list. Passing an unsupported tool produces a
+     *    compile-time error on the array element.
+     */
+    tools?: Array<(AnyRuntimeTool & {
+        readonly '~toolKind'?: never;
+    }) | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>> | undefined;
+    /**
+     * Hand MCP clients/pools to chat(): their tools are discovered at run start
+     * and merged into the run; `connection` controls whether chat() closes them
+     * when the run ends. See docs/tools/mcp.md "Managing MCP clients with chat()".
+     */
+    mcp?: ChatMCPOptions;
+    /** Additional metadata to attach to the request. */
+    metadata?: TextOptions['metadata'];
+    /** Model-specific provider options (type comes from adapter) */
+    modelOptions?: TAdapter['~types']['providerOptions'];
+    /** AbortController for cancellation */
+    abortController?: TextOptions['abortController'];
+    /** Strategy for controlling the agent loop */
+    agentLoopStrategy?: TextOptions['agentLoopStrategy'];
+    /**
+     * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
+     * Tunes how much of each lazy tool's description appears in the discovery
+     * catalog. Optional — defaults to `{ includeDescription: 'none' }`.
+     */
+    lazyToolsConfig?: LazyToolsConfig;
+    /** Unique conversation identifier for tracking */
+    conversationId?: TextOptions['conversationId'];
+    /** Thread/conversation ID for AG-UI protocol. Auto-generated if not provided. */
+    threadId?: TextOptions['threadId'];
+    /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */
+    runId?: TextOptions['runId'];
+    /** Parent run ID for AG-UI protocol nested run correlation. */
+    parentRunId?: TextOptions['parentRunId'];
+    /**
+     * Optional Standard Schema for structured output.
+     * When provided, the activity will:
+     * 1. Run the full agentic loop (executing tools as needed)
+     * 2. Once complete, return a Promise with the parsed output matching the schema
+     *
+     * Supports any Standard Schema compliant library (Zod v4+, ArkType, Valibot, etc.)
+     *
+     * @example
+     * ```ts
+     * const result = await chat({
+     *   adapter: openaiText('gpt-4o'),
+     *   messages: [{ role: 'user', content: 'Generate a person' }],
+     *   outputSchema: z.object({ name: z.string(), age: z.number() })
+     * })
+     * // result is { name: string, age: number }
+     * ```
+     */
+    outputSchema?: TSchema;
+    /**
+     * Whether to stream the text result.
+     * When true (default), returns an AsyncIterable<StreamChunk> 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
+     * is always a Promise<InferSchemaType<TSchema>>.
+     *
+     * @default true
+     *
+     * @example Non-streaming text
+     * ```ts
+     * const text = await chat({
+     *   adapter: openaiText('gpt-4o'),
+     *   messages: [{ role: 'user', content: 'Hello!' }],
+     *   stream: false
+     * })
+     * // text is a string with the full response
+     * ```
+     */
+    stream?: TStream;
+    /**
+     * Optional middleware array for observing/transforming chat behavior.
+     * Middleware hooks are called in array order. See {@link ChatMiddleware} for available hooks.
+     *
+     * @example
+     * ```ts
+     * const stream = chat({
+     *   adapter: openaiText('gpt-4o'),
+     *   messages: [...],
+     *   middleware: [loggingMiddleware, redactionMiddleware],
+     * })
+     * ```
+     */
+    middleware?: Array<ChatMiddleware<TContext>>;
+    /**
+     * Runtime context value passed to middleware hooks and server tools.
+     */
+    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
+     * granular control and/or a custom `Logger`. Defaults to `undefined`, which
+     * means only the `errors` category is active.
+     */
+    debug?: DebugOption;
+}
+/**
+ * Create typed options for the chat() function without executing.
+ * This is useful for pre-defining configurations with full type inference.
+ *
+ * @example
+ * ```ts
+ * const chatOptions = createChatOptions({
+ *   adapter: anthropicText('claude-sonnet-4-5'),
+ * })
+ *
+ * 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>>;
+/**
+ * Result type for the text activity.
+ * - If outputSchema is provided AND stream is explicitly true:
+ *   StructuredOutputStream<InferSchemaType<TSchema>> — yields raw JSON deltas
+ *   via TEXT_MESSAGE_CONTENT plus a terminal StructuredOutputCompleteEvent
+ *   carrying the validated object.
+ * - If outputSchema is provided without explicit stream:true:
+ *   Promise<InferSchemaType<TSchema>>.
+ * - If stream is explicitly false (no schema): Promise<string>.
+ * - Otherwise (default): AsyncIterable<StreamChunk>.
+ *
+ * `[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> : AsyncIterable<StreamChunk>;
+/**
+ * Text activity - handles agentic text generation, one-shot text generation, and agentic structured output.
+ *
+ * This activity supports four modes:
+ * 1. **Streaming agentic text**: Stream responses with automatic tool execution
+ * 2. **Streaming one-shot text**: Simple streaming request/response without tools
+ * 3. **Non-streaming text**: Returns collected text as a string (stream: false)
+ * 4. **Agentic structured output**: Run tools, then return structured data
+ *
+ * @example Full agentic text (streaming with tools)
+ * ```ts
+ * import { chat } from '@tanstack/ai'
+ * import { openaiText } from '@tanstack/ai-openai'
+ *
+ * for await (const chunk of chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'What is the weather?' }],
+ *   tools: [weatherTool]
+ * })) {
+ *   if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+ *     console.log(chunk.delta)
+ *   }
+ * }
+ * ```
+ *
+ * @example One-shot text (streaming without tools)
+ * ```ts
+ * for await (const chunk of chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * })) {
+ *   console.log(chunk)
+ * }
+ * ```
+ *
+ * @example Non-streaming text (stream: false)
+ * ```ts
+ * const text = await chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   stream: false
+ * })
+ * // text is a string with the full response
+ * ```
+ *
+ * @example Agentic structured output (tools + structured response)
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const result = await chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'Research and summarize the topic' }],
+ *   tools: [researchTool, analyzeTool],
+ *   outputSchema: z.object({
+ *     summary: z.string(),
+ *     keyPoints: z.array(z.string())
+ *   })
+ * })
+ * // 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 type { TextAdapter, TextAdapterConfig, StructuredOutputOptions, StructuredOutputResult, } from './adapter.js';
+export { BaseTextAdapter } from './adapter.js';