kernl 0.10.0 → 0.11.1

package/src/lifecycle.ts

@@ -1,131 +1,307 @@
 import { Emitter } from "@kernl-sdk/shared";
 
-import { Agent } from "./agent";
-import { Context, UnknownContext } from "./context";
-import { Tool } from "./tool";
-import type { ToolCall } from "@kernl-sdk/protocol";
-
-import { AgentOutputType } from "@/agent/types";
-import { TextOutput } from "@/thread/types";
-
-export type AgentHookEvents<
-  TContext = UnknownContext,
-  TOutput extends AgentOutputType = TextOutput,
-> = {
-  /**
-   * @param context - The context of the run
-   */
-  agent_start: [context: Context<TContext>, agent: Agent<TContext, TOutput>];
-  /**
-   * @param context - The context of the run
-   * @param output - The output of the agent
-   */
-  agent_end: [context: Context<TContext>, output: string];
-  // /**
-  //  * @param context - The context of the run
-  //  * @param agent - The agent that is handing off
-  //  * @param nextAgent - The next agent to run
-  //  */
-  // agent_handoff: [context: Context<TContext>, nextAgent: Agent<any, any>];
-  /**
-   * @param context - The context of the run
-   * @param agent - The agent that is starting a tool
-   * @param tool - The tool that is starting
-   */
-  agent_tool_start: [
-    context: Context<TContext>,
-    tool: Tool<any>,
-    details: { toolCall: ToolCall },
-  ];
-  /**
-   * @param context - The context of the run
-   * @param agent - The agent that is ending a tool
-   * @param tool - The tool that is ending
-   * @param result - The result of the tool
-   */
-  agent_tool_end: [
-    context: Context<TContext>,
-    tool: Tool<any>,
-    result: string,
-    details: { toolCall: ToolCall },
-  ];
-};
+import type {
+  LanguageModelUsage,
+  LanguageModelFinishReason,
+  LanguageModelRequestSettings,
+  ToolCallState,
+} from "@kernl-sdk/protocol";
+import type { Context } from "@/context";
+import type { ThreadState } from "@/thread/types";
+
+// --- Thread Events ---
 
 /**
- * Event emitter that every Agent instance inherits from and that emits events for the lifecycle
- * of the agent.
+ * Emitted when a thread starts execution.
  */
-export class AgentHooks<
-  TContext = UnknownContext,
-  TOutput extends AgentOutputType = TextOutput,
-> extends Emitter<AgentHookEvents<TContext, TOutput>> {}
+export interface ThreadStartEvent<TContext = unknown> {
+  readonly kind: "thread.start";
+
+  /**
+   * The thread ID.
+   */
+  threadId: string;
+
+  /**
+   * The agent executing this thread.
+   */
+  agentId: string;
+
+  /**
+   * The namespace of the thread.
+   */
+  namespace: string;
+
+  /**
+   * The context for this execution.
+   *
+   * NOTE: Includes `context.agent` reference for tools - may be optimized in future.
+   */
+  context: Context<TContext>;
+}
 
 /**
- * Events emitted by the kernl during execution.
- *
- * Unlike AgentHookEvents (which are emitted by individual agents with implicit context),
- * KernlHookEvents explicitly include the agent reference in all events since it needs to
- * coordinate multiple agents and listeners need to know which agent triggered each event.
+ * Emitted when a thread stops execution.
  */
-export type KernlHookEvents<
-  TContext = UnknownContext,
-  TOutput extends AgentOutputType = TextOutput,
-> = {
-  /**
-   * @param context - The context of the run
-   * @param agent - The agent that is starting
-   */
-  agent_start: [context: Context<TContext>, agent: Agent<TContext, TOutput>];
-  /**
-   * @param context - The context of the run
-   * @param agent - The agent that is ending
-   * @param output - The output of the agent
-   */
-  agent_end: [
-    context: Context<TContext>,
-    agent: Agent<TContext, TOutput>,
-    output: string,
-  ];
-  /**
-   * @param context - The context of the run
-   * @param fromAgent - The agent that is handing off
-   * @param toAgent - The next agent to run
-   */
-  agent_handoff: [
-    context: Context<TContext>,
-    fromAgent: Agent<any, any>,
-    toAgent: Agent<any, any>,
-  ];
-  /**
-   * @param context - The context of the run
-   * @param agent - The agent that is starting a tool
-   * @param tool - The tool that is starting
-   */
-  agent_tool_start: [
-    context: Context<TContext>,
-    agent: Agent<TContext, TOutput>,
-    tool: Tool,
-    details: { toolCall: ToolCall },
-  ];
-  /**
-   * @param context - The context of the run
-   * @param agent - The agent that is ending a tool
-   * @param tool - The tool that is ending
-   * @param result - The result of the tool
-   */
-  agent_tool_end: [
-    context: Context<TContext>,
-    agent: Agent<TContext, TOutput>,
-    tool: Tool,
-    result: string,
-    details: { toolCall: ToolCall },
-  ];
+export interface ThreadStopEvent<TContext = unknown, TOutput = unknown> {
+  readonly kind: "thread.stop";
+
+  /**
+   * The thread ID.
+   */
+  threadId: string;
+
+  /**
+   * The agent that executed this thread.
+   */
+  agentId: string;
+
+  /**
+   * The namespace of the thread.
+   */
+  namespace: string;
+
+  /**
+   * The context for this execution.
+   *
+   * NOTE: Includes `context.agent` reference for tools - may be optimized in future.
+   */
+  context: Context<TContext>;
+
+  /**
+   * Final state of the thread.
+   */
+  state: ThreadState;
+
+  /**
+   * The outcome of the execution.
+   */
+  outcome: "success" | "error" | "cancelled";
+
+  /**
+   * The result if outcome is "success".
+   */
+  result?: TOutput;
+
+  /**
+   * Error message if outcome is "error".
+   */
+  error?: string;
+}
+
+// --- Model Events ---
+
+/**
+ * Emitted when a model call starts.
+ */
+export interface ModelCallStartEvent<TContext = unknown> {
+  readonly kind: "model.call.start";
+
+  /**
+   * The model provider.
+   */
+  provider: string;
+
+  /**
+   * The model ID.
+   */
+  modelId: string;
+
+  /**
+   * Request settings passed to the model.
+   */
+  settings: LanguageModelRequestSettings;
+
+  /**
+   * Thread ID if called within a thread context.
+   */
+  threadId?: string;
+
+  /**
+   * Agent ID if called within an agent context.
+   */
+  agentId?: string;
+
+  /**
+   * Execution context if available.
+   *
+   * NOTE: Includes `context.agent` reference for tools - may be optimized in future.
+   */
+  context?: Context<TContext>;
+}
+
+/**
+ * Emitted when a model call ends.
+ */
+export interface ModelCallEndEvent<TContext = unknown> {
+  readonly kind: "model.call.end";
+
+  /**
+   * The model provider.
+   */
+  provider: string;
+
+  /**
+   * The model ID.
+   */
+  modelId: string;
+
+  /**
+   * Reason the model stopped generating.
+   */
+  finishReason: LanguageModelFinishReason;
+
+  /**
+   * Token usage for this call.
+   */
+  usage?: LanguageModelUsage;
+
+  /**
+   * Thread ID if called within a thread context.
+   */
+  threadId?: string;
+
+  /**
+   * Agent ID if called within an agent context.
+   */
+  agentId?: string;
+
+  /**
+   * Execution context if available.
+   *
+   * NOTE: Includes `context.agent` reference for tools - may be optimized in future.
+   */
+  context?: Context<TContext>;
+}
+
+// --- Tool Events ---
+
+/**
+ * Emitted when a tool call starts.
+ */
+export interface ToolCallStartEvent<TContext = unknown> {
+  readonly kind: "tool.call.start";
+
+  /**
+   * The thread ID.
+   */
+  threadId: string;
+
+  /**
+   * The agent executing this tool.
+   */
+  agentId: string;
+
+  /**
+   * The context for this execution.
+   *
+   * NOTE: Includes `context.agent` reference for tools - may be optimized in future.
+   */
+  context: Context<TContext>;
+
+  /**
+   * The tool being called.
+   */
+  toolId: string;
+
+  /**
+   * Unique identifier for this call.
+   */
+  callId: string;
+
+  /**
+   * Arguments passed to the tool (parsed JSON).
+   */
+  args: Record<string, unknown>;
+}
+
+/**
+ * Emitted when a tool call ends.
+ */
+export interface ToolCallEndEvent<TContext = unknown> {
+  readonly kind: "tool.call.end";
+
+  /**
+   * The thread ID.
+   */
+  threadId: string;
+
+  /**
+   * The agent that executed this tool.
+   */
+  agentId: string;
+
+  /**
+   * The context for this execution.
+   *
+   * NOTE: Includes `context.agent` reference for tools - may be optimized in future.
+   */
+  context: Context<TContext>;
+
+  /**
+   * The tool that was called.
+   */
+  toolId: string;
+
+  /**
+   * Unique identifier for this call.
+   */
+  callId: string;
+
+  /**
+   * Final state of the tool call.
+   */
+  state: ToolCallState;
+
+  /**
+   * Result if state is "completed".
+   */
+  result?: string;
+
+  /**
+   * Error message if state is "failed", null if successful.
+   */
+  error: string | null;
+}
+
+// --- Union ---
+
+export type LifecycleEvent<TContext = unknown, TOutput = unknown> =
+  | ThreadStartEvent<TContext>
+  | ThreadStopEvent<TContext, TOutput>
+  | ModelCallStartEvent<TContext>
+  | ModelCallEndEvent<TContext>
+  | ToolCallStartEvent<TContext>
+  | ToolCallEndEvent<TContext>;
+
+// --- Event Maps ---
+
+/**
+ * Event map for agent-level lifecycle hooks (typed).
+ */
+export type AgentHookEvents<TContext = unknown, TOutput = unknown> = {
+  "thread.start": [event: ThreadStartEvent<TContext>];
+  "thread.stop": [event: ThreadStopEvent<TContext, TOutput>];
+  "model.call.start": [event: ModelCallStartEvent<TContext>];
+  "model.call.end": [event: ModelCallEndEvent<TContext>];
+  "tool.call.start": [event: ToolCallStartEvent<TContext>];
+  "tool.call.end": [event: ToolCallEndEvent<TContext>];
 };
 
 /**
- * Event emitter that the kernl uses to emit events for the lifecycle of every agent run.
+ * Event map for Kernl-level lifecycle hooks (untyped).
+ */
+export type KernlHookEvents = AgentHookEvents<unknown, unknown>;
+
+/**
+ * Event emitter for agent-level lifecycle events.
+ */
+export class AgentHooks<
+  TContext = unknown,
+  TOutput = unknown,
+> extends Emitter<AgentHookEvents<TContext, TOutput>> {}
+
+/**
+ * Event emitter for Kernl-level lifecycle events.
  */
-export class KernlHooks<
-  TContext = UnknownContext,
-  TOutput extends AgentOutputType = TextOutput,
-> extends Emitter<KernlHookEvents<TContext, TOutput>> {}
+export class KernlHooks extends Emitter<KernlHookEvents> {}

package/src/thread/__tests__/thread.test.ts

@@ -316,7 +316,7 @@ describe("Thread", () => {
                 toolId: "simple",
                 state: IN_PROGRESS,
                 callId: "call_1",
-                arguments: "first",
+                arguments: JSON.stringify({ value: "first" }),
               },
             ],
             finishReason: "stop",
@@ -343,7 +343,7 @@ describe("Thread", () => {
                 toolId: "simple",
                 state: IN_PROGRESS,
                 callId: "call_2",
-                arguments: "second",
+                arguments: JSON.stringify({ value: "second" }),
               },
             ],
             finishReason: "stop",

package/src/thread/thread.ts

@@ -19,6 +19,8 @@ import {
   LanguageModel,
   LanguageModelItem,
   LanguageModelRequest,
+  type LanguageModelUsage,
+  type LanguageModelFinishReason,
 } from "@kernl-sdk/protocol";
 import { randomID, filter } from "@kernl-sdk/shared/lib";
 
@@ -90,8 +92,8 @@ export class Thread<
   readonly tid: string;
   readonly namespace: string;
   readonly agent: Agent<TContext, TOutput>;
-  readonly context: Context<TContext>;
-  readonly model: LanguageModel; /* inherited from the agent unless specified */
+  context: Context<TContext>;
+  model: LanguageModel; /* inherited from the agent unless specified */
   readonly parent: Task<TContext> | null; /* parent task which spawned this thread */
   readonly createdAt: Date;
   readonly updatedAt: Date;
@@ -200,7 +202,7 @@ export class Thread<
    */
   private async *_execute(): AsyncGenerator<ThreadStreamEvent, void> {
     for (;;) {
-      let err = false;
+      let err: Error | undefined = undefined;
 
       if (this.abort?.signal.aborted) {
         return;
@@ -209,7 +211,7 @@ export class Thread<
       const events = [];
       for await (const e of this.tick()) {
         if (e.kind === "error") {
-          err = true;
+          err = e.error;
           logger.error(e.error); // (TODO): onError callback in options
         }
         // we don't want deltas in the history
@@ -220,9 +222,9 @@ export class Thread<
         yield e;
       }
 
-      // if an error event occurred → terminate
+      // if an error event occurred → throw it
       if (err) {
-        return;
+        throw err;
       }
 
       // if model returns a message with no action intentions → terminal state
@@ -276,21 +278,59 @@ export class Thread<
 
     const req = await this.prepareModelRequest(this.history);
 
+    this.agent.emit("model.call.start", {
+      kind: "model.call.start",
+      provider: this.model.provider,
+      modelId: this.model.modelId,
+      settings: req.settings ?? {},
+      threadId: this.tid,
+      agentId: this.agent.id,
+      context: this.context,
+    });
+
+    let usage: LanguageModelUsage | undefined;
+    let finishReason: LanguageModelFinishReason = "unknown";
+
     try {
       if (this.model.stream) {
-        const stream = this.model.stream(req);
-        for await (const event of stream) {
-          yield event; // [text-delta, tool-call, message, reasoning, ...]
+        for await (const event of this.model.stream(req)) {
+          if (event.kind === "finish") {
+            usage = event.usage;
+            finishReason = event.finishReason;
+          }
+          yield event;
         }
       } else {
         // fallback: blocking generate, yield events as batch
         const res = await this.model.generate(req);
+        usage = res.usage;
+        finishReason = res.finishReason;
         for (const event of res.content) {
           yield event;
         }
-        // (TODO): this.stats.usage.add(res.usage)
       }
+
+      this.agent.emit("model.call.end", {
+        kind: "model.call.end",
+        provider: this.model.provider,
+        modelId: this.model.modelId,
+        finishReason,
+        usage,
+        threadId: this.tid,
+        agentId: this.agent.id,
+        context: this.context,
+      });
     } catch (error) {
+      this.agent.emit("model.call.end", {
+        kind: "model.call.end",
+        provider: this.model.provider,
+        modelId: this.model.modelId,
+        finishReason: "error",
+        threadId: this.tid,
+        agentId: this.agent.id,
+        context: this.context,
+      });
+
       yield {
         kind: "error",
         error: error instanceof Error ? error : new Error(String(error)),
@@ -369,6 +409,8 @@ export class Thread<
 
   /**
    * Cancel the running thread
+   *
+   * TODO: Emit thread.stop with outcome: 'cancelled' when cancelled
    */
   cancel() {
     this.abort?.abort();
@@ -430,6 +472,18 @@ export class Thread<
   private async executeTools(calls: ToolCall[]): Promise<ThreadEventInner[]> {
     return await Promise.all(
       calls.map(async (call: ToolCall) => {
+        const parsedArgs = JSON.parse(call.arguments || "{}");
+
+        this.agent.emit("tool.call.start", {
+          kind: "tool.call.start",
+          threadId: this.tid,
+          agentId: this.agent.id,
+          context: this.context,
+          toolId: call.toolId,
+          callId: call.callId,
+          args: parsedArgs,
+        });
+
         try {
           const tool = this.agent.tool(call.toolId);
           if (!tool) {
@@ -449,6 +503,21 @@ export class Thread<
           ctx.approve(call.callId); // mark this call as approved
           const res = await tool.invoke(ctx, call.arguments, call.callId);
 
+          this.agent.emit("tool.call.end", {
+            kind: "tool.call.end",
+            threadId: this.tid,
+            agentId: this.agent.id,
+            context: this.context,
+            toolId: call.toolId,
+            callId: call.callId,
+            state: res.state,
+            result:
+              typeof res.result === "string"
+                ? res.result
+                : JSON.stringify(res.result),
+            error: res.error,
+          });
+
           return {
             kind: "tool-result" as const,
             callId: call.callId,
@@ -458,6 +527,17 @@ export class Thread<
             error: res.error,
           };
         } catch (error) {
+          this.agent.emit("tool.call.end", {
+            kind: "tool.call.end",
+            threadId: this.tid,
+            agentId: this.agent.id,
+            context: this.context,
+            toolId: call.toolId,
+            callId: call.callId,
+            state: FAILED,
+            error: error instanceof Error ? error.message : String(error),
+          });
+
           return {
             kind: "tool-result" as const,
             callId: call.callId,

package/src/thread/types.ts

@@ -179,7 +179,7 @@ export interface ThreadOptions<
  * Options passed to agent.execute() and agent.stream().
  */
 export interface ThreadExecuteOptions<TContext> {
-  context?: Context<TContext>;
+  context?: TContext;
   model?: LanguageModel;
   task?: Task<TContext>;
   threadId?: string;