kernl 0.1.1

package/src/tool/types.ts

@@ -0,0 +1,243 @@
+import { z, type ZodType } from "zod";
+
+import { Agent } from "@/agent";
+import { Context, UnknownContext } from "@/context";
+import { MCPServer } from "@/mcp/base";
+import type { ToolCallState } from "@kernl/protocol";
+
+import type { FunctionTool, HostedTool } from "./tool";
+
+/**
+ * A tool that can be called by the model.
+ * @template TContext The context passed to the tool
+ */
+export type Tool<TContext = UnknownContext> =
+  | FunctionTool<TContext, any, any>
+  | HostedTool;
+
+/**
+ * Configuration options for creating a tool.
+ *
+ * @param TContext The context of the tool
+ * @param TParameters The parameters of the tool
+ * @param TResult The result type of the tool
+ */
+export type ToolConfig<
+  TContext = UnknownContext,
+  TParameters extends ToolInputParameters = undefined,
+  TResult = unknown,
+> = {
+  /**
+   * Unique identifier for the tool (required)
+   */
+  id: string;
+
+  /**
+   * Optional friendly name for the tool
+   */
+  name?: string;
+
+  /**
+   * The description of the tool that helps the model understand when to use it.
+   */
+  description: string;
+
+  /**
+   * A Zod object schema describing the tool parameters, or undefined for string input.
+   */
+  parameters: TParameters;
+
+  /**
+   * Execution mode - 'blocking' waits for completion, 'async' lets the agent continue to execute while executing.
+   * Defaults to 'blocking'.
+   */
+  mode?: "blocking" | "async";
+
+  /**
+   * The function to invoke when the tool is called.
+   */
+  execute: ToolExecuteFunction<TContext, TParameters, TResult>;
+
+  /**
+   * The function to invoke when an error occurs while running the tool.
+   */
+  errorfn?: ToolErrorFunction | null;
+
+  /**
+   * Whether the tool requires human approval before it can be called.
+   */
+  requiresApproval?: boolean | ToolApprovalFunction<TParameters>;
+
+  /**
+   * Determines whether the tool should be exposed to the model for the current run.
+   */
+  isEnabled?: ToolEnabledOption<TContext>;
+};
+
+/**
+ * Context provided to toolkit filters during tool resolution.
+ */
+export interface ToolkitFilterContext<TContext = UnknownContext> {
+  context: Context<TContext>;
+  agent: Agent<TContext, any>;
+  toolkitId: string;
+}
+
+/**
+ * Toolkit-level filter for tools.
+ *
+ * Operates at the application layer on converted Tool objects.
+ * Use this for dynamic, context-aware filtering based on runtime state
+ * (e.g., user permissions, current workflow, etc.).
+ *
+ * This is the second filter in the pipeline (after MCPToolFilter for MCP tools).
+ *
+ * @example
+ * ```typescript
+ * const toolkit = new MCPToolkit({
+ *   id: "github",
+ *   server: githubServer,
+ *   filter: async (ctx, tool) => {
+ *     // Only allow read tools for non-admin users
+ *     if (!ctx.context.data.isAdmin) {
+ *       return tool.id.startsWith("read_");
+ *     }
+ *     return true;
+ *   }
+ * });
+ * ```
+ */
+export type ToolkitFilter<TContext = UnknownContext> = (
+  context: ToolkitFilterContext<TContext>,
+  tool: Tool<TContext>,
+) => Promise<boolean> | boolean;
+
+/**
+ * Configuration for FunctionToolkit.
+ */
+export interface FunctionToolkitConfig<TContext = UnknownContext> {
+  /**
+   * Unique identifier for this toolkit.
+   */
+  id: string;
+
+  /**
+   * Array of tools to include in this toolkit.
+   */
+  tools: Tool<TContext>[];
+}
+
+/**
+ * Configuration for MCPToolkit.
+ */
+export interface MCPToolkitConfig<TContext = UnknownContext> {
+  /**
+   * Unique identifier for this toolkit.
+   */
+  id: string;
+
+  /**
+   * The MCP server instance to wrap.
+   */
+  server: MCPServer;
+
+  /**
+   * Toolkit-level filter to control which tools are exposed to the agent.
+   * Defaults to allowing all tools if not provided.
+   *
+   * This is applied after the server's toolFilter (if any). Use this for
+   * dynamic, context-aware filtering. Use server.toolFilter for static filtering.
+   */
+  filter?: ToolkitFilter<TContext>;
+}
+
+/**
+ * Type of tool
+ */
+export type ToolType = "function" | "hosted-tool";
+
+/**
+ * The result of invoking a function tool. Either the actual output of the execution or a tool
+ * approval request.
+ *
+ * These get passed for example to the `toolUseBehavior` option of the `Agent` constructor.
+ */
+export type ToolResult<TResult = unknown> = {
+  state: ToolCallState;
+  /**
+   * The result of the tool call.
+   */
+  result: TResult | undefined;
+  /**
+   * Error message if state is "error"
+   */
+  error: string | null;
+};
+
+/**
+ * The parameters of a tool.
+ * Either undefined (tool takes string input) or a Zod schema.
+ */
+export type ToolInputParameters = ZodType | undefined;
+
+/**
+ * The arguments to a tool - inferred from the Zod schema or string.
+ */
+export type ToolExecuteArgument<TParameters extends ToolInputParameters> =
+  TParameters extends ZodType ? z.infer<TParameters> : string;
+
+/**
+ * The function to invoke when the tool is called.
+ *
+ * @param context An instance of the current RunContext
+ * @param params The arguments to the tool (see ToolExecuteArgument)
+ */
+export type ToolExecuteFunction<
+  TContext = UnknownContext,
+  TParameters extends ToolInputParameters = undefined,
+  TResult = unknown,
+> = (
+  context: Context<TContext>,
+  params: ToolExecuteArgument<TParameters>,
+) => Promise<TResult> | TResult;
+
+/**
+ * A function that determines if a tool call should be approved.
+ *
+ * @param context The current execution context
+ * @param input The input to the tool
+ * @param callId The ID of the tool call
+ * @returns True if the tool call should be approved, false otherwise
+ */
+export type ToolApprovalFunction<TParameters extends ToolInputParameters> = (
+  context: Context,
+  input: ToolExecuteArgument<TParameters>,
+  callId?: string,
+) => Promise<boolean>;
+
+export type ToolEnabledFunction<TContext = UnknownContext> = (
+  context: Context<TContext>,
+  agent: Agent<any, any>, // (TODO): why would we need to take an agent here?
+) => Promise<boolean>;
+
+export type ToolEnabledPredicate<TContext = UnknownContext> = (args: {
+  context: Context<TContext>;
+  agent: Agent<any, any>; // (TODO): why take an agent here? other options?
+}) => boolean | Promise<boolean>;
+
+type ToolEnabledOption<Context = UnknownContext> =
+  | boolean
+  | ToolEnabledPredicate<Context>;
+
+/**
+ * The function to invoke when an error occurs while running the tool. This can be used to define
+ * what the model should receive as tool output in case of an error. It can be used to provide
+ * for example additional context or a fallback value.
+ *
+ * @param context An instance of the current RunContext
+ * @param error The error that occurred
+ */
+export type ToolErrorFunction = (
+  context: Context,
+  error: Error | unknown,
+) => string;

package/src/trace/traces.ts

@@ -0,0 +1,86 @@
+// import { defaultProcessor, TracingProcessor } from "./processor";
+// import { generateTraceId } from "./utils";
+
+// export type TraceOptions = {
+//   traceId?: string;
+//   name?: string;
+//   groupId?: string;
+//   metadata?: Record<string, any>;
+//   started?: boolean;
+// };
+
+// export class Trace {
+//   public type = "trace" as const;
+//   public traceId: string;
+//   public name: string;
+//   public groupId: string | null = null;
+//   public metadata?: Record<string, any>;
+
+//   #processor: TracingProcessor;
+//   #started: boolean;
+
+//   constructor(options: TraceOptions, processor?: TracingProcessor) {
+//     this.traceId = options.traceId ?? generateTraceId();
+//     this.name = options.name ?? "Agent workflow";
+//     this.groupId = options.groupId ?? null;
+//     this.metadata = options.metadata ?? {};
+//     this.#processor = processor ?? defaultProcessor();
+//     this.#started = options.started ?? false;
+//   }
+
+//   async start() {
+//     if (this.#started) {
+//       return;
+//     }
+
+//     this.#started = true;
+//     await this.#processor.onTraceStart(this);
+//   }
+
+//   async end() {
+//     if (!this.#started) {
+//       return;
+//     }
+
+//     this.#started = false;
+//     await this.#processor.onTraceEnd(this);
+//   }
+
+//   clone(): Trace {
+//     return new Trace({
+//       traceId: this.traceId,
+//       name: this.name,
+//       groupId: this.groupId ?? undefined,
+//       metadata: this.metadata,
+//       started: this.#started,
+//     });
+//   }
+
+//   toJSON(): object | null {
+//     return {
+//       object: this.type,
+//       id: this.traceId,
+//       workflow_name: this.name, // (TODO): why workflow?
+//       group_id: this.groupId,
+//       metadata: this.metadata,
+//     };
+//   }
+// }
+
+// export class NoopTrace extends Trace {
+//   constructor() {
+//     super({});
+//   }
+
+//   async start(): Promise<void> {
+//     return;
+//   }
+
+//   async end(): Promise<void> {
+//     return;
+//   }
+
+//   toJSON(): object | null {
+//     return null;
+//   }
+// }

package/src/trace/utils.ts

@@ -0,0 +1,38 @@
+import { randomID } from "@kernl/shared/lib";
+
+/**
+ * Generate a trace ID using 16 random bytes (128-bit, 32 hex chars).
+ * @returns A trace ID prefixed with `trace_`.
+ */
+export function generateTraceId(): string {
+  return `trace_${randomID(16)}`;
+}
+
+/**
+ * Generate a span ID using 12 random bytes (96-bit, 24 hex chars).
+ * @returns A span ID prefixed with `span_`.
+ */
+export function generateSpanId(): string {
+  return `span_${randomID(12)}`;
+}
+
+/**
+ * Generate a group ID using 12 random bytes (96-bit, 24 hex chars).
+ * @returns A group ID prefixed with `group_`.
+ */
+export function generateGroupId(): string {
+  return `group_${randomID(12)}`;
+}
+
+/**
+ * Remove fields that start with an underscore from an object.
+ * @param obj - The object to remove private fields from.
+ * @returns A new object with private fields removed.
+ */
+export function removePrivateFields(
+  obj: Record<string, any>,
+): Record<string, any> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key]) => !key.startsWith("_")),
+  );
+}

package/src/types/agent.ts

@@ -0,0 +1,145 @@
+import { type ZodType } from "zod";
+
+import { Context, UnknownContext } from "@/context";
+import { LanguageModel, LanguageModelRequestSettings } from "@kernl/protocol";
+import { InputGuardrail, OutputGuardrail } from "@/guardrail";
+import { Toolkit } from "@/tool";
+
+import { TextResponse } from "./thread";
+
+/**
+ * Configuration for an agent.
+ */
+export interface AgentConfig<
+  TContext = UnknownContext,
+  TResponse extends AgentResponseType = TextResponse,
+> {
+  /* The unique identifier for the agent */
+  id: string;
+
+  /* The name of the agent (defaults to ID if not provided) */
+  name: string;
+
+  /**
+   * The instructions for the agent. Will be used as the "system prompt" when this agent is
+   * invoked. Describes what the agent should do, and how it responds.
+   *
+   * Can either be a string, or a function that dynamically generates instructions for the agent.
+   * If you provide a function, it will be called with the context and the agent instance. It
+   * must return a string.
+   */
+  instructions:
+    | string
+    | ((context: Context<TContext>) => Promise<string> | string);
+
+  // /**
+  //  * A description of the agent. This is used when the agent is used as a handoff, so that an LLM
+  //  * knows what it does and when to invoke it.
+  //  */
+  // handoffDescription: string;
+
+  // /**
+  //  * Handoffs are sub-agents that the agent can delegate to. You can provide a list of handoffs,
+  //  * and the agent can choose to delegate to them if relevant. Allows for separation of concerns
+  //  * and modularity.
+  //  */
+  // handoffs: (Agent<any, any> | Handoff<any, TResponse>)[];
+
+  /**
+   * The model implementation to use when invoking the LLM.
+   *
+   * By default, if not set, the agent will use a default model that throws an error when called.
+   */
+  model?: LanguageModel;
+
+  /**
+   * Configures model-specific tuning parameters (e.g. temperature, top_p, etc.)
+   */
+  modelSettings?: LanguageModelRequestSettings;
+
+  /**
+   * A list of toolkits the agent can use. Toolkits are collections of related tools
+   * that can be static (FunctionToolkit) or dynamic (MCPToolkit).
+   *
+   * @example
+   * ```typescript
+   * const myTools = new FunctionToolkit({
+   *   id: "custom",
+   *   tools: [tool1, tool2]
+   * });
+   *
+   * const github = new MCPToolkit({
+   *   id: "github",
+   *   server: githubServer
+   * });
+   *
+   * const agent = new Agent({
+   *   name: "Assistant",
+   *   instructions: "...",
+   *   toolkits: [myTools, github]
+   * });
+   * ```
+   */
+  toolkits?: Toolkit<TContext>[];
+
+  /**
+   * A list of checks that run in parallel to the agent's execution on the input + output for the agent,
+   * depending on the configuration.
+   */
+  guardrails?: AgentGuardrails<TResponse>;
+
+  /**
+   * The type of the response that the agent will return. If not provided, response will be a string.
+   */
+  responseType?: TResponse;
+
+  // /**
+  //  * (TODO): Not sure if this is really necessary.. need to see use case examples
+  //  *
+  //  * This lets you configure how tool use is handled.
+  //  * - `run_llm_again`: The default behavior. Tools are run, and then the LLM receives the results
+  //  *   and gets to respond.
+  //  * - `stop_on_first_tool`: The output of the first tool call is used as the final output. This means
+  //  *   that the LLM does not process the result of the tool call.
+  //  * - A list of tool names: The agent will stop running if any of the tools in the list are called.
+  //  *   The final output will be the output of the first matching tool call. The LLM does not process
+  //  *   the result of the tool call.
+  //  * - A function: if you pass a function, it will be called with the run context and the list of
+  //  *   tool results. It must return a `ToolsToFinalOutputResult`, which determines whether the tool
+  //  *   call resulted in a final output.
+  //  *
+  //  * NOTE: This configuration is specific to `FunctionTools`. Hosted tools, such as file search, web
+  //  * search, etc. are always processed by the LLM
+  //  */
+  // toolUseBehavior: ToolUseBehavior;
+
+  /**
+   * Whether to reset the tool choice to the default value after a tool has been called. Defaults
+   * to `true`. This ensures that the agent doesn't enter an infinite loop of tool usage.
+   */
+  resetToolChoice?: boolean;
+}
+
+/**
+ * Guardrails for an agent.
+ */
+export interface AgentGuardrails<
+  TResponse extends AgentResponseType = TextResponse,
+> {
+  /**
+   * A list of checks that run in parallel to the agent's execution, before generating a response.
+   * Runs only if the agent is the first agent in the chain.
+   */
+  input: InputGuardrail[];
+  /**
+   * A list of checks that run on the final output of the agent, after generating a response. Runs
+   * only if the agent produces a final output.
+   */
+  output: OutputGuardrail<TResponse>[];
+}
+
+/**
+ * The type of the output object. If not provided, the output will be a string.
+ * 'text' is a special type that indicates the output will be a string.
+ */
+export type AgentResponseType = TextResponse | ZodType;

package/src/types/thread.ts

@@ -0,0 +1,86 @@
+import {
+  ToolCall,
+  LanguageModel,
+  LanguageModelItem,
+  LanguageModelStreamEvent,
+} from "@kernl/protocol";
+
+import { Task } from "@/task";
+import { Context } from "@/context";
+
+/**
+ * Thread-specific tool call state for approval workflow.
+ * This extends the protocol states for internal thread use.
+ */
+export const REQUIRES_APPROVAL = "requires_approval";
+
+/**
+ * ThreadEvent uses protocol types directly.
+ *
+ * (TODO): just an alias for LanguageModelItem for now, but there may be other thread events later
+ * which don't go to the model.
+ */
+export type ThreadEvent = LanguageModelItem;
+
+/**
+ * Stream events - use protocol definition directly.
+ */
+export type ThreadStreamEvent = LanguageModelStreamEvent;
+
+/**
+ * Set of actionable items extracted from a model response
+ */
+export interface ActionSet {
+  toolCalls: ToolCall[];
+  // Future: other actions, mcpRequests, etc.
+}
+
+/**
+ * Result of a single tick of execution
+ */
+export interface TickResult {
+  /**
+   * Events to add to thread history
+   */
+  events: ThreadEvent[];
+  /**
+   * Action intentions that need to be performed as a result of this tick
+   */
+  intentions: ActionSet | null;
+}
+
+/**
+ * Result of performing actions, including both executed results and pending approvals
+ */
+export interface PerformActionsResult {
+  /**
+   * Action events generated from executing tools (tool results)
+   */
+  actions: ThreadEvent[];
+  /**
+   * Tool calls that require approval before execution
+   */
+  pendingApprovals: ToolCall[];
+}
+
+/**
+ * Result of thread execution
+ */
+export interface ThreadExecuteResult<TResponse = any> {
+  /**
+   * The final parsed response from the agent
+   */
+  response: TResponse;
+  /**
+   * The thread state at completion
+   */
+  state: any; // Will be ThreadState, but avoiding circular dependency
+}
+
+export interface ThreadOptions<TContext> {
+  context: Context<TContext>;
+  task?: Task<TContext>;
+  model?: LanguageModel;
+}
+
+export type TextResponse = "text";

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+import path from "path";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+  },
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+});