@tanstack/ai 0.0.1

package/src/tools/tool-definition.ts

@@ -0,0 +1,206 @@
+import type { z } from 'zod'
+import type { Tool } from '../types'
+
+/**
+ * Marker type for server-side tools
+ */
+export interface ServerTool<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodType,
+  TName extends string = string,
+> extends Tool<TInput, TOutput, TName> {
+  __toolSide: 'server'
+}
+
+/**
+ * Marker type for client-side tools
+ */
+export interface ClientTool<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodType,
+  TName extends string = string,
+> {
+  __toolSide: 'client'
+  name: TName
+  description: string
+  inputSchema?: TInput
+  outputSchema?: TOutput
+  needsApproval?: boolean
+  metadata?: Record<string, any>
+  execute?: (
+    args: z.infer<TInput>,
+  ) => Promise<z.infer<TOutput>> | z.infer<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,
+  TName extends string = string,
+> extends Tool<TInput, TOutput, TName> {
+  __toolSide: 'definition'
+}
+
+/**
+ * Union type for any kind of client-side tool (client tool or definition)
+ */
+export type AnyClientTool =
+  | ClientTool<any, any>
+  | ToolDefinitionInstance<any, any>
+
+/**
+ * Extract the tool name as a literal type
+ */
+export type InferToolName<T> = T extends { name: infer N } ? N : never
+
+/**
+ * Extract the input type from a tool (inferred from Zod schema)
+ */
+export type InferToolInput<T> = T extends { inputSchema?: infer TInput }
+  ? TInput extends z.ZodType
+    ? z.infer<TInput>
+    : any
+  : any
+
+/**
+ * Extract the output type from a tool (inferred from Zod schema)
+ */
+export type InferToolOutput<T> = T extends { outputSchema?: infer TOutput }
+  ? TOutput extends z.ZodType
+    ? z.infer<TOutput>
+    : any
+  : any
+
+/**
+ * Tool definition configuration
+ */
+export interface ToolDefinitionConfig<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodType,
+  TName extends string = string,
+> {
+  name: TName
+  description: string
+  inputSchema?: TInput
+  outputSchema?: TOutput
+  needsApproval?: boolean
+  metadata?: Record<string, any>
+}
+
+/**
+ * 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,
+  TName extends string = string,
+> extends ToolDefinitionInstance<TInput, TOutput, TName> {
+  /**
+   * Create a server-side tool with execute function
+   */
+  server: (
+    execute: (
+      args: z.infer<TInput>,
+    ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+  ) => ServerTool<TInput, TOutput, TName>
+
+  /**
+   * Create a client-side tool with optional execute function
+   */
+  client: (
+    execute?: (
+      args: z.infer<TInput>,
+    ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+  ) => ClientTool<TInput, TOutput, TName>
+}
+
+/**
+ * Create an isomorphic tool definition that can be used directly or instantiated for server/client
+ *
+ * The definition contains all tool metadata (name, description, schemas) and can be:
+ * 1. Used directly in chat() on the server (as a tool definition without execute)
+ * 2. Instantiated as a server tool with .server()
+ * 3. Instantiated as a client tool with .client()
+ *
+ * @example
+ * ```typescript
+ * import { toolDefinition } from '@tanstack/ai';
+ * import { z } from 'zod';
+ *
+ * const addToCartTool = toolDefinition({
+ *   name: 'addToCart',
+ *   description: 'Add a guitar to the shopping cart (requires approval)',
+ *   needsApproval: true,
+ *   inputSchema: z.object({
+ *     guitarId: z.string(),
+ *     quantity: z.number(),
+ *   }),
+ *   outputSchema: z.object({
+ *     success: z.boolean(),
+ *     cartId: z.string(),
+ *     totalItems: z.number(),
+ *   }),
+ * });
+ *
+ * // Use directly in chat (server-side, no execute function)
+ * chat({
+ *   tools: [addToCartTool],
+ *   // ...
+ * });
+ *
+ * // Or create server-side implementation
+ * const addToCartServer = addToCartTool.server(async (args) => {
+ *   // args is typed as { guitarId: string; quantity: number }
+ *   return {
+ *     success: true,
+ *     cartId: 'CART_' + Date.now(),
+ *     totalItems: args.quantity,
+ *   };
+ * });
+ *
+ * // Or create client-side implementation
+ * const addToCartClient = addToCartTool.client(async (args) => {
+ *   // Client-specific logic (e.g., localStorage)
+ *   return { success: true, cartId: 'local', totalItems: 1 };
+ * });
+ * ```
+ */
+export function toolDefinition<
+  TInput extends z.ZodType = z.ZodAny,
+  TOutput extends z.ZodType = z.ZodAny,
+  TName extends string = string,
+>(
+  config: ToolDefinitionConfig<TInput, TOutput, TName>,
+): ToolDefinition<TInput, TOutput, TName> {
+  const definition: ToolDefinition<TInput, TOutput, TName> = {
+    __toolSide: 'definition',
+    ...config,
+    server(
+      execute: (
+        args: z.infer<TInput>,
+      ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+    ): ServerTool<TInput, TOutput, TName> {
+      return {
+        __toolSide: 'server',
+        ...config,
+        execute,
+      }
+    },
+
+    client(
+      execute?: (
+        args: z.infer<TInput>,
+      ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+    ): ClientTool<TInput, TOutput, TName> {
+      return {
+        __toolSide: 'client',
+        ...config,
+        execute,
+      }
+    },
+  }
+
+  return definition
+}

package/src/tools/zod-converter.ts

@@ -0,0 +1,85 @@
+import { toJSONSchema } from 'zod'
+import type { z } from 'zod'
+/**
+ * Converts a Zod schema to JSON Schema format compatible with LLM providers.
+ *
+ *
+ * @param schema - Zod schema to convert
+ * @returns JSON Schema object that can be sent to LLM providers
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   location: z.string().describe('City name'),
+ *   unit: z.enum(['celsius', 'fahrenheit']).optional()
+ * });
+ *
+ * const jsonSchema = convertZodToJsonSchema(schema);
+ * // Returns:
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     location: { type: 'string', description: 'City name' },
+ * //     unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
+ * //   },
+ * //   required: ['location']
+ * // }
+ * ```
+ */
+export function convertZodToJsonSchema(
+  schema: z.ZodType | undefined,
+): Record<string, any> | undefined {
+  if (!schema) return undefined
+
+  // 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 = []
+    }
+  }
+
+  return result
+}