@livekit/agents 0.7.8 → 1.0.0-next.0

package/dist/llm/remote_chat_context.test.js

@@ -0,0 +1,224 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { ChatMessage } from "./chat_context.js";
+import { RemoteChatContext } from "./remote_chat_context.js";
+function createMessage(id, content) {
+  return new ChatMessage({ id, role: "user", content });
+}
+describe("RemoteChatContext", () => {
+  let context;
+  beforeEach(() => {
+    context = new RemoteChatContext();
+  });
+  describe("empty context", () => {
+    it("should return empty ChatContext", () => {
+      const chatCtx = context.toChatCtx();
+      expect(chatCtx.items).toHaveLength(0);
+    });
+    it("should return null for non-existent item", () => {
+      expect(context.get("nonexistent")).toBeNull();
+    });
+    it("should throw error when deleting non-existent item", () => {
+      expect(() => context.delete("nonexistent")).toThrow("Item with ID nonexistent not found");
+    });
+  });
+  describe("single item operations", () => {
+    it("should insert single item at head", () => {
+      const msg = createMessage("msg1", "Hello");
+      context.insert(void 0, msg);
+      expect(context.get("msg1")).toBeDefined();
+      expect(context.get("msg1").item).toBe(msg);
+      expect(context.toChatCtx().items).toEqual([msg]);
+    });
+    it("should delete single item", () => {
+      const msg = createMessage("msg1", "Hello");
+      context.insert(void 0, msg);
+      context.delete("msg1");
+      expect(context.get("msg1")).toBeNull();
+      expect(context.toChatCtx().items).toHaveLength(0);
+    });
+  });
+  describe("multiple item operations", () => {
+    it("should insert multiple items at head", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      context.insert(void 0, msg1);
+      context.insert(void 0, msg2);
+      context.insert(void 0, msg3);
+      expect(context.toChatCtx().items).toEqual([msg3, msg2, msg1]);
+    });
+    it("should insert items after specific nodes", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg1", msg3);
+      expect(context.toChatCtx().items).toEqual([msg1, msg3, msg2]);
+    });
+    it("should insert at tail", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg2", msg3);
+      expect(context.toChatCtx().items).toEqual([msg1, msg2, msg3]);
+    });
+  });
+  describe("deletion edge cases", () => {
+    it("should delete head node from multi-item list", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg2", msg3);
+      context.delete("msg1");
+      expect(context.toChatCtx().items).toEqual([msg2, msg3]);
+    });
+    it("should delete tail node from multi-item list", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg2", msg3);
+      context.delete("msg3");
+      expect(context.toChatCtx().items).toEqual([msg1, msg2]);
+    });
+    it("should delete middle node from multi-item list", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg2", msg3);
+      context.delete("msg2");
+      expect(context.toChatCtx().items).toEqual([msg1, msg3]);
+    });
+    it("should handle multiple deletions", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      const msg4 = createMessage("msg4", "Fourth");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg2", msg3);
+      context.insert("msg3", msg4);
+      context.delete("msg2");
+      context.delete("msg4");
+      expect(context.toChatCtx().items).toEqual([msg1, msg3]);
+      context.delete("msg1");
+      expect(context.toChatCtx().items).toEqual([msg3]);
+      context.delete("msg3");
+      expect(context.toChatCtx().items).toHaveLength(0);
+    });
+  });
+  describe("error conditions", () => {
+    it("should throw error when inserting duplicate ID", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg1", "Duplicate");
+      context.insert(void 0, msg1);
+      expect(() => context.insert(void 0, msg2)).toThrow("Item with ID msg1 already exists.");
+    });
+    it("should throw error when inserting after non-existent ID", () => {
+      const msg = createMessage("msg1", "Hello");
+      expect(() => context.insert("nonexistent", msg)).toThrow(
+        "previousItemId nonexistent not found"
+      );
+    });
+    it("should throw error when deleting non-existent ID", () => {
+      expect(() => context.delete("nonexistent")).toThrow("Item with ID nonexistent not found");
+    });
+  });
+  describe("complex scenarios", () => {
+    it("should handle interleaved inserts and deletes", () => {
+      const msg1 = createMessage("msg1", "A");
+      const msg2 = createMessage("msg2", "B");
+      const msg3 = createMessage("msg3", "C");
+      const msg4 = createMessage("msg4", "D");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.delete("msg1");
+      context.insert("msg2", msg3);
+      context.insert(void 0, msg4);
+      expect(context.toChatCtx().items).toEqual([msg4, msg2, msg3]);
+    });
+    it("should maintain correct pointers after complex operations", () => {
+      const msg1 = createMessage("msg1", "A");
+      const msg2 = createMessage("msg2", "B");
+      const msg3 = createMessage("msg3", "C");
+      const msg4 = createMessage("msg4", "D");
+      const msg5 = createMessage("msg5", "E");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg2", msg3);
+      context.insert("msg1", msg4);
+      context.insert("msg4", msg5);
+      expect(context.toChatCtx().items).toEqual([msg1, msg4, msg5, msg2, msg3]);
+      context.delete("msg4");
+      expect(context.toChatCtx().items).toEqual([msg1, msg5, msg2, msg3]);
+      context.delete("msg1");
+      expect(context.toChatCtx().items).toEqual([msg5, msg2, msg3]);
+      context.delete("msg2");
+      expect(context.toChatCtx().items).toEqual([msg5, msg3]);
+    });
+    it("should handle rebuilding from scratch", () => {
+      const messages = Array.from(
+        { length: 10 },
+        (_, i) => createMessage(`msg${i}`, `Content ${i}`)
+      );
+      for (const msg of messages) {
+        context.insert(void 0, msg);
+      }
+      expect(context.toChatCtx().items).toEqual([...messages].reverse());
+      for (let i = 0; i < 5; i++) {
+        context.delete(`msg${i}`);
+      }
+      const remaining = [...messages].reverse().filter((msg) => !["msg0", "msg1", "msg2", "msg3", "msg4"].includes(msg.id));
+      expect(context.toChatCtx().items).toEqual(remaining);
+    });
+  });
+  describe("get method", () => {
+    it("should return correct item for existing ID", () => {
+      const msg1 = createMessage("msg1", "Hello");
+      const msg2 = createMessage("msg2", "World");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      const retrieved = context.get("msg2");
+      expect(retrieved).toBeDefined();
+      expect(retrieved.item).toBe(msg2);
+    });
+    it("should return null for non-existent ID", () => {
+      const msg = createMessage("msg1", "Hello");
+      context.insert(void 0, msg);
+      expect(context.get("nonexistent")).toBeNull();
+    });
+  });
+  describe("toChatCtx method", () => {
+    it("should preserve order in ChatContext", () => {
+      const msg1 = createMessage("msg1", "First");
+      const msg2 = createMessage("msg2", "Second");
+      const msg3 = createMessage("msg3", "Third");
+      context.insert(void 0, msg1);
+      context.insert("msg1", msg2);
+      context.insert("msg2", msg3);
+      const chatCtx = context.toChatCtx();
+      expect(chatCtx.items).toEqual([msg1, msg2, msg3]);
+    });
+    it("should work with empty context", () => {
+      const chatCtx = context.toChatCtx();
+      expect(chatCtx.items).toHaveLength(0);
+    });
+    it("should create new ChatContext instance", () => {
+      const msg = createMessage("msg1", "Hello");
+      context.insert(void 0, msg);
+      const chatCtx1 = context.toChatCtx();
+      const chatCtx2 = context.toChatCtx();
+      expect(chatCtx1).not.toBe(chatCtx2);
+      expect(chatCtx1.items).toEqual(chatCtx2.items);
+    });
+  });
+});
+//# sourceMappingURL=remote_chat_context.test.js.map

package/dist/llm/remote_chat_context.test.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/llm/remote_chat_context.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { beforeEach, describe, expect, it } from 'vitest';\nimport { ChatMessage } from './chat_context.js';\nimport { RemoteChatContext } from './remote_chat_context.js';\n\nfunction createMessage(id: string, content: string): ChatMessage {\n  return new ChatMessage({ id, role: 'user', content });\n}\n\ndescribe('RemoteChatContext', () => {\n  let context: RemoteChatContext;\n\n  beforeEach(() => {\n    context = new RemoteChatContext();\n  });\n\n  describe('empty context', () => {\n    it('should return empty ChatContext', () => {\n      const chatCtx = context.toChatCtx();\n      expect(chatCtx.items).toHaveLength(0);\n    });\n\n    it('should return null for non-existent item', () => {\n      expect(context.get('nonexistent')).toBeNull();\n    });\n\n    it('should throw error when deleting non-existent item', () => {\n      expect(() => context.delete('nonexistent')).toThrow('Item with ID nonexistent not found');\n    });\n  });\n\n  describe('single item operations', () => {\n    it('should insert single item at head', () => {\n      const msg = createMessage('msg1', 'Hello');\n      context.insert(undefined, msg);\n\n      expect(context.get('msg1')).toBeDefined();\n      expect(context.get('msg1')!.item).toBe(msg);\n      expect(context.toChatCtx().items).toEqual([msg]);\n    });\n\n    it('should delete single item', () => {\n      const msg = createMessage('msg1', 'Hello');\n      context.insert(undefined, msg);\n      context.delete('msg1');\n\n      expect(context.get('msg1')).toBeNull();\n      expect(context.toChatCtx().items).toHaveLength(0);\n    });\n  });\n\n  describe('multiple item operations', () => {\n    it('should insert multiple items at head', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n\n      context.insert(undefined, msg1);\n      context.insert(undefined, msg2);\n      context.insert(undefined, msg3);\n\n      expect(context.toChatCtx().items).toEqual([msg3, msg2, msg1]);\n    });\n\n    it('should insert items after specific nodes', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg1', msg3);\n\n      expect(context.toChatCtx().items).toEqual([msg1, msg3, msg2]);\n    });\n\n    it('should insert at tail', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg2', msg3);\n\n      expect(context.toChatCtx().items).toEqual([msg1, msg2, msg3]);\n    });\n  });\n\n  describe('deletion edge cases', () => {\n    it('should delete head node from multi-item list', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg2', msg3);\n\n      context.delete('msg1');\n      expect(context.toChatCtx().items).toEqual([msg2, msg3]);\n    });\n\n    it('should delete tail node from multi-item list', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg2', msg3);\n\n      context.delete('msg3');\n      expect(context.toChatCtx().items).toEqual([msg1, msg2]);\n    });\n\n    it('should delete middle node from multi-item list', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg2', msg3);\n\n      context.delete('msg2');\n      expect(context.toChatCtx().items).toEqual([msg1, msg3]);\n    });\n\n    it('should handle multiple deletions', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n      const msg4 = createMessage('msg4', 'Fourth');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg2', msg3);\n      context.insert('msg3', msg4);\n\n      context.delete('msg2');\n      context.delete('msg4');\n      expect(context.toChatCtx().items).toEqual([msg1, msg3]);\n\n      context.delete('msg1');\n      expect(context.toChatCtx().items).toEqual([msg3]);\n\n      context.delete('msg3');\n      expect(context.toChatCtx().items).toHaveLength(0);\n    });\n  });\n\n  describe('error conditions', () => {\n    it('should throw error when inserting duplicate ID', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg1', 'Duplicate');\n\n      context.insert(undefined, msg1);\n      expect(() => context.insert(undefined, msg2)).toThrow('Item with ID msg1 already exists.');\n    });\n\n    it('should throw error when inserting after non-existent ID', () => {\n      const msg = createMessage('msg1', 'Hello');\n      expect(() => context.insert('nonexistent', msg)).toThrow(\n        'previousItemId nonexistent not found',\n      );\n    });\n\n    it('should throw error when deleting non-existent ID', () => {\n      expect(() => context.delete('nonexistent')).toThrow('Item with ID nonexistent not found');\n    });\n  });\n\n  describe('complex scenarios', () => {\n    it('should handle interleaved inserts and deletes', () => {\n      const msg1 = createMessage('msg1', 'A');\n      const msg2 = createMessage('msg2', 'B');\n      const msg3 = createMessage('msg3', 'C');\n      const msg4 = createMessage('msg4', 'D');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.delete('msg1');\n      context.insert('msg2', msg3);\n      context.insert(undefined, msg4);\n\n      expect(context.toChatCtx().items).toEqual([msg4, msg2, msg3]);\n    });\n\n    it('should maintain correct pointers after complex operations', () => {\n      const msg1 = createMessage('msg1', 'A');\n      const msg2 = createMessage('msg2', 'B');\n      const msg3 = createMessage('msg3', 'C');\n      const msg4 = createMessage('msg4', 'D');\n      const msg5 = createMessage('msg5', 'E');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg2', msg3);\n      context.insert('msg1', msg4);\n      context.insert('msg4', msg5);\n\n      expect(context.toChatCtx().items).toEqual([msg1, msg4, msg5, msg2, msg3]);\n\n      context.delete('msg4');\n      expect(context.toChatCtx().items).toEqual([msg1, msg5, msg2, msg3]);\n\n      context.delete('msg1');\n      expect(context.toChatCtx().items).toEqual([msg5, msg2, msg3]);\n\n      context.delete('msg2');\n      expect(context.toChatCtx().items).toEqual([msg5, msg3]);\n    });\n\n    it('should handle rebuilding from scratch', () => {\n      const messages = Array.from({ length: 10 }, (_, i) =>\n        createMessage(`msg${i}`, `Content ${i}`),\n      );\n\n      for (const msg of messages) {\n        context.insert(undefined, msg);\n      }\n\n      expect(context.toChatCtx().items).toEqual([...messages].reverse());\n\n      for (let i = 0; i < 5; i++) {\n        context.delete(`msg${i}`);\n      }\n\n      const remaining = [...messages]\n        .reverse()\n        .filter((msg) => !['msg0', 'msg1', 'msg2', 'msg3', 'msg4'].includes(msg.id));\n      expect(context.toChatCtx().items).toEqual(remaining);\n    });\n  });\n\n  describe('get method', () => {\n    it('should return correct item for existing ID', () => {\n      const msg1 = createMessage('msg1', 'Hello');\n      const msg2 = createMessage('msg2', 'World');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n\n      const retrieved = context.get('msg2');\n      expect(retrieved).toBeDefined();\n      expect(retrieved!.item).toBe(msg2);\n    });\n\n    it('should return null for non-existent ID', () => {\n      const msg = createMessage('msg1', 'Hello');\n      context.insert(undefined, msg);\n\n      expect(context.get('nonexistent')).toBeNull();\n    });\n  });\n\n  describe('toChatCtx method', () => {\n    it('should preserve order in ChatContext', () => {\n      const msg1 = createMessage('msg1', 'First');\n      const msg2 = createMessage('msg2', 'Second');\n      const msg3 = createMessage('msg3', 'Third');\n\n      context.insert(undefined, msg1);\n      context.insert('msg1', msg2);\n      context.insert('msg2', msg3);\n\n      const chatCtx = context.toChatCtx();\n      expect(chatCtx.items).toEqual([msg1, msg2, msg3]);\n    });\n\n    it('should work with empty context', () => {\n      const chatCtx = context.toChatCtx();\n      expect(chatCtx.items).toHaveLength(0);\n    });\n\n    it('should create new ChatContext instance', () => {\n      const msg = createMessage('msg1', 'Hello');\n      context.insert(undefined, msg);\n\n      const chatCtx1 = context.toChatCtx();\n      const chatCtx2 = context.toChatCtx();\n\n      expect(chatCtx1).not.toBe(chatCtx2);\n      expect(chatCtx1.items).toEqual(chatCtx2.items);\n    });\n  });\n});\n"],"mappings":"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","names":[]}

package/dist/llm/tool_context.cjs

@@ -0,0 +1,111 @@
+"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,
+  isTool: () => isTool,
+  isToolError: () => isToolError,
+  tool: () => tool
+});
+module.exports = __toCommonJS(tool_context_exports);
+var import_zod = require("zod");
+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 tool(tool2) {
+  if (tool2.execute !== void 0) {
+    const parameters = tool2.parameters ?? import_zod.z.object({});
+    if (parameters instanceof import_zod.ZodType && parameters._def.typeName !== "ZodObject") {
+      throw new Error("Tool parameters must be a Zod object schema (z.object(...))");
+    }
+    if (!(parameters instanceof import_zod.ZodObject) && !(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,
+  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 { 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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,iBAAsC;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,aAAE,OAAO,CAAC,CAAC;AAGjD,QAAI,sBAAsB,sBAAW,WAAW,KAAK,aAAa,aAAa;AAC7E,YAAM,IAAI,MAAM,6DAA6D;AAAA,IAC/E;AAEA,QAAI,EAAE,sBAAsB,yBAAc,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"]}

package/dist/llm/tool_context.d.cts

@@ -0,0 +1,125 @@
+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;
+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 extends JSONObject> = ZodObject<any, any, any, T, T> | JSONSchema7;
+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>;
+};
+/**
+ * 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.
+ */
+export declare function tool<Parameters extends JSONObject = Record<string, never>, UserData = UnknownUserData, Result = unknown>({ description, parameters, execute, }: {
+    description: string;
+    parameters?: ToolInputSchema<Parameters>;
+    execute: ToolExecuteFunction<Parameters, UserData, Result>;
+}): FunctionTool<Parameters, 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,125 @@
+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;
+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 extends JSONObject> = ZodObject<any, any, any, T, T> | JSONSchema7;
+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>;
+};
+/**
+ * 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.
+ */
+export declare function tool<Parameters extends JSONObject = Record<string, never>, UserData = UnknownUserData, Result = unknown>({ description, parameters, execute, }: {
+    description: string;
+    parameters?: ToolInputSchema<Parameters>;
+    execute: ToolExecuteFunction<Parameters, UserData, Result>;
+}): FunctionTool<Parameters, 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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"}