@tanstack/ai 0.0.3 → 0.1.0

package/src/{message-converters.ts → activities/chat/messages.ts}

@@ -1,9 +1,3 @@
-/**
- * Message Converters
- *
- * Functions for converting between UIMessage and ModelMessage formats.
- */
-
 import type {
   ContentPart,
   MessagePart,
@@ -12,7 +6,10 @@ import type {
   ToolCallPart,
   ToolResultPart,
   UIMessage,
-} from './types'
+} from '../../types'
+// ===========================
+// Message Converters
+// ===========================
 
 /**
  * Helper to extract text content from string or ContentPart array
@@ -65,11 +62,11 @@ export function convertMessagesToModelMessages(
 export function uiMessageToModelMessages(
   uiMessage: UIMessage,
 ): Array<ModelMessage> {
-  const messages: Array<ModelMessage> = []
+  const messageList: Array<ModelMessage> = []
 
   // Skip system messages - they're handled via systemPrompts, not ModelMessages
   if (uiMessage.role === 'system') {
-    return messages
+    return messageList
   }
 
   // Separate parts by type
@@ -112,14 +109,14 @@ export function uiMessageToModelMessages(
 
   // Create the main message
   if (uiMessage.role !== 'assistant' || content || !toolCalls) {
-    messages.push({
+    messageList.push({
       role: uiMessage.role,
       content,
       ...(toolCalls && toolCalls.length > 0 && { toolCalls }),
     })
   } else if (toolCalls.length > 0) {
     // Assistant message with only tool calls
-    messages.push({
+    messageList.push({
       role: 'assistant',
       content,
       toolCalls,
@@ -132,7 +129,7 @@ export function uiMessageToModelMessages(
       toolResultPart.state === 'complete' ||
       toolResultPart.state === 'error'
     ) {
-      messages.push({
+      messageList.push({
         role: 'tool',
         content: toolResultPart.content,
         toolCallId: toolResultPart.toolCallId,
@@ -140,7 +137,7 @@ export function uiMessageToModelMessages(
     }
   }
 
-  return messages
+  return messageList
 }
 
 /**

package/src/{stream → activities/chat/stream}/message-updaters.ts

@@ -10,7 +10,7 @@ import type {
   ToolCallPart,
   ToolResultPart,
   UIMessage,
-} from '../types'
+} from '../../../types'
 import type { ToolCallState, ToolResultState } from './types'
 
 /**

package/src/{stream → activities/chat/stream}/processor.ts

@@ -13,10 +13,7 @@
  * - Recording/replay for testing
  * - Event-driven architecture for UI updates
  */
-import {
-  generateMessageId,
-  uiMessageToModelMessages,
-} from '../message-converters'
+import { generateMessageId, uiMessageToModelMessages } from '../messages.js'
 import { defaultJSONParser } from './json-parser'
 import {
   updateTextPart,
@@ -43,7 +40,7 @@ import type {
   ToolCall,
   ToolCallPart,
   UIMessage,
-} from '../types'
+} from '../../../types'
 
 /**
  * Events emitted by the StreamProcessor

package/src/{stream → activities/chat/stream}/types.ts

@@ -5,25 +5,15 @@
  * The canonical chunk format is StreamChunk from @tanstack/ai types.
  */
 
-import type { StreamChunk, ToolCall } from '../types'
+import type {
+  StreamChunk,
+  ToolCall,
+  ToolCallState,
+  ToolResultState,
+} from '../../../types'
 
-/**
- * Tool call states - track the lifecycle of a tool call
- */
-export type ToolCallState =
-  | 'awaiting-input' // Received start but no arguments yet
-  | 'input-streaming' // Partial arguments received
-  | 'input-complete' // All arguments received
-  | 'approval-requested' // Waiting for user approval
-  | 'approval-responded' // User has approved/denied
-
-/**
- * Tool result states - track the lifecycle of a tool result
- */
-export type ToolResultState =
-  | 'streaming' // Placeholder for future streamed output
-  | 'complete' // Result is complete
-  | 'error' // Error occurred
+// Re-export for backwards compatibility
+export type { ToolCallState, ToolResultState }
 
 /**
  * Internal state for a tool call being tracked

package/src/{tools → activities/chat/tools}/tool-calls.ts

@@ -1,10 +1,20 @@
 import type {
   DoneStreamChunk,
   ModelMessage,
+  SchemaInput,
   Tool,
   ToolCall,
   ToolResultStreamChunk,
-} from '../types'
+} 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.
@@ -130,8 +140,8 @@ export class ToolCallManager {
             )
           }
 
-          // Validate input against inputSchema
-          if (tool.inputSchema) {
+          // Validate input against inputSchema (only for Zod schemas)
+          if (tool.inputSchema && isZodSchema(tool.inputSchema)) {
             try {
               args = tool.inputSchema.parse(args)
             } catch (validationError: any) {
@@ -144,8 +154,13 @@ export class ToolCallManager {
           // Execute the tool
           let result = await tool.execute(args)
 
-          // Validate output against outputSchema if provided
-          if (tool.outputSchema && result !== undefined && result !== null) {
+          // Validate output against outputSchema if provided (only for Zod schemas)
+          if (
+            tool.outputSchema &&
+            isZodSchema(tool.outputSchema) &&
+            result !== undefined &&
+            result !== null
+          ) {
             try {
               result = tool.outputSchema.parse(result)
             } catch (validationError: any) {
@@ -282,8 +297,8 @@ export async function executeToolCalls(
       }
     }
 
-    // Validate input against inputSchema
-    if (tool.inputSchema) {
+    // Validate input against inputSchema (only for Zod schemas)
+    if (tool.inputSchema && isZodSchema(tool.inputSchema)) {
       try {
         input = tool.inputSchema.parse(input)
       } catch (validationError: any) {
@@ -378,8 +393,13 @@ export async function executeToolCalls(
             let result = await tool.execute(input)
             const duration = Date.now() - startTime
 
-            // Validate output against outputSchema if provided
-            if (tool.outputSchema && result !== undefined && result !== null) {
+            // Validate output against outputSchema if provided (only for Zod schemas)
+            if (
+              tool.outputSchema &&
+              isZodSchema(tool.outputSchema) &&
+              result !== undefined &&
+              result !== null
+            ) {
               const parsed = tool.outputSchema.safeParse(result)
               if (parsed.success) {
                 result = parsed.data
@@ -436,8 +456,13 @@ export async function executeToolCalls(
       let result = await tool.execute(input)
       const duration = Date.now() - startTime
 
-      // Validate output against outputSchema if provided
-      if (tool.outputSchema && result !== undefined && result !== null) {
+      // Validate output against outputSchema if provided (only for Zod schemas)
+      if (
+        tool.outputSchema &&
+        isZodSchema(tool.outputSchema) &&
+        result !== undefined &&
+        result !== null
+      ) {
         const parsed = tool.outputSchema.safeParse(result)
         if (parsed.success) {
           result = parsed.data

package/src/{tools → activities/chat/tools}/tool-definition.ts

@@ -1,12 +1,17 @@
 import type { z } from 'zod'
-import type { Tool } from '../types'
+import type {
+  InferSchemaType,
+  JSONSchema,
+  SchemaInput,
+  Tool,
+} from '../../../types'
 
 /**
  * Marker type for server-side tools
  */
 export interface ServerTool<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = z.ZodType,
+  TOutput extends SchemaInput = z.ZodType,
   TName extends string = string,
 > extends Tool<TInput, TOutput, TName> {
   __toolSide: 'server'
@@ -16,8 +21,8 @@ export interface ServerTool<
  * Marker type for client-side tools
  */
 export interface ClientTool<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = z.ZodType,
+  TOutput extends SchemaInput = z.ZodType,
   TName extends string = string,
 > {
   __toolSide: 'client'
@@ -28,16 +33,16 @@ export interface ClientTool<
   needsApproval?: boolean
   metadata?: Record<string, any>
   execute?: (
-    args: z.infer<TInput>,
-  ) => Promise<z.infer<TOutput>> | z.infer<TOutput>
+    args: InferSchemaType<TInput>,
+  ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>
 }
 
 /**
  * Tool definition that can be used directly or instantiated for server/client
  */
 export interface ToolDefinitionInstance<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = z.ZodType,
+  TOutput extends SchemaInput = z.ZodType,
   TName extends string = string,
 > extends Tool<TInput, TOutput, TName> {
   __toolSide: 'definition'
@@ -56,29 +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)
+ * Extract the input type from a tool (inferred from Zod schema, or `any` for JSONSchema)
  */
 export type InferToolInput<T> = T extends { inputSchema?: infer TInput }
   ? TInput extends z.ZodType
     ? z.infer<TInput>
-    : any
+    : TInput extends JSONSchema
+      ? any
+      : any
   : any
 
 /**
- * Extract the output type from a tool (inferred from Zod schema)
+ * Extract the output type from a tool (inferred from Zod schema, or `any` for JSONSchema)
  */
 export type InferToolOutput<T> = T extends { outputSchema?: infer TOutput }
   ? TOutput extends z.ZodType
     ? z.infer<TOutput>
-    : any
+    : TOutput extends JSONSchema
+      ? any
+      : any
   : any
 
 /**
  * Tool definition configuration
  */
 export interface ToolDefinitionConfig<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = z.ZodType,
+  TOutput extends SchemaInput = z.ZodType,
   TName extends string = string,
 > {
   name: TName
@@ -93,8 +102,8 @@ export interface ToolDefinitionConfig<
  * Tool definition builder that allows creating server or client tools from a shared definition
  */
 export interface ToolDefinition<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = z.ZodType,
+  TOutput extends SchemaInput = z.ZodType,
   TName extends string = string,
 > extends ToolDefinitionInstance<TInput, TOutput, TName> {
   /**
@@ -102,8 +111,8 @@ export interface ToolDefinition<
    */
   server: (
     execute: (
-      args: z.infer<TInput>,
-    ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+      args: InferSchemaType<TInput>,
+    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
   ) => ServerTool<TInput, TOutput, TName>
 
   /**
@@ -111,8 +120,8 @@ export interface ToolDefinition<
    */
   client: (
     execute?: (
-      args: z.infer<TInput>,
-    ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+      args: InferSchemaType<TInput>,
+    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
   ) => ClientTool<TInput, TOutput, TName>
 }
 
@@ -168,8 +177,8 @@ export interface ToolDefinition<
  * ```
  */
 export function toolDefinition<
-  TInput extends z.ZodType = z.ZodAny,
-  TOutput extends z.ZodType = z.ZodAny,
+  TInput extends SchemaInput = z.ZodAny,
+  TOutput extends SchemaInput = z.ZodAny,
   TName extends string = string,
 >(
   config: ToolDefinitionConfig<TInput, TOutput, TName>,
@@ -179,8 +188,8 @@ export function toolDefinition<
     ...config,
     server(
       execute: (
-        args: z.infer<TInput>,
-      ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+        args: InferSchemaType<TInput>,
+      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
     ): ServerTool<TInput, TOutput, TName> {
       return {
         __toolSide: 'server',
@@ -191,8 +200,8 @@ export function toolDefinition<
 
     client(
       execute?: (
-        args: z.infer<TInput>,
-      ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+        args: InferSchemaType<TInput>,
+      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
     ): ClientTool<TInput, TOutput, TName> {
       return {
         __toolSide: 'client',

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

@@ -0,0 +1,235 @@
+import { toJSONSchema } from 'zod'
+import type { z } from 'zod'
+import type { SchemaInput } from '../../../types'
+
+/**
+ * Check if a value is a Zod schema by looking for Zod-specific internals.
+ * Zod schemas have a `_zod` property that contains metadata.
+ */
+function isZodSchema(schema: unknown): schema is z.ZodType {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    '_zod' in schema &&
+    typeof (schema as any)._zod === 'object'
+  )
+}
+
+/**
+ * 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 schema (Zod or JSONSchema) to JSON Schema format compatible with LLM providers.
+ * If the input is already a JSONSchema object, it is returned as-is.
+ * If the input is a Zod schema, it is converted to JSON Schema.
+ *
+ * @param schema - Zod schema or JSONSchema object to convert
+ * @param options - Conversion options
+ * @returns JSON Schema object that can be sent to LLM providers
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * // Using Zod schema
+ * const zodSchema = z.object({
+ *   location: z.string().describe('City name'),
+ *   unit: z.enum(['celsius', 'fahrenheit']).optional()
+ * });
+ *
+ * const jsonSchema = convertZodToJsonSchema(zodSchema);
+ * // Returns:
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     location: { type: 'string', description: 'City name' },
+ * //     unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
+ * //   },
+ * //   required: ['location']
+ * // }
+ *
+ * // For OpenAI structured output (all fields required, optional fields nullable)
+ * const structuredSchema = convertZodToJsonSchema(zodSchema, { forStructuredOutput: true });
+ * // Returns:
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     location: { type: 'string', description: 'City name' },
+ * //     unit: { type: ['string', 'null'], enum: ['celsius', 'fahrenheit'] }
+ * //   },
+ * //   required: ['location', 'unit'],
+ * //   additionalProperties: false
+ * // }
+ *
+ * // Using JSONSchema directly (passes through unchanged)
+ * const rawSchema = {
+ *   type: 'object',
+ *   properties: { location: { type: 'string' } },
+ *   required: ['location']
+ * };
+ * const result = convertZodToJsonSchema(rawSchema);
+ * // Returns the same object
+ * ```
+ */
+export function convertZodToJsonSchema(
+  schema: SchemaInput | undefined,
+  options: ConvertSchemaOptions = {},
+): Record<string, any> | undefined {
+  if (!schema) return undefined
+
+  const { forStructuredOutput = false } = options
+
+  // If it's not a Zod schema, assume it's already a JSONSchema and pass through
+  if (!isZodSchema(schema)) {
+    // Still apply structured output transformation if requested
+    if (forStructuredOutput && typeof schema === 'object') {
+      return makeStructuredOutputCompatible(
+        schema,
+        (schema as any).required || [],
+      )
+    }
+    return schema
+  }
+
+  // Use Alcyone Labs fork which is compatible with Zod v4
+  const jsonSchema = toJSONSchema(schema, {
+    target: 'openapi-3.0',
+    reused: 'ref',
+  })
+
+  // Remove $schema property as it's not needed for LLM providers
+  let result = jsonSchema
+  if (typeof result === 'object' && '$schema' in result) {
+    const { $schema, ...rest } = result
+    result = rest
+  }
+
+  // Ensure object schemas always have type: "object"
+  // This fixes cases where zod-to-json-schema doesn't set type for empty objects
+  if (typeof result === 'object') {
+    // Check if the input schema is a ZodObject by inspecting its internal structure
+    const isZodObject =
+      typeof schema === 'object' &&
+      'def' in schema &&
+      schema.def.type === 'object'
+
+    // If we know it's a ZodObject but result doesn't have type, set it
+    if (isZodObject && !result.type) {
+      result.type = 'object'
+    }
+
+    // If result is completely empty (no keys), it's likely an empty object schema
+    if (Object.keys(result).length === 0) {
+      result.type = '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 || [])
+    }
+  }
+
+  return result
+}