kernl 0.2.1 → 0.6.0

package/dist/storage/__tests__/in-memory.test.js

@@ -0,0 +1,455 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { STOPPED, RUNNING, DEAD, IN_PROGRESS } from "@kernl-sdk/protocol";
+import { InMemoryStorage, InMemoryThreadStore } from "../in-memory";
+import { Agent } from "../../agent";
+import { Thread } from "../../thread";
+import { createMockModel } from "../../thread/__tests__/fixtures/mock-model";
+describe("InMemoryThreadStore", () => {
+    let store;
+    let agent;
+    let model;
+    beforeEach(() => {
+        store = new InMemoryThreadStore();
+        model = createMockModel(async () => ({
+            content: [
+                {
+                    kind: "message",
+                    id: "msg_1",
+                    role: "assistant",
+                    content: [{ kind: "text", text: "Hello" }],
+                },
+            ],
+            finishReason: "stop",
+            usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+            warnings: [],
+        }));
+        agent = new Agent({
+            id: "test-agent",
+            name: "Test Agent",
+            instructions: "Test instructions",
+            model,
+        });
+        // Bind registries
+        const agents = new Map([[agent.id, agent]]);
+        const models = new Map([[`${model.provider}/${model.modelId}`, model]]);
+        store.bind({ agents, models });
+    });
+    describe("insert", () => {
+        it("should insert a new thread", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+                context: { foo: "bar" },
+            };
+            const thread = await store.insert(newThread);
+            expect(thread).toBeInstanceOf(Thread);
+            expect(thread.tid).toBe("thread-1");
+            expect(thread._tick).toBe(0);
+            expect(thread.state).toBe(STOPPED);
+        });
+        it("should use provided defaults", async () => {
+            const createdAt = new Date("2024-01-01");
+            const newThread = {
+                id: "thread-2",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+                tick: 5,
+                state: RUNNING,
+                createdAt,
+            };
+            const thread = await store.insert(newThread);
+            expect(thread._tick).toBe(5);
+            expect(thread.state).toBe(RUNNING);
+        });
+    });
+    describe("get", () => {
+        it("should get a thread by id", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            const thread = await store.get("thread-1");
+            expect(thread).not.toBeNull();
+            expect(thread?.tid).toBe("thread-1");
+        });
+        it("should return null for non-existent thread", async () => {
+            const thread = await store.get("non-existent");
+            expect(thread).toBeNull();
+        });
+        it("should include history when requested", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            const events = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    tid: "thread-1",
+                    seq: 0,
+                    timestamp: new Date(),
+                    role: "user",
+                    content: [{ kind: "text", text: "Hello" }],
+                    metadata: {},
+                },
+            ];
+            await store.append(events);
+            const thread = await store.get("thread-1", { history: true });
+            expect(thread).not.toBeNull();
+            // Access private history for testing
+            const history = thread.history;
+            expect(history).toHaveLength(1);
+            expect(history[0].id).toBe("msg-1");
+        });
+    });
+    describe("update", () => {
+        it("should update thread state", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            const updated = await store.update("thread-1", {
+                state: DEAD,
+                tick: 10,
+            });
+            expect(updated.state).toBe(DEAD);
+            expect(updated._tick).toBe(10);
+        });
+        it("should throw on non-existent thread", async () => {
+            await expect(store.update("non-existent", { state: DEAD })).rejects.toThrow("Thread non-existent not found");
+        });
+    });
+    describe("delete", () => {
+        it("should delete a thread and its events", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            await store.append([
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    tid: "thread-1",
+                    seq: 0,
+                    timestamp: new Date(),
+                    role: "user",
+                    content: [{ kind: "text", text: "Hello" }],
+                    metadata: {},
+                },
+            ]);
+            await store.delete("thread-1");
+            const thread = await store.get("thread-1");
+            const history = await store.history("thread-1");
+            expect(thread).toBeNull();
+            expect(history).toHaveLength(0);
+        });
+    });
+    describe("append", () => {
+        it("should append events to thread history", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            const events = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    tid: "thread-1",
+                    seq: 0,
+                    timestamp: new Date(),
+                    role: "user",
+                    content: [{ kind: "text", text: "Hello" }],
+                    metadata: {},
+                },
+                {
+                    kind: "message",
+                    id: "msg-2",
+                    tid: "thread-1",
+                    seq: 1,
+                    timestamp: new Date(),
+                    role: "assistant",
+                    content: [{ kind: "text", text: "Hi" }],
+                    metadata: {},
+                },
+            ];
+            await store.append(events);
+            const history = await store.history("thread-1");
+            expect(history).toHaveLength(2);
+            expect(history[0].seq).toBe(0);
+            expect(history[1].seq).toBe(1);
+        });
+        it("should be idempotent on event.id", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            const event = {
+                kind: "message",
+                id: "msg-1",
+                tid: "thread-1",
+                seq: 0,
+                timestamp: new Date(),
+                role: "user",
+                content: [{ kind: "text", text: "Hello" }],
+                metadata: {},
+            };
+            await store.append([event]);
+            await store.append([event]); // duplicate
+            const history = await store.history("thread-1");
+            expect(history).toHaveLength(1);
+        });
+        it("should maintain seq ordering", async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            // Insert out of order
+            await store.append([
+                {
+                    kind: "message",
+                    id: "msg-2",
+                    tid: "thread-1",
+                    seq: 2,
+                    timestamp: new Date(),
+                    role: "user",
+                    content: [{ kind: "text", text: "Second" }],
+                    metadata: {},
+                },
+            ]);
+            await store.append([
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    tid: "thread-1",
+                    seq: 1,
+                    timestamp: new Date(),
+                    role: "user",
+                    content: [{ kind: "text", text: "First" }],
+                    metadata: {},
+                },
+            ]);
+            const history = await store.history("thread-1");
+            expect(history).toHaveLength(2);
+            expect(history[0].seq).toBe(1);
+            expect(history[1].seq).toBe(2);
+        });
+    });
+    describe("history", () => {
+        beforeEach(async () => {
+            const newThread = {
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+            };
+            await store.insert(newThread);
+            await store.append([
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    tid: "thread-1",
+                    seq: 0,
+                    timestamp: new Date(),
+                    role: "user",
+                    content: [{ kind: "text", text: "First" }],
+                    metadata: {},
+                },
+                {
+                    kind: "message",
+                    id: "msg-2",
+                    tid: "thread-1",
+                    seq: 1,
+                    timestamp: new Date(),
+                    role: "assistant",
+                    content: [{ kind: "text", text: "Second" }],
+                    metadata: {},
+                },
+                {
+                    kind: "message",
+                    id: "msg-3",
+                    tid: "thread-1",
+                    seq: 2,
+                    timestamp: new Date(),
+                    role: "user",
+                    content: [{ kind: "text", text: "Third" }],
+                    metadata: {},
+                },
+            ]);
+        });
+        it("should return all events by default", async () => {
+            const history = await store.history("thread-1");
+            expect(history).toHaveLength(3);
+        });
+        it("should filter by after seq", async () => {
+            const history = await store.history("thread-1", { after: 0 });
+            expect(history).toHaveLength(2);
+            expect(history[0].seq).toBe(1);
+        });
+        it("should filter by kinds", async () => {
+            await store.append([
+                {
+                    kind: "tool-call",
+                    id: "tc-1",
+                    tid: "thread-1",
+                    seq: 3,
+                    timestamp: new Date(),
+                    callId: "call-1",
+                    toolId: "test-tool",
+                    state: IN_PROGRESS,
+                    arguments: "{}",
+                    metadata: {},
+                },
+            ]);
+            const history = await store.history("thread-1", {
+                kinds: ["tool-call"],
+            });
+            expect(history).toHaveLength(1);
+            expect(history[0].kind).toBe("tool-call");
+        });
+        it("should apply limit", async () => {
+            const history = await store.history("thread-1", { limit: 2 });
+            expect(history).toHaveLength(2);
+        });
+        it("should support desc ordering", async () => {
+            const history = await store.history("thread-1", { order: "desc" });
+            expect(history).toHaveLength(3);
+            expect(history[0].seq).toBe(2);
+            expect(history[2].seq).toBe(0);
+        });
+    });
+    describe("list", () => {
+        beforeEach(async () => {
+            await store.insert({
+                id: "thread-1",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+                state: STOPPED,
+                createdAt: new Date("2024-01-01"),
+            });
+            await store.insert({
+                id: "thread-2",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+                state: RUNNING,
+                createdAt: new Date("2024-01-02"),
+            });
+            await store.insert({
+                id: "thread-3",
+                namespace: "test",
+                agentId: agent.id,
+                model: `${model.provider}/${model.modelId}`,
+                state: DEAD,
+                createdAt: new Date("2024-01-03"),
+            });
+        });
+        it("should list all threads", async () => {
+            const threads = await store.list();
+            expect(threads).toHaveLength(3);
+        });
+        it("should filter by state", async () => {
+            const threads = await store.list({
+                filter: { state: RUNNING },
+            });
+            expect(threads).toHaveLength(1);
+            expect(threads[0].tid).toBe("thread-2");
+        });
+        it("should filter by multiple states", async () => {
+            const threads = await store.list({
+                filter: { state: [STOPPED, DEAD] },
+            });
+            expect(threads).toHaveLength(2);
+        });
+        it("should filter by agentId", async () => {
+            const threads = await store.list({
+                filter: { agentId: agent.id },
+            });
+            expect(threads).toHaveLength(3);
+        });
+        it("should filter by createdAfter", async () => {
+            const threads = await store.list({
+                filter: { createdAfter: new Date("2024-01-01T12:00:00") },
+            });
+            expect(threads).toHaveLength(2);
+        });
+        it("should filter by createdBefore", async () => {
+            const threads = await store.list({
+                filter: { createdBefore: new Date("2024-01-02T12:00:00") },
+            });
+            expect(threads).toHaveLength(2);
+        });
+        it("should apply limit", async () => {
+            const threads = await store.list({ limit: 2 });
+            expect(threads).toHaveLength(2);
+        });
+        it("should apply offset", async () => {
+            const threads = await store.list({ offset: 1, limit: 2 });
+            expect(threads).toHaveLength(2);
+        });
+        it("should sort by createdAt asc", async () => {
+            const threads = await store.list({
+                order: { createdAt: "asc" },
+            });
+            expect(threads[0].tid).toBe("thread-1");
+            expect(threads[2].tid).toBe("thread-3");
+        });
+        it("should sort by createdAt desc (default)", async () => {
+            const threads = await store.list({
+                order: { createdAt: "desc" },
+            });
+            expect(threads[0].tid).toBe("thread-3");
+            expect(threads[2].tid).toBe("thread-1");
+        });
+    });
+});
+describe("InMemoryStorage", () => {
+    it("should create storage with thread store", () => {
+        const storage = new InMemoryStorage();
+        expect(storage.threads).toBeInstanceOf(InMemoryThreadStore);
+    });
+    it("should bind registries to thread store", () => {
+        const storage = new InMemoryStorage();
+        const agents = new Map();
+        const models = new Map();
+        storage.bind({ agents, models });
+        // Verify binding by checking thread store can hydrate (would throw if not bound)
+        expect(() => {
+            storage.threads.registries;
+        }).not.toThrow();
+    });
+    it("should have no-op lifecycle methods", async () => {
+        const storage = new InMemoryStorage();
+        await expect(storage.init()).resolves.toBeUndefined();
+        await expect(storage.close()).resolves.toBeUndefined();
+        await expect(storage.migrate()).resolves.toBeUndefined();
+    });
+    it("should throw on transaction", async () => {
+        const storage = new InMemoryStorage();
+        await expect(storage.transaction(async () => { })).rejects.toThrow("Transactions not supported");
+    });
+});

package/dist/storage/base.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Core storage contracts.
+ */
+import type { AgentRegistry, ModelRegistry } from "../types/kernl";
+import type { ThreadStore } from "./thread";
+/**
+ * The main storage interface for Kernl.
+ *
+ * Provides access to system stores (threads, tasks, traces) and transaction support.
+ */
+export interface KernlStorage {
+    /**
+     * Thread store - manages thread execution records and event history.
+     */
+    threads: ThreadStore;
+    /**
+     * Bind runtime registries to storage.
+     *
+     * Called by Kernl after construction to wire up agent/model lookups.
+     */
+    bind(registries: {
+        agents: AgentRegistry;
+        models: ModelRegistry;
+    }): void;
+    /**
+     * Execute a function within a transaction.
+     *
+     * All operations performed using the transaction-scoped stores will be
+     * committed atomically or rolled back on error.
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Initialize the storage backend.
+     *
+     * Connects to the database and ensures all required schemas/tables exist.
+     */
+    init(): Promise<void>;
+    /**
+     * Close the storage backend and cleanup resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Runs the migrations in order to ensure all required tables exist.
+     */
+    migrate(): Promise<void>;
+}
+/**
+ * Transaction context providing transactional access to stores.
+ */
+export interface Transaction {
+    /**
+     * Thread store within this transaction.
+     */
+    threads: ThreadStore;
+    /**
+     * Commit the transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the transaction.
+     */
+    rollback(): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/storage/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/storage/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,EAAE,WAAW,CAAC;IAKrB;;;;OAIG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI,CAAC;IAEzE;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEhE;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,OAAO,EAAE,WAAW,CAAC;IAMrB;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/storage/base.js

@@ -0,0 +1,4 @@
+/**
+ * Core storage contracts.
+ */
+export {};

package/dist/storage/in-memory.d.ts

@@ -0,0 +1,62 @@
+/**
+ * In-memory storage implementation for Kernl.
+ *
+ * Pure domain-level - no codecs, schemas, or DB records.
+ *
+ * Defined here so that it can be used as default and for testing.
+ */
+import { Thread } from "../thread";
+import type { KernlStorage, Transaction, ThreadStore, NewThread, ThreadUpdate, ThreadInclude, ThreadListOptions, ThreadHistoryOptions } from "../storage";
+import type { ThreadEvent } from "../types/thread";
+import type { AgentRegistry, ModelRegistry } from "../types/kernl";
+/**
+ * In-memory storage implementation.
+ */
+export declare class InMemoryStorage implements KernlStorage {
+    threads: InMemoryThreadStore;
+    constructor();
+    bind(registries: {
+        agents: AgentRegistry;
+        models: ModelRegistry;
+    }): void;
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    init(): Promise<void>;
+    close(): Promise<void>;
+    migrate(): Promise<void>;
+}
+/**
+ * In-memory thread store implementation.
+ */
+export declare class InMemoryThreadStore implements ThreadStore {
+    private threads;
+    private events;
+    private registries;
+    bind(registries: {
+        agents: AgentRegistry;
+        models: ModelRegistry;
+    }): void;
+    get(tid: string, include?: ThreadInclude): Promise<Thread | null>;
+    list(options?: ThreadListOptions): Promise<Thread[]>;
+    insert(thread: NewThread): Promise<Thread>;
+    update(tid: string, patch: ThreadUpdate): Promise<Thread>;
+    delete(tid: string): Promise<void>;
+    history(tid: string, opts?: ThreadHistoryOptions): Promise<ThreadEvent[]>;
+    append(events: ThreadEvent[]): Promise<void>;
+    /**
+     * Hydrate a Thread instance from in-memory data.
+     */
+    private hydrate;
+    /**
+     * Filter and sort event history based on options.
+     */
+    private filterHistory;
+    /**
+     * Apply filters to thread list.
+     */
+    private applyFilters;
+    /**
+     * Apply sorting to thread list.
+     */
+    private applySorting;
+}
+//# sourceMappingURL=in-memory.d.ts.map

package/dist/storage/in-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../src/storage/in-memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAKlC,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EAGrB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAElE;;GAEG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,OAAO,EAAE,mBAAmB,CAAC;;IAM7B,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIlE,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAM/D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAmBD;;GAEG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,UAAU,CACX;IAEP,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIlE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAejE,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA2BpD,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAsB1C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBzD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,OAAO,CACX,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,WAAW,EAAE,CAAC;IAInB,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BlD;;OAEG;IACH,OAAO,CAAC,OAAO;IAgCf;;OAEG;IACH,OAAO,CAAC,aAAa;IAyCrB;;OAEG;IACH,OAAO,CAAC,YAAY;IA2CpB;;OAEG;IACH,OAAO,CAAC,YAAY;CA6BrB"}