@tanstack/ai 0.23.1 → 0.24.0

package/dist/esm/index.js

@@ -6,7 +6,7 @@ import { createVideoOptions, generateVideo, getVideoJobStatus } from "./activiti
 import { createSpeechOptions, generateSpeech } from "./activities/generateSpeech/index.js";
 import { createTranscriptionOptions, generateTranscription } from "./activities/generateTranscription/index.js";
 import { toolDefinition } from "./activities/chat/tools/tool-definition.js";
-import { StandardSchemaValidationError, convertSchemaToJsonSchema } from "./activities/chat/tools/schema-converter.js";
+import { StandardSchemaValidationError, convertSchemaToJsonSchema, isStandardSchema, parseWithStandardSchema } from "./activities/chat/tools/schema-converter.js";
 import { streamToText, toHttpResponse, toHttpStream, toServerSentEventsResponse, toServerSentEventsStream } from "./stream-to-response.js";
 import { ToolCallManager } from "./activities/chat/tools/tool-calls.js";
 import { brandProviderTool } from "./tools/provider-tool.js";
@@ -18,6 +18,7 @@ import { realtimeToken } from "./realtime/index.js";
 import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, uiMessageToModelMessages } from "./activities/chat/messages.js";
 import { chatParamsFromRequest, chatParamsFromRequestBody, mergeAgentTools } from "./utilities/chat-params.js";
 import { uiMessagesToWire } from "./utilities/ag-ui-wire.js";
+import { isContentPart, isContentPartArray, normalizeToolResult } from "./utilities/tool-result.js";
 import { createModel, extendAdapter } from "./extend-adapter.js";
 import { ConsoleLogger } from "./logger/console-logger.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PunctuationStrategy, WordBoundaryStrategy } from "./activities/chat/stream/strategies.js";
@@ -64,13 +65,18 @@ export {
   generateTranscription,
   generateVideo,
   getVideoJobStatus,
+  isContentPart,
+  isContentPartArray,
+  isStandardSchema,
   maxIterations,
   mergeAgentTools,
   modelMessageToUIMessage,
   modelMessagesToUIMessages,
   normalizeSystemPrompts,
   normalizeToUIMessage,
+  normalizeToolResult,
   parsePartialJSON,
+  parseWithStandardSchema,
   realtimeToken,
   streamToText,
   summarize,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/tool-registry.d.ts

@@ -1,23 +1,23 @@
-import { Tool } from './types.js';
+import { AnyTool } from './types.js';
 /**
  * A registry that holds tools and allows dynamic tool management.
  *
  * The registry can be either mutable (allowing additions/removals during execution)
  * or frozen (static tool list, for backward compatibility with tools arrays).
  */
-export interface ToolRegistry {
+export interface ToolRegistry<TTool extends AnyTool = AnyTool> {
     /**
      * Get all current tools in the registry.
      * Called each agent loop iteration to get the latest tool list.
      */
-    getTools: () => ReadonlyArray<Tool>;
+    getTools: () => Array<TTool>;
     /**
      * Add a tool to the registry dynamically.
      * For frozen registries, this is a no-op.
      *
      * @param tool - The tool to add
      */
-    add: (tool: Tool) => void;
+    add: (tool: TTool) => void;
     /**
      * Remove a tool from the registry by name.
      * For frozen registries, this always returns false.
@@ -38,7 +38,7 @@ export interface ToolRegistry {
      * @param name - The name of the tool to get
      * @returns The tool if found, undefined otherwise
      */
-    get: (name: string) => Tool | undefined;
+    get: (name: string) => TTool | undefined;
     /**
      * Whether this registry is frozen (immutable).
      * Frozen registries don't allow add/remove operations.
@@ -68,7 +68,7 @@ export interface ToolRegistry {
  * registry.add(newTool)  // Immediately available to LLM
  * ```
  */
-export declare function createToolRegistry(initialTools?: Array<Tool>): ToolRegistry;
+export declare function createToolRegistry<TTool extends AnyTool = AnyTool>(initialTools?: Array<TTool>): ToolRegistry<TTool>;
 /**
  * Create a frozen (immutable) tool registry from a tools array.
  *
@@ -78,4 +78,4 @@ export declare function createToolRegistry(initialTools?: Array<Tool>): ToolRegi
  * @param tools - The static array of tools
  * @returns A frozen ToolRegistry
  */
-export declare function createFrozenRegistry(tools?: Array<Tool>): ToolRegistry;
+export declare function createFrozenRegistry<TTool extends AnyTool = AnyTool>(tools?: Array<TTool>): ToolRegistry<TTool>;

package/dist/esm/tool-registry.js

@@ -27,7 +27,7 @@ function createFrozenRegistry(tools = []) {
   }
   const frozenTools = Object.freeze([...tools]);
   return {
-    getTools: () => frozenTools,
+    getTools: () => [...frozenTools],
     add: (_tool) => {
     },
     remove: (_name) => {

package/dist/esm/tool-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.js","sources":["../../src/tool-registry.ts"],"sourcesContent":["import type { Tool } from './types'\n\n/**\n * A registry that holds tools and allows dynamic tool management.\n *\n * The registry can be either mutable (allowing additions/removals during execution)\n * or frozen (static tool list, for backward compatibility with tools arrays).\n */\nexport interface ToolRegistry {\n  /**\n   * Get all current tools in the registry.\n   * Called each agent loop iteration to get the latest tool list.\n   */\n  getTools: () => ReadonlyArray<Tool>\n\n  /**\n   * Add a tool to the registry dynamically.\n   * For frozen registries, this is a no-op.\n   *\n   * @param tool - The tool to add\n   */\n  add: (tool: Tool) => void\n\n  /**\n   * Remove a tool from the registry by name.\n   * For frozen registries, this always returns false.\n   *\n   * @param name - The name of the tool to remove\n   * @returns true if the tool was removed, false if not found or frozen\n   */\n  remove: (name: string) => boolean\n\n  /**\n   * Check if a tool exists in the registry.\n   *\n   * @param name - The name of the tool to check\n   */\n  has: (name: string) => boolean\n\n  /**\n   * Get a tool by name.\n   *\n   * @param name - The name of the tool to get\n   * @returns The tool if found, undefined otherwise\n   */\n  get: (name: string) => Tool | undefined\n\n  /**\n   * Whether this registry is frozen (immutable).\n   * Frozen registries don't allow add/remove operations.\n   */\n  readonly isFrozen: boolean\n}\n\n/**\n * Create a mutable tool registry for dynamic tool scenarios.\n *\n * Tools can be added and removed during chat execution, and the\n * changes will be reflected in subsequent agent loop iterations.\n *\n * @param initialTools - Optional initial set of tools\n * @returns A mutable ToolRegistry\n *\n * @example\n * ```typescript\n * const registry = createToolRegistry([toolA, toolB])\n *\n * const stream = chat({\n *   adapter,\n *   messages,\n *   toolRegistry: registry,\n * })\n *\n * // Later, during tool execution:\n * registry.add(newTool)  // Immediately available to LLM\n * ```\n */\nexport function createToolRegistry(\n  initialTools: Array<Tool> = [],\n): ToolRegistry {\n  const tools = new Map<string, Tool>()\n\n  for (const tool of initialTools) {\n    tools.set(tool.name, tool)\n  }\n\n  return {\n    getTools: () => Array.from(tools.values()),\n\n    add: (tool: Tool) => {\n      tools.set(tool.name, tool)\n    },\n\n    remove: (name: string) => {\n      return tools.delete(name)\n    },\n\n    has: (name: string) => {\n      return tools.has(name)\n    },\n\n    get: (name: string) => {\n      return tools.get(name)\n    },\n\n    isFrozen: false,\n  }\n}\n\n/**\n * Create a frozen (immutable) tool registry from a tools array.\n *\n * This is used internally to wrap static `tools` arrays for backward compatibility.\n * Add and remove operations are no-ops on frozen registries.\n *\n * @param tools - The static array of tools\n * @returns A frozen ToolRegistry\n */\nexport function createFrozenRegistry(tools: Array<Tool> = []): ToolRegistry {\n  const toolMap = new Map<string, Tool>()\n\n  for (const tool of tools) {\n    toolMap.set(tool.name, tool)\n  }\n\n  const frozenTools = Object.freeze([...tools])\n\n  return {\n    getTools: () => frozenTools,\n\n    add: (_tool: Tool) => {\n      // No-op for frozen registry\n    },\n\n    remove: (_name: string) => {\n      // No-op for frozen registry\n      return false\n    },\n\n    has: (name: string) => {\n      return toolMap.has(name)\n    },\n\n    get: (name: string) => {\n      return toolMap.get(name)\n    },\n\n    isFrozen: true,\n  }\n}\n"],"names":[],"mappings":"AA6EO,SAAS,mBACd,eAA4B,IACd;AACd,QAAM,4BAAY,IAAA;AAElB,aAAW,QAAQ,cAAc;AAC/B,UAAM,IAAI,KAAK,MAAM,IAAI;AAAA,EAC3B;AAEA,SAAO;AAAA,IACL,UAAU,MAAM,MAAM,KAAK,MAAM,QAAQ;AAAA,IAEzC,KAAK,CAAC,SAAe;AACnB,YAAM,IAAI,KAAK,MAAM,IAAI;AAAA,IAC3B;AAAA,IAEA,QAAQ,CAAC,SAAiB;AACxB,aAAO,MAAM,OAAO,IAAI;AAAA,IAC1B;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,MAAM,IAAI,IAAI;AAAA,IACvB;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,MAAM,IAAI,IAAI;AAAA,IACvB;AAAA,IAEA,UAAU;AAAA,EAAA;AAEd;AAWO,SAAS,qBAAqB,QAAqB,IAAkB;AAC1E,QAAM,8BAAc,IAAA;AAEpB,aAAW,QAAQ,OAAO;AACxB,YAAQ,IAAI,KAAK,MAAM,IAAI;AAAA,EAC7B;AAEA,QAAM,cAAc,OAAO,OAAO,CAAC,GAAG,KAAK,CAAC;AAE5C,SAAO;AAAA,IACL,UAAU,MAAM;AAAA,IAEhB,KAAK,CAAC,UAAgB;AAAA,IAEtB;AAAA,IAEA,QAAQ,CAAC,UAAkB;AAEzB,aAAO;AAAA,IACT;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,QAAQ,IAAI,IAAI;AAAA,IACzB;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,QAAQ,IAAI,IAAI;AAAA,IACzB;AAAA,IAEA,UAAU;AAAA,EAAA;AAEd;"}
+{"version":3,"file":"tool-registry.js","sources":["../../src/tool-registry.ts"],"sourcesContent":["import type { AnyTool } from './types'\n\n/**\n * A registry that holds tools and allows dynamic tool management.\n *\n * The registry can be either mutable (allowing additions/removals during execution)\n * or frozen (static tool list, for backward compatibility with tools arrays).\n */\nexport interface ToolRegistry<TTool extends AnyTool = AnyTool> {\n  /**\n   * Get all current tools in the registry.\n   * Called each agent loop iteration to get the latest tool list.\n   */\n  getTools: () => Array<TTool>\n\n  /**\n   * Add a tool to the registry dynamically.\n   * For frozen registries, this is a no-op.\n   *\n   * @param tool - The tool to add\n   */\n  add: (tool: TTool) => void\n\n  /**\n   * Remove a tool from the registry by name.\n   * For frozen registries, this always returns false.\n   *\n   * @param name - The name of the tool to remove\n   * @returns true if the tool was removed, false if not found or frozen\n   */\n  remove: (name: string) => boolean\n\n  /**\n   * Check if a tool exists in the registry.\n   *\n   * @param name - The name of the tool to check\n   */\n  has: (name: string) => boolean\n\n  /**\n   * Get a tool by name.\n   *\n   * @param name - The name of the tool to get\n   * @returns The tool if found, undefined otherwise\n   */\n  get: (name: string) => TTool | undefined\n\n  /**\n   * Whether this registry is frozen (immutable).\n   * Frozen registries don't allow add/remove operations.\n   */\n  readonly isFrozen: boolean\n}\n\n/**\n * Create a mutable tool registry for dynamic tool scenarios.\n *\n * Tools can be added and removed during chat execution, and the\n * changes will be reflected in subsequent agent loop iterations.\n *\n * @param initialTools - Optional initial set of tools\n * @returns A mutable ToolRegistry\n *\n * @example\n * ```typescript\n * const registry = createToolRegistry([toolA, toolB])\n *\n * const stream = chat({\n *   adapter,\n *   messages,\n *   toolRegistry: registry,\n * })\n *\n * // Later, during tool execution:\n * registry.add(newTool)  // Immediately available to LLM\n * ```\n */\nexport function createToolRegistry<TTool extends AnyTool = AnyTool>(\n  initialTools: Array<TTool> = [],\n): ToolRegistry<TTool> {\n  const tools = new Map<string, TTool>()\n\n  for (const tool of initialTools) {\n    tools.set(tool.name, tool)\n  }\n\n  return {\n    getTools: () => Array.from(tools.values()),\n\n    add: (tool: TTool) => {\n      tools.set(tool.name, tool)\n    },\n\n    remove: (name: string) => {\n      return tools.delete(name)\n    },\n\n    has: (name: string) => {\n      return tools.has(name)\n    },\n\n    get: (name: string) => {\n      return tools.get(name)\n    },\n\n    isFrozen: false,\n  }\n}\n\n/**\n * Create a frozen (immutable) tool registry from a tools array.\n *\n * This is used internally to wrap static `tools` arrays for backward compatibility.\n * Add and remove operations are no-ops on frozen registries.\n *\n * @param tools - The static array of tools\n * @returns A frozen ToolRegistry\n */\nexport function createFrozenRegistry<TTool extends AnyTool = AnyTool>(\n  tools: Array<TTool> = [],\n): ToolRegistry<TTool> {\n  const toolMap = new Map<string, TTool>()\n\n  for (const tool of tools) {\n    toolMap.set(tool.name, tool)\n  }\n\n  const frozenTools = Object.freeze([...tools])\n\n  return {\n    getTools: () => [...frozenTools],\n\n    add: (_tool: TTool) => {\n      // No-op for frozen registry\n    },\n\n    remove: (_name: string) => {\n      // No-op for frozen registry\n      return false\n    },\n\n    has: (name: string) => {\n      return toolMap.has(name)\n    },\n\n    get: (name: string) => {\n      return toolMap.get(name)\n    },\n\n    isFrozen: true,\n  }\n}\n"],"names":[],"mappings":"AA6EO,SAAS,mBACd,eAA6B,IACR;AACrB,QAAM,4BAAY,IAAA;AAElB,aAAW,QAAQ,cAAc;AAC/B,UAAM,IAAI,KAAK,MAAM,IAAI;AAAA,EAC3B;AAEA,SAAO;AAAA,IACL,UAAU,MAAM,MAAM,KAAK,MAAM,QAAQ;AAAA,IAEzC,KAAK,CAAC,SAAgB;AACpB,YAAM,IAAI,KAAK,MAAM,IAAI;AAAA,IAC3B;AAAA,IAEA,QAAQ,CAAC,SAAiB;AACxB,aAAO,MAAM,OAAO,IAAI;AAAA,IAC1B;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,MAAM,IAAI,IAAI;AAAA,IACvB;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,MAAM,IAAI,IAAI;AAAA,IACvB;AAAA,IAEA,UAAU;AAAA,EAAA;AAEd;AAWO,SAAS,qBACd,QAAsB,IACD;AACrB,QAAM,8BAAc,IAAA;AAEpB,aAAW,QAAQ,OAAO;AACxB,YAAQ,IAAI,KAAK,MAAM,IAAI;AAAA,EAC7B;AAEA,QAAM,cAAc,OAAO,OAAO,CAAC,GAAG,KAAK,CAAC;AAE5C,SAAO;AAAA,IACL,UAAU,MAAM,CAAC,GAAG,WAAW;AAAA,IAE/B,KAAK,CAAC,UAAiB;AAAA,IAEvB;AAAA,IAEA,QAAQ,CAAC,UAAkB;AAEzB,aAAO;AAAA,IACT;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,QAAQ,IAAI,IAAI;AAAA,IACzB;AAAA,IAEA,KAAK,CAAC,SAAiB;AACrB,aAAO,QAAQ,IAAI,IAAI;AAAA,IACzB;AAAA,IAEA,UAAU;AAAA,EAAA;AAEd;"}

package/dist/esm/types.d.ts

@@ -10,6 +10,7 @@ export type ToolCallState = 'awaiting-input' | 'input-streaming' | 'input-comple
  * Tool result states - track the lifecycle of a tool result
  */
 export type ToolResultState = 'streaming' | 'complete' | 'error';
+export type ToolOutputState = 'output-available' | 'output-error';
 /**
  * JSON Schema type for defining tool input/output schemas as raw JSON Schema objects.
  * This allows tools to be defined without schema libraries when you have JSON Schema definitions available.
@@ -255,7 +256,7 @@ export interface ToolCallPart<TMetadata = unknown> {
 export interface ToolResultPart {
     type: 'tool-result';
     toolCallId: string;
-    content: string;
+    content: string | Array<ContentPart>;
     state: ToolResultState;
     error?: string;
 }
@@ -321,11 +322,29 @@ export type InputModalitiesTypes = {
 export type ConstrainedModelMessage<TInputModalitiesTypes extends InputModalitiesTypes> = Omit<ModelMessage, 'content'> & {
     content: ConstrainedContent<TInputModalitiesTypes>;
 };
+type IsUnknown<T> = unknown extends T ? [T] extends [unknown] ? true : false : false;
+type RuntimeContextField<TContext> = IsUnknown<TContext> extends true ? {
+    /**
+     * Runtime context provided by the caller.
+     *
+     * This is request-local application state for tool and middleware
+     * implementations, not the AG-UI `Context[]` protocol field.
+     */
+    context?: TContext;
+} : {
+    /**
+     * Runtime context provided by the caller.
+     *
+     * This is request-local application state for tool and middleware
+     * implementations, not the AG-UI `Context[]` protocol field.
+     */
+    context: TContext;
+};
 /**
  * Context passed to tool execute functions, providing capabilities like
  * emitting custom events during execution.
  */
-export interface ToolExecutionContext {
+export type ToolExecutionContext<TContext = unknown> = RuntimeContextField<TContext> & {
     /** The ID of the tool call being executed */
     toolCallId?: string;
     /**
@@ -347,7 +366,8 @@ export interface ToolExecutionContext {
      * ```
      */
     emitCustomEvent: (eventName: string, value: Record<string, any>) => void;
-}
+};
+export type ToolExecuteFunction<TInput extends SchemaInput = SchemaInput, TOutput extends SchemaInput = SchemaInput, TContext = unknown> = undefined extends TContext ? (args: InferSchemaType<TInput>, context?: ToolExecutionContext<TContext>) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput> : (args: InferSchemaType<TInput>, context: ToolExecutionContext<TContext>) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>;
 /**
  * Tool/Function definition for function calling.
  *
@@ -361,7 +381,7 @@ export interface ToolExecutionContext {
  * @see https://docs.anthropic.com/claude/docs/tool-use
  * @see https://standardschema.dev/json-schema
  */
-export interface Tool<TInput extends SchemaInput = SchemaInput, TOutput extends SchemaInput = SchemaInput, TName extends string = string> {
+export interface Tool<TInput extends SchemaInput = SchemaInput, TOutput extends SchemaInput = SchemaInput, TName extends string = string, TContext = unknown> {
     /**
      * Unique name of the tool (used by the model to call it).
      *
@@ -456,7 +476,7 @@ export interface Tool<TInput extends SchemaInput = SchemaInput, TOutput extends
      *   return weather; // Can return object or string
      * }
      */
-    execute?: ((args: any, context?: ToolExecutionContext) => Promise<any> | any) | undefined;
+    execute?: ToolExecuteFunction<TInput, TOutput, TContext> | undefined;
     /** If true, tool execution requires user approval before running. Works with both server and client tools. */
     needsApproval?: boolean;
     /** If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Only meaningful when used with chat(). */
@@ -464,6 +484,9 @@ export interface Tool<TInput extends SchemaInput = SchemaInput, TOutput extends
     /** Additional metadata for adapters or custom extensions */
     metadata?: Record<string, any> | undefined;
 }
+export type AnyTool = Omit<Tool<any, any, any, any>, 'execute'> & {
+    execute?: ((args: any, context?: any) => any) | undefined;
+};
 export interface ToolConfig {
     [key: string]: Tool;
 }
@@ -580,10 +603,15 @@ export type AgentLoopStrategy = (state: AgentLoopState) => boolean;
 /**
  * Options passed into the SDK and further piped to the AI provider.
  */
-export interface TextOptions<TProviderOptionsSuperset extends Record<string, any> = Record<string, any>, TProviderOptionsForModel = TProviderOptionsSuperset> {
+export interface TextOptions<TProviderOptionsSuperset extends Record<string, any> = Record<string, any>, TProviderOptionsForModel = TProviderOptionsSuperset, TContext = unknown> {
     model: string;
     messages: Array<ModelMessage>;
-    tools?: Array<Tool<any, any, any>> | undefined;
+    tools?: Array<AnyTool> | undefined;
+    /**
+     * Runtime context provided by the caller and passed to middleware and
+     * server-side tool implementations.
+     */
+    context?: TContext;
     /**
      * System prompts to include with the request.
      *
@@ -907,7 +935,9 @@ export interface ToolCallEndEvent extends AGUIToolCallEndEvent {
     /** Final parsed input arguments (TanStack AI internal) */
     input?: unknown;
     /** Tool execution result (TanStack AI internal) */
-    result?: string;
+    result?: string | Array<ContentPart>;
+    /** Tool execution output state (TanStack AI internal) */
+    state?: ToolOutputState;
 }
 /**
  * Emitted when a tool call result is available.
@@ -918,6 +948,8 @@ export interface ToolCallEndEvent extends AGUIToolCallEndEvent {
 export interface ToolCallResultEvent extends AGUIToolCallResultEvent {
     /** Model identifier for multi-model support */
     model?: string;
+    /** Tool execution output state (TanStack AI internal) */
+    state?: ToolOutputState;
 }
 /**
  * Emitted when a thinking/reasoning step starts.

package/dist/esm/utilities/ag-ui-wire.js

@@ -41,7 +41,7 @@ function uiMessagesToWire(messages) {
           role: "tool",
           id: deriveToolMessageId(part.toolCallId),
           toolCallId: part.toolCallId,
-          content: part.content,
+          content: typeof part.content === "string" ? part.content : JSON.stringify(part.content),
           ...part.error !== void 0 && { error: part.error }
         });
       }

package/dist/esm/utilities/ag-ui-wire.js.map

@@ -1 +1 @@
-{"version":3,"file":"ag-ui-wire.js","sources":["../../../src/utilities/ag-ui-wire.ts"],"sourcesContent":["import type { ContentPart, MessagePart, UIMessage } from '../types'\n\ntype AGUITextInputContent = { type: 'text'; text: string }\ntype AGUIInputContent =\n  | AGUITextInputContent\n  | (ContentPart & { type: 'image' | 'audio' | 'video' | 'document' })\n\ntype AGUIToolCallMirror = {\n  id: string\n  type: 'function'\n  function: { name: string; arguments: string }\n}\n\ntype AGUIToolMessage = {\n  role: 'tool'\n  id: string\n  toolCallId: string\n  content: string\n  error?: string\n}\n\ntype AGUIReasoningMessage = {\n  role: 'reasoning'\n  id: string\n  content: string\n}\n\ntype WireAnchorMessage = UIMessage & {\n  content?: string | Array<AGUIInputContent>\n  toolCalls?: Array<AGUIToolCallMirror>\n}\n\nexport type WireMessage =\n  | WireAnchorMessage\n  | AGUIToolMessage\n  | AGUIReasoningMessage\n\n/**\n * Serialize TanStack `UIMessage`s into the AG-UI `RunAgentInput.messages`\n * wire shape. Each anchor (system/user/assistant) carries the canonical\n * `parts` array verbatim plus AG-UI mirror fields (`content`, `toolCalls`)\n * so AG-UI Zod parsing succeeds. Tool results and thinking parts on\n * assistant messages are additionally emitted as fan-out\n * `{role:'tool',...}` and `{role:'reasoning',...}` entries for strict\n * AG-UI server consumers.\n */\nexport function uiMessagesToWire(\n  messages: Array<UIMessage>,\n): Array<WireMessage> {\n  const wire: Array<WireMessage> = []\n\n  for (const msg of messages) {\n    // Defensive: if parts is missing (ModelMessage-shaped input), pass through as-is.\n    // UIMessage always has parts; ModelMessage uses content directly.\n    const parts: ReadonlyArray<MessagePart> =\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- runtime input may be ModelMessage-shaped (no `parts`); cast forces the optional-chain fallback below to remain in scope\n      (msg.parts as ReadonlyArray<MessagePart> | undefined) ?? []\n\n    if (msg.role === 'system') {\n      wire.push({\n        ...msg,\n        content:\n          parts.length > 0\n            ? collectText(parts)\n            : ((msg as { content?: string }).content ?? ''),\n      })\n      continue\n    }\n\n    if (msg.role === 'user') {\n      wire.push({\n        ...msg,\n        content:\n          parts.length > 0\n            ? collectUserContent(parts)\n            : ((msg as { content?: string }).content ?? ''),\n      })\n      continue\n    }\n\n    // assistant: emit reasoning fan-outs first, then anchor, then tool fan-outs\n    for (const part of parts) {\n      if (part.type === 'thinking') {\n        wire.push({\n          role: 'reasoning',\n          id: deriveReasoningId(msg.id, part),\n          content: part.content,\n        })\n      }\n    }\n\n    const text = collectText(parts)\n    const toolCalls = collectToolCalls(parts)\n    wire.push({\n      ...msg,\n      ...(text !== '' && { content: text }),\n      ...(toolCalls && { toolCalls }),\n    })\n\n    for (const part of parts) {\n      if (part.type === 'tool-result') {\n        wire.push({\n          role: 'tool',\n          id: deriveToolMessageId(part.toolCallId),\n          toolCallId: part.toolCallId,\n          content: part.content,\n          ...(part.error !== undefined && { error: part.error }),\n        })\n      }\n    }\n  }\n\n  return wire\n}\n\nfunction collectText(parts: ReadonlyArray<MessagePart>): string {\n  // The streamed JSON of a completed structured-output part is the source of\n  // truth for multi-turn coherence — emitting it back as assistant content\n  // lets the LLM see its own prior structured response. Streaming/errored\n  // parts are skipped: they'd ship malformed JSON fragments and confuse the\n  // model. `completeStructuredOutputPart` tries hard to populate `raw`\n  // (caller → existing buffer → `JSON.stringify(data)`), but the stringify\n  // fallback can leave it empty when `data` is unserializable (BigInt,\n  // circular). The `p.raw !== ''` guard below is what enforces \"no malformed\n  // round-trip\" in that case — without it we'd ship `''` and the model would\n  // see an empty assistant turn.\n  const out: Array<string> = []\n  for (const p of parts) {\n    if (p.type === 'text') {\n      out.push(p.content)\n    } else if (\n      p.type === 'structured-output' &&\n      p.status === 'complete' &&\n      p.raw !== ''\n    ) {\n      out.push(p.raw)\n    }\n  }\n  return out.join('')\n}\n\nfunction collectUserContent(\n  parts: ReadonlyArray<MessagePart>,\n): string | Array<AGUIInputContent> {\n  const hasMultimodal = parts.some(\n    (p) =>\n      p.type === 'image' ||\n      p.type === 'audio' ||\n      p.type === 'video' ||\n      p.type === 'document',\n  )\n  if (!hasMultimodal) {\n    return collectText(parts)\n  }\n  const out: Array<AGUIInputContent> = []\n  for (const p of parts) {\n    if (p.type === 'text') {\n      out.push({ type: 'text', text: p.content })\n    } else if (\n      p.type === 'image' ||\n      p.type === 'audio' ||\n      p.type === 'video' ||\n      p.type === 'document'\n    ) {\n      out.push(p)\n    }\n  }\n  return out\n}\n\nfunction collectToolCalls(\n  parts: ReadonlyArray<MessagePart>,\n): Array<AGUIToolCallMirror> | undefined {\n  const calls: Array<AGUIToolCallMirror> = []\n  for (const p of parts) {\n    if (p.type === 'tool-call') {\n      calls.push({\n        id: p.id,\n        type: 'function',\n        function: { name: p.name, arguments: p.arguments },\n      })\n    }\n  }\n  return calls.length > 0 ? calls : undefined\n}\n\nfunction deriveReasoningId(messageId: string, part: MessagePart): string {\n  return `${messageId}-reasoning-${(part as { id?: string }).id ?? hashContent((part as { content: string }).content)}`\n}\n\nfunction deriveToolMessageId(toolCallId: string): string {\n  return `tool-${toolCallId}`\n}\n\nfunction hashContent(s: string): string {\n  // Cheap deterministic id suffix; collisions are tolerable since\n  // reasoning ids only matter for AG-UI server consumers, not for our\n  // own server's dedup logic (which keys on toolCallId, not reasoning id).\n  let h = 0\n  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0\n  return Math.abs(h).toString(36)\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"ag-ui-wire.js","sources":["../../../src/utilities/ag-ui-wire.ts"],"sourcesContent":["import type { ContentPart, MessagePart, UIMessage } from '../types'\n\ntype AGUITextInputContent = { type: 'text'; text: string }\ntype AGUIInputContent =\n  | AGUITextInputContent\n  | (ContentPart & { type: 'image' | 'audio' | 'video' | 'document' })\n\ntype AGUIToolCallMirror = {\n  id: string\n  type: 'function'\n  function: { name: string; arguments: string }\n}\n\ntype AGUIToolMessage = {\n  role: 'tool'\n  id: string\n  toolCallId: string\n  content: string\n  error?: string\n}\n\ntype AGUIReasoningMessage = {\n  role: 'reasoning'\n  id: string\n  content: string\n}\n\ntype WireAnchorMessage = UIMessage & {\n  content?: string | Array<AGUIInputContent>\n  toolCalls?: Array<AGUIToolCallMirror>\n}\n\nexport type WireMessage =\n  | WireAnchorMessage\n  | AGUIToolMessage\n  | AGUIReasoningMessage\n\n/**\n * Serialize TanStack `UIMessage`s into the AG-UI `RunAgentInput.messages`\n * wire shape. Each anchor (system/user/assistant) carries the canonical\n * `parts` array verbatim plus AG-UI mirror fields (`content`, `toolCalls`)\n * so AG-UI Zod parsing succeeds. Tool results and thinking parts on\n * assistant messages are additionally emitted as fan-out\n * `{role:'tool',...}` and `{role:'reasoning',...}` entries for strict\n * AG-UI server consumers.\n */\nexport function uiMessagesToWire(\n  messages: Array<UIMessage>,\n): Array<WireMessage> {\n  const wire: Array<WireMessage> = []\n\n  for (const msg of messages) {\n    // Defensive: if parts is missing (ModelMessage-shaped input), pass through as-is.\n    // UIMessage always has parts; ModelMessage uses content directly.\n    const parts: ReadonlyArray<MessagePart> =\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- runtime input may be ModelMessage-shaped (no `parts`); cast forces the optional-chain fallback below to remain in scope\n      (msg.parts as ReadonlyArray<MessagePart> | undefined) ?? []\n\n    if (msg.role === 'system') {\n      wire.push({\n        ...msg,\n        content:\n          parts.length > 0\n            ? collectText(parts)\n            : ((msg as { content?: string }).content ?? ''),\n      })\n      continue\n    }\n\n    if (msg.role === 'user') {\n      wire.push({\n        ...msg,\n        content:\n          parts.length > 0\n            ? collectUserContent(parts)\n            : ((msg as { content?: string }).content ?? ''),\n      })\n      continue\n    }\n\n    // assistant: emit reasoning fan-outs first, then anchor, then tool fan-outs\n    for (const part of parts) {\n      if (part.type === 'thinking') {\n        wire.push({\n          role: 'reasoning',\n          id: deriveReasoningId(msg.id, part),\n          content: part.content,\n        })\n      }\n    }\n\n    const text = collectText(parts)\n    const toolCalls = collectToolCalls(parts)\n    wire.push({\n      ...msg,\n      ...(text !== '' && { content: text }),\n      ...(toolCalls && { toolCalls }),\n    })\n\n    for (const part of parts) {\n      if (part.type === 'tool-result') {\n        wire.push({\n          role: 'tool',\n          id: deriveToolMessageId(part.toolCallId),\n          toolCallId: part.toolCallId,\n          content:\n            typeof part.content === 'string'\n              ? part.content\n              : JSON.stringify(part.content),\n          ...(part.error !== undefined && { error: part.error }),\n        })\n      }\n    }\n  }\n\n  return wire\n}\n\nfunction collectText(parts: ReadonlyArray<MessagePart>): string {\n  // The streamed JSON of a completed structured-output part is the source of\n  // truth for multi-turn coherence — emitting it back as assistant content\n  // lets the LLM see its own prior structured response. Streaming/errored\n  // parts are skipped: they'd ship malformed JSON fragments and confuse the\n  // model. `completeStructuredOutputPart` tries hard to populate `raw`\n  // (caller → existing buffer → `JSON.stringify(data)`), but the stringify\n  // fallback can leave it empty when `data` is unserializable (BigInt,\n  // circular). The `p.raw !== ''` guard below is what enforces \"no malformed\n  // round-trip\" in that case — without it we'd ship `''` and the model would\n  // see an empty assistant turn.\n  const out: Array<string> = []\n  for (const p of parts) {\n    if (p.type === 'text') {\n      out.push(p.content)\n    } else if (\n      p.type === 'structured-output' &&\n      p.status === 'complete' &&\n      p.raw !== ''\n    ) {\n      out.push(p.raw)\n    }\n  }\n  return out.join('')\n}\n\nfunction collectUserContent(\n  parts: ReadonlyArray<MessagePart>,\n): string | Array<AGUIInputContent> {\n  const hasMultimodal = parts.some(\n    (p) =>\n      p.type === 'image' ||\n      p.type === 'audio' ||\n      p.type === 'video' ||\n      p.type === 'document',\n  )\n  if (!hasMultimodal) {\n    return collectText(parts)\n  }\n  const out: Array<AGUIInputContent> = []\n  for (const p of parts) {\n    if (p.type === 'text') {\n      out.push({ type: 'text', text: p.content })\n    } else if (\n      p.type === 'image' ||\n      p.type === 'audio' ||\n      p.type === 'video' ||\n      p.type === 'document'\n    ) {\n      out.push(p)\n    }\n  }\n  return out\n}\n\nfunction collectToolCalls(\n  parts: ReadonlyArray<MessagePart>,\n): Array<AGUIToolCallMirror> | undefined {\n  const calls: Array<AGUIToolCallMirror> = []\n  for (const p of parts) {\n    if (p.type === 'tool-call') {\n      calls.push({\n        id: p.id,\n        type: 'function',\n        function: { name: p.name, arguments: p.arguments },\n      })\n    }\n  }\n  return calls.length > 0 ? calls : undefined\n}\n\nfunction deriveReasoningId(messageId: string, part: MessagePart): string {\n  return `${messageId}-reasoning-${(part as { id?: string }).id ?? hashContent((part as { content: string }).content)}`\n}\n\nfunction deriveToolMessageId(toolCallId: string): string {\n  return `tool-${toolCallId}`\n}\n\nfunction hashContent(s: string): string {\n  // Cheap deterministic id suffix; collisions are tolerable since\n  // reasoning ids only matter for AG-UI server consumers, not for our\n  // own server's dedup logic (which keys on toolCallId, not reasoning id).\n  let h = 0\n  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0\n  return Math.abs(h).toString(36)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/utilities/chat-params.d.ts

@@ -1,5 +1,5 @@
 import { Context as AGUIContext } from '@ag-ui/core';
-import { JSONSchema, ModelMessage, Tool, UIMessage } from '../types.js';
+import { JSONSchema, ModelMessage, SchemaInput, Tool, UIMessage } from '../types.js';
 /**
  * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.
  *
@@ -24,7 +24,12 @@ export declare function chatParamsFromRequestBody(body: unknown): Promise<{
     }>;
     forwardedProps: Record<string, unknown>;
     state: unknown;
+    /**
+     * @deprecated Use `aguiContext` instead. This alias will be removed in a
+     * future release.
+     */
     context: Array<AGUIContext>;
+    aguiContext: Array<AGUIContext>;
 }>;
 /**
  * Read an HTTP `Request`, parse its JSON body, and validate it as an
@@ -73,8 +78,8 @@ export declare function chatParamsFromRequest(req: Request): Promise<Awaited<Ret
  *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.
  * @returns A merged array suitable for `chat({ tools })`.
  */
-export declare function mergeAgentTools(serverTools: ReadonlyArray<Tool>, clientTools: ReadonlyArray<{
+export declare function mergeAgentTools<TContext = unknown>(serverTools: ReadonlyArray<Tool<SchemaInput, SchemaInput, string, TContext>>, clientTools: ReadonlyArray<{
     name: string;
     description: string;
     parameters: JSONSchema;
-}>): Array<Tool>;
+}>): Array<Tool<SchemaInput, SchemaInput, string, TContext>>;

package/dist/esm/utilities/chat-params.js

@@ -28,6 +28,7 @@ function chatParamsFromRequestBody(body) {
     );
   }
   const parsed = parseResult.data;
+  const aguiContext = parsed.context;
   const rawMessages = body.messages ?? [];
   const messages = parsed.messages.map((m, i) => {
     const raw = rawMessages[i];
@@ -44,7 +45,8 @@ function chatParamsFromRequestBody(body) {
     tools: parsed.tools,
     forwardedProps: parsed.forwardedProps ?? {},
     state: parsed.state,
-    context: parsed.context
+    context: aguiContext,
+    aguiContext
   });
 }
 async function chatParamsFromRequest(req) {
@@ -72,7 +74,9 @@ async function chatParamsFromRequest(req) {
 }
 function mergeAgentTools(serverTools, clientTools) {
   const seen = new Set(serverTools.map((t) => t.name));
-  const merged = [...serverTools];
+  const merged = [
+    ...serverTools
+  ];
   for (const ct of clientTools) {
     if (seen.has(ct.name)) {
       continue;

package/dist/esm/utilities/chat-params.js.map

@@ -1 +1 @@
-{"version":3,"file":"chat-params.js","sources":["../../../src/utilities/chat-params.ts"],"sourcesContent":["import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'\nimport type { Context as AGUIContext } from '@ag-ui/core'\nimport type { JSONSchema, ModelMessage, Tool, UIMessage } from '../types'\n\nconst KNOWN_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n  'tool-call',\n  'tool-result',\n  'thinking',\n])\n\nfunction isValidParts(value: unknown): value is Array<{ type: string }> {\n  if (!Array.isArray(value)) return false\n  for (const p of value) {\n    if (!p || typeof p !== 'object') return false\n    const type = (p as { type?: unknown }).type\n    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false\n  }\n  return true\n}\n\n/**\n * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.\n *\n * Returns a spread-friendly object whose `messages` field is suitable for\n * passing directly to `chat({ messages })`. The existing\n * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and\n * reasoning/activity/developer-role normalization internally.\n *\n * @throws An error with a migration-pointing message when the body does\n *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a\n *   400 Bad Request to the client.\n */\nexport function chatParamsFromRequestBody(body: unknown): Promise<{\n  messages: Array<UIMessage | ModelMessage>\n  threadId: string\n  runId: string\n  parentRunId?: string\n  tools: Array<{ name: string; description: string; parameters: JSONSchema }>\n  forwardedProps: Record<string, unknown>\n  state: unknown\n  context: Array<AGUIContext>\n}> {\n  const parseResult = RunAgentInputSchema.safeParse(body)\n  if (!parseResult.success) {\n    return Promise.reject(\n      new AGUIError(\n        `Request body is not a valid AG-UI RunAgentInput. ` +\n          `If you're upgrading from a previous @tanstack/ai-client release, ` +\n          `see docs/migration/ag-ui-compliance.md. ` +\n          `Validation errors: ${parseResult.error.message}`,\n      ),\n    )\n  }\n\n  const parsed = parseResult.data\n\n  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are\n  // dropped during parse. We re-attach them from the original body so the\n  // existing UIMessage path inside `chat()` can use them directly.\n  const rawMessages =\n    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []\n  const messages = parsed.messages.map((m, i) => {\n    const raw = rawMessages[i]\n    if (\n      raw &&\n      typeof raw === 'object' &&\n      'parts' in raw &&\n      isValidParts(raw.parts)\n    ) {\n      return { ...m, parts: raw.parts } as UIMessage | ModelMessage\n    }\n    return m as ModelMessage\n  })\n\n  return Promise.resolve({\n    messages,\n    threadId: parsed.threadId,\n    runId: parsed.runId,\n    parentRunId: parsed.parentRunId,\n    tools: parsed.tools as Array<{\n      name: string\n      description: string\n      parameters: JSONSchema\n    }>,\n    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,\n    state: parsed.state,\n    context: parsed.context,\n  })\n}\n\n/**\n * Read an HTTP `Request`, parse its JSON body, and validate it as an\n * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +\n * `chatParamsFromRequestBody(...)` pair into a single call.\n *\n * On a malformed body or invalid AG-UI shape, this **throws a\n * `Response`** with status 400 and a migration-pointing message in the\n * body. Frameworks that natively handle thrown `Response` objects\n * (TanStack Start, SolidStart, Remix, React Router 7) will return the\n * 400 to the client automatically, so the handler reduces to:\n *\n * ```ts\n * export async function POST(req: Request) {\n *   const params = await chatParamsFromRequest(req)\n *   // ...use params\n * }\n * ```\n *\n * In frameworks that do not auto-handle thrown `Response` objects\n * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call\n * with try/catch and return the caught Response yourself, or use\n * `chatParamsFromRequestBody` directly with your own JSON-parsing.\n *\n * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.\n */\nexport async function chatParamsFromRequest(\n  req: Request,\n): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>> {\n  let body: unknown\n  try {\n    body = await req.json()\n  } catch (cause) {\n    // Preserve the underlying error on the thrown Response for\n    // server-side observability without leaking it to the client.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as { cause?: unknown }).cause = cause\n    throw res\n  }\n  try {\n    return await chatParamsFromRequestBody(body)\n  } catch (cause) {\n    // Generic public message — avoid echoing Zod paths (which can contain\n    // user payload fragments) or internal validator strings to the client.\n    // The original AGUIError is attached as `cause` so server logs can\n    // surface it without exposing it to remote callers.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as { cause?: unknown }).cause = cause\n    throw res\n  }\n}\n\n/**\n * Merge a server-side tool array with the AG-UI client-declared tools\n * received in the request body.\n *\n * Rules:\n * - Server tools win on name collision. The client's declaration is\n *   ignored if the server already has a tool with that name. The client's\n *   UI-side handler still fires when the streamed tool-result event comes\n *   through (see `chat-client.ts` `onToolCall`), giving the\n *   \"after server execution the client also handles\" semantic for free.\n * - Client-only tools (name not in `serverTools`) become no-execute\n *   entries: the runtime's existing `ClientToolRequest` path handles\n *   them — server emits a tool-call request, client executes via its\n *   registered handler, client posts back the result.\n *\n * @param serverTools - The server's tool array (e.g. from\n *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.\n * @param clientTools - The `tools` array received from\n *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.\n * @returns A merged array suitable for `chat({ tools })`.\n */\nexport function mergeAgentTools(\n  serverTools: ReadonlyArray<Tool>,\n  clientTools: ReadonlyArray<{\n    name: string\n    description: string\n    parameters: JSONSchema\n  }>,\n): Array<Tool> {\n  const seen = new Set(serverTools.map((t) => t.name))\n  const merged: Array<Tool> = [...serverTools]\n  for (const ct of clientTools) {\n    if (seen.has(ct.name)) {\n      // Server wins on name collision.\n      continue\n    }\n    seen.add(ct.name)\n    merged.push({\n      name: ct.name,\n      description: ct.description,\n      inputSchema: ct.parameters,\n      // No `execute` — runtime treats this as a client-side tool and\n      // emits ClientToolRequest events.\n    } as Tool)\n  }\n  return merged\n}\n"],"names":[],"mappings":";AAIA,MAAM,uCAAuB,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,aAAa,OAAkD;AACtE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO;AAClC,aAAW,KAAK,OAAO;AACrB,QAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,UAAM,OAAQ,EAAyB;AACvC,QAAI,OAAO,SAAS,YAAY,CAAC,iBAAiB,IAAI,IAAI,EAAG,QAAO;AAAA,EACtE;AACA,SAAO;AACT;AAcO,SAAS,0BAA0B,MASvC;AACD,QAAM,cAAc,oBAAoB,UAAU,IAAI;AACtD,MAAI,CAAC,YAAY,SAAS;AACxB,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,gLAGwB,YAAY,MAAM,OAAO;AAAA,MAAA;AAAA,IACnD;AAAA,EAEJ;AAEA,QAAM,SAAS,YAAY;AAK3B,QAAM,cACH,KAAuD,YAAY,CAAA;AACtE,QAAM,WAAW,OAAO,SAAS,IAAI,CAAC,GAAG,MAAM;AAC7C,UAAM,MAAM,YAAY,CAAC;AACzB,QACE,OACA,OAAO,QAAQ,YACf,WAAW,OACX,aAAa,IAAI,KAAK,GACtB;AACA,aAAO,EAAE,GAAG,GAAG,OAAO,IAAI,MAAA;AAAA,IAC5B;AACA,WAAO;AAAA,EACT,CAAC;AAED,SAAO,QAAQ,QAAQ;AAAA,IACrB;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,OAAO,OAAO;AAAA,IACd,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO;AAAA,IAKd,gBAAiB,OAAO,kBAAkB,CAAA;AAAA,IAC1C,OAAO,OAAO;AAAA,IACd,SAAS,OAAO;AAAA,EAAA,CACjB;AACH;AA2BA,eAAsB,sBACpB,KACgE;AAChE,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,IAAI,KAAA;AAAA,EACnB,SAAS,OAAO;AAGd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAA4B,QAAQ;AACtC,UAAM;AAAA,EACR;AACA,MAAI;AACF,WAAO,MAAM,0BAA0B,IAAI;AAAA,EAC7C,SAAS,OAAO;AAKd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAA4B,QAAQ;AACtC,UAAM;AAAA,EACR;AACF;AAuBO,SAAS,gBACd,aACA,aAKa;AACb,QAAM,OAAO,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AACnD,QAAM,SAAsB,CAAC,GAAG,WAAW;AAC3C,aAAW,MAAM,aAAa;AAC5B,QAAI,KAAK,IAAI,GAAG,IAAI,GAAG;AAErB;AAAA,IACF;AACA,SAAK,IAAI,GAAG,IAAI;AAChB,WAAO,KAAK;AAAA,MACV,MAAM,GAAG;AAAA,MACT,aAAa,GAAG;AAAA,MAChB,aAAa,GAAG;AAAA;AAAA;AAAA,IAAA,CAGT;AAAA,EACX;AACA,SAAO;AACT;"}
+{"version":3,"file":"chat-params.js","sources":["../../../src/utilities/chat-params.ts"],"sourcesContent":["import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'\nimport type { Context as AGUIContext } from '@ag-ui/core'\nimport type {\n  JSONSchema,\n  ModelMessage,\n  SchemaInput,\n  Tool,\n  UIMessage,\n} from '../types'\n\nconst KNOWN_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n  'tool-call',\n  'tool-result',\n  'thinking',\n])\n\nfunction isValidParts(value: unknown): value is Array<{ type: string }> {\n  if (!Array.isArray(value)) return false\n  for (const p of value) {\n    if (!p || typeof p !== 'object') return false\n    const type = (p as { type?: unknown }).type\n    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false\n  }\n  return true\n}\n\n/**\n * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.\n *\n * Returns a spread-friendly object whose `messages` field is suitable for\n * passing directly to `chat({ messages })`. The existing\n * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and\n * reasoning/activity/developer-role normalization internally.\n *\n * @throws An error with a migration-pointing message when the body does\n *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a\n *   400 Bad Request to the client.\n */\nexport function chatParamsFromRequestBody(body: unknown): Promise<{\n  messages: Array<UIMessage | ModelMessage>\n  threadId: string\n  runId: string\n  parentRunId?: string\n  tools: Array<{ name: string; description: string; parameters: JSONSchema }>\n  forwardedProps: Record<string, unknown>\n  state: unknown\n  /**\n   * @deprecated Use `aguiContext` instead. This alias will be removed in a\n   * future release.\n   */\n  context: Array<AGUIContext>\n  aguiContext: Array<AGUIContext>\n}> {\n  const parseResult = RunAgentInputSchema.safeParse(body)\n  if (!parseResult.success) {\n    return Promise.reject(\n      new AGUIError(\n        `Request body is not a valid AG-UI RunAgentInput. ` +\n          `If you're upgrading from a previous @tanstack/ai-client release, ` +\n          `see docs/migration/ag-ui-compliance.md. ` +\n          `Validation errors: ${parseResult.error.message}`,\n      ),\n    )\n  }\n\n  const parsed = parseResult.data\n  const aguiContext = parsed.context\n\n  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are\n  // dropped during parse. We re-attach them from the original body so the\n  // existing UIMessage path inside `chat()` can use them directly.\n  const rawMessages =\n    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []\n  const messages = parsed.messages.map((m, i) => {\n    const raw = rawMessages[i]\n    if (\n      raw &&\n      typeof raw === 'object' &&\n      'parts' in raw &&\n      isValidParts(raw.parts)\n    ) {\n      return { ...m, parts: raw.parts } as UIMessage | ModelMessage\n    }\n    return m as ModelMessage\n  })\n\n  return Promise.resolve({\n    messages,\n    threadId: parsed.threadId,\n    runId: parsed.runId,\n    parentRunId: parsed.parentRunId,\n    tools: parsed.tools as Array<{\n      name: string\n      description: string\n      parameters: JSONSchema\n    }>,\n    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,\n    state: parsed.state,\n    context: aguiContext,\n    aguiContext,\n  })\n}\n\n/**\n * Read an HTTP `Request`, parse its JSON body, and validate it as an\n * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +\n * `chatParamsFromRequestBody(...)` pair into a single call.\n *\n * On a malformed body or invalid AG-UI shape, this **throws a\n * `Response`** with status 400 and a migration-pointing message in the\n * body. Frameworks that natively handle thrown `Response` objects\n * (TanStack Start, SolidStart, Remix, React Router 7) will return the\n * 400 to the client automatically, so the handler reduces to:\n *\n * ```ts\n * export async function POST(req: Request) {\n *   const params = await chatParamsFromRequest(req)\n *   // ...use params\n * }\n * ```\n *\n * In frameworks that do not auto-handle thrown `Response` objects\n * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call\n * with try/catch and return the caught Response yourself, or use\n * `chatParamsFromRequestBody` directly with your own JSON-parsing.\n *\n * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.\n */\nexport async function chatParamsFromRequest(\n  req: Request,\n): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>> {\n  let body: unknown\n  try {\n    body = await req.json()\n  } catch (cause) {\n    // Preserve the underlying error on the thrown Response for\n    // server-side observability without leaking it to the client.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as { cause?: unknown }).cause = cause\n    throw res\n  }\n  try {\n    return await chatParamsFromRequestBody(body)\n  } catch (cause) {\n    // Generic public message — avoid echoing Zod paths (which can contain\n    // user payload fragments) or internal validator strings to the client.\n    // The original AGUIError is attached as `cause` so server logs can\n    // surface it without exposing it to remote callers.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as { cause?: unknown }).cause = cause\n    throw res\n  }\n}\n\n/**\n * Merge a server-side tool array with the AG-UI client-declared tools\n * received in the request body.\n *\n * Rules:\n * - Server tools win on name collision. The client's declaration is\n *   ignored if the server already has a tool with that name. The client's\n *   UI-side handler still fires when the streamed tool-result event comes\n *   through (see `chat-client.ts` `onToolCall`), giving the\n *   \"after server execution the client also handles\" semantic for free.\n * - Client-only tools (name not in `serverTools`) become no-execute\n *   entries: the runtime's existing `ClientToolRequest` path handles\n *   them — server emits a tool-call request, client executes via its\n *   registered handler, client posts back the result.\n *\n * @param serverTools - The server's tool array (e.g. from\n *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.\n * @param clientTools - The `tools` array received from\n *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.\n * @returns A merged array suitable for `chat({ tools })`.\n */\nexport function mergeAgentTools<TContext = unknown>(\n  serverTools: ReadonlyArray<Tool<SchemaInput, SchemaInput, string, TContext>>,\n  clientTools: ReadonlyArray<{\n    name: string\n    description: string\n    parameters: JSONSchema\n  }>,\n): Array<Tool<SchemaInput, SchemaInput, string, TContext>> {\n  const seen = new Set(serverTools.map((t) => t.name))\n  const merged: Array<Tool<SchemaInput, SchemaInput, string, TContext>> = [\n    ...serverTools,\n  ]\n  for (const ct of clientTools) {\n    if (seen.has(ct.name)) {\n      // Server wins on name collision.\n      continue\n    }\n    seen.add(ct.name)\n    merged.push({\n      name: ct.name,\n      description: ct.description,\n      inputSchema: ct.parameters,\n      // No `execute` — runtime treats this as a client-side tool and\n      // emits ClientToolRequest events.\n    } as Tool<SchemaInput, SchemaInput, string, TContext>)\n  }\n  return merged\n}\n"],"names":[],"mappings":";AAUA,MAAM,uCAAuB,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,aAAa,OAAkD;AACtE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO;AAClC,aAAW,KAAK,OAAO;AACrB,QAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,UAAM,OAAQ,EAAyB;AACvC,QAAI,OAAO,SAAS,YAAY,CAAC,iBAAiB,IAAI,IAAI,EAAG,QAAO;AAAA,EACtE;AACA,SAAO;AACT;AAcO,SAAS,0BAA0B,MAcvC;AACD,QAAM,cAAc,oBAAoB,UAAU,IAAI;AACtD,MAAI,CAAC,YAAY,SAAS;AACxB,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,gLAGwB,YAAY,MAAM,OAAO;AAAA,MAAA;AAAA,IACnD;AAAA,EAEJ;AAEA,QAAM,SAAS,YAAY;AAC3B,QAAM,cAAc,OAAO;AAK3B,QAAM,cACH,KAAuD,YAAY,CAAA;AACtE,QAAM,WAAW,OAAO,SAAS,IAAI,CAAC,GAAG,MAAM;AAC7C,UAAM,MAAM,YAAY,CAAC;AACzB,QACE,OACA,OAAO,QAAQ,YACf,WAAW,OACX,aAAa,IAAI,KAAK,GACtB;AACA,aAAO,EAAE,GAAG,GAAG,OAAO,IAAI,MAAA;AAAA,IAC5B;AACA,WAAO;AAAA,EACT,CAAC;AAED,SAAO,QAAQ,QAAQ;AAAA,IACrB;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,OAAO,OAAO;AAAA,IACd,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO;AAAA,IAKd,gBAAiB,OAAO,kBAAkB,CAAA;AAAA,IAC1C,OAAO,OAAO;AAAA,IACd,SAAS;AAAA,IACT;AAAA,EAAA,CACD;AACH;AA2BA,eAAsB,sBACpB,KACgE;AAChE,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,IAAI,KAAA;AAAA,EACnB,SAAS,OAAO;AAGd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAA4B,QAAQ;AACtC,UAAM;AAAA,EACR;AACA,MAAI;AACF,WAAO,MAAM,0BAA0B,IAAI;AAAA,EAC7C,SAAS,OAAO;AAKd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAA4B,QAAQ;AACtC,UAAM;AAAA,EACR;AACF;AAuBO,SAAS,gBACd,aACA,aAKyD;AACzD,QAAM,OAAO,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AACnD,QAAM,SAAkE;AAAA,IACtE,GAAG;AAAA,EAAA;AAEL,aAAW,MAAM,aAAa;AAC5B,QAAI,KAAK,IAAI,GAAG,IAAI,GAAG;AAErB;AAAA,IACF;AACA,SAAK,IAAI,GAAG,IAAI;AAChB,WAAO,KAAK;AAAA,MACV,MAAM,GAAG;AAAA,MACT,aAAa,GAAG;AAAA,MAChB,aAAa,GAAG;AAAA;AAAA;AAAA,IAAA,CAGmC;AAAA,EACvD;AACA,SAAO;AACT;"}

package/dist/esm/utilities/tool-result.d.ts

@@ -0,0 +1,21 @@
+import { ContentPart } from '../types.js';
+/**
+ * Structural check for a single `ContentPart`. A text part must carry a string
+ * `content`; every other modality must carry a `source` with `type` of
+ * `'url' | 'data'` and a string `value`.
+ */
+export declare function isContentPart(value: unknown): value is ContentPart;
+/**
+ * True iff `value` is a NON-EMPTY array whose every element is a valid
+ * `ContentPart`. Empty arrays and mixed arrays return false so they continue
+ * to be treated as ordinary (stringified) data — this keeps the auto-detection
+ * footgun narrow.
+ */
+export declare function isContentPartArray(value: unknown): value is Array<ContentPart>;
+/**
+ * Normalize a tool's return value for transport:
+ * - string            → unchanged
+ * - ContentPart array → unchanged (multimodal, passed through to the adapter)
+ * - anything else     → `JSON.stringify`
+ */
+export declare function normalizeToolResult(result: unknown): string | Array<ContentPart>;

package/dist/esm/utilities/tool-result.js

@@ -0,0 +1,37 @@
+const CONTENT_PART_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "image",
+  "audio",
+  "video",
+  "document"
+]);
+function isContentPart(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const part = value;
+  if (typeof part.type !== "string" || !CONTENT_PART_TYPES.has(part.type)) {
+    return false;
+  }
+  if (part.type === "text") {
+    return typeof part.content === "string";
+  }
+  const source = part.source;
+  if (typeof source !== "object" || source === null) return false;
+  const src = source;
+  if (typeof src.value !== "string") return false;
+  if (src.type === "data") return typeof src.mimeType === "string";
+  return src.type === "url";
+}
+function isContentPartArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isContentPart);
+}
+function normalizeToolResult(result) {
+  if (typeof result === "string") return result;
+  if (isContentPartArray(result)) return result;
+  return JSON.stringify(result);
+}
+export {
+  isContentPart,
+  isContentPartArray,
+  normalizeToolResult
+};
+//# sourceMappingURL=tool-result.js.map

package/dist/esm/utilities/tool-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.js","sources":["../../../src/utilities/tool-result.ts"],"sourcesContent":["import type { ContentPart } from '../types'\n\nconst CONTENT_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n])\n\n/**\n * Structural check for a single `ContentPart`. A text part must carry a string\n * `content`; every other modality must carry a `source` with `type` of\n * `'url' | 'data'` and a string `value`.\n */\nexport function isContentPart(value: unknown): value is ContentPart {\n  if (typeof value !== 'object' || value === null) return false\n  const part = value as Record<string, unknown>\n  if (typeof part.type !== 'string' || !CONTENT_PART_TYPES.has(part.type)) {\n    return false\n  }\n  if (part.type === 'text') {\n    return typeof part.content === 'string'\n  }\n  const source = part.source\n  if (typeof source !== 'object' || source === null) return false\n  const src = source as Record<string, unknown>\n  if (typeof src.value !== 'string') return false\n  // `data` sources require a mimeType (matches ContentPartDataSource); `url`\n  // sources don't. Requiring it here keeps the runtime guard consistent with\n  // the type and avoids emitting `data:undefined;base64,...` downstream.\n  if (src.type === 'data') return typeof src.mimeType === 'string'\n  return src.type === 'url'\n}\n\n/**\n * True iff `value` is a NON-EMPTY array whose every element is a valid\n * `ContentPart`. Empty arrays and mixed arrays return false so they continue\n * to be treated as ordinary (stringified) data — this keeps the auto-detection\n * footgun narrow.\n */\nexport function isContentPartArray(\n  value: unknown,\n): value is Array<ContentPart> {\n  return Array.isArray(value) && value.length > 0 && value.every(isContentPart)\n}\n\n/**\n * Normalize a tool's return value for transport:\n * - string            → unchanged\n * - ContentPart array → unchanged (multimodal, passed through to the adapter)\n * - anything else     → `JSON.stringify`\n */\nexport function normalizeToolResult(\n  result: unknown,\n): string | Array<ContentPart> {\n  if (typeof result === 'string') return result\n  if (isContentPartArray(result)) return result\n  return JSON.stringify(result)\n}\n"],"names":[],"mappings":"AAEA,MAAM,yCAAyB,IAAI;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAOM,SAAS,cAAc,OAAsC;AAClE,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAO;AACb,MAAI,OAAO,KAAK,SAAS,YAAY,CAAC,mBAAmB,IAAI,KAAK,IAAI,GAAG;AACvE,WAAO;AAAA,EACT;AACA,MAAI,KAAK,SAAS,QAAQ;AACxB,WAAO,OAAO,KAAK,YAAY;AAAA,EACjC;AACA,QAAM,SAAS,KAAK;AACpB,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO;AAC1D,QAAM,MAAM;AACZ,MAAI,OAAO,IAAI,UAAU,SAAU,QAAO;AAI1C,MAAI,IAAI,SAAS,OAAQ,QAAO,OAAO,IAAI,aAAa;AACxD,SAAO,IAAI,SAAS;AACtB;AAQO,SAAS,mBACd,OAC6B;AAC7B,SAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,aAAa;AAC9E;AAQO,SAAS,oBACd,QAC6B;AAC7B,MAAI,OAAO,WAAW,SAAU,QAAO;AACvC,MAAI,mBAAmB,MAAM,EAAG,QAAO;AACvC,SAAO,KAAK,UAAU,MAAM;AAC9B;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.4.2"
+    "@tanstack/ai-event-client": "0.4.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"