kernl 0.7.3 → 0.8.0

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

@@ -2,6 +2,7 @@ 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";
 import { Kernl } from "@/kernl";
@@ -23,21 +24,17 @@ import type { LanguageModelItem } from "@kernl-sdk/protocol";
 
 const SKIP_INTEGRATION_TESTS = !process.env.OPENAI_API_KEY;
 
-describe.skipIf(SKIP_INTEGRATION_TESTS)(
-  "Thread streaming integration",
-  () => {
-    let kernl: Kernl;
-    let model: AISDKLanguageModel;
-
-    beforeAll(() => {
-      kernl = new Kernl();
-      model = new AISDKLanguageModel(openai("gpt-4o"));
-    });
-
-    describe("stream()", () => {
-      it(
-        "should yield both delta events and complete items",
-        async () => {
+describe.skipIf(SKIP_INTEGRATION_TESTS)("Thread streaming integration", () => {
+  let kernl: Kernl;
+  let model: AISDKLanguageModel;
+
+  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",
@@ -103,13 +100,9 @@ describe.skipIf(SKIP_INTEGRATION_TESTS)(
       // Should have finish event
       const finishEvents = events.filter((e) => e.kind === "finish");
       expect(finishEvents.length).toBe(1);
-        },
-        30000,
-      );
+    }, 30000);
 
-      it(
-        "should filter deltas from history but include complete items",
-        async () => {
+    it("should filter deltas from history but include complete items", async () => {
       const agent = new Agent({
         id: "test-history",
         name: "Test History Agent",
@@ -153,8 +146,12 @@ describe.skipIf(SKIP_INTEGRATION_TESTS)(
       );
       expect(streamDeltas.length).toBeGreaterThan(0);
 
-      // History should contain the input message
-      expect(history[0]).toEqual(input[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");
@@ -170,11 +167,9 @@ describe.skipIf(SKIP_INTEGRATION_TESTS)(
       );
       expect(textContent.text).toBeTruthy();
       expect(textContent.text.length).toBeGreaterThan(0);
-        },
-        30000,
-      );
+    }, 30000);
 
-      it("should work with tool calls", async () => {
+    it("should work with tool calls", async () => {
       const addTool = tool({
         id: "add",
         name: "add",
@@ -257,122 +252,118 @@ describe.skipIf(SKIP_INTEGRATION_TESTS)(
 
       // Verify the assistant's final response references the correct answer
       const messages = events.filter((e) => e.kind === "message");
-      const assistantMessage = messages.find((m: any) => m.role === "assistant");
+      const assistantMessage = messages.find(
+        (m: any) => m.role === "assistant",
+      );
       expect(assistantMessage).toBeDefined();
       const textContent = (assistantMessage as any).content.find(
         (c: any) => 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;
         },
-        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: LanguageModelItem[] = [
-            {
-              kind: "message",
-              id: "msg-1",
-              role: "user",
-              content: [{ kind: "text", text: "What is 7 times 6?" }],
-            },
-          ];
-
-          const thread = new Thread({ agent, input });
-          const events: ThreadStreamEvent[] = [];
-
-          // 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 is Extract<ThreadStreamEvent, { kind: "tool-call" }> =>
-              e.kind === "tool-call",
-          );
-          const toolResults = events.filter(
-            (e): e is Extract<ThreadStreamEvent, { kind: "tool-result" }> =>
-              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 as any).history as ThreadEvent[];
-          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 as any).callId).toBe(
-            (historyToolResult as any).callId,
-          );
-
-          // Verify final response uses the tool result
-          const messages = events.filter((e) => e.kind === "message");
-          const assistantMessage = messages.find((m: any) => m.role === "assistant");
-          expect(assistantMessage).toBeDefined();
-          const textContent = (assistantMessage as any).content.find(
-            (c: any) => c.kind === "text",
-          );
-          expect(textContent).toBeDefined();
-          expect(textContent.text).toContain("42");
+      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: LanguageModelItem[] = [
+        {
+          kind: "message",
+          id: "msg-1",
+          role: "user",
+          content: [{ kind: "text", text: "What is 7 times 6?" }],
         },
-        30000,
+      ];
+
+      const thread = new Thread({ agent, input });
+      const events: ThreadStreamEvent[] = [];
+
+      // 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 is Extract<ThreadStreamEvent, { kind: "tool-call" }> =>
+          e.kind === "tool-call",
+      );
+      const toolResults = events.filter(
+        (e): e is Extract<ThreadStreamEvent, { kind: "tool-result" }> =>
+          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 as any).history as ThreadEvent[];
+      const historyToolCall = history.find(
+        (e) => e.kind === "tool-call" && e.toolId === "multiply",
+      );
+      const historyToolResult = history.find(
+        (e) => e.kind === "tool-result" && e.toolId === "multiply",
       );
-    });
 
-    describe("execute()", () => {
-      it(
-        "should consume stream and return final response",
-        async () => {
+      expect(historyToolCall).toBeDefined();
+      expect(historyToolResult).toBeDefined();
+      expect((historyToolCall as any).callId).toBe(
+        (historyToolResult as any).callId,
+      );
+
+      // Verify final response uses the tool result
+      const messages = events.filter((e) => e.kind === "message");
+      const assistantMessage = messages.find(
+        (m: any) => m.role === "assistant",
+      );
+      expect(assistantMessage).toBeDefined();
+      const textContent = (assistantMessage as any).content.find(
+        (c: any) => 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",
@@ -399,14 +390,10 @@ describe.skipIf(SKIP_INTEGRATION_TESTS)(
 
       // Should have final state
       expect(result.state).toBe("stopped");
-        },
-        30000,
-      );
+    }, 30000);
 
-      it(
-        "should validate structured output in blocking mode",
-        async () => {
-      const responseSchema = z.object({
+    it("should validate structured output in blocking mode", async () => {
+      const PersonSchema = z.object({
         name: z.string(),
         age: z.number(),
       });
@@ -417,7 +404,7 @@ describe.skipIf(SKIP_INTEGRATION_TESTS)(
         instructions:
           "You are a helpful assistant. Return JSON with name and age fields.",
         model,
-        responseType: responseSchema,
+        output: PersonSchema,
       });
 
       const input: LanguageModelItem[] = [
@@ -442,9 +429,6 @@ describe.skipIf(SKIP_INTEGRATION_TESTS)(
       expect(typeof result.response).toBe("object");
       expect((result.response as any).name).toBeTruthy();
       expect(typeof (result.response as any).age).toBe("number");
-        },
-        30000,
-      );
-    });
-  },
-);
+    }, 30000);
+  });
+});

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

@@ -1061,7 +1061,7 @@ describe("Thread", () => {
   });
 
   describe("Final Output Parsing", () => {
-    it("should return text output when responseType is 'text'", async () => {
+    it("should return text output when output is 'text'", async () => {
       const model = createMockModel(async (req: LanguageModelRequest) => {
         return {
           content: [
@@ -1087,7 +1087,7 @@ describe("Thread", () => {
         name: "Test",
         instructions: "Test agent",
         model,
-        responseType: "text",
+        output: "text",
       });
 
       const kernl = new Kernl();
@@ -1136,7 +1136,7 @@ describe("Thread", () => {
         name: "Test",
         instructions: "Test agent",
         model,
-        responseType: responseSchema,
+        output: responseSchema,
       });
 
       const kernl = new Kernl();
@@ -1186,7 +1186,7 @@ describe("Thread", () => {
         name: "Test",
         instructions: "Test agent",
         model,
-        responseType: responseSchema,
+        output: responseSchema,
       });
 
       const kernl = new Kernl();
@@ -1231,7 +1231,7 @@ describe("Thread", () => {
         name: "Test",
         instructions: "Test agent",
         model,
-        responseType: responseSchema,
+        output: responseSchema,
       });
 
       const kernl = new Kernl();
@@ -1277,7 +1277,7 @@ describe("Thread", () => {
         name: "Test",
         instructions: "Test agent",
         model,
-        responseType: responseSchema,
+        output: responseSchema,
       });
 
       const kernl = new Kernl();
@@ -1336,7 +1336,7 @@ describe("Thread", () => {
         name: "Test",
         instructions: "Test agent",
         model,
-        responseType: responseSchema,
+        output: responseSchema,
       });
 
       const kernl = new Kernl();
@@ -1405,7 +1405,7 @@ describe("Thread", () => {
         name: "Test",
         instructions: "Test agent",
         model,
-        responseType: "text",
+        output: "text",
       });
 
       const kernl = new Kernl();

package/src/thread/thread.ts

@@ -1,4 +1,6 @@
 import assert from "assert";
+import { ZodType } from "zod";
+import * as z from "zod";
 
 import { Agent } from "@/agent";
 import { Context } from "@/context";
@@ -30,7 +32,8 @@ import type {
   ThreadExecuteResult,
   PerformActionsResult,
 } from "./types";
-import type { AgentResponseType } from "@/agent/types";
+import type { AgentOutputType } from "@/agent/types";
+import type { LanguageModelResponseType } from "@kernl-sdk/protocol";
 
 import {
   tevent,
@@ -82,11 +85,11 @@ import {
  */
 export class Thread<
   TContext = unknown,
-  TResponse extends AgentResponseType = "text",
+  TOutput extends AgentOutputType = "text",
 > {
   readonly tid: string;
   readonly namespace: string;
-  readonly agent: Agent<TContext, TResponse>;
+  readonly agent: Agent<TContext, TOutput>;
   readonly context: Context<TContext>;
   readonly model: LanguageModel; /* inherited from the agent unless specified */
   readonly parent: Task<TContext> | null; /* parent task which spawned this thread */
@@ -106,7 +109,7 @@ export class Thread<
   private abort?: AbortController;
   private storage?: ThreadStore;
 
-  constructor(options: ThreadOptions<TContext, TResponse>) {
+  constructor(options: ThreadOptions<TContext, TOutput>) {
     this.tid = options.tid ?? `tid_${randomID()}`;
     this.namespace = options.namespace ?? "kernl";
     this.agent = options.agent;
@@ -142,7 +145,7 @@ export class Thread<
    * Blocking execution - runs until terminal state or interruption
    */
   async execute(): Promise<
-    ThreadExecuteResult<ResolvedAgentResponse<TResponse>>
+    ThreadExecuteResult<ResolvedAgentResponse<TOutput>>
   > {
     for await (const _event of this.stream()) {
       // just consume the stream (already in history in _execute())
@@ -158,7 +161,7 @@ export class Thread<
 
     const text = getFinalResponse(items);
     assert(text, "_execute continues until text !== null"); // (TODO): consider preventing infinite loops here
-    const parsed = parseFinalResponse(text, this.agent.responseType);
+    const parsed = parseFinalResponse(text, this.agent.output);
 
     return { response: parsed, state: this.state };
   }
@@ -405,7 +408,7 @@ export class Thread<
         e.kind === "tool-result" &&
         (e.state as any) === "requires_approval" // (TODO): fix this
       ) {
-        // Find the original tool call for this pending approval
+        // find the original tool call for this pending approval
         const call = intentions.toolCalls.find((c) => c.callId === e.callId);
         call && pendingApprovals.push(call);
       } else {
@@ -508,10 +511,21 @@ export class Thread<
     );
     const tools = enabled.map((tool) => tool.serialize());
 
+    // derive responseType from agent.output
+    let responseType: LanguageModelResponseType | undefined;
+    if (this.agent.output && this.agent.output !== "text") {
+      const schema = this.agent.output as ZodType;
+      responseType = {
+        kind: "json",
+        schema: z.toJSONSchema(schema, { target: "draft-7" }) as any,
+      };
+    }
+
     return {
       input: filtered,
       settings,
       tools,
+      responseType,
     };
   }
 }

package/src/thread/types.ts

@@ -15,7 +15,7 @@ import { Task } from "@/task";
 import { Context } from "@/context";
 import { Agent } from "@/agent";
 
-import type { AgentResponseType } from "@/agent/types";
+import type { AgentOutputType } from "@/agent/types";
 import type { ThreadStore } from "@/storage";
 
 /**
@@ -23,7 +23,10 @@ import type { ThreadStore } from "@/storage";
  */
 export type PublicThreadEvent = LanguageModelItem & ThreadEventBase;
 
-export type TextResponse = "text";
+/**
+ * Text output type - indicates the agent returns a plain string.
+ */
+export type TextOutput = "text";
 
 /**
  * Thread state values as a const array (for zod schemas).
@@ -61,10 +64,10 @@ export const REQUIRES_APPROVAL = "requires_approval";
  */
 export interface IThread<
   TContext = unknown,
-  TResponse extends AgentResponseType = "text",
+  TOutput extends AgentOutputType = "text",
 > {
   tid: string;
-  agent: Agent<TContext, TResponse>;
+  agent: Agent<TContext, TOutput>;
   model: LanguageModel;
 
   context: Context<TContext>;
@@ -148,9 +151,9 @@ export interface ThreadExecuteResult<TResponse = unknown> {
  */
 export interface ThreadOptions<
   TContext = unknown,
-  TResponse extends AgentResponseType = "text",
+  TOutput extends AgentOutputType = "text",
 > {
-  agent: Agent<TContext, TResponse>;
+  agent: Agent<TContext, TOutput>;
   input?: LanguageModelItem[];
   history?: ThreadEvent[];
   context?: Context<TContext>;

package/src/thread/utils.ts

@@ -8,7 +8,7 @@ import { ToolCall, LanguageModelItem } from "@kernl-sdk/protocol";
 import { ModelBehaviorError } from "@/lib/error";
 
 /* types */
-import type { AgentResponseType } from "@/agent/types";
+import type { AgentOutputType } from "@/agent/types";
 import type {
   ThreadEvent,
   ThreadEventBase,
@@ -129,30 +129,31 @@ export function getFinalResponse(items: LanguageModelItem[]): string | null {
 }
 
 /**
- * (TODO): This should run through the language model's native structured output (if avail)
+ * Parse the final response according to the output type schema.
  *
- * Parse the final response according to the response type schema.
- * - If responseType is "text", returns the text as-is
- * - If responseType is a ZodType, parses and validates the text as JSON
+ * This serves as a safety net validation after native structured output from the provider.
+ *
+ * - If output is "text", returns the text as-is
+ * - If output is a ZodType, parses and validates the text as JSON
  *
  * @throws {ModelBehaviorError} if structured output validation fails
  */
-export function parseFinalResponse<TResponse extends AgentResponseType>(
+export function parseFinalResponse<TOutput extends AgentOutputType>(
   text: string,
-  responseType: TResponse,
-): ResolvedAgentResponse<TResponse> {
-  if (responseType === "text") {
-    return text as ResolvedAgentResponse<TResponse>; // text output - return as-is
+  output: TOutput,
+): ResolvedAgentResponse<TOutput> {
+  if (output === "text") {
+    return text as ResolvedAgentResponse<TOutput>; // text output - return as-is
   }
 
   // structured output - decode JSON and validate with schema
-  if (responseType && typeof responseType === "object") {
+  if (output && typeof output === "object") {
     // (TODO): prob better way of checking this here
-    const schema = responseType as ZodType;
+    const schema = output as ZodType;
 
     try {
       const validated = json(schema).decode(text); // (TODO): it would be nice if we could use `decodeSafe` here
-      return validated as ResolvedAgentResponse<TResponse>;
+      return validated as ResolvedAgentResponse<TOutput>;
     } catch (error) {
       throw new ModelBehaviorError(
         `Failed to parse structured output: ${error instanceof Error ? error.message : String(error)}`,
@@ -161,5 +162,5 @@ export function parseFinalResponse<TResponse extends AgentResponseType>(
   }
 
   // Fallback - should not reach here
-  return text as ResolvedAgentResponse<TResponse>;
+  return text as ResolvedAgentResponse<TOutput>;
 }