kernl 0.8.4 → 0.9.0

package/src/agent.ts

@@ -6,7 +6,6 @@ import {
 } from "@kernl-sdk/protocol";
 
 import { Thread } from "./thread";
-import type { Kernl } from "./kernl";
 import type {
   RThreadsListParams,
   RThreadCreateParams,
@@ -15,30 +14,16 @@ import type {
   RThreadUpdateParams,
 } from "@/api/resources/threads/types";
 import type { Context, UnknownContext } from "./context";
-import { Tool, memory } from "./tool";
-import { BaseToolkit } from "./tool/toolkit";
 import {
   InputGuardrail,
   OutputGuardrail,
   type ResolvedAgentResponse,
 } from "./guardrail";
-import { AgentHooks } from "./lifecycle";
-import type {
-  AgentMemoryCreate,
-  AgentMemoryUpdate,
-  MemoryListOptions,
-  MemorySearchQuery,
-} from "./memory";
+import { BaseAgent } from "./agent/base";
 
-import { randomID } from "@kernl-sdk/shared/lib";
 import { MisconfiguredError, RuntimeError } from "./lib/error";
 
-/* types */
-import type {
-  AgentConfig,
-  AgentMemoryConfig,
-  AgentOutputType,
-} from "./agent/types";
+import type { AgentConfig, AgentOutputType } from "./agent/types";
 import type {
   TextOutput,
   ThreadExecuteOptions,
@@ -50,74 +35,30 @@ export class Agent<
     TContext = UnknownContext,
     TOutput extends AgentOutputType = TextOutput,
   >
-  extends AgentHooks<TContext, TOutput>
+  extends BaseAgent<TContext, TOutput>
   implements AgentConfig<TContext, TOutput>
 {
-  private kernl?: Kernl;
-
-  id: string;
-  name: string;
-  description?: string;
-  instructions: (context: Context<TContext>) => Promise<string> | string;
+  readonly kind = "llm";
+  readonly model: LanguageModel;
+  readonly modelSettings: LanguageModelRequestSettings;
 
-  model: LanguageModel;
-  modelSettings: LanguageModelRequestSettings;
-  // actions: ActionSet; /* TODO */
-  toolkits: BaseToolkit<TContext>[];
-  systools: BaseToolkit<TContext>[];
-  memory: AgentMemoryConfig;
-
-  guardrails: {
+  readonly guardrails: {
     input: InputGuardrail[];
     output: OutputGuardrail<AgentOutputType>[];
   };
-  output: TOutput = "text" as TOutput;
-  resetToolChoice: boolean;
+  readonly output: TOutput = "text" as TOutput;
+  readonly resetToolChoice: boolean;
 
   constructor(config: AgentConfig<TContext, TOutput>) {
-    super();
-    if (config.id.trim() === "") {
-      throw new MisconfiguredError("Agent must have an id.");
-    }
-    this.id = config.id;
-    this.name = config.name;
-    this.description = config.description;
-    this.instructions =
-      typeof config.instructions === "function"
-        ? config.instructions
-        : () => config.instructions as string;
-    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 ?? [];
-    this.systools = [];
-    this.memory = config.memory ?? { enabled: false };
-
-    for (const toolkit of this.toolkits) {
-      toolkit.bind(this);
-    }
+    super(config);
 
+    this.model = config.model;
+    this.modelSettings = config.modelSettings ?? {};
     this.guardrails = config.guardrails ?? { input: [], output: [] };
     if (config.output) {
       this.output = config.output;
     }
     this.resetToolChoice = config.resetToolChoice ?? true;
-    // this.toolUseBehavior = config.toolUseBehavior ?? "run_llm_again";
-  }
-
-  /**
-   * Bind this agent to a kernl instance. Called by kernl.register().
-   */
-  bind(kernl: Kernl): void {
-    this.kernl = kernl;
-
-    // initialize system toolkits
-    if (this.memory.enabled) {
-      // safety: system tools only rely on ctx.agent, not ctx.context
-      const toolkit = memory as unknown as BaseToolkit<TContext>;
-      this.systools.push(toolkit);
-      toolkit.bind(this);
-    }
   }
 
   /**
@@ -241,60 +182,6 @@ export class Agent<
     yield* this.kernl.scheduleStream(thread);
   }
 
-  /**
-   * @internal
-   *
-   * Get a specific tool by ID from systools and toolkits.
-   *
-   * @param id The tool ID to look up
-   * @returns The tool if found, undefined otherwise
-   */
-  tool(id: string): Tool<TContext> | undefined {
-    // Check systools first
-    for (const toolkit of this.systools) {
-      const tool = toolkit.get(id);
-      if (tool) return tool;
-    }
-    // Then user toolkits
-    for (const toolkit of this.toolkits) {
-      const tool = toolkit.get(id);
-      if (tool) return tool;
-    }
-    return undefined;
-  }
-
-  /**
-   * @internal
-   *
-   * Get all tools available from systools and toolkits for the given context.
-   * Checks for duplicate tool IDs across toolkits and throws an error if found.
-   *
-   * (TODO): Consider returning toolkits alongside tools so we can serialize them
-   * together and give agents more options for dealing with tool groups.
-   *
-   * @param context The context to use for filtering tools
-   * @returns Array of all available tools
-   * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
-   */
-  async tools(context: Context<TContext>): Promise<Tool<TContext>[]> {
-    const all: Tool<TContext>[] = [];
-
-    for (const toolkit of [...this.systools, ...this.toolkits]) {
-      all.push(...(await toolkit.list(context)));
-    }
-
-    const ids = all.map((t) => t.id);
-    const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
-
-    if (duplicates.length > 0) {
-      throw new MisconfiguredError(
-        `Duplicate tool IDs found: ${[...new Set(duplicates)].join(", ")}`,
-      );
-    }
-
-    return all;
-  }
-
   /**
    * Thread management scoped to this agent.
    *
@@ -331,110 +218,4 @@ export class Agent<
         kthreads.update(tid, patch),
     };
   }
-
-  /**
-   * Memory management scoped to this agent.
-   *
-   * Provides a simplified API for creating memories with:
-   * - Auto-generated IDs
-   * - Flattened scope fields (namespace, entityId) - agentId is implicit
-   * - Default kind of "semantic"
-   *
-   * @example
-   * ```ts
-   * await agent.memories.create({
-   *   namespace: "user-123",
-   *   collection: "preferences",
-   *   content: { text: "User prefers TypeScript" },
-   * });
-   * ```
-   */
-  get memories() {
-    if (!this.kernl) {
-      throw new MisconfiguredError(
-        `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
-      );
-    }
-
-    const agentId = this.id;
-    const kmem = this.kernl.memories;
-
-    return {
-      /**
-       * List memories scoped to this agent.
-       */
-      list: (
-        params?: Omit<MemoryListOptions, "filter"> & {
-          collection?: string;
-          limit?: number;
-          // (TODO): we might want to add the filter back here
-        },
-      ) =>
-        kmem.list({
-          filter: {
-            scope: { agentId },
-            collections: params?.collection ? [params.collection] : undefined,
-          },
-          limit: params?.limit,
-        }),
-
-      /**
-       * Create a new memory scoped to this agent.
-       */
-      create: (params: AgentMemoryCreate) =>
-        kmem.create({
-          id: params.id ?? `mem_${randomID()}`,
-          scope: {
-            namespace: params.namespace,
-            entityId: params.entityId,
-            agentId,
-          },
-          kind: "semantic",
-          collection: params.collection,
-          content: params.content,
-          wmem: params.wmem,
-          smem: params.smem,
-          timestamp: params.timestamp,
-          metadata: params.metadata,
-        }),
-
-      /**
-       * Update an existing memory scoped to this agent.
-       */
-      update: (params: AgentMemoryUpdate) =>
-        kmem.update({
-          id: params.id,
-          content: params.content,
-          collection: params.collection,
-          wmem: params.wmem,
-          smem: params.smem,
-          metadata: params.metadata,
-        }),
-
-      /**
-       * Search memories scoped to this agent.
-       */
-      search: (
-        params: Omit<MemorySearchQuery, "filter"> & {
-          // (TODO): is this correct?
-          filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
-            scope?: Omit<
-              NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>,
-              "agentId"
-            >;
-          };
-        },
-      ) =>
-        kmem.search({
-          ...params,
-          filter: {
-            ...params.filter,
-            scope: {
-              ...params.filter?.scope,
-              agentId,
-            },
-          },
-        }),
-    };
-  }
 }

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

@@ -1,4 +1,5 @@
-import type { Agent } from "@/agent";
+import { Agent } from "@/agent";
+import type { BaseAgent } from "@/agent/base";
 import type { AgentOutputType } from "@/agent/types";
 import type { UnknownContext } from "@/context";
 import type { TextOutput } from "@/thread/types";
@@ -9,13 +10,19 @@ import type { TextOutput } from "@/thread/types";
  * Thin facade over the in-process agent registry, returning live Agent instances.
  *
  * Note: agents are code, not persisted data; this is process-local.
+ *
+ * Currently only exposes LLM agents (kind: "llm"). RealtimeAgents are stored
+ * in the internal registry but not returned by these methods. If public access
+ * to realtime agents is needed, add a separate `kernl.realtimeAgents` resource.
  */
 export class RAgents {
-  constructor(private readonly registry: Map<string, Agent>) {}
+  constructor(private readonly registry: Map<string, BaseAgent>) {}
 
   /**
    * Get a live Agent instance by id.
    *
+   * Only returns LLM agents. Returns undefined for realtime agents.
+   *
    * Callers are expected to know the concrete TContext/TOutput types
    * for their own agents and can specify them via generics.
    */
@@ -24,27 +31,26 @@ export class RAgents {
     TOutput extends AgentOutputType = TextOutput,
   >(id: string): Agent<TContext, TOutput> | undefined {
     const agent = this.registry.get(id);
-    return agent as Agent<TContext, TOutput> | undefined;
+    if (agent?.kind === "llm") {
+      return agent as Agent<TContext, TOutput>;
+    }
+    return undefined;
   }
 
   /**
-   * Check if an agent with the given id is registered.
+   * Check if an LLM agent with the given id is registered.
    */
   has(id: string): boolean {
-    return this.registry.has(id);
+    return this.registry.get(id)?.kind === "llm";
   }
 
   /**
-   * List all registered agents as live instances.
-   *
-   * Since this is a heterogeneous collection, we expose the widest safe
-   * type parameters here.
+   * List all registered LLM agents as live instances.
    */
   list(): Agent<UnknownContext, AgentOutputType>[] {
-    return Array.from(this.registry.values()) as Agent<
-      UnknownContext,
-      AgentOutputType
-    >[];
+    return Array.from(this.registry.values()).filter(
+      (a): a is Agent<UnknownContext, AgentOutputType> => a.kind === "llm",
+    );
   }
 
   /**

package/src/kernl/kernl.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel } from "@kernl-sdk/protocol";
 import { resolveEmbeddingModel } from "@kernl-sdk/retrieval";
 
-import { Agent } from "@/agent";
+import { BaseAgent } from "@/agent/base";
 import { UnknownContext } from "@/context";
 import { KernlHooks } from "@/lifecycle";
 import type { Thread } from "@/thread";
@@ -29,7 +29,7 @@ import type { KernlOptions, MemoryOptions, StorageOptions } from "./types";
  * tracing.
  */
 export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
-  private readonly _agents: Map<string, Agent> = new Map();
+  private readonly _agents: Map<string, BaseAgent> = new Map();
   private readonly _models: Map<string, LanguageModel> = new Map();
 
   readonly storage: KernlStorage;
@@ -64,7 +64,7 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
   /**
    * Registers a new agent with the kernl instance.
    */
-  register(agent: Agent): void {
+  register(agent: BaseAgent): void {
     this._agents.set(agent.id, agent);
     agent.bind(this);
 
@@ -87,12 +87,12 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
       }
     }
 
-    // (TODO): implement exhaustive model registry in protocol/ package
-    //
-    // auto-populate model registry for storage hydration
-    const key = `${agent.model.provider}/${agent.model.modelId}`;
-    if (!this._models.has(key)) {
-      this._models.set(key, agent.model);
+    // auto-populate model registry for storage hydration (llm agents only - for now)
+    if (agent.kind === "llm") {
+      const key = `${agent.model.provider}/${agent.model.modelId}`;
+      if (!this._models.has(key)) {
+        this._models.set(key, agent.model as LanguageModel);
+      }
     }
   }
 

package/src/kernl/types.ts

@@ -1,7 +1,7 @@
 import { LanguageModel, EmbeddingModel } from "@kernl-sdk/protocol";
 import { SearchIndex } from "@kernl-sdk/retrieval";
 
-import { Agent } from "@/agent";
+import { BaseAgent } from "@/agent/base";
 import { KernlStorage } from "@/storage";
 
 /**
@@ -87,10 +87,10 @@ export interface KernlOptions {
 /**
  * Agent registry interface.
  *
- * Satisfied by Map<string, Agent>.
+ * Satisfied by Map<string, BaseAgent>.
  */
 export interface AgentRegistry {
-  get(id: string): Agent<any> | undefined;
+  get(id: string): BaseAgent<any> | undefined;
 }
 
 /**

package/src/mcp/__tests__/utils.test.ts

@@ -63,7 +63,7 @@ describe("mcpToFunctionTool", () => {
     expect(functionTool.parameters).toBeDefined();
   });
 
-  it("should handle tools without inputSchema (undefined parameters)", () => {
+  it("should handle tools without inputSchema (empty object parameters)", () => {
     const server = createMockServer();
     // In practice, MCP SDK tools require inputSchema, but our function handles
     // the case where it might not be present. We use 'as any' to test this edge case.
@@ -75,7 +75,9 @@ describe("mcpToFunctionTool", () => {
     const functionTool = mcpToFunctionTool(server, mcpTool);
 
     expect(functionTool.id).toBe("no_params");
-    expect(functionTool.parameters).toBeUndefined();
+    // When no inputSchema, we use an empty z.object({}) to match AI SDK behavior
+    expect(functionTool.parameters).toBeDefined();
+    expect(functionTool.parameters?.def.type).toBe("object");
   });
 
   it("should invoke server.callTool with correct params", async () => {

package/src/mcp/utils.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 import { UnknownContext } from "@/context";
-import { tool } from "@/tool";
+import { tool } from "@/tool/tool";
 
 import { MCPServer } from "./base";
 import type { MCPTool, MCPToolFilter } from "./types";

package/src/realtime/agent.ts

@@ -0,0 +1,24 @@
+import type { RealtimeModel } from "@kernl-sdk/protocol";
+
+import type { UnknownContext } from "@/context";
+import { BaseAgent } from "@/agent/base";
+
+import type { RealtimeAgentConfig, RealtimeAgentVoiceConfig } from "./types";
+
+/**
+ * A realtime agent definition.
+ *
+ * Stateless configuration that describes what a realtime voice agent does.
+ * Create sessions with `new RealtimeSession(agent, options)`.
+ */
+export class RealtimeAgent<TContext = UnknownContext> extends BaseAgent<TContext> {
+  readonly kind = "realtime";
+  readonly model: RealtimeModel;
+  readonly voice?: RealtimeAgentVoiceConfig;
+
+  constructor(config: RealtimeAgentConfig<TContext>) {
+    super(config);
+    this.model = config.model;
+    this.voice = config.voice;
+  }
+}

package/src/realtime/channel.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from "node:events";
+
+/**
+ * Base interface for audio I/O channels.
+ *
+ * Channels bridge between audio sources (browser mic, Twilio, Discord)
+ * and the realtime session. They handle audio capture/playback and emit
+ * events that the session listens to.
+ *
+ * Events emitted:
+ * - 'audio' (audio: string) - Raw audio chunk (base64)
+ * - 'commit' () - User finished speaking (VAD or manual)
+ * - 'interrupt' () - User started speaking mid-response
+ */
+export interface RealtimeChannel extends EventEmitter {
+  /**
+   * Send audio to be played/transmitted by the channel.
+   * Called by session when audio is received from the model.
+   */
+  sendAudio(audio: string): void;
+
+  /**
+   * Interrupt current audio playback.
+   * Called by session when response is cancelled.
+   */
+  interrupt(): void;
+
+  /**
+   * Clean up resources and close the channel.
+   */
+  close(): void;
+}

package/src/realtime/index.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./channel";
+export * from "./agent";
+export * from "./session";