kernl 0.1.1

package/dist/usage.js

@@ -0,0 +1,61 @@
+import { UsageData } from "./types/thread";
+/**
+ * Tracks token usage and request counts for an agent run.
+ */
+export class Usage {
+    /**
+     * The number of requests made to the LLM API.
+     */
+    requests;
+    /**
+     * The number of input tokens used across all requests.
+     */
+    inputTokens;
+    /**
+     * The number of output tokens used across all requests.
+     */
+    outputTokens;
+    /**
+     * The total number of tokens sent and received, across all requests.
+     */
+    totalTokens;
+    /**
+     * Details about the input tokens used across all requests.
+     */
+    inputTokensDetails = [];
+    /**
+     * Details about the output tokens used across all requests.
+     */
+    outputTokensDetails = [];
+    constructor(input) {
+        if (typeof input === "undefined") {
+            this.requests = 0;
+            this.inputTokens = 0;
+            this.outputTokens = 0;
+            this.totalTokens = 0;
+            this.inputTokensDetails = [];
+            this.outputTokensDetails = [];
+        }
+        else {
+            this.requests = input?.requests ?? 1;
+            this.inputTokens = input?.inputTokens ?? input?.input_tokens ?? 0;
+            this.outputTokens = input?.outputTokens ?? input?.output_tokens ?? 0;
+            this.totalTokens = input?.totalTokens ?? input?.total_tokens ?? 0;
+        }
+    }
+    add(newUsage) {
+        this.requests += newUsage.requests;
+        this.inputTokens += newUsage.inputTokens;
+        this.outputTokens += newUsage.outputTokens;
+        this.totalTokens += newUsage.totalTokens;
+        if (newUsage.inputTokensDetails) {
+            // The type does not allow undefined, but it could happen runtime
+            this.inputTokensDetails.push(...newUsage.inputTokensDetails);
+        }
+        if (newUsage.outputTokensDetails) {
+            // The type does not allow undefined, but it could happen runtime
+            this.outputTokensDetails.push(...newUsage.outputTokensDetails);
+        }
+    }
+}
+export { UsageData };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "kernl",
+  "version": "0.1.1",
+  "description": "A modern AI agent framework with MCP integration",
+  "keywords": [
+    "kernl",
+    "ai",
+    "agent",
+    "framework",
+    "mcp"
+  ],
+  "author": "dremnik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dremnik/kernl.git",
+    "directory": "packages/kernl"
+  },
+  "homepage": "https://github.com/dremnik/kernl#readme",
+  "bugs": {
+    "url": "https://github.com/dremnik/kernl/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "pino": "^9.6.0",
+    "zod": "^4.1.12",
+    "@kernl/protocol": "0.1.1",
+    "@kernl/shared": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "tsc-alias": "^1.8.10",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.8"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "dev": "tsc --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:run": "vitest run"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,203 @@
+import { LanguageModel, LanguageModelRequestSettings } from "@kernl/protocol";
+
+import type { Context, UnknownContext } from "./context";
+import { InputGuardrail, OutputGuardrail } from "./guardrail";
+import { AgentHooks } from "./lifecycle";
+import { Toolkit } from "./tool/toolkit";
+import { Tool } from "./tool";
+// import { DEFAULT_LANGUAGE_MODEL } from "@/providers/default";
+
+import { MisconfiguredError } from "./lib/error";
+
+import type { AgentConfig, AgentResponseType } from "./types/agent";
+import { TextResponse } from "./types/thread";
+
+export class Agent<
+    TContext = UnknownContext,
+    TResponse extends AgentResponseType = TextResponse,
+  >
+  extends AgentHooks<TContext, TResponse>
+  implements AgentConfig<TContext, TResponse>
+{
+  id: string;
+  name: string;
+  instructions: (context: Context<TContext>) => Promise<string> | string;
+
+  model: LanguageModel;
+  modelSettings: LanguageModelRequestSettings;
+  toolkits: Toolkit<TContext>[];
+
+  // --- (TODO) ---
+  // handoffDescription: string; // ??
+  // handoffs: (Agent<any, TResponse> | Handoff<any, TResponse>)[];
+  // ----------
+
+  // /* Process/thread-group–wide signal state shared by all threads in the group: shared pending signals, job control
+  // (stops/cont, group exit), rlimits, etc. */
+  // signal: *struct signal_struct;
+  //  /* Table of signal handlers (sa_handler, sa_mask, flags) shared by threads (CLONE_SIGHAND). RCU-protected so readers can access it locklessly. */
+  // sighand: *struct sighand_struct __rcu;
+
+  guardrails: {
+    input: InputGuardrail[];
+    output: OutputGuardrail<AgentResponseType>[];
+  };
+  responseType: TResponse = "text" as TResponse;
+  resetToolChoice: boolean;
+  // toolUseBehavior: ToolUseBehavior; (TODO)
+
+  // /**
+  //  * Create an Agent with handoffs and automatically infer the union type for TResponse from the handoff agents' response types.
+  //  */
+  // static create<
+  //   TResponse extends AgentResponseType = TextResponse,
+  //   Handoffs extends readonly (Agent<any, any> | Handoff<any, any>)[] = [],
+  // >(
+  //   config: AgentConfigWithHandoffs<TResponse, Handoffs>,
+  // ): Agent<UnknownContext, TResponse | HandoffsOutputUnion<Handoffs>> {
+  //   return new Agent<UnknownContext, TResponse | HandoffsOutputUnion<Handoffs>>(
+  //     {
+  //       ...config,
+  //       handoffs: config.handoffs as any,
+  //       responseType: config.responseType,
+  //       handoffresponseTypeWarningEnabled: false,
+  //     },
+  //   );
+  // }
+
+  constructor(config: AgentConfig<TContext, TResponse>) {
+    super();
+    if (config.id.trim() === "") {
+      throw new MisconfiguredError("Agent must have an id.");
+    }
+    this.id = config.id;
+    this.name = config.name;
+    this.instructions =
+      typeof config.instructions === "function"
+        ? config.instructions
+        : () => config.instructions as string;
+    this.model = config.model as LanguageModel; // TODO: Add default model
+    this.modelSettings = config.modelSettings ?? {};
+
+    this.toolkits = config.toolkits ?? [];
+    for (const toolkit of this.toolkits) {
+      toolkit.bind(this);
+    }
+
+    this.guardrails = config.guardrails ?? { input: [], output: [] };
+    if (config.responseType) {
+      this.responseType = config.responseType;
+    }
+    this.resetToolChoice = config.resetToolChoice ?? true;
+    // this.toolUseBehavior = config.toolUseBehavior ?? "run_llm_again";
+
+    // this.handoffDescription = config.handoffDescription ?? "";
+    // this.handoffs = config.handoffs ?? [];
+
+    // --- Runtime warning for handoff response type compatibility ---
+    // if (
+    //   config.handoffresponseTypeWarningEnabled === undefined ||
+    //   config.handoffresponseTypeWarningEnabled
+    // ) {
+    //   if (this.handoffs && this.responseType) {
+    //     const responseTypes = new Set<string>([
+    //       JSON.stringify(this.responseType),
+    //     ]);
+    //     for (const h of this.handoffs) {
+    //       if ("responseType" in h && h.responseType) {
+    //         responseTypes.add(JSON.stringify(h.responseType));
+    //       } else if ("agent" in h && h.agent.responseType) {
+    //         responseTypes.add(JSON.stringify(h.agent.responseType));
+    //       }
+    //     }
+    //     if (responseTypes.size > 1) {
+    //       logger.warn(
+    //         `[Agent] Warning: Handoff agents have different response types: ${Array.from(responseTypes).join(", ")}. You can make it type-safe by using Agent.create({ ... }) method instead.`,
+    //       );
+    //     }
+    //   }
+    // }
+  }
+
+  /**
+   * Get a specific tool by ID from all toolkits.
+   *
+   * @param id The tool ID to look up
+   * @returns The tool if found, undefined otherwise
+   */
+  tool(id: string): Tool<TContext> | undefined {
+    for (const toolkit of this.toolkits) {
+      const tool = toolkit.get(id);
+      if (tool) return tool;
+    }
+    return undefined;
+  }
+
+  /**
+   * Get all tools available from all toolkits for the given context.
+   * Checks for duplicate tool IDs across toolkits and throws an error if found.
+   *
+   * (TODO): Consider returning toolkits alongside tools so we can serialize them
+   * together and give agents more options for dealing with tool groups.
+   *
+   * @param context The context to use for filtering tools
+   * @returns Array of all available tools
+   * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
+   */
+  async tools(context: Context<TContext>): Promise<Tool<TContext>[]> {
+    const allTools: Tool<TContext>[] = [];
+    const toolIds = new Set<string>();
+
+    for (const toolkit of this.toolkits) {
+      const tools = await toolkit.list(context);
+
+      const duplicates = tools.map((t) => t.id).filter((id) => toolIds.has(id));
+      if (duplicates.length > 0) {
+        throw new MisconfiguredError(
+          `Duplicate tool IDs found across toolkits: ${duplicates.join(", ")}`,
+        );
+      }
+
+      tools.forEach((t) => toolIds.add(t.id));
+      allTools.push(...tools);
+    }
+
+    return allTools;
+  }
+
+  // async run<TContext>(
+  //   input: string,
+  //   options: SharedRunOptions<TContext>,
+  // ): Promise<RunResult<TContext>> {
+  //   // TODO
+  //   // ...
+  // }
+
+  // async stream<TContext>(
+  //   input: string,
+  //   options: StreamOptions<TContext>,
+  // ): Promise<StreamedRunResult<TContext>> {
+  //   // TODO
+  //   // ...
+  // }
+  //
+
+  // ----------------------
+  // Events
+  // ----------------------
+
+  // on(event: any, handler: Function): void {
+  //   // TODO
+  //   // ...
+  // }
+
+  // once(event: any, handler: Function): void {
+  //   // TODO
+  //   // ...
+  // }
+
+  // off(event: any, handler: Function): void {
+  //   // TODO
+  //   // ...
+  // }
+}

package/src/context.ts

@@ -0,0 +1,265 @@
+/**
+ * Status of a tool call approval.
+ */
+export type ApprovalStatus = "approved" | "rejected" | "pending";
+
+/**
+ * A propagation mechanism which carries execution-scoped values across API boundaries and between logically associated
+ * execution units.
+ */
+export class Context<TContext = UnknownContext> {
+  /**
+   * The inner context object.
+   */
+  context: TContext;
+
+  // ----------------------
+  // TEMPORARY: Tool approval tracking until actions system is refined
+  // ----------------------
+
+  /**
+   * Map of tool call IDs to their approval status.
+   * (TEMPORARY) Used until the actions system is refined.
+   */
+  approvals: Map<string, ApprovalStatus>;
+
+  /**
+   * Approve a tool call by its call ID.
+   * (TEMPORARY) Used until the actions system is refined.
+   */
+  approve(callId: string): void {
+    this.approvals.set(callId, "approved");
+  }
+
+  /**
+   * Reject a tool call by its call ID.
+   * (TEMPORARY) Used until the actions system is refined.
+   */
+  reject(callId: string): void {
+    this.approvals.set(callId, "rejected");
+  }
+
+  // ----------------------
+  // End temporary approval tracking
+  // ----------------------
+
+  // /**
+  //  * Serialization format in which to render the context to the agent
+  //  */
+  // private format: "md" | "yaml" | "json" | "html" | "xml";
+
+  // /**
+  //  * The usage of the agent run so far. For streamed responses, the usage will be stale until the
+  //  * last chunk of the stream is processed.
+  //  */
+  // usage: Usage;
+
+  // /**
+  //  * A map of tool names to whether they have been approved.
+  //  */
+  // #approvals: Map<string, ApprovalRecord>;
+
+  constructor(context: TContext = {} as TContext) {
+    this.context = context;
+    this.approvals = new Map();
+    // this.format = format; // (TODO): configure()
+    // this.usage = new Usage();
+    // this.#approvals = new Map();
+  }
+
+  /**
+   * Renders the context as a prompt using the default format selected. Kernel would inject this info automatically, but exposed in case of control
+   */
+  render(self: Context<TContext>): string {
+    throw new Error("UNIMPLEMENTED");
+    // switch (self.format) {
+    //   case "yaml":
+    //     return self.yaml();
+    //   // case "json":
+    //   //   return self.json();
+    //   // case "xml":
+    //   //   return self.xml();
+    //   case "md":
+    //   default:
+    //     return self.md();
+    // }
+  }
+
+  /**
+   * Render the context object as a markdown string:
+   *
+   *  <context>
+   *    <user>
+   *      <name>John</name>
+   *      <email>john@gmail.com</email>
+   *    </user>
+   *    <org>
+   *      <id>org_235234523</id>
+   *      <name>Acme Corp.<name>
+   *    </org>
+   *  </context>
+   *
+   */
+  md(): string {
+    throw new Error("UNIMPLEMENTED");
+  }
+
+  /**
+   *  Render the context object as a yaml string:
+   *
+   *  context:
+   *    user:
+   *      name: John
+   *      email: john@gmail.com
+   *    org:
+   *      id: org_235234523
+   *      name: Acme Corp.
+   */
+  yaml(): string {
+    throw new Error("UNIMPLEMENTED");
+  }
+
+  toJSON(): {
+    context: any;
+    // usage: Usage;
+    // approvals: Record<string, ApprovalRecord>;
+  } {
+    return {
+      context: this.context,
+      // usage: this.usage,
+      // approvals: Object.fromEntries(this.#approvals.entries()),
+    };
+  }
+
+  // /**
+  //  * Rebuild the approvals map from a serialized state.
+  //  * @internal
+  //  *
+  //  * @param approvals - The approvals map to rebuild.
+  //  */
+  // _rebuildApprovals(approvals: Record<string, ApprovalRecord>) {
+  //   this.#approvals = new Map(Object.entries(approvals));
+  // }
+
+  // /**
+  //  * Check if a tool call has been approved.
+  //  *
+  //  * @param approval - Details about the tool call being evaluated.
+  //  * @returns `true` if the tool call has been approved, `false` if blocked and `undefined` if not yet approved or rejected.
+  //  */
+  // isToolApproved(approval: { toolName: string; callId: string }) {
+  //   const { toolName, callId } = approval;
+  //   const approvalEntry = this.#approvals.get(toolName);
+  //   if (approvalEntry?.approved === true && approvalEntry.rejected === true) {
+  //     logger.warn(
+  //       "Tool is permanently approved and rejected at the same time. Approval takes precedence",
+  //     );
+  //     return true;
+  //   }
+
+  //   if (approvalEntry?.approved === true) {
+  //     return true;
+  //   }
+
+  //   if (approvalEntry?.rejected === true) {
+  //     return false;
+  //   }
+
+  //   const individualCallApproval = Array.isArray(approvalEntry?.approved)
+  //     ? approvalEntry.approved.includes(callId)
+  //     : false;
+  //   const individualCallRejection = Array.isArray(approvalEntry?.rejected)
+  //     ? approvalEntry.rejected.includes(callId)
+  //     : false;
+
+  //   if (individualCallApproval && individualCallRejection) {
+  //     logger.warn(
+  //       `Tool call ${callId} is both approved and rejected at the same time. Approval takes precedence`,
+  //     );
+  //     return true;
+  //   }
+
+  //   if (individualCallApproval) {
+  //     return true;
+  //   }
+
+  //   if (individualCallRejection) {
+  //     return false;
+  //   }
+
+  //   return undefined;
+  // }
+
+  // /**
+  //  * Approve a tool call.
+  //  *
+  //  * @param approvalItem - The tool approval item to approve.
+  //  * @param options - Additional approval behavior options.
+  //  */
+  // approveTool(
+  //   approvalItem: RunToolApprovalItem,
+  //   { alwaysApprove = false }: { alwaysApprove?: boolean } = {},
+  // ) {
+  //   const toolName = approvalItem.rawItem.name;
+  //   if (alwaysApprove) {
+  //     this.#approvals.set(toolName, {
+  //       approved: true,
+  //       rejected: [],
+  //     });
+  //     return;
+  //   }
+
+  //   const approvalEntry = this.#approvals.get(toolName) ?? {
+  //     approved: [],
+  //     rejected: [],
+  //   };
+  //   if (Array.isArray(approvalEntry.approved)) {
+  //     // function tool has call_id, hosted tool call has id
+  //     const callId =
+  //       "callId" in approvalItem.rawItem
+  //         ? approvalItem.rawItem.callId // function tools
+  //         : approvalItem.rawItem.id!; // hosted tools
+  //     approvalEntry.approved.push(callId);
+  //   }
+  //   this.#approvals.set(toolName, approvalEntry);
+  // }
+
+  // /**
+  //  * Reject a tool call.
+  //  *
+  //  * @param approvalItem - The tool approval item to reject.
+  //  */
+  // rejectTool(
+  //   approvalItem: RunToolApprovalItem,
+  //   { alwaysReject = false }: { alwaysReject?: boolean } = {},
+  // ) {
+  //   const toolName = approvalItem.rawItem.name;
+  //   if (alwaysReject) {
+  //     this.#approvals.set(toolName, {
+  //       approved: false,
+  //       rejected: true,
+  //     });
+  //     return;
+  //   }
+
+  //   const approvalEntry = this.#approvals.get(toolName) ?? {
+  //     approved: [] as string[],
+  //     rejected: [] as string[],
+  //   };
+
+  //   if (Array.isArray(approvalEntry.rejected)) {
+  //     // function tool has call_id, hosted tool call has id
+  //     const callId =
+  //       "callId" in approvalItem.rawItem
+  //         ? approvalItem.rawItem.callId // function tools
+  //         : approvalItem.rawItem.id!; // hosted tools
+  //     approvalEntry.rejected.push(callId);
+  //   }
+  //   this.#approvals.set(toolName, approvalEntry);
+  // }
+}
+
+/**
+ * Context that is being passed around as part of the session is unknown
+ */
+export type UnknownContext = unknown;