@tanstack/ai 0.23.1 → 0.24.0

package/src/activities/chat/tools/tool-definition.ts

@@ -1,10 +1,9 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
 import type {
-  InferSchemaType,
   JSONSchema,
   SchemaInput,
   Tool,
-  ToolExecutionContext,
+  ToolExecuteFunction,
 } from '../../../types'
 
 /**
@@ -14,7 +13,8 @@ export interface ServerTool<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
-> extends Tool<TInput, TOutput, TName> {
+  TContext = unknown,
+> extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'server'
 }
 
@@ -25,6 +25,7 @@ export interface ClientTool<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
+  TContext = unknown,
 > {
   __toolSide: 'client'
   name: TName
@@ -39,9 +40,7 @@ export interface ClientTool<
   needsApproval?: boolean
   lazy?: boolean
   metadata?: Record<string, unknown>
-  execute?: (
-    args: InferSchemaType<TInput>,
-  ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>
+  execute?: ToolExecuteFunction<TInput, TOutput, TContext>
 }
 
 /**
@@ -51,7 +50,8 @@ export interface ToolDefinitionInstance<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
-> extends Tool<TInput, TOutput, TName> {
+  TContext = unknown,
+> extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'definition'
 }
 
@@ -59,8 +59,12 @@ export interface ToolDefinitionInstance<
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | ClientTool<SchemaInput, SchemaInput>
-  | ToolDefinitionInstance<SchemaInput, SchemaInput>
+  | (Omit<ClientTool<any, any, string, any>, 'execute'> & {
+      execute?: ((args: any, context?: any) => any) | undefined
+    })
+  | (Omit<ToolDefinitionInstance<any, any, string, any>, 'execute'> & {
+      execute?: ((args: any, context?: any) => any) | undefined
+    })
 
 /**
  * Extract the tool name as a literal type
@@ -117,21 +121,16 @@ export interface ToolDefinition<
   /**
    * Create a server-side tool with execute function
    */
-  server: (
-    execute: (
-      args: InferSchemaType<TInput>,
-      context?: ToolExecutionContext,
-    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-  ) => ServerTool<TInput, TOutput, TName>
+  server: <TContext = unknown>(
+    execute: ToolExecuteFunction<TInput, TOutput, TContext>,
+  ) => ServerTool<TInput, TOutput, TName, TContext>
 
   /**
    * Create a client-side tool with optional execute function
    */
-  client: (
-    execute?: (
-      args: InferSchemaType<TInput>,
-    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-  ) => ClientTool<TInput, TOutput, TName>
+  client: <TContext = unknown>(
+    execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
+  ) => ClientTool<TInput, TOutput, TName, TContext>
 }
 
 /**
@@ -199,12 +198,9 @@ export function toolDefinition<
   const definition: ToolDefinition<TInput, TOutput, TName> = {
     __toolSide: 'definition',
     ...config,
-    server(
-      execute: (
-        args: InferSchemaType<TInput>,
-        context?: ToolExecutionContext,
-      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-    ): ServerTool<TInput, TOutput, TName> {
+    server<TContext = unknown>(
+      execute: ToolExecuteFunction<TInput, TOutput, TContext>,
+    ): ServerTool<TInput, TOutput, TName, TContext> {
       return {
         __toolSide: 'server',
         ...config,
@@ -212,11 +208,9 @@ export function toolDefinition<
       }
     },
 
-    client(
-      execute?: (
-        args: InferSchemaType<TInput>,
-      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-    ): ClientTool<TInput, TOutput, TName> {
+    client<TContext = unknown>(
+      execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
+    ): ClientTool<TInput, TOutput, TName, TContext> {
       return {
         __toolSide: 'client',
         ...config,

package/src/activities/error-payload.ts

@@ -62,3 +62,47 @@ export function toRunErrorPayload(
   }
   return { message: fallbackMessage, code: undefined }
 }
+
+/**
+ * Extract the provider's *structured error body* from a thrown value, to attach
+ * as the AG-UI `rawEvent` on a RUN_ERROR event. This is the recoverable upstream
+ * detail (provider name, the upstream model's error JSON, rate-limit/overload
+ * codes, etc.) that `toRunErrorPayload`'s `{ message, code }` deliberately drops.
+ *
+ * Security boundary: only known provider-response-body fields are forwarded —
+ * never the raw SDK exception object, which can carry request metadata such as
+ * auth headers or request ids. The recognized sources, in priority order:
+ *
+ *  - `error.rawEvent` — a provider body an adapter attached explicitly (e.g. the
+ *    OpenRouter mid-stream `chunk.error`).
+ *  - `error.error` (object) — the parsed provider response body exposed by SDK
+ *    `APIError` instances (OpenAI/Anthropic `{ type, message, code, param }`,
+ *    OpenRouter typed errors whose `.error` carries `.metadata`). This is
+ *    provider-shaped data, distinct from `.headers` / `.request_id`.
+ *  - `error.metadata` — OpenRouter's `provider_name` + raw upstream body, when
+ *    surfaced directly on the thrown error.
+ *
+ * Returns `undefined` when no structured provider body is present, so callers
+ * omit the field entirely rather than setting it to `null`:
+ *
+ *   const rawEvent = toRunErrorRawEvent(error)
+ *   yield { type: EventType.RUN_ERROR, ..., ...(rawEvent !== undefined && { rawEvent }) }
+ */
+export function toRunErrorRawEvent(error: unknown): unknown {
+  if (!error || typeof error !== 'object') return undefined
+  const e = error as {
+    rawEvent?: unknown
+    error?: unknown
+    metadata?: unknown
+  }
+  if (e.rawEvent !== undefined && e.rawEvent !== null) return e.rawEvent
+  if (
+    e.error !== undefined &&
+    e.error !== null &&
+    typeof e.error === 'object'
+  ) {
+    return e.error
+  }
+  if (e.metadata !== undefined && e.metadata !== null) return e.metadata
+  return undefined
+}

package/src/adapter-internals.ts

@@ -6,4 +6,7 @@ export type { ResolvedCategories } from './logger/internal-logger'
 export { InternalLogger } from './logger/internal-logger'
 export type { Logger } from './logger/types'
 export { resolveDebugOption } from './logger/resolve'
-export { toRunErrorPayload } from './activities/error-payload'
+export {
+  toRunErrorPayload,
+  toRunErrorRawEvent,
+} from './activities/error-payload'

package/src/client.ts

@@ -46,7 +46,11 @@ export {
   type ToolDefinitionInstance,
 } from './activities/chat/tools/tool-definition'
 
-export { convertSchemaToJsonSchema } from './activities/chat/tools/schema-converter'
+export {
+  convertSchemaToJsonSchema,
+  isStandardSchema,
+  parseWithStandardSchema,
+} from './activities/chat/tools/schema-converter'
 
 export {
   convertMessagesToModelMessages,

package/src/index.ts

@@ -55,6 +55,8 @@ export {
 // Schema conversion (Standard JSON Schema compliant)
 export {
   convertSchemaToJsonSchema,
+  isStandardSchema,
+  parseWithStandardSchema,
   StandardSchemaValidationError,
 } from './activities/chat/tools/schema-converter'
 
@@ -187,6 +189,11 @@ export {
 // AG-UI wire serialization (used internally by @tanstack/ai-client)
 export { uiMessagesToWire } from './utilities/ag-ui-wire'
 export type { WireMessage } from './utilities/ag-ui-wire'
+export {
+  isContentPart,
+  isContentPartArray,
+  normalizeToolResult,
+} from './utilities/tool-result'
 
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'

package/src/tool-registry.ts

@@ -1,4 +1,4 @@
-import type { Tool } from './types'
+import type { AnyTool } from './types'
 
 /**
  * A registry that holds tools and allows dynamic tool management.
@@ -6,12 +6,12 @@ import type { Tool } from './types'
  * 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.
@@ -19,7 +19,7 @@ export interface ToolRegistry {
    *
    * @param tool - The tool to add
    */
-  add: (tool: Tool) => void
+  add: (tool: TTool) => void
 
   /**
    * Remove a tool from the registry by name.
@@ -43,7 +43,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).
@@ -75,10 +75,10 @@ export interface ToolRegistry {
  * registry.add(newTool)  // Immediately available to LLM
  * ```
  */
-export function createToolRegistry(
-  initialTools: Array<Tool> = [],
-): ToolRegistry {
-  const tools = new Map<string, Tool>()
+export function createToolRegistry<TTool extends AnyTool = AnyTool>(
+  initialTools: Array<TTool> = [],
+): ToolRegistry<TTool> {
+  const tools = new Map<string, TTool>()
 
   for (const tool of initialTools) {
     tools.set(tool.name, tool)
@@ -87,7 +87,7 @@ export function createToolRegistry(
   return {
     getTools: () => Array.from(tools.values()),
 
-    add: (tool: Tool) => {
+    add: (tool: TTool) => {
       tools.set(tool.name, tool)
     },
 
@@ -116,8 +116,10 @@ export function createToolRegistry(
  * @param tools - The static array of tools
  * @returns A frozen ToolRegistry
  */
-export function createFrozenRegistry(tools: Array<Tool> = []): ToolRegistry {
-  const toolMap = new Map<string, Tool>()
+export function createFrozenRegistry<TTool extends AnyTool = AnyTool>(
+  tools: Array<TTool> = [],
+): ToolRegistry<TTool> {
+  const toolMap = new Map<string, TTool>()
 
   for (const tool of tools) {
     toolMap.set(tool.name, tool)
@@ -126,9 +128,9 @@ export function createFrozenRegistry(tools: Array<Tool> = []): ToolRegistry {
   const frozenTools = Object.freeze([...tools])
 
   return {
-    getTools: () => frozenTools,
+    getTools: () => [...frozenTools],
 
-    add: (_tool: Tool) => {
+    add: (_tool: TTool) => {
       // No-op for frozen registry
     },
 

package/src/types.ts

@@ -50,6 +50,8 @@ export type ToolResultState =
   | 'complete' // Result is complete
   | 'error' // Error occurred
 
+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.
@@ -355,7 +357,7 @@ export interface ToolCallPart<TMetadata = unknown> {
 export interface ToolResultPart {
   type: 'tool-result'
   toolCallId: string
-  content: string
+  content: string | Array<ContentPart>
   state: ToolResultState
   error?: string // Error message if state is "error"
 }
@@ -443,33 +445,75 @@ export type ConstrainedModelMessage<
   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 {
-  /** The ID of the tool call being executed */
-  toolCallId?: string
-  /**
-   * Emit a custom event during tool execution.
-   * Events are streamed to the client in real-time as AG-UI CUSTOM events.
-   *
-   * @param eventName - Name of the custom event
-   * @param value - Event payload value
-   *
-   * @example
-   * ```ts
-   * const tool = toolDefinition({ ... }).server(async (args, context) => {
-   *   context?.emitCustomEvent('progress', { step: 1, total: 3 })
-   *   // ... do work ...
-   *   context?.emitCustomEvent('progress', { step: 2, total: 3 })
-   *   // ... do more work ...
-   *   return result
-   * })
-   * ```
-   */
-  emitCustomEvent: (eventName: string, value: Record<string, any>) => void
-}
+export type ToolExecutionContext<TContext = unknown> =
+  RuntimeContextField<TContext> & {
+    /** The ID of the tool call being executed */
+    toolCallId?: string
+    /**
+     * Emit a custom event during tool execution.
+     * Events are streamed to the client in real-time as AG-UI CUSTOM events.
+     *
+     * @param eventName - Name of the custom event
+     * @param value - Event payload value
+     *
+     * @example
+     * ```ts
+     * const tool = toolDefinition({ ... }).server(async (args, context) => {
+     *   context?.emitCustomEvent('progress', { step: 1, total: 3 })
+     *   // ... do work ...
+     *   context?.emitCustomEvent('progress', { step: 2, total: 3 })
+     *   // ... do more work ...
+     *   return result
+     * })
+     * ```
+     */
+    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.
@@ -488,6 +532,7 @@ 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).
@@ -587,9 +632,7 @@ export interface Tool<
    *   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
@@ -601,6 +644,10 @@ export interface Tool<
   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
 }
@@ -729,10 +776,16 @@ export type AgentLoopStrategy = (state: AgentLoopState) => boolean
 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.
    *
@@ -1084,7 +1137,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
 }
 
 /**
@@ -1096,6 +1151,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
 }
 
 /**

package/src/utilities/ag-ui-wire.ts

@@ -103,7 +103,10 @@ export function uiMessagesToWire(
           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 !== undefined && { error: part.error }),
         })
       }

package/src/utilities/chat-params.ts

@@ -1,6 +1,12 @@
 import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'
 import type { Context as AGUIContext } from '@ag-ui/core'
-import type { JSONSchema, ModelMessage, Tool, UIMessage } from '../types'
+import type {
+  JSONSchema,
+  ModelMessage,
+  SchemaInput,
+  Tool,
+  UIMessage,
+} from '../types'
 
 const KNOWN_PART_TYPES = new Set([
   'text',
@@ -43,7 +49,12 @@ export function chatParamsFromRequestBody(body: unknown): Promise<{
   tools: Array<{ name: string; description: string; parameters: JSONSchema }>
   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>
 }> {
   const parseResult = RunAgentInputSchema.safeParse(body)
   if (!parseResult.success) {
@@ -58,6 +69,7 @@ export function chatParamsFromRequestBody(body: unknown): Promise<{
   }
 
   const parsed = parseResult.data
+  const aguiContext = parsed.context
 
   // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are
   // dropped during parse. We re-attach them from the original body so the
@@ -89,7 +101,8 @@ export function chatParamsFromRequestBody(body: unknown): Promise<{
     }>,
     forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,
     state: parsed.state,
-    context: parsed.context,
+    context: aguiContext,
+    aguiContext,
   })
 }
 
@@ -171,16 +184,18 @@ export async function chatParamsFromRequest(
  *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.
  * @returns A merged array suitable for `chat({ tools })`.
  */
-export function mergeAgentTools(
-  serverTools: ReadonlyArray<Tool>,
+export 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>> {
   const seen = new Set(serverTools.map((t) => t.name))
-  const merged: Array<Tool> = [...serverTools]
+  const merged: Array<Tool<SchemaInput, SchemaInput, string, TContext>> = [
+    ...serverTools,
+  ]
   for (const ct of clientTools) {
     if (seen.has(ct.name)) {
       // Server wins on name collision.
@@ -193,7 +208,7 @@ export function mergeAgentTools(
       inputSchema: ct.parameters,
       // No `execute` — runtime treats this as a client-side tool and
       // emits ClientToolRequest events.
-    } as Tool)
+    } as Tool<SchemaInput, SchemaInput, string, TContext>)
   }
   return merged
 }

package/src/utilities/tool-result.ts

@@ -0,0 +1,60 @@
+import type { ContentPart } from '../types'
+
+const CONTENT_PART_TYPES = new Set([
+  'text',
+  'image',
+  'audio',
+  'video',
+  'document',
+])
+
+/**
+ * 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 function isContentPart(value: unknown): value is ContentPart {
+  if (typeof value !== 'object' || value === null) return false
+  const part = value as Record<string, unknown>
+  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 as Record<string, unknown>
+  if (typeof src.value !== 'string') return false
+  // `data` sources require a mimeType (matches ContentPartDataSource); `url`
+  // sources don't. Requiring it here keeps the runtime guard consistent with
+  // the type and avoids emitting `data:undefined;base64,...` downstream.
+  if (src.type === 'data') return typeof src.mimeType === 'string'
+  return src.type === 'url'
+}
+
+/**
+ * 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 function isContentPartArray(
+  value: unknown,
+): value is Array<ContentPart> {
+  return Array.isArray(value) && value.length > 0 && value.every(isContentPart)
+}
+
+/**
+ * Normalize a tool's return value for transport:
+ * - string            → unchanged
+ * - ContentPart array → unchanged (multimodal, passed through to the adapter)
+ * - anything else     → `JSON.stringify`
+ */
+export function normalizeToolResult(
+  result: unknown,
+): string | Array<ContentPart> {
+  if (typeof result === 'string') return result
+  if (isContentPartArray(result)) return result
+  return JSON.stringify(result)
+}