kernl 0.2.1 → 0.6.1

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