@livekit/agents 1.0.14 → 1.0.15

package/src/llm/__snapshots__/zod-utils.test.ts.snap

@@ -0,0 +1,341 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v3 schemas > should convert basic v3 object schema to JSON Schema 1`] = `
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "age": {
+      "type": "number",
+    },
+    "name": {
+      "type": "string",
+    },
+  },
+  "required": [
+    "name",
+    "age",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v3 schemas > should handle v3 array schemas 1`] = `
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "tags": {
+      "items": {
+        "type": "string",
+      },
+      "type": "array",
+    },
+  },
+  "required": [
+    "tags",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v3 schemas > should handle v3 enum schemas 1`] = `
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "color": {
+      "enum": [
+        "red",
+        "blue",
+        "green",
+      ],
+      "type": "string",
+    },
+  },
+  "required": [
+    "color",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v3 schemas > should handle v3 nested object schemas 1`] = `
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "user": {
+      "additionalProperties": false,
+      "properties": {
+        "email": {
+          "type": "string",
+        },
+        "name": {
+          "type": "string",
+        },
+      },
+      "required": [
+        "name",
+        "email",
+      ],
+      "type": "object",
+    },
+  },
+  "required": [
+    "user",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v3 schemas > should handle v3 schemas with default values 1`] = `
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "active": {
+      "anyOf": [
+        {
+          "default": true,
+          "type": "boolean",
+        },
+        {
+          "type": "null",
+        },
+      ],
+    },
+    "name": {
+      "type": "string",
+    },
+    "role": {
+      "anyOf": [
+        {
+          "default": "user",
+          "type": "string",
+        },
+        {
+          "type": "null",
+        },
+      ],
+    },
+  },
+  "required": [
+    "name",
+    "role",
+    "active",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v3 schemas > should handle v3 schemas with descriptions 1`] = `
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "location": {
+      "description": "The location to search",
+      "type": "string",
+    },
+  },
+  "required": [
+    "location",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v3 schemas > should handle v3 schemas with multiple optional fields 1`] = `
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "age": {
+      "type": [
+        "number",
+        "null",
+      ],
+    },
+    "email": {
+      "type": "string",
+    },
+    "id": {
+      "type": "string",
+    },
+    "name": {
+      "type": [
+        "string",
+        "null",
+      ],
+    },
+  },
+  "required": [
+    "id",
+    "name",
+    "age",
+    "email",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v4 schemas > should convert basic v4 object schema to JSON Schema 1`] = `
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "age": {
+      "type": "number",
+    },
+    "name": {
+      "type": "string",
+    },
+  },
+  "required": [
+    "name",
+    "age",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v4 schemas > should handle v4 array schemas 1`] = `
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "tags": {
+      "items": {
+        "type": "string",
+      },
+      "type": "array",
+    },
+  },
+  "required": [
+    "tags",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v4 schemas > should handle v4 enum schemas 1`] = `
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "color": {
+      "enum": [
+        "red",
+        "blue",
+        "green",
+      ],
+      "type": "string",
+    },
+  },
+  "required": [
+    "color",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v4 schemas > should handle v4 nested object schemas 1`] = `
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "user": {
+      "additionalProperties": false,
+      "properties": {
+        "email": {
+          "type": "string",
+        },
+        "name": {
+          "type": "string",
+        },
+      },
+      "required": [
+        "name",
+        "email",
+      ],
+      "type": "object",
+    },
+  },
+  "required": [
+    "user",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v4 schemas > should handle v4 schemas with default values 1`] = `
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "active": {
+      "default": true,
+      "type": "boolean",
+    },
+    "name": {
+      "type": "string",
+    },
+    "role": {
+      "default": "user",
+      "type": "string",
+    },
+  },
+  "required": [
+    "name",
+    "role",
+    "active",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v4 schemas > should handle v4 schemas with multiple optional fields 1`] = `
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "age": {
+      "type": "number",
+    },
+    "email": {
+      "type": "string",
+    },
+    "id": {
+      "type": "string",
+    },
+    "name": {
+      "type": "string",
+    },
+  },
+  "required": [
+    "id",
+    "email",
+  ],
+  "type": "object",
+}
+`;
+
+exports[`Zod Utils > zodSchemaToJsonSchema > Zod v4 schemas > should handle v4 schemas with optional fields 1`] = `
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "optional": {
+      "type": "string",
+    },
+    "required": {
+      "type": "string",
+    },
+  },
+  "required": [
+    "required",
+  ],
+  "type": "object",
+}
+`;

package/src/llm/tool_context.test.ts

@@ -3,6 +3,8 @@
 // SPDX-License-Identifier: Apache-2.0
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
+import * as z3 from 'zod/v3';
+import * as z4 from 'zod/v4';
 import { type ToolOptions, tool } from './tool_context.js';
 import { createToolOptions, oaiParams } from './utils.js';
 
@@ -164,12 +166,43 @@ describe('Tool Context', () => {
         expect(simpleAction.type).toBe('function');
         expect(simpleAction.description).toBe('Perform a simple action');
         expect(simpleAction.parameters).toBeDefined();
-        expect(simpleAction.parameters._def.typeName).toBe('ZodObject');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        expect((simpleAction.parameters as any)._def.typeName).toBe('ZodObject');
 
         const result = await simpleAction.execute({}, createToolOptions('123'));
         expect(result).toBe('Action performed');
       });
 
+      it('should support .optional() fields in tool parameters', async () => {
+        const weatherTool = tool({
+          description: 'Get weather information',
+          parameters: z.object({
+            location: z.string().describe('The city or location').optional(),
+            units: z.enum(['celsius', 'fahrenheit']).describe('Temperature units').optional(),
+          }),
+          execute: async ({ location, units }) => {
+            const loc = location ?? 'Unknown';
+            const unit = units ?? 'celsius';
+            return `Weather in ${loc} (${unit})`;
+          },
+        });
+
+        expect(weatherTool.type).toBe('function');
+        expect(weatherTool.description).toBe('Get weather information');
+
+        const result1 = await weatherTool.execute(
+          { location: 'London', units: 'celsius' },
+          createToolOptions('123'),
+        );
+        expect(result1).toBe('Weather in London (celsius)');
+
+        const result2 = await weatherTool.execute({}, createToolOptions('123'));
+        expect(result2).toBe('Weather in Unknown (celsius)');
+
+        const result3 = await weatherTool.execute({ location: 'Paris' }, createToolOptions('123'));
+        expect(result3).toBe('Weather in Paris (celsius)');
+      });
+
       it('should handle tools with context but no parameters', async () => {
         const greetUser = tool({
           description: 'Greet the current user',
@@ -194,5 +227,181 @@ describe('Tool Context', () => {
         expect(result).toBe('Tool call ID: test-id-456');
       });
     });
+
+    describe('Zod v3 and v4 compatibility', () => {
+      it('should work with Zod v3 schemas', async () => {
+        const v3Tool = tool({
+          description: 'A tool using Zod v3 schema',
+          parameters: z3.object({
+            name: z3.string(),
+            count: z3.number(),
+          }),
+          execute: async ({ name, count }) => {
+            return `${name}: ${count}`;
+          },
+        });
+
+        const result = await v3Tool.execute(
+          { name: 'Test', count: 42 },
+          createToolOptions('v3-test'),
+        );
+        expect(result).toBe('Test: 42');
+      });
+
+      it('should work with Zod v4 schemas', async () => {
+        const v4Tool = tool({
+          description: 'A tool using Zod v4 schema',
+          parameters: z4.object({
+            name: z4.string(),
+            count: z4.number(),
+          }),
+          execute: async ({ name, count }) => {
+            return `${name}: ${count}`;
+          },
+        });
+
+        const result = await v4Tool.execute(
+          { name: 'Test', count: 42 },
+          createToolOptions('v4-test'),
+        );
+        expect(result).toBe('Test: 42');
+      });
+
+      it('should handle v4 schemas with optional fields', async () => {
+        const v4Tool = tool({
+          description: 'Tool with optional field using v4',
+          parameters: z4.object({
+            required: z4.string(),
+            optional: z4.string().optional(),
+          }),
+          execute: async ({ required, optional }) => {
+            return optional ? `${required} - ${optional}` : required;
+          },
+        });
+
+        const result1 = await v4Tool.execute({ required: 'Hello' }, createToolOptions('test-1'));
+        expect(result1).toBe('Hello');
+
+        const result2 = await v4Tool.execute(
+          { required: 'Hello', optional: 'World' },
+          createToolOptions('test-2'),
+        );
+        expect(result2).toBe('Hello - World');
+      });
+
+      it('should handle v4 enum schemas', async () => {
+        const v4Tool = tool({
+          description: 'Tool with enum using v4',
+          parameters: z4.object({
+            color: z4.enum(['red', 'blue', 'green']),
+          }),
+          execute: async ({ color }) => {
+            return `Selected color: ${color}`;
+          },
+        });
+
+        const result = await v4Tool.execute({ color: 'blue' }, createToolOptions('test-enum'));
+        expect(result).toBe('Selected color: blue');
+      });
+
+      it('should handle v4 array schemas', async () => {
+        const v4Tool = tool({
+          description: 'Tool with array using v4',
+          parameters: z4.object({
+            tags: z4.array(z4.string()),
+          }),
+          execute: async ({ tags }) => {
+            return `Tags: ${tags.join(', ')}`;
+          },
+        });
+
+        const result = await v4Tool.execute(
+          { tags: ['nodejs', 'typescript', 'testing'] },
+          createToolOptions('test-array'),
+        );
+        expect(result).toBe('Tags: nodejs, typescript, testing');
+      });
+
+      it('should handle v4 nested object schemas', async () => {
+        const v4Tool = tool({
+          description: 'Tool with nested object using v4',
+          parameters: z4.object({
+            user: z4.object({
+              name: z4.string(),
+              email: z4.string(),
+            }),
+          }),
+          execute: async ({ user }) => {
+            return `${user.name} (${user.email})`;
+          },
+        });
+
+        const result = await v4Tool.execute(
+          { user: { name: 'John Doe', email: 'john@example.com' } },
+          createToolOptions('test-nested'),
+        );
+        expect(result).toBe('John Doe (john@example.com)');
+      });
+    });
+
+    describe('oaiParams with v4 schemas', () => {
+      it('should convert v4 basic object schema', () => {
+        const schema = z4.object({
+          name: z4.string().describe('User name'),
+          age: z4.number().describe('User age'),
+        });
+
+        const result = oaiParams(schema);
+
+        expect(result.type).toBe('object');
+        expect(result.properties).toHaveProperty('name');
+        expect(result.properties).toHaveProperty('age');
+        expect(result.required).toContain('name');
+        expect(result.required).toContain('age');
+      });
+
+      it('should handle v4 optional fields', () => {
+        const schema = z4.object({
+          required: z4.string(),
+          optional: z4.string().optional(),
+        });
+
+        const result = oaiParams(schema);
+
+        expect(result.required).toContain('required');
+        expect(result.required).not.toContain('optional');
+      });
+
+      it('should handle v4 enum fields', () => {
+        const schema = z4.object({
+          status: z4.enum(['pending', 'approved', 'rejected']),
+        });
+
+        const result = oaiParams(schema);
+
+        const properties = result.properties as Record<string, Record<string, unknown>>;
+        expect(properties.status?.enum).toEqual(['pending', 'approved', 'rejected']);
+      });
+
+      it('should handle v4 array fields', () => {
+        const schema = z4.object({
+          items: z4.array(z4.string()),
+        });
+
+        const result = oaiParams(schema);
+
+        const properties = result.properties as Record<string, any>;
+        expect(
+          properties.items && typeof properties.items === 'object'
+            ? properties.items.type
+            : undefined,
+        ).toBe('array');
+        expect(
+          properties.items && properties.items.items && typeof properties.items.items === 'object'
+            ? properties.items.items.type
+            : undefined,
+        ).toBe('string');
+      });
+    });
   });
 });

package/src/llm/tool_context.ts

@@ -2,9 +2,10 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import type { JSONSchema7 } from 'json-schema';
-import { ZodObject, ZodType, z } from 'zod';
+import { z } from 'zod';
 import type { Agent } from '../voice/agent.js';
 import type { RunContext, UnknownUserData } from '../voice/run_context.js';
+import { isZodObjectSchema, isZodSchema } from './zod-utils.js';
 
 // heavily inspired by Vercel AI's `tool()`:
 // https://github.com/vercel/ai/blob/3b0983b/packages/ai/core/tool/tool.ts
@@ -23,9 +24,38 @@ export type JSONObject = {
   [key: string]: JSONValue;
 };
 
-// TODO(AJS-111): support Zod cross-version compatibility, raw JSON schema, both strict and non-strict versions
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ToolInputSchema<T extends JSONObject> = ZodObject<any, any, any, T, T> | JSONSchema7;
+// Supports both Zod v3 and v4 schemas, as well as raw JSON schema
+// Adapted from Vercel AI SDK's FlexibleSchema approach
+// Source: https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts#L67-L70
+//
+// Vercel uses StandardSchemaV1 from @standard-schema/spec package.
+// We use a simpler approach by directly checking for schema properties:
+// - Zod v3: Has `_output` property
+// - Zod v4: Implements Standard Schema spec with `~standard` property
+// - JSON Schema: Plain object fallback
+export type ToolInputSchema<T = JSONObject> =
+  | {
+      // Zod v3 schema - has _output property for type inference
+      _output: T;
+    }
+  | {
+      // Zod v4 schema (Standard Schema) - has ~standard property
+      '~standard': {
+        types?: { output: T };
+      };
+    }
+  | JSONSchema7;
+
+/**
+ * Infer the output type from a ToolInputSchema.
+ * Adapted from Vercel AI SDK's InferSchema type.
+ * Source: https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts#L72-L79
+ */
+export type InferToolInput<T> = T extends { _output: infer O }
+  ? O
+  : T extends { '~standard': { types?: { output: infer O } } }
+    ? O
+    : any; // eslint-disable-line @typescript-eslint/no-explicit-any -- Fallback type for JSON Schema objects without type inference
 
 export type ToolType = 'function' | 'provider-defined';
 
@@ -153,18 +183,15 @@ export interface FunctionTool<
 
 // TODO(AJS-112): support provider-defined tools in the future)
 export type ToolContext<UserData = UnknownUserData> = {
-  [name: string]: FunctionTool<any, UserData, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic tool registry needs to accept any parameter/result types
+  [name: string]: FunctionTool<any, UserData, any>;
 };
 
 /**
- * Create a function tool.
- *
- * @param description - The description of the tool.
- * @param parameters - The schema of the input that the tool expects. If not provided, defaults to z.object({}).
- * @param execute - The function that is called with the arguments from the tool call and produces a result.
+ * Create a function tool with inferred parameters from the schema.
  */
 export function tool<
-  Parameters extends JSONObject = Record<string, never>,
+  Schema extends ToolInputSchema<any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- Generic constraint needs to accept any JSONObject type
   UserData = UnknownUserData,
   Result = unknown,
 >({
@@ -173,9 +200,21 @@ export function tool<
   execute,
 }: {
   description: string;
-  parameters?: ToolInputSchema<Parameters>;
-  execute: ToolExecuteFunction<Parameters, UserData, Result>;
-}): FunctionTool<Parameters, UserData, Result>;
+  parameters: Schema;
+  execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;
+}): FunctionTool<InferToolInput<Schema>, UserData, Result>;
+
+/**
+ * Create a function tool without parameters.
+ */
+export function tool<UserData = UnknownUserData, Result = unknown>({
+  description,
+  execute,
+}: {
+  description: string;
+  parameters?: never;
+  execute: ToolExecuteFunction<Record<string, never>, UserData, Result>;
+}): FunctionTool<Record<string, never>, UserData, Result>;
 
 /**
  * Create a provider-defined tool.
@@ -197,12 +236,13 @@ export function tool(tool: any): any {
     // Default parameters to z.object({}) if not provided
     const parameters = tool.parameters ?? z.object({});
 
-    // if parameters is not zod object, throw an error
-    if (parameters instanceof ZodType && parameters._def.typeName !== 'ZodObject') {
+    // if parameters is a Zod schema, ensure it's an object schema
+    if (isZodSchema(parameters) && !isZodObjectSchema(parameters)) {
       throw new Error('Tool parameters must be a Zod object schema (z.object(...))');
     }
 
-    if (!(parameters instanceof ZodObject) && !(typeof parameters === 'object')) {
+    // Ensure parameters is either a Zod schema or a plain object (JSON schema)
+    if (!isZodSchema(parameters) && !(typeof parameters === 'object')) {
       throw new Error('Tool parameters must be a Zod object schema or a raw JSON schema');
     }