@livekit/agents 0.0.0-20260120144724

package/dist/llm/tool_context.cjs

@@ -0,0 +1,152 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tool_context_exports = {};
+__export(tool_context_exports, {
+  ToolError: () => ToolError,
+  handoff: () => handoff,
+  isAgentHandoff: () => isAgentHandoff,
+  isFunctionTool: () => isFunctionTool,
+  isProviderDefinedTool: () => isProviderDefinedTool,
+  isSameToolChoice: () => isSameToolChoice,
+  isSameToolContext: () => isSameToolContext,
+  isTool: () => isTool,
+  isToolError: () => isToolError,
+  tool: () => tool
+});
+module.exports = __toCommonJS(tool_context_exports);
+var import_zod = require("zod");
+var import_zod_utils = require("./zod-utils.cjs");
+const TOOL_SYMBOL = Symbol("tool");
+const FUNCTION_TOOL_SYMBOL = Symbol("function_tool");
+const PROVIDER_DEFINED_TOOL_SYMBOL = Symbol("provider_defined_tool");
+const TOOL_ERROR_SYMBOL = Symbol("tool_error");
+const HANDOFF_SYMBOL = Symbol("handoff");
+class ToolError extends Error {
+  constructor(message) {
+    super(message);
+    Object.defineProperty(this, TOOL_ERROR_SYMBOL, {
+      value: true
+    });
+  }
+}
+function handoff(options) {
+  return {
+    agent: options.agent,
+    returns: options.returns,
+    [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 ?? import_zod.z.object({});
+    if ((0, import_zod_utils.isZodSchema)(parameters) && !(0, import_zod_utils.isZodObjectSchema)(parameters)) {
+      throw new Error("Tool parameters must be a Zod object schema (z.object(...))");
+    }
+    if (!(0, import_zod_utils.isZodSchema)(parameters) && !(typeof parameters === "object")) {
+      throw new Error("Tool parameters must be a Zod object schema or a raw JSON schema");
+    }
+    return {
+      type: "function",
+      description: tool2.description,
+      parameters,
+      execute: tool2.execute,
+      [TOOL_SYMBOL]: true,
+      [FUNCTION_TOOL_SYMBOL]: true
+    };
+  }
+  if (tool2.config !== void 0 && tool2.id !== void 0) {
+    return {
+      type: "provider-defined",
+      id: tool2.id,
+      config: tool2.config,
+      [TOOL_SYMBOL]: true,
+      [PROVIDER_DEFINED_TOOL_SYMBOL]: true
+    };
+  }
+  throw new Error("Invalid tool");
+}
+function isTool(tool2) {
+  return tool2 && tool2[TOOL_SYMBOL] === true;
+}
+function isFunctionTool(tool2) {
+  const isTool2 = tool2 && tool2[TOOL_SYMBOL] === true;
+  const isFunctionTool2 = tool2[FUNCTION_TOOL_SYMBOL] === true;
+  return isTool2 && isFunctionTool2;
+}
+function isProviderDefinedTool(tool2) {
+  const isTool2 = tool2 && tool2[TOOL_SYMBOL] === true;
+  const isProviderDefinedTool2 = tool2[PROVIDER_DEFINED_TOOL_SYMBOL] === true;
+  return isTool2 && isProviderDefinedTool2;
+}
+function isToolError(error) {
+  return error && error[TOOL_ERROR_SYMBOL] === true;
+}
+function isAgentHandoff(handoff2) {
+  return handoff2 && handoff2[HANDOFF_SYMBOL] === true;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ToolError,
+  handoff,
+  isAgentHandoff,
+  isFunctionTool,
+  isProviderDefinedTool,
+  isSameToolChoice,
+  isSameToolContext,
+  isTool,
+  isToolError,
+  tool
+});
+//# sourceMappingURL=tool_context.cjs.map

package/dist/llm/tool_context.cjs.map

@@ -0,0 +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 { 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 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  // 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}: {\n  description: string;\n  parameters: Schema;\n  execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;\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}: {\n  description: string;\n  parameters?: never;\n  execute: ToolExecuteFunction<Record<string, never>, UserData, Result>;\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      [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.d.cts

@@ -0,0 +1,153 @@
+import type { JSONSchema7 } from 'json-schema';
+import type { Agent } from '../voice/agent.js';
+import type { RunContext, UnknownUserData } from '../voice/run_context.js';
+declare const TOOL_SYMBOL: unique symbol;
+declare const FUNCTION_TOOL_SYMBOL: unique symbol;
+declare const PROVIDER_DEFINED_TOOL_SYMBOL: unique symbol;
+declare const HANDOFF_SYMBOL: unique symbol;
+export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+export type JSONArray = JSONValue[];
+export type JSONObject = {
+    [key: string]: JSONValue;
+};
+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';
+    function: {
+        name: string;
+    };
+};
+export declare class ToolError extends Error {
+    constructor(message: string);
+}
+export interface AgentHandoff {
+    /**
+     * The agent to handoff to.
+     */
+    agent: Agent;
+    /**
+     * The return value of the tool.
+     */
+    returns?: any;
+    [HANDOFF_SYMBOL]: true;
+}
+export declare function handoff(options: {
+    agent: Agent;
+    returns?: any;
+}): AgentHandoff;
+export interface ToolOptions<UserData = UnknownUserData> {
+    /**
+     * RunContext for the current agent session.
+     */
+    ctx: RunContext<UserData>;
+    /**
+     * The ID of the tool call.
+     */
+    toolCallId: string;
+    /**
+     * An optional abort signal that indicates that the overall operation should be aborted.
+     */
+    abortSignal?: AbortSignal;
+}
+export type ToolExecuteFunction<Parameters extends JSONObject, UserData = UnknownUserData, Result = unknown> = (args: Parameters, opts: ToolOptions<UserData>) => Promise<Result>;
+export interface Tool {
+    /**
+     * The type of the tool.
+     * @internal Either user-defined core tool or provider-defined tool.
+     */
+    type: ToolType;
+    [TOOL_SYMBOL]: true;
+}
+export interface ProviderDefinedTool extends Tool {
+    type: 'provider-defined';
+    /**
+     * The ID of the tool.
+     */
+    id: string;
+    /**
+     * The configuration of the tool.
+     */
+    config: Record<string, unknown>;
+    [PROVIDER_DEFINED_TOOL_SYMBOL]: true;
+}
+export interface FunctionTool<Parameters extends JSONObject, UserData = UnknownUserData, Result = unknown> extends Tool {
+    type: 'function';
+    /**
+     * The description of the tool. Will be used by the language model to decide whether to use the tool.
+     */
+    description: string;
+    /**
+     * The schema of the input that the tool expects. The language model will use this to generate the input.
+     * It is also used to validate the output of the language model.
+     * Use descriptions to make the input understandable for the language model.
+     */
+    parameters: ToolInputSchema<Parameters>;
+    /**
+     * An async function that is called with the arguments from the tool call and produces a result.
+     * It also carries context about current session, user-defined data, and the tool call id, etc.
+     */
+    execute: ToolExecuteFunction<Parameters, UserData, Result>;
+    [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 with inferred parameters from the schema.
+ */
+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, }: {
+    description: string;
+    parameters: Schema;
+    execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;
+}): FunctionTool<InferToolInput<Schema>, UserData, Result>;
+/**
+ * Create a function tool without parameters.
+ */
+export declare 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.
+ *
+ * @param id - The ID of the tool.
+ * @param config - The configuration of the tool.
+ */
+export declare function tool({ id, config, }: {
+    id: string;
+    config: Record<string, unknown>;
+}): ProviderDefinedTool;
+export declare function isTool(tool: any): tool is Tool;
+export declare function isFunctionTool(tool: any): tool is FunctionTool<any, any, any>;
+export declare function isProviderDefinedTool(tool: any): tool is ProviderDefinedTool;
+export declare function isToolError(error: any): error is ToolError;
+export declare function isAgentHandoff(handoff: any): handoff is AgentHandoff;
+export {};
+//# sourceMappingURL=tool_context.d.ts.map

package/dist/llm/tool_context.d.ts

@@ -0,0 +1,153 @@
+import type { JSONSchema7 } from 'json-schema';
+import type { Agent } from '../voice/agent.js';
+import type { RunContext, UnknownUserData } from '../voice/run_context.js';
+declare const TOOL_SYMBOL: unique symbol;
+declare const FUNCTION_TOOL_SYMBOL: unique symbol;
+declare const PROVIDER_DEFINED_TOOL_SYMBOL: unique symbol;
+declare const HANDOFF_SYMBOL: unique symbol;
+export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+export type JSONArray = JSONValue[];
+export type JSONObject = {
+    [key: string]: JSONValue;
+};
+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';
+    function: {
+        name: string;
+    };
+};
+export declare class ToolError extends Error {
+    constructor(message: string);
+}
+export interface AgentHandoff {
+    /**
+     * The agent to handoff to.
+     */
+    agent: Agent;
+    /**
+     * The return value of the tool.
+     */
+    returns?: any;
+    [HANDOFF_SYMBOL]: true;
+}
+export declare function handoff(options: {
+    agent: Agent;
+    returns?: any;
+}): AgentHandoff;
+export interface ToolOptions<UserData = UnknownUserData> {
+    /**
+     * RunContext for the current agent session.
+     */
+    ctx: RunContext<UserData>;
+    /**
+     * The ID of the tool call.
+     */
+    toolCallId: string;
+    /**
+     * An optional abort signal that indicates that the overall operation should be aborted.
+     */
+    abortSignal?: AbortSignal;
+}
+export type ToolExecuteFunction<Parameters extends JSONObject, UserData = UnknownUserData, Result = unknown> = (args: Parameters, opts: ToolOptions<UserData>) => Promise<Result>;
+export interface Tool {
+    /**
+     * The type of the tool.
+     * @internal Either user-defined core tool or provider-defined tool.
+     */
+    type: ToolType;
+    [TOOL_SYMBOL]: true;
+}
+export interface ProviderDefinedTool extends Tool {
+    type: 'provider-defined';
+    /**
+     * The ID of the tool.
+     */
+    id: string;
+    /**
+     * The configuration of the tool.
+     */
+    config: Record<string, unknown>;
+    [PROVIDER_DEFINED_TOOL_SYMBOL]: true;
+}
+export interface FunctionTool<Parameters extends JSONObject, UserData = UnknownUserData, Result = unknown> extends Tool {
+    type: 'function';
+    /**
+     * The description of the tool. Will be used by the language model to decide whether to use the tool.
+     */
+    description: string;
+    /**
+     * The schema of the input that the tool expects. The language model will use this to generate the input.
+     * It is also used to validate the output of the language model.
+     * Use descriptions to make the input understandable for the language model.
+     */
+    parameters: ToolInputSchema<Parameters>;
+    /**
+     * An async function that is called with the arguments from the tool call and produces a result.
+     * It also carries context about current session, user-defined data, and the tool call id, etc.
+     */
+    execute: ToolExecuteFunction<Parameters, UserData, Result>;
+    [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 with inferred parameters from the schema.
+ */
+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, }: {
+    description: string;
+    parameters: Schema;
+    execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;
+}): FunctionTool<InferToolInput<Schema>, UserData, Result>;
+/**
+ * Create a function tool without parameters.
+ */
+export declare 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.
+ *
+ * @param id - The ID of the tool.
+ * @param config - The configuration of the tool.
+ */
+export declare function tool({ id, config, }: {
+    id: string;
+    config: Record<string, unknown>;
+}): ProviderDefinedTool;
+export declare function isTool(tool: any): tool is Tool;
+export declare function isFunctionTool(tool: any): tool is FunctionTool<any, any, any>;
+export declare function isProviderDefinedTool(tool: any): tool is ProviderDefinedTool;
+export declare function isToolError(error: any): error is ToolError;
+export declare function isAgentHandoff(handoff: any): handoff is AgentHandoff;
+export {};
+//# sourceMappingURL=tool_context.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,119 @@
+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");
+const TOOL_ERROR_SYMBOL = Symbol("tool_error");
+const HANDOFF_SYMBOL = Symbol("handoff");
+class ToolError extends Error {
+  constructor(message) {
+    super(message);
+    Object.defineProperty(this, TOOL_ERROR_SYMBOL, {
+      value: true
+    });
+  }
+}
+function handoff(options) {
+  return {
+    agent: options.agent,
+    returns: options.returns,
+    [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 (isZodSchema(parameters) && !isZodObjectSchema(parameters)) {
+      throw new Error("Tool parameters must be a Zod object schema (z.object(...))");
+    }
+    if (!isZodSchema(parameters) && !(typeof parameters === "object")) {
+      throw new Error("Tool parameters must be a Zod object schema or a raw JSON schema");
+    }
+    return {
+      type: "function",
+      description: tool2.description,
+      parameters,
+      execute: tool2.execute,
+      [TOOL_SYMBOL]: true,
+      [FUNCTION_TOOL_SYMBOL]: true
+    };
+  }
+  if (tool2.config !== void 0 && tool2.id !== void 0) {
+    return {
+      type: "provider-defined",
+      id: tool2.id,
+      config: tool2.config,
+      [TOOL_SYMBOL]: true,
+      [PROVIDER_DEFINED_TOOL_SYMBOL]: true
+    };
+  }
+  throw new Error("Invalid tool");
+}
+function isTool(tool2) {
+  return tool2 && tool2[TOOL_SYMBOL] === true;
+}
+function isFunctionTool(tool2) {
+  const isTool2 = tool2 && tool2[TOOL_SYMBOL] === true;
+  const isFunctionTool2 = tool2[FUNCTION_TOOL_SYMBOL] === true;
+  return isTool2 && isFunctionTool2;
+}
+function isProviderDefinedTool(tool2) {
+  const isTool2 = tool2 && tool2[TOOL_SYMBOL] === true;
+  const isProviderDefinedTool2 = tool2[PROVIDER_DEFINED_TOOL_SYMBOL] === true;
+  return isTool2 && isProviderDefinedTool2;
+}
+function isToolError(error) {
+  return error && error[TOOL_ERROR_SYMBOL] === true;
+}
+function isAgentHandoff(handoff2) {
+  return handoff2 && handoff2[HANDOFF_SYMBOL] === true;
+}
+export {
+  ToolError,
+  handoff,
+  isAgentHandoff,
+  isFunctionTool,
+  isProviderDefinedTool,
+  isSameToolChoice,
+  isSameToolContext,
+  isTool,
+  isToolError,
+  tool
+};
+//# sourceMappingURL=tool_context.js.map

package/dist/llm/tool_context.js.map

@@ -0,0 +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 { 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 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  // 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}: {\n  description: string;\n  parameters: Schema;\n  execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;\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}: {\n  description: string;\n  parameters?: never;\n  execute: ToolExecuteFunction<Record<string, never>, UserData, Result>;\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      [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"]}