kernl 0.2.0 → 0.6.0

package/src/tool/__tests__/toolkit.test.ts

@@ -115,12 +115,12 @@ describe("FunctionToolkit", () => {
 
       const serialized = (await toolkit.list()).map((tool: any) => tool.serialize());
       expect(serialized).toHaveLength(1);
-      expect(serialized[0]).toEqual({
-        type: "function",
-        name: simpleStringTool.name,
+      expect(serialized[0]).toMatchObject({
+        kind: "function",
+        name: simpleStringTool.id,
         description: simpleStringTool.description,
-        parameters: simpleStringTool.parameters,
       });
+      expect(serialized[0].parameters).toBeDefined();
     });
 
     it("should serialize hosted tools correctly", async () => {
@@ -129,10 +129,10 @@ describe("FunctionToolkit", () => {
       const serialized = (await toolkit.list()).map((tool: any) => tool.serialize());
       expect(serialized).toHaveLength(1);
       expect(serialized[0]).toEqual({
-        type: "hosted-tool",
+        kind: "provider-defined",
         id: mockHostedTool.id,
         name: mockHostedTool.name,
-        providerData: mockHostedTool.providerData,
+        args: mockHostedTool.providerData,
       });
     });
 
@@ -144,18 +144,21 @@ describe("FunctionToolkit", () => {
 
       // Check both tools are present (order not guaranteed with Map)
       expect(serialized).toContainEqual({
-        type: "hosted-tool",
+        kind: "provider-defined",
         id: mockHostedTool.id,
         name: mockHostedTool.name,
-        providerData: mockHostedTool.providerData,
+        args: mockHostedTool.providerData,
       });
 
-      expect(serialized).toContainEqual({
-        type: "function",
-        name: simpleStringTool.name,
+      // Check that function tool is present with correct structure
+      const functionTool = serialized.find((t: any) => t.kind === "function");
+      expect(functionTool).toBeDefined();
+      expect(functionTool).toMatchObject({
+        kind: "function",
+        name: simpleStringTool.id,
         description: simpleStringTool.description,
-        parameters: simpleStringTool.parameters,
       });
+      expect(functionTool.parameters).toBeDefined();
     });
 
     it("should handle hosted tools without providerData", async () => {

package/src/tool/tool.ts

@@ -197,9 +197,9 @@ export class FunctionTool<
       kind: "function",
       name: this.id,
       description: this.description,
-      parameters: (this.parameters
-        ? z.toJSONSchema(this.parameters, { target: "draft-7" })
-        : {}) as any, // JSONSchema7 - target: 'draft-7' produces this
+      parameters: z.toJSONSchema(this.parameters ?? z.object({}), {
+        target: "draft-7",
+      }) as any, // Use empty object if no parameters (matches AI SDK)
     };
   }
 }

package/src/types/kernl.ts

@@ -0,0 +1,51 @@
+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;
+
+  // Future storage layers (deferred):
+  // vector?: VectorStore;
+  // blob?: BlobStore;
+  // lake?: DataLake;
+}
+
+/**
+ * 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;
+}

package/src/types/thread.ts

@@ -13,9 +13,30 @@ import {
 
 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 const THREAD_STATES = [
+  RUNNING,
+  STOPPED,
+  INTERRUPTIBLE,
+  UNINTERRUPTIBLE,
+  ZOMBIE,
+  DEAD,
+] as const;
+
 /**
  * Thread state discriminated union
  */
@@ -34,44 +55,84 @@ export type ThreadState =
 export 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[] /* initial input for the thread */;
+  history: ThreadEvent[];
+  task: Task<TContext> | null /* parent task which spawned this thread (if any) */;
+
+  /* state */
+  tick: number;
+  state: ThreadState /* running | stopped | ... */;
+  namespace: string;
+
+  /* metadata */
+  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[];
-  // Future: other actions, mcpRequests, etc.
+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";
+  // Future: error?, state-change?, etc.
 }
 
+/**
+ * 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
    */
@@ -79,16 +140,69 @@ export interface ThreadExecuteResult<TResponse = any> {
   /**
    * The thread state at completion
    */
-  state: any; // Will be ThreadState, but avoiding circular dependency
+  state: any; // (TODO): Update this
 }
 
-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;
+}
 
-  // conversationId?: string;
+/**
+ * Set of actionable items extracted from a model response
+ */
+export interface ActionSet {
+  toolCalls: ToolCall[];
+  // Future: other actions, mcpRequests, etc.
+}
+
+/**
+ * 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[];
 }

package/vitest.config.ts

@@ -5,6 +5,7 @@ export default defineConfig({
   test: {
     globals: true,
     environment: "node",
+    exclude: ["**/node_modules/**", "**/dist/**"],
   },
   resolve: {
     alias: {

package/dist/env.d.ts

@@ -1,45 +0,0 @@
-import { z } from "zod";
-/**
- * Environment variable validation schema
- *
- * This ensures all environment variables are valid at startup.
- * All variables are optional with sensible defaults.
- */
-declare const envSchema: z.ZodObject<{
-    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
-        trace: "trace";
-        debug: "debug";
-        info: "info";
-        warn: "warn";
-        error: "error";
-        fatal: "fatal";
-    }>>;
-    KERNL_LOG_MODEL_DATA: z.ZodPipe<z.ZodOptional<z.ZodEnum<{
-        true: "true";
-        false: "false";
-    }>>, z.ZodTransform<boolean, "true" | "false" | undefined>>;
-    KERNL_LOG_TOOL_DATA: z.ZodPipe<z.ZodOptional<z.ZodEnum<{
-        true: "true";
-        false: "false";
-    }>>, z.ZodTransform<boolean, "true" | "false" | undefined>>;
-}, z.core.$strip>;
-/**
- * Validated and type-safe environment variables
- *
- * Use this throughout the library instead of process.env directly.
- *
- * @example
- * import { env } from './env';
- * console.log(env.LOG_LEVEL);
- */
-export declare const env: {
-    LOG_LEVEL: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
-    KERNL_LOG_MODEL_DATA: boolean;
-    KERNL_LOG_TOOL_DATA: boolean;
-};
-/**
- * Type of the validated environment variables
- */
-export type Env = z.infer<typeof envSchema>;
-export {};
-//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,QAAA,MAAM,SAAS;;;;;;;;;;;;;;;;;iBAab,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG;;;;CAA+B,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/env.js

@@ -1,31 +0,0 @@
-import { z } from "zod";
-/**
- * Environment variable validation schema
- *
- * This ensures all environment variables are valid at startup.
- * All variables are optional with sensible defaults.
- */
-const envSchema = z.object({
-    // --- Logging ---
-    LOG_LEVEL: z
-        .enum(["trace", "debug", "info", "warn", "error", "fatal"])
-        .default("info"),
-    KERNL_LOG_MODEL_DATA: z
-        .enum(["true", "false"])
-        .optional()
-        .transform((val) => val === "true"),
-    KERNL_LOG_TOOL_DATA: z
-        .enum(["true", "false"])
-        .optional()
-        .transform((val) => val === "true"),
-});
-/**
- * Validated and type-safe environment variables
- *
- * Use this throughout the library instead of process.env directly.
- *
- * @example
- * import { env } from './env';
- * console.log(env.LOG_LEVEL);
- */
-export const env = envSchema.parse(process.env);

package/dist/error.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":""}

package/dist/kernel.d.ts

@@ -1,7 +0,0 @@
-import type { Agent } from './agent';
-export declare class Kernel {
-    private agents;
-    constructor();
-    register(agent: Agent): void;
-}
-//# sourceMappingURL=kernel.d.ts.map

package/dist/kernel.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../src/kernel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAiC;;IAI/C,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAG7B"}

package/dist/kernel.js

@@ -1,7 +0,0 @@
-export class Kernel {
-    agents = new Map();
-    constructor() { }
-    register(agent) {
-        // TODO: Implement agent registration
-    }
-}

package/dist/lib/serde/__tests__/codec.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=codec.test.d.ts.map

package/dist/lib/serde/__tests__/codec.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codec.test.d.ts","sourceRoot":"","sources":["../../../../src/lib/serde/__tests__/codec.test.ts"],"names":[],"mappings":""}

package/dist/lib/serde/__tests__/codec.test.js

@@ -1,75 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { z } from "zod";
-import { json } from "../codec";
-describe("json codec", () => {
-    it("should parse valid JSON and validate against schema", () => {
-        const schema = z.object({
-            name: z.string(),
-            age: z.number(),
-        });
-        const codec = json(schema);
-        const result = codec.decode('{"name": "Alice", "age": 30}');
-        expect(result).toEqual({ name: "Alice", age: 30 });
-    });
-    it("should reject invalid JSON syntax", () => {
-        const schema = z.object({
-            name: z.string(),
-        });
-        const codec = json(schema);
-        expect(() => {
-            codec.decode('{"name": "Alice"');
-        }).toThrow();
-    });
-    it("should reject valid JSON that doesn't match schema", () => {
-        const schema = z.object({
-            name: z.string(),
-            age: z.number(),
-        });
-        const codec = json(schema);
-        // Valid JSON but age is a string, not a number
-        expect(() => {
-            codec.decode('{"name": "Alice", "age": "30"}');
-        }).toThrow();
-    });
-    it("should reject JSON missing required fields", () => {
-        const schema = z.object({
-            name: z.string(),
-            age: z.number(),
-        });
-        const codec = json(schema);
-        // Valid JSON but missing age field
-        expect(() => {
-            codec.decode('{"name": "Alice"}');
-        }).toThrow();
-    });
-    it("should handle nested objects", () => {
-        const schema = z.object({
-            user: z.object({
-                name: z.string(),
-                email: z.string().email(),
-            }),
-            metadata: z.object({
-                createdAt: z.string(),
-            }),
-        });
-        const codec = json(schema);
-        const result = codec.decode('{"user": {"name": "Bob", "email": "bob@example.com"}, "metadata": {"createdAt": "2024-01-01"}}');
-        expect(result).toEqual({
-            user: { name: "Bob", email: "bob@example.com" },
-            metadata: { createdAt: "2024-01-01" },
-        });
-    });
-    it("should reject nested objects that don't match schema", () => {
-        const schema = z.object({
-            user: z.object({
-                name: z.string(),
-                email: z.string().email(),
-            }),
-        });
-        const codec = json(schema);
-        // Invalid email format
-        expect(() => {
-            codec.decode('{"user": {"name": "Bob", "email": "not-an-email"}}');
-        }).toThrow();
-    });
-});

package/dist/lib/serde/codec.d.ts

@@ -1,12 +0,0 @@
-import { z } from "zod";
-export declare const stringToNumber: z.ZodCodec<z.ZodString, z.ZodNumber>;
-export declare const stringToInt: z.ZodCodec<z.ZodString, z.ZodInt>;
-export declare const isotime: z.ZodCodec<z.ZodISODateTime, z.ZodDate>;
-export declare const epochsec: z.ZodCodec<z.ZodInt, z.ZodDate>;
-export declare const epochms: z.ZodCodec<z.ZodInt, z.ZodDate>;
-export declare const json: <T extends z.core.$ZodType>(schema: T) => z.ZodCodec<z.ZodString, T>;
-export declare const stringToURL: z.ZodCodec<z.ZodURL, z.ZodCustom<import("url").URL, import("url").URL>>;
-export declare const stringToHttpURL: z.ZodCodec<z.ZodURL, z.ZodCustom<import("url").URL, import("url").URL>>;
-export declare const base64ToBytes: z.ZodCodec<z.ZodBase64, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
-export declare const base64urlToBytes: z.ZodCodec<z.ZodBase64URL, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
-//# sourceMappingURL=codec.d.ts.map

package/dist/lib/serde/codec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/lib/serde/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc,sCAO1B,CAAC;AAEF,eAAO,MAAM,WAAW,mCAOvB,CAAC;AAEF,eAAO,MAAM,OAAO,yCAGlB,CAAC;AAEH,eAAO,MAAM,QAAQ,iCAGnB,CAAC;AAEH,eAAO,MAAM,OAAO,iCAGlB,CAAC;AAEH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,+BAgBrD,CAAC;AAEL,eAAO,MAAM,WAAW,yEAGtB,CAAC;AAEH,eAAO,MAAM,eAAe,yEAG1B,CAAC;AAEH,eAAO,MAAM,aAAa,wFAGxB,CAAC;AAEH,eAAO,MAAM,gBAAgB,2FAO5B,CAAC"}

package/dist/lib/serde/codec.js

@@ -1,54 +0,0 @@
-import { z } from "zod";
-export const stringToNumber = z.codec(z.string().regex(z.regexes.number), z.number(), {
-    decode: (str) => Number.parseFloat(str),
-    encode: (num) => num.toString(),
-});
-export const stringToInt = z.codec(z.string().regex(z.regexes.integer), z.int(), {
-    decode: (str) => Number.parseInt(str, 10),
-    encode: (num) => num.toString(),
-});
-export const isotime = z.codec(z.iso.datetime(), z.date(), {
-    decode: (isoString) => new Date(isoString),
-    encode: (date) => date.toISOString(),
-});
-export const epochsec = z.codec(z.int().min(0), z.date(), {
-    decode: (seconds) => new Date(seconds * 1000),
-    encode: (date) => Math.floor(date.getTime() / 1000),
-});
-export const epochms = z.codec(z.int().min(0), z.date(), {
-    decode: (millis) => new Date(millis),
-    encode: (date) => date.getTime(),
-});
-export const json = (schema) => z.codec(z.string(), schema, {
-    decode: (jsonString, ctx) => {
-        try {
-            return JSON.parse(jsonString);
-        }
-        catch (err) {
-            ctx.issues.push({
-                code: "invalid_format",
-                format: "json",
-                input: jsonString,
-                message: err.message,
-            });
-            return z.NEVER;
-        }
-    },
-    encode: (value) => JSON.stringify(value),
-});
-export const stringToURL = z.codec(z.url(), z.instanceof(URL), {
-    decode: (urlString) => new URL(urlString),
-    encode: (url) => url.href,
-});
-export const stringToHttpURL = z.codec(z.httpUrl(), z.instanceof(URL), {
-    decode: (urlString) => new URL(urlString),
-    encode: (url) => url.href,
-});
-export const base64ToBytes = z.codec(z.base64(), z.instanceof(Uint8Array), {
-    decode: (base64String) => z.util.base64ToUint8Array(base64String),
-    encode: (bytes) => z.util.uint8ArrayToBase64(bytes),
-});
-export const base64urlToBytes = z.codec(z.base64url(), z.instanceof(Uint8Array), {
-    decode: (base64urlString) => z.util.base64urlToUint8Array(base64urlString),
-    encode: (bytes) => z.util.uint8ArrayToBase64url(bytes),
-});

package/dist/lib/serde/thread.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=thread.d.ts.map

package/dist/lib/serde/thread.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../../src/lib/serde/thread.ts"],"names":[],"mappings":""}