kernl 0.2.0 → 0.6.0

package/src/context.ts

@@ -8,6 +8,11 @@ export type ApprovalStatus = "approved" | "rejected" | "pending";
  * execution units.
  */
 export class Context<TContext = UnknownContext> {
+  /**
+   * The namespace that this context belongs to.
+   */
+  namespace: string;
+  
   /**
    * The inner context object.
    */
@@ -59,7 +64,11 @@ export class Context<TContext = UnknownContext> {
   //  */
   // #approvals: Map<string, ApprovalRecord>;
 
-  constructor(context: TContext = {} as TContext) {
+  constructor(
+    namespace: string = "kernl",
+    context: TContext = {} as TContext,
+  ) {
+    this.namespace = namespace;
     this.context = context;
     this.approvals = new Map();
     // this.format = format; // (TODO): configure()

package/src/index.ts

@@ -1,4 +1,52 @@
 export { Kernl } from "./kernl";
+export type {
+  KernlOptions,
+  StorageOptions,
+  AgentRegistry,
+  ModelRegistry,
+} from "./types/kernl";
 export { Agent } from "./agent";
-export type { Context } from "./context";
+export { Context } from "./context";
+
+// --- tools --
 export { tool, Toolkit, FunctionToolkit, MCPToolkit } from "./tool";
+export { MCPServerSSE } from "./mcp/sse";
+export { MCPServerStdio } from "./mcp/stdio";
+export { MCPServerStreamableHttp } from "./mcp/http";
+
+// --- thread models ---
+export type {
+  MThread as Thread,
+  MThreadEvent as ThreadEvent,
+  MThreadEventBase as ThreadEventBase,
+} from "./api/models";
+
+// --- thread resource types ---
+export type {
+  RThreadsListParams as ThreadsListParams,
+  RThreadGetOptions as ThreadGetOptions,
+  RThreadHistoryParams as ThreadHistoryParams,
+  RThreadCreateParams as ThreadCreateParams,
+  RThreadUpdateParams as ThreadUpdateParams,
+} from "./api/resources/threads";
+
+// --- thread state enums ---
+export {
+  THREAD_STATES,
+  type ThreadState,
+  type PublicThreadEvent,
+} from "./types/thread";
+
+// --- storage types ---
+export type {
+  ThreadStore,
+  NewThread,
+  ThreadUpdate,
+  ThreadFilter,
+  ThreadHistoryOptions,
+  ThreadInclude,
+  ThreadListOptions,
+  SortOrder,
+  KernlStorage,
+  Transaction,
+} from "./storage";

package/src/internal.ts

@@ -0,0 +1,15 @@
+export { Thread } from "./thread/thread";
+
+export type {
+  IThread,
+  ThreadEvent,
+  ThreadEventBase,
+  ThreadEventInner,
+  ThreadSystemEvent,
+  ThreadState,
+  PublicThreadEvent,
+} from "./types/thread";
+
+export { THREAD_STATES } from "./types/thread";
+
+

package/src/kernl.ts

@@ -1,21 +1,41 @@
-import { Agent } from "./agent";
-import { UnknownContext } from "./context";
-import { KernlHooks } from "./lifecycle";
-import type { Thread } from "./thread";
+import type { LanguageModel } from "@kernl-sdk/protocol";
 
-import type { AgentResponseType } from "./types/agent";
-import type { ThreadExecuteResult, ThreadStreamEvent } from "./types/thread";
-import type { ResolvedAgentResponse } from "./guardrail";
+import { Agent } from "@/agent";
+import { UnknownContext } from "@/context";
+import { KernlHooks } from "@/lifecycle";
+import type { Thread } from "@/thread";
+import type { ResolvedAgentResponse } from "@/guardrail";
+import { InMemoryStorage, type KernlStorage } from "@/storage";
+import { RThreads } from "@/api/resources/threads";
+
+import type { KernlOptions } from "@/types/kernl";
+import type { ThreadExecuteResult, ThreadStreamEvent } from "@/types/thread";
+import type { AgentResponseType } from "@/types/agent";
 
 /**
- * The kernl - manages agent processes, scheduling, and task lifecycle
+ * The kernl - manages agent processes, scheduling, and task lifecycle.
  *
  * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
  * tracing.
  */
 export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
   private agents: Map<string, Agent> = new Map();
-  threads: Map<string, Thread<any, any>> = new Map();
+  private models: Map<string, LanguageModel> = new Map();
+
+  readonly storage: KernlStorage;
+  athreads: Map<string, Thread<any, any>> = new Map(); /* active threads */
+
+  private initPromise: Promise<void> | null = null;
+
+  // --- public API ---
+  readonly threads: RThreads; /* Threads resource */
+
+  constructor(options: KernlOptions = {}) {
+    super();
+    this.storage = options.storage?.db ?? new InMemoryStorage();
+    this.storage.bind({ agents: this.agents, models: this.models });
+    this.threads = new RThreads(this.storage.threads);
+  }
 
   /**
    * Registers a new agent with the kernl instance.
@@ -23,6 +43,14 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
   register(agent: Agent): void {
     this.agents.set(agent.id, agent);
     agent.bind(this);
+
+    // (TODO): implement exhaustive model registry in protocol/ package
+    //
+    // auto-populate model registry for storage hydration
+    const key = `${agent.model.provider}/${agent.model.modelId}`;
+    if (!this.models.has(key)) {
+      this.models.set(key, agent.model);
+    }
   }
 
   /**
@@ -31,8 +59,13 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
   async spawn<TContext, TResponse extends AgentResponseType>(
     thread: Thread<TContext, TResponse>,
   ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
-    this.threads.set(thread.id, thread);
-    return await thread.execute();
+    await this.ensureInitialized();
+    this.athreads.set(thread.tid, thread);
+    try {
+      return await thread.execute();
+    } finally {
+      this.athreads.delete(thread.tid);
+    }
   }
 
   /**
@@ -43,29 +76,65 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
   async schedule<TContext, TResponse extends AgentResponseType>(
     thread: Thread<TContext, TResponse>,
   ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
-    return await thread.execute();
+    await this.ensureInitialized();
+    this.athreads.set(thread.tid, thread);
+    try {
+      return await thread.execute();
+    } finally {
+      this.athreads.delete(thread.tid);
+    }
   }
 
   /**
-   * (TMP) - probably won't make sense with assync scheduling contexts
+   * (TMP) - won't make sense in async scheduling contexts
    *
    * Spawn a new thread - streaming execution
    */
   async *spawnStream<TContext, TResponse extends AgentResponseType>(
     thread: Thread<TContext, TResponse>,
   ): AsyncIterable<ThreadStreamEvent> {
-    this.threads.set(thread.id, thread);
-    yield* thread.stream();
+    await this.ensureInitialized();
+    this.athreads.set(thread.tid, thread);
+    try {
+      yield* thread.stream();
+    } finally {
+      this.athreads.delete(thread.tid);
+    }
   }
 
   /**
-   * (TMP) - probably won't make sense with assync scheduling contexts
+   * (TMP) - won't make sense with async scheduling contexts
    *
    * Schedule an existing thread - streaming execution
    */
   async *scheduleStream<TContext, TResponse extends AgentResponseType>(
     thread: Thread<TContext, TResponse>,
   ): AsyncIterable<ThreadStreamEvent> {
-    yield* thread.stream();
+    await this.ensureInitialized();
+    this.athreads.set(thread.tid, thread);
+    try {
+      yield* thread.stream();
+    } finally {
+      this.athreads.delete(thread.tid);
+    }
+  }
+
+  /**
+   * Ensure the underlying storage backend has been initialized.
+   *
+   * This is called lazily on first use so that callers do not need to worry
+   * about calling storage.init() themselves. Safe and idempotent to call
+   * multiple times; concurrent calls share the same initialization promise.
+   */
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initPromise) {
+      this.initPromise = this.storage.init().catch((error) => {
+        // allow a retry if initialization fails.
+        this.initPromise = null;
+        throw error;
+      });
+    }
+
+    await this.initPromise;
   }
 }

package/src/mcp/__tests__/integration.test.ts

@@ -7,7 +7,6 @@ import { Agent } from "@/agent";
 import { Context } from "@/context";
 import { tool } from "@/tool";
 import { z } from "zod";
-import { Thread } from "@/thread";
 import { createMCPToolStaticFilter } from "../utils";
 import { createMockModel } from "@/thread/__tests__/fixtures/mock-model";
 
@@ -171,7 +170,7 @@ describe("MCP Integration Tests", () => {
         toolkits: [toolkit],
       });
 
-      const context = new Context({});
+      const context = new Context("test-namespace", {});
       const tools = await toolkit.list(context);
 
       // Should have 3 math tools only
@@ -208,7 +207,7 @@ describe("MCP Integration Tests", () => {
         toolkits: [toolkit],
       });
 
-      const context = new Context({});
+      const context = new Context("test-namespace", {});
       const tools = await toolkit.list(context);
 
       // Should have only add and divide (multiply blocked by toolkit filter)
@@ -247,7 +246,7 @@ describe("MCP Integration Tests", () => {
         toolkits: [toolkit],
       });
 
-      const context = new Context({ userId: "test-user" });
+      const context = new Context("test-namespace", { userId: "test-user" });
       await toolkit.list(context);
 
       // Verify context was passed correctly
@@ -281,7 +280,7 @@ describe("MCP Integration Tests", () => {
         toolkits: [mcpToolkit],
       });
 
-      const context = new Context({});
+      const context = new Context("test-namespace", {});
       const tools = await agent.tools(context);
 
       expect(tools.length).toBe(6);
@@ -312,7 +311,7 @@ describe("MCP Integration Tests", () => {
       });
 
       // Populate toolkit cache
-      const context = new Context({});
+      const context = new Context("test-namespace", {});
       await agent.tools(context);
 
       // Now get specific tool
@@ -343,7 +342,7 @@ describe("MCP Integration Tests", () => {
         toolkits: [mcpToolkit],
       });
 
-      const context = new Context({});
+      const context = new Context("test-namespace", {});
       await agent.tools(context);
 
       const addTool = agent.tool("add");
@@ -401,7 +400,7 @@ describe("MCP Integration Tests", () => {
         toolkits: [mcpToolkit, functionToolkit],
       });
 
-      const context = new Context({});
+      const context = new Context("test-namespace", {});
       const tools = await agent.tools(context);
 
       // Should have 7 tools (6 MCP + 1 local)
@@ -451,7 +450,7 @@ describe("MCP Integration Tests", () => {
         toolkits: [mcpToolkit, functionToolkit],
       });
 
-      const context = new Context({});
+      const context = new Context("test-namespace", {});
 
       // Should throw error about duplicate tool IDs
       await expect(agent.tools(context)).rejects.toThrow(

package/src/mcp/__tests__/utils.test.ts

@@ -95,7 +95,7 @@ describe("mcpToFunctionTool", () => {
     };
 
     const functionTool = mcpToFunctionTool(server, mcpTool);
-    const ctx = new Context({});
+    const ctx = new Context("test-namespace", {});
     const input = { arg1: "value1" };
 
     await functionTool.invoke(ctx, JSON.stringify(input));
@@ -119,7 +119,7 @@ describe("mcpToFunctionTool", () => {
     };
 
     const functionTool = mcpToFunctionTool(server, mcpTool);
-    const ctx = new Context({});
+    const ctx = new Context("test-namespace", {});
     const toolResult = await functionTool.invoke(ctx, JSON.stringify({}));
 
     expect(toolResult.state).toBe("completed");
@@ -144,7 +144,7 @@ describe("mcpToFunctionTool", () => {
     };
 
     const functionTool = mcpToFunctionTool(server, mcpTool);
-    const ctx = new Context({});
+    const ctx = new Context("test-namespace", {});
     const toolResult = await functionTool.invoke(ctx, JSON.stringify({}));
 
     expect(toolResult.state).toBe("completed");
@@ -171,7 +171,7 @@ describe("mcpToFunctionTool", () => {
     const functionTool1 = mcpToFunctionTool(server, tool1);
     const functionTool2 = mcpToFunctionTool(server, tool2);
 
-    const ctx = new Context({});
+    const ctx = new Context("test-namespace", {});
 
     await functionTool1.invoke(ctx, JSON.stringify({}));
     expect(server.callTool).toHaveBeenCalledWith("tool1", {});
@@ -199,7 +199,7 @@ describe("mcpToFunctionTool", () => {
     const functionTool = mcpToFunctionTool(server, mcpTool);
 
     // Invoke takes (context, params as JSON string) in that order
-    const ctx = new Context({});
+    const ctx = new Context("test-namespace", {});
     const params = { foo: "bar" };
     await functionTool.invoke(ctx, JSON.stringify(params));
 
@@ -211,7 +211,7 @@ describe("mcpToFunctionTool", () => {
 describe("createMCPToolStaticFilter", () => {
   // Helper to create mock filter context
   const createMockFilterContext = (): MCPToolFilterContext => ({
-    context: new Context({}),
+    context: new Context("test-namespace", {}),
     agent: {} as Agent,
     serverId: "test-server",
   });

package/src/mcp/http.ts

@@ -28,7 +28,7 @@ export class MCPServerStreamableHttp extends BaseMCPServer {
   protected timeout: number;
   protected serverInitializeResult: InitializeResult | null = null;
 
-  params: MCPServerStreamableHttpOptions;
+  options: MCPServerStreamableHttpOptions;
   private transport: any = null;
 
   constructor(options: MCPServerStreamableHttpOptions) {
@@ -40,8 +40,8 @@ export class MCPServerStreamableHttp extends BaseMCPServer {
         getLogger(DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME),
     });
 
-    this.params = options;
-    this.id = options.id || `streamable-http: ${this.params.url}`;
+    this.options = options;
+    this.id = options.id || `streamable-http: ${this.options.url}`;
     this.timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
   }
 
@@ -51,13 +51,13 @@ export class MCPServerStreamableHttp extends BaseMCPServer {
   async connect(): Promise<void> {
     try {
       this.transport = new StreamableHTTPClientTransport(
-        new URL(this.params.url),
+        new URL(this.options.url),
         {
-          authProvider: this.params.authProvider,
-          requestInit: this.params.requestInit,
-          fetch: this.params.fetch,
-          reconnectionOptions: this.params.reconnectionOptions,
-          sessionId: this.params.sessionId,
+          authProvider: this.options.authProvider,
+          requestInit: this.options.requestInit,
+          fetch: this.options.fetch,
+          reconnectionOptions: this.options.reconnectionOptions,
+          sessionId: this.options.sessionId,
         },
       );
 

package/src/mcp/sse.ts

@@ -25,7 +25,7 @@ export class MCPServerSSE extends BaseMCPServer {
   protected timeout: number;
   protected serverInitializeResult: InitializeResult | null = null;
 
-  params: MCPServerSSEOptions;
+  options: MCPServerSSEOptions;
   private transport: any = null;
 
   constructor(options: MCPServerSSEOptions) {
@@ -35,8 +35,8 @@ export class MCPServerSSE extends BaseMCPServer {
       logger: options.logger ?? getLogger(DEFAULT_SSE_MCP_CLIENT_LOGGER_NAME),
     });
 
-    this.params = options;
-    this.id = options.id || `sse: ${this.params.url}`;
+    this.options = options;
+    this.id = options.id || `sse: ${this.options.url}`;
     this.timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
   }
 
@@ -45,10 +45,10 @@ export class MCPServerSSE extends BaseMCPServer {
    */
   async connect(): Promise<void> {
     try {
-      this.transport = new SSEClientTransport(new URL(this.params.url), {
-        authProvider: this.params.authProvider,
-        requestInit: this.params.requestInit,
-        eventSourceInit: this.params.eventSourceInit,
+      this.transport = new SSEClientTransport(new URL(this.options.url), {
+        authProvider: this.options.authProvider,
+        requestInit: this.options.requestInit,
+        eventSourceInit: this.options.eventSourceInit,
       });
 
       this.session = new Client({

package/src/mcp/utils.ts

@@ -15,11 +15,12 @@ export function mcpToFunctionTool(server: MCPServer, mcpTool: MCPTool) {
     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;
+  const hasProperties =
+    mcpTool.inputSchema &&
+    Object.keys(mcpTool.inputSchema.properties || {}).length > 0;
+
+  // If tool has properties, use passthrough to accept any object, else empty object (matches AI SDK)
+  const parameters = hasProperties ? z.object({}).passthrough() : z.object({});
 
   return tool({
     id: mcpTool.name,