kernl 0.10.0 → 0.11.1

package/src/agent/base.ts

@@ -4,7 +4,7 @@ import type { Context, UnknownContext } from "@/context";
 import type { Tool, BaseToolkit } from "@/tool";
 import { memory } from "@/tool";
 import { MisconfiguredError } from "@/lib/error";
-import { AgentHooks } from "@/lifecycle";
+import { AgentHooks, type AgentHookEvents } from "@/lifecycle";
 import type { Kernl } from "@/kernl";
 import type {
   AgentMemoryCreate,
@@ -101,6 +101,18 @@ export abstract class BaseAgent<
     }
   }
 
+  /**
+   * Emit a lifecycle event to agent and kernl listeners.
+   */
+  emit<K extends keyof AgentHookEvents<TContext, TOutput>>(
+    event: K,
+    ...args: AgentHookEvents<TContext, TOutput>[K]
+  ): boolean {
+    const result = super.emit(event, ...args);
+    this.kernl?.emit(event, ...(args as any));
+    return result;
+  }
+
   /**
    * Get a specific tool by ID from systools and toolkits.
    */

package/src/agent.ts

@@ -13,7 +13,7 @@ import type {
   RThreadHistoryParams,
   RThreadUpdateParams,
 } from "@/api/resources/threads/types";
-import type { Context, UnknownContext } from "./context";
+import { Context, type UnknownContext } from "./context";
 import {
   InputGuardrail,
   OutputGuardrail,
@@ -102,10 +102,14 @@ export class Agent<
 
     // create new thread if not found in storage or no tid provided
     if (!thread) {
+      const ctx = options?.context
+        ? new Context<TContext>(options?.namespace ?? "kernl", options.context)
+        : undefined;
+
       thread = new Thread({
         agent: this,
         input: items,
-        context: options?.context,
+        context: ctx,
         model: options?.model,
         task: options?.task,
         tid: options?.threadId,
@@ -116,6 +120,9 @@ export class Agent<
     }
 
     // resume existing thread from storage
+    if (options?.context) {
+      thread.context.context = options.context;
+    }
     thread.append(...items);
     return this.kernl.schedule(thread);
   }
@@ -163,10 +170,14 @@ export class Agent<
 
     // create new thread if not found in storage or no tid provided
     if (!thread) {
+      const ctx = options?.context
+        ? new Context<TContext>(options?.namespace ?? "kernl", options.context)
+        : undefined;
+
       thread = new Thread({
         agent: this,
         input: items,
-        context: options?.context,
+        context: ctx,
         model: options?.model,
         task: options?.task,
         tid: options?.threadId,
@@ -178,6 +189,9 @@ export class Agent<
     }
 
     // resume existing thread from storage
+    if (options?.context) {
+      thread.context.context = options.context;
+    }
     thread.append(...items);
     yield* this.kernl.scheduleStream(thread);
   }

package/src/context.ts

@@ -23,6 +23,8 @@ export class Context<TContext = UnknownContext> {
   /**
    * The agent executing this context.
    * Set by the thread during execution.
+   *
+   * NOTE: Primarily used by system tools (e.g., memory) that need agent access.
    */
   agent?: Agent<TContext, any>;
 

package/src/index.ts

@@ -8,6 +8,18 @@ export type {
 export { Agent } from "./agent";
 export { Context } from "./context";
 
+// --- lifecycle hooks ---
+
+export type {
+  LifecycleEvent,
+  ThreadStartEvent,
+  ThreadStopEvent,
+  ModelCallStartEvent,
+  ModelCallEndEvent,
+  ToolCallStartEvent,
+  ToolCallEndEvent,
+} from "./lifecycle";
+
 // --- realtime ---
 
 export { RealtimeAgent, RealtimeSession, WebSocketTransport } from "./realtime";

package/src/kernl/kernl.ts

@@ -2,7 +2,6 @@ import type { LanguageModel } from "@kernl-sdk/protocol";
 import { resolveEmbeddingModel } from "@kernl-sdk/retrieval";
 
 import { BaseAgent } from "@/agent/base";
-import { UnknownContext } from "@/context";
 import { KernlHooks } from "@/lifecycle";
 import type { Thread } from "@/thread";
 import type { ResolvedAgentResponse } from "@/guardrail";
@@ -28,7 +27,7 @@ import type { KernlOptions, MemoryOptions, StorageOptions } from "./types";
  * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
  * tracing.
  */
-export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
+export class Kernl extends KernlHooks {
   private readonly _agents: Map<string, BaseAgent> = new Map();
   private readonly _models: Map<string, LanguageModel> = new Map();
 
@@ -103,8 +102,42 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
     thread: Thread<TContext, TOutput>,
   ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>> {
     this.athreads.set(thread.tid, thread);
+
+    this.emit("thread.start", {
+      kind: "thread.start",
+      threadId: thread.tid,
+      agentId: thread.agent.id,
+      namespace: thread.namespace,
+      context: thread.context,
+    });
+
     try {
-      return await thread.execute();
+      const result = await thread.execute();
+
+      this.emit("thread.stop", {
+        kind: "thread.stop",
+        threadId: thread.tid,
+        agentId: thread.agent.id,
+        namespace: thread.namespace,
+        context: thread.context,
+        state: thread.state,
+        outcome: "success",
+        result: result.response,
+      });
+
+      return result;
+    } catch (err) {
+      this.emit("thread.stop", {
+        kind: "thread.stop",
+        threadId: thread.tid,
+        agentId: thread.agent.id,
+        namespace: thread.namespace,
+        context: thread.context,
+        state: thread.state,
+        outcome: "error",
+        error: err instanceof Error ? err.message : String(err),
+      });
+      throw err;
     } finally {
       this.athreads.delete(thread.tid);
     }
@@ -135,8 +168,39 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
     thread: Thread<TContext, TOutput>,
   ): AsyncIterable<ThreadStreamEvent> {
     this.athreads.set(thread.tid, thread);
+
+    this.emit("thread.start", {
+      kind: "thread.start",
+      threadId: thread.tid,
+      agentId: thread.agent.id,
+      namespace: thread.namespace,
+      context: thread.context,
+    });
+
     try {
       yield* thread.stream();
+
+      this.emit("thread.stop", {
+        kind: "thread.stop",
+        threadId: thread.tid,
+        agentId: thread.agent.id,
+        namespace: thread.namespace,
+        context: thread.context,
+        state: thread.state,
+        outcome: "success",
+      });
+    } catch (err) {
+      this.emit("thread.stop", {
+        kind: "thread.stop",
+        threadId: thread.tid,
+        agentId: thread.agent.id,
+        namespace: thread.namespace,
+        context: thread.context,
+        state: thread.state,
+        outcome: "error",
+        error: err instanceof Error ? err.message : String(err),
+      });
+      throw err;
     } finally {
       this.athreads.delete(thread.tid);
     }