kernl 0.2.1 → 0.6.1

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");
+  });
+});

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

@@ -0,0 +1,441 @@
+import { describe, it, expect } from "vitest";
+import { Agent } from "@/agent";
+import { Kernl } from "@/kernl";
+import { createMockModel } from "@/thread/__tests__/fixtures/mock-model";
+import { MisconfiguredError } from "@/lib/error";
+import { message } from "@kernl-sdk/protocol";
+import { InMemoryStorage } from "@/storage/in-memory";
+
+describe("Agent.run() lifecycle", () => {
+  describe("Storage wiring", () => {
+    it("should pass storage to new Thread when creating", async () => {
+      const storage = new InMemoryStorage();
+      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({ storage: { db: storage } });
+      kernl.register(agent);
+
+      await agent.run("Hello");
+
+      // Verify storage was used - check that events were appended
+      const threads = await storage.threads.list();
+      expect(threads).toHaveLength(1);
+
+      const history = await storage.threads.history(threads[0].tid);
+      expect(history.length).toBeGreaterThan(0);
+    });
+
+    it("should work without storage (persist is no-op)", 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(); // No storage
+      kernl.register(agent);
+
+      const result = await agent.run("Hello");
+
+      // Should complete successfully
+      expect(result.response).toBe("Done");
+      expect(result.state).toBe("stopped");
+    });
+
+    it("should throw MisconfiguredError when agent not bound to kernl", 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,
+      });
+
+      // Don't register with kernl
+      await expect(agent.run("Hello")).rejects.toThrow(MisconfiguredError);
+      await expect(agent.run("Hello")).rejects.toThrow(/not bound to kernl/);
+    });
+  });
+
+  describe("New thread path", () => {
+    it("should create new thread when no threadId provided", 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 result = await agent.run("Hello");
+
+      expect(result.response).toBe("Done");
+      expect(result.state).toBe("stopped");
+    });
+
+    it("should create new thread when threadId not found in storage", async () => {
+      const storage = new InMemoryStorage();
+      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({ storage: { db: storage } });
+      kernl.register(agent);
+
+      await agent.run("Hello", { threadId: "non-existent" });
+
+      // Should have created new thread with the specified tid
+      const threads = await storage.threads.list();
+      expect(threads).toHaveLength(1);
+      expect(threads[0].tid).toBe("non-existent");
+    });
+
+    it("should resume existing thread from storage", async () => {
+      const storage = new InMemoryStorage();
+      const model = createMockModel(async () => ({
+        content: [message({ role: "assistant", text: "Response" })],
+        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({ storage: { db: storage } });
+      kernl.register(agent);
+
+      const tid = "resume-thread";
+
+      // First run
+      await agent.run("First", { threadId: tid });
+
+      const firstHistory = await storage.threads.history(tid);
+      const firstEventCount = firstHistory.length;
+      expect(firstEventCount).toBeGreaterThanOrEqual(2); // user + assistant
+
+      // Second run (resume)
+      await agent.run("Second", { threadId: tid });
+
+      const secondHistory = await storage.threads.history(tid);
+      const secondEventCount = secondHistory.length;
+
+      // Should have more events (added user + assistant from second run)
+      expect(secondEventCount).toBeGreaterThanOrEqual(firstEventCount + 2);
+    });
+  });
+
+  describe("String vs array input", () => {
+    it("should handle string input (converted to message)", async () => {
+      const storage = new InMemoryStorage();
+      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({ storage: { db: storage } });
+      kernl.register(agent);
+
+      await agent.run("Hello world");
+
+      const threads = await storage.threads.list();
+      const events = await storage.threads.history(threads[0].tid);
+
+      // Find the user message (first event should be user message)
+      const userMessage = events.find((e: any) => e.role === "user");
+      expect(userMessage).toMatchObject({
+        kind: "message",
+        role: "user",
+        content: [{ kind: "text", text: "Hello world" }],
+      });
+    });
+
+    it("should handle array input (used as-is)", async () => {
+      const storage = new InMemoryStorage();
+      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({ storage: { db: storage } });
+      kernl.register(agent);
+
+      const input = [message({ role: "user", text: "Custom" })];
+      await agent.run(input);
+
+      const threads = await storage.threads.list();
+      const events = await storage.threads.history(threads[0].tid);
+
+      // Find the user message
+      const userMessage = events.find((e: any) => e.role === "user");
+      expect(userMessage).toMatchObject({
+        kind: "message",
+        role: "user",
+        content: [{ kind: "text", text: "Custom" }],
+      });
+    });
+  });
+});
+
+describe("Agent.stream() lifecycle", () => {
+  it("should yield stream-start event first", 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 events = [];
+    for await (const event of agent.stream("Hello")) {
+      events.push(event);
+    }
+
+    expect(events[0]).toEqual({ kind: "stream-start" });
+  });
+
+  it("should have same persistence behavior as run()", async () => {
+    const storage = new InMemoryStorage();
+    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({ storage: { db: storage } });
+    kernl.register(agent);
+
+    const events = [];
+    for await (const event of agent.stream("Hello")) {
+      events.push(event);
+    }
+
+    // Should have persisted like run()
+    const threads = await storage.threads.list();
+    expect(threads).toHaveLength(1);
+
+    const history = await storage.threads.history(threads[0].tid);
+    expect(history.length).toBeGreaterThan(0);
+
+    // Should have streamed events
+    expect(events).toEqual(
+      expect.arrayContaining([
+        { kind: "stream-start" },
+        expect.objectContaining({ kind: "message" }),
+      ]),
+    );
+  });
+});
+
+describe("Agent.threads helper", () => {
+  it("should throw MisconfiguredError when agent is not bound to kernl", () => {
+    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,
+    });
+
+    expect(() => agent.threads).toThrow(MisconfiguredError);
+  });
+
+  it("should list only threads for this agent", async () => {
+    const storage = new InMemoryStorage();
+    const model = createMockModel(async () => ({
+      content: [message({ role: "assistant", text: "Done" })],
+      finishReason: "stop",
+      usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+      warnings: [],
+    }));
+
+    const agentA = new Agent({
+      id: "agent-a",
+      name: "Agent A",
+      instructions: "Test",
+      model,
+    });
+
+    const agentB = new Agent({
+      id: "agent-b",
+      name: "Agent B",
+      instructions: "Test",
+      model,
+    });
+
+    const kernl = new Kernl({ storage: { db: storage } });
+    kernl.register(agentA);
+    kernl.register(agentB);
+
+    await agentA.run("Hello from A");
+    await agentB.run("Hello from B");
+    await agentB.run("Another from B");
+
+    const threadsAPage = await agentA.threads.list();
+    const threadsBPage = await agentB.threads.list();
+
+    const threadsA = await threadsAPage.collect();
+    const threadsB = await threadsBPage.collect();
+
+    expect(threadsA).toHaveLength(1);
+    expect(threadsB.length).toBeGreaterThanOrEqual(2);
+
+    for (const thread of threadsA) {
+      expect(thread.agentId).toBe("agent-a");
+    }
+
+    for (const thread of threadsB) {
+      expect(thread.agentId).toBe("agent-b");
+    }
+  });
+
+  it("should expose thread history via threads.history()", async () => {
+    const storage = new InMemoryStorage();
+    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({ storage: { db: storage } });
+    kernl.register(agent);
+
+    await agent.run("Hello");
+
+    const threadsPage = await agent.threads.list();
+    const threads = await threadsPage.collect();
+    expect(threads).toHaveLength(1);
+
+    const tid = threads[0].tid;
+    const events = await agent.threads.history(tid, { order: "asc" });
+
+    // Expect exactly two events: user message then assistant message
+    expect(events).toHaveLength(2);
+
+    const [userEvent, assistantEvent] = events;
+
+    // Common headers
+    expect(userEvent.tid).toBe(tid);
+    expect(assistantEvent.tid).toBe(tid);
+    expect(userEvent.seq).toBe(0);
+    expect(assistantEvent.seq).toBe(1);
+
+    // User message
+    expect(userEvent.kind).toBe("message");
+    // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+    expect(userEvent.role).toBe("user");
+    // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+    expect(userEvent.content).toEqual([
+      { kind: "text", text: "Hello" },
+    ]);
+
+    // Assistant message
+    expect(assistantEvent.kind).toBe("message");
+    // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+    expect(assistantEvent.role).toBe("assistant");
+    // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+    expect(assistantEvent.content).toEqual([
+      { kind: "text", text: "Done" },
+    ]);
+  });
+});
+