kernl 0.2.0 → 0.6.0

package/dist/types/kernl.d.ts

@@ -0,0 +1,42 @@
+import { LanguageModel } from "@kernl-sdk/protocol";
+import { Agent } from "../agent";
+import { KernlStorage } from "../storage";
+/**
+ * Storage configuration for Kernl.
+ */
+export interface StorageOptions {
+    /**
+     * Relational database storage (threads, tasks, traces).
+     */
+    db?: KernlStorage;
+}
+/**
+ * Configuration options for creating a Kernl instance.
+ */
+export interface KernlOptions {
+    /**
+     * Storage configuration for persisting threads, tasks, and traces.
+     */
+    storage?: StorageOptions;
+}
+/**
+ * Agent registry interface.
+ *
+ * Satisfied by Map<string, Agent>.
+ */
+export interface AgentRegistry {
+    get(id: string): Agent<any> | undefined;
+}
+/**
+ * Model registry interface.
+ *
+ * Satisfied by Map<string, LanguageModel>.
+ * Key format: "provider/modelId"
+ *
+ * TODO: Create an exhaustive model registry in the protocol package
+ * with all supported models and their metadata.
+ */
+export interface ModelRegistry {
+    get(key: string): LanguageModel | undefined;
+}
+//# sourceMappingURL=kernl.d.ts.map

package/dist/types/kernl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernl.d.ts","sourceRoot":"","sources":["../../src/types/kernl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,EAAE,CAAC,EAAE,YAAY,CAAC;CAMnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;CAC7C"}

package/dist/types/thread.d.ts

@@ -1,7 +1,18 @@
 import { ToolCall, LanguageModel, LanguageModelItem, LanguageModelStreamEvent, RUNNING, STOPPED, INTERRUPTIBLE, UNINTERRUPTIBLE, ZOMBIE, DEAD } from "@kernl-sdk/protocol";
 import { Task } from "../task";
 import { Context } from "../context";
+import { Agent } from "../agent";
+import type { AgentResponseType } from "./agent";
+import type { ThreadStore } from "../storage";
+/**
+ * Public/client-facing thread events (excludes internal system events).
+ */
+export type PublicThreadEvent = LanguageModelItem & ThreadEventBase;
 export type TextResponse = "text";
+/**
+ * Thread state values as a const array (for zod schemas).
+ */
+export declare const THREAD_STATES: readonly ["running", "stopped", "interruptible", "uninterruptible", "zombie", "dead"];
 /**
  * Thread state discriminated union
  */
@@ -12,39 +23,66 @@ export type ThreadState = typeof RUNNING | typeof STOPPED | typeof INTERRUPTIBLE
  */
 export declare const REQUIRES_APPROVAL = "requires_approval";
 /**
- * ThreadEvent uses protocol types directly.
+ * Thread domain interface.
  *
- * (TODO): just an alias for LanguageModelItem for now, but there may be other thread events later
- * which don't go to the model.
+ * Represents the complete state of a Thread that can be stored and restored.
  */
-export type ThreadEvent = LanguageModelItem;
+export interface IThread<TContext = unknown, TResponse extends AgentResponseType = "text"> {
+    tid: string;
+    agent: Agent<TContext, TResponse>;
+    model: LanguageModel;
+    context: Context<TContext>;
+    input: LanguageModelItem[];
+    history: ThreadEvent[];
+    task: Task<TContext> | null;
+    tick: number;
+    state: ThreadState;
+    namespace: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata: Record<string, unknown> | null;
+}
+export interface CheckpointDelta {
+    state?: ThreadState;
+    tick?: number;
+    seq?: number;
+    events?: ThreadEvent[];
+}
 /**
- * Stream events - use protocol definition directly.
+ * The inner data of a ThreadEvent without the headers
  */
-export type ThreadStreamEvent = LanguageModelStreamEvent;
+export type ThreadEventInner = LanguageModelItem;
 /**
- * Set of actionable items extracted from a model response
+ * Base fields for all thread events - added to every LanguageModelItem when stored in thread.
  */
-export interface ActionSet {
-    toolCalls: ToolCall[];
+export interface ThreadEventBase {
+    id: string;
+    tid: string;
+    seq: number;
+    timestamp: Date;
+    metadata: Record<string, unknown>;
 }
 /**
- * Result of performing actions, including both executed results and pending approvals
+ * System event - runtime state changes (not sent to model).
  */
-export interface PerformActionsResult {
-    /**
-     * Action events generated from executing tools (tool results)
-     */
-    actions: ThreadEvent[];
-    /**
-     * Tool calls that require approval before execution
-     */
-    pendingApprovals: ToolCall[];
+export interface ThreadSystemEvent extends ThreadEventBase {
+    readonly kind: "system";
 }
+/**
+ * Thread events are append-only log entries ordered by seq.
+ *
+ * Events extend LanguageModelItem types with thread-specific metadata (tid, seq, timestamp).
+ * When sent to the model, we extract the LanguageModelItem by omitting the base fields.
+ */
+export type ThreadEvent = (LanguageModelItem & ThreadEventBase) | ThreadSystemEvent;
+/**
+ * Stream events - use protocol definition directly.
+ */
+export type ThreadStreamEvent = LanguageModelStreamEvent;
 /**
  * Result of thread execution
  */
-export interface ThreadExecuteResult<TResponse = any> {
+export interface ThreadExecuteResult<TResponse = unknown> {
     /**
      * The final parsed response from the agent
      */
@@ -54,12 +92,60 @@ export interface ThreadExecuteResult<TResponse = any> {
      */
     state: any;
 }
-export interface ThreadOptions<TContext> {
-    context: Context<TContext>;
+/**
+ * Options for constructing a Thread.
+ */
+export interface ThreadOptions<TContext = unknown, TResponse extends AgentResponseType = "text"> {
+    agent: Agent<TContext, TResponse>;
+    input?: LanguageModelItem[];
+    history?: ThreadEvent[];
+    context?: Context<TContext>;
+    model?: LanguageModel;
+    task?: Task<TContext> | null;
+    namespace?: string;
+    tid?: string;
+    tick?: number;
+    state?: ThreadState;
+    storage?: ThreadStore;
+    createdAt?: Date;
+    updatedAt?: Date;
+    metadata?: Record<string, unknown> | null;
+    /**
+     * Internal flag indicating whether this thread already has a persisted
+     * row in storage. Storage implementations MUST set this to true when
+     * hydrating from a store. Callers creating new threads should omit it.
+     */
+    persisted?: boolean;
+}
+/**
+ * Options passed to agent.execute() and agent.stream().
+ */
+export interface ThreadExecuteOptions<TContext> {
+    context?: Context<TContext>;
     model?: LanguageModel;
     task?: Task<TContext>;
     threadId?: string;
+    namespace?: string;
     maxTicks?: number;
     abort?: AbortSignal;
 }
+/**
+ * Set of actionable items extracted from a model response
+ */
+export interface ActionSet {
+    toolCalls: ToolCall[];
+}
+/**
+ * Result of performing actions, including both executed results and pending approvals
+ */
+export interface PerformActionsResult {
+    /**
+     * Action events generated from executing tools (tool results)
+     */
+    actions: ThreadEventInner[];
+    /**
+     * Tool calls that require approval before execution
+     */
+    pendingApprovals: ToolCall[];
+}
 //# sourceMappingURL=thread.d.ts.map

package/dist/types/thread.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/types/thread.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,OAAO,EACP,OAAO,EACP,aAAa,EACb,eAAe,EACf,MAAM,EACN,IAAI,EACL,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,OAAO,OAAO,GACd,OAAO,OAAO,GACd,OAAO,aAAa,GACpB,OAAO,eAAe,GACtB,OAAO,MAAM,GACb,OAAO,IAAI,CAAC;AAEhB;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,QAAQ,EAAE,CAAC;CAEvB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB;;OAEG;IACH,gBAAgB,EAAE,QAAQ,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,GAAG;IAClD;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,GAAG,CAAC;CACZ;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ;IACrC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;CAGrB"}
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/types/thread.ts"],"names":[],"mappings":"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"}

package/dist/types/thread.js

@@ -1,3 +1,15 @@
+import { RUNNING, STOPPED, INTERRUPTIBLE, UNINTERRUPTIBLE, ZOMBIE, DEAD, } from "@kernl-sdk/protocol";
+/**
+ * Thread state values as a const array (for zod schemas).
+ */
+export const THREAD_STATES = [
+    RUNNING,
+    STOPPED,
+    INTERRUPTIBLE,
+    UNINTERRUPTIBLE,
+    ZOMBIE,
+    DEAD,
+];
 /**
  * Thread-specific tool call state for approval workflow.
  * This extends the protocol states for internal thread use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -13,26 +13,30 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dremnik/kernl.git",
+    "url": "https://github.com/kernl-sdk/kernl.git",
     "directory": "packages/kernl"
   },
-  "homepage": "https://github.com/dremnik/kernl#readme",
+  "homepage": "https://github.com/kernl-sdk/kernl#readme",
   "bugs": {
-    "url": "https://github.com/dremnik/kernl/issues"
+    "url": "https://github.com/kernl-sdk/kernl/issues"
   },
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     }
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
     "pino": "^9.6.0",
     "zod": "^4.1.12",
-    "@kernl-sdk/protocol": "0.2.0",
-    "@kernl-sdk/shared": "^0.1.1"
+    "@kernl-sdk/protocol": "0.2.4",
+    "@kernl-sdk/shared": "^0.1.5"
   },
   "devDependencies": {
     "@ai-sdk/openai": "3.0.0-beta.57",
@@ -40,7 +44,7 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/ai": "0.1.1"
+    "@kernl-sdk/ai": "0.2.5"
   },
   "scripts": {
     "build": "tsc && tsc-alias",

package/src/agent/__tests__/concurrency.test.ts

@@ -0,0 +1,194 @@
+import { describe, it, expect } from "vitest";
+import { Agent } from "@/agent";
+import { Kernl } from "@/kernl";
+import { createMockModel } from "@/thread/__tests__/fixtures/mock-model";
+import { RuntimeError } from "@/lib/error";
+import { message } from "@kernl-sdk/protocol";
+
+describe("Concurrent execution prevention", () => {
+  // (TODO): this should work
+  it.skip("should prevent two Agent.run() calls with same threadId", async () => {
+    const model = createMockModel(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      return {
+        content: [message({ role: "assistant", text: "Done" })],
+        finishReason: "stop",
+        usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+        warnings: [],
+      };
+    });
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test",
+      instructions: "Test",
+      model,
+    });
+
+    const kernl = new Kernl();
+    kernl.register(agent);
+
+    const tid = "concurrent-test-1";
+
+    // Start first run
+    const run1 = agent.run("First", { threadId: tid });
+
+    // Try second run immediately
+    await expect(agent.run("Second", { threadId: tid })).rejects.toThrow(
+      RuntimeError,
+    );
+
+    await expect(agent.run("Second", { threadId: tid })).rejects.toThrow(
+      /already running/,
+    );
+
+    // Wait for first to complete
+    await run1;
+
+    // Now third should work
+    await expect(agent.run("Third", { threadId: tid })).resolves.toBeDefined();
+  });
+
+  // (TODO): this should work
+  it.skip("should prevent Agent.stream() on thread already in Agent.run()", async () => {
+    const model = createMockModel(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      return {
+        content: [message({ role: "assistant", text: "Done" })],
+        finishReason: "stop",
+        usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+        warnings: [],
+      };
+    });
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test",
+      instructions: "Test",
+      model,
+    });
+
+    const kernl = new Kernl();
+    kernl.register(agent);
+
+    const tid = "concurrent-test-2";
+
+    // Start run()
+    const runPromise = agent.run("Test", { threadId: tid });
+
+    // Try to stream same thread
+    const streamIterable = agent.stream("Test", { threadId: tid });
+    const streamIterator = streamIterable[Symbol.asyncIterator]();
+    await expect(streamIterator.next()).rejects.toThrow(RuntimeError);
+    await expect(streamIterator.next()).rejects.toThrow(/already running/);
+
+    await runPromise;
+  });
+
+  it("should prevent Agent.run() on thread already in Agent.stream()", async () => {
+    const model = createMockModel(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      return {
+        content: [message({ role: "assistant", text: "Done" })],
+        finishReason: "stop",
+        usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+        warnings: [],
+      };
+    });
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test",
+      instructions: "Test",
+      model,
+    });
+
+    const kernl = new Kernl();
+    kernl.register(agent);
+
+    const tid = "concurrent-test-3";
+
+    // Start stream() but don't await - start consuming
+    const streamIterator = agent.stream("Test", { threadId: tid });
+    const streamPromise = (async () => {
+      for await (const _event of streamIterator) {
+        // consume
+      }
+    })();
+
+    // Give stream time to start
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Try to run() same thread
+    await expect(agent.run("Test", { threadId: tid })).rejects.toThrow(
+      RuntimeError,
+    );
+
+    await streamPromise;
+  });
+
+  it("should allow different threadIds to run concurrently", async () => {
+    const model = createMockModel(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      return {
+        content: [message({ role: "assistant", text: "Done" })],
+        finishReason: "stop",
+        usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+        warnings: [],
+      };
+    });
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test",
+      instructions: "Test",
+      model,
+    });
+
+    const kernl = new Kernl();
+    kernl.register(agent);
+
+    // These should all succeed
+    const results = await Promise.all([
+      agent.run("Test 1", { threadId: "thread-1" }),
+      agent.run("Test 2", { threadId: "thread-2" }),
+      agent.run("Test 3", { threadId: "thread-3" }),
+    ]);
+
+    expect(results).toHaveLength(3);
+    expect(results.every((r) => r.response === "Done")).toBe(true);
+  });
+
+  it("should allow same threadId after previous run completes", async () => {
+    const model = createMockModel(async () => ({
+      content: [message({ role: "assistant", text: "Done" })],
+      finishReason: "stop",
+      usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+      warnings: [],
+    }));
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test",
+      instructions: "Test",
+      model,
+    });
+
+    const kernl = new Kernl();
+    kernl.register(agent);
+
+    const tid = "reuse-thread";
+
+    // First run
+    const result1 = await agent.run("First", { threadId: tid });
+    expect(result1.response).toBe("Done");
+
+    // Second run (should work since first completed)
+    const result2 = await agent.run("Second", { threadId: tid });
+    expect(result2.response).toBe("Done");
+
+    // Third run
+    const result3 = await agent.run("Third", { threadId: tid });
+    expect(result3.response).toBe("Done");
+  });
+});