kernl 0.6.3 → 0.7.0

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)
     };
   }
 }