kernl 0.1.1

package/dist/lib/logger.js

@@ -0,0 +1,43 @@
+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,
+});
+/**
+ * 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 = "kernl") {
+    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/dist/lib/serde/__tests__/codec.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec.test.d.ts.map

package/dist/lib/serde/__tests__/codec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.test.d.ts","sourceRoot":"","sources":["../../../../src/lib/serde/__tests__/codec.test.ts"],"names":[],"mappings":""}

package/dist/lib/serde/__tests__/codec.test.js

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { json } from "../codec";
+describe("json codec", () => {
+    it("should parse valid JSON and validate against schema", () => {
+        const schema = z.object({
+            name: z.string(),
+            age: z.number(),
+        });
+        const codec = json(schema);
+        const result = codec.decode('{"name": "Alice", "age": 30}');
+        expect(result).toEqual({ name: "Alice", age: 30 });
+    });
+    it("should reject invalid JSON syntax", () => {
+        const schema = z.object({
+            name: z.string(),
+        });
+        const codec = json(schema);
+        expect(() => {
+            codec.decode('{"name": "Alice"');
+        }).toThrow();
+    });
+    it("should reject valid JSON that doesn't match schema", () => {
+        const schema = z.object({
+            name: z.string(),
+            age: z.number(),
+        });
+        const codec = json(schema);
+        // Valid JSON but age is a string, not a number
+        expect(() => {
+            codec.decode('{"name": "Alice", "age": "30"}');
+        }).toThrow();
+    });
+    it("should reject JSON missing required fields", () => {
+        const schema = z.object({
+            name: z.string(),
+            age: z.number(),
+        });
+        const codec = json(schema);
+        // Valid JSON but missing age field
+        expect(() => {
+            codec.decode('{"name": "Alice"}');
+        }).toThrow();
+    });
+    it("should handle nested objects", () => {
+        const schema = z.object({
+            user: z.object({
+                name: z.string(),
+                email: z.string().email(),
+            }),
+            metadata: z.object({
+                createdAt: z.string(),
+            }),
+        });
+        const codec = json(schema);
+        const result = codec.decode('{"user": {"name": "Bob", "email": "bob@example.com"}, "metadata": {"createdAt": "2024-01-01"}}');
+        expect(result).toEqual({
+            user: { name: "Bob", email: "bob@example.com" },
+            metadata: { createdAt: "2024-01-01" },
+        });
+    });
+    it("should reject nested objects that don't match schema", () => {
+        const schema = z.object({
+            user: z.object({
+                name: z.string(),
+                email: z.string().email(),
+            }),
+        });
+        const codec = json(schema);
+        // Invalid email format
+        expect(() => {
+            codec.decode('{"user": {"name": "Bob", "email": "not-an-email"}}');
+        }).toThrow();
+    });
+});

package/dist/lib/serde/codec.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export declare const stringToNumber: z.ZodCodec<z.ZodString, z.ZodNumber>;
+export declare const stringToInt: z.ZodCodec<z.ZodString, z.ZodInt>;
+export declare const isotime: z.ZodCodec<z.ZodISODateTime, z.ZodDate>;
+export declare const epochsec: z.ZodCodec<z.ZodInt, z.ZodDate>;
+export declare const epochms: z.ZodCodec<z.ZodInt, z.ZodDate>;
+export declare const json: <T extends z.core.$ZodType>(schema: T) => z.ZodCodec<z.ZodString, T>;
+export declare const stringToURL: z.ZodCodec<z.ZodURL, z.ZodCustom<import("url").URL, import("url").URL>>;
+export declare const stringToHttpURL: z.ZodCodec<z.ZodURL, z.ZodCustom<import("url").URL, import("url").URL>>;
+export declare const base64ToBytes: z.ZodCodec<z.ZodBase64, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+export declare const base64urlToBytes: z.ZodCodec<z.ZodBase64URL, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/lib/serde/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/lib/serde/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc,sCAO1B,CAAC;AAEF,eAAO,MAAM,WAAW,mCAOvB,CAAC;AAEF,eAAO,MAAM,OAAO,yCAGlB,CAAC;AAEH,eAAO,MAAM,QAAQ,iCAGnB,CAAC;AAEH,eAAO,MAAM,OAAO,iCAGlB,CAAC;AAEH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,+BAgBrD,CAAC;AAEL,eAAO,MAAM,WAAW,yEAGtB,CAAC;AAEH,eAAO,MAAM,eAAe,yEAG1B,CAAC;AAEH,eAAO,MAAM,aAAa,wFAGxB,CAAC;AAEH,eAAO,MAAM,gBAAgB,2FAO5B,CAAC"}

package/dist/lib/serde/codec.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export const stringToNumber = z.codec(z.string().regex(z.regexes.number), z.number(), {
+    decode: (str) => Number.parseFloat(str),
+    encode: (num) => num.toString(),
+});
+export const stringToInt = z.codec(z.string().regex(z.regexes.integer), z.int(), {
+    decode: (str) => Number.parseInt(str, 10),
+    encode: (num) => num.toString(),
+});
+export const isotime = z.codec(z.iso.datetime(), z.date(), {
+    decode: (isoString) => new Date(isoString),
+    encode: (date) => date.toISOString(),
+});
+export const epochsec = z.codec(z.int().min(0), z.date(), {
+    decode: (seconds) => new Date(seconds * 1000),
+    encode: (date) => Math.floor(date.getTime() / 1000),
+});
+export const epochms = z.codec(z.int().min(0), z.date(), {
+    decode: (millis) => new Date(millis),
+    encode: (date) => date.getTime(),
+});
+export const json = (schema) => z.codec(z.string(), schema, {
+    decode: (jsonString, ctx) => {
+        try {
+            return JSON.parse(jsonString);
+        }
+        catch (err) {
+            ctx.issues.push({
+                code: "invalid_format",
+                format: "json",
+                input: jsonString,
+                message: err.message,
+            });
+            return z.NEVER;
+        }
+    },
+    encode: (value) => JSON.stringify(value),
+});
+export const stringToURL = z.codec(z.url(), z.instanceof(URL), {
+    decode: (urlString) => new URL(urlString),
+    encode: (url) => url.href,
+});
+export const stringToHttpURL = z.codec(z.httpUrl(), z.instanceof(URL), {
+    decode: (urlString) => new URL(urlString),
+    encode: (url) => url.href,
+});
+export const base64ToBytes = z.codec(z.base64(), z.instanceof(Uint8Array), {
+    decode: (base64String) => z.util.base64ToUint8Array(base64String),
+    encode: (bytes) => z.util.uint8ArrayToBase64(bytes),
+});
+export const base64urlToBytes = z.codec(z.base64url(), z.instanceof(Uint8Array), {
+    decode: (base64urlString) => z.util.base64urlToUint8Array(base64urlString),
+    encode: (bytes) => z.util.uint8ArrayToBase64url(bytes),
+});

package/dist/lib/serde/json.d.ts

@@ -0,0 +1,8 @@
+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 declare const JSONValue: z.ZodType<unknown>;
+export type JSONValue = z.infer<typeof JSONValue>;
+//# sourceMappingURL=json.d.ts.map

package/dist/lib/serde/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/lib/serde/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CASxC,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/lib/serde/json.js

@@ -0,0 +1,13 @@
+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.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JSONValue),
+    z.record(z.string(), JSONValue),
+]));

package/dist/lib/serde/thread.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=thread.d.ts.map

package/dist/lib/serde/thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../../src/lib/serde/thread.ts"],"names":[],"mappings":""}

package/dist/lib/serde/thread.js

@@ -0,0 +1,172 @@
+"use strict";
+// import { z } from "zod";
+// import * as events from "../../types/thread";
+// /**
+//  * Utilities and schemas for serializing the run-state so that it can be paused / resumed later.
+//  *
+//  * (TODO): should be able to define this as a codec for the ThreadState schema
+//  */
+// /**
+//  * The schema version of the serialized run state. This is used to ensure that the serialized
+//  * run state is compatible with the current version of the SDK.
+//  * If anything in this schema changes, the version will have to be incremented.
+//  */
+// export const CURRENT_SCHEMA_VERSION = "1.0" as const;
+// const $schemaVersion = z.literal(CURRENT_SCHEMA_VERSION);
+// const serializedAgentSchema = z.object({
+//   id: z.string(),
+//   name: z.string().optional(),
+// });
+// const serializedSpanBase = z.object({
+//   object: z.literal("trace.span"),
+//   id: z.string(),
+//   trace_id: z.string(),
+//   parent_id: z.string().nullable(),
+//   started_at: z.string().nullable(),
+//   ended_at: z.string().nullable(),
+//   error: z
+//     .object({
+//       message: z.string(),
+//       data: z.record(z.string(), z.any()).optional(),
+//     })
+//     .nullable(),
+//   span_data: z.record(z.string(), z.any()),
+// });
+// type SerializedSpanType = z.infer<typeof serializedSpanBase> & {
+//   previous_span?: SerializedSpanType;
+// };
+// const SerializedSpan: z.ZodType<SerializedSpanType> = serializedSpanBase.extend(
+//   {
+//     previous_span: z.lazy(() => SerializedSpan).optional(),
+//   },
+// );
+// const usageSchema = z.object({
+//   requests: z.number(),
+//   inputTokens: z.number(),
+//   outputTokens: z.number(),
+//   totalTokens: z.number(),
+// });
+// const modelResponseSchema = z.object({
+//   usage: usageSchema,
+//   events: z.array(events.ThreadEvent),
+//   responseId: z.string().optional(),
+//   providerData: z.record(z.string(), z.any()).optional(),
+// });
+// const itemSchema = z.discriminatedUnion("kind", [
+//   z.object({
+//     kind: z.literal("message"),
+//     rawItem: events.AssistantMessage,
+//     agent: serializedAgentSchema,
+//   }),
+//   z.object({
+//     kind: z.literal("tool-call"),
+//     // rawItem: events.ToolCall.or(events.HostedToolCall),
+//     rawItem: events.ToolCall,
+//     agent: serializedAgentSchema,
+//   }),
+//   z.object({
+//     kind: z.literal("tool-result"),
+//     rawItem: events.ToolResultEvent,
+//     agent: serializedAgentSchema,
+//     output: z.string(),
+//   }),
+//   z.object({
+//     kind: z.literal("reasoning"),
+//     rawItem: events.Reasoning,
+//     agent: serializedAgentSchema,
+//   }),
+// ]);
+// const serializedTraceSchema = z.object({
+//   object: z.literal("trace"),
+//   id: z.string(),
+//   workflow_name: z.string(),
+//   group_id: z.string().nullable(),
+//   metadata: z.record(z.string(), z.any()),
+// });
+// const serializedProcessedResponseSchema = z.object({
+//   newItems: z.array(itemSchema),
+//   toolsUsed: z.array(z.string()),
+//   functions: z.array(
+//     z.object({
+//       toolCall: z.any(),
+//       tool: z.any(),
+//     }),
+//   ),
+//   mcpApprovalRequests: z
+//     .array(
+//       z.object({
+//         requestItem: z.object({
+//           // protocol.HostedToolCallItem
+//           rawItem: z.object({
+//             type: z.literal("hosted_tool_call"),
+//             name: z.string(),
+//             arguments: z.string().optional(),
+//             status: z.string().optional(),
+//             output: z.string().optional(),
+//             // this always exists but marked as optional for early version compatibility; when releasing 1.0, we can remove the nullable and optional
+//             providerData: z.record(z.string(), z.any()).nullable().optional(),
+//           }),
+//         }),
+//         // HostedMCPTool
+//         mcpTool: z.object({
+//           type: z.literal("hosted_tool"),
+//           name: z.literal("hosted_mcp"),
+//           providerData: z.record(z.string(), z.any()),
+//         }),
+//       }),
+//     )
+//     .optional(),
+// });
+// const guardrailFunctionOutputSchema = z.object({
+//   tripwireTriggered: z.boolean(),
+//   outputInfo: z.any(),
+// });
+// const inputGuardrailResultSchema = z.object({
+//   guardrail: z.object({
+//     type: z.literal("input"),
+//     name: z.string(),
+//   }),
+//   output: guardrailFunctionOutputSchema,
+// });
+// const outputGuardrailResultSchema = z.object({
+//   guardrail: z.object({
+//     type: z.literal("output"),
+//     name: z.string(),
+//   }),
+//   agentOutput: z.any(),
+//   agent: serializedAgentSchema,
+//   output: guardrailFunctionOutputSchema,
+// });
+// // (TODO): define z.codec
+// export const SerializedThread = z.object({
+//   $schemaVersion,
+//   currentTurn: z.number(),
+//   currentAgent: serializedAgentSchema, // (TODO): in our case we probably don't need to serialize the whole agent - an ID would suffice
+//   originalInput: z.string().or(z.array(events.ThreadEvent)),
+//   modelResponses: z.array(modelResponseSchema),
+//   context: z.object({
+//     usage: usageSchema, // (TODO): move to stats
+//     // (TODO): belongs elsewhere
+//     approvals: z.record(
+//       z.string(),
+//       z.object({
+//         approved: z.array(z.string()).or(z.boolean()),
+//         rejected: z.array(z.string()).or(z.boolean()),
+//       }),
+//     ),
+//     context: z.record(z.string(), z.any()),
+//   }),
+//   toolUseTracker: z.record(z.string(), z.array(z.string())),
+//   maxTurns: z.number(),
+//   currentAgentSpan: SerializedSpan.nullable().optional(),
+//   noActiveAgentRun: z.boolean(),
+//   inputGuardrailResults: z.array(inputGuardrailResultSchema),
+//   outputGuardrailResults: z.array(outputGuardrailResultSchema),
+//   // (TODO): currentStep: nextStepSchema.optional(),
+//   lastModelResponse: modelResponseSchema.optional(),
+//   generatedItems: z.array(itemSchema),
+//   lastProcessedResponse: serializedProcessedResponseSchema.optional(),
+//   currentTurnPersistedItemCount: z.number().int().min(0).optional(),
+//   trace: serializedTraceSchema.nullable(),
+// });
+// export type SerializedThread = z.infer<typeof SerializedThread>;

package/dist/lib/serde/tool.d.ts

@@ -0,0 +1,36 @@
+import type { ToolInputParameters } from "../../tool/types";
+/**
+ * Serialized function tool for model requests
+ */
+export type SerializedFunctionTool = {
+    /**
+     * The type of the tool.
+     */
+    type: "function";
+    /**
+     * The name of the tool.
+     */
+    name?: string;
+    /**
+     * The description of the tool that helps the model to understand when to use the tool
+     */
+    description: string;
+    /**
+     * A JSON schema describing the parameters of the tool.
+     */
+    parameters: ToolInputParameters;
+};
+/**
+ * Serialized hosted tool for model requests
+ */
+export type SerializedHostedTool = {
+    type: "hosted-tool";
+    id: string;
+    name?: string;
+    providerData?: Record<string, any>;
+};
+/**
+ * Union of all serialized tool types
+ */
+export type SerializedTool = SerializedFunctionTool | SerializedHostedTool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/lib/serde/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/lib/serde/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,mBAAmB,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,sBAAsB,GAAG,oBAAoB,CAAC"}

package/dist/lib/serde/tool.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Async version of Array.filter() that works with async predicates.
+ * Runs all predicates in parallel and filters based on results.
+ */
+export declare function filter<T>(array: T[], predicate: (item: T) => Promise<boolean>): Promise<T[]>;
+/**
+ * Generate an ISO 8601 timestamp of the current time.
+ * @returns An ISO 8601 timestamp.
+ */
+export declare function timeISO(): string;
+/**
+ * Generate a random ID with the specified number of bytes.
+ * @param bytes - Number of bytes to generate (e.g., 8 for 64-bit, 16 for 128-bit)
+ * @returns A hex string representation of the random bytes
+ */
+export declare function randomID(bytes?: number): string;
+export type SafeExecuteResult<T> = [Error | unknown | null, T | null];
+export declare function safeExecute<T>(fn: () => T): Promise<SafeExecuteResult<T>>;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/lib/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,CAAC,EAAE,CAAC,CAGd;AAED;;;GAGG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,GAAE,MAAW,GAAG,MAAM,CAanD;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;AAEtE,wBAAsB,WAAW,CAAC,CAAC,EACjC,EAAE,EAAE,MAAM,CAAC,GACV,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAM/B"}

package/dist/lib/utils.js

@@ -0,0 +1,41 @@
+/**
+ * Async version of Array.filter() that works with async predicates.
+ * Runs all predicates in parallel and filters based on results.
+ */
+export async function filter(array, predicate) {
+    const results = await Promise.all(array.map(predicate));
+    return array.filter((_, index) => results[index]);
+}
+/**
+ * Generate an ISO 8601 timestamp of the current time.
+ * @returns An ISO 8601 timestamp.
+ */
+export function timeISO() {
+    return new Date().toISOString();
+}
+/**
+ * Generate a random ID with the specified number of bytes.
+ * @param bytes - Number of bytes to generate (e.g., 8 for 64-bit, 16 for 128-bit)
+ * @returns A hex string representation of the random bytes
+ */
+export function randomID(bytes = 12) {
+    const byteArray = new Uint8Array(bytes);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        crypto.getRandomValues(byteArray);
+    }
+    else {
+        // Fallback for environments without crypto.getRandomValues
+        for (let i = 0; i < bytes; i++) {
+            byteArray[i] = Math.floor(Math.random() * 256);
+        }
+    }
+    return Array.from(byteArray, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export async function safeExecute(fn) {
+    try {
+        return [null, await fn()];
+    }
+    catch (error) {
+        return [error, null];
+    }
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,133 @@
+import { EventEmitter } from "node:events";
+import { Agent } from "./agent";
+import { Context, UnknownContext } from "./context";
+import { Tool } from "./tool";
+import type { ToolCall } from "@kernl/protocol";
+import { AgentResponseType } from "./types/agent";
+import { TextResponse } from "./types/thread";
+export type EventEmitterEvents = Record<string, any[]>;
+/**
+ * Generic typed event emitter that wraps Node's EventEmitter with type safety
+ */
+declare class TypedEventEmitter<EventTypes extends EventEmitterEvents = Record<string, any[]>> extends EventEmitter {
+    on<K extends keyof EventTypes>(event: K, listener: (...args: EventTypes[K]) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    off<K extends keyof EventTypes>(event: K, listener: (...args: EventTypes[K]) => void): this;
+    off(event: string | symbol, listener: (...args: any[]) => void): this;
+    emit<K extends keyof EventTypes>(event: K, ...args: EventTypes[K]): boolean;
+    emit(event: string | symbol, ...args: any[]): boolean;
+    once<K extends keyof EventTypes>(event: K, listener: (...args: EventTypes[K]) => void): this;
+    once(event: string | symbol, listener: (...args: any[]) => void): this;
+}
+export type AgentHookEvents<TContext = UnknownContext, TOutput extends AgentResponseType = TextResponse> = {
+    /**
+     * @param context - The context of the run
+     */
+    agent_start: [context: Context<TContext>, agent: Agent<TContext, TOutput>];
+    /**
+     * @param context - The context of the run
+     * @param output - The output of the agent
+     */
+    agent_end: [context: Context<TContext>, output: string];
+    /**
+     * @param context - The context of the run
+     * @param agent - The agent that is starting a tool
+     * @param tool - The tool that is starting
+     */
+    agent_tool_start: [
+        context: Context<TContext>,
+        tool: Tool<any>,
+        details: {
+            toolCall: ToolCall;
+        }
+    ];
+    /**
+     * @param context - The context of the run
+     * @param agent - The agent that is ending a tool
+     * @param tool - The tool that is ending
+     * @param result - The result of the tool
+     */
+    agent_tool_end: [
+        context: Context<TContext>,
+        tool: Tool<any>,
+        result: string,
+        details: {
+            toolCall: ToolCall;
+        }
+    ];
+};
+/**
+ * Event emitter that every Agent instance inherits from and that emits events for the lifecycle
+ * of the agent.
+ */
+export declare class AgentHooks<TContext = UnknownContext, TOutput extends AgentResponseType = TextResponse> extends TypedEventEmitter<AgentHookEvents<TContext, TOutput>> {
+}
+/**
+ * Events emitted by the kernl during execution.
+ *
+ * Unlike AgentHookEvents (which are emitted by individual agents with implicit context),
+ * KernlHookEvents explicitly include the agent reference in all events since it needs to
+ * coordinate multiple agents and listeners need to know which agent triggered each event.
+ */
+export type KernlHookEvents<TContext = UnknownContext, TOutput extends AgentResponseType = TextResponse> = {
+    /**
+     * @param context - The context of the run
+     * @param agent - The agent that is starting
+     */
+    agent_start: [context: Context<TContext>, agent: Agent<TContext, TOutput>];
+    /**
+     * @param context - The context of the run
+     * @param agent - The agent that is ending
+     * @param output - The output of the agent
+     */
+    agent_end: [
+        context: Context<TContext>,
+        agent: Agent<TContext, TOutput>,
+        output: string
+    ];
+    /**
+     * @param context - The context of the run
+     * @param fromAgent - The agent that is handing off
+     * @param toAgent - The next agent to run
+     */
+    agent_handoff: [
+        context: Context<TContext>,
+        fromAgent: Agent<any, any>,
+        toAgent: Agent<any, any>
+    ];
+    /**
+     * @param context - The context of the run
+     * @param agent - The agent that is starting a tool
+     * @param tool - The tool that is starting
+     */
+    agent_tool_start: [
+        context: Context<TContext>,
+        agent: Agent<TContext, TOutput>,
+        tool: Tool,
+        details: {
+            toolCall: ToolCall;
+        }
+    ];
+    /**
+     * @param context - The context of the run
+     * @param agent - The agent that is ending a tool
+     * @param tool - The tool that is ending
+     * @param result - The result of the tool
+     */
+    agent_tool_end: [
+        context: Context<TContext>,
+        agent: Agent<TContext, TOutput>,
+        tool: Tool,
+        result: string,
+        details: {
+            toolCall: ToolCall;
+        }
+    ];
+};
+/**
+ * Event emitter that the kernl uses to emit events for the lifecycle of every agent run.
+ */
+export declare class KernlHooks<TContext = UnknownContext, TOutput extends AgentResponseType = TextResponse> extends TypedEventEmitter<KernlHookEvents<TContext, TOutput>> {
+}
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;AAEvD;;GAEG;AACH,cAAM,iBAAiB,CACrB,UAAU,SAAS,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAC7D,SAAQ,YAAY;IAEpB,EAAE,CAAC,CAAC,SAAS,MAAM,UAAU,EAC3B,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,GACzC,IAAI;IAEP,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;IAMpE,GAAG,CAAC,CAAC,SAAS,MAAM,UAAU,EAC5B,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,GACzC,IAAI;IAEP,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;IAMrE,IAAI,CAAC,CAAC,SAAS,MAAM,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO;IAE3E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO;IAMrD,IAAI,CAAC,CAAC,SAAS,MAAM,UAAU,EAC7B,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,GACzC,IAAI;IAEP,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;CAIvE;AAED,MAAM,MAAM,eAAe,CACzB,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,iBAAiB,GAAG,YAAY,IAC9C;IACF;;OAEG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3E;;;OAGG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAOxD;;;;OAIG;IACH,gBAAgB,EAAE;QAChB,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;QAC1B,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;QACf,OAAO,EAAE;YAAE,QAAQ,EAAE,QAAQ,CAAA;SAAE;KAChC,CAAC;IACF;;;;;OAKG;IACH,cAAc,EAAE;QACd,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;QAC1B,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;QACf,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YAAE,QAAQ,EAAE,QAAQ,CAAA;SAAE;KAChC,CAAC;CACH,CAAC;AAEF;;;GAGG;AACH,qBAAa,UAAU,CACrB,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,iBAAiB,GAAG,YAAY,CAChD,SAAQ,iBAAiB,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;CAAG;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CACzB,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,iBAAiB,GAAG,YAAY,IAC9C;IACF;;;OAGG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3E;;;;OAIG;IACH,SAAS,EAAE;QACT,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;QAC1B,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC/B,MAAM,EAAE,MAAM;KACf,CAAC;IACF;;;;OAIG;IACH,aAAa,EAAE;QACb,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;QAC1B,SAAS,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC;QAC1B,OAAO,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC;KACzB,CAAC;IACF;;;;OAIG;IACH,gBAAgB,EAAE;QAChB,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;QAC1B,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC/B,IAAI,EAAE,IAAI;QACV,OAAO,EAAE;YAAE,QAAQ,EAAE,QAAQ,CAAA;SAAE;KAChC,CAAC;IACF;;;;;OAKG;IACH,cAAc,EAAE;QACd,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;QAC1B,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC/B,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YAAE,QAAQ,EAAE,QAAQ,CAAA;SAAE;KAChC,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,qBAAa,UAAU,CACrB,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,iBAAiB,GAAG,YAAY,CAChD,SAAQ,iBAAiB,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;CAAG"}