kernl 0.8.3 → 0.9.0

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/__tests__/memory-config.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { LanguageModel, EmbeddingModel } from "@kernl-sdk/protocol";
+import type { SearchIndex } from "@kernl-sdk/retrieval";
+
+import { Kernl } from "../kernl";
+import { Agent } from "@/agent";
+import { logger } from "@/lib/logger";
+
+function createMockLanguageModel(): LanguageModel {
+  return {
+    spec: "1.0" as const,
+    provider: "test",
+    modelId: "test-model",
+  } as unknown as LanguageModel;
+}
+
+function createMockEmbeddingModel(): EmbeddingModel<string> {
+  return {
+    provider: "test",
+    modelId: "test-embedder",
+    embed: vi.fn(async ({ values }: { values: string[] }) => ({
+      embeddings: values.map((v) => [v.length, 0, 0]),
+    })),
+  } as unknown as EmbeddingModel<string>;
+}
+
+function createMockVectorIndex(): SearchIndex {
+  return {
+    id: "mock",
+    capabilities: () => ({
+      namespacing: false,
+      filtering: { basic: true },
+      hybrid: false,
+    }),
+    createIndex: vi.fn(),
+    deleteIndex: vi.fn(),
+    upsert: vi.fn(),
+    query: vi.fn(),
+    delete: vi.fn(),
+  } as unknown as SearchIndex;
+}
+
+describe("Kernl memory config warnings", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(logger, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it("warns when agent enables memory but no embedding configured", () => {
+    const kernl = new Kernl({
+      storage: {
+        vector: createMockVectorIndex(),
+      },
+      // no memory.embedding
+    });
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test Agent",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      memory: { enabled: true },
+    });
+
+    kernl.register(agent);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Embeddings are not configured"),
+    );
+  });
+
+  it("warns when agent enables memory but no vector storage configured", () => {
+    const kernl = new Kernl({
+      memory: {
+        embedding: createMockEmbeddingModel(),
+      },
+      // no storage.vector
+    });
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test Agent",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      memory: { enabled: true },
+    });
+
+    kernl.register(agent);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No vector storage configured"),
+    );
+  });
+
+  it("warns for both missing embedding and vector storage", () => {
+    const kernl = new Kernl({});
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test Agent",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      memory: { enabled: true },
+    });
+
+    kernl.register(agent);
+
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Embeddings are not configured"),
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No vector storage configured"),
+    );
+  });
+
+  it("warns only once across multiple agents", () => {
+    const kernl = new Kernl({});
+
+    const agent1 = new Agent({
+      id: "agent-1",
+      name: "Agent 1",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      memory: { enabled: true },
+    });
+
+    const agent2 = new Agent({
+      id: "agent-2",
+      name: "Agent 2",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      memory: { enabled: true },
+    });
+
+    kernl.register(agent1);
+    kernl.register(agent2);
+
+    // Should only warn twice total (once for embedding, once for vector)
+    // not four times (twice per agent)
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not warn when memory config is complete", () => {
+    const kernl = new Kernl({
+      storage: {
+        vector: createMockVectorIndex(),
+      },
+      memory: {
+        embedding: createMockEmbeddingModel(),
+      },
+    });
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test Agent",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      memory: { enabled: true },
+    });
+
+    kernl.register(agent);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not warn when agent does not enable memory", () => {
+    const kernl = new Kernl({});
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test Agent",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      memory: { enabled: false },
+    });
+
+    kernl.register(agent);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not warn when agent has no memory config", () => {
+    const kernl = new Kernl({});
+
+    const agent = new Agent({
+      id: "test-agent",
+      name: "Test Agent",
+      instructions: "test",
+      model: createMockLanguageModel(),
+      // no memory config at all
+    });
+
+    kernl.register(agent);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

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";
@@ -16,10 +16,11 @@ import {
   buildMemoryIndexSchema,
 } from "@/memory";
 
+import { logger } from "@/lib/logger";
+
 import type { ThreadExecuteResult, ThreadStreamEvent } from "@/thread/types";
 import type { AgentOutputType } from "@/agent/types";
-
-import type { KernlOptions } from "./types";
+import type { KernlOptions, MemoryOptions, StorageOptions } from "./types";
 
 /**
  * The kernl - manages agent processes, scheduling, and task lifecycle.
@@ -28,12 +29,20 @@ import type { KernlOptions } 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;
   athreads: Map<string, Thread<any, any>> = new Map(); /* active threads */
 
+  private readonly _memopts: MemoryOptions | undefined;
+  private readonly _storopts: StorageOptions | undefined;
+
+  private warnings = {
+    embedding: false, // "Embeddings are not configured. If you want memories to auto-embed text content..."
+    vector: false, // "No vector storage configured. The memories.search() function will not be..."
+  }; /* tracks warnings that have been logged */
+
   // --- public API ---
   readonly threads: RThreads;
   readonly agents: RAgents;
@@ -41,53 +50,49 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
 
   constructor(options: KernlOptions = {}) {
     super();
+
+    this._memopts = options.memory;
+    this._storopts = options.storage;
+
     this.storage = options.storage?.db ?? new InMemoryStorage();
     this.storage.bind({ agents: this._agents, models: this._models });
     this.threads = new RThreads(this.storage.threads);
     this.agents = new RAgents(this._agents);
-
-    // initialize memory
-    const embeddingModel =
-      options.memory?.embeddingModel ?? "openai/text-embedding-3-small";
-    const embedder =
-      typeof embeddingModel === "string"
-        ? resolveEmbeddingModel<string>(embeddingModel)
-        : embeddingModel;
-    const encoder = new MemoryByteEncoder(embedder);
-
-    const vector = options.storage?.vector;
-    const indexId = options.memory?.indexId ?? "memories_sindex";
-    const dimensions = options.memory?.dimensions ?? 1536;
-    const providerOptions = options.memory?.indexProviderOptions ?? { schema: "kernl" };
-
-    this.memories = new Memory({
-      store: this.storage.memories,
-      search:
-        vector !== undefined
-          ? new MemoryIndexHandle({
-              index: vector,
-              indexId,
-              schema: buildMemoryIndexSchema({ dimensions }),
-              providerOptions,
-            })
-          : undefined,
-      encoder,
-    });
+    this.memories = this.initializeMemory();
   }
 
   /**
    * 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);
 
-    // (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);
+    // memory config warnings (log once)
+    if (agent.memory.enabled) {
+      if (!this._memopts?.embedding && !this.warnings.embedding) {
+        logger.warn(
+          "Embeddings are not configured. If you want memories to auto-embed text content, " +
+            "pass an embedding model into the memory config in new Kernl()",
+        );
+        this.warnings.embedding = true;
+      }
+
+      if (!this._storopts?.vector && !this.warnings.vector) {
+        logger.warn(
+          "No vector storage configured. The memories.search() function will not be " +
+            "available. To enable memory search, pass storage.vector in new Kernl()",
+        );
+        this.warnings.vector = true;
+      }
+    }
+
+    // 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);
+      }
     }
   }
 
@@ -152,4 +157,41 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
       this.athreads.delete(thread.tid);
     }
   }
+
+  // --- private utils ---
+
+  /**
+   * @internal
+   *
+   * Initialize the memory system based on the storage + memory configuration.
+   */
+  private initializeMemory(): Memory {
+    const embeddingModel = this._memopts?.embedding;
+    const embedder = embeddingModel
+      ? typeof embeddingModel === "string"
+        ? resolveEmbeddingModel<string>(embeddingModel)
+        : embeddingModel
+      : undefined;
+    const encoder = new MemoryByteEncoder(embedder);
+
+    const vector = this._storopts?.vector;
+    const indexId = this._memopts?.indexId ?? "memories_sindex";
+    const dimensions = this._memopts?.dimensions ?? 1536;
+    const providerOptions = this._memopts?.indexProviderOptions ?? {
+      schema: "kernl",
+    };
+
+    return new Memory({
+      store: this.storage.memories,
+      search: vector
+        ? new MemoryIndexHandle({
+            index: vector,
+            indexId,
+            schema: buildMemoryIndexSchema({ dimensions }),
+            providerOptions,
+          })
+        : undefined,
+      encoder,
+    });
+  }
 }

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";
 
 /**
@@ -35,9 +35,10 @@ export interface MemoryOptions {
    * - A string like "openai/text-embedding-3-small" (resolved via provider registry)
    * - An EmbeddingModel instance
    *
-   * @default "openai/text-embedding-3-small"
+   * If not provided, memories will not auto-embed text content and
+   * semantic search will not be available.
    */
-  embeddingModel?: string | EmbeddingModel<string>;
+  embedding?: string | EmbeddingModel<string>;
 
   /**
    * Logical index ID used by the search backend.
@@ -86,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/memory/__tests__/encoder.test.ts

@@ -150,5 +150,68 @@ describe("MemoryByteEncoder", () => {
 
       expect(vec).toEqual([12, 0, 0]); // "search query".length = 12
     });
+
+    it("returns null when no embedder configured", async () => {
+      const encoder = new MemoryByteEncoder(); // no embedder
+
+      const vec = await encoder.embed("search query");
+
+      expect(vec).toBeNull();
+    });
+
+    it("throws when embedder returns empty embedding", async () => {
+      const embedder = {
+        provider: "test",
+        modelId: "test-embedder",
+        embed: vi.fn(async () => ({
+          embeddings: [[]], // empty embedding
+        })),
+      } as unknown as EmbeddingModel<string>;
+      const encoder = new MemoryByteEncoder(embedder);
+
+      await expect(encoder.embed("test")).rejects.toThrow(
+        "Embedder returned empty embedding",
+      );
+    });
+
+    it("throws when embedder returns undefined embedding", async () => {
+      const embedder = {
+        provider: "test",
+        modelId: "test-embedder",
+        embed: vi.fn(async () => ({
+          embeddings: [], // no embeddings at all
+        })),
+      } as unknown as EmbeddingModel<string>;
+      const encoder = new MemoryByteEncoder(embedder);
+
+      await expect(encoder.embed("test")).rejects.toThrow(
+        "Embedder returned empty embedding",
+      );
+    });
+  });
+
+  describe("without embedder", () => {
+    it("returns undefined tvec when encoding with no embedder", async () => {
+      const encoder = new MemoryByteEncoder(); // no embedder
+
+      const byte: MemoryByte = { text: "Hello world" };
+      const result = await encoder.encode(byte);
+
+      expect(result.text).toBe("Hello world");
+      expect(result.tvec).toBeUndefined();
+    });
+
+    it("still produces objtext projection without embedder", async () => {
+      const encoder = new MemoryByteEncoder(); // no embedder
+
+      const byte: MemoryByte = {
+        object: { preference: "coffee", shots: 2 },
+      };
+      const result = await encoder.encode(byte);
+
+      expect(result.text).toContain("preference: coffee");
+      expect(result.objtext).toContain("preference: coffee");
+      expect(result.tvec).toBeUndefined();
+    });
   });
 });

package/src/memory/codecs/domain.ts

@@ -110,7 +110,7 @@ export const PATCH_CODEC: Codec<MemoryRecordUpdate, IndexMemoryRecordPatch> = {
     if (update.collection !== undefined) patch.collection = update.collection;
     if (update.timestamp !== undefined) patch.timestamp = update.timestamp;
     if (update.updatedAt !== undefined) patch.updatedAt = update.updatedAt;
-    if (update.metadata !== undefined) patch.metadata = update.metadata;
+    // metadata is stored in primary DB only, not indexed
 
     return patch;
   },

package/src/memory/encoder.ts

@@ -41,11 +41,12 @@ export const ObjectTextCodec = {
  * Encoder that converts MemoryByte to IndexableByte.
  *
  * Extracts canonical text from content and computes embeddings.
+ * If no embedder is provided, skips embedding and tvec will be undefined.
  */
 export class MemoryByteEncoder implements MemoryByteCodec {
-  private readonly embedder: EmbeddingModel<string>;
+  private readonly embedder?: EmbeddingModel<string>;
 
-  constructor(embedder: EmbeddingModel<string>) {
+  constructor(embedder?: EmbeddingModel<string>) {
     this.embedder = embedder;
   }
 
@@ -55,9 +56,6 @@ export class MemoryByteEncoder implements MemoryByteCodec {
    * - Produces `objtext` string projection for FTS indexing
    * - Combines text + objtext for embedding input
    * - Returns text (fallback to objtext if no text provided)
-   *
-   * Note: metadata is NOT set here - it comes from record.metadata
-   * via the domain codec, not from MemoryByte.object.
    */
   async encode(byte: MemoryByte): Promise<IndexableByte> {
     const objtext = byte.object
@@ -67,8 +65,9 @@ export class MemoryByteEncoder implements MemoryByteCodec {
     // (TODO): this behavior deserves consideration - do we always want to merge text + object?
     //
     // combine text + object for richer embedding
+    // skip embedding if no embedder configured (embed returns null)
     const combined = [byte.text, objtext].filter(Boolean).join("\n");
-    const tvec = combined ? await this.embed(combined) : undefined;
+    const tvec = combined ? await this.embed(combined) : null;
 
     // TODO: embed other modalities (image, audio, video)
     //
@@ -79,7 +78,7 @@ export class MemoryByteEncoder implements MemoryByteCodec {
     return {
       text: byte.text ?? objtext, // fallback to projection if no text
       objtext,
-      tvec,
+      tvec: tvec ?? undefined,
     };
   }
 
@@ -92,10 +91,19 @@ export class MemoryByteEncoder implements MemoryByteCodec {
 
   /**
    * Embed a text string.
-   * Exposed for query embedding.
+   *
+   * @returns Embedding vector, or null if no embedder configured.
+   * @throws If embedder returns empty embedding.
    */
-  async embed(text: string): Promise<number[]> {
+  async embed(text: string): Promise<number[] | null> {
+    if (!this.embedder) {
+      return null;
+    }
     const result = await this.embedder.embed({ values: [text] });
-    return result.embeddings[0] ?? [];
+    const embedding = result.embeddings[0];
+    if (!embedding || embedding.length === 0) {
+      throw new Error("Embedder returned empty embedding");
+    }
+    return embedding;
   }
 }

package/src/memory/memory.ts

@@ -95,7 +95,7 @@ export class Memory {
     const tvec = await this.encoder.embed(q.query);
 
     return this._search.query({
-      query: [{ text: q.query, tvec }],
+      query: [{ text: q.query, tvec: tvec ?? undefined }],
       filter: q.filter ? MEMORY_FILTER.encode(q.filter) : undefined,
       topK: q.limit ?? 20,
     });

package/src/memory/types.ts

@@ -75,7 +75,12 @@ export interface IndexableByte {
  * Encoder that converts MemoryByte to IndexableByte with embeddings.
  */
 export interface MemoryByteCodec extends AsyncCodec<MemoryByte, IndexableByte> {
-  embed(text: string): Promise<number[]>;
+  /**
+   * Embed a text string.
+   *
+   * @returns Embedding vector, or null if no embedder configured.
+   */
+  embed(text: string): Promise<number[] | null>;
 }
 
 // -------------------
@@ -294,5 +299,4 @@ export interface IndexMemoryRecordPatch {
   collection?: string;
   timestamp?: number;
   updatedAt?: number;
-  metadata?: JSONObject | null;
 }