kernl 0.7.4 → 0.8.1

package/dist/thread/types.d.ts

@@ -2,13 +2,16 @@ import { ToolCall, LanguageModel, LanguageModelItem, LanguageModelStreamEvent, R
 import { Task } from "../task.js";
 import { Context } from "../context.js";
 import { Agent } from "../agent.js";
-import type { AgentResponseType } from "../agent/types.js";
+import type { AgentOutputType } from "../agent/types.js";
 import type { ThreadStore } from "../storage/index.js";
 /**
  * Public/client-facing thread events (excludes internal system events).
  */
 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).
  */
@@ -27,9 +30,9 @@ export declare const REQUIRES_APPROVAL = "requires_approval";
  *
  * Represents the complete state of a Thread that can be stored and restored.
  */
-export interface IThread<TContext = unknown, TResponse extends AgentResponseType = "text"> {
+export interface IThread<TContext = unknown, TOutput extends AgentOutputType = "text"> {
     tid: string;
-    agent: Agent<TContext, TResponse>;
+    agent: Agent<TContext, TOutput>;
     model: LanguageModel;
     context: Context<TContext>;
     input: LanguageModelItem[];
@@ -95,8 +98,8 @@ export interface ThreadExecuteResult<TResponse = unknown> {
 /**
  * Options for constructing a Thread.
  */
-export interface ThreadOptions<TContext = unknown, TResponse extends AgentResponseType = "text"> {
-    agent: Agent<TContext, TResponse>;
+export interface ThreadOptions<TContext = unknown, TOutput extends AgentOutputType = "text"> {
+    agent: Agent<TContext, TOutput>;
     input?: LanguageModelItem[];
     history?: ThreadEvent[];
     context?: Context<TContext>;

package/dist/thread/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/thread/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/thread/types.ts"],"names":[],"mappings":"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"}

package/dist/thread/utils.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedAgentResponse } from "../guardrail.js";
 import { ToolCall, LanguageModelItem } from "@kernl-sdk/protocol";
-import type { AgentResponseType } from "../agent/types.js";
+import type { AgentOutputType } from "../agent/types.js";
 import type { ThreadEvent, ThreadStreamEvent, ActionSet, PublicThreadEvent } from "./types.js";
 /**
  * Create a ThreadEvent from a LanguageModelItem with thread metadata.
@@ -50,13 +50,14 @@ export declare function isPublicEvent(event: ThreadEvent): event is PublicThread
  */
 export declare 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 declare function parseFinalResponse<TResponse extends AgentResponseType>(text: string, responseType: TResponse): ResolvedAgentResponse<TResponse>;
+export declare function parseFinalResponse<TOutput extends AgentOutputType>(text: string, output: TOutput): ResolvedAgentResponse<TOutput>;
 //# sourceMappingURL=utils.d.ts.map

package/dist/thread/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/thread/utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAIlE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EACV,WAAW,EAEX,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,WAAW,CAad;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,QAAQ,CAE7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,SAAS,GAAG,IAAI,CAG3E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,iBAAiB,CAY7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,iBAAiB,CAc5E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAAG,IAAI,CAc1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,SAAS,iBAAiB,EACpE,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,GACtB,qBAAqB,CAAC,SAAS,CAAC,CAsBlC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/thread/utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAIlE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACV,WAAW,EAEX,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,WAAW,CAad;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,QAAQ,CAE7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,SAAS,GAAG,IAAI,CAG3E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,iBAAiB,CAY7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,iBAAiB,CAc5E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAAG,IAAI,CAc1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,eAAe,EAChE,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,GACd,qBAAqB,CAAC,OAAO,CAAC,CAsBhC"}

package/dist/thread/utils.js

@@ -95,22 +95,23 @@ export function getFinalResponse(items) {
     return 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(text, responseType) {
-    if (responseType === "text") {
+export function parseFinalResponse(text, output) {
+    if (output === "text") {
         return text; // 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;
+        const schema = output;
         try {
             const validated = json(schema).decode(text); // (TODO): it would be nice if we could use `decodeSafe` here
             return validated;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -34,10 +34,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
     "pino": "^9.6.0",
+    "yaml": "^2.8.2",
     "zod": "^4.1.12",
+    "@kernl-sdk/protocol": "0.2.8",
     "@kernl-sdk/retrieval": "0.1.3",
-    "@kernl-sdk/shared": "^0.3.0",
-    "@kernl-sdk/protocol": "0.2.8"
+    "@kernl-sdk/shared": "^0.3.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "3.0.0-beta.57",
@@ -45,7 +46,7 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/ai": "0.2.10"
+    "@kernl-sdk/ai": "0.3.0"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/agent/types.ts

@@ -1,30 +1,26 @@
 import { type ZodType } from "zod";
 
-import { Context, UnknownContext } from "@/context";
 import {
   LanguageModel,
   LanguageModelRequestSettings,
 } from "@kernl-sdk/protocol";
+
+import { Context, UnknownContext } from "@/context";
 import { InputGuardrail, OutputGuardrail } from "@/guardrail";
 import { BaseToolkit } from "@/tool";
 
-import { TextResponse } from "@/thread/types";
+import { TextOutput } from "@/thread/types";
 
 /**
  * Configuration for an agent.
  */
 export interface AgentConfig<
   TContext = UnknownContext,
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
-  /* The unique identifier for the agent */
-  id: string;
-
-  /* The name of the agent (defaults to ID if not provided) */
-  name: string;
-
-  /* A brief description of the agent's purpose */
-  description?: string;
+  id: string /* The unique identifier for the agent */;
+  name: string /* The name of the agent (defaults to ID if not provided) */;
+  description?: string /* A brief description of the agent's purpose */;
 
   /**
    * The instructions for the agent. Will be used as the "system prompt" when this agent is
@@ -38,12 +34,6 @@ export interface AgentConfig<
     | string
     | ((context: Context<TContext>) => Promise<string> | string);
 
-  // /**
-  //  * A description of the agent. This is used when the agent is used as a handoff, so that an LLM
-  //  * knows what it does and when to invoke it.
-  //  */
-  // handoffDescription: string;
-
   // /**
   //  * Handoffs are sub-agents that the agent can delegate to. You can provide a list of handoffs,
   //  * and the agent can choose to delegate to them if relevant. Allows for separation of concerns
@@ -63,6 +53,19 @@ export interface AgentConfig<
    */
   modelSettings?: LanguageModelRequestSettings;
 
+  /**
+   * The type of the output that the agent will return.
+   *
+   * Can be either:
+   * - `"text"` (default): The agent returns a plain string response
+   * - A Zod schema: The agent returns structured output validated against the schema
+   *
+   * When a Zod schema is provided, the output is converted to JSON Schema and sent to the
+   * model for native structured output support. The response is then validated against
+   * the Zod schema as a safety net.
+   */
+  output?: TOutput;
+
   /**
    * A list of toolkits the agent can use. Toolkits are collections of related tools
    * that can be static (Toolkit) or dynamic (MCPToolkit).
@@ -100,12 +103,7 @@ export interface AgentConfig<
    * A list of checks that run in parallel to the agent's execution on the input + output for the agent,
    * depending on the configuration.
    */
-  guardrails?: AgentGuardrails<TResponse>;
-
-  /**
-   * The type of the response that the agent will return. If not provided, response will be a string.
-   */
-  responseType?: TResponse;
+  guardrails?: AgentGuardrails<TOutput>;
 
   // /**
   //  * (TODO): Not sure if this is really necessary.. need to see use case examples
@@ -137,9 +135,7 @@ export interface AgentConfig<
 /**
  * Guardrails for an agent.
  */
-export interface AgentGuardrails<
-  TResponse extends AgentResponseType = TextResponse,
-> {
+export interface AgentGuardrails<TOutput extends AgentOutputType = TextOutput> {
   /**
    * A list of checks that run in parallel to the agent's execution, before generating a response.
    * Runs only if the agent is the first agent in the chain.
@@ -149,14 +145,14 @@ export interface AgentGuardrails<
    * A list of checks that run on the final output of the agent, after generating a response. Runs
    * only if the agent produces a final output.
    */
-  output: OutputGuardrail<TResponse>[];
+  output: OutputGuardrail<TOutput>[];
 }
 
 /**
- * The type of the output object. If not provided, the output will be a string.
+ * The type of the output. If not provided, the output will be a string.
  * 'text' is a special type that indicates the output will be a string.
  */
-export type AgentResponseType = TextResponse | ZodType;
+export type AgentOutputType = TextOutput | ZodType;
 
 /**
  * Memory configuration for an agent.

package/src/agent.ts

@@ -37,10 +37,10 @@ import { MisconfiguredError, RuntimeError } from "./lib/error";
 import type {
   AgentConfig,
   AgentMemoryConfig,
-  AgentResponseType,
+  AgentOutputType,
 } from "./agent/types";
 import type {
-  TextResponse,
+  TextOutput,
   ThreadExecuteOptions,
   ThreadExecuteResult,
   ThreadStreamEvent,
@@ -48,10 +48,10 @@ import type {
 
 export class Agent<
     TContext = UnknownContext,
-    TResponse extends AgentResponseType = TextResponse,
+    TOutput extends AgentOutputType = TextOutput,
   >
-  extends AgentHooks<TContext, TResponse>
-  implements AgentConfig<TContext, TResponse>
+  extends AgentHooks<TContext, TOutput>
+  implements AgentConfig<TContext, TOutput>
 {
   private kernl?: Kernl;
 
@@ -69,25 +69,12 @@ export class Agent<
 
   guardrails: {
     input: InputGuardrail[];
-    output: OutputGuardrail<AgentResponseType>[];
+    output: OutputGuardrail<AgentOutputType>[];
   };
-  responseType: TResponse = "text" as TResponse;
+  output: TOutput = "text" as TOutput;
   resetToolChoice: boolean;
 
-  // --- (TODO) ---
-  // toolUseBehavior: ToolUseBehavior;
-  // handoffs: (Agent<any, TResponse> | Handoff<any, TResponse>)[];
-  // ----------
-
-  // /* Process/thread-group–wide signal state shared by all threads in the group: shared pending signals, job control
-  // (stops/cont, group exit), rlimits, etc. */
-  // signal: *struct signal_struct;
-  //
-  //  /* Table of signal handlers (sa_handler, sa_mask, flags) shared by threads
-  // (CLONE_SIGHAND). RCU-protected so readers can access it locklessly. */
-  // sighand: *struct sighand_struct __rcu;
-
-  constructor(config: AgentConfig<TContext, TResponse>) {
+  constructor(config: AgentConfig<TContext, TOutput>) {
     super();
     if (config.id.trim() === "") {
       throw new MisconfiguredError("Agent must have an id.");
@@ -111,8 +98,8 @@ export class Agent<
     }
 
     this.guardrails = config.guardrails ?? { input: [], output: [] };
-    if (config.responseType) {
-      this.responseType = config.responseType;
+    if (config.output) {
+      this.output = config.output;
     }
     this.resetToolChoice = config.resetToolChoice ?? true;
     // this.toolUseBehavior = config.toolUseBehavior ?? "run_llm_again";
@@ -142,7 +129,7 @@ export class Agent<
   async run(
     input: string | LanguageModelItem[],
     options?: ThreadExecuteOptions<TContext>,
-  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>> {
     if (!this.kernl) {
       throw new MisconfiguredError(
         `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
@@ -155,7 +142,7 @@ export class Agent<
         : input;
     const tid = options?.threadId;
 
-    let thread: Thread<TContext, TResponse> | null = null;
+    let thread: Thread<TContext, TOutput> | null = null;
 
     if (tid) {
       // no concurrent execution of same thread - correctness contract
@@ -168,7 +155,7 @@ export class Agent<
       if (this.kernl.storage?.threads) {
         thread = (await this.kernl.storage.threads.get(tid, {
           history: true,
-        })) as Thread<TContext, TResponse> | null;
+        })) as Thread<TContext, TOutput> | null;
       }
     }
 
@@ -216,7 +203,7 @@ export class Agent<
         : input;
     const tid = options?.threadId;
 
-    let thread: Thread<TContext, TResponse> | null = null;
+    let thread: Thread<TContext, TOutput> | null = null;
 
     if (tid) {
       // no concurrent execution of same thread - correctness contract
@@ -229,7 +216,7 @@ export class Agent<
       if (this.kernl.storage?.threads) {
         thread = (await this.kernl.storage.threads.get(tid, {
           history: true,
-        })) as Thread<TContext, TResponse> | null;
+        })) as Thread<TContext, TOutput> | null;
       }
     }
 

package/src/api/resources/agents/agents.ts

@@ -1,7 +1,7 @@
 import type { Agent } from "@/agent";
-import type { AgentResponseType } from "@/agent/types";
+import type { AgentOutputType } from "@/agent/types";
 import type { UnknownContext } from "@/context";
-import type { TextResponse } from "@/thread/types";
+import type { TextOutput } from "@/thread/types";
 
 /**
  * Agents resource.
@@ -16,15 +16,15 @@ export class RAgents {
   /**
    * Get a live Agent instance by id.
    *
-   * Callers are expected to know the concrete TContext/TResponse types
+   * Callers are expected to know the concrete TContext/TOutput types
    * for their own agents and can specify them via generics.
    */
   get<
     TContext = UnknownContext,
-    TResponse extends AgentResponseType = TextResponse,
-  >(id: string): Agent<TContext, TResponse> | undefined {
+    TOutput extends AgentOutputType = TextOutput,
+  >(id: string): Agent<TContext, TOutput> | undefined {
     const agent = this.registry.get(id);
-    return agent as Agent<TContext, TResponse> | undefined;
+    return agent as Agent<TContext, TOutput> | undefined;
   }
 
   /**
@@ -40,10 +40,10 @@ export class RAgents {
    * Since this is a heterogeneous collection, we expose the widest safe
    * type parameters here.
    */
-  list(): Agent<UnknownContext, AgentResponseType>[] {
+  list(): Agent<UnknownContext, AgentOutputType>[] {
     return Array.from(this.registry.values()) as Agent<
       UnknownContext,
-      AgentResponseType
+      AgentOutputType
     >[];
   }
 

package/src/guardrail.ts

@@ -4,19 +4,19 @@ import { LanguageModelResponse } from "@kernl-sdk/protocol";
 
 import { Agent } from "./agent";
 import { Context, UnknownContext } from "./context";
-import type { AgentResponseType } from "@/agent/types";
-import type { TextResponse, ThreadEvent } from "@/thread/types";
+import type { AgentOutputType } from "@/agent/types";
+import type { TextOutput, ThreadEvent } from "@/thread/types";
 
 /**
  * Resolves the agent output type based on the response type.
- * - If TResponse is "text" → output is string
- * - If TResponse is a ZodType → output is the inferred type from that schema
+ * - If TOutput is "text" → output is string
+ * - If TOutput is a ZodType → output is the inferred type from that schema
  */
-export type ResolvedAgentResponse<TResponse extends AgentResponseType> =
-  TResponse extends TextResponse
+export type ResolvedAgentResponse<TOutput extends AgentOutputType> =
+  TOutput extends TextOutput
     ? string
-    : TResponse extends ZodType
-      ? z.infer<TResponse>
+    : TOutput extends ZodType
+      ? z.infer<TOutput>
       : never;
 
 /**
@@ -149,10 +149,10 @@ export function defineInputGuardrail({
  */
 export interface OutputGuardrailFunctionArgs<
   TContext = UnknownContext,
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   agent: Agent<any, any>;
-  agentOutput: ResolvedAgentResponse<TResponse>; // ??
+  agentOutput: ResolvedAgentResponse<TOutput>; // ??
   context: Context<TContext>;
   /**
    * Additional details about the agent output.
@@ -166,16 +166,16 @@ export interface OutputGuardrailFunctionArgs<
  * A function that takes an output guardrail function arguments and returns a `GuardrailFunctionOutput`.
  */
 export type OutputGuardrailFunction<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > = (
-  args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
+  args: OutputGuardrailFunctionArgs<UnknownContext, TOutput>,
 ) => Promise<GuardrailFunctionOutput>;
 
 /**
  * A guardrail that checks the output of the agent.
  */
 export interface OutputGuardrail<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   /**
    * The name of the guardrail.
@@ -185,7 +185,7 @@ export interface OutputGuardrail<
   /**
    * The function that performs the guardrail check.
    */
-  execute: OutputGuardrailFunction<TResponse>;
+  execute: OutputGuardrailFunction<TOutput>;
 }
 
 /**
@@ -201,7 +201,7 @@ export interface OutputGuardrailMetadata {
  */
 export interface OutputGuardrailResult<
   TMeta = OutputGuardrailMetadata,
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   /**
    * The metadata of the guardrail.
@@ -211,12 +211,12 @@ export interface OutputGuardrailResult<
   /**
    * The output of the agent that ran.
    */
-  agentOutput: ResolvedAgentResponse<TResponse>; // ??
+  agentOutput: ResolvedAgentResponse<TOutput>; // ??
 
   /**
    * The agent that ran.
    */
-  agent: Agent<UnknownContext, TResponse>;
+  agent: Agent<UnknownContext, TOutput>;
 
   /**
    * The output of the guardrail.
@@ -229,43 +229,43 @@ export interface OutputGuardrailResult<
  */
 export interface OutputGuardrailDefinition<
   TMeta = OutputGuardrailMetadata,
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > extends OutputGuardrailMetadata {
-  guardrailFunction: OutputGuardrailFunction<TResponse>;
+  guardrailFunction: OutputGuardrailFunction<TOutput>;
   run(
-    args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
-  ): Promise<OutputGuardrailResult<TMeta, TResponse>>;
+    args: OutputGuardrailFunctionArgs<UnknownContext, TOutput>,
+  ): Promise<OutputGuardrailResult<TMeta, TOutput>>;
 }
 
 /**
  * Arguments for defining an output guardrail definition.
  */
 export interface DefineOutputGuardrailArgs<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   name: string;
-  execute: OutputGuardrailFunction<TResponse>;
+  execute: OutputGuardrailFunction<TOutput>;
 }
 
 /**
  * Creates an output guardrail definition.
  */
 export function defineOutputGuardrail<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 >({
   name,
   execute,
-}: DefineOutputGuardrailArgs<TResponse>): OutputGuardrailDefinition<
+}: DefineOutputGuardrailArgs<TOutput>): OutputGuardrailDefinition<
   OutputGuardrailMetadata,
-  TResponse
+  TOutput
 > {
   return {
     type: "output",
     name,
     guardrailFunction: execute,
     async run(
-      args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
-    ): Promise<OutputGuardrailResult<OutputGuardrailMetadata, TResponse>> {
+      args: OutputGuardrailFunctionArgs<UnknownContext, TOutput>,
+    ): Promise<OutputGuardrailResult<OutputGuardrailMetadata, TOutput>> {
       return {
         guardrail: { type: "output", name },
         agent: args.agent,

package/src/kernl/kernl.ts

@@ -17,7 +17,7 @@ import {
 } from "@/memory";
 
 import type { ThreadExecuteResult, ThreadStreamEvent } from "@/thread/types";
-import type { AgentResponseType } from "@/agent/types";
+import type { AgentOutputType } from "@/agent/types";
 
 import type { KernlOptions } from "./types";
 
@@ -27,7 +27,7 @@ import type { KernlOptions } from "./types";
  * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
  * tracing.
  */
-export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
+export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
   private readonly _agents: Map<string, Agent> = new Map();
   private readonly _models: Map<string, LanguageModel> = new Map();
 
@@ -94,9 +94,9 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
   /**
    * Spawn a new thread - blocking execution
    */
-  async spawn<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
-  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+  async spawn<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>> {
     this.athreads.set(thread.tid, thread);
     try {
       return await thread.execute();
@@ -110,9 +110,9 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
    *
    * NOTE: just blocks for now
    */
-  async schedule<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
-  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+  async schedule<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>> {
     this.athreads.set(thread.tid, thread);
     try {
       return await thread.execute();
@@ -126,8 +126,8 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
    *
    * Spawn a new thread - streaming execution
    */
-  async *spawnStream<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
+  async *spawnStream<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
   ): AsyncIterable<ThreadStreamEvent> {
     this.athreads.set(thread.tid, thread);
     try {
@@ -142,8 +142,8 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
    *
    * Schedule an existing thread - streaming execution
    */
-  async *scheduleStream<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
+  async *scheduleStream<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
   ): AsyncIterable<ThreadStreamEvent> {
     this.athreads.set(thread.tid, thread);
     try {

package/src/lib/error.ts

@@ -9,8 +9,8 @@ import { randomID } from "@kernl-sdk/shared/lib";
 // import { SerializedThread } from "@/lib/serde/thread";
 type SerializedThread = any;
 
-import { AgentResponseType } from "@/agent/types";
-import { TextResponse } from "@/thread/types";
+import { AgentOutputType } from "@/agent/types";
+import { TextOutput } from "@/thread/types";
 
 /**
  * Abstract base class for all `kernl` errors
@@ -144,7 +144,7 @@ export class InputGuardrailTripwireTriggered extends AgentError {
  */
 export class OutputGuardrailTripwireTriggered<
   TMeta extends OutputGuardrailMetadata,
-  TOutputType extends AgentResponseType = TextResponse,
+  TOutputType extends AgentOutputType = TextOutput,
 > extends AgentError {
   result: OutputGuardrailResult<TMeta, TOutputType>;
   constructor(