@livekit/agents 1.1.0 → 1.2.1

package/dist/llm/tool_context.d.cts

@@ -1,5 +1,4 @@
 import type { JSONSchema7 } from 'json-schema';
-import { ZodObject } from 'zod';
 import type { Agent } from '../voice/agent.js';
 import type { RunContext, UnknownUserData } from '../voice/run_context.js';
 declare const TOOL_SYMBOL: unique symbol;
@@ -11,7 +10,29 @@ export type JSONArray = JSONValue[];
 export type JSONObject = {
     [key: string]: JSONValue;
 };
-export type ToolInputSchema<T extends JSONObject> = ZodObject<any, any, any, T, T> | JSONSchema7;
+export type ToolInputSchema<T = JSONObject> = {
+    _output: T;
+} | {
+    '~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;
 export type ToolType = 'function' | 'provider-defined';
 export type ToolChoice = 'auto' | 'none' | 'required' | {
     type: 'function';
@@ -22,6 +43,11 @@ export type ToolChoice = 'auto' | 'none' | 'required' | {
 export declare class ToolError extends Error {
     constructor(message: string);
 }
+export declare const ToolFlag: {
+    readonly NONE: 0;
+    readonly IGNORE_ON_ENTER: number;
+};
+export type ToolFlag = (typeof ToolFlag)[keyof typeof ToolFlag];
 export interface AgentHandoff {
     /**
      * The agent to handoff to.
@@ -89,23 +115,33 @@ export interface FunctionTool<Parameters extends JSONObject, UserData = UnknownU
      * It also carries context about current session, user-defined data, and the tool call id, etc.
      */
     execute: ToolExecuteFunction<Parameters, UserData, Result>;
+    flags: number;
     [FUNCTION_TOOL_SYMBOL]: true;
 }
 export type ToolContext<UserData = UnknownUserData> = {
     [name: string]: FunctionTool<any, UserData, any>;
 };
+export declare function isSameToolContext(ctx1: ToolContext, ctx2: ToolContext): boolean;
+export declare function isSameToolChoice(choice1: ToolChoice | null, choice2: ToolChoice | null): boolean;
 /**
- * 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 declare function tool<Parameters extends JSONObject = Record<string, never>, UserData = UnknownUserData, Result = unknown>({ description, parameters, execute, }: {
+export declare function tool<Schema extends ToolInputSchema<any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- Generic constraint needs to accept any JSONObject type
+UserData = UnknownUserData, Result = unknown>({ description, parameters, execute, flags, }: {
     description: string;
-    parameters?: ToolInputSchema<Parameters>;
-    execute: ToolExecuteFunction<Parameters, UserData, Result>;
-}): FunctionTool<Parameters, UserData, Result>;
+    parameters: Schema;
+    execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;
+    flags?: number;
+}): FunctionTool<InferToolInput<Schema>, UserData, Result>;
+/**
+ * Create a function tool without parameters.
+ */
+export declare function tool<UserData = UnknownUserData, Result = unknown>({ description, execute, flags, }: {
+    description: string;
+    parameters?: never;
+    execute: ToolExecuteFunction<Record<string, never>, UserData, Result>;
+    flags?: number;
+}): FunctionTool<Record<string, never>, UserData, Result>;
 /**
  * Create a provider-defined tool.
  *

package/dist/llm/tool_context.d.ts

@@ -1,5 +1,4 @@
 import type { JSONSchema7 } from 'json-schema';
-import { ZodObject } from 'zod';
 import type { Agent } from '../voice/agent.js';
 import type { RunContext, UnknownUserData } from '../voice/run_context.js';
 declare const TOOL_SYMBOL: unique symbol;
@@ -11,7 +10,29 @@ export type JSONArray = JSONValue[];
 export type JSONObject = {
     [key: string]: JSONValue;
 };
-export type ToolInputSchema<T extends JSONObject> = ZodObject<any, any, any, T, T> | JSONSchema7;
+export type ToolInputSchema<T = JSONObject> = {
+    _output: T;
+} | {
+    '~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;
 export type ToolType = 'function' | 'provider-defined';
 export type ToolChoice = 'auto' | 'none' | 'required' | {
     type: 'function';
@@ -22,6 +43,11 @@ export type ToolChoice = 'auto' | 'none' | 'required' | {
 export declare class ToolError extends Error {
     constructor(message: string);
 }
+export declare const ToolFlag: {
+    readonly NONE: 0;
+    readonly IGNORE_ON_ENTER: number;
+};
+export type ToolFlag = (typeof ToolFlag)[keyof typeof ToolFlag];
 export interface AgentHandoff {
     /**
      * The agent to handoff to.
@@ -89,23 +115,33 @@ export interface FunctionTool<Parameters extends JSONObject, UserData = UnknownU
      * It also carries context about current session, user-defined data, and the tool call id, etc.
      */
     execute: ToolExecuteFunction<Parameters, UserData, Result>;
+    flags: number;
     [FUNCTION_TOOL_SYMBOL]: true;
 }
 export type ToolContext<UserData = UnknownUserData> = {
     [name: string]: FunctionTool<any, UserData, any>;
 };
+export declare function isSameToolContext(ctx1: ToolContext, ctx2: ToolContext): boolean;
+export declare function isSameToolChoice(choice1: ToolChoice | null, choice2: ToolChoice | null): boolean;
 /**
- * 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 declare function tool<Parameters extends JSONObject = Record<string, never>, UserData = UnknownUserData, Result = unknown>({ description, parameters, execute, }: {
+export declare function tool<Schema extends ToolInputSchema<any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- Generic constraint needs to accept any JSONObject type
+UserData = UnknownUserData, Result = unknown>({ description, parameters, execute, flags, }: {
     description: string;
-    parameters?: ToolInputSchema<Parameters>;
-    execute: ToolExecuteFunction<Parameters, UserData, Result>;
-}): FunctionTool<Parameters, UserData, Result>;
+    parameters: Schema;
+    execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;
+    flags?: number;
+}): FunctionTool<InferToolInput<Schema>, UserData, Result>;
+/**
+ * Create a function tool without parameters.
+ */
+export declare function tool<UserData = UnknownUserData, Result = unknown>({ description, execute, flags, }: {
+    description: string;
+    parameters?: never;
+    execute: ToolExecuteFunction<Record<string, never>, UserData, Result>;
+    flags?: number;
+}): FunctionTool<Record<string, never>, UserData, Result>;
 /**
  * Create a provider-defined tool.
  *

package/dist/llm/tool_context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool_context.d.ts","sourceRoot":"","sources":["../../src/llm/tool_context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAc,MAAM,KAAK,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAK3E,QAAA,MAAM,WAAW,eAAiB,CAAC;AACnC,QAAA,MAAM,oBAAoB,eAA0B,CAAC;AACrD,QAAA,MAAM,4BAA4B,eAAkC,CAAC;AAErE,QAAA,MAAM,cAAc,eAAoB,CAAC;AAEzC,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAElF,MAAM,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC;AAEpC,MAAM,MAAM,UAAU,GAAG;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,CAAC;AAIF,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,UAAU,IAAI,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC;AAEjG,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,kBAAkB,CAAC;AAEvD,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,MAAM,GACN,UAAU,GACV;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH,CAAC;AAEN,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAO5B;AAED,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;IAEb;;OAEG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;IAEd,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;CACxB;AAGD,wBAAgB,OAAO,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,YAAY,CAM9E;AAED,MAAM,WAAW,WAAW,CAAC,QAAQ,GAAG,eAAe;IACrD;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAE1B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,MAAM,mBAAmB,CAC7B,UAAU,SAAS,UAAU,EAC7B,QAAQ,GAAG,eAAe,EAC1B,MAAM,GAAG,OAAO,IACd,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,WAAW,IAAI;IACnB;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAC;IAEf,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;CACrB;AAGD,MAAM,WAAW,mBAAoB,SAAQ,IAAI;IAC/C,IAAI,EAAE,kBAAkB,CAAC;IAEzB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,CAAC,4BAA4B,CAAC,EAAE,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,YAAY,CAC3B,UAAU,SAAS,UAAU,EAC7B,QAAQ,GAAG,eAAe,EAC1B,MAAM,GAAG,OAAO,CAChB,SAAQ,IAAI;IACZ,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IAExC;;;OAGG;IACH,OAAO,EAAE,mBAAmB,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAE3D,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAC;CAC9B;AAGD,MAAM,MAAM,WAAW,CAAC,QAAQ,GAAG,eAAe,IAAI;IACpD,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;CAClD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,IAAI,CAClB,UAAU,SAAS,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACrD,QAAQ,GAAG,eAAe,EAC1B,MAAM,GAAG,OAAO,EAChB,EACA,WAAW,EACX,UAAU,EACV,OAAO,GACR,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IACzC,OAAO,EAAE,mBAAmB,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;CAC5D,GAAG,YAAY,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EACF,MAAM,GACP,EAAE;IACD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,GAAG,mBAAmB,CAAC;AAyCxB,wBAAgB,MAAM,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,IAAI,IAAI,CAE9C;AAGD,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,IAAI,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAI7E;AAGD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,IAAI,mBAAmB,CAI5E;AAGD,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,SAAS,CAE1D;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,YAAY,CAEpE"}
+{"version":3,"file":"tool_context.d.ts","sourceRoot":"","sources":["../../src/llm/tool_context.ts"],"names":[],"mappings":"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"}

package/dist/llm/tool_context.js

@@ -1,4 +1,5 @@
-import { ZodObject, ZodType, z } from "zod";
+import { z } from "zod";
+import { isZodObjectSchema, isZodSchema } from "./zod-utils.js";
 const TOOL_SYMBOL = Symbol("tool");
 const FUNCTION_TOOL_SYMBOL = Symbol("function_tool");
 const PROVIDER_DEFINED_TOOL_SYMBOL = Symbol("provider_defined_tool");
@@ -12,6 +13,10 @@ class ToolError extends Error {
     });
   }
 }
+const ToolFlag = {
+  NONE: 0,
+  IGNORE_ON_ENTER: 1 << 0
+};
 function handoff(options) {
   return {
     agent: options.agent,
@@ -19,13 +24,49 @@ function handoff(options) {
     [HANDOFF_SYMBOL]: true
   };
 }
+function isSameToolContext(ctx1, ctx2) {
+  const toolNames = new Set(Object.keys(ctx1));
+  const toolNames2 = new Set(Object.keys(ctx2));
+  if (toolNames.size !== toolNames2.size) {
+    return false;
+  }
+  for (const name of toolNames) {
+    if (!toolNames2.has(name)) {
+      return false;
+    }
+    const tool1 = ctx1[name];
+    const tool2 = ctx2[name];
+    if (!tool1 || !tool2) {
+      return false;
+    }
+    if (tool1.description !== tool2.description) {
+      return false;
+    }
+  }
+  return true;
+}
+function isSameToolChoice(choice1, choice2) {
+  if (choice1 === choice2) {
+    return true;
+  }
+  if (choice1 === null || choice2 === null) {
+    return false;
+  }
+  if (typeof choice1 === "string" && typeof choice2 === "string") {
+    return choice1 === choice2;
+  }
+  if (typeof choice1 === "object" && typeof choice2 === "object") {
+    return choice1.type === choice2.type && choice1.function.name === choice2.function.name;
+  }
+  return false;
+}
 function tool(tool2) {
   if (tool2.execute !== void 0) {
     const parameters = tool2.parameters ?? z.object({});
-    if (parameters instanceof ZodType && parameters._def.typeName !== "ZodObject") {
+    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")) {
+    if (!isZodSchema(parameters) && !(typeof parameters === "object")) {
       throw new Error("Tool parameters must be a Zod object schema or a raw JSON schema");
     }
     return {
@@ -33,6 +74,7 @@ function tool(tool2) {
       description: tool2.description,
       parameters,
       execute: tool2.execute,
+      flags: tool2.flags ?? ToolFlag.NONE,
       [TOOL_SYMBOL]: true,
       [FUNCTION_TOOL_SYMBOL]: true
     };
@@ -69,10 +111,13 @@ function isAgentHandoff(handoff2) {
 }
 export {
   ToolError,
+  ToolFlag,
   handoff,
   isAgentHandoff,
   isFunctionTool,
   isProviderDefinedTool,
+  isSameToolChoice,
+  isSameToolContext,
   isTool,
   isToolError,
   tool

package/dist/llm/tool_context.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/llm/tool_context.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { JSONSchema7 } from 'json-schema';\nimport { ZodObject, ZodType, z } from 'zod';\nimport type { Agent } from '../voice/agent.js';\nimport type { RunContext, UnknownUserData } from '../voice/run_context.js';\n\n// heavily inspired by Vercel AI's `tool()`:\n// https://github.com/vercel/ai/blob/3b0983b/packages/ai/core/tool/tool.ts\n\nconst TOOL_SYMBOL = Symbol('tool');\nconst FUNCTION_TOOL_SYMBOL = Symbol('function_tool');\nconst PROVIDER_DEFINED_TOOL_SYMBOL = Symbol('provider_defined_tool');\nconst TOOL_ERROR_SYMBOL = Symbol('tool_error');\nconst HANDOFF_SYMBOL = Symbol('handoff');\n\nexport type JSONValue = null | string | number | boolean | JSONObject | JSONArray;\n\nexport type JSONArray = JSONValue[];\n\nexport type JSONObject = {\n  [key: string]: JSONValue;\n};\n\n// TODO(AJS-111): support Zod cross-version compatibility, raw JSON schema, both strict and non-strict versions\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type ToolInputSchema<T extends JSONObject> = ZodObject<any, any, any, T, T> | JSONSchema7;\n\nexport type ToolType = 'function' | 'provider-defined';\n\nexport type ToolChoice =\n  | 'auto'\n  | 'none'\n  | 'required'\n  | {\n      type: 'function';\n      function: {\n        name: string;\n      };\n    };\n\nexport class ToolError extends Error {\n  constructor(message: string) {\n    super(message);\n\n    Object.defineProperty(this, TOOL_ERROR_SYMBOL, {\n      value: true,\n    });\n  }\n}\n\nexport interface AgentHandoff {\n  /**\n   * The agent to handoff to.\n   */\n  agent: Agent;\n\n  /**\n   * The return value of the tool.\n   */\n  returns?: any; // eslint-disable-line @typescript-eslint/no-explicit-any\n\n  [HANDOFF_SYMBOL]: true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function handoff(options: { agent: Agent; returns?: any }): AgentHandoff {\n  return {\n    agent: options.agent,\n    returns: options.returns,\n    [HANDOFF_SYMBOL]: true,\n  };\n}\n\nexport interface ToolOptions<UserData = UnknownUserData> {\n  /**\n   * RunContext for the current agent session.\n   */\n  ctx: RunContext<UserData>;\n\n  /**\n   * The ID of the tool call.\n   */\n  toolCallId: string;\n\n  /**\n   * An optional abort signal that indicates that the overall operation should be aborted.\n   */\n  abortSignal?: AbortSignal;\n}\n\nexport type ToolExecuteFunction<\n  Parameters extends JSONObject,\n  UserData = UnknownUserData,\n  Result = unknown,\n> = (args: Parameters, opts: ToolOptions<UserData>) => Promise<Result>;\n\nexport interface Tool {\n  /**\n   * The type of the tool.\n   * @internal Either user-defined core tool or provider-defined tool.\n   */\n  type: ToolType;\n\n  [TOOL_SYMBOL]: true;\n}\n\n// TODO(AJS-112): support provider-defined tools\nexport interface ProviderDefinedTool extends Tool {\n  type: 'provider-defined';\n\n  /**\n   * The ID of the tool.\n   */\n  id: string;\n\n  /**\n   * The configuration of the tool.\n   */\n  config: Record<string, unknown>;\n\n  [PROVIDER_DEFINED_TOOL_SYMBOL]: true;\n}\n\nexport interface FunctionTool<\n  Parameters extends JSONObject,\n  UserData = UnknownUserData,\n  Result = unknown,\n> extends Tool {\n  type: 'function';\n\n  /**\n   * The description of the tool. Will be used by the language model to decide whether to use the tool.\n   */\n  description: string;\n\n  /**\n   * The schema of the input that the tool expects. The language model will use this to generate the input.\n   * It is also used to validate the output of the language model.\n   * Use descriptions to make the input understandable for the language model.\n   */\n  parameters: ToolInputSchema<Parameters>;\n\n  /**\n   * An async function that is called with the arguments from the tool call and produces a result.\n   * It also carries context about current session, user-defined data, and the tool call id, etc.\n   */\n  execute: ToolExecuteFunction<Parameters, UserData, Result>;\n\n  [FUNCTION_TOOL_SYMBOL]: true;\n}\n\n// TODO(AJS-112): support provider-defined tools in the future)\nexport type ToolContext<UserData = UnknownUserData> = {\n  [name: string]: FunctionTool<any, UserData, any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n};\n\n/**\n * Create a function tool.\n *\n * @param description - The description of the tool.\n * @param parameters - The schema of the input that the tool expects. If not provided, defaults to z.object({}).\n * @param execute - The function that is called with the arguments from the tool call and produces a result.\n */\nexport function tool<\n  Parameters extends JSONObject = Record<string, never>,\n  UserData = UnknownUserData,\n  Result = unknown,\n>({\n  description,\n  parameters,\n  execute,\n}: {\n  description: string;\n  parameters?: ToolInputSchema<Parameters>;\n  execute: ToolExecuteFunction<Parameters, UserData, Result>;\n}): FunctionTool<Parameters, UserData, Result>;\n\n/**\n * Create a provider-defined tool.\n *\n * @param id - The ID of the tool.\n * @param config - The configuration of the tool.\n */\nexport function tool({\n  id,\n  config,\n}: {\n  id: string;\n  config: Record<string, unknown>;\n}): ProviderDefinedTool;\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function tool(tool: any): any {\n  if (tool.execute !== undefined) {\n    // Default parameters to z.object({}) if not provided\n    const parameters = tool.parameters ?? z.object({});\n\n    // if parameters is not zod object, throw an error\n    if (parameters instanceof ZodType && parameters._def.typeName !== 'ZodObject') {\n      throw new Error('Tool parameters must be a Zod object schema (z.object(...))');\n    }\n\n    if (!(parameters instanceof ZodObject) && !(typeof parameters === 'object')) {\n      throw new Error('Tool parameters must be a Zod object schema or a raw JSON schema');\n    }\n\n    return {\n      type: 'function',\n      description: tool.description,\n      parameters,\n      execute: tool.execute,\n      [TOOL_SYMBOL]: true,\n      [FUNCTION_TOOL_SYMBOL]: true,\n    };\n  }\n\n  if (tool.config !== undefined && tool.id !== undefined) {\n    return {\n      type: 'provider-defined',\n      id: tool.id,\n      config: tool.config,\n      [TOOL_SYMBOL]: true,\n      [PROVIDER_DEFINED_TOOL_SYMBOL]: true,\n    };\n  }\n\n  throw new Error('Invalid tool');\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isTool(tool: any): tool is Tool {\n  return tool && tool[TOOL_SYMBOL] === true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isFunctionTool(tool: any): tool is FunctionTool<any, any, any> {\n  const isTool = tool && tool[TOOL_SYMBOL] === true;\n  const isFunctionTool = tool[FUNCTION_TOOL_SYMBOL] === true;\n  return isTool && isFunctionTool;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isProviderDefinedTool(tool: any): tool is ProviderDefinedTool {\n  const isTool = tool && tool[TOOL_SYMBOL] === true;\n  const isProviderDefinedTool = tool[PROVIDER_DEFINED_TOOL_SYMBOL] === true;\n  return isTool && isProviderDefinedTool;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isToolError(error: any): error is ToolError {\n  return error && error[TOOL_ERROR_SYMBOL] === true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isAgentHandoff(handoff: any): handoff is AgentHandoff {\n  return handoff && handoff[HANDOFF_SYMBOL] === true;\n}\n"],"mappings":"AAIA,SAAS,WAAW,SAAS,SAAS;AAOtC,MAAM,cAAc,OAAO,MAAM;AACjC,MAAM,uBAAuB,OAAO,eAAe;AACnD,MAAM,+BAA+B,OAAO,uBAAuB;AACnE,MAAM,oBAAoB,OAAO,YAAY;AAC7C,MAAM,iBAAiB,OAAO,SAAS;AA2BhC,MAAM,kBAAkB,MAAM;AAAA,EACnC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AAEb,WAAO,eAAe,MAAM,mBAAmB;AAAA,MAC7C,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;AAiBO,SAAS,QAAQ,SAAwD;AAC9E,SAAO;AAAA,IACL,OAAO,QAAQ;AAAA,IACf,SAAS,QAAQ;AAAA,IACjB,CAAC,cAAc,GAAG;AAAA,EACpB;AACF;AAyHO,SAAS,KAAKA,OAAgB;AACnC,MAAIA,MAAK,YAAY,QAAW;AAE9B,UAAM,aAAaA,MAAK,cAAc,EAAE,OAAO,CAAC,CAAC;AAGjD,QAAI,sBAAsB,WAAW,WAAW,KAAK,aAAa,aAAa;AAC7E,YAAM,IAAI,MAAM,6DAA6D;AAAA,IAC/E;AAEA,QAAI,EAAE,sBAAsB,cAAc,EAAE,OAAO,eAAe,WAAW;AAC3E,YAAM,IAAI,MAAM,kEAAkE;AAAA,IACpF;AAEA,WAAO;AAAA,MACL,MAAM;AAAA,MACN,aAAaA,MAAK;AAAA,MAClB;AAAA,MACA,SAASA,MAAK;AAAA,MACd,CAAC,WAAW,GAAG;AAAA,MACf,CAAC,oBAAoB,GAAG;AAAA,IAC1B;AAAA,EACF;AAEA,MAAIA,MAAK,WAAW,UAAaA,MAAK,OAAO,QAAW;AACtD,WAAO;AAAA,MACL,MAAM;AAAA,MACN,IAAIA,MAAK;AAAA,MACT,QAAQA,MAAK;AAAA,MACb,CAAC,WAAW,GAAG;AAAA,MACf,CAAC,4BAA4B,GAAG;AAAA,IAClC;AAAA,EACF;AAEA,QAAM,IAAI,MAAM,cAAc;AAChC;AAGO,SAAS,OAAOA,OAAyB;AAC9C,SAAOA,SAAQA,MAAK,WAAW,MAAM;AACvC;AAGO,SAAS,eAAeA,OAAgD;AAC7E,QAAMC,UAASD,SAAQA,MAAK,WAAW,MAAM;AAC7C,QAAME,kBAAiBF,MAAK,oBAAoB,MAAM;AACtD,SAAOC,WAAUC;AACnB;AAGO,SAAS,sBAAsBF,OAAwC;AAC5E,QAAMC,UAASD,SAAQA,MAAK,WAAW,MAAM;AAC7C,QAAMG,yBAAwBH,MAAK,4BAA4B,MAAM;AACrE,SAAOC,WAAUE;AACnB;AAGO,SAAS,YAAY,OAAgC;AAC1D,SAAO,SAAS,MAAM,iBAAiB,MAAM;AAC/C;AAGO,SAAS,eAAeC,UAAuC;AACpE,SAAOA,YAAWA,SAAQ,cAAc,MAAM;AAChD;","names":["tool","isTool","isFunctionTool","isProviderDefinedTool","handoff"]}
+{"version":3,"sources":["../../src/llm/tool_context.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { JSONSchema7 } from 'json-schema';\nimport { z } from 'zod';\nimport type { Agent } from '../voice/agent.js';\nimport type { RunContext, UnknownUserData } from '../voice/run_context.js';\nimport { isZodObjectSchema, isZodSchema } from './zod-utils.js';\n\n// heavily inspired by Vercel AI's `tool()`:\n// https://github.com/vercel/ai/blob/3b0983b/packages/ai/core/tool/tool.ts\n\nconst TOOL_SYMBOL = Symbol('tool');\nconst FUNCTION_TOOL_SYMBOL = Symbol('function_tool');\nconst PROVIDER_DEFINED_TOOL_SYMBOL = Symbol('provider_defined_tool');\nconst TOOL_ERROR_SYMBOL = Symbol('tool_error');\nconst HANDOFF_SYMBOL = Symbol('handoff');\n\nexport type JSONValue = null | string | number | boolean | JSONObject | JSONArray;\n\nexport type JSONArray = JSONValue[];\n\nexport type JSONObject = {\n  [key: string]: JSONValue;\n};\n\n// Supports both Zod v3 and v4 schemas, as well as raw JSON schema\n// Adapted from Vercel AI SDK's FlexibleSchema approach\n// Source: https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts#L67-L70\n//\n// Vercel uses StandardSchemaV1 from @standard-schema/spec package.\n// We use a simpler approach by directly checking for schema properties:\n// - Zod v3: Has `_output` property\n// - Zod v4: Implements Standard Schema spec with `~standard` property\n// - JSON Schema: Plain object fallback\nexport type ToolInputSchema<T = JSONObject> =\n  | {\n      // Zod v3 schema - has _output property for type inference\n      _output: T;\n    }\n  | {\n      // Zod v4 schema (Standard Schema) - has ~standard property\n      '~standard': {\n        types?: { output: T };\n      };\n    }\n  | JSONSchema7;\n\n/**\n * Infer the output type from a ToolInputSchema.\n * Adapted from Vercel AI SDK's InferSchema type.\n * Source: https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts#L72-L79\n */\nexport type InferToolInput<T> = T extends { _output: infer O }\n  ? O\n  : T extends { '~standard': { types?: { output: infer O } } }\n    ? O\n    : any; // eslint-disable-line @typescript-eslint/no-explicit-any -- Fallback type for JSON Schema objects without type inference\n\nexport type ToolType = 'function' | 'provider-defined';\n\nexport type ToolChoice =\n  | 'auto'\n  | 'none'\n  | 'required'\n  | {\n      type: 'function';\n      function: {\n        name: string;\n      };\n    };\n\nexport class ToolError extends Error {\n  constructor(message: string) {\n    super(message);\n\n    Object.defineProperty(this, TOOL_ERROR_SYMBOL, {\n      value: true,\n    });\n  }\n}\n\nexport const ToolFlag = {\n  NONE: 0,\n  IGNORE_ON_ENTER: 1 << 0,\n} as const;\n\nexport type ToolFlag = (typeof ToolFlag)[keyof typeof ToolFlag];\n\nexport interface AgentHandoff {\n  /**\n   * The agent to handoff to.\n   */\n  agent: Agent;\n\n  /**\n   * The return value of the tool.\n   */\n  returns?: any; // eslint-disable-line @typescript-eslint/no-explicit-any\n\n  [HANDOFF_SYMBOL]: true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function handoff(options: { agent: Agent; returns?: any }): AgentHandoff {\n  return {\n    agent: options.agent,\n    returns: options.returns,\n    [HANDOFF_SYMBOL]: true,\n  };\n}\n\nexport interface ToolOptions<UserData = UnknownUserData> {\n  /**\n   * RunContext for the current agent session.\n   */\n  ctx: RunContext<UserData>;\n\n  /**\n   * The ID of the tool call.\n   */\n  toolCallId: string;\n\n  /**\n   * An optional abort signal that indicates that the overall operation should be aborted.\n   */\n  abortSignal?: AbortSignal;\n}\n\nexport type ToolExecuteFunction<\n  Parameters extends JSONObject,\n  UserData = UnknownUserData,\n  Result = unknown,\n> = (args: Parameters, opts: ToolOptions<UserData>) => Promise<Result>;\n\nexport interface Tool {\n  /**\n   * The type of the tool.\n   * @internal Either user-defined core tool or provider-defined tool.\n   */\n  type: ToolType;\n\n  [TOOL_SYMBOL]: true;\n}\n\n// TODO(AJS-112): support provider-defined tools\nexport interface ProviderDefinedTool extends Tool {\n  type: 'provider-defined';\n\n  /**\n   * The ID of the tool.\n   */\n  id: string;\n\n  /**\n   * The configuration of the tool.\n   */\n  config: Record<string, unknown>;\n\n  [PROVIDER_DEFINED_TOOL_SYMBOL]: true;\n}\n\nexport interface FunctionTool<\n  Parameters extends JSONObject,\n  UserData = UnknownUserData,\n  Result = unknown,\n> extends Tool {\n  type: 'function';\n\n  /**\n   * The description of the tool. Will be used by the language model to decide whether to use the tool.\n   */\n  description: string;\n\n  /**\n   * The schema of the input that the tool expects. The language model will use this to generate the input.\n   * It is also used to validate the output of the language model.\n   * Use descriptions to make the input understandable for the language model.\n   */\n  parameters: ToolInputSchema<Parameters>;\n\n  /**\n   * An async function that is called with the arguments from the tool call and produces a result.\n   * It also carries context about current session, user-defined data, and the tool call id, etc.\n   */\n  execute: ToolExecuteFunction<Parameters, UserData, Result>;\n\n  flags: number;\n\n  [FUNCTION_TOOL_SYMBOL]: true;\n}\n\n// TODO(AJS-112): support provider-defined tools in the future)\nexport type ToolContext<UserData = UnknownUserData> = {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic tool registry needs to accept any parameter/result types\n  [name: string]: FunctionTool<any, UserData, any>;\n};\n\nexport function isSameToolContext(ctx1: ToolContext, ctx2: ToolContext): boolean {\n  const toolNames = new Set(Object.keys(ctx1));\n  const toolNames2 = new Set(Object.keys(ctx2));\n\n  if (toolNames.size !== toolNames2.size) {\n    return false;\n  }\n\n  for (const name of toolNames) {\n    if (!toolNames2.has(name)) {\n      return false;\n    }\n\n    const tool1 = ctx1[name];\n    const tool2 = ctx2[name];\n\n    if (!tool1 || !tool2) {\n      return false;\n    }\n\n    if (tool1.description !== tool2.description) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\nexport function isSameToolChoice(choice1: ToolChoice | null, choice2: ToolChoice | null): boolean {\n  if (choice1 === choice2) {\n    return true;\n  }\n  if (choice1 === null || choice2 === null) {\n    return false;\n  }\n  if (typeof choice1 === 'string' && typeof choice2 === 'string') {\n    return choice1 === choice2;\n  }\n  if (typeof choice1 === 'object' && typeof choice2 === 'object') {\n    return choice1.type === choice2.type && choice1.function.name === choice2.function.name;\n  }\n  return false;\n}\n\n/**\n * Create a function tool with inferred parameters from the schema.\n */\nexport function tool<\n  Schema extends ToolInputSchema<any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- Generic constraint needs to accept any JSONObject type\n  UserData = UnknownUserData,\n  Result = unknown,\n>({\n  description,\n  parameters,\n  execute,\n  flags,\n}: {\n  description: string;\n  parameters: Schema;\n  execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;\n  flags?: number;\n}): FunctionTool<InferToolInput<Schema>, UserData, Result>;\n\n/**\n * Create a function tool without parameters.\n */\nexport function tool<UserData = UnknownUserData, Result = unknown>({\n  description,\n  execute,\n  flags,\n}: {\n  description: string;\n  parameters?: never;\n  execute: ToolExecuteFunction<Record<string, never>, UserData, Result>;\n  flags?: number;\n}): FunctionTool<Record<string, never>, UserData, Result>;\n\n/**\n * Create a provider-defined tool.\n *\n * @param id - The ID of the tool.\n * @param config - The configuration of the tool.\n */\nexport function tool({\n  id,\n  config,\n}: {\n  id: string;\n  config: Record<string, unknown>;\n}): ProviderDefinedTool;\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function tool(tool: any): any {\n  if (tool.execute !== undefined) {\n    // Default parameters to z.object({}) if not provided\n    const parameters = tool.parameters ?? z.object({});\n\n    // if parameters is a Zod schema, ensure it's an object schema\n    if (isZodSchema(parameters) && !isZodObjectSchema(parameters)) {\n      throw new Error('Tool parameters must be a Zod object schema (z.object(...))');\n    }\n\n    // Ensure parameters is either a Zod schema or a plain object (JSON schema)\n    if (!isZodSchema(parameters) && !(typeof parameters === 'object')) {\n      throw new Error('Tool parameters must be a Zod object schema or a raw JSON schema');\n    }\n\n    return {\n      type: 'function',\n      description: tool.description,\n      parameters,\n      execute: tool.execute,\n      flags: tool.flags ?? ToolFlag.NONE,\n      [TOOL_SYMBOL]: true,\n      [FUNCTION_TOOL_SYMBOL]: true,\n    };\n  }\n\n  if (tool.config !== undefined && tool.id !== undefined) {\n    return {\n      type: 'provider-defined',\n      id: tool.id,\n      config: tool.config,\n      [TOOL_SYMBOL]: true,\n      [PROVIDER_DEFINED_TOOL_SYMBOL]: true,\n    };\n  }\n\n  throw new Error('Invalid tool');\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isTool(tool: any): tool is Tool {\n  return tool && tool[TOOL_SYMBOL] === true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isFunctionTool(tool: any): tool is FunctionTool<any, any, any> {\n  const isTool = tool && tool[TOOL_SYMBOL] === true;\n  const isFunctionTool = tool[FUNCTION_TOOL_SYMBOL] === true;\n  return isTool && isFunctionTool;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isProviderDefinedTool(tool: any): tool is ProviderDefinedTool {\n  const isTool = tool && tool[TOOL_SYMBOL] === true;\n  const isProviderDefinedTool = tool[PROVIDER_DEFINED_TOOL_SYMBOL] === true;\n  return isTool && isProviderDefinedTool;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isToolError(error: any): error is ToolError {\n  return error && error[TOOL_ERROR_SYMBOL] === true;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function isAgentHandoff(handoff: any): handoff is AgentHandoff {\n  return handoff && handoff[HANDOFF_SYMBOL] === true;\n}\n"],"mappings":"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","names":["tool","isTool","isFunctionTool","isProviderDefinedTool","handoff"]}

package/dist/llm/tool_context.test.cjs

@@ -1,6 +1,30 @@
 "use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var import_vitest = require("vitest");
 var import_zod = require("zod");
+var z3 = __toESM(require("zod/v3"), 1);
+var z4 = __toESM(require("zod/v4"), 1);
 var import_tool_context = require("./tool_context.cjs");
 var import_utils = require("./utils.cjs");
 (0, import_vitest.describe)("Tool Context", () => {
@@ -136,6 +160,31 @@ var import_utils = require("./utils.cjs");
         const result = await simpleAction.execute({}, (0, import_utils.createToolOptions)("123"));
         (0, import_vitest.expect)(result).toBe("Action performed");
       });
+      (0, import_vitest.it)("should support .optional() fields in tool parameters", async () => {
+        const weatherTool = (0, import_tool_context.tool)({
+          description: "Get weather information",
+          parameters: import_zod.z.object({
+            location: import_zod.z.string().describe("The city or location").optional(),
+            units: import_zod.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})`;
+          }
+        });
+        (0, import_vitest.expect)(weatherTool.type).toBe("function");
+        (0, import_vitest.expect)(weatherTool.description).toBe("Get weather information");
+        const result1 = await weatherTool.execute(
+          { location: "London", units: "celsius" },
+          (0, import_utils.createToolOptions)("123")
+        );
+        (0, import_vitest.expect)(result1).toBe("Weather in London (celsius)");
+        const result2 = await weatherTool.execute({}, (0, import_utils.createToolOptions)("123"));
+        (0, import_vitest.expect)(result2).toBe("Weather in Unknown (celsius)");
+        const result3 = await weatherTool.execute({ location: "Paris" }, (0, import_utils.createToolOptions)("123"));
+        (0, import_vitest.expect)(result3).toBe("Weather in Paris (celsius)");
+      });
       (0, import_vitest.it)("should handle tools with context but no parameters", async () => {
         const greetUser = (0, import_tool_context.tool)({
           description: "Greet the current user",
@@ -157,6 +206,154 @@ var import_utils = require("./utils.cjs");
         (0, import_vitest.expect)(result).toBe("Tool call ID: test-id-456");
       });
     });
+    (0, import_vitest.describe)("Zod v3 and v4 compatibility", () => {
+      (0, import_vitest.it)("should work with Zod v3 schemas", async () => {
+        const v3Tool = (0, import_tool_context.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 },
+          (0, import_utils.createToolOptions)("v3-test")
+        );
+        (0, import_vitest.expect)(result).toBe("Test: 42");
+      });
+      (0, import_vitest.it)("should work with Zod v4 schemas", async () => {
+        const v4Tool = (0, import_tool_context.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 },
+          (0, import_utils.createToolOptions)("v4-test")
+        );
+        (0, import_vitest.expect)(result).toBe("Test: 42");
+      });
+      (0, import_vitest.it)("should handle v4 schemas with optional fields", async () => {
+        const v4Tool = (0, import_tool_context.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" }, (0, import_utils.createToolOptions)("test-1"));
+        (0, import_vitest.expect)(result1).toBe("Hello");
+        const result2 = await v4Tool.execute(
+          { required: "Hello", optional: "World" },
+          (0, import_utils.createToolOptions)("test-2")
+        );
+        (0, import_vitest.expect)(result2).toBe("Hello - World");
+      });
+      (0, import_vitest.it)("should handle v4 enum schemas", async () => {
+        const v4Tool = (0, import_tool_context.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" }, (0, import_utils.createToolOptions)("test-enum"));
+        (0, import_vitest.expect)(result).toBe("Selected color: blue");
+      });
+      (0, import_vitest.it)("should handle v4 array schemas", async () => {
+        const v4Tool = (0, import_tool_context.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"] },
+          (0, import_utils.createToolOptions)("test-array")
+        );
+        (0, import_vitest.expect)(result).toBe("Tags: nodejs, typescript, testing");
+      });
+      (0, import_vitest.it)("should handle v4 nested object schemas", async () => {
+        const v4Tool = (0, import_tool_context.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" } },
+          (0, import_utils.createToolOptions)("test-nested")
+        );
+        (0, import_vitest.expect)(result).toBe("John Doe (john@example.com)");
+      });
+    });
+    (0, import_vitest.describe)("oaiParams with v4 schemas", () => {
+      (0, import_vitest.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 = (0, import_utils.oaiParams)(schema);
+        (0, import_vitest.expect)(result.type).toBe("object");
+        (0, import_vitest.expect)(result.properties).toHaveProperty("name");
+        (0, import_vitest.expect)(result.properties).toHaveProperty("age");
+        (0, import_vitest.expect)(result.required).toContain("name");
+        (0, import_vitest.expect)(result.required).toContain("age");
+      });
+      (0, import_vitest.it)("should handle v4 optional fields", () => {
+        const schema = z4.object({
+          required: z4.string(),
+          optional: z4.string().optional()
+        });
+        const result = (0, import_utils.oaiParams)(schema);
+        (0, import_vitest.expect)(result.required).toContain("required");
+        (0, import_vitest.expect)(result.required).not.toContain("optional");
+      });
+      (0, import_vitest.it)("should handle v4 enum fields", () => {
+        var _a;
+        const schema = z4.object({
+          status: z4.enum(["pending", "approved", "rejected"])
+        });
+        const result = (0, import_utils.oaiParams)(schema);
+        const properties = result.properties;
+        (0, import_vitest.expect)((_a = properties.status) == null ? void 0 : _a.enum).toEqual(["pending", "approved", "rejected"]);
+      });
+      (0, import_vitest.it)("should handle v4 array fields", () => {
+        const schema = z4.object({
+          items: z4.array(z4.string())
+        });
+        const result = (0, import_utils.oaiParams)(schema);
+        const properties = result.properties;
+        (0, import_vitest.expect)(
+          properties.items && typeof properties.items === "object" ? properties.items.type : void 0
+        ).toBe("array");
+        (0, import_vitest.expect)(
+          properties.items && properties.items.items && typeof properties.items.items === "object" ? properties.items.items.type : void 0
+        ).toBe("string");
+      });
+    });
   });
 });
 //# sourceMappingURL=tool_context.test.cjs.map