kernl 0.1.1

package/dist/tool/tool.d.ts

@@ -0,0 +1,95 @@
+import { Context, UnknownContext } from "../context";
+import type { LanguageModelTool } from "@kernl/protocol";
+import type { ToolConfig, ToolApprovalFunction, ToolEnabledFunction, ToolErrorFunction, 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 declare function tool<TContext = UnknownContext, TParameters extends ToolInputParameters = undefined, TResult = string>(config: ToolConfig<TContext, TParameters, TResult>): FunctionTool<TContext, TParameters, TResult>;
+/**
+ * Base class for all tools (function and hosted)
+ */
+export declare 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 declare class FunctionTool<TContext = UnknownContext, TParameters extends ToolInputParameters = undefined, TResult = unknown> extends BaseTool<TContext> {
+    readonly type: "function";
+    readonly id: string;
+    readonly name?: string;
+    readonly description: string;
+    readonly parameters?: TParameters;
+    readonly mode: "blocking" | "async";
+    private execute;
+    errorfn: ToolErrorFunction | null;
+    requiresApproval: ToolApprovalFunction<TParameters>;
+    isEnabled: ToolEnabledFunction<TContext>;
+    constructor(config: ToolConfig<TContext, TParameters, TResult>);
+    /**
+     * Main invocation method -
+     *
+     * Wraps execute with parsing, approval, and error handling
+     */
+    invoke(context: Context<TContext>, args: string, callId?: string): Promise<ToolResult<TResult>>;
+    /**
+     * Executes the tool with the provided execute() function
+     */
+    private _invoke;
+    /**
+     * Serialize this function tool for sending to the model
+     */
+    serialize(): LanguageModelTool;
+}
+/**
+ * Hosted tool executed server-side by the model provider
+ */
+export declare class HostedTool extends BaseTool {
+    readonly type: "hosted-tool";
+    readonly id: string;
+    readonly name?: string;
+    readonly providerData?: Record<string, any>;
+    /**
+     * Hosted tools use the default error function
+     */
+    errorfn: ToolErrorFunction | null;
+    /**
+     * Hosted tools do not require approval by default
+     */
+    requiresApproval: ToolApprovalFunction<any>;
+    constructor(config: {
+        id: string;
+        name?: string;
+        providerData?: Record<string, any>;
+    });
+    /**
+     * Hosted tools are always enabled
+     */
+    isEnabled(): Promise<boolean>;
+    /**
+     * Serialize this hosted tool for sending to the model
+     */
+    serialize(): LanguageModelTool;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tool/tool.ts"],"names":[],"mappings":"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"}

package/dist/tool/tool.js

@@ -0,0 +1,176 @@
+import { ModelBehaviorError } from "../lib/error";
+import { logger } from "../lib/logger";
+import { json } from "@kernl/shared/lib";
+import { FAILED, COMPLETED, INTERRUPTIBLE } from "@kernl/protocol";
+/**
+ * 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(config) {
+    return new FunctionTool(config);
+}
+/**
+ * Base class for all tools (function and hosted)
+ */
+export class BaseTool {
+}
+/**
+ * A function tool that can be used by agents.
+ */
+export class FunctionTool extends BaseTool {
+    type = "function";
+    id;
+    name;
+    description;
+    parameters;
+    mode;
+    execute;
+    errorfn;
+    requiresApproval;
+    isEnabled;
+    constructor(config) {
+        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;
+                    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, args, callId) {
+        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
+     */
+    async _invoke(context, args, callId) {
+        let parsed = args;
+        if (this.parameters) {
+            try {
+                parsed = json(this.parameters).decode(args);
+            }
+            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() {
+        return {
+            kind: "function",
+            name: this.id,
+            description: this.description,
+            parameters: this.parameters, // TODO: convert Zod to JSON Schema
+        };
+    }
+}
+/**
+ * Hosted tool executed server-side by the model provider
+ */
+export class HostedTool extends BaseTool {
+    type = "hosted-tool";
+    id;
+    name;
+    providerData;
+    /**
+     * Hosted tools use the default error function
+     */
+    errorfn = defaultToolErrorFunction;
+    /**
+     * Hosted tools do not require approval by default
+     */
+    requiresApproval = async () => false;
+    constructor(config) {
+        super();
+        this.id = config.id;
+        this.name = config.name;
+        this.providerData = config.providerData;
+    }
+    /**
+     * Hosted tools are always enabled
+     */
+    async isEnabled() {
+        return true;
+    }
+    /**
+     * Serialize this hosted tool for sending to the model
+     */
+    serialize() {
+        return {
+            kind: "provider-defined",
+            id: this.id,
+            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, error) {
+    const details = error instanceof Error ? error.toString() : String(error);
+    return `An error occurred while running the tool. Please try again. Error: ${details}`;
+}

package/dist/tool/toolkit.d.ts

@@ -0,0 +1,121 @@
+import type { Agent } from "../agent";
+import type { Context, UnknownContext } from "../context";
+import type { Tool } from ".";
+import type { FunctionToolkitConfig, MCPToolkitConfig } 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 declare 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;
+    /**
+     * 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.
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * A toolkit containing static function tools.
+ *
+ * @example
+ * ```ts
+ * const fs = new FunctionToolkit({
+ *   id: "fs",
+ *   tools: [readFile, writeFile, listDir, ...]
+ * });
+ * ```
+ */
+export declare class FunctionToolkit<TContext = UnknownContext> extends Toolkit<TContext> {
+    readonly id: string;
+    private tools;
+    /**
+     * Create a new function toolkit.
+     *
+     * @param config Toolkit configuration with id and tools array
+     */
+    constructor(config: FunctionToolkitConfig<TContext>);
+    /**
+     * 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;
+    /**
+     * List all tools in this toolkit.
+     *
+     * @param context Optional context for filtering tools (currently unused)
+     * @returns Array of all tools in this toolkit
+     */
+    list(context?: Context<TContext>): Promise<Tool<TContext>[]>;
+}
+export declare class MCPToolkit<TContext = UnknownContext> extends Toolkit<TContext> {
+    readonly id: string;
+    private server;
+    private cache;
+    private filter;
+    private connected;
+    private cached;
+    /**
+     * Create a new MCP toolkit.
+     *
+     * @param config Toolkit configuration with id and server instance
+     */
+    constructor(config: MCPToolkitConfig<TContext>);
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    list(context?: Context<TContext>): Promise<Tool<TContext>[]>;
+    /**
+     * Cleanup resources and close the MCP server connection.
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=toolkit.d.ts.map

package/dist/tool/toolkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../../src/tool/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;AAC9B,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,8BAAsB,OAAO,CAAC,QAAQ,GAAG,cAAc;IACrD;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAEvC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,IAAI;IAIvC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAEpD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAErE;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe,CAC1B,QAAQ,GAAG,cAAc,CACzB,SAAQ,OAAO,CAAC,QAAQ,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,KAAK,CAA8B;IAE3C;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC;IAMnD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;CAGnE;AAiCD,qBAAa,UAAU,CAAC,QAAQ,GAAG,cAAc,CAAE,SAAQ,OAAO,CAAC,QAAQ,CAAC;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAA0B;IAExC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IAQ9C;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IA+BlE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}

package/dist/tool/toolkit.js

@@ -0,0 +1,180 @@
+import { mcpToFunctionTool } from "../mcp/utils";
+import { filter } from "@kernl/shared/lib";
+/**
+ * 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 class Toolkit {
+    /**
+     * The agent this toolkit is bound to (if any)
+     */
+    agent;
+    /**
+     * Bind this toolkit to an agent.
+     * Called by Agent constructor.
+     */
+    bind(agent) {
+        this.agent = agent;
+    }
+    /**
+     * Cleanup resources held by this toolkit.
+     * Override if your toolkit needs cleanup (e.g., closing connections).
+     * Default implementation does nothing.
+     */
+    async destroy() {
+        // Default: no-op
+    }
+}
+/**
+ * A toolkit containing static function tools.
+ *
+ * @example
+ * ```ts
+ * const fs = new FunctionToolkit({
+ *   id: "fs",
+ *   tools: [readFile, writeFile, listDir, ...]
+ * });
+ * ```
+ */
+export class FunctionToolkit extends Toolkit {
+    id;
+    tools;
+    /**
+     * Create a new function toolkit.
+     *
+     * @param config Toolkit configuration with id and tools array
+     */
+    constructor(config) {
+        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) {
+        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) {
+        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 extends Toolkit {
+    id;
+    server;
+    cache;
+    filter;
+    connected = false;
+    cached = false;
+    /**
+     * Create a new MCP toolkit.
+     *
+     * @param config Toolkit configuration with id and server instance
+     */
+    constructor(config) {
+        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) {
+        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) {
+        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() {
+        if (this.connected) {
+            await this.server.close();
+            this.connected = false;
+            this.cache.clear();
+            this.cached = false;
+        }
+    }
+}