kernl 0.12.0 → 0.12.2

package/src/storage/in-memory.ts

@@ -25,7 +25,7 @@ import type {
   SortOrder,
 } from "@/storage";
 import type { ThreadEvent, ThreadState } from "@/thread/types";
-import type { AgentRegistry, ModelRegistry } from "@/kernl/types";
+import type { IAgentRegistry, IModelRegistry } from "@/kernl/types";
 import type {
   MemoryStore,
   MemoryRecord,
@@ -47,7 +47,7 @@ export class InMemoryStorage implements KernlStorage {
     this.memories = new InMemoryMemoryStore();
   }
 
-  bind(registries: { agents: AgentRegistry; models: ModelRegistry }): void {
+  bind(registries: { agents: IAgentRegistry; models: IModelRegistry }): void {
     this.threads.bind(registries);
   }
 
@@ -93,10 +93,10 @@ interface ThreadData {
 export class InMemoryThreadStore implements ThreadStore {
   private threads = new Map<string, ThreadData>();
   private events = new Map<string, ThreadEvent[]>(); // tid -> events
-  private registries: { agents: AgentRegistry; models: ModelRegistry } | null =
+  private registries: { agents: IAgentRegistry; models: IModelRegistry } | null =
     null;
 
-  bind(registries: { agents: AgentRegistry; models: ModelRegistry }): void {
+  bind(registries: { agents: IAgentRegistry; models: IModelRegistry }): void {
     this.registries = registries;
   }
 

package/src/thread/__tests__/mock.ts

@@ -4,8 +4,8 @@ import {
   LanguageModelResponse,
   LanguageModelResponseItem,
   LanguageModelItem,
+  LanguageModelStreamEvent,
 } from "@kernl-sdk/protocol";
-import type { ThreadStreamEvent } from "@/thread/types";
 
 /**
  * A mock language model that echoes the user input back as an assistant message.
@@ -54,7 +54,7 @@ export class MockLanguageModel implements LanguageModel {
 
   async *stream(
     request: LanguageModelRequest,
-  ): AsyncIterable<ThreadStreamEvent> {
+  ): AsyncIterable<LanguageModelStreamEvent> {
     // TODO: Implement streaming (not needed for hello world)
     throw new Error("MockLanguageModel.stream() not implemented yet");
   }

package/src/thread/thread.ts

@@ -19,6 +19,7 @@ import {
   LanguageModel,
   LanguageModelItem,
   LanguageModelRequest,
+  LanguageModelStreamEvent,
   type LanguageModelUsage,
   type LanguageModelFinishReason,
 } from "@kernl-sdk/protocol";
@@ -33,6 +34,7 @@ import type {
   ThreadStreamEvent,
   ThreadExecuteResult,
   PerformActionsResult,
+  PublicThreadEvent,
 } from "./types";
 import type { AgentOutputType } from "@/agent/types";
 import type { LanguageModelResponseType } from "@kernl-sdk/protocol";
@@ -176,35 +178,15 @@ export class Thread<
 
     await this.checkpoint(); /* c1: persist RUNNING state + initial input */
 
-    this.agent.emit("thread.start", {
-      kind: "thread.start",
-      threadId: this.tid,
-      agentId: this.agent.id,
-      namespace: this.namespace,
-      context: this.context,
-    });
+    this.emit("thread.start");
 
     yield { kind: "stream.start" }; // always yield start immediately
 
     try {
       yield* this._execute();
-
-      this.agent.emit("thread.stop", {
-        kind: "thread.stop",
-        threadId: this.tid,
-        agentId: this.agent.id,
-        namespace: this.namespace,
-        context: this.context,
-        state: STOPPED,
-        result: this.tickres,
-      });
+      this.emit("thread.stop", { state: STOPPED, result: this.tickres });
     } catch (err) {
-      this.agent.emit("thread.stop", {
-        kind: "thread.stop",
-        threadId: this.tid,
-        agentId: this.agent.id,
-        namespace: this.namespace,
-        context: this.context,
+      this.emit("thread.stop", {
         state: STOPPED,
         error: err instanceof Error ? err.message : String(err),
       });
@@ -236,12 +218,14 @@ export class Thread<
           err = e.error;
           logger.error(e.error); // (TODO): onError callback in options
         }
-        // we don't want deltas in the history
+        // complete items get persisted with seq, deltas are ephemeral
         if (notDelta(e)) {
-          events.push(e);
-          this.append(e);
+          const [seqd] = this.append(e);
+          events.push(seqd);
+          yield seqd;
+        } else {
+          yield e;
         }
-        yield e;
       }
 
       // if an error event occurred → throw it
@@ -267,10 +251,10 @@ export class Thread<
       const { actions, pendingApprovals } =
         await this.performActions(intentions);
 
-      // append + yield action events
+      // append + yield action events (sequenced)
       for (const a of actions) {
-        this.append(a);
-        yield a;
+        const [seqd] = this.append(a);
+        yield seqd;
       }
 
       await this.checkpoint(); /* c3: tick complete */
@@ -293,23 +277,16 @@ export class Thread<
    * NOTE: Streaming structured outputs deferred until concrete use cases emerge.
    * For now, we stream text-delta and tool events, final validation happens in _execute().
    */
-  private async *tick(): AsyncGenerator<ThreadStreamEvent> {
+  private async *tick(): AsyncGenerator<LanguageModelStreamEvent> {
     this._tick++;
 
     // (TODO): check limits (if this._tick > this.limits.maxTicks)
     // (TODO): run input guardrails on first tick (if this._tick === 1)
+    // (TODO): compaction if necessary
 
     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,
-    });
+    this.emit("model.call.start", { settings: req.settings ?? {} });
 
     let usage: LanguageModelUsage | undefined;
     let finishReason: LanguageModelFinishReason = "unknown";
@@ -333,27 +310,9 @@ export class Thread<
         }
       }
 
-      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,
-      });
+      this.emit("model.call.end", { finishReason, usage });
     } 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,
-      });
-
+      this.emit("model.call.end", { finishReason: "error" });
       yield {
         kind: "error",
         error: error instanceof Error ? error : new Error(String(error)),
@@ -439,9 +398,31 @@ export class Thread<
     this.abort?.abort();
   }
 
-  // ----------------------------
-  // utils
-  // ----------------------------
+  /**
+   * Emit an agent event with common fields auto-filled.
+   */
+  private emit(kind: string, payload?: Record<string, unknown>): void {
+    const base = {
+      kind,
+      threadId: this.tid,
+      agentId: this.agent.id,
+      context: this.context,
+    };
+
+    let auto = {};
+    switch (kind) {
+      case "thread.start":
+      case "thread.stop":
+        auto = { namespace: this.namespace };
+        break;
+      case "model.call.start":
+      case "model.call.end":
+        auto = { provider: this.model.provider, modelId: this.model.modelId };
+        break;
+    }
+
+    this.agent.emit(kind as any, { ...base, ...auto, ...payload } as any);
+  }
 
   /**
    * Perform the actions returned by the model
@@ -497,11 +478,7 @@ export class Thread<
       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,
+        this.emit("tool.call.start", {
           toolId: call.toolId,
           callId: call.callId,
           args: parsedArgs,
@@ -526,11 +503,7 @@ 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,
+          this.emit("tool.call.end", {
             toolId: call.toolId,
             callId: call.callId,
             state: res.state,
@@ -550,11 +523,7 @@ 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,
+          this.emit("tool.call.end", {
             toolId: call.toolId,
             callId: call.callId,
             state: FAILED,

package/src/thread/types.ts

@@ -2,13 +2,27 @@ import {
   ToolCall,
   LanguageModel,
   LanguageModelItem,
-  LanguageModelStreamEvent,
   RUNNING,
   STOPPED,
   INTERRUPTIBLE,
   UNINTERRUPTIBLE,
   ZOMBIE,
   DEAD,
+  // Stream event types
+  TextStartEvent,
+  TextEndEvent,
+  TextDeltaEvent,
+  ReasoningStartEvent,
+  ReasoningEndEvent,
+  ReasoningDeltaEvent,
+  ToolInputStartEvent,
+  ToolInputEndEvent,
+  ToolInputDeltaEvent,
+  StartEvent,
+  FinishEvent,
+  AbortEvent,
+  ErrorEvent,
+  RawEvent,
 } from "@kernl-sdk/protocol";
 
 import { Task } from "@/task";
@@ -128,9 +142,41 @@ export type ThreadEvent =
   | ThreadSystemEvent;
 
 /**
- * Stream events - use protocol definition directly.
+ * Incremental content chunks (ephemeral, not persisted).
  */
-export type ThreadStreamEvent = LanguageModelStreamEvent;
+export type StreamDeltaEvent =
+  | TextDeltaEvent
+  | ReasoningDeltaEvent
+  | ToolInputDeltaEvent;
+
+/**
+ * Boundary markers + control flow (ephemeral, not persisted).
+ */
+export type StreamControlEvent =
+  | TextStartEvent
+  | TextEndEvent
+  | ReasoningStartEvent
+  | ReasoningEndEvent
+  | ToolInputStartEvent
+  | ToolInputEndEvent
+  | StartEvent
+  | FinishEvent
+  | AbortEvent
+  | ErrorEvent
+  | RawEvent;
+
+/**
+ * All ephemeral stream types (not persisted to history).
+ */
+export type StreamEvent = StreamDeltaEvent | StreamControlEvent;
+
+/**
+ * Thread stream events = sequenced ThreadEvents + ephemeral StreamEvents.
+ *
+ * Complete items (Message, ToolCall, etc.) are yielded as ThreadEvents with seq.
+ * Deltas and control events are yielded as StreamEvents without seq.
+ */
+export type ThreadStreamEvent = ThreadEvent | StreamEvent;
 
 /**
  * Result of thread execution

package/src/thread/utils.ts

@@ -4,7 +4,11 @@ import type { ResolvedAgentResponse } from "@/guardrail";
 
 /* lib */
 import { json, randomID } from "@kernl-sdk/shared/lib";
-import { ToolCall, LanguageModelItem } from "@kernl-sdk/protocol";
+import {
+  ToolCall,
+  LanguageModelItem,
+  LanguageModelStreamEvent,
+} from "@kernl-sdk/protocol";
 import { ModelBehaviorError } from "@/lib/error";
 
 /* types */
@@ -12,7 +16,6 @@ import type { AgentOutputType } from "@/agent/types";
 import type {
   ThreadEvent,
   ThreadEventBase,
-  ThreadStreamEvent,
   ActionSet,
   PublicThreadEvent,
 } from "./types";
@@ -21,7 +24,7 @@ import type {
  * Create a ThreadEvent from a LanguageModelItem with thread metadata.
  *
  * @example
- * ```typescript
+ * ```ts
  * tevent({
  *   kind: "message",
  *   seq: 0,
@@ -57,7 +60,9 @@ export function tevent(event: {
 /**
  * Check if an event is a tool call
  */
-export function isActionIntention(event: LanguageModelItem): event is ToolCall {
+export function isActionIntention(
+  event: ThreadEvent,
+): event is ToolCall & ThreadEventBase {
   return event.kind === "tool.call";
 }
 
@@ -65,7 +70,7 @@ export function isActionIntention(event: LanguageModelItem): event is ToolCall {
  * Extract action intentions from a list of events.
  * Returns ActionSet if there are any tool calls, null otherwise.
  */
-export function getIntentions(events: LanguageModelItem[]): ActionSet | null {
+export function getIntentions(events: ThreadEvent[]): ActionSet | null {
   const toolCalls = events.filter(isActionIntention);
   return toolCalls.length > 0 ? { toolCalls } : null;
 }
@@ -74,7 +79,9 @@ export function getIntentions(events: LanguageModelItem[]): ActionSet | null {
  * Check if an event is NOT a delta/start/end event (i.e., a complete item).
  * Returns true for complete items: Message, Reasoning, ToolCall, ToolResult
  */
-export function notDelta(event: ThreadStreamEvent): event is LanguageModelItem {
+export function notDelta(
+  event: LanguageModelStreamEvent,
+): event is LanguageModelItem {
   switch (event.kind) {
     case "message":
     case "reasoning":
@@ -112,7 +119,7 @@ export function isPublicEvent(event: ThreadEvent): event is PublicThreadEvent {
  * Extract the final text response from a list of items.
  * Returns null if no assistant message with text content is found.
  */
-export function getFinalResponse(items: LanguageModelItem[]): string | null {
+export function getFinalResponse(items: ThreadEvent[]): string | null {
   // scan backwards for the last assistant message
   for (let i = items.length - 1; i >= 0; i--) {
     const item = items[i];

package/dist/thread/__tests__/integration.test.d.ts

@@ -1,2 +0,0 @@
-import "@kernl-sdk/ai/openai";
-//# sourceMappingURL=integration.test.d.ts.map

package/dist/thread/__tests__/integration.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"integration.test.d.ts","sourceRoot":"","sources":["../../../src/thread/__tests__/integration.test.ts"],"names":[],"mappings":"AAIA,OAAO,sBAAsB,CAAC"}