kernl 0.1.3 → 0.2.0

package/dist/tool/index.js

@@ -1,2 +1,2 @@
 export { BaseTool, FunctionTool, HostedTool, tool } from "./tool";
-export { Toolkit, FunctionToolkit, MCPToolkit } from "./toolkit";
+export { BaseToolkit, Toolkit, FunctionToolkit, MCPToolkit } from "./toolkit";

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

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

package/dist/tool/tool.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { ModelBehaviorError } from "../lib/error";
 import { logger } from "../lib/logger";
 import { json } from "@kernl-sdk/shared/lib";
@@ -93,9 +94,10 @@ export class FunctionTool extends BaseTool {
                 throw new ModelBehaviorError("Invalid JSON input for tool");
             }
         }
-        // Check if approval is required
+        // check if approval is required
         const needsApproval = await this.requiresApproval(context, parsed, callId);
         const approvalStatus = callId ? context.approvals.get(callId) : undefined;
+        // (TODO): this will become a more detailed action.approval event
         if (needsApproval && approvalStatus !== "approved") {
             return {
                 state: INTERRUPTIBLE,
@@ -118,7 +120,9 @@ export class FunctionTool extends BaseTool {
             kind: "function",
             name: this.id,
             description: this.description,
-            parameters: this.parameters, // TODO: convert Zod to JSON Schema
+            parameters: (this.parameters
+                ? z.toJSONSchema(this.parameters, { target: "draft-7" })
+                : {}), // JSONSchema7 - target: 'draft-7' produces this
         };
     }
 }

package/dist/tool/toolkit.d.ts

@@ -8,11 +8,15 @@ import type { FunctionToolkitConfig, MCPToolkitConfig } from "./types";
  * Toolkits can be static (FunctionToolkit) or dynamic (MCPToolkit), and provide
  * a unified interface for tool discovery and management.
  */
-export declare abstract class Toolkit<TContext = UnknownContext> {
+export declare abstract class BaseToolkit<TContext = UnknownContext> {
     /**
      * Unique identifier for this toolkit
      */
     abstract readonly id: string;
+    /**
+     * Description of what this toolkit provides
+     */
+    abstract readonly description: string;
     /**
      * The agent this toolkit is bound to (if any)
      */
@@ -55,8 +59,9 @@ export declare abstract class Toolkit<TContext = UnknownContext> {
  * });
  * ```
  */
-export declare class FunctionToolkit<TContext = UnknownContext> extends Toolkit<TContext> {
+export declare class FunctionToolkit<TContext = UnknownContext> extends BaseToolkit<TContext> {
     readonly id: string;
+    readonly description: string;
     private tools;
     /**
      * Create a new function toolkit.
@@ -79,8 +84,13 @@ export declare class FunctionToolkit<TContext = UnknownContext> extends Toolkit<
      */
     list(context?: Context<TContext>): Promise<Tool<TContext>[]>;
 }
-export declare class MCPToolkit<TContext = UnknownContext> extends Toolkit<TContext> {
+/**
+ * Convenience alias for FunctionToolkit - the default toolkit implementation.
+ */
+export { FunctionToolkit as Toolkit };
+export declare class MCPToolkit<TContext = UnknownContext> extends BaseToolkit<TContext> {
     readonly id: string;
+    readonly description: string;
     private server;
     private cache;
     private filter;

package/dist/tool/toolkit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../../src/tool/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;AAC9B,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,8BAAsB,OAAO,CAAC,QAAQ,GAAG,cAAc;IACrD;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAEvC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,IAAI;IAIvC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAEpD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAErE;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe,CAC1B,QAAQ,GAAG,cAAc,CACzB,SAAQ,OAAO,CAAC,QAAQ,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,KAAK,CAA8B;IAE3C;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC;IAMnD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;CAGnE;AAiCD,qBAAa,UAAU,CAAC,QAAQ,GAAG,cAAc,CAAE,SAAQ,OAAO,CAAC,QAAQ,CAAC;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAA0B;IAExC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IAQ9C;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IA+BlE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}
+{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../../src/tool/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;AAC9B,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,8BAAsB,WAAW,CAAC,QAAQ,GAAG,cAAc;IACzD;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAEvC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,IAAI;IAIvC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAEpD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAErE;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe,CAC1B,QAAQ,GAAG,cAAc,CACzB,SAAQ,WAAW,CAAC,QAAQ,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,KAAK,CAA8B;IAE3C;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC;IAOnD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;CAGnE;AAED;;GAEG;AACH,OAAO,EAAE,eAAe,IAAI,OAAO,EAAE,CAAC;AAiCtC,qBAAa,UAAU,CACrB,QAAQ,GAAG,cAAc,CACzB,SAAQ,WAAW,CAAC,QAAQ,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAA0B;IAExC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IAS9C;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IA+BlE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}

package/dist/tool/toolkit.js

@@ -6,7 +6,7 @@ import { filter } from "@kernl-sdk/shared/lib";
  * Toolkits can be static (FunctionToolkit) or dynamic (MCPToolkit), and provide
  * a unified interface for tool discovery and management.
  */
-export class Toolkit {
+export class BaseToolkit {
     /**
      * The agent this toolkit is bound to (if any)
      */
@@ -38,8 +38,9 @@ export class Toolkit {
  * });
  * ```
  */
-export class FunctionToolkit extends Toolkit {
+export class FunctionToolkit extends BaseToolkit {
     id;
+    description;
     tools;
     /**
      * Create a new function toolkit.
@@ -49,6 +50,7 @@ export class FunctionToolkit extends Toolkit {
     constructor(config) {
         super();
         this.id = config.id;
+        this.description = config.description ?? "";
         this.tools = new Map(config.tools.map((t) => [t.id, t]));
     }
     /**
@@ -70,6 +72,10 @@ export class FunctionToolkit extends Toolkit {
         return Array.from(this.tools.values());
     }
 }
+/**
+ * Convenience alias for FunctionToolkit - the default toolkit implementation.
+ */
+export { FunctionToolkit as Toolkit };
 /*
  * A toolkit that wraps an MCP server and provides tools from it.
  *
@@ -101,8 +107,9 @@ export class FunctionToolkit extends Toolkit {
  * });
  * ```
  */
-export class MCPToolkit extends Toolkit {
+export class MCPToolkit extends BaseToolkit {
     id;
+    description;
     server;
     cache;
     filter;
@@ -116,6 +123,7 @@ export class MCPToolkit extends Toolkit {
     constructor(config) {
         super();
         this.id = config.id;
+        this.description = config.description ?? "";
         this.server = config.server;
         this.filter = config.filter ?? (() => true);
         this.cache = new Map();

package/dist/tool/types.d.ts

@@ -96,6 +96,10 @@ export interface FunctionToolkitConfig<TContext = UnknownContext> {
      * Unique identifier for this toolkit.
      */
     id: string;
+    /**
+     * Optional description of what this toolkit provides.
+     */
+    description?: string;
     /**
      * Array of tools to include in this toolkit.
      */
@@ -109,6 +113,10 @@ export interface MCPToolkitConfig<TContext = UnknownContext> {
      * Unique identifier for this toolkit.
      */
     id: string;
+    /**
+     * Optional description of what this toolkit provides.
+     */
+    description?: string;
     /**
      * The MCP server instance to wrap.
      */

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

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

package/dist/types/agent.d.ts

@@ -2,7 +2,7 @@ import { type ZodType } from "zod";
 import { Context, UnknownContext } from "../context";
 import { LanguageModel, LanguageModelRequestSettings } from "@kernl-sdk/protocol";
 import { InputGuardrail, OutputGuardrail } from "../guardrail";
-import { Toolkit } from "../tool";
+import { BaseToolkit } from "../tool";
 import { TextResponse } from "./thread";
 /**
  * Configuration for an agent.
@@ -24,18 +24,18 @@ export interface AgentConfig<TContext = UnknownContext, TResponse extends AgentR
      *
      * By default, if not set, the agent will use a default model that throws an error when called.
      */
-    model?: LanguageModel;
+    model: LanguageModel;
     /**
      * Configures model-specific tuning parameters (e.g. temperature, top_p, etc.)
      */
     modelSettings?: LanguageModelRequestSettings;
     /**
      * A list of toolkits the agent can use. Toolkits are collections of related tools
-     * that can be static (FunctionToolkit) or dynamic (MCPToolkit).
+     * that can be static (Toolkit) or dynamic (MCPToolkit).
      *
      * @example
      * ```typescript
-     * const myTools = new FunctionToolkit({
+     * const myTools = new Toolkit({
      *   id: "custom",
      *   tools: [tool1, tool2]
      * });
@@ -52,7 +52,7 @@ export interface AgentConfig<TContext = UnknownContext, TResponse extends AgentR
      * });
      * ```
      */
-    toolkits?: Toolkit<TContext>[];
+    toolkits?: BaseToolkit<TContext>[];
     /**
      * A list of checks that run in parallel to the agent's execution on the input + output for the agent,
      * depending on the configuration.

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAGlD,EAAE,EAAE,MAAM,CAAC;IAGX,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,YAAY,EACR,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;IAe/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAsBzB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAElD;;;OAGG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB;;;OAGG;IACH,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,aAAa,EACb,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAGlD,EAAE,EAAE,MAAM,CAAC;IAGX,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,YAAY,EACR,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;IAe/D;;;;OAIG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAsBzB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAElD;;;OAGG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB;;;OAGG;IACH,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC"}

package/dist/types/thread.d.ts

@@ -1,6 +1,11 @@
-import { ToolCall, LanguageModel, LanguageModelItem, LanguageModelStreamEvent } from "@kernl-sdk/protocol";
+import { ToolCall, LanguageModel, LanguageModelItem, LanguageModelStreamEvent, RUNNING, STOPPED, INTERRUPTIBLE, UNINTERRUPTIBLE, ZOMBIE, DEAD } from "@kernl-sdk/protocol";
 import { Task } from "../task";
 import { Context } from "../context";
+export type TextResponse = "text";
+/**
+ * Thread state discriminated union
+ */
+export type ThreadState = typeof RUNNING | typeof STOPPED | typeof INTERRUPTIBLE | typeof UNINTERRUPTIBLE | typeof ZOMBIE | typeof DEAD;
 /**
  * Thread-specific tool call state for approval workflow.
  * This extends the protocol states for internal thread use.
@@ -23,19 +28,6 @@ export type ThreadStreamEvent = LanguageModelStreamEvent;
 export interface ActionSet {
     toolCalls: ToolCall[];
 }
-/**
- * Result of a single tick of execution
- */
-export interface TickResult {
-    /**
-     * Events to add to thread history
-     */
-    events: ThreadEvent[];
-    /**
-     * Action intentions that need to be performed as a result of this tick
-     */
-    intentions: ActionSet | null;
-}
 /**
  * Result of performing actions, including both executed results and pending approvals
  */
@@ -64,8 +56,10 @@ export interface ThreadExecuteResult<TResponse = any> {
 }
 export interface ThreadOptions<TContext> {
     context: Context<TContext>;
-    task?: Task<TContext>;
     model?: LanguageModel;
+    task?: Task<TContext>;
+    threadId?: string;
+    maxTicks?: number;
+    abort?: AbortSignal;
 }
-export type TextResponse = "text";
 //# sourceMappingURL=thread.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/types/thread.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,QAAQ,EAAE,CAAC;CAEvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB;;OAEG;IACH,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB;;OAEG;IACH,gBAAgB,EAAE,QAAQ,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,GAAG;IAClD;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,GAAG,CAAC;CACZ;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ;IACrC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC"}
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/types/thread.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,OAAO,EACP,OAAO,EACP,aAAa,EACb,eAAe,EACf,MAAM,EACN,IAAI,EACL,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,OAAO,OAAO,GACd,OAAO,OAAO,GACd,OAAO,aAAa,GACpB,OAAO,eAAe,GACtB,OAAO,MAAM,GACb,OAAO,IAAI,CAAC;AAEhB;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,QAAQ,EAAE,CAAC;CAEvB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB;;OAEG;IACH,gBAAgB,EAAE,QAAQ,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,GAAG;IAClD;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,GAAG,CAAC;CACZ;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ;IACrC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;CAGrB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kernl",
-  "version": "0.1.3",
-  "description": "A modern AI agent framework with MCP integration",
+  "version": "0.2.0",
+  "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
     "ai",
@@ -31,14 +31,16 @@
     "@modelcontextprotocol/sdk": "^1.20.2",
     "pino": "^9.6.0",
     "zod": "^4.1.12",
-    "@kernl-sdk/protocol": "0.1.1",
+    "@kernl-sdk/protocol": "0.2.0",
     "@kernl-sdk/shared": "^0.1.1"
   },
   "devDependencies": {
+    "@ai-sdk/openai": "3.0.0-beta.57",
     "@types/node": "^24.10.0",
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
-    "vitest": "^4.0.8"
+    "vitest": "^4.0.8",
+    "@kernl-sdk/ai": "0.1.1"
   },
   "scripts": {
     "build": "tsc && tsc-alias",

package/src/agent.ts

@@ -1,16 +1,27 @@
-import { LanguageModel, LanguageModelRequestSettings } from "@kernl-sdk/protocol";
+import {
+  LanguageModel,
+  LanguageModelRequestSettings,
+  message,
+} from "@kernl-sdk/protocol";
 
 import type { Context, UnknownContext } from "./context";
 import { InputGuardrail, OutputGuardrail } from "./guardrail";
 import { AgentHooks } from "./lifecycle";
-import { Toolkit } from "./tool/toolkit";
+import { BaseToolkit } from "./tool/toolkit";
 import { Tool } from "./tool";
-// import { DEFAULT_LANGUAGE_MODEL } from "@/providers/default";
+import { Thread } from "./thread";
 
 import { MisconfiguredError } from "./lib/error";
 
 import type { AgentConfig, AgentResponseType } from "./types/agent";
-import { TextResponse } from "./types/thread";
+import type {
+  TextResponse,
+  ThreadOptions,
+  ThreadExecuteResult,
+  ThreadStreamEvent,
+} from "./types/thread";
+import type { Kernl } from "./kernl";
+import type { ResolvedAgentResponse } from "./guardrail";
 
 export class Agent<
     TContext = UnknownContext,
@@ -19,13 +30,22 @@ export class Agent<
   extends AgentHooks<TContext, TResponse>
   implements AgentConfig<TContext, TResponse>
 {
+  private kernl?: Kernl;
+
   id: string;
   name: string;
   instructions: (context: Context<TContext>) => Promise<string> | string;
 
   model: LanguageModel;
   modelSettings: LanguageModelRequestSettings;
-  toolkits: Toolkit<TContext>[];
+  toolkits: BaseToolkit<TContext>[];
+  guardrails: {
+    input: InputGuardrail[];
+    output: OutputGuardrail<AgentResponseType>[];
+  };
+  responseType: TResponse = "text" as TResponse;
+  resetToolChoice: boolean;
+  // toolUseBehavior: ToolUseBehavior; (TODO)
 
   // --- (TODO) ---
   // handoffDescription: string; // ??
@@ -35,36 +55,11 @@ export class Agent<
   // /* 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. */
+  //
+  //  /* 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;
 
-  guardrails: {
-    input: InputGuardrail[];
-    output: OutputGuardrail<AgentResponseType>[];
-  };
-  responseType: TResponse = "text" as TResponse;
-  resetToolChoice: boolean;
-  // toolUseBehavior: ToolUseBehavior; (TODO)
-
-  // /**
-  //  * Create an Agent with handoffs and automatically infer the union type for TResponse from the handoff agents' response types.
-  //  */
-  // static create<
-  //   TResponse extends AgentResponseType = TextResponse,
-  //   Handoffs extends readonly (Agent<any, any> | Handoff<any, any>)[] = [],
-  // >(
-  //   config: AgentConfigWithHandoffs<TResponse, Handoffs>,
-  // ): Agent<UnknownContext, TResponse | HandoffsOutputUnion<Handoffs>> {
-  //   return new Agent<UnknownContext, TResponse | HandoffsOutputUnion<Handoffs>>(
-  //     {
-  //       ...config,
-  //       handoffs: config.handoffs as any,
-  //       responseType: config.responseType,
-  //       handoffresponseTypeWarningEnabled: false,
-  //     },
-  //   );
-  // }
-
   constructor(config: AgentConfig<TContext, TResponse>) {
     super();
     if (config.id.trim() === "") {
@@ -76,7 +71,7 @@ export class Agent<
       typeof config.instructions === "function"
         ? config.instructions
         : () => config.instructions as string;
-    this.model = config.model as LanguageModel; // TODO: Add default model
+    this.model = config.model; // (TODO): include optional default setting for convenience like env.DEFAULT_LLM = "gpt-5"
     this.modelSettings = config.modelSettings ?? {};
 
     this.toolkits = config.toolkits ?? [];
@@ -95,30 +90,82 @@ export class Agent<
     // this.handoffs = config.handoffs ?? [];
 
     // --- Runtime warning for handoff response type compatibility ---
-    // if (
-    //   config.handoffresponseTypeWarningEnabled === undefined ||
-    //   config.handoffresponseTypeWarningEnabled
-    // ) {
-    //   if (this.handoffs && this.responseType) {
-    //     const responseTypes = new Set<string>([
-    //       JSON.stringify(this.responseType),
-    //     ]);
-    //     for (const h of this.handoffs) {
-    //       if ("responseType" in h && h.responseType) {
-    //         responseTypes.add(JSON.stringify(h.responseType));
-    //       } else if ("agent" in h && h.agent.responseType) {
-    //         responseTypes.add(JSON.stringify(h.agent.responseType));
-    //       }
-    //     }
+    // if (config.handoffresponseTypeWarningEnabled) {
+    //     ...
     //     if (responseTypes.size > 1) {
     //       logger.warn(
-    //         `[Agent] Warning: Handoff agents have different response types: ${Array.from(responseTypes).join(", ")}. You can make it type-safe by using Agent.create({ ... }) method instead.`,
+    //         `[Agent] Warning: Handoff agents have different response types: ${Array.from(responseTypes).join(", ")}.
+    //          You can make it type-safe by using Agent.create({ ... }) method instead.`,
     //       );
     //     }
     //   }
     // }
   }
 
+  /**
+   * Bind this agent to a kernl instance. Called by kernl.register().
+   */
+  bind(kernl: Kernl): void {
+    this.kernl = kernl;
+  }
+
+  /**
+   * Blocking execution - spawns or resumes thread and waits for completion
+   */
+  async run(
+    instructions: string,
+    options?: ThreadOptions<TContext>,
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+    if (!this.kernl) {
+      throw new MisconfiguredError(
+        `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
+      );
+    }
+
+    const m = message({ role: "user", text: instructions });
+    const tid = options?.threadId;
+
+    // NOTE: may end up moving this to the kernl
+    let thread = tid ? this.kernl.threads.get(tid) : null;
+    if (!thread) {
+      thread = new Thread(this.kernl, this, [m], options);
+      return this.kernl.spawn(thread);
+    }
+
+    thread.append(m);
+    return this.kernl.schedule(thread);
+  }
+
+  /**
+   * Streaming execution - spawns or resumes thread and returns async iterator
+   *
+   * NOTE: streaming probably won't make sense in scheduling contexts so spawnStream etc. won't make sense
+   */
+  async *stream(
+    instructions: string,
+    options?: ThreadOptions<TContext>,
+  ): AsyncIterable<ThreadStreamEvent> {
+    if (!this.kernl) {
+      throw new MisconfiguredError(
+        `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
+      );
+    }
+
+    const m = message({ role: "user", text: instructions });
+    const tid = options?.threadId;
+
+    // NOTE: may end up moving this to the kernl
+    let thread = tid ? this.kernl.threads.get(tid) : null;
+    if (!thread) {
+      thread = new Thread(this.kernl, this, [m], options);
+      yield* this.kernl.spawnStream(thread);
+      return;
+    }
+
+    thread.append(m);
+    yield* this.kernl.scheduleStream(thread);
+  }
+
   /**
    * Get a specific tool by ID from all toolkits.
    *
@@ -164,40 +211,4 @@ export class Agent<
 
     return allTools;
   }
-
-  // async run<TContext>(
-  //   input: string,
-  //   options: SharedRunOptions<TContext>,
-  // ): Promise<RunResult<TContext>> {
-  //   // TODO
-  //   // ...
-  // }
-
-  // async stream<TContext>(
-  //   input: string,
-  //   options: StreamOptions<TContext>,
-  // ): Promise<StreamedRunResult<TContext>> {
-  //   // TODO
-  //   // ...
-  // }
-  //
-
-  // ----------------------
-  // Events
-  // ----------------------
-
-  // on(event: any, handler: Function): void {
-  //   // TODO
-  //   // ...
-  // }
-
-  // once(event: any, handler: Function): void {
-  //   // TODO
-  //   // ...
-  // }
-
-  // off(event: any, handler: Function): void {
-  //   // TODO
-  //   // ...
-  // }
 }

package/src/index.ts

@@ -1,4 +1,4 @@
 export { Kernl } from "./kernl";
 export { Agent } from "./agent";
 export type { Context } from "./context";
-export { tool, FunctionToolkit, MCPToolkit } from "./tool";
+export { tool, Toolkit, FunctionToolkit, MCPToolkit } from "./tool";

package/src/kernl.ts

@@ -1,22 +1,71 @@
 import { Agent } from "./agent";
 import { UnknownContext } from "./context";
 import { KernlHooks } from "./lifecycle";
+import type { Thread } from "./thread";
 
 import type { AgentResponseType } from "./types/agent";
+import type { ThreadExecuteResult, ThreadStreamEvent } from "./types/thread";
+import type { ResolvedAgentResponse } from "./guardrail";
 
 /**
- * Central coordinator for the entire application.
+ * The kernl - manages agent processes, scheduling, and task lifecycle
  *
  * 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();
+  threads: Map<string, Thread<any, any>> = new Map();
 
   /**
    * Registers a new agent with the kernl instance.
    */
   register(agent: Agent): void {
-    // TODO: Implement agent registration
+    this.agents.set(agent.id, agent);
+    agent.bind(this);
+  }
+
+  /**
+   * Spawn a new thread - blocking execution
+   */
+  async spawn<TContext, TResponse extends AgentResponseType>(
+    thread: Thread<TContext, TResponse>,
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+    this.threads.set(thread.id, thread);
+    return await thread.execute();
+  }
+
+  /**
+   * Schedule an existing thread - blocking execution
+   *
+   * NOTE: just blocks for now
+   */
+  async schedule<TContext, TResponse extends AgentResponseType>(
+    thread: Thread<TContext, TResponse>,
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+    return await thread.execute();
+  }
+
+  /**
+   * (TMP) - probably won't make sense with assync scheduling contexts
+   *
+   * Spawn a new thread - streaming execution
+   */
+  async *spawnStream<TContext, TResponse extends AgentResponseType>(
+    thread: Thread<TContext, TResponse>,
+  ): AsyncIterable<ThreadStreamEvent> {
+    this.threads.set(thread.id, thread);
+    yield* thread.stream();
+  }
+
+  /**
+   * (TMP) - probably won't make sense with assync scheduling contexts
+   *
+   * Schedule an existing thread - streaming execution
+   */
+  async *scheduleStream<TContext, TResponse extends AgentResponseType>(
+    thread: Thread<TContext, TResponse>,
+  ): AsyncIterable<ThreadStreamEvent> {
+    yield* thread.stream();
   }
 }