kernl 0.2.1 → 0.6.0

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

package/src/agent.ts

@@ -1,27 +1,37 @@
 import {
+  message,
   LanguageModel,
+  LanguageModelItem,
   LanguageModelRequestSettings,
-  message,
 } from "@kernl-sdk/protocol";
 
+import { Thread } from "./thread";
+import type { Kernl } from "./kernl";
+import type {
+  RThreadsListParams,
+  RThreadCreateParams,
+  RThreadGetOptions,
+  RThreadHistoryParams,
+  RThreadUpdateParams,
+} from "@/api/resources/threads/types";
 import type { Context, UnknownContext } from "./context";
-import { InputGuardrail, OutputGuardrail } from "./guardrail";
-import { AgentHooks } from "./lifecycle";
-import { BaseToolkit } from "./tool/toolkit";
 import { Tool } from "./tool";
-import { Thread } from "./thread";
-
-import { MisconfiguredError } from "./lib/error";
+import { BaseToolkit } from "./tool/toolkit";
+import {
+  InputGuardrail,
+  OutputGuardrail,
+  type ResolvedAgentResponse,
+} from "./guardrail";
+import { AgentHooks } from "./lifecycle";
 
+import { MisconfiguredError, RuntimeError } from "./lib/error";
 import type { AgentConfig, AgentResponseType } from "./types/agent";
 import type {
   TextResponse,
-  ThreadOptions,
+  ThreadExecuteOptions,
   ThreadExecuteResult,
   ThreadStreamEvent,
 } from "./types/thread";
-import type { Kernl } from "./kernl";
-import type { ResolvedAgentResponse } from "./guardrail";
 
 export class Agent<
     TContext = UnknownContext,
@@ -113,10 +123,13 @@ export class Agent<
 
   /**
    * Blocking execution - spawns or resumes thread and waits for completion
+   *
+   * @throws {RuntimeError} If the specified thread is already running (concurrent execution not allowed)
+   * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
    */
   async run(
-    instructions: string,
-    options?: ThreadOptions<TContext>,
+    input: string | LanguageModelItem[],
+    options?: ThreadExecuteOptions<TContext>,
   ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
     if (!this.kernl) {
       throw new MisconfiguredError(
@@ -124,17 +137,46 @@ export class Agent<
       );
     }
 
-    const m = message({ role: "user", text: instructions });
+    const items =
+      typeof input === "string"
+        ? [message({ role: "user", text: input })]
+        : input;
     const tid = options?.threadId;
 
-    // NOTE: may end up moving this to the kernl
-    let thread = tid ? this.kernl.threads.get(tid) : null;
+    let thread: Thread<TContext, TResponse> | null = null;
+
+    if (tid) {
+      // no concurrent execution of same thread - correctness contract
+      // TODO: race condition - need to check again after async storage.get()
+      if (this.kernl.athreads.has(tid)) {
+        throw new RuntimeError(`Thread ${tid} is already running.`);
+      }
+
+      // try to resume from storage if available
+      if (this.kernl.storage?.threads) {
+        thread = (await this.kernl.storage.threads.get(tid, {
+          history: true,
+        })) as Thread<TContext, TResponse> | null;
+      }
+    }
+
+    // create new thread if not found in storage or no tid provided
     if (!thread) {
-      thread = new Thread(this.kernl, this, [m], options);
+      thread = new Thread({
+        agent: this,
+        input: items,
+        context: options?.context,
+        model: options?.model,
+        task: options?.task,
+        tid: options?.threadId,
+        namespace: options?.namespace,
+        storage: this.kernl.storage?.threads,
+      });
       return this.kernl.spawn(thread);
     }
 
-    thread.append(m);
+    // resume existing thread from storage
+    thread.append(...items);
     return this.kernl.schedule(thread);
   }
 
@@ -142,10 +184,13 @@ export class Agent<
    * Streaming execution - spawns or resumes thread and returns async iterator
    *
    * NOTE: streaming probably won't make sense in scheduling contexts so spawnStream etc. won't make sense
+   *
+   * @throws {RuntimeError} If the specified thread is already running (concurrent execution not allowed)
+   * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
    */
   async *stream(
-    instructions: string,
-    options?: ThreadOptions<TContext>,
+    input: string | LanguageModelItem[],
+    options?: ThreadExecuteOptions<TContext>,
   ): AsyncIterable<ThreadStreamEvent> {
     if (!this.kernl) {
       throw new MisconfiguredError(
@@ -153,22 +198,53 @@ export class Agent<
       );
     }
 
-    const m = message({ role: "user", text: instructions });
+    const items =
+      typeof input === "string"
+        ? [message({ role: "user", text: input })]
+        : input;
     const tid = options?.threadId;
 
-    // NOTE: may end up moving this to the kernl
-    let thread = tid ? this.kernl.threads.get(tid) : null;
+    let thread: Thread<TContext, TResponse> | null = null;
+
+    if (tid) {
+      // no concurrent execution of same thread - correctness contract
+      // TODO: race condition - need to check again after async storage.get()
+      if (this.kernl.athreads.has(tid)) {
+        throw new RuntimeError(`Thread ${tid} is already running.`);
+      }
+
+      // try to resume from storage if available
+      if (this.kernl.storage?.threads) {
+        thread = (await this.kernl.storage.threads.get(tid, {
+          history: true,
+        })) as Thread<TContext, TResponse> | null;
+      }
+    }
+
+    // create new thread if not found in storage or no tid provided
     if (!thread) {
-      thread = new Thread(this.kernl, this, [m], options);
+      thread = new Thread({
+        agent: this,
+        input: items,
+        context: options?.context,
+        model: options?.model,
+        task: options?.task,
+        tid: options?.threadId,
+        namespace: options?.namespace,
+        storage: this.kernl.storage?.threads,
+      });
       yield* this.kernl.spawnStream(thread);
       return;
     }
 
-    thread.append(m);
+    // resume existing thread from storage
+    thread.append(...items);
     yield* this.kernl.scheduleStream(thread);
   }
 
   /**
+   * @internal
+   *
    * Get a specific tool by ID from all toolkits.
    *
    * @param id The tool ID to look up
@@ -183,6 +259,8 @@ export class Agent<
   }
 
   /**
+   * @internal
+   *
    * Get all tools available from all toolkits for the given context.
    * Checks for duplicate tool IDs across toolkits and throws an error if found.
    *
@@ -213,4 +291,41 @@ export class Agent<
 
     return allTools;
   }
+
+  /**
+   * Thread management scoped to this agent.
+   *
+   * Convenience wrapper around kernl.threads that automatically filters to this agent's threads.
+   */
+  get threads() {
+    if (!this.kernl) {
+      throw new MisconfiguredError(
+        `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
+      );
+    }
+
+    const agentId = this.id;
+    const kthreads = this.kernl.threads;
+
+    return {
+      get: (tid: string, options?: RThreadGetOptions) =>
+        kthreads.get(tid, options),
+      list: (params: Omit<RThreadsListParams, "agentId"> = {}) =>
+        kthreads.list({ ...params, agentId }),
+      delete: (tid: string) => kthreads.delete(tid),
+      history: (tid: string, params?: RThreadHistoryParams) =>
+        kthreads.history(tid, params),
+      create: (params: Omit<RThreadCreateParams, "agentId" | "model">) =>
+        kthreads.create({
+          ...params,
+          agentId,
+          model: {
+            provider: this.model.provider,
+            modelId: this.model.modelId,
+          },
+        }),
+      update: (tid: string, patch: RThreadUpdateParams) =>
+        kthreads.update(tid, patch),
+    };
+  }
 }