kernl 0.1.1

package/src/tool/tool.ts

@@ -0,0 +1,264 @@
+import { Context, UnknownContext } from "@/context";
+
+import { ModelBehaviorError } from "@/lib/error";
+import { logger } from "@/lib/logger";
+import { json } from "@kernl/shared/lib";
+import { FAILED, COMPLETED, INTERRUPTIBLE } from "@kernl/protocol";
+import type { LanguageModelTool } from "@kernl/protocol";
+
+import type {
+  ToolType,
+  ToolConfig,
+  ToolApprovalFunction,
+  ToolEnabledFunction,
+  ToolEnabledPredicate,
+  ToolErrorFunction,
+  ToolExecuteArgument,
+  ToolExecuteFunction,
+  ToolInputParameters,
+  ToolResult,
+} from "./types";
+
+/**
+ * Exposes a function to the agent as a tool to be called
+ *
+ * @param config The options for the tool
+ * @returns A new tool instance
+ */
+export function tool<
+  TContext = UnknownContext,
+  TParameters extends ToolInputParameters = undefined,
+  TResult = string,
+>(
+  config: ToolConfig<TContext, TParameters, TResult>,
+): FunctionTool<TContext, TParameters, TResult> {
+  return new FunctionTool(config);
+}
+
+/**
+ * Base class for all tools (function and hosted)
+ */
+export abstract class BaseTool<TContext = UnknownContext> {
+  abstract readonly type: "function" | "hosted-tool";
+  abstract readonly id: string;
+  abstract readonly name?: string;
+
+  /**
+   * The function to invoke when an error occurs while running the tool.
+   */
+  abstract errorfn: ToolErrorFunction | null;
+
+  /**
+   * Whether the tool requires human approval before it can be called.
+   */
+  abstract requiresApproval: ToolApprovalFunction<any>;
+
+  /**
+   * Determines whether the tool should be exposed to the model for the current run.
+   */
+  abstract isEnabled(context: Context<TContext>, agent: any): Promise<boolean>;
+
+  /**
+   * Serialize this tool for sending to the model
+   */
+  abstract serialize(): LanguageModelTool;
+}
+
+/**
+ * A function tool that can be used by agents.
+ */
+export class FunctionTool<
+  TContext = UnknownContext,
+  TParameters extends ToolInputParameters = undefined,
+  TResult = unknown,
+> extends BaseTool<TContext> {
+  readonly type = "function" as const;
+  readonly id: string;
+  readonly name?: string;
+  readonly description: string;
+  readonly parameters?: TParameters;
+  readonly mode: "blocking" | "async";
+  private execute: ToolExecuteFunction<TContext, TParameters, TResult>;
+
+  errorfn: ToolErrorFunction | null;
+  requiresApproval: ToolApprovalFunction<TParameters>;
+  isEnabled: ToolEnabledFunction<TContext>;
+
+  constructor(config: ToolConfig<TContext, TParameters, TResult>) {
+    super();
+    this.id = config.id;
+    this.name = config.name;
+    this.description = config.description;
+    this.parameters = config.parameters;
+    this.mode = config.mode ?? "blocking";
+    this.execute = config.execute;
+
+    // setup error function
+    this.errorfn =
+      typeof config.errorfn === "undefined"
+        ? defaultToolErrorFunction
+        : config.errorfn;
+
+    // setup approval function
+    this.requiresApproval =
+      typeof config.requiresApproval === "function"
+        ? config.requiresApproval
+        : async () =>
+            typeof config.requiresApproval === "boolean"
+              ? config.requiresApproval
+              : false;
+
+    // setup enabled function
+    this.isEnabled =
+      typeof config.isEnabled === "function"
+        ? async (context, agent) => {
+            const predicate =
+              config.isEnabled as ToolEnabledPredicate<TContext>;
+            const result = await predicate({ context, agent });
+            return Boolean(result);
+          }
+        : async () =>
+            typeof config.isEnabled === "boolean" ? config.isEnabled : true;
+  }
+
+  /**
+   * Main invocation method -
+   *
+   * Wraps execute with parsing, approval, and error handling
+   */
+  async invoke(
+    context: Context<TContext>,
+    args: string,
+    callId?: string,
+  ): Promise<ToolResult<TResult>> {
+    return this._invoke(context, args, callId).catch((error) => {
+      const msg = this.errorfn
+        ? this.errorfn(context, error)
+        : error instanceof Error
+          ? error.message
+          : String(error);
+
+      return {
+        state: FAILED,
+        result: undefined,
+        error: msg,
+      };
+    });
+  }
+
+  /**
+   * Executes the tool with the provided execute() function
+   */
+  private async _invoke(
+    context: Context<TContext>,
+    args: string,
+    callId?: string,
+  ): Promise<ToolResult<TResult>> {
+    let parsed = args as ToolExecuteArgument<TParameters>;
+
+    if (this.parameters) {
+      try {
+        parsed = json(this.parameters).decode(
+          args,
+        ) as ToolExecuteArgument<TParameters>;
+      } catch (error) {
+        logger.debug(`Invalid JSON input for tool ${this.id}: ${args}`);
+        throw new ModelBehaviorError("Invalid JSON input for tool");
+      }
+    }
+
+    // Check if approval is required
+    const needsApproval = await this.requiresApproval(context, parsed, callId);
+    const approvalStatus = callId ? context.approvals.get(callId) : undefined;
+
+    if (needsApproval && approvalStatus !== "approved") {
+      return {
+        state: INTERRUPTIBLE,
+        result: undefined,
+        error: null,
+      };
+    }
+
+    const result = await this.execute(context, parsed);
+    return {
+      state: COMPLETED,
+      result: result,
+      error: null,
+    };
+  }
+
+  /**
+   * Serialize this function tool for sending to the model
+   */
+  serialize(): LanguageModelTool {
+    return {
+      kind: "function",
+      name: this.id,
+      description: this.description,
+      parameters: this.parameters as any, // TODO: convert Zod to JSON Schema
+    };
+  }
+}
+
+/**
+ * Hosted tool executed server-side by the model provider
+ */
+export class HostedTool extends BaseTool {
+  readonly type = "hosted-tool" as const;
+  readonly id: string;
+  readonly name?: string;
+  readonly providerData?: Record<string, any>;
+
+  /**
+   * Hosted tools use the default error function
+   */
+  errorfn: ToolErrorFunction | null = defaultToolErrorFunction;
+
+  /**
+   * Hosted tools do not require approval by default
+   */
+  requiresApproval: ToolApprovalFunction<any> = async () => false;
+
+  constructor(config: {
+    id: string;
+    name?: string;
+    providerData?: Record<string, any>;
+  }) {
+    super();
+    this.id = config.id;
+    this.name = config.name;
+    this.providerData = config.providerData;
+  }
+
+  /**
+   * Hosted tools are always enabled
+   */
+  async isEnabled(): Promise<boolean> {
+    return true;
+  }
+
+  /**
+   * Serialize this hosted tool for sending to the model
+   */
+  serialize(): LanguageModelTool {
+    return {
+      kind: "provider-defined",
+      id: this.id as `${string}.${string}`,
+      name: this.name || this.id,
+      args: this.providerData || {},
+    };
+  }
+}
+
+/**
+ * The default function to invoke when an error occurs while running the tool.
+ *
+ * Always returns `An error occurred while running the tool. Please try again. Error: <error details>`
+ *
+ * @param context - An instance of the current Context
+ * @param error - The error that occurred
+ */
+function defaultToolErrorFunction(context: Context, error: Error | unknown) {
+  const details = error instanceof Error ? error.toString() : String(error);
+  return `An error occurred while running the tool. Please try again. Error: ${details}`;
+}

package/src/tool/toolkit.ts

@@ -0,0 +1,234 @@
+import type { Agent } from "@/agent";
+import type { Context, UnknownContext } from "@/context";
+
+import { MCPServer } from "@/mcp/base";
+import { mcpToFunctionTool } from "@/mcp/utils";
+import { filter } from "@kernl/shared/lib";
+
+import type { Tool } from ".";
+import type {
+  FunctionToolkitConfig,
+  MCPToolkitConfig,
+  ToolkitFilter,
+} from "./types";
+
+/**
+ * A toolkit is a collection of related tools that can be used by an agent.
+ *
+ * Toolkits can be static (FunctionToolkit) or dynamic (MCPToolkit), and provide
+ * a unified interface for tool discovery and management.
+ */
+export abstract class Toolkit<TContext = UnknownContext> {
+  /**
+   * Unique identifier for this toolkit
+   */
+  abstract readonly id: string;
+
+  /**
+   * The agent this toolkit is bound to (if any)
+   */
+  protected agent?: Agent<TContext, any>;
+
+  /**
+   * Bind this toolkit to an agent.
+   * Called by Agent constructor.
+   */
+  bind(agent: Agent<TContext, any>): void {
+    this.agent = agent;
+  }
+
+  /**
+   * Get a specific tool by its ID.
+   *
+   * @param id The tool ID to look up
+   * @returns The tool if found, undefined otherwise
+   */
+  abstract get(id: string): Tool<TContext> | undefined;
+
+  /**
+   * List all tools available for the given context.
+   * If no context provided, returns all tools without filtering.
+   *
+   * @param context Optional context for filtering tools
+   * @returns Array of tools available in this toolkit
+   */
+  abstract list(context?: Context<TContext>): Promise<Tool<TContext>[]>;
+
+  /**
+   * Cleanup resources held by this toolkit.
+   * Override if your toolkit needs cleanup (e.g., closing connections).
+   * Default implementation does nothing.
+   */
+  async destroy(): Promise<void> {
+    // Default: no-op
+  }
+}
+
+/**
+ * A toolkit containing static function tools.
+ *
+ * @example
+ * ```ts
+ * const fs = new FunctionToolkit({
+ *   id: "fs",
+ *   tools: [readFile, writeFile, listDir, ...]
+ * });
+ * ```
+ */
+export class FunctionToolkit<
+  TContext = UnknownContext,
+> extends Toolkit<TContext> {
+  readonly id: string;
+  private tools: Map<string, Tool<TContext>>;
+
+  /**
+   * Create a new function toolkit.
+   *
+   * @param config Toolkit configuration with id and tools array
+   */
+  constructor(config: FunctionToolkitConfig<TContext>) {
+    super();
+    this.id = config.id;
+    this.tools = new Map(config.tools.map((t) => [t.id, t]));
+  }
+
+  /**
+   * Get a specific tool by ID.
+   *
+   * @param id The tool ID to look up
+   * @returns The tool if found, undefined otherwise
+   */
+  get(id: string): Tool<TContext> | undefined {
+    return this.tools.get(id);
+  }
+
+  /**
+   * List all tools in this toolkit.
+   *
+   * @param context Optional context for filtering tools (currently unused)
+   * @returns Array of all tools in this toolkit
+   */
+  async list(context?: Context<TContext>): Promise<Tool<TContext>[]> {
+    return Array.from(this.tools.values());
+  }
+}
+
+/*
+ * A toolkit that wraps an MCP server and provides tools from it.
+ *
+ * Handles connection lifecycle automatically - connects lazily on first tool request
+ * and provides cleanup via destroy().
+ *
+ * @example
+ * ```ts
+ * const server = new MCPServerStdio({
+ *   id: "github",
+ *   command: "npx",
+ *   args: ["-y", "@modelcontextprotocol/server-github"],
+ *   env: {
+ *     GITHUB_TOKEN: process.env.GITHUB_TOKEN,
+ *   },
+ * });
+ *
+ * const github = new MCPToolkit({
+ *   id: "github",
+ *   server,
+ *   filter: async (ctx, tool) => {
+ *     // Only allow certain tools
+ *     return !tool.id.startsWith("dangerous_");
+ *   },
+ * });
+ *
+ * const agent = new Agent({
+ *   toolkits: [github],
+ * });
+ * ```
+ */
+export class MCPToolkit<TContext = UnknownContext> extends Toolkit<TContext> {
+  readonly id: string;
+  private server: MCPServer;
+  private cache: Map<string, Tool<TContext>>;
+  private filter: ToolkitFilter<TContext>;
+
+  private connected = false;
+  private cached = false;
+
+  /**
+   * Create a new MCP toolkit.
+   *
+   * @param config Toolkit configuration with id and server instance
+   */
+  constructor(config: MCPToolkitConfig<TContext>) {
+    super();
+    this.id = config.id;
+    this.server = config.server;
+    this.filter = config.filter ?? (() => true);
+    this.cache = new Map();
+  }
+
+  /**
+   * Get a specific tool by ID.
+   *
+   * Returns the tool from the local cache. The cache is populated on the first
+   * call to list(). Returns undefined if list() hasn't been called yet.
+   *
+   * @param id The tool ID to look up
+   * @returns The tool if found in cache, undefined otherwise
+   */
+  get(id: string): Tool<TContext> | undefined {
+    return this.cache.get(id);
+  }
+
+  /**
+   * List all tools available from the MCP server.
+   *
+   * Connects to the server lazily on first call. Tools are cached locally after
+   * the first fetch. The MCP server itself also handles caching via the
+   * cacheToolsList option, so the network call is only made once.
+   *
+   * @param context Optional context for filtering tools
+   * @returns Array of tools from the MCP server
+   */
+  async list(context?: Context<TContext>): Promise<Tool<TContext>[]> {
+    if (!this.connected) {
+      await this.server.connect();
+      this.connected = true;
+    }
+
+    // lazy cache population
+    if (!this.cached) {
+      const mcpTools = await this.server.listTools();
+
+      for (const mcpTool of mcpTools) {
+        const tool = mcpToFunctionTool(this.server, mcpTool);
+        this.cache.set(tool.id, tool);
+      }
+
+      this.cached = true;
+    }
+
+    const tools = Array.from(this.cache.values());
+
+    // apply filter
+    if (context && this.agent) {
+      const ctx = { context, agent: this.agent, toolkitId: this.id };
+      return filter(tools, async (tool) => {
+        return await this.filter(ctx, tool);
+      });
+    }
+
+    return tools;
+  }
+
+  /**
+   * Cleanup resources and close the MCP server connection.
+   */
+  async destroy(): Promise<void> {
+    if (this.connected) {
+      await this.server.close();
+      this.connected = false;
+      this.cache.clear();
+      this.cached = false;
+    }
+  }
+}