kernl 0.1.1

package/src/mcp/types.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+
+import { Agent } from "@/agent";
+import { Context, UnknownContext } from "@/context";
+import { Logger } from "@/lib/logger";
+
+/**
+ * MCP tool type from the SDK.
+ * We use the SDK's type directly to avoid compatibility issues.
+ */
+export type MCPTool = Tool;
+
+/**
+ * Custom MCP tool schema definition with stricter contracts.
+ * NOTE: Currently not used, but kept for potential future runtime validation.
+ * If needed, we could parse SDK tools through this schema to enforce stricter requirements.
+ */
+export const MCPToolSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  inputSchema: z.object({
+    type: z.literal("object"),
+    properties: z.record(z.string(), z.any()),
+    required: z.array(z.string()),
+    additionalProperties: z.boolean(),
+  }),
+});
+
+/**
+ * Context provided to server-level tool filters during tool resolution.
+ */
+export interface MCPToolFilterContext<TContext = UnknownContext> {
+  context: Context<TContext>;
+  agent: Agent<TContext, any>;
+  serverId: string;
+}
+
+/**
+ * Server-level filter for MCP tools.
+ *
+ * Operates at the protocol layer on raw MCPTool objects before conversion.
+ * Use this for static, security-focused filtering (e.g., "never expose tool X").
+ *
+ * This is the first filter in the pipeline. For dynamic, context-aware filtering,
+ * use ToolkitFilter on MCPToolkit instead.
+ *
+ * @example
+ * ```typescript
+ * const server = new MCPServerStdio({
+ *   command: "npx",
+ *   args: ["-y", "some-server"],
+ *   toolFilter: async (ctx, tool) => {
+ *     // Never expose dangerous tools
+ *     return !tool.name.startsWith("dangerous_");
+ *   }
+ * });
+ * ```
+ */
+export type MCPToolFilter<TContext = UnknownContext> = (
+  context: MCPToolFilterContext<TContext>,
+  tool: MCPTool,
+) => Promise<boolean>;
+
+/**
+ * Static tool filter using allowlist and blocklist of tool names.
+ */
+export interface MCPToolFilterStatic {
+  allowedToolNames?: string[];
+  blockedToolNames?: string[];
+}
+
+/**
+ * JSON-RPC 2.0 request message.
+ */
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+/**
+ * JSON-RPC 2.0 notification message (no response expected).
+ */
+export interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+/**
+ * JSON-RPC 2.0 response message.
+ */
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number;
+  result?: any;
+  error?: any;
+}
+
+/**
+ * Response from calling an MCP tool.
+ */
+export interface CallToolResponse extends JsonRpcResponse {
+  result: {
+    content: { type: string; text: string }[];
+  };
+}
+export type CallToolResult = CallToolResponse["result"];
+export type CallToolResultContent = CallToolResult["content"];
+
+/**
+ * Response from MCP server initialization.
+ */
+export interface InitializeResponse extends JsonRpcResponse {
+  result: {
+    protocolVersion: string;
+    capabilities: {
+      tools: Record<string, unknown>;
+    };
+    serverInfo: {
+      name: string;
+      version: string;
+    };
+  };
+}
+export type InitializeResult = InitializeResponse["result"];
+
+/**
+ * Base configuration options for stdio-based MCP servers.
+ */
+export interface BaseMCPServerStdioOptions {
+  env?: Record<string, string>;
+  cwd?: string;
+  cacheToolsList?: boolean;
+  clientSessionTimeoutSeconds?: number;
+  id?: string;
+  encoding?: string;
+  encodingErrorHandler?: "strict" | "ignore" | "replace";
+  logger?: Logger;
+  toolFilter?: MCPToolFilter;
+  timeout?: number;
+}
+
+/**
+ * Stdio MCP server options with command and args.
+ */
+export interface MCPServerStdioOptions extends BaseMCPServerStdioOptions {
+  command: string;
+  args?: string[];
+}
+
+/**
+ * Configuration options for streamable HTTP MCP servers.
+ */
+export interface MCPServerStreamableHttpOptions {
+  url: string;
+  cacheToolsList?: boolean;
+  clientSessionTimeoutSeconds?: number;
+  id?: string;
+  logger?: Logger;
+  toolFilter?: MCPToolFilter;
+  timeout?: number;
+
+  // ----------------------------------------------------
+  // OAuth
+  // import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+  authProvider?: any;
+  // RequestInit
+  requestInit?: any;
+  // Custom fetch implementation used for all network requests.
+  // import { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js';
+  fetch?: any;
+  // import { StreamableHTTPReconnectionOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+  reconnectionOptions?: any;
+  sessionId?: string;
+  // ----------------------------------------------------
+}
+
+/**
+ * Configuration options for Server-Sent Events (SSE) MCP servers.
+ */
+export interface MCPServerSSEOptions {
+  url: string;
+  cacheToolsList?: boolean;
+  clientSessionTimeoutSeconds?: number;
+  id?: string;
+  logger?: Logger;
+  toolFilter?: MCPToolFilter;
+  timeout?: number;
+
+  // ----------------------------------------------------
+  // OAuth
+  // import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+  authProvider?: any;
+  // RequestInit
+  requestInit?: any;
+  // import { SSEReconnectionOptions } from '@modelcontextprotocol/sdk/client/sse.js';
+  eventSourceInit?: any;
+  // ----------------------------------------------------
+}

package/src/mcp/utils.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+import { UnknownContext } from "@/context";
+import { tool } from "@/tool";
+
+import { MCPServer } from "./base";
+import type { MCPTool, MCPToolFilter } from "./types";
+
+/**
+ * Converts an MCP tool definition into a function tool usable by the SDK.
+ */
+export function mcpToFunctionTool(server: MCPServer, mcpTool: MCPTool) {
+  async function invoke(_ctx: UnknownContext, input: any) {
+    const content = await server.callTool(mcpTool.name, input);
+    return content.length === 1 ? content[0] : content;
+  }
+
+  // MCP tools accept an object with any properties based on their inputSchema
+  // We use z.record(z.any()) to represent this flexible schema
+  const parameters = mcpTool.inputSchema
+    ? z.record(z.string(), z.any())
+    : undefined;
+
+  return tool({
+    id: mcpTool.name,
+    name: mcpTool.name,
+    description: mcpTool.description ?? "",
+    parameters,
+    execute: invoke,
+  });
+}
+
+// ----------------------------
+// Tool filters
+// ----------------------------
+
+/**
+ * Creates a static tool filter from allowed and blocked tool name lists.
+ * Returns a filter function that can be used with MCP servers.
+ */
+export function createMCPToolStaticFilter<TContext = UnknownContext>(options?: {
+  allowed?: string[];
+  blocked?: string[];
+}): MCPToolFilter<TContext> | undefined {
+  if (!options?.allowed && !options?.blocked) {
+    return undefined;
+  }
+
+  const allowedToolNames = options.allowed ?? [];
+  const blockedToolNames = options.blocked ?? [];
+
+  return async (_ctx, tool) => {
+    const allowed =
+      allowedToolNames.length > 0 ? allowedToolNames.includes(tool.name) : true;
+    const blocked =
+      blockedToolNames.length > 0
+        ? blockedToolNames.includes(tool.name)
+        : false;
+
+    return allowed && !blocked;
+  };
+}

package/src/task.ts

@@ -0,0 +1,119 @@
+import type { Agent } from "@/agent";
+import type { Context, UnknownContext } from "@/context";
+
+import type { Thread } from "@/thread";
+
+/**
+ * A Task represents a unit of work scheduled by the kernl.
+ * Analogous to task_struct in the Linux kernel.
+ */
+export class Task<TContext = UnknownContext, TResult = unknown> {
+  pid: string /* process ID - unique identifier for this task */;
+  // tgid: string | null; /* task groupid */
+  // prio: TaskPriority;
+  instructions:
+    | string
+    | ((context: Context<TContext>) => string) /* dynamic instructions */;
+  // sched: TaskSched; /* scheduling (timers, timeouts, deadlines) */
+  state: TaskState /* current state of the task */;
+  owner: Agent<TContext> /* agent that currently owns this task */;
+
+  context: Context<TContext> /* execution context propagated throughout call graph */;
+  // cred: Credentials; /* Effective (overridable) subjective task credentials (COW): */
+  // realcred: Credentials; /* Objective and real subjective task credentials (COW): */
+
+  /**
+   * Might want the ability to pick up a new thread of execution from a compressed task checkpoint instead of including
+   * all of the events from the old threads (which may no longer be useful if they completed with good artifacts + reasoning / action summaries).
+   * At that point its really more about tracing.
+   */
+  threads: Thread<TContext>[] /* all threads associated with this task */;
+  current: Thread<TContext> | null /* current executing thread (if any) */;
+  result: TResult | null /* final result of the task */;
+  // checkpoints: TaskCheckpoint<TContext>[]; /* checkpoints for resuming execution */
+
+  // TODO: Deferred fields for later implementation
+  // tgid: string;              // Thread group ID
+  // limits: TaskLimits;        // Resource limits (max ticks, tokens, timeout)
+  // nsproxy: NamespaceProxy;   // Namespace isolation
+
+  constructor(init: {
+    pid: string;
+    instructions: string | ((context: Context<TContext>) => string);
+    state: TaskState;
+    owner: Agent<TContext>;
+    context: Context<TContext>;
+  }) {
+    this.pid = init.pid;
+    this.instructions = init.instructions;
+    this.state = init.state;
+    this.owner = init.owner;
+    this.context = init.context;
+    this.threads = [];
+    this.current = null;
+    this.result = null;
+  }
+}
+
+/**
+ * The various states that a task may be in.
+ */
+export enum TaskState {
+  /**
+   * Task is either:
+   * - Currently executing
+   * - In run queue waiting to be scheduled (might want to differentiate between running + queued here)
+   */
+  RUNNING = "running",
+
+  /**
+   * Task is sleeping/blocked, waiting for a condition.
+   * Can be woken up by:
+   * - The condition being met (e.g., approval granted)
+   * - A signal (e.g., user cancellation)
+   *
+   * Examples:
+   * - Waiting for tool approval
+   * - Waiting for user input
+   * - Sleeping on a timer
+   */
+  INTERRUPTIBLE = "interruptible",
+
+  /**
+   * Task is sleeping/blocked and CANNOT be interrupted by signals.
+   * Only wakes when the condition is met.
+   *
+   * Examples:
+   * - Waiting for critical I/O (model API call)
+   * - Waiting for resource that MUST complete
+   *
+   * Use sparingly - these tasks can't be cancelled!
+   */
+  UNINTERRUPTIBLE = "uninterruptible",
+
+  /**
+   * Task has been stopped by a signal (SIGSTOP).
+   * Will remain stopped until explicitly continued (SIGCONT).
+   *
+   * Examples:
+   * - User explicitly paused the agent
+   * - Debugger attached
+   */
+  STOPPED = "stopped",
+
+  /**
+   * Task has finished execution but hasn't been cleaned up yet.
+   * Waiting for parent to read exit status (wait/waitpid).
+   *
+   * Examples:
+   * - Agent completed but result not yet retrieved
+   * - Child agent finished, parent needs to collect result
+   */
+  ZOMBIE = "zombie",
+
+  /**
+   * Task is being removed from the system.
+   * Final cleanup in progress, about to be fully deleted.
+   */
+  DEAD = "dead",
+}

package/src/thread/__tests__/mock.ts

@@ -0,0 +1,95 @@
+import {
+  LanguageModel,
+  LanguageModelRequest,
+  LanguageModelResponse,
+  LanguageModelResponseItem,
+  LanguageModelItem,
+} from "@kernl/protocol";
+import type { ThreadStreamEvent } from "@/types/thread";
+
+/**
+ * A mock language model that echoes the user input back as an assistant message.
+ * Useful for testing the execution flow without calling a real LLM.
+ *
+ * (TODO): Support tool calls for testing.
+ */
+export class MockLanguageModel implements LanguageModel {
+  readonly spec = "1.0" as const;
+  readonly provider = "mock";
+  readonly modelId = "mock-model";
+
+  async generate(
+    request: LanguageModelRequest,
+  ): Promise<LanguageModelResponse> {
+    // Extract user message text from input
+    const userText = this.extractUserText(request.input);
+
+    // Create assistant message that echoes the input
+    const content: LanguageModelResponseItem[] = [
+      {
+        kind: "message",
+        id: this.generateId(),
+        role: "assistant",
+        content: [
+          {
+            kind: "text",
+            text: userText,
+          },
+        ],
+      },
+    ];
+
+    // Return with fake usage stats
+    return {
+      content,
+      finishReason: "stop",
+      usage: {
+        inputTokens: this.countTokens(userText),
+        outputTokens: this.countTokens(userText),
+        totalTokens: this.countTokens(userText) * 2,
+      },
+      warnings: [],
+    };
+  }
+
+  async *stream(
+    request: LanguageModelRequest,
+  ): AsyncIterable<ThreadStreamEvent> {
+    // TODO: Implement streaming (not needed for hello world)
+    throw new Error("MockLanguageModel.stream() not implemented yet");
+  }
+
+  /**
+   * Extract text from the input (LanguageModelItem[])
+   */
+  private extractUserText(input: LanguageModelItem[]): string {
+    // Extract text from LanguageModelItem array
+    const text: string[] = [];
+    for (const item of input) {
+      if (item.kind === "message" && item.role === "user") {
+        for (const part of item.content) {
+          if (part.kind === "text") {
+            text.push(part.text);
+          }
+        }
+      }
+    }
+
+    return text.join(" ");
+  }
+
+  /**
+   * Simple token counter (fake approximation)
+   */
+  private countTokens(text: string): number {
+    // Rough approximation: 1 token H 4 characters
+    return Math.ceil(text.length / 4);
+  }
+
+  /**
+   * Generate a simple ID for messages
+   */
+  private generateId(): string {
+    return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+}