kernl 0.1.1

package/dist/lifecycle.js

@@ -0,0 +1,29 @@
+import { EventEmitter } from "node:events";
+/**
+ * Generic typed event emitter that wraps Node's EventEmitter with type safety
+ */
+class TypedEventEmitter extends EventEmitter {
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+}
+/**
+ * Event emitter that every Agent instance inherits from and that emits events for the lifecycle
+ * of the agent.
+ */
+export class AgentHooks extends TypedEventEmitter {
+}
+/**
+ * Event emitter that the kernl uses to emit events for the lifecycle of every agent run.
+ */
+export class KernlHooks extends TypedEventEmitter {
+}

package/dist/logger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A logger instance with namespace support and sensitive data flags.
+ */
+export type Logger = {
+    /**
+     * The namespace used for the logger.
+     */
+    namespace: string;
+    trace: (message: any, ...args: any[]) => void;
+    debug: (message: any, ...args: any[]) => void;
+    info: (message: any, ...args: any[]) => void;
+    warn: (message: any, ...args: any[]) => void;
+    error: (message: any, ...args: any[]) => void;
+    fatal: (message: any, ...args: any[]) => void;
+    /**
+     * Whether to log model data.
+     */
+    dontLogModelData: boolean;
+    /**
+     * Whether to log tool data.
+     */
+    dontLogToolData: boolean;
+};
+/**
+ * Get a logger for a given namespace.
+ *
+ * @param namespace - the namespace to use for the logger (e.g., 'kernl:core', 'kernl:agent').
+ * @returns A logger object with all pino log levels and sensitive data flags.
+ */
+export declare function getLogger(namespace?: string): Logger;
+/**
+ * Default logger instance for the core library.
+ */
+export declare const logger: Logger;
+export default logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAsBA;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9C,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9C,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC7C,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC7C,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9C,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAE9C;;OAEG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B;;OAEG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,SAAS,GAAE,MAAgB,GAAG,MAAM,CAc7D;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,QAA0B,CAAC;AAE9C,eAAe,MAAM,CAAC"}

package/dist/logger.js

@@ -0,0 +1,43 @@
+import pino from "pino";
+import { env } from "./env";
+/**
+ * By default we don't log LLM inputs/outputs, to prevent exposing sensitive data.
+ * Set KERNL_LOG_MODEL_DATA=true to enable.
+ */
+const dontLogModelData = !env.KERNL_LOG_MODEL_DATA;
+/**
+ * By default we don't log tool inputs/outputs, to prevent exposing sensitive data.
+ * Set KERNL_LOG_TOOL_DATA=true to enable.
+ */
+const dontLogToolData = !env.KERNL_LOG_TOOL_DATA;
+/**
+ * Base pino logger instance
+ */
+const base = pino({
+    level: env.LOG_LEVEL,
+});
+/**
+ * Get a logger for a given namespace.
+ *
+ * @param namespace - the namespace to use for the logger (e.g., 'kernl:core', 'kernl:agent').
+ * @returns A logger object with all pino log levels and sensitive data flags.
+ */
+export function getLogger(namespace = "kernl") {
+    const child = base.child({ namespace });
+    return {
+        namespace,
+        trace: child.trace.bind(child),
+        debug: child.debug.bind(child),
+        info: child.info.bind(child),
+        warn: child.warn.bind(child),
+        error: child.error.bind(child),
+        fatal: child.fatal.bind(child),
+        dontLogModelData,
+        dontLogToolData,
+    };
+}
+/**
+ * Default logger instance for the core library.
+ */
+export const logger = getLogger("kernl:core");
+export default logger;

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

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

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

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

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

@@ -0,0 +1,268 @@
+import { describe, it, expect, vi } from "vitest";
+import { BaseMCPServer } from "../base";
+import { logger } from "../../lib/logger";
+// Create a minimal concrete implementation for testing
+class TestMCPServer extends BaseMCPServer {
+    id;
+    mockTools = [];
+    isConnected = false;
+    constructor(id, options) {
+        super({
+            cacheToolsList: options?.cacheToolsList,
+            toolFilter: options?.toolFilter,
+            logger: logger,
+        });
+        this.id = id;
+    }
+    // Method to set mock tools for testing
+    setMockTools(tools) {
+        this.mockTools = tools;
+    }
+    async connect() {
+        this.isConnected = true;
+    }
+    async close() {
+        this.isConnected = false;
+    }
+    async _listTools() {
+        if (!this.isConnected) {
+            throw new Error("Not connected");
+        }
+        return this.mockTools;
+    }
+    async callTool(toolName, args) {
+        if (!this.isConnected) {
+            throw new Error("Not connected");
+        }
+        return [{ type: "text", text: `Called ${toolName}` }];
+    }
+}
+describe("BaseMCPServer", () => {
+    describe("Caching mechanisms", () => {
+        it("should have cache disabled by default", () => {
+            const server = new TestMCPServer("test-server");
+            expect(server.cacheToolsList).toBe(false);
+        });
+        it("should store tools correctly when cache enabled", async () => {
+            const server = new TestMCPServer("test-server", {
+                cacheToolsList: true,
+            });
+            const mockTools = [
+                {
+                    name: "tool1",
+                    description: "First tool",
+                    inputSchema: { type: "object", properties: {} },
+                },
+                {
+                    name: "tool2",
+                    description: "Second tool",
+                    inputSchema: { type: "object", properties: {} },
+                },
+            ];
+            server.setMockTools(mockTools);
+            await server.connect();
+            const tools = await server.listTools();
+            expect(tools).toEqual(mockTools);
+            expect(tools).toHaveLength(2);
+        });
+        it("should return same reference on subsequent calls when cached", async () => {
+            const server = new TestMCPServer("test-server", {
+                cacheToolsList: true,
+            });
+            const mockTools = [
+                {
+                    name: "tool1",
+                    inputSchema: { type: "object", properties: {} },
+                },
+            ];
+            server.setMockTools(mockTools);
+            await server.connect();
+            const tools1 = await server.listTools();
+            const tools2 = await server.listTools();
+            // Should return the exact same cached reference
+            expect(tools1).toBe(tools2);
+        });
+        it("should fetch fresh tools when cache disabled", async () => {
+            const server = new TestMCPServer("test-server", {
+                cacheToolsList: false,
+            });
+            const mockTools = [
+                {
+                    name: "tool1",
+                    inputSchema: { type: "object", properties: {} },
+                },
+            ];
+            server.setMockTools(mockTools);
+            await server.connect();
+            const tools1 = await server.listTools();
+            const tools2 = await server.listTools();
+            // Both should succeed and have correct data
+            expect(tools1).toEqual(mockTools);
+            expect(tools2).toEqual(mockTools);
+        });
+        it("should have cache isolated per server instance", async () => {
+            const server1 = new TestMCPServer("server1", {
+                cacheToolsList: true,
+            });
+            const server2 = new TestMCPServer("server2", {
+                cacheToolsList: true,
+            });
+            const tools1 = [
+                {
+                    name: "tool1",
+                    inputSchema: { type: "object", properties: {} },
+                },
+            ];
+            const tools2 = [
+                {
+                    name: "tool2",
+                    inputSchema: { type: "object", properties: {} },
+                },
+            ];
+            server1.setMockTools(tools1);
+            server2.setMockTools(tools2);
+            await server1.connect();
+            await server2.connect();
+            const result1 = await server1.listTools();
+            const result2 = await server2.listTools();
+            expect(result1).toEqual(tools1);
+            expect(result2).toEqual(tools2);
+            expect(result1).not.toEqual(result2);
+        });
+        it("should clear cache when invalidateCache() called", async () => {
+            const server = new TestMCPServer("test-server", {
+                cacheToolsList: true,
+            });
+            const initialTools = [
+                {
+                    name: "tool1",
+                    inputSchema: { type: "object", properties: {} },
+                },
+            ];
+            server.setMockTools(initialTools);
+            await server.connect();
+            // First fetch - populates cache
+            await server.listTools();
+            // Invalidate cache
+            await server.invalidateCache();
+            // Update mock tools
+            const newTools = [
+                {
+                    name: "tool2",
+                    inputSchema: { type: "object", properties: {} },
+                },
+            ];
+            server.setMockTools(newTools);
+            // Next fetch should get new tools, not cached ones
+            const result = await server.listTools();
+            expect(result).toEqual(newTools);
+        });
+        it("should set _cacheDirty flag when invalidateCache() called", async () => {
+            const server = new TestMCPServer("test-server", {
+                cacheToolsList: true,
+            });
+            await server.connect();
+            server.setMockTools([
+                { name: "tool1", inputSchema: { type: "object", properties: {} } },
+            ]);
+            // Populate cache
+            await server.listTools();
+            // Invalidate
+            await server.invalidateCache();
+            // The next listTools() call should fetch fresh data
+            // We can verify this by changing the mock tools and seeing the change
+            server.setMockTools([
+                { name: "tool2", inputSchema: { type: "object", properties: {} } },
+            ]);
+            const tools = await server.listTools();
+            expect(tools[0].name).toBe("tool2");
+        });
+        it("should skip cache when _cacheDirty is true", async () => {
+            const server = new TestMCPServer("test-server", {
+                cacheToolsList: true,
+            });
+            await server.connect();
+            // First call
+            server.setMockTools([
+                { name: "tool1", inputSchema: { type: "object", properties: {} } },
+            ]);
+            await server.listTools();
+            // Invalidate cache (sets _cacheDirty = true)
+            await server.invalidateCache();
+            // Change mock tools
+            server.setMockTools([
+                { name: "tool2", inputSchema: { type: "object", properties: {} } },
+            ]);
+            // Should fetch fresh tools, not use cache
+            const tools = await server.listTools();
+            expect(tools[0].name).toBe("tool2");
+        });
+    });
+    describe("Abstract class contracts", () => {
+        it("should allow subclass to implement connect()", async () => {
+            const server = new TestMCPServer("test-server");
+            await expect(server.connect()).resolves.not.toThrow();
+        });
+        it("should allow subclass to implement close()", async () => {
+            const server = new TestMCPServer("test-server");
+            await server.connect();
+            await expect(server.close()).resolves.not.toThrow();
+        });
+        it("should allow subclass to implement _listTools()", async () => {
+            const server = new TestMCPServer("test-server");
+            server.setMockTools([
+                { name: "tool1", inputSchema: { type: "object", properties: {} } },
+            ]);
+            await server.connect();
+            const tools = await server.listTools();
+            expect(tools).toHaveLength(1);
+            expect(tools[0].name).toBe("tool1");
+        });
+        it("should allow subclass to implement callTool()", async () => {
+            const server = new TestMCPServer("test-server");
+            await server.connect();
+            const result = await server.callTool("test_tool", { arg: "value" });
+            expect(result).toHaveLength(1);
+            expect(result[0].text).toContain("test_tool");
+        });
+    });
+    describe("toolFilter integration", () => {
+        it("should default to allow-all filter", async () => {
+            const server = new TestMCPServer("test-server");
+            // The default filter should allow all tools
+            expect(server.toolFilter).toBeDefined();
+            // Test that it returns true for any tool
+            const mockContext = {
+                context: {},
+                agent: {},
+                serverId: "test",
+            };
+            const mockTool = {
+                name: "any_tool",
+                inputSchema: { type: "object", properties: {} },
+            };
+            const result = await server.toolFilter(mockContext, mockTool);
+            expect(result).toBe(true);
+        });
+        it("should store custom filter correctly in constructor", async () => {
+            const customFilter = vi.fn().mockResolvedValue(false);
+            const server = new TestMCPServer("test-server", {
+                toolFilter: customFilter,
+            });
+            expect(server.toolFilter).toBe(customFilter);
+            // Verify the filter is actually used
+            const mockContext = {
+                context: {},
+                agent: {},
+                serverId: "test",
+            };
+            const mockTool = {
+                name: "tool1",
+                inputSchema: { type: "object", properties: {} },
+            };
+            const result = await server.toolFilter(mockContext, mockTool);
+            expect(result).toBe(false);
+            expect(customFilter).toHaveBeenCalledWith(mockContext, mockTool);
+        });
+    });
+});

package/dist/mcp/__tests__/fixtures/echo-server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=echo-server.d.ts.map

package/dist/mcp/__tests__/fixtures/echo-server.d.ts.map

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

package/dist/mcp/__tests__/fixtures/echo-server.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Simple echo/string manipulation server for testing MCP stdio transport.
+ *
+ * Provides deterministic string transformations.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+const server = new Server({
+    name: "echo-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler("tools/list", async () => ({
+    tools: [
+        {
+            name: "echo",
+            description: "Echo back the input text",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    text: { type: "string", description: "Text to echo" },
+                },
+                required: ["text"],
+            },
+        },
+        {
+            name: "uppercase",
+            description: "Convert text to uppercase",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    text: { type: "string", description: "Text to convert" },
+                },
+                required: ["text"],
+            },
+        },
+        {
+            name: "reverse",
+            description: "Reverse the text",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    text: { type: "string", description: "Text to reverse" },
+                },
+                required: ["text"],
+            },
+        },
+    ],
+}));
+// Handle tool calls
+server.setRequestHandler("tools/call", async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case "echo":
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: args.text,
+                    },
+                ],
+            };
+        case "uppercase":
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: args.text.toUpperCase(),
+                    },
+                ],
+            };
+        case "reverse":
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: args.text.split("").reverse().join(""),
+                    },
+                ],
+            };
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/mcp/__tests__/fixtures/math-server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=math-server.d.ts.map

package/dist/mcp/__tests__/fixtures/math-server.d.ts.map

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

package/dist/mcp/__tests__/fixtures/math-server.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * Simple deterministic math server for testing MCP stdio transport.
+ *
+ * Provides basic arithmetic operations with predictable results.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+const server = new Server({
+    name: "math-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler("tools/list", async () => ({
+    tools: [
+        {
+            name: "add",
+            description: "Add two numbers",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    a: { type: "number", description: "First number" },
+                    b: { type: "number", description: "Second number" },
+                },
+                required: ["a", "b"],
+            },
+        },
+        {
+            name: "multiply",
+            description: "Multiply two numbers",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    a: { type: "number", description: "First number" },
+                    b: { type: "number", description: "Second number" },
+                },
+                required: ["a", "b"],
+            },
+        },
+        {
+            name: "divide",
+            description: "Divide two numbers",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    a: { type: "number", description: "Numerator" },
+                    b: { type: "number", description: "Denominator" },
+                },
+                required: ["a", "b"],
+            },
+        },
+    ],
+}));
+// Handle tool calls
+server.setRequestHandler("tools/call", async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case "add":
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: String(args.a + args.b),
+                    },
+                ],
+            };
+        case "multiply":
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: String(args.a * args.b),
+                    },
+                ],
+            };
+        case "divide":
+            if (args.b === 0) {
+                throw new Error("Division by zero");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: String(args.a / args.b),
+                    },
+                ],
+            };
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/mcp/__tests__/fixtures/server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/__tests__/fixtures/server.d.ts.map

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