kernl 0.7.4 → 0.8.0

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>;
 }