kernl 0.1.1

package/src/guardrail.ts

@@ -0,0 +1,277 @@
+import { z, type ZodType } from "zod";
+
+import { LanguageModelResponse } from "@kernl/protocol";
+
+import { Agent } from "./agent";
+import { Context, UnknownContext } from "./context";
+import type { AgentResponseType } from "./types/agent";
+import type { TextResponse, ThreadEvent } from "./types/thread";
+
+/**
+ * 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
+ */
+export type ResolvedAgentResponse<TResponse extends AgentResponseType> =
+  TResponse extends TextResponse
+    ? string
+    : TResponse extends ZodType
+      ? z.infer<TResponse>
+      : never;
+
+/**
+ * The output of a guardrail function.
+ */
+export interface GuardrailFunctionOutput {
+  /**
+   * Whether the tripwire was triggered. If triggered, the agent's execution will be halted.
+   */
+  tripwireTriggered: boolean;
+  /**
+   * Optional information about the guardrail's output.
+   * For example, the guardrail could include information about the checks it performed and granular results.
+   */
+  outputInfo: any; // (TODO): better name
+}
+
+// ----------------------------------------------------------
+// Input Guardrail
+// ----------------------------------------------------------
+
+/**
+ * A guardrail that checks the input to the agent.
+ */
+export interface InputGuardrail {
+  /**
+   * The name of the guardrail.
+   */
+  name: string;
+
+  /**
+   * The function that performs the guardrail check
+   */
+  execute: InputGuardrailFunction;
+}
+
+/**
+ * The result of an input guardrail execution.
+ */
+export interface InputGuardrailResult {
+  /**
+   * The metadata of the guardrail.
+   */
+  guardrail: InputGuardrailMetadata;
+
+  /**
+   * The output of the guardrail.
+   */
+  output: GuardrailFunctionOutput;
+}
+
+/**
+ * Arguments for an input guardrail function.
+ */
+export interface InputGuardrailFunctionArgs<TContext = UnknownContext> {
+  /**
+   * The agent that is being run.
+   */
+  agent: Agent<any, any>;
+
+  /**
+   * The input to the agent.
+   */
+  input: string | ThreadEvent[];
+
+  /**
+   * The context of the agent run.
+   */
+  context: Context<TContext>;
+}
+
+/**
+ * The function that performs the actual input guardrail check and returns the decision on whether
+ * a guardrail was triggered.
+ */
+export type InputGuardrailFunction = (
+  args: InputGuardrailFunctionArgs,
+) => Promise<GuardrailFunctionOutput>;
+
+/**
+ * Metadata for an input guardrail.
+ */
+export interface InputGuardrailMetadata {
+  type: "input";
+  name: string;
+}
+
+/**
+ * Definition of an input guardrail. SDK users usually do not need to create this.
+ */
+export interface InputGuardrailDefinition extends InputGuardrailMetadata {
+  guardrailFunction: InputGuardrailFunction;
+  run(args: InputGuardrailFunctionArgs): Promise<InputGuardrailResult>;
+}
+
+/**
+ * Arguments for defining an input guardrail definition.
+ */
+export interface DefineInputGuardrailArgs {
+  name: string;
+  execute: InputGuardrailFunction;
+}
+
+/**
+ * Defines an input guardrail definition.
+ */
+export function defineInputGuardrail({
+  name,
+  execute,
+}: DefineInputGuardrailArgs): InputGuardrailDefinition {
+  return {
+    type: "input",
+    name,
+    guardrailFunction: execute,
+    async run(args: InputGuardrailFunctionArgs): Promise<InputGuardrailResult> {
+      return {
+        guardrail: { type: "input", name },
+        output: await execute(args),
+      };
+    },
+  };
+}
+
+// ----------------------------------------------------------
+// Output Guardrail
+// ----------------------------------------------------------
+
+/**
+ * Arguments for an output guardrail function.
+ */
+export interface OutputGuardrailFunctionArgs<
+  TContext = UnknownContext,
+  TResponse extends AgentResponseType = TextResponse,
+> {
+  agent: Agent<any, any>;
+  agentOutput: ResolvedAgentResponse<TResponse>; // ??
+  context: Context<TContext>;
+  /**
+   * Additional details about the agent output.
+   */
+  details?: {
+    /** Model response associated with the output if available. */
+    modelResponse?: LanguageModelResponse;
+  };
+}
+/**
+ * A function that takes an output guardrail function arguments and returns a `GuardrailFunctionOutput`.
+ */
+export type OutputGuardrailFunction<
+  TResponse extends AgentResponseType = TextResponse,
+> = (
+  args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
+) => Promise<GuardrailFunctionOutput>;
+
+/**
+ * A guardrail that checks the output of the agent.
+ */
+export interface OutputGuardrail<
+  TResponse extends AgentResponseType = TextResponse,
+> {
+  /**
+   * The name of the guardrail.
+   */
+  name: string;
+
+  /**
+   * The function that performs the guardrail check.
+   */
+  execute: OutputGuardrailFunction<TResponse>;
+}
+
+/**
+ * Metadata for an output guardrail.
+ */
+export interface OutputGuardrailMetadata {
+  type: "output";
+  name: string;
+}
+
+/**
+ * The result of an output guardrail execution.
+ */
+export interface OutputGuardrailResult<
+  TMeta = OutputGuardrailMetadata,
+  TResponse extends AgentResponseType = TextResponse,
+> {
+  /**
+   * The metadata of the guardrail.
+   */
+  guardrail: TMeta;
+
+  /**
+   * The output of the agent that ran.
+   */
+  agentOutput: ResolvedAgentResponse<TResponse>; // ??
+
+  /**
+   * The agent that ran.
+   */
+  agent: Agent<UnknownContext, TResponse>;
+
+  /**
+   * The output of the guardrail.
+   */
+  output: GuardrailFunctionOutput;
+}
+
+/**
+ * Definition of an output guardrail.
+ */
+export interface OutputGuardrailDefinition<
+  TMeta = OutputGuardrailMetadata,
+  TResponse extends AgentResponseType = TextResponse,
+> extends OutputGuardrailMetadata {
+  guardrailFunction: OutputGuardrailFunction<TResponse>;
+  run(
+    args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
+  ): Promise<OutputGuardrailResult<TMeta, TResponse>>;
+}
+
+/**
+ * Arguments for defining an output guardrail definition.
+ */
+export interface DefineOutputGuardrailArgs<
+  TResponse extends AgentResponseType = TextResponse,
+> {
+  name: string;
+  execute: OutputGuardrailFunction<TResponse>;
+}
+
+/**
+ * Creates an output guardrail definition.
+ */
+export function defineOutputGuardrail<
+  TResponse extends AgentResponseType = TextResponse,
+>({
+  name,
+  execute,
+}: DefineOutputGuardrailArgs<TResponse>): OutputGuardrailDefinition<
+  OutputGuardrailMetadata,
+  TResponse
+> {
+  return {
+    type: "output",
+    name,
+    guardrailFunction: execute,
+    async run(
+      args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
+    ): Promise<OutputGuardrailResult<OutputGuardrailMetadata, TResponse>> {
+      return {
+        guardrail: { type: "output", name },
+        agent: args.agent,
+        agentOutput: args.agentOutput,
+        output: await execute(args),
+      };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { Kernl } from "./kernl";
+export { Agent } from "./agent";
+export type { Context } from "./context";

package/src/kernl.ts

@@ -0,0 +1,22 @@
+import { Agent } from "./agent";
+import { UnknownContext } from "./context";
+import { KernlHooks } from "./lifecycle";
+
+import type { AgentResponseType } from "./types/agent";
+
+/**
+ * Central coordinator for the entire application.
+ *
+ * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
+ * tracing.
+ */
+export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
+  private agents: Map<string, Agent> = new Map();
+
+  /**
+   * Registers a new agent with the kernl instance.
+   */
+  register(agent: Agent): void {
+    // TODO: Implement agent registration
+  }
+}

package/src/lib/env.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+/**
+ * Environment variable validation schema
+ *
+ * This ensures all environment variables are valid at startup.
+ * All variables are optional with sensible defaults.
+ */
+const envSchema = z.object({
+  // --- Logging ---
+  LOG_LEVEL: z
+    .enum(["trace", "debug", "info", "warn", "error", "fatal"])
+    .default("info"),
+  KERNL_LOG_MODEL_DATA: z
+    .enum(["true", "false"])
+    .optional()
+    .transform((val) => val === "true"),
+  KERNL_LOG_TOOL_DATA: z
+    .enum(["true", "false"])
+    .optional()
+    .transform((val) => val === "true"),
+});
+
+/**
+ * Validated and type-safe environment variables
+ *
+ * @example
+ * import { env } from '@/env';
+ * console.log(env.LOG_LEVEL);
+ */
+export const env = envSchema.parse(process.env);
+
+/**
+ * Type of the validated environment variables
+ */
+export type Env = z.infer<typeof envSchema>;

package/src/lib/error.ts

@@ -0,0 +1,158 @@
+import {
+  InputGuardrailResult,
+  OutputGuardrailMetadata,
+  OutputGuardrailResult,
+} from "@/guardrail";
+
+import { randomID } from "@kernl/shared/lib";
+// TODO: implement checkpointing/serialization
+// import { SerializedThread } from "@/lib/serde/thread";
+type SerializedThread = any;
+
+import { AgentResponseType } from "@/types/agent";
+import { TextResponse } from "@/types/thread";
+
+/**
+ * Abstract base class for all `kernl` errors
+ * Requires subclasses to implement JSON serialization
+ */
+export abstract class BaseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+
+  /**
+   * Convert error to JSON representation
+   * Must be implemented by subclasses
+   */
+  abstract toJSON(): Record<string, any>;
+}
+
+/**
+ * Runtime error with trace ID for debugging
+ */
+export class RuntimeError extends BaseError {
+  public readonly traceId: string;
+
+  constructor(message: string, traceId?: string) {
+    super(message);
+    this.traceId = traceId || randomID();
+  }
+
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      message: this.message,
+      traceId: this.traceId,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Base class for all errors thrown by the library.
+ */
+export abstract class AgentError extends RuntimeError {
+  thread?: SerializedThread;
+
+  constructor(message: string, state?: SerializedThread, traceId?: string) {
+    super(message, traceId);
+    this.thread = state;
+  }
+
+  override toJSON(): Record<string, any> {
+    return {
+      ...super.toJSON(),
+      thread: this.thread,
+    };
+  }
+}
+
+/**
+ * System error thrown when the library encounters an error that is not caused by the user's
+ * misconfiguration.
+ */
+export class SystemError extends RuntimeError {}
+
+/**
+ * Thrown due to user misconfiguration
+ *
+ * This error indicates that the library was not configured correctly by the user.
+ * Common causes include invalid configuration options, missing required fields,
+ * or incompatible configuration combinations.
+ */
+export class MisconfiguredError extends BaseError {
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      message: this.message,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Error thrown when the maximum number of turns is exceeded.
+ */
+export class MaxTurnsExceededError extends AgentError {}
+
+/**
+ * Error thrown when a model behavior is unexpected.
+ */
+export class ModelBehaviorError extends AgentError {}
+
+/**
+ * Error thrown when a guardrail execution fails.
+ */
+export class GuardrailExecutionError extends AgentError {
+  error: Error;
+  constructor(message: string, error: Error, thread?: SerializedThread) {
+    super(message, thread);
+    this.error = error;
+  }
+}
+
+/**
+ * Error thrown when a tool call fails.
+ */
+export class ToolCallError extends AgentError {
+  error: Error;
+  constructor(message: string, error: Error, thread?: SerializedThread) {
+    super(message, thread);
+    this.error = error;
+  }
+}
+
+/**
+ * Error thrown when an input guardrail tripwire is triggered.
+ */
+export class InputGuardrailTripwireTriggered extends AgentError {
+  result: InputGuardrailResult;
+  constructor(
+    message: string,
+    result: InputGuardrailResult,
+    thread?: SerializedThread,
+  ) {
+    super(message, thread);
+    this.result = result;
+  }
+}
+
+/**
+ * Error thrown when an output guardrail tripwire is triggered.
+ */
+export class OutputGuardrailTripwireTriggered<
+  TMeta extends OutputGuardrailMetadata,
+  TOutputType extends AgentResponseType = TextResponse,
+> extends AgentError {
+  result: OutputGuardrailResult<TMeta, TOutputType>;
+  constructor(
+    message: string,
+    result: OutputGuardrailResult<TMeta, TOutputType>,
+    thread?: SerializedThread,
+  ) {
+    super(message, thread);
+    this.result = result;
+  }
+}

package/src/lib/logger.ts

@@ -0,0 +1,78 @@
+import pino from "pino";
+
+import { env } from "./env";
+
+/**
+ * By default we don't log LLM inputs/outputs, to prevent exposing sensitive data.
+ * Set KERNL_LOG_MODEL_DATA=true to enable.
+ */
+const dontLogModelData = !env.KERNL_LOG_MODEL_DATA;
+
+/**
+ * By default we don't log tool inputs/outputs, to prevent exposing sensitive data.
+ * Set KERNL_LOG_TOOL_DATA=true to enable.
+ */
+const dontLogToolData = !env.KERNL_LOG_TOOL_DATA;
+
+/**
+ * Base pino logger instance
+ */
+const base = pino({
+  level: env.LOG_LEVEL,
+});
+
+/**
+ * A logger instance with namespace support and sensitive data flags.
+ */
+export type Logger = {
+  /**
+   * The namespace used for the logger.
+   */
+  namespace: string;
+
+  trace: (message: any, ...args: any[]) => void;
+  debug: (message: any, ...args: any[]) => void;
+  info: (message: any, ...args: any[]) => void;
+  warn: (message: any, ...args: any[]) => void;
+  error: (message: any, ...args: any[]) => void;
+  fatal: (message: any, ...args: any[]) => void;
+
+  /**
+   * Whether to log model data.
+   */
+  dontLogModelData: boolean;
+
+  /**
+   * Whether to log tool data.
+   */
+  dontLogToolData: boolean;
+};
+
+/**
+ * Get a logger for a given namespace.
+ *
+ * @param namespace - the namespace to use for the logger (e.g., 'kernl:core', 'kernl:agent').
+ * @returns A logger object with all pino log levels and sensitive data flags.
+ */
+export function getLogger(namespace: string = "kernl"): Logger {
+  const child = base.child({ namespace });
+
+  return {
+    namespace,
+    trace: child.trace.bind(child),
+    debug: child.debug.bind(child),
+    info: child.info.bind(child),
+    warn: child.warn.bind(child),
+    error: child.error.bind(child),
+    fatal: child.fatal.bind(child),
+    dontLogModelData,
+    dontLogToolData,
+  };
+}
+
+/**
+ * Default logger instance for the core library.
+ */
+export const logger = getLogger("kernl");
+
+export default logger;

package/src/lib/serde/json.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+/**
+ * Represents a JSON-serializable value that can be safely stringified and sent to the model.
+ * Recursive type that allows nested structures.
+ */
+export const JSONValue: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JSONValue),
+    z.record(z.string(), JSONValue),
+  ]),
+);
+
+export type JSONValue = z.infer<typeof JSONValue>;