kernl 0.1.1

package/dist/mcp/__tests__/integration.test.js

@@ -0,0 +1,360 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import path from "path";
+import { MCPServerStdio } from "../stdio";
+import { MCPToolkit } from "../../tool/toolkit";
+import { FunctionToolkit } from "../../tool/toolkit";
+import { Agent } from "../../agent";
+import { Context } from "../../context";
+import { tool } from "../../tool";
+import { z } from "zod";
+import { createMCPToolStaticFilter } from "../utils";
+const TEST_SERVER = path.join(__dirname, "fixtures", "server.ts");
+describe("MCP Integration Tests", () => {
+    describe("MCPToolkit Integration", () => {
+        let server;
+        let toolkit;
+        beforeEach(() => {
+            server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            toolkit = new MCPToolkit({
+                id: "test-toolkit",
+                server,
+            });
+        });
+        afterEach(async () => {
+            await toolkit.destroy();
+        });
+        it("should wrap server correctly", () => {
+            expect(toolkit.id).toBe("test-toolkit");
+            expect(toolkit).toBeDefined();
+        });
+        it("should connect lazily on first list()", async () => {
+            // Server should not be connected yet
+            // (we can't directly test this without exposing internals)
+            const tools = await toolkit.list();
+            // Should have successfully fetched tools
+            expect(tools.length).toBeGreaterThan(0);
+            expect(tools.length).toBe(6); // Our test server has 6 tools
+        });
+        it("should convert MCPTools to Tools", async () => {
+            const tools = await toolkit.list();
+            // Verify they are FunctionTools with proper structure
+            for (const tool of tools) {
+                expect(tool.id).toBeDefined();
+                expect(tool.name).toBeDefined();
+                expect(tool.type).toBe("function");
+                // MCP tools are converted to FunctionTools
+                if (tool.type === "function") {
+                    expect(tool.description).toBeDefined();
+                    expect(tool.invoke).toBeDefined();
+                }
+            }
+            // Check specific tool
+            const addTool = tools.find((t) => t.id === "add");
+            expect(addTool).toBeDefined();
+            if (addTool && addTool.type === "function") {
+                expect(addTool.description).toBe("Add two numbers");
+            }
+        });
+        it("should cache converted tools", async () => {
+            const tools1 = await toolkit.list();
+            const tools2 = await toolkit.list();
+            // Should return the same tool objects (cached)
+            expect(tools1).toEqual(tools2);
+            expect(tools1[0]).toBe(tools2[0]); // Same reference
+        });
+        it("should return tools from cache via get()", async () => {
+            // First, list to populate cache
+            await toolkit.list();
+            // Then get specific tool
+            const addTool = toolkit.get("add");
+            expect(addTool).toBeDefined();
+            expect(addTool.id).toBe("add");
+            if (addTool && addTool.type === "function") {
+                expect(addTool.description).toBe("Add two numbers");
+            }
+        });
+        it("should close server connection on destroy()", async () => {
+            // First connect
+            await toolkit.list();
+            // Destroy
+            await toolkit.destroy();
+            // Trying to list again should reconnect
+            const tools = await toolkit.list();
+            expect(tools.length).toBe(6);
+            await toolkit.destroy();
+        });
+    });
+    describe("Two-Layer Filtering", () => {
+        it("should apply server-level filter to block tools", async () => {
+            const server = new MCPServerStdio({
+                id: "filtered-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+                toolFilter: createMCPToolStaticFilter({
+                    blocked: ["divide", "multiply"],
+                }),
+            });
+            const toolkit = new MCPToolkit({
+                id: "filtered-toolkit",
+                server,
+            });
+            const tools = await toolkit.list();
+            // Should have 4 tools (6 - 2 blocked)
+            expect(tools.length).toBe(4);
+            expect(tools.find((t) => t.id === "divide")).toBeUndefined();
+            expect(tools.find((t) => t.id === "multiply")).toBeUndefined();
+            expect(tools.find((t) => t.id === "add")).toBeDefined();
+            await toolkit.destroy();
+        });
+        it("should apply toolkit-level filter to block tools", async () => {
+            const server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            const toolkit = new MCPToolkit({
+                id: "filtered-toolkit",
+                server,
+                filter: async (ctx, tool) => {
+                    // Block all string tools
+                    return !["echo", "uppercase", "reverse"].includes(tool.id);
+                },
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [toolkit],
+            });
+            const context = new Context({});
+            const tools = await toolkit.list(context);
+            // Should have 3 math tools only
+            expect(tools.length).toBe(3);
+            expect(tools.find((t) => t.id === "add")).toBeDefined();
+            expect(tools.find((t) => t.id === "echo")).toBeUndefined();
+            await toolkit.destroy();
+        });
+        it("should combine server and toolkit filters with AND logic", async () => {
+            const server = new MCPServerStdio({
+                id: "filtered-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+                toolFilter: createMCPToolStaticFilter({
+                    // Only allow math tools at server level
+                    allowed: ["add", "multiply", "divide"],
+                }),
+            });
+            const toolkit = new MCPToolkit({
+                id: "filtered-toolkit",
+                server,
+                // At toolkit level, block multiply
+                filter: async (ctx, tool) => tool.id !== "multiply",
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [toolkit],
+            });
+            const context = new Context({});
+            const tools = await toolkit.list(context);
+            // Should have only add and divide (multiply blocked by toolkit filter)
+            expect(tools.length).toBe(2);
+            expect(tools.find((t) => t.id === "add")).toBeDefined();
+            expect(tools.find((t) => t.id === "divide")).toBeDefined();
+            expect(tools.find((t) => t.id === "multiply")).toBeUndefined();
+            expect(tools.find((t) => t.id === "echo")).toBeUndefined();
+            await toolkit.destroy();
+        });
+        it("should receive correct context in toolkit filter", async () => {
+            const server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            let receivedContext = null;
+            const toolkit = new MCPToolkit({
+                id: "test-toolkit",
+                server,
+                filter: async (ctx, tool) => {
+                    receivedContext = ctx;
+                    return true;
+                },
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [toolkit],
+            });
+            const context = new Context({ userId: "test-user" });
+            await toolkit.list(context);
+            // Verify context was passed correctly
+            expect(receivedContext).toBeDefined();
+            expect(receivedContext.context).toBe(context);
+            expect(receivedContext.agent).toBe(agent);
+            expect(receivedContext.toolkitId).toBe("test-toolkit");
+            await toolkit.destroy();
+        });
+    });
+    describe("Agent Integration", () => {
+        it("should include MCP tools in agent.tools()", async () => {
+            const server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            const mcpToolkit = new MCPToolkit({
+                id: "mcp-toolkit",
+                server,
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [mcpToolkit],
+            });
+            const context = new Context({});
+            const tools = await agent.tools(context);
+            expect(tools.length).toBe(6);
+            expect(tools.find((t) => t.id === "add")).toBeDefined();
+            expect(tools.find((t) => t.id === "echo")).toBeDefined();
+            await mcpToolkit.destroy();
+        });
+        it("should find MCP tools via agent.tool()", async () => {
+            const server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            const mcpToolkit = new MCPToolkit({
+                id: "mcp-toolkit",
+                server,
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [mcpToolkit],
+            });
+            // Populate toolkit cache
+            const context = new Context({});
+            await agent.tools(context);
+            // Now get specific tool
+            const addTool = agent.tool("add");
+            expect(addTool).toBeDefined();
+            expect(addTool.id).toBe("add");
+            await mcpToolkit.destroy();
+        });
+        it("should execute MCP tools through tool.invoke()", async () => {
+            const server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            const mcpToolkit = new MCPToolkit({
+                id: "mcp-toolkit",
+                server,
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [mcpToolkit],
+            });
+            const context = new Context({});
+            await agent.tools(context);
+            const addTool = agent.tool("add");
+            expect(addTool).toBeDefined();
+            // Execute the tool
+            if (addTool && addTool.type === "function") {
+                const result = await addTool.invoke(context, JSON.stringify({ a: 5, b: 3 }));
+                expect(result.state).toBe("completed");
+                expect(result.result).toEqual({ type: "text", text: "8" });
+            }
+            await mcpToolkit.destroy();
+        });
+        it("should work with multiple toolkits together", async () => {
+            const server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            const mcpToolkit = new MCPToolkit({
+                id: "mcp-toolkit",
+                server,
+            });
+            // Create a function toolkit
+            const localTool = tool({
+                id: "local_tool",
+                name: "local_tool",
+                description: "A local tool",
+                parameters: z.object({
+                    input: z.string(),
+                }),
+                execute: async (context, params) => {
+                    return `Local: ${params.input}`;
+                },
+            });
+            const functionToolkit = new FunctionToolkit({
+                id: "function-toolkit",
+                tools: [localTool],
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [mcpToolkit, functionToolkit],
+            });
+            const context = new Context({});
+            const tools = await agent.tools(context);
+            // Should have 7 tools (6 MCP + 1 local)
+            expect(tools.length).toBe(7);
+            expect(tools.find((t) => t.id === "add")).toBeDefined();
+            expect(tools.find((t) => t.id === "local_tool")).toBeDefined();
+            await mcpToolkit.destroy();
+        });
+        it("should detect duplicate tool IDs across toolkits", async () => {
+            const server = new MCPServerStdio({
+                id: "test-server",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            const mcpToolkit = new MCPToolkit({
+                id: "mcp-toolkit",
+                server,
+            });
+            // Create a function toolkit with a duplicate ID
+            const duplicateTool = tool({
+                id: "add", // Same as MCP tool
+                name: "add",
+                description: "Duplicate add tool",
+                parameters: z.object({
+                    a: z.number(),
+                    b: z.number(),
+                }),
+                execute: async (context, params) => {
+                    return params.a + params.b;
+                },
+            });
+            const functionToolkit = new FunctionToolkit({
+                id: "function-toolkit",
+                tools: [duplicateTool],
+            });
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test Agent",
+                instructions: "Test",
+                toolkits: [mcpToolkit, functionToolkit],
+            });
+            const context = new Context({});
+            // Should throw error about duplicate tool IDs
+            await expect(agent.tools(context)).rejects.toThrow(/Duplicate tool IDs found/);
+            await mcpToolkit.destroy();
+        });
+    });
+});

package/dist/mcp/__tests__/stdio.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stdio.test.d.ts.map

package/dist/mcp/__tests__/stdio.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.test.d.ts","sourceRoot":"","sources":["../../../src/mcp/__tests__/stdio.test.ts"],"names":[],"mappings":""}

package/dist/mcp/__tests__/stdio.test.js

@@ -0,0 +1,180 @@
+import { describe, it, expect } from "vitest";
+import { MCPServerStdio } from "../stdio";
+import { withMCPServer, createMCPServer } from "./fixtures/utils";
+import path from "path";
+const TEST_SERVER = path.join(__dirname, "fixtures", "server.ts");
+describe("MCPServerStdio", () => {
+    describe("Connection Lifecycle", () => {
+        it("should connect successfully to a server", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                expect(server).toBeDefined();
+                // If we get here, connection was successful
+            });
+        });
+        it("should handle connection failure gracefully", async () => {
+            const server = createMCPServer("/nonexistent/server.ts");
+            await expect(server.connect()).rejects.toThrow();
+        });
+        it("should close connection cleanly", async () => {
+            const server = createMCPServer(TEST_SERVER);
+            await server.connect();
+            await server.close();
+            // Attempting to call a tool after close should fail
+            await expect(server.callTool("add", { a: 1, b: 2 })).rejects.toThrow();
+        });
+        it("should allow reconnection after close", async () => {
+            const server = createMCPServer(TEST_SERVER);
+            await server.connect();
+            await server.close();
+            await server.connect();
+            const tools = await server.listTools();
+            expect(tools.length).toBeGreaterThan(0);
+            await server.close();
+        });
+    });
+    describe("Tool Discovery", () => {
+        it("should list tools after connect", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                const tools = await server.listTools();
+                expect(tools).toHaveLength(6);
+                expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining([
+                    "add",
+                    "multiply",
+                    "divide",
+                    "echo",
+                    "uppercase",
+                    "reverse",
+                ]));
+            });
+        });
+        it("should include tool metadata", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                const tools = await server.listTools();
+                const addTool = tools.find((t) => t.name === "add");
+                expect(addTool).toBeDefined();
+                expect(addTool.description).toBe("Add two numbers");
+                expect(addTool.inputSchema).toBeDefined();
+                expect(addTool.inputSchema.properties).toHaveProperty("a");
+                expect(addTool.inputSchema.properties).toHaveProperty("b");
+            });
+        });
+        it("should handle empty tool list", async () => {
+            // We'd need a server with no tools for this, skip for now
+            // or create a minimal-server fixture
+        });
+    });
+    describe("Tool Execution", () => {
+        it("should call tool with valid params", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                const result = await server.callTool("add", { a: 5, b: 3 });
+                expect(result).toHaveLength(1);
+                expect(result[0].type).toBe("text");
+                expect(result[0].text).toBe("8");
+            });
+        });
+        it("should handle multiple different tool calls", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                const add = await server.callTool("add", { a: 10, b: 20 });
+                expect(add[0].text).toBe("30");
+                const multiply = await server.callTool("multiply", { a: 4, b: 5 });
+                expect(multiply[0].text).toBe("20");
+                const divide = await server.callTool("divide", { a: 100, b: 4 });
+                expect(divide[0].text).toBe("25");
+            });
+        });
+        it("should handle tool execution error", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                // Division by zero should throw
+                await expect(server.callTool("divide", { a: 10, b: 0 })).rejects.toThrow("Division by zero");
+            });
+        });
+        it("should handle tool not found", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                await expect(server.callTool("nonexistent", { foo: "bar" })).rejects.toThrow();
+            });
+        });
+        it("should work with string manipulation tools", async () => {
+            await withMCPServer(TEST_SERVER, async (server) => {
+                const echo = await server.callTool("echo", { text: "hello" });
+                expect(echo[0].text).toBe("hello");
+                const upper = await server.callTool("uppercase", { text: "hello" });
+                expect(upper[0].text).toBe("HELLO");
+                const reverse = await server.callTool("reverse", { text: "hello" });
+                expect(reverse[0].text).toBe("olleh");
+            });
+        });
+    });
+    describe("Caching", () => {
+        it("should not cache tools list by default", async () => {
+            const server = createMCPServer(TEST_SERVER, {
+                cacheToolsList: false,
+            });
+            await server.connect();
+            const tools1 = await server.listTools();
+            const tools2 = await server.listTools();
+            // Both should succeed (no cache = fresh fetch each time)
+            expect(tools1).toHaveLength(6);
+            expect(tools2).toHaveLength(6);
+            await server.close();
+        });
+        it("should cache tools list when enabled", async () => {
+            const server = createMCPServer(TEST_SERVER, {
+                cacheToolsList: true,
+            });
+            await server.connect();
+            const tools1 = await server.listTools();
+            const tools2 = await server.listTools();
+            // Should get same results from cache
+            expect(tools1).toHaveLength(6);
+            expect(tools2).toHaveLength(6);
+            expect(tools1).toEqual(tools2);
+            await server.close();
+        });
+        it("should invalidate cache when requested", async () => {
+            const server = createMCPServer(TEST_SERVER, {
+                cacheToolsList: true,
+            });
+            await server.connect();
+            const tools1 = await server.listTools();
+            expect(tools1).toHaveLength(6);
+            await server.invalidateCache();
+            const tools2 = await server.listTools();
+            expect(tools2).toHaveLength(6);
+            await server.close();
+        });
+    });
+    describe("Constructor options", () => {
+        it("should accept command and args", async () => {
+            const server = new MCPServerStdio({
+                id: "test",
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            await server.connect();
+            const tools = await server.listTools();
+            expect(tools.length).toBeGreaterThan(0);
+            await server.close();
+        });
+        it("should use custom id", async () => {
+            const server = createMCPServer(TEST_SERVER, { id: "my-test-server" });
+            expect(server.id).toBe("my-test-server");
+        });
+        it("should generate default id from command", async () => {
+            const server = new MCPServerStdio({
+                command: "npx",
+                args: ["tsx", TEST_SERVER],
+            });
+            expect(server.id).toContain("npx");
+        });
+    });
+    describe("Error handling", () => {
+        it("should throw error when calling tool before connect", async () => {
+            const server = createMCPServer(TEST_SERVER);
+            await expect(server.callTool("add", { a: 1, b: 2 })).rejects.toThrow();
+        });
+        it("should throw error when listing tools before connect", async () => {
+            const server = createMCPServer(TEST_SERVER);
+            await expect(server.listTools()).rejects.toThrow();
+        });
+    });
+});

package/dist/mcp/__tests__/test-utils.d.ts

@@ -0,0 +1,17 @@
+import { MCPServerStdio } from "../stdio";
+/**
+ * Helper to run a test with an MCP server, ensuring cleanup.
+ */
+export declare function withMCPServer<T>(serverPath: string, fn: (server: MCPServerStdio) => Promise<T>): Promise<T>;
+/**
+ * Helper to create a server without auto-connecting.
+ */
+export declare function createMCPServer(serverPath: string, options?: {
+    id?: string;
+    cacheToolsList?: boolean;
+}): MCPServerStdio;
+/**
+ * Wait for a condition to be true or timeout.
+ */
+export declare function waitFor(condition: () => boolean | Promise<boolean>, timeout?: number, interval?: number): Promise<void>;
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/mcp/__tests__/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/mcp/__tests__/test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GACtD,cAAc,CAOhB;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAC3C,OAAO,SAAO,EACd,QAAQ,SAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/mcp/__tests__/test-utils.js

@@ -0,0 +1,42 @@
+import { MCPServerStdio } from "../stdio";
+/**
+ * Helper to run a test with an MCP server, ensuring cleanup.
+ */
+export async function withMCPServer(serverPath, fn) {
+    const server = new MCPServerStdio({
+        id: "test-server",
+        command: "npx",
+        args: ["tsx", serverPath],
+    });
+    try {
+        await server.connect();
+        return await fn(server);
+    }
+    finally {
+        await server.close();
+    }
+}
+/**
+ * Helper to create a server without auto-connecting.
+ */
+export function createMCPServer(serverPath, options = {}) {
+    return new MCPServerStdio({
+        id: options.id ?? "test-server",
+        command: "npx",
+        args: ["tsx", serverPath],
+        cacheToolsList: options.cacheToolsList,
+    });
+}
+/**
+ * Wait for a condition to be true or timeout.
+ */
+export async function waitFor(condition, timeout = 5000, interval = 100) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        if (await condition()) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(`Timeout waiting for condition after ${timeout}ms`);
+}

package/dist/mcp/__tests__/utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=utils.test.d.ts.map

package/dist/mcp/__tests__/utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.test.d.ts","sourceRoot":"","sources":["../../../src/mcp/__tests__/utils.test.ts"],"names":[],"mappings":""}