@tanstack/ai 0.35.0 → 0.36.0

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

@@ -1,264 +0,0 @@
-import { AnyTextAdapter } from './adapter.js';
-import { AnyTool, ConstrainedModelMessage, InferSchemaType, 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'];
-    /** 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';