kernl 0.11.4 → 0.12.1

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

@@ -194,7 +194,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "echo",
                 state: IN_PROGRESS,
                 callId: "call_1",
@@ -270,7 +270,7 @@ describe("Thread", () => {
         }),
         // Tool call (tick 1)
         expect.objectContaining({
-          kind: "tool-call",
+          kind: "tool.call",
           toolId: "echo",
           callId: "call_1",
           state: IN_PROGRESS,
@@ -278,7 +278,7 @@ describe("Thread", () => {
         }),
         // Tool result (executed after tick 1)
         expect.objectContaining({
-          kind: "tool-result",
+          kind: "tool.result",
           callId: "call_1",
           toolId: "echo",
           state: COMPLETED,
@@ -312,7 +312,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "simple",
                 state: IN_PROGRESS,
                 callId: "call_1",
@@ -339,7 +339,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "simple",
                 state: IN_PROGRESS,
                 callId: "call_2",
@@ -423,7 +423,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "nonexistent",
                 state: IN_PROGRESS,
                 callId: "call_1",
@@ -476,9 +476,9 @@ describe("Thread", () => {
       const history = (thread as any).history as ThreadEvent[];
 
       // Check that the tool result is an error
-      const toolResult = history.find((e) => e.kind === "tool-result");
+      const toolResult = history.find((e) => e.kind === "tool.result");
       expect(toolResult).toEqual(expect.objectContaining({
-        kind: "tool-result",
+        kind: "tool.result",
         callId: "call_1",
         toolId: "nonexistent",
         state: FAILED,
@@ -504,7 +504,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "failing",
                 state: IN_PROGRESS,
                 callId: "call_1",
@@ -567,9 +567,9 @@ describe("Thread", () => {
 
       const history = (thread as any).history as ThreadEvent[];
 
-      const toolResult = history.find((e) => e.kind === "tool-result");
+      const toolResult = history.find((e) => e.kind === "tool.result");
       expect(toolResult).toMatchObject({
-        kind: "tool-result",
+        kind: "tool.result",
         callId: "call_1",
         toolId: "failing",
         state: FAILED,
@@ -595,7 +595,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "add",
                 state: IN_PROGRESS,
                 callId: "call_1",
@@ -655,9 +655,9 @@ describe("Thread", () => {
       // @ts-expect-error
       const history = thread.history as ThreadEvent[];
 
-      const toolResult = history.find((e) => e.kind === "tool-result");
+      const toolResult = history.find((e) => e.kind === "tool.result");
       expect(toolResult).toEqual(expect.objectContaining({
-        kind: "tool-result",
+        kind: "tool.result",
         callId: "call_1",
         toolId: "add",
         state: COMPLETED,
@@ -685,14 +685,14 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "tool1",
                 state: IN_PROGRESS,
                 callId: "call_1",
                 arguments: JSON.stringify({ value: "a" }),
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "tool2",
                 state: IN_PROGRESS,
                 callId: "call_2",
@@ -761,12 +761,12 @@ describe("Thread", () => {
       const history = (thread as any).history as ThreadEvent[];
 
       // Should have both tool results in history
-      const toolResults = history.filter((e) => e.kind === "tool-result");
+      const toolResults = history.filter((e) => e.kind === "tool.result");
       expect(toolResults).toHaveLength(2);
       expect(toolResults).toEqual(
         expect.arrayContaining([
           expect.objectContaining({
-            kind: "tool-result",
+            kind: "tool.result",
             callId: "call_1",
             toolId: "tool1",
             state: COMPLETED,
@@ -774,7 +774,7 @@ describe("Thread", () => {
             error: null,
           }),
           expect.objectContaining({
-            kind: "tool-result",
+            kind: "tool.result",
             callId: "call_2",
             toolId: "tool2",
             state: COMPLETED,
@@ -803,7 +803,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "simple",
                 state: IN_PROGRESS,
                 callId: `call_${callCount}`,
@@ -880,7 +880,7 @@ describe("Thread", () => {
                 content: [],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "simple",
                 state: IN_PROGRESS,
                 callId: "call_1",
@@ -997,7 +997,7 @@ describe("Thread", () => {
                 content: [{ kind: "text" as const, text: "Let me use a tool" }],
               },
               {
-                kind: "tool-call" as const,
+                kind: "tool.call" as const,
                 toolId: "simple",
                 state: IN_PROGRESS,
                 callId: "call_1",

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
+    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
@@ -470,7 +451,7 @@ export class Thread<
     // (TODO): clean this - approval tracking should be handled differently
     for (const e of toolEvents) {
       if (
-        e.kind === "tool-result" &&
+        e.kind === "tool.result" &&
         (e.state as any) === "requires_approval" // (TODO): fix this
       ) {
         // find the original tool call for this pending approval
@@ -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,
@@ -542,7 +515,7 @@ export class Thread<
           });
 
           return {
-            kind: "tool-result" as const,
+            kind: "tool.result" as const,
             callId: call.callId,
             toolId: call.toolId,
             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,
@@ -562,7 +531,7 @@ export class Thread<
           });
 
           return {
-            kind: "tool-result" as const,
+            kind: "tool.result" as const,
             callId: call.callId,
             toolId: call.toolId,
             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,15 +60,17 @@ export function tevent(event: {
 /**
  * Check if an event is a tool call
  */
-export function isActionIntention(event: LanguageModelItem): event is ToolCall {
-  return event.kind === "tool-call";
+export function isActionIntention(
+  event: ThreadEvent,
+): event is ToolCall & ThreadEventBase {
+  return event.kind === "tool.call";
 }
 
 /**
  * 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,12 +79,14 @@ 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":
-    case "tool-call":
-    case "tool-result":
+    case "tool.call":
+    case "tool.result":
       return true;
 
     // all other events are streaming deltas/control events
@@ -96,8 +103,8 @@ export function isPublicEvent(event: ThreadEvent): event is PublicThreadEvent {
   switch (event.kind) {
     case "message":
     case "reasoning":
-    case "tool-call":
-    case "tool-result":
+    case "tool.call":
+    case "tool.result":
       return true;
 
     case "system":
@@ -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"}