kernl 0.1.1

package/src/lib/serde/thread.ts

@@ -0,0 +1,188 @@
+// import { z } from "zod";
+
+// import * as events from "@/types/thread";
+
+// /**
+//  * Utilities and schemas for serializing the run-state so that it can be paused / resumed later.
+//  *
+//  * (TODO): should be able to define this as a codec for the ThreadState schema
+//  */
+
+// /**
+//  * The schema version of the serialized run state. This is used to ensure that the serialized
+//  * run state is compatible with the current version of the SDK.
+//  * If anything in this schema changes, the version will have to be incremented.
+//  */
+// export const CURRENT_SCHEMA_VERSION = "1.0" as const;
+// const $schemaVersion = z.literal(CURRENT_SCHEMA_VERSION);
+
+// const serializedAgentSchema = z.object({
+//   id: z.string(),
+//   name: z.string().optional(),
+// });
+
+// const serializedSpanBase = z.object({
+//   object: z.literal("trace.span"),
+//   id: z.string(),
+//   trace_id: z.string(),
+//   parent_id: z.string().nullable(),
+//   started_at: z.string().nullable(),
+//   ended_at: z.string().nullable(),
+//   error: z
+//     .object({
+//       message: z.string(),
+//       data: z.record(z.string(), z.any()).optional(),
+//     })
+//     .nullable(),
+//   span_data: z.record(z.string(), z.any()),
+// });
+
+// type SerializedSpanType = z.infer<typeof serializedSpanBase> & {
+//   previous_span?: SerializedSpanType;
+// };
+
+// const SerializedSpan: z.ZodType<SerializedSpanType> = serializedSpanBase.extend(
+//   {
+//     previous_span: z.lazy(() => SerializedSpan).optional(),
+//   },
+// );
+
+// const usageSchema = z.object({
+//   requests: z.number(),
+//   inputTokens: z.number(),
+//   outputTokens: z.number(),
+//   totalTokens: z.number(),
+// });
+
+// const modelResponseSchema = z.object({
+//   usage: usageSchema,
+//   events: z.array(events.ThreadEvent),
+//   responseId: z.string().optional(),
+//   providerData: z.record(z.string(), z.any()).optional(),
+// });
+
+// const itemSchema = z.discriminatedUnion("kind", [
+//   z.object({
+//     kind: z.literal("message"),
+//     rawItem: events.AssistantMessage,
+//     agent: serializedAgentSchema,
+//   }),
+//   z.object({
+//     kind: z.literal("tool-call"),
+//     // rawItem: events.ToolCall.or(events.HostedToolCall),
+//     rawItem: events.ToolCall,
+//     agent: serializedAgentSchema,
+//   }),
+//   z.object({
+//     kind: z.literal("tool-result"),
+//     rawItem: events.ToolResultEvent,
+//     agent: serializedAgentSchema,
+//     output: z.string(),
+//   }),
+//   z.object({
+//     kind: z.literal("reasoning"),
+//     rawItem: events.Reasoning,
+//     agent: serializedAgentSchema,
+//   }),
+// ]);
+
+// const serializedTraceSchema = z.object({
+//   object: z.literal("trace"),
+//   id: z.string(),
+//   workflow_name: z.string(),
+//   group_id: z.string().nullable(),
+//   metadata: z.record(z.string(), z.any()),
+// });
+
+// const serializedProcessedResponseSchema = z.object({
+//   newItems: z.array(itemSchema),
+//   toolsUsed: z.array(z.string()),
+//   functions: z.array(
+//     z.object({
+//       toolCall: z.any(),
+//       tool: z.any(),
+//     }),
+//   ),
+//   mcpApprovalRequests: z
+//     .array(
+//       z.object({
+//         requestItem: z.object({
+//           // protocol.HostedToolCallItem
+//           rawItem: z.object({
+//             type: z.literal("hosted_tool_call"),
+//             name: z.string(),
+//             arguments: z.string().optional(),
+//             status: z.string().optional(),
+//             output: z.string().optional(),
+//             // this always exists but marked as optional for early version compatibility; when releasing 1.0, we can remove the nullable and optional
+//             providerData: z.record(z.string(), z.any()).nullable().optional(),
+//           }),
+//         }),
+//         // HostedMCPTool
+//         mcpTool: z.object({
+//           type: z.literal("hosted_tool"),
+//           name: z.literal("hosted_mcp"),
+//           providerData: z.record(z.string(), z.any()),
+//         }),
+//       }),
+//     )
+//     .optional(),
+// });
+
+// const guardrailFunctionOutputSchema = z.object({
+//   tripwireTriggered: z.boolean(),
+//   outputInfo: z.any(),
+// });
+
+// const inputGuardrailResultSchema = z.object({
+//   guardrail: z.object({
+//     type: z.literal("input"),
+//     name: z.string(),
+//   }),
+//   output: guardrailFunctionOutputSchema,
+// });
+
+// const outputGuardrailResultSchema = z.object({
+//   guardrail: z.object({
+//     type: z.literal("output"),
+//     name: z.string(),
+//   }),
+//   agentOutput: z.any(),
+//   agent: serializedAgentSchema,
+//   output: guardrailFunctionOutputSchema,
+// });
+
+// // (TODO): define z.codec
+// export const SerializedThread = z.object({
+//   $schemaVersion,
+//   currentTurn: z.number(),
+//   currentAgent: serializedAgentSchema, // (TODO): in our case we probably don't need to serialize the whole agent - an ID would suffice
+//   originalInput: z.string().or(z.array(events.ThreadEvent)),
+//   modelResponses: z.array(modelResponseSchema),
+//   context: z.object({
+//     usage: usageSchema, // (TODO): move to stats
+//     // (TODO): belongs elsewhere
+//     approvals: z.record(
+//       z.string(),
+//       z.object({
+//         approved: z.array(z.string()).or(z.boolean()),
+//         rejected: z.array(z.string()).or(z.boolean()),
+//       }),
+//     ),
+//     context: z.record(z.string(), z.any()),
+//   }),
+//   toolUseTracker: z.record(z.string(), z.array(z.string())),
+//   maxTurns: z.number(),
+//   currentAgentSpan: SerializedSpan.nullable().optional(),
+//   noActiveAgentRun: z.boolean(),
+//   inputGuardrailResults: z.array(inputGuardrailResultSchema),
+//   outputGuardrailResults: z.array(outputGuardrailResultSchema),
+//   // (TODO): currentStep: nextStepSchema.optional(),
+//   lastModelResponse: modelResponseSchema.optional(),
+//   generatedItems: z.array(itemSchema),
+//   lastProcessedResponse: serializedProcessedResponseSchema.optional(),
+//   currentTurnPersistedItemCount: z.number().int().min(0).optional(),
+//   trace: serializedTraceSchema.nullable(),
+// });
+
+// export type SerializedThread = z.infer<typeof SerializedThread>;

package/src/lifecycle.ts

@@ -0,0 +1,181 @@
+import { EventEmitter } from "node:events";
+
+import { Agent } from "./agent";
+import { Context, UnknownContext } from "./context";
+import { Tool } from "./tool";
+import type { ToolCall } from "@kernl/protocol";
+
+import { AgentResponseType } from "./types/agent";
+import { TextResponse } from "./types/thread";
+
+export type EventEmitterEvents = Record<string, any[]>;
+
+/**
+ * Generic typed event emitter that wraps Node's EventEmitter with type safety
+ */
+class TypedEventEmitter<
+  EventTypes extends EventEmitterEvents = Record<string, any[]>,
+> extends EventEmitter {
+  // Overload for typed events
+  on<K extends keyof EventTypes>(
+    event: K,
+    listener: (...args: EventTypes[K]) => void,
+  ): this;
+  // Fallback for compatibility with parent
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+  on(event: any, listener: any): this {
+    return super.on(event, listener);
+  }
+
+  // Overload for typed events
+  off<K extends keyof EventTypes>(
+    event: K,
+    listener: (...args: EventTypes[K]) => void,
+  ): this;
+  // Fallback for compatibility with parent
+  off(event: string | symbol, listener: (...args: any[]) => void): this;
+  off(event: any, listener: any): this {
+    return super.off(event, listener);
+  }
+
+  // Overload for typed events
+  emit<K extends keyof EventTypes>(event: K, ...args: EventTypes[K]): boolean;
+  // Fallback for compatibility with parent
+  emit(event: string | symbol, ...args: any[]): boolean;
+  emit(event: any, ...args: any[]): boolean {
+    return super.emit(event, ...args);
+  }
+
+  // Overload for typed events
+  once<K extends keyof EventTypes>(
+    event: K,
+    listener: (...args: EventTypes[K]) => void,
+  ): this;
+  // Fallback for compatibility with parent
+  once(event: string | symbol, listener: (...args: any[]) => void): this;
+  once(event: any, listener: any): this {
+    return super.once(event, listener);
+  }
+}
+
+export type AgentHookEvents<
+  TContext = UnknownContext,
+  TOutput extends AgentResponseType = TextResponse,
+> = {
+  /**
+   * @param context - The context of the run
+   */
+  agent_start: [context: Context<TContext>, agent: Agent<TContext, TOutput>];
+  /**
+   * @param context - The context of the run
+   * @param output - The output of the agent
+   */
+  agent_end: [context: Context<TContext>, output: string];
+  // /**
+  //  * @param context - The context of the run
+  //  * @param agent - The agent that is handing off
+  //  * @param nextAgent - The next agent to run
+  //  */
+  // agent_handoff: [context: Context<TContext>, nextAgent: Agent<any, any>];
+  /**
+   * @param context - The context of the run
+   * @param agent - The agent that is starting a tool
+   * @param tool - The tool that is starting
+   */
+  agent_tool_start: [
+    context: Context<TContext>,
+    tool: Tool<any>,
+    details: { toolCall: ToolCall },
+  ];
+  /**
+   * @param context - The context of the run
+   * @param agent - The agent that is ending a tool
+   * @param tool - The tool that is ending
+   * @param result - The result of the tool
+   */
+  agent_tool_end: [
+    context: Context<TContext>,
+    tool: Tool<any>,
+    result: string,
+    details: { toolCall: ToolCall },
+  ];
+};
+
+/**
+ * Event emitter that every Agent instance inherits from and that emits events for the lifecycle
+ * of the agent.
+ */
+export class AgentHooks<
+  TContext = UnknownContext,
+  TOutput extends AgentResponseType = TextResponse,
+> extends TypedEventEmitter<AgentHookEvents<TContext, TOutput>> {}
+
+/**
+ * Events emitted by the kernl during execution.
+ *
+ * Unlike AgentHookEvents (which are emitted by individual agents with implicit context),
+ * KernlHookEvents explicitly include the agent reference in all events since it needs to
+ * coordinate multiple agents and listeners need to know which agent triggered each event.
+ */
+export type KernlHookEvents<
+  TContext = UnknownContext,
+  TOutput extends AgentResponseType = TextResponse,
+> = {
+  /**
+   * @param context - The context of the run
+   * @param agent - The agent that is starting
+   */
+  agent_start: [context: Context<TContext>, agent: Agent<TContext, TOutput>];
+  /**
+   * @param context - The context of the run
+   * @param agent - The agent that is ending
+   * @param output - The output of the agent
+   */
+  agent_end: [
+    context: Context<TContext>,
+    agent: Agent<TContext, TOutput>,
+    output: string,
+  ];
+  /**
+   * @param context - The context of the run
+   * @param fromAgent - The agent that is handing off
+   * @param toAgent - The next agent to run
+   */
+  agent_handoff: [
+    context: Context<TContext>,
+    fromAgent: Agent<any, any>,
+    toAgent: Agent<any, any>,
+  ];
+  /**
+   * @param context - The context of the run
+   * @param agent - The agent that is starting a tool
+   * @param tool - The tool that is starting
+   */
+  agent_tool_start: [
+    context: Context<TContext>,
+    agent: Agent<TContext, TOutput>,
+    tool: Tool,
+    details: { toolCall: ToolCall },
+  ];
+  /**
+   * @param context - The context of the run
+   * @param agent - The agent that is ending a tool
+   * @param tool - The tool that is ending
+   * @param result - The result of the tool
+   */
+  agent_tool_end: [
+    context: Context<TContext>,
+    agent: Agent<TContext, TOutput>,
+    tool: Tool,
+    result: string,
+    details: { toolCall: ToolCall },
+  ];
+};
+
+/**
+ * Event emitter that the kernl uses to emit events for the lifecycle of every agent run.
+ */
+export class KernlHooks<
+  TContext = UnknownContext,
+  TOutput extends AgentResponseType = TextResponse,
+> extends TypedEventEmitter<KernlHookEvents<TContext, TOutput>> {}

package/src/mcp/__tests__/base.test.ts

@@ -0,0 +1,344 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { BaseMCPServer } from "../base";
+import type { MCPTool, CallToolResultContent } from "../types";
+import { logger } from "@/lib/logger";
+
+// Create a minimal concrete implementation for testing
+class TestMCPServer extends BaseMCPServer {
+  readonly id: string;
+  private mockTools: MCPTool[] = [];
+  private isConnected = false;
+
+  constructor(
+    id: string,
+    options?: {
+      cacheToolsList?: boolean;
+      toolFilter?: any;
+    },
+  ) {
+    super({
+      cacheToolsList: options?.cacheToolsList,
+      toolFilter: options?.toolFilter,
+      logger: logger,
+    });
+    this.id = id;
+  }
+
+  // Method to set mock tools for testing
+  setMockTools(tools: MCPTool[]): void {
+    this.mockTools = tools;
+  }
+
+  async connect(): Promise<void> {
+    this.isConnected = true;
+  }
+
+  async close(): Promise<void> {
+    this.isConnected = false;
+  }
+
+  protected async _listTools(): Promise<MCPTool[]> {
+    if (!this.isConnected) {
+      throw new Error("Not connected");
+    }
+    return this.mockTools;
+  }
+
+  async callTool(
+    toolName: string,
+    args: Record<string, unknown> | null,
+  ): Promise<CallToolResultContent> {
+    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: MCPTool[] = [
+        {
+          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: MCPTool[] = [
+        {
+          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: MCPTool[] = [
+        {
+          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: MCPTool[] = [
+        {
+          name: "tool1",
+          inputSchema: { type: "object", properties: {} },
+        },
+      ];
+      const tools2: MCPTool[] = [
+        {
+          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: MCPTool[] = [
+        {
+          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: MCPTool[] = [
+        {
+          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: any = {
+        context: {},
+        agent: {},
+        serverId: "test",
+      };
+      const mockTool: MCPTool = {
+        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: any = {
+        context: {},
+        agent: {},
+        serverId: "test",
+      };
+      const mockTool: MCPTool = {
+        name: "tool1",
+        inputSchema: { type: "object", properties: {} },
+      };
+
+      const result = await server.toolFilter(mockContext, mockTool);
+      expect(result).toBe(false);
+      expect(customFilter).toHaveBeenCalledWith(mockContext, mockTool);
+    });
+  });
+});