kernl 0.6.3 → 0.7.1

package/src/agent.ts

@@ -15,7 +15,7 @@ import type {
   RThreadUpdateParams,
 } from "@/api/resources/threads/types";
 import type { Context, UnknownContext } from "./context";
-import { Tool } from "./tool";
+import { Tool, memory } from "./tool";
 import { BaseToolkit } from "./tool/toolkit";
 import {
   InputGuardrail,
@@ -23,17 +23,27 @@ import {
   type ResolvedAgentResponse,
 } from "./guardrail";
 import { AgentHooks } from "./lifecycle";
+import type {
+  AgentMemoryCreate,
+  MemoryListOptions,
+  MemorySearchQuery,
+} from "./memory";
 
+import { randomID } from "@kernl-sdk/shared/lib";
 import { MisconfiguredError, RuntimeError } from "./lib/error";
-import type { AgentConfig, AgentResponseType } from "@/agent/types";
+
+/* types */
+import type {
+  AgentConfig,
+  AgentMemoryConfig,
+  AgentResponseType,
+} from "./agent/types";
 import type {
   TextResponse,
   ThreadExecuteOptions,
   ThreadExecuteResult,
   ThreadStreamEvent,
-} from "@/thread/types";
-import type { AgentMemoryCreate, MemorySearchQuery } from "./memory";
-import { randomID } from "@kernl-sdk/shared/lib";
+} from "./thread/types";
 
 export class Agent<
     TContext = UnknownContext,
@@ -46,12 +56,15 @@ export class Agent<
 
   id: string;
   name: string;
+  description?: string;
   instructions: (context: Context<TContext>) => Promise<string> | string;
 
   model: LanguageModel;
   modelSettings: LanguageModelRequestSettings;
-  toolkits: BaseToolkit<TContext>[];
   // actions: ActionSet; /* TODO */
+  toolkits: BaseToolkit<TContext>[];
+  systools: BaseToolkit<TContext>[];
+  memory: AgentMemoryConfig;
 
   guardrails: {
     input: InputGuardrail[];
@@ -59,10 +72,9 @@ export class Agent<
   };
   responseType: TResponse = "text" as TResponse;
   resetToolChoice: boolean;
-  // toolUseBehavior: ToolUseBehavior; (TODO)
 
   // --- (TODO) ---
-  // handoffDescription: string; // ??
+  // toolUseBehavior: ToolUseBehavior;
   // handoffs: (Agent<any, TResponse> | Handoff<any, TResponse>)[];
   // ----------
 
@@ -81,6 +93,7 @@ export class Agent<
     }
     this.id = config.id;
     this.name = config.name;
+    this.description = config.description;
     this.instructions =
       typeof config.instructions === "function"
         ? config.instructions
@@ -89,6 +102,9 @@ export class Agent<
     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);
     }
@@ -99,21 +115,6 @@ export class Agent<
     }
     this.resetToolChoice = config.resetToolChoice ?? true;
     // this.toolUseBehavior = config.toolUseBehavior ?? "run_llm_again";
-
-    // this.handoffDescription = config.handoffDescription ?? "";
-    // this.handoffs = config.handoffs ?? [];
-
-    // --- Runtime warning for handoff response type compatibility ---
-    // 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.`,
-    //       );
-    //     }
-    //   }
-    // }
   }
 
   /**
@@ -121,6 +122,14 @@ export class Agent<
    */
   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);
+    }
   }
 
   /**
@@ -247,12 +256,18 @@ export class Agent<
   /**
    * @internal
    *
-   * Get a specific tool by ID from all toolkits.
+   * 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;
@@ -263,7 +278,7 @@ export class Agent<
   /**
    * @internal
    *
-   * Get all tools available from all toolkits for the given context.
+   * 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
@@ -274,24 +289,22 @@ export class Agent<
    * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
    */
   async tools(context: Context<TContext>): Promise<Tool<TContext>[]> {
-    const allTools: Tool<TContext>[] = [];
-    const toolIds = new Set<string>();
+    const all: Tool<TContext>[] = [];
 
-    for (const toolkit of this.toolkits) {
-      const tools = await toolkit.list(context);
+    for (const toolkit of [...this.systools, ...this.toolkits]) {
+      all.push(...(await toolkit.list(context)));
+    }
 
-      const duplicates = tools.map((t) => t.id).filter((id) => toolIds.has(id));
-      if (duplicates.length > 0) {
-        throw new MisconfiguredError(
-          `Duplicate tool IDs found across toolkits: ${duplicates.join(", ")}`,
-        );
-      }
+    const ids = all.map((t) => t.id);
+    const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
 
-      tools.forEach((t) => toolIds.add(t.id));
-      allTools.push(...tools);
+    if (duplicates.length > 0) {
+      throw new MisconfiguredError(
+        `Duplicate tool IDs found: ${[...new Set(duplicates)].join(", ")}`,
+      );
     }
 
-    return allTools;
+    return all;
   }
 
   /**
@@ -359,6 +372,24 @@ export class Agent<
     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.
        */
@@ -384,6 +415,7 @@ export class Agent<
        */
       search: (
         params: Omit<MemorySearchQuery, "filter"> & {
+          // (TODO): is this correct?
           filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
             scope?: Omit<
               NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>,

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

@@ -0,0 +1,56 @@
+import type { Agent } from "@/agent";
+import type { AgentResponseType } from "@/agent/types";
+import type { UnknownContext } from "@/context";
+import type { TextResponse } from "@/thread/types";
+
+/**
+ * Agents resource.
+ *
+ * Thin facade over the in-process agent registry, returning live Agent instances.
+ *
+ * Note: agents are code, not persisted data; this is process-local.
+ */
+export class RAgents {
+  constructor(private readonly registry: Map<string, Agent>) {}
+
+  /**
+   * Get a live Agent instance by id.
+   *
+   * Callers are expected to know the concrete TContext/TResponse types
+   * for their own agents and can specify them via generics.
+   */
+  get<
+    TContext = UnknownContext,
+    TResponse extends AgentResponseType = TextResponse,
+  >(id: string): Agent<TContext, TResponse> | undefined {
+    const agent = this.registry.get(id);
+    return agent as Agent<TContext, TResponse> | undefined;
+  }
+
+  /**
+   * Check if an agent with the given id is registered.
+   */
+  has(id: string): boolean {
+    return this.registry.has(id);
+  }
+
+  /**
+   * List all registered agents as live instances.
+   *
+   * Since this is a heterogeneous collection, we expose the widest safe
+   * type parameters here.
+   */
+  list(): Agent<UnknownContext, AgentResponseType>[] {
+    return Array.from(this.registry.values()) as Agent<
+      UnknownContext,
+      AgentResponseType
+    >[];
+  }
+
+  /**
+   * Unregister an agent at runtime.
+   */
+  unregister(id: string): boolean {
+    return this.registry.delete(id);
+  }
+}

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

@@ -0,0 +1 @@
+export { RAgents } from "./agents";

package/src/context.ts

@@ -1,3 +1,5 @@
+import type { Agent } from "@/agent";
+
 /**
  * Context that is being passed around as part of the session is unknown
  */
@@ -18,6 +20,12 @@ export class Context<TContext = UnknownContext> {
    */
   context: TContext;
 
+  /**
+   * The agent executing this context.
+   * Set by the thread during execution.
+   */
+  agent?: Agent<TContext, any>;
+
   // ----------------------
   // TEMPORARY: Tool approval tracking until actions system is refined
   // ----------------------

package/src/kernl/kernl.ts

@@ -8,6 +8,7 @@ import type { Thread } from "@/thread";
 import type { ResolvedAgentResponse } from "@/guardrail";
 import { InMemoryStorage, type KernlStorage } from "@/storage";
 import { RThreads } from "@/api/resources/threads";
+import { RAgents } from "@/api/resources/agents";
 import {
   Memory,
   MemoryByteEncoder,
@@ -27,21 +28,23 @@ import type { KernlOptions } from "./types";
  * tracing.
  */
 export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
-  private agents: Map<string, Agent> = new Map();
-  private models: Map<string, LanguageModel> = new Map();
+  private readonly _agents: Map<string, Agent> = new Map();
+  private readonly _models: Map<string, LanguageModel> = new Map();
 
   readonly storage: KernlStorage;
   athreads: Map<string, Thread<any, any>> = new Map(); /* active threads */
 
   // --- public API ---
-  readonly threads: RThreads; /* Threads resource */
-  readonly memories: Memory; /* Memory system */
+  readonly threads: RThreads;
+  readonly agents: RAgents;
+  readonly memories: Memory;
 
   constructor(options: KernlOptions = {}) {
     super();
     this.storage = options.storage?.db ?? new InMemoryStorage();
-    this.storage.bind({ agents: this.agents, models: this.models });
+    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 =
@@ -76,15 +79,15 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
    * Registers a new agent with the kernl instance.
    */
   register(agent: Agent): void {
-    this.agents.set(agent.id, agent);
+    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);
+    if (!this._models.has(key)) {
+      this._models.set(key, agent.model);
     }
   }
 

package/src/memory/memory.ts

@@ -9,6 +9,7 @@ import type {
   MemoryScope,
   MemoryConfig,
   MemorySearchQuery,
+  MemoryListOptions,
   MemoryByteCodec,
   IndexMemoryRecord,
   WorkingMemorySnapshot,
@@ -100,6 +101,13 @@ export class Memory {
     });
   }
 
+  /**
+   * List memories matching the filter.
+   */
+  async list(options?: MemoryListOptions): Promise<MemoryRecord[]> {
+    return this.store.list(options);
+  }
+
   /**
    * Repair indexing for a memory without modifying the DB row.
    */

package/src/thread/thread.ts

@@ -112,6 +112,7 @@ export class Thread<
     this.agent = options.agent;
     this.context =
       options.context ?? new Context<TContext>(this.namespace, {} as TContext);
+    this.context.agent = options.agent;
     this.parent = options.task ?? null;
     this.model = options.model ?? options.agent.model;
     this.storage = options.storage;
@@ -335,7 +336,7 @@ export class Thread<
       state: this.state,
       tick: this._tick,
       context: this.context,
-      metadata: this.metadata,
+      // no metadata - not owned by checkpoint
     });
   }
 
@@ -441,6 +442,7 @@ export class Thread<
           // (TMP) - passing the approval status through the context until actions system
           // is refined
           const ctx = new Context(this.namespace, this.context.context);
+          ctx.agent = this.agent;
           ctx.approve(call.callId); // mark this call as approved
           const res = await tool.invoke(ctx, call.arguments, call.callId);
 

package/src/tool/index.ts

@@ -8,3 +8,6 @@ export type {
   ToolkitFilter,
   ToolkitFilterContext,
 } from "./types";
+
+// --- system toolkits ---
+export { memory } from "./sys";

package/src/tool/sys/index.ts

@@ -0,0 +1,7 @@
+/**
+ * System toolkits.
+ *
+ * These are internal toolkits that can be enabled via agent config flags.
+ */
+
+export { memory } from "./memory";

package/src/tool/sys/memory.ts

@@ -0,0 +1,120 @@
+/**
+ * Memory system toolkit.
+ *
+ * Provides tools for agents to store and retrieve memories.
+ * Enabled via `memory: true` in agent config.
+ */
+
+import assert from "assert";
+import { z } from "zod";
+
+import { tool } from "../tool";
+import { Toolkit } from "../toolkit";
+
+// --- Tools ---
+
+/**
+ * Search memories for relevant information using natural language.
+ */
+const search = tool({
+  id: "memories.search",
+  description:
+    "Search your memories. " +
+    "Use this to recall facts, preferences, or context you've previously stored.",
+  parameters: z.object({
+    query: z.string().describe("Natural language search query"),
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Max results (default: 10)"),
+  }),
+  execute: async (ctx, { query, limit }) => {
+    assert(ctx.agent, "ctx.agent required for memory tools");
+
+    const mems = await ctx.agent.memories.search({
+      query,
+      limit: limit ?? 10,
+    });
+
+    return mems.map((h) => ({
+      id: h.document?.id,
+      text: h.document?.text,
+      score: h.score,
+    }));
+  },
+});
+
+/**
+ * Store a new memory to persist across conversations.
+ */
+const create = tool({
+  id: "memories.create",
+  description:
+    "Store a new memory. Use this to remember important facts, user preferences, " +
+    "or context that should persist across conversations.",
+  parameters: z.object({
+    content: z.string().describe("Text content to remember"),
+    collection: z
+      .string()
+      .optional()
+      .describe("Category for organizing memories (default: 'facts')"),
+  }),
+  execute: async (ctx, { content, collection }) => {
+    assert(ctx.agent, "ctx.agent required for memory tools");
+
+    const mem = await ctx.agent.memories.create({
+      collection: collection ?? "facts",
+      content: { text: content },
+    });
+
+    return { id: mem.id, stored: true };
+  },
+});
+
+/**
+ * List stored memories, optionally filtered by collection.
+ */
+const list = tool({
+  id: "memories.list",
+  description:
+    "List your stored memories. Use this to see what you've remembered, " +
+    "optionally filtered by collection.",
+  parameters: z.object({
+    collection: z.string().optional().describe("Filter by collection name"),
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Max results (default: 20)"),
+  }),
+  execute: async (ctx, { collection, limit }) => {
+    assert(ctx.agent, "ctx.agent required for memory tools");
+
+    const mems = await ctx.agent.memories.list({
+      collection,
+      limit: limit ?? 20,
+    });
+
+    return mems.map((r) => ({
+      id: r.id,
+      collection: r.collection,
+      text: r.content.text,
+    }));
+  },
+});
+
+// --- Toolkit ---
+
+/**
+ * Memory system toolkit.
+ *
+ * Provides memories.search, memories.create, and memories.list tools.
+ */
+export const memory = new Toolkit({
+  id: "sys.memory",
+  description: "Tools for storing and retrieving agent memories",
+  tools: [list, create, search],
+});

package/src/tool/tool.ts

@@ -3,12 +3,16 @@ import { Context, UnknownContext } from "@/context";
 
 import { ModelBehaviorError } from "@/lib/error";
 import { logger } from "@/lib/logger";
+
+import {
+  FAILED,
+  COMPLETED,
+  INTERRUPTIBLE,
+  type LanguageModelTool,
+} from "@kernl-sdk/protocol";
 import { json } from "@kernl-sdk/shared/lib";
-import { FAILED, COMPLETED, INTERRUPTIBLE } from "@kernl-sdk/protocol";
-import type { LanguageModelTool } from "@kernl-sdk/protocol";
 
 import type {
-  ToolType,
   ToolConfig,
   ToolApprovalFunction,
   ToolEnabledFunction,
@@ -199,7 +203,7 @@ export class FunctionTool<
       description: this.description,
       parameters: z.toJSONSchema(this.parameters ?? z.object({}), {
         target: "draft-7",
-      }) as any, // Use empty object if no parameters (matches AI SDK)
+      }) as any, // use empty object if no parameters (matches AI SDK)
     };
   }
 }