kernl 0.1.1

package/src/tool/__tests__/fixtures.ts

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { Context } from "@/context";
+import { tool, HostedTool } from "../tool";
+
+/**
+ * Create a minimal mock context for testing
+ */
+export const mockContext = <T = any>(data?: T): Context<T> => {
+  return new Context<T>(data ?? ({} as T));
+};
+
+/**
+ * Simple string tool with no parameters
+ */
+export const simpleStringTool = tool({
+  id: "simple",
+  description: "A simple tool that echoes input",
+  parameters: undefined,
+  execute: async (ctx, input: string) => `Echo: ${input}`,
+});
+
+/**
+ * Tool with Zod schema validation
+ */
+export const zodTool = tool({
+  id: "zod-tool",
+  description: "Tool with Zod schema",
+  parameters: z.object({
+    name: z.string(),
+    age: z.number(),
+  }),
+  execute: async (ctx, { name, age }) => `${name} is ${age} years old`,
+});
+
+/**
+ * Tool that always throws an error
+ */
+export const errorTool = tool({
+  id: "error-tool",
+  description: "Always throws an error",
+  parameters: undefined,
+  execute: async () => {
+    throw new Error("Tool execution failed");
+  },
+});
+
+/**
+ * Tool with custom error handler
+ */
+export const customErrorTool = tool({
+  id: "custom-error-tool",
+  description: "Tool with custom error handler",
+  parameters: undefined,
+  execute: async () => {
+    throw new Error("Original error");
+  },
+  errorfn: (ctx, error) => {
+    return "Custom error message";
+  },
+});
+
+/**
+ * Tool requiring approval (boolean)
+ */
+export const approvalRequiredTool = tool({
+  id: "approval-tool",
+  description: "Requires approval",
+  parameters: undefined,
+  requiresApproval: true,
+  execute: async () => "executed",
+});
+
+/**
+ * Tool with conditional approval (function)
+ */
+export const conditionalApprovalTool = tool({
+  id: "conditional-approval",
+  description: "Conditionally requires approval",
+  parameters: z.object({
+    dangerous: z.boolean(),
+  }),
+  requiresApproval: async (ctx, input) => {
+    return input.dangerous === true;
+  },
+  execute: async (ctx, { dangerous }) => `Executed with dangerous=${dangerous}`,
+});
+
+/**
+ * Mock hosted tool (e.g., web_search)
+ */
+export const mockHostedTool = new HostedTool({
+  id: "web-search",
+  name: "Web Search",
+  providerData: {
+    provider: "anthropic",
+    capabilities: ["search", "fetch"],
+  },
+});
+
+/**
+ * Another mock hosted tool
+ */
+export const anotherHostedTool = new HostedTool({
+  id: "file-search",
+  name: "File Search",
+});

package/src/tool/__tests__/tool.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect } from "vitest";
+import { COMPLETED, FAILED } from "@kernl/protocol";
+import { tool } from "../tool";
+import {
+  mockContext,
+  simpleStringTool,
+  zodTool,
+  errorTool,
+  customErrorTool,
+  approvalRequiredTool,
+  conditionalApprovalTool,
+} from "./fixtures";
+
+describe("FunctionTool", () => {
+  describe("creation", () => {
+    it("should create tool with required config", () => {
+      const t = tool({
+        id: "test",
+        description: "Test tool",
+        parameters: undefined,
+        execute: async () => "result",
+      });
+
+      expect(t.id).toBe("test");
+      expect(t.description).toBe("Test tool");
+      expect(t.type).toBe("function");
+    });
+
+    it("should default mode to blocking", () => {
+      const t = tool({
+        id: "test",
+        description: "Test tool",
+        parameters: undefined,
+        execute: async () => "result",
+      });
+
+      expect(t.mode).toBe("blocking");
+    });
+
+    it("should accept custom mode", () => {
+      const t = tool({
+        id: "test",
+        description: "Test tool",
+        parameters: undefined,
+        mode: "async",
+        execute: async () => "result",
+      });
+
+      expect(t.mode).toBe("async");
+    });
+  });
+
+  describe("parameter parsing", () => {
+    it("should handle string input when no parameters schema", async () => {
+      const ctx = mockContext();
+      const result = await simpleStringTool.invoke(ctx, "hello");
+
+      expect(result.state).toBe(COMPLETED);
+      expect(result.result).toBe("Echo: hello");
+    });
+
+    it("should parse and validate with Zod schema", async () => {
+      const ctx = mockContext();
+      const input = JSON.stringify({ name: "Alice", age: 30 });
+      const result = await zodTool.invoke(ctx, input);
+
+      expect(result.state).toBe(COMPLETED);
+      expect(result.result).toBe("Alice is 30 years old");
+    });
+
+    it("should throw ModelBehaviorError on invalid JSON", async () => {
+      const ctx = mockContext();
+      const result = await zodTool.invoke(ctx, "not valid json");
+
+      expect(result.state).toBe(FAILED);
+      expect(result.error).toContain("Invalid JSON input for tool");
+    });
+
+    it("should throw ModelBehaviorError on schema validation failure", async () => {
+      const ctx = mockContext();
+      const input = JSON.stringify({ name: "Alice", age: "not a number" });
+      const result = await zodTool.invoke(ctx, input);
+
+      expect(result.state).toBe(FAILED);
+      expect(result.error).toContain("Invalid JSON input for tool");
+    });
+  });
+
+  describe("execution", () => {
+    it("should execute and return ToolResult with completed status", async () => {
+      const ctx = mockContext();
+      const result = await simpleStringTool.invoke(ctx, "test");
+
+      expect(result.state).toBe(COMPLETED);
+      expect(result.result).toBe("Echo: test");
+      expect(result.error).toBe(null);
+    });
+
+    it("should handle sync execute functions", async () => {
+      const syncTool = tool({
+        id: "sync",
+        description: "Sync tool",
+        parameters: undefined,
+        execute: (ctx, input: string) => `Sync: ${input}`,
+      });
+
+      const ctx = mockContext();
+      const result = await syncTool.invoke(ctx, "test");
+
+      expect(result.state).toBe(COMPLETED);
+      expect(result.result).toBe("Sync: test");
+    });
+
+    it("should handle async execute functions", async () => {
+      const asyncTool = tool({
+        id: "async",
+        description: "Async tool",
+        parameters: undefined,
+        execute: async (ctx, input: string) =>
+          Promise.resolve(`Async: ${input}`),
+      });
+
+      const ctx = mockContext();
+      const result = await asyncTool.invoke(ctx, "test");
+
+      expect(result.state).toBe(COMPLETED);
+      expect(result.result).toBe("Async: test");
+    });
+  });
+
+  describe("error handling", () => {
+    it("should return error ToolResult when execute throws", async () => {
+      const ctx = mockContext();
+      const result = await errorTool.invoke(ctx, "test");
+
+      expect(result.state).toBe(FAILED);
+      expect(result.result).toBe(undefined);
+      expect(result.error).toContain("Tool execution failed");
+    });
+
+    it("should use custom error function if provided", async () => {
+      const ctx = mockContext();
+      const result = await customErrorTool.invoke(ctx, "test");
+
+      expect(result.state).toBe(FAILED);
+      expect(result.error).toBe("Custom error message");
+    });
+
+    it("should use default error function if none provided", async () => {
+      const ctx = mockContext();
+      const result = await errorTool.invoke(ctx, "test");
+
+      expect(result.state).toBe(FAILED);
+      expect(result.error).toContain(
+        "An error occurred while running the tool",
+      );
+    });
+  });
+
+  describe("approval", () => {
+    it("should evaluate boolean requiresApproval", async () => {
+      const ctx = mockContext();
+      const requiresApproval = await approvalRequiredTool.requiresApproval(
+        ctx,
+        "test",
+      );
+
+      expect(requiresApproval).toBe(true);
+    });
+
+    it("should evaluate function requiresApproval", async () => {
+      const ctx = mockContext();
+
+      const dangerous = await conditionalApprovalTool.requiresApproval(ctx, {
+        dangerous: true,
+      });
+      const safe = await conditionalApprovalTool.requiresApproval(ctx, {
+        dangerous: false,
+      });
+
+      expect(dangerous).toBe(true);
+      expect(safe).toBe(false);
+    });
+  });
+
+  describe("isEnabled", () => {
+    it("should default to enabled", async () => {
+      const ctx = mockContext();
+      const enabled = await simpleStringTool.isEnabled(ctx, null as any);
+
+      expect(enabled).toBe(true);
+    });
+
+    it("should evaluate boolean isEnabled", async () => {
+      const disabledTool = tool({
+        id: "disabled",
+        description: "Disabled tool",
+        parameters: undefined,
+        isEnabled: false,
+        execute: async () => "result",
+      });
+
+      const ctx = mockContext();
+      const enabled = await disabledTool.isEnabled(ctx, null as any);
+
+      expect(enabled).toBe(false);
+    });
+
+    it("should evaluate function isEnabled with typed context", async () => {
+      interface MyContext {
+        enabled: boolean;
+      }
+
+      const conditionalTool = tool<MyContext>({
+        id: "conditional",
+        description: "Conditional tool",
+        parameters: undefined,
+        isEnabled: ({ context }) => {
+          return context.context.enabled === true;
+        },
+        execute: async () => "result",
+      });
+
+      const enabledCtx = mockContext<MyContext>({ enabled: true });
+      const disabledCtx = mockContext<MyContext>({ enabled: false });
+
+      expect(await conditionalTool.isEnabled(enabledCtx, null as any)).toBe(
+        true,
+      );
+      expect(await conditionalTool.isEnabled(disabledCtx, null as any)).toBe(
+        false,
+      );
+    });
+  });
+});

package/src/tool/__tests__/toolkit.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect } from "vitest";
+import { FunctionToolkit } from "../toolkit";
+import {
+  simpleStringTool,
+  zodTool,
+  errorTool,
+  mockHostedTool,
+  anotherHostedTool,
+} from "./fixtures";
+
+describe("FunctionToolkit", () => {
+  describe("constructor", () => {
+    it("should create empty toolkit with no tools", async () => {
+      const toolkit = new FunctionToolkit({ id: "empty", tools: [] });
+
+      expect(await toolkit.list()).toEqual([]);
+    });
+
+    it("should initialize with systools", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [mockHostedTool] });
+
+      expect(await toolkit.list()).toHaveLength(1);
+      expect(toolkit.get("web-search")).toBe(mockHostedTool);
+    });
+
+    it("should initialize with function tools", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [simpleStringTool, zodTool] });
+
+      expect(await toolkit.list()).toHaveLength(2);
+      expect(toolkit.get("simple")).toBe(simpleStringTool);
+      expect(toolkit.get("zod-tool")).toBe(zodTool);
+    });
+
+    it("should initialize with both systools and functions", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [mockHostedTool, simpleStringTool] });
+
+      expect(await toolkit.list()).toHaveLength(2);
+      expect(toolkit.get("web-search")).toBe(mockHostedTool);
+      expect(toolkit.get("simple")).toBe(simpleStringTool);
+    });
+  });
+
+  describe("get", () => {
+    it("should return undefined for non-existent tool", () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [] });
+
+      expect(toolkit.get("non-existent")).toBeUndefined();
+    });
+
+    it("should get systool by id", () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [mockHostedTool] });
+
+      expect(toolkit.get("web-search")).toBe(mockHostedTool);
+    });
+
+    it("should get function tool by id", () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [simpleStringTool] });
+
+      expect(toolkit.get("simple")).toBe(simpleStringTool);
+    });
+  });
+
+  describe("list", () => {
+    it("should return empty array for empty toolkit", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [] });
+
+      expect(await toolkit.list()).toEqual([]);
+    });
+
+    it("should list all systools", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [mockHostedTool, anotherHostedTool] });
+
+      const tools = await toolkit.list();
+      expect(tools).toHaveLength(2);
+      expect(tools).toContain(mockHostedTool);
+      expect(tools).toContain(anotherHostedTool);
+    });
+
+    it("should list all function tools", async () => {
+      const toolkit = new FunctionToolkit({
+        id: "test",
+        tools: [simpleStringTool, zodTool, errorTool],
+      });
+
+      const tools = await toolkit.list();
+      expect(tools).toHaveLength(3);
+      expect(tools).toContain(simpleStringTool);
+      expect(tools).toContain(zodTool);
+      expect(tools).toContain(errorTool);
+    });
+
+    it("should list both systools and function tools", async () => {
+      const toolkit = new FunctionToolkit({
+        id: "test",
+        tools: [mockHostedTool, simpleStringTool, zodTool],
+      });
+
+      const tools = await toolkit.list();
+      expect(tools).toHaveLength(3);
+      expect(tools).toContain(mockHostedTool);
+      expect(tools).toContain(simpleStringTool);
+      expect(tools).toContain(zodTool);
+    });
+  });
+
+  describe("serialize", () => {
+    it("should return empty array for empty toolkit", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [] });
+
+      expect((await toolkit.list()).map((tool: any) => tool.serialize())).toEqual([]);
+    });
+
+    it("should serialize function tools correctly", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [simpleStringTool] });
+
+      const serialized = (await toolkit.list()).map((tool: any) => tool.serialize());
+      expect(serialized).toHaveLength(1);
+      expect(serialized[0]).toEqual({
+        type: "function",
+        name: simpleStringTool.name,
+        description: simpleStringTool.description,
+        parameters: simpleStringTool.parameters,
+      });
+    });
+
+    it("should serialize hosted tools correctly", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [mockHostedTool] });
+
+      const serialized = (await toolkit.list()).map((tool: any) => tool.serialize());
+      expect(serialized).toHaveLength(1);
+      expect(serialized[0]).toEqual({
+        type: "hosted-tool",
+        id: mockHostedTool.id,
+        name: mockHostedTool.name,
+        providerData: mockHostedTool.providerData,
+      });
+    });
+
+    it("should serialize both function and hosted tools", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [mockHostedTool, simpleStringTool] });
+
+      const serialized = (await toolkit.list()).map((tool: any) => tool.serialize());
+      expect(serialized).toHaveLength(2);
+
+      // Check both tools are present (order not guaranteed with Map)
+      expect(serialized).toContainEqual({
+        type: "hosted-tool",
+        id: mockHostedTool.id,
+        name: mockHostedTool.name,
+        providerData: mockHostedTool.providerData,
+      });
+
+      expect(serialized).toContainEqual({
+        type: "function",
+        name: simpleStringTool.name,
+        description: simpleStringTool.description,
+        parameters: simpleStringTool.parameters,
+      });
+    });
+
+    it("should handle hosted tools without providerData", async () => {
+      const toolkit = new FunctionToolkit({ id: "test", tools: [anotherHostedTool] });
+
+      const serialized = (await toolkit.list()).map((tool: any) => tool.serialize());
+      expect(serialized).toHaveLength(1);
+      expect(serialized[0]).toEqual({
+        type: "hosted-tool",
+        id: anotherHostedTool.id,
+        name: anotherHostedTool.name,
+        providerData: undefined,
+      });
+    });
+  });
+});

package/src/tool/index.ts

@@ -0,0 +1,10 @@
+export { BaseTool, FunctionTool, HostedTool, tool } from "./tool";
+export { Toolkit, FunctionToolkit, MCPToolkit } from "./toolkit";
+export type {
+  Tool,
+  ToolResult,
+  FunctionToolkitConfig,
+  MCPToolkitConfig,
+  ToolkitFilter,
+  ToolkitFilterContext,
+} from "./types";