kernl 0.12.0 → 0.12.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
 
     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"}

package/dist/thread/__tests__/integration.test.js

@@ -1,320 +0,0 @@
-import { describe, it, expect, beforeAll } from "vitest";
-import { z } from "zod";
-import { openai } from "@ai-sdk/openai";
-import { AISDKLanguageModel } from "@kernl-sdk/ai";
-import "@kernl-sdk/ai/openai"; // (TMP)
-import { Agent } from "../../agent.js";
-import { Kernl } from "../../kernl/index.js";
-import { tool, Toolkit } from "../../tool/index.js";
-import { Thread } from "../thread.js";
-/**
- * Integration tests for Thread streaming with real AI SDK providers.
- *
- * These tests require an OPENAI_API_KEY environment variable to be set.
- * They will be skipped if the API key is not available.
- *
- * Run with: OPENAI_API_KEY=your-key pnpm test:run
- */
-const SKIP_INTEGRATION_TESTS = !process.env.OPENAI_API_KEY;
-describe.skipIf(SKIP_INTEGRATION_TESTS)("Thread streaming integration", () => {
-    let kernl;
-    let model;
-    beforeAll(() => {
-        kernl = new Kernl();
-        model = new AISDKLanguageModel(openai("gpt-4.1"));
-    });
-    describe("stream()", () => {
-        it("should yield both delta events and complete items", async () => {
-            const agent = new Agent({
-                id: "test-stream",
-                name: "Test Stream Agent",
-                instructions: "You are a helpful assistant.",
-                model,
-            });
-            const input = [
-                {
-                    kind: "message",
-                    id: "msg-1",
-                    role: "user",
-                    content: [
-                        { kind: "text", text: "Say 'Hello World' and nothing else." },
-                    ],
-                },
-            ];
-            const thread = new Thread({ agent, input });
-            const events = [];
-            for await (const event of thread.stream()) {
-                events.push(event);
-            }
-            expect(events.length).toBeGreaterThan(0);
-            // Should have text-delta events (for streaming UX)
-            const textDeltas = events.filter((e) => e.kind === "text.delta");
-            expect(textDeltas.length).toBeGreaterThan(0);
-            // Should have text-start event
-            const textStarts = events.filter((e) => e.kind === "text.start");
-            expect(textStarts.length).toBeGreaterThan(0);
-            // Should have text-end event
-            const textEnds = events.filter((e) => e.kind === "text.end");
-            expect(textEnds.length).toBeGreaterThan(0);
-            // Should have complete Message item (for history)
-            const messages = events.filter((e) => e.kind === "message");
-            expect(messages.length).toBeGreaterThan(0);
-            const assistantMessage = messages.find((m) => m.role === "assistant");
-            expect(assistantMessage).toBeDefined();
-            expect(assistantMessage.content).toBeDefined();
-            expect(assistantMessage.content.length).toBeGreaterThan(0);
-            // Message should have accumulated text from all deltas
-            const textContent = assistantMessage.content.find((c) => c.kind === "text");
-            expect(textContent).toBeDefined();
-            expect(textContent.text).toBeDefined();
-            expect(textContent.text.length).toBeGreaterThan(0);
-            // Verify accumulated text matches concatenated deltas
-            const accumulatedFromDeltas = textDeltas.map((d) => d.text).join("");
-            expect(textContent.text).toBe(accumulatedFromDeltas);
-            // Should have finish event
-            const finishEvents = events.filter((e) => e.kind === "finish");
-            expect(finishEvents.length).toBe(1);
-        }, 30000);
-        it("should filter deltas from history but include complete items", async () => {
-            const agent = new Agent({
-                id: "test-history",
-                name: "Test History Agent",
-                instructions: "You are a helpful assistant.",
-                model,
-            });
-            const input = [
-                {
-                    kind: "message",
-                    id: "msg-1",
-                    role: "user",
-                    content: [{ kind: "text", text: "Count to 3" }],
-                },
-            ];
-            const thread = new Thread({ agent, input });
-            const streamEvents = [];
-            for await (const event of thread.stream()) {
-                streamEvents.push(event);
-            }
-            // Access private history via type assertion for testing
-            const history = thread.history;
-            // History should only contain complete items (message, reasoning, tool-call, tool-result)
-            // TypeScript already enforces this via ThreadEvent type, but let's verify at runtime
-            for (const event of history) {
-                expect(["message", "reasoning", "tool-call", "tool-result"]).toContain(event.kind);
-            }
-            // Stream events should include deltas (but history should not)
-            const streamDeltas = streamEvents.filter((e) => e.kind === "text.delta" ||
-                e.kind === "text.start" ||
-                e.kind === "text.end");
-            expect(streamDeltas.length).toBeGreaterThan(0);
-            // History should contain the input message (with ThreadEvent headers added)
-            expect(history[0]).toMatchObject({
-                kind: "message",
-                role: "user",
-                content: [{ kind: "text", text: "Count to 3" }],
-            });
-            // History should contain complete Message items
-            const historyMessages = history.filter((e) => e.kind === "message");
-            expect(historyMessages.length).toBeGreaterThan(1); // input + assistant response
-            // Verify assistant message has complete text (not deltas)
-            const assistantMessage = historyMessages.find((m) => m.role === "assistant");
-            expect(assistantMessage).toBeDefined();
-            const textContent = assistantMessage.content.find((c) => c.kind === "text");
-            expect(textContent.text).toBeTruthy();
-            expect(textContent.text.length).toBeGreaterThan(0);
-        }, 30000);
-        it("should work with tool calls", async () => {
-            const addTool = tool({
-                id: "add",
-                name: "add",
-                description: "Add two numbers together",
-                parameters: z.object({
-                    a: z.number().describe("The first number"),
-                    b: z.number().describe("The second number"),
-                }),
-                execute: async (ctx, { a, b }) => {
-                    return a + b;
-                },
-            });
-            const toolkit = new Toolkit({
-                id: "math",
-                tools: [addTool],
-            });
-            const agent = new Agent({
-                id: "test-tools",
-                name: "Test Tools Agent",
-                instructions: "You are a helpful assistant that can do math.",
-                model,
-                toolkits: [toolkit],
-            });
-            const input = [
-                {
-                    kind: "message",
-                    id: "msg-1",
-                    role: "user",
-                    content: [{ kind: "text", text: "What is 25 + 17?" }],
-                },
-            ];
-            const thread = new Thread({ agent, input });
-            const events = [];
-            for await (const event of thread.stream()) {
-                events.push(event);
-            }
-            expect(events.length).toBeGreaterThan(0);
-            // Should have tool calls
-            const toolCalls = events.filter((e) => e.kind === "tool.call");
-            expect(toolCalls.length).toBeGreaterThan(0);
-            // Verify tool was called with correct parameters
-            const addToolCall = toolCalls.find((tc) => tc.toolId === "add");
-            expect(addToolCall).toBeDefined();
-            expect(JSON.parse(addToolCall.arguments)).toEqual({ a: 25, b: 17 });
-            // Should have tool results
-            const toolResults = events.filter((e) => e.kind === "tool.result");
-            expect(toolResults.length).toBeGreaterThan(0);
-            // Verify tool result is correct
-            const addToolResult = toolResults.find((tr) => tr.callId === addToolCall.callId);
-            expect(addToolResult).toBeDefined();
-            expect(addToolResult.result).toBe(42);
-            // History should contain tool calls and results
-            const history = thread.history;
-            const historyToolCalls = history.filter((e) => e.kind === "tool.call");
-            const historyToolResults = history.filter((e) => e.kind === "tool.result");
-            expect(historyToolCalls.length).toBe(toolCalls.length);
-            expect(historyToolResults.length).toBe(toolResults.length);
-            // Verify the assistant's final response references the correct answer
-            const messages = events.filter((e) => e.kind === "message");
-            const assistantMessage = messages.find((m) => m.role === "assistant");
-            expect(assistantMessage).toBeDefined();
-            const textContent = assistantMessage.content.find((c) => c.kind === "text");
-            expect(textContent).toBeDefined();
-            expect(textContent.text).toContain("42");
-        }, 30000);
-        it("should properly encode tool results with matching callIds for multi-turn", async () => {
-            const multiplyTool = tool({
-                id: "multiply",
-                name: "multiply",
-                description: "Multiply two numbers",
-                parameters: z.object({
-                    a: z.number().describe("First number"),
-                    b: z.number().describe("Second number"),
-                }),
-                execute: async (ctx, { a, b }) => {
-                    return a * b;
-                },
-            });
-            const toolkit = new Toolkit({
-                id: "math",
-                tools: [multiplyTool],
-            });
-            const agent = new Agent({
-                id: "test-multi-turn",
-                name: "Test Multi-Turn Agent",
-                instructions: "You are a helpful assistant that can do math.",
-                model,
-                toolkits: [toolkit],
-            });
-            const input = [
-                {
-                    kind: "message",
-                    id: "msg-1",
-                    role: "user",
-                    content: [{ kind: "text", text: "What is 7 times 6?" }],
-                },
-            ];
-            const thread = new Thread({ agent, input });
-            const events = [];
-            // Collect all events from the stream
-            for await (const event of thread.stream()) {
-                events.push(event);
-            }
-            // Find the tool call and result
-            const toolCalls = events.filter((e) => e.kind === "tool.call");
-            const toolResults = events.filter((e) => e.kind === "tool.result");
-            expect(toolCalls.length).toBeGreaterThan(0);
-            expect(toolResults.length).toBeGreaterThan(0);
-            const multiplyCall = toolCalls[0];
-            const multiplyResult = toolResults[0];
-            // Verify callId matches between tool call and result
-            expect(multiplyCall.callId).toBe(multiplyResult.callId);
-            expect(multiplyCall.toolId).toBe("multiply");
-            expect(multiplyResult.toolId).toBe("multiply");
-            // Verify the tool result has the correct structure
-            expect(multiplyResult.callId).toBeDefined();
-            expect(typeof multiplyResult.callId).toBe("string");
-            expect(multiplyResult.callId.length).toBeGreaterThan(0);
-            // Verify history contains both with matching callIds
-            const history = thread.history;
-            const historyToolCall = history.find((e) => e.kind === "tool.call" && e.toolId === "multiply");
-            const historyToolResult = history.find((e) => e.kind === "tool.result" && e.toolId === "multiply");
-            expect(historyToolCall).toBeDefined();
-            expect(historyToolResult).toBeDefined();
-            expect(historyToolCall.callId).toBe(historyToolResult.callId);
-            // Verify final response uses the tool result
-            const messages = events.filter((e) => e.kind === "message");
-            const assistantMessage = messages.find((m) => m.role === "assistant");
-            expect(assistantMessage).toBeDefined();
-            const textContent = assistantMessage.content.find((c) => c.kind === "text");
-            expect(textContent).toBeDefined();
-            expect(textContent.text).toContain("42");
-        }, 30000);
-    });
-    describe("execute()", () => {
-        it("should consume stream and return final response", async () => {
-            const agent = new Agent({
-                id: "test-blocking",
-                name: "Test Blocking Agent",
-                instructions: "You are a helpful assistant.",
-                model,
-            });
-            const input = [
-                {
-                    kind: "message",
-                    id: "msg-1",
-                    role: "user",
-                    content: [{ kind: "text", text: "Say 'Testing' and nothing else." }],
-                },
-            ];
-            const thread = new Thread({ agent, input });
-            const result = await thread.execute();
-            // Should have a response
-            expect(result.response).toBeDefined();
-            expect(typeof result.response).toBe("string");
-            expect(result.response.length).toBeGreaterThan(0);
-            // Should have final state
-            expect(result.state).toBe("stopped");
-        }, 30000);
-        it("should validate structured output in blocking mode", async () => {
-            const PersonSchema = z.object({
-                name: z.string(),
-                age: z.number(),
-            });
-            const agent = new Agent({
-                id: "test-structured",
-                name: "Test Structured Agent",
-                instructions: "You are a helpful assistant. Return JSON with name and age fields.",
-                model,
-                output: PersonSchema,
-            });
-            const input = [
-                {
-                    kind: "message",
-                    id: "msg-1",
-                    role: "user",
-                    content: [
-                        {
-                            kind: "text",
-                            text: 'Return a JSON object with name "Alice" and age 30',
-                        },
-                    ],
-                },
-            ];
-            const thread = new Thread({ agent, input });
-            const result = await thread.execute();
-            // Response should be validated and parsed
-            expect(result.response).toBeDefined();
-            expect(typeof result.response).toBe("object");
-            expect(result.response.name).toBeTruthy();
-            expect(typeof result.response.age).toBe("number");
-        }, 30000);
-    });
-});