@tanstack/ai 0.1.0 → 0.2.1

package/src/activities/chat/tools/schema-converter.ts

@@ -0,0 +1,332 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
+import type { JSONSchema, SchemaInput } from '../../../types'
+
+/**
+ * Check if a value is a Standard JSON Schema compliant schema.
+ * Standard JSON Schema compliant libraries (Zod v4+, ArkType, Valibot with toStandardJsonSchema, etc.)
+ * implement the '~standard' property with jsonSchema converter methods.
+ */
+export function isStandardJSONSchema(
+  schema: unknown,
+): schema is StandardJSONSchemaV1 {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    '~standard' in schema &&
+    typeof (schema as StandardJSONSchemaV1)['~standard'] === 'object' &&
+    (schema as StandardJSONSchemaV1)['~standard'].version === 1 &&
+    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema ===
+      'object' &&
+    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema.input ===
+      'function'
+  )
+}
+
+/**
+ * Check if a value is a Standard Schema compliant schema (for validation).
+ * Standard Schema compliant libraries implement the '~standard' property with a validate function.
+ */
+export function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    '~standard' in schema &&
+    typeof schema['~standard'] === 'object' &&
+    schema !== null &&
+    schema['~standard'] !== null &&
+    'version' in schema['~standard'] &&
+    schema['~standard'].version === 1 &&
+    'validate' in schema['~standard'] &&
+    typeof schema['~standard'].validate === 'function'
+  )
+}
+
+/**
+ * Transform a JSON schema to be compatible with OpenAI's structured output requirements.
+ * OpenAI requires:
+ * - All properties must be in the `required` array
+ * - Optional fields should have null added to their type union
+ * - additionalProperties must be false for objects
+ *
+ * @param schema - JSON schema to transform
+ * @param originalRequired - Original required array (to know which fields were optional)
+ * @returns Transformed schema compatible with OpenAI structured output
+ */
+function makeStructuredOutputCompatible(
+  schema: Record<string, any>,
+  originalRequired: Array<string> = [],
+): Record<string, any> {
+  const result = { ...schema }
+
+  // Handle object types
+  if (result.type === 'object' && result.properties) {
+    const properties = { ...result.properties }
+    const allPropertyNames = Object.keys(properties)
+
+    // Transform each property
+    for (const propName of allPropertyNames) {
+      const prop = properties[propName]
+      const wasOptional = !originalRequired.includes(propName)
+
+      // Recursively transform nested objects/arrays
+      if (prop.type === 'object' && prop.properties) {
+        properties[propName] = makeStructuredOutputCompatible(
+          prop,
+          prop.required || [],
+        )
+      } else if (prop.type === 'array' && prop.items) {
+        properties[propName] = {
+          ...prop,
+          items: makeStructuredOutputCompatible(
+            prop.items,
+            prop.items.required || [],
+          ),
+        }
+      } else if (wasOptional) {
+        // Make optional fields nullable by adding null to the type
+        if (prop.type && !Array.isArray(prop.type)) {
+          properties[propName] = {
+            ...prop,
+            type: [prop.type, 'null'],
+          }
+        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {
+          properties[propName] = {
+            ...prop,
+            type: [...prop.type, 'null'],
+          }
+        }
+      }
+    }
+
+    result.properties = properties
+    // ALL properties must be required for OpenAI structured output
+    result.required = allPropertyNames
+    // additionalProperties must be false
+    result.additionalProperties = false
+  }
+
+  // Handle array types with object items
+  if (result.type === 'array' && result.items) {
+    result.items = makeStructuredOutputCompatible(
+      result.items,
+      result.items.required || [],
+    )
+  }
+
+  return result
+}
+
+/**
+ * Options for schema conversion
+ */
+export interface ConvertSchemaOptions {
+  /**
+   * When true, transforms the schema to be compatible with OpenAI's structured output requirements:
+   * - All properties are added to the `required` array
+   * - Optional fields get null added to their type union
+   * - additionalProperties is set to false for all objects
+   *
+   * @default false
+   */
+  forStructuredOutput?: boolean
+}
+
+/**
+ * Converts a Standard JSON Schema compliant schema or plain JSONSchema to JSON Schema format
+ * compatible with LLM providers.
+ *
+ * Supports any schema library that implements the Standard JSON Schema spec (v1):
+ * - Zod v4+ (natively supports StandardJSONSchemaV1)
+ * - ArkType (natively supports StandardJSONSchemaV1)
+ * - Valibot (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)
+ *
+ * If the input is already a plain JSONSchema object, it is returned as-is.
+ *
+ * @param schema - Standard JSON Schema compliant schema or plain JSONSchema object to convert
+ * @param options - Conversion options
+ * @returns JSON Schema object that can be sent to LLM providers
+ *
+ * @example
+ * ```typescript
+ * // Using Zod v4+ (natively supports Standard JSON Schema)
+ * import * as z from 'zod';
+ *
+ * const zodSchema = z.object({
+ *   location: z.string().describe('City name'),
+ *   unit: z.enum(['celsius', 'fahrenheit']).optional()
+ * });
+ *
+ * const jsonSchema = convertSchemaToJsonSchema(zodSchema);
+ *
+ * @example
+ * // Using ArkType (natively supports Standard JSON Schema)
+ * import { type } from 'arktype';
+ *
+ * const arkSchema = type({
+ *   location: 'string',
+ *   unit: "'celsius' | 'fahrenheit'"
+ * });
+ *
+ * const jsonSchema = convertSchemaToJsonSchema(arkSchema);
+ *
+ * @example
+ * // Using Valibot (via toStandardJsonSchema)
+ * import * as v from 'valibot';
+ * import { toStandardJsonSchema } from '@valibot/to-json-schema';
+ *
+ * const valibotSchema = toStandardJsonSchema(v.object({
+ *   location: v.string(),
+ *   unit: v.optional(v.picklist(['celsius', 'fahrenheit']))
+ * }));
+ *
+ * const jsonSchema = convertSchemaToJsonSchema(valibotSchema);
+ *
+ * @example
+ * // Using JSONSchema directly (passes through unchanged)
+ * const rawSchema = {
+ *   type: 'object',
+ *   properties: { location: { type: 'string' } },
+ *   required: ['location']
+ * };
+ * const result = convertSchemaToJsonSchema(rawSchema);
+ * ```
+ */
+export function convertSchemaToJsonSchema(
+  schema: SchemaInput | undefined,
+  options: ConvertSchemaOptions = {},
+): JSONSchema | undefined {
+  if (!schema) return undefined
+
+  const { forStructuredOutput = false } = options
+
+  // If it's a Standard JSON Schema compliant schema, use the standard interface
+  if (isStandardJSONSchema(schema)) {
+    const jsonSchema = schema['~standard'].jsonSchema.input({
+      target: 'draft-07',
+    })
+
+    let result = jsonSchema
+
+    if (typeof result === 'object' && '$schema' in result) {
+      // Remove $schema property as it's not needed for LLM providers
+      const { $schema, ...rest } = result
+      result = rest
+    }
+
+    // Ensure object schemas always have type: "object"
+
+    if (typeof result === 'object') {
+      // If it has properties (even empty), it should be an object type
+      if ('properties' in result && !result.type) {
+        result.type = 'object'
+      }
+
+      // Ensure properties exists for object types (even if empty)
+      if (result.type === 'object' && !('properties' in result)) {
+        result.properties = {}
+      }
+
+      // Ensure required exists for object types (even if empty array)
+      if (result.type === 'object' && !('required' in result)) {
+        result.required = []
+      }
+
+      // Apply structured output transformation if requested
+      if (forStructuredOutput) {
+        result = makeStructuredOutputCompatible(
+          result,
+          (result.required as Array<string>) || [],
+        )
+      }
+    }
+
+    return result as JSONSchema
+  }
+
+  // If it's not a Standard JSON Schema, assume it's already a JSONSchema and pass through
+  // Still apply structured output transformation if requested
+
+  if (forStructuredOutput && typeof schema === 'object') {
+    return makeStructuredOutputCompatible(
+      schema as Record<string, any>,
+      ((schema as JSONSchema).required as Array<string>) || [],
+    ) as JSONSchema
+  }
+
+  return schema as JSONSchema
+}
+
+/**
+ * Validates data against a Standard Schema compliant schema.
+ *
+ * @param schema - Standard Schema compliant schema
+ * @param data - Data to validate
+ * @returns Validation result with success status, data or issues
+ */
+export async function validateWithStandardSchema<T>(
+  schema: unknown,
+  data: unknown,
+): Promise<
+  | { success: true; data: T }
+  | { success: false; issues: Array<{ message: string; path?: Array<string> }> }
+> {
+  if (!isStandardSchema(schema)) {
+    // If it's not a Standard Schema, just return the data as-is
+    return { success: true, data: data as T }
+  }
+
+  const result = await schema['~standard'].validate(data)
+
+  if (!result.issues) {
+    return { success: true, data: result.value as T }
+  }
+
+  return {
+    success: false,
+    issues: result.issues.map((issue) => ({
+      message: issue.message || 'Validation failed',
+      path: issue.path?.map(String),
+    })),
+  }
+}
+
+/**
+ * Synchronously validates data against a Standard Schema compliant schema.
+ * Note: Some Standard Schema implementations may only support async validation.
+ * In those cases, this function will throw.
+ *
+ * @param schema - Standard Schema compliant schema
+ * @param data - Data to validate
+ * @returns Parsed/validated data
+ * @throws Error if validation fails or if the schema only supports async validation
+ */
+export function parseWithStandardSchema<T>(schema: unknown, data: unknown): T {
+  if (!isStandardSchema(schema)) {
+    // If it's not a Standard Schema, just return the data as-is
+    return data as T
+  }
+
+  const result = schema['~standard'].validate(data)
+
+  // Handle async result (Promise)
+  if (result instanceof Promise) {
+    throw new Error(
+      'Schema validation returned a Promise. Use validateWithStandardSchema for async validation.',
+    )
+  }
+  // Standard Schema validation returns { value } for success or { issues } for failure
+  if (!result.issues) {
+    return result.value as T
+  }
+
+  // invalid validation, throw error with all issues
+  const errorMessages = result.issues
+    .map((issue) => issue.message || 'Validation failed')
+    .join(', ')
+  throw new Error(`Validation failed: ${errorMessages}`)
+}

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

@@ -1,20 +1,11 @@
+import { isStandardSchema, parseWithStandardSchema } from './schema-converter'
 import type {
   DoneStreamChunk,
   ModelMessage,
-  SchemaInput,
   Tool,
   ToolCall,
   ToolResultStreamChunk,
 } from '../../../types'
-import type { z } from 'zod'
-
-/**
- * Check if a value is a Zod schema by looking for Zod-specific internals.
- */
-function isZodSchema(schema: SchemaInput | undefined): schema is z.ZodType {
-  if (!schema) return false
-  return '_zod' in schema && typeof (schema as any)._zod === 'object'
-}
 
 /**
  * Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.
@@ -131,7 +122,7 @@ export class ToolCallManager {
       if (tool?.execute) {
         try {
           // Parse arguments
-          let args: any
+          let args: unknown
           try {
             args = JSON.parse(toolCall.function.arguments)
           } catch (parseError) {
@@ -140,13 +131,17 @@ export class ToolCallManager {
             )
           }
 
-          // Validate input against inputSchema (only for Zod schemas)
-          if (tool.inputSchema && isZodSchema(tool.inputSchema)) {
+          // Validate input against inputSchema (for Standard Schema compliant schemas)
+          if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {
             try {
-              args = tool.inputSchema.parse(args)
-            } catch (validationError: any) {
+              args = parseWithStandardSchema(tool.inputSchema, args)
+            } catch (validationError: unknown) {
+              const message =
+                validationError instanceof Error
+                  ? validationError.message
+                  : 'Validation failed'
               throw new Error(
-                `Input validation failed for tool ${tool.name}: ${validationError.message}`,
+                `Input validation failed for tool ${tool.name}: ${message}`,
               )
             }
           }
@@ -154,27 +149,33 @@ export class ToolCallManager {
           // Execute the tool
           let result = await tool.execute(args)
 
-          // Validate output against outputSchema if provided (only for Zod schemas)
+          // Validate output against outputSchema if provided (for Standard Schema compliant schemas)
           if (
             tool.outputSchema &&
-            isZodSchema(tool.outputSchema) &&
+            isStandardSchema(tool.outputSchema) &&
             result !== undefined &&
             result !== null
           ) {
             try {
-              result = tool.outputSchema.parse(result)
-            } catch (validationError: any) {
+              result = parseWithStandardSchema(tool.outputSchema, result)
+            } catch (validationError: unknown) {
+              const message =
+                validationError instanceof Error
+                  ? validationError.message
+                  : 'Validation failed'
               throw new Error(
-                `Output validation failed for tool ${tool.name}: ${validationError.message}`,
+                `Output validation failed for tool ${tool.name}: ${message}`,
               )
             }
           }
 
           toolResultContent =
             typeof result === 'string' ? result : JSON.stringify(result)
-        } catch (error: any) {
+        } catch (error: unknown) {
           // If tool execution fails, add error message
-          toolResultContent = `Error executing tool: ${error.message}`
+          const message =
+            error instanceof Error ? error.message : 'Unknown error'
+          toolResultContent = `Error executing tool: ${message}`
         }
       } else {
         // Tool doesn't have execute function, add placeholder
@@ -286,7 +287,7 @@ export async function executeToolCalls(
     }
 
     // Parse arguments, throwing error if invalid JSON
-    let input: any = {}
+    let input: unknown = {}
     const argsStr = toolCall.function.arguments.trim() || '{}'
     if (argsStr) {
       try {
@@ -297,16 +298,20 @@ export async function executeToolCalls(
       }
     }
 
-    // Validate input against inputSchema (only for Zod schemas)
-    if (tool.inputSchema && isZodSchema(tool.inputSchema)) {
+    // Validate input against inputSchema (for Standard Schema compliant schemas)
+    if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {
       try {
-        input = tool.inputSchema.parse(input)
-      } catch (validationError: any) {
+        input = parseWithStandardSchema(tool.inputSchema, input)
+      } catch (validationError: unknown) {
+        const message =
+          validationError instanceof Error
+            ? validationError.message
+            : 'Validation failed'
         results.push({
           toolCallId: toolCall.id,
           toolName,
           result: {
-            error: `Input validation failed for tool ${tool.name}: ${validationError.message}`,
+            error: `Input validation failed for tool ${tool.name}: ${message}`,
           },
           state: 'output-error',
         })
@@ -393,21 +398,14 @@ export async function executeToolCalls(
             let result = await tool.execute(input)
             const duration = Date.now() - startTime
 
-            // Validate output against outputSchema if provided (only for Zod schemas)
+            // Validate output against outputSchema if provided (for Standard Schema compliant schemas)
             if (
               tool.outputSchema &&
-              isZodSchema(tool.outputSchema) &&
+              isStandardSchema(tool.outputSchema) &&
               result !== undefined &&
               result !== null
             ) {
-              const parsed = tool.outputSchema.safeParse(result)
-              if (parsed.success) {
-                result = parsed.data
-              } else {
-                throw new Error(
-                  `Output validation failed for tool ${tool.name}: ${parsed.error.message}`,
-                )
-              }
+              result = parseWithStandardSchema(tool.outputSchema, result)
             }
 
             results.push({
@@ -419,12 +417,14 @@ export async function executeToolCalls(
                   : result || null,
               duration,
             })
-          } catch (error: any) {
+          } catch (error: unknown) {
             const duration = Date.now() - startTime
+            const message =
+              error instanceof Error ? error.message : 'Unknown error'
             results.push({
               toolCallId: toolCall.id,
               toolName,
-              result: { error: error.message },
+              result: { error: message },
               state: 'output-error',
               duration,
             })
@@ -456,21 +456,14 @@ export async function executeToolCalls(
       let result = await tool.execute(input)
       const duration = Date.now() - startTime
 
-      // Validate output against outputSchema if provided (only for Zod schemas)
+      // Validate output against outputSchema if provided (for Standard Schema compliant schemas)
       if (
         tool.outputSchema &&
-        isZodSchema(tool.outputSchema) &&
+        isStandardSchema(tool.outputSchema) &&
         result !== undefined &&
         result !== null
       ) {
-        const parsed = tool.outputSchema.safeParse(result)
-        if (parsed.success) {
-          result = parsed.data
-        } else {
-          throw new Error(
-            `Output validation failed for tool ${tool.name}: ${parsed.error.message}`,
-          )
-        }
+        result = parseWithStandardSchema(tool.outputSchema, result)
       }
 
       results.push({
@@ -480,12 +473,13 @@ export async function executeToolCalls(
           typeof result === 'string' ? JSON.parse(result) : result || null,
         duration,
       })
-    } catch (error: any) {
+    } catch (error: unknown) {
       const duration = Date.now() - startTime
+      const message = error instanceof Error ? error.message : 'Unknown error'
       results.push({
         toolCallId: toolCall.id,
         toolName,
-        result: { error: error.message },
+        result: { error: message },
         state: 'output-error',
         duration,
       })

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

@@ -1,4 +1,4 @@
-import type { z } from 'zod'
+import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
 import type {
   InferSchemaType,
   JSONSchema,
@@ -10,8 +10,8 @@ import type {
  * Marker type for server-side tools
  */
 export interface ServerTool<
-  TInput extends SchemaInput = z.ZodType,
-  TOutput extends SchemaInput = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > extends Tool<TInput, TOutput, TName> {
   __toolSide: 'server'
@@ -21,8 +21,8 @@ export interface ServerTool<
  * Marker type for client-side tools
  */
 export interface ClientTool<
-  TInput extends SchemaInput = z.ZodType,
-  TOutput extends SchemaInput = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > {
   __toolSide: 'client'
@@ -31,7 +31,7 @@ export interface ClientTool<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: boolean
-  metadata?: Record<string, any>
+  metadata?: Record<string, unknown>
   execute?: (
     args: InferSchemaType<TInput>,
   ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>
@@ -41,8 +41,8 @@ export interface ClientTool<
  * Tool definition that can be used directly or instantiated for server/client
  */
 export interface ToolDefinitionInstance<
-  TInput extends SchemaInput = z.ZodType,
-  TOutput extends SchemaInput = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > extends Tool<TInput, TOutput, TName> {
   __toolSide: 'definition'
@@ -52,8 +52,8 @@ export interface ToolDefinitionInstance<
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | ClientTool<any, any>
-  | ToolDefinitionInstance<any, any>
+  | ClientTool<SchemaInput, SchemaInput>
+  | ToolDefinitionInstance<SchemaInput, SchemaInput>
 
 /**
  * Extract the tool name as a literal type
@@ -61,33 +61,33 @@ export type AnyClientTool =
 export type InferToolName<T> = T extends { name: infer N } ? N : never
 
 /**
- * Extract the input type from a tool (inferred from Zod schema, or `any` for JSONSchema)
+ * Extract the input type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolInput<T> = T extends { inputSchema?: infer TInput }
-  ? TInput extends z.ZodType
-    ? z.infer<TInput>
+  ? TInput extends StandardJSONSchemaV1<infer TInferred, unknown>
+    ? TInferred
     : TInput extends JSONSchema
-      ? any
-      : any
-  : any
+      ? unknown
+      : unknown
+  : unknown
 
 /**
- * Extract the output type from a tool (inferred from Zod schema, or `any` for JSONSchema)
+ * Extract the output type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolOutput<T> = T extends { outputSchema?: infer TOutput }
-  ? TOutput extends z.ZodType
-    ? z.infer<TOutput>
+  ? TOutput extends StandardJSONSchemaV1<infer TInferred, unknown>
+    ? TInferred
     : TOutput extends JSONSchema
-      ? any
-      : any
-  : any
+      ? unknown
+      : unknown
+  : unknown
 
 /**
  * Tool definition configuration
  */
 export interface ToolDefinitionConfig<
-  TInput extends SchemaInput = z.ZodType,
-  TOutput extends SchemaInput = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > {
   name: TName
@@ -95,15 +95,15 @@ export interface ToolDefinitionConfig<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: boolean
-  metadata?: Record<string, any>
+  metadata?: Record<string, unknown>
 }
 
 /**
  * Tool definition builder that allows creating server or client tools from a shared definition
  */
 export interface ToolDefinition<
-  TInput extends SchemaInput = z.ZodType,
-  TOutput extends SchemaInput = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > extends ToolDefinitionInstance<TInput, TOutput, TName> {
   /**
@@ -133,11 +133,15 @@ export interface ToolDefinition<
  * 2. Instantiated as a server tool with .server()
  * 3. Instantiated as a client tool with .client()
  *
+ * Supports any Standard JSON Schema compliant library (Zod v4+, ArkType, Valibot, etc.)
+ * or plain JSON Schema objects.
+ *
  * @example
  * ```typescript
  * import { toolDefinition } from '@tanstack/ai';
  * import { z } from 'zod';
  *
+ * // Using Zod (natively supports Standard JSON Schema)
  * const addToCartTool = toolDefinition({
  *   name: 'addToCart',
  *   description: 'Add a guitar to the shopping cart (requires approval)',
@@ -177,8 +181,8 @@ export interface ToolDefinition<
  * ```
  */
 export function toolDefinition<
-  TInput extends SchemaInput = z.ZodAny,
-  TOutput extends SchemaInput = z.ZodAny,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 >(
   config: ToolDefinitionConfig<TInput, TOutput, TName>,