kernl 0.6.2 → 0.7.0

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

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/agent.ts","./src/context.ts","./src/guardrail.ts","./src/index.ts","./src/internal.ts","./src/kernl.ts","./src/lifecycle.ts","./src/task.ts","./src/agent/index.ts","./src/agent/__tests__/concurrency.test.ts","./src/agent/__tests__/run.test.ts","./src/api/__tests__/threads.test.ts","./src/api/models/index.ts","./src/api/models/thread.ts","./src/api/resources/threads/events.ts","./src/api/resources/threads/index.ts","./src/api/resources/threads/threads.ts","./src/api/resources/threads/types.ts","./src/api/resources/threads/utils.ts","./src/lib/env.ts","./src/lib/error.ts","./src/lib/logger.ts","./src/lib/serde/json.ts","./src/mcp/base.ts","./src/mcp/http.ts","./src/mcp/sse.ts","./src/mcp/stdio.ts","./src/mcp/types.ts","./src/mcp/utils.ts","./src/mcp/__tests__/base.test.ts","./src/mcp/__tests__/integration.test.ts","./src/mcp/__tests__/stdio.test.ts","./src/mcp/__tests__/utils.test.ts","./src/mcp/__tests__/fixtures/server.ts","./src/mcp/__tests__/fixtures/utils.ts","./src/memory/byte.ts","./src/memory/index.ts","./src/memory/indexes.ts","./src/memory/memory.ts","./src/memory/store.ts","./src/memory/types.ts","./src/storage/base.ts","./src/storage/in-memory.ts","./src/storage/index.ts","./src/storage/thread.ts","./src/storage/__tests__/in-memory.test.ts","./src/thread/index.ts","./src/thread/thread.ts","./src/thread/utils.ts","./src/thread/__tests__/integration.test.ts","./src/thread/__tests__/mock.ts","./src/thread/__tests__/namespace.test.ts","./src/thread/__tests__/thread-persistence.test.ts","./src/thread/__tests__/thread.test.ts","./src/thread/__tests__/fixtures/mock-model.ts","./src/tool/index.ts","./src/tool/tool.ts","./src/tool/toolkit.ts","./src/tool/types.ts","./src/tool/__tests__/fixtures.ts","./src/tool/__tests__/tool.test.ts","./src/tool/__tests__/toolkit.test.ts","./src/trace/processor.ts","./src/trace/traces.ts","./src/trace/utils.ts","./src/types/agent.ts","./src/types/kernl.ts","./src/types/thread.ts"],"version":"5.9.2"}

package/dist/api/__tests__/cursor-page.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=cursor-page.test.d.ts.map

package/dist/api/__tests__/cursor-page.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cursor-page.test.d.ts","sourceRoot":"","sources":["../../../src/api/__tests__/cursor-page.test.ts"],"names":[],"mappings":""}

package/dist/api/__tests__/cursor-page.test.js

@@ -1,414 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { CursorPage, } from "../pagination/cursor.js";
-describe("CursorPage", () => {
-    describe("construction", () => {
-        it("should initialize with response data", () => {
-            const response = {
-                data: ["a", "b", "c"],
-                next: "cursor_123",
-                last: false,
-            };
-            const loader = vi.fn();
-            const page = new CursorPage({
-                params: {},
-                response,
-                loader,
-            });
-            expect(page.data).toEqual(["a", "b", "c"]);
-            expect(page.items).toEqual(["a", "b", "c"]);
-            expect(page.last).toBe(false);
-        });
-        it("should handle empty data array", () => {
-            const response = {
-                data: [],
-                next: null,
-                last: true,
-            };
-            const loader = vi.fn();
-            const page = new CursorPage({
-                params: {},
-                response,
-                loader,
-            });
-            expect(page.data).toEqual([]);
-            expect(page.items).toEqual([]);
-            expect(page.last).toBe(true);
-        });
-        it("should handle null data gracefully", () => {
-            const response = {
-                data: null, // simulate backend returning null
-                next: null,
-                last: true,
-            };
-            const loader = vi.fn();
-            const page = new CursorPage({
-                params: {},
-                response,
-                loader,
-            });
-            expect(page.data).toEqual([]);
-            expect(page.items).toEqual([]);
-        });
-    });
-    describe("items getter", () => {
-        it("should return exact reference to data array", () => {
-            const data = ["a", "b", "c"];
-            const response = {
-                data,
-                next: null,
-                last: false,
-            };
-            const page = new CursorPage({
-                params: {},
-                response,
-                loader: vi.fn(),
-            });
-            expect(page.items).toBe(page.data);
-        });
-    });
-    describe("last getter", () => {
-        it("should return true when response.last is true", () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: "cursor", last: true },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(true);
-        });
-        it("should return true when next cursor is null", () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: null, last: false },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(true);
-        });
-        it("should return true when data is empty", () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: [], next: "cursor", last: false },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(true);
-        });
-        it("should return false when has next cursor and data", () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a", "b"], next: "cursor_123", last: false },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(false);
-        });
-        it("should prioritize response.last over next cursor", () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: "cursor", last: true },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(true);
-        });
-    });
-    describe("next()", () => {
-        it("should return null when last is true", async () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: null, last: true },
-                loader: vi.fn(),
-            });
-            const nextPage = await page.next();
-            expect(nextPage).toBe(null);
-        });
-        it("should return null when no next cursor", async () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: null, last: false },
-                loader: vi.fn(),
-            });
-            const nextPage = await page.next();
-            expect(nextPage).toBe(null);
-        });
-        it("should fetch next page with cursor in params", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["d", "e", "f"],
-                next: "cursor_456",
-                last: false,
-            });
-            const page = new CursorPage({
-                params: { limit: 10 },
-                response: { data: ["a", "b", "c"], next: "cursor_123", last: false },
-                loader,
-            });
-            const nextPage = await page.next();
-            expect(loader).toHaveBeenCalledTimes(1);
-            expect(loader).toHaveBeenCalledWith({
-                limit: 10,
-                cursor: "cursor_123",
-            });
-            expect(nextPage).not.toBe(null);
-            expect(nextPage.data).toEqual(["d", "e", "f"]);
-            expect(nextPage.items).toEqual(["d", "e", "f"]);
-        });
-        it("should preserve params across pagination", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["x"],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: { limit: 5, cursor: "initial" },
-                response: { data: ["a"], next: "cursor_next", last: false },
-                loader,
-            });
-            await page.next();
-            expect(loader).toHaveBeenCalledWith({
-                limit: 5,
-                cursor: "cursor_next", // cursor gets updated
-            });
-        });
-        it("should return instance of CursorPage", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["d"],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: "cursor", last: false },
-                loader,
-            });
-            const nextPage = await page.next();
-            expect(nextPage).toBeInstanceOf(CursorPage);
-        });
-    });
-    describe("pages() generator", () => {
-        it("should yield only current page when last", async () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: null, last: true },
-                loader: vi.fn(),
-            });
-            const pages = [];
-            for await (const p of page.pages()) {
-                pages.push(p);
-            }
-            expect(pages).toHaveLength(1);
-            expect(pages[0]).toBe(page);
-        });
-        it("should yield multiple pages until last", async () => {
-            const loader = vi
-                .fn()
-                .mockResolvedValueOnce({
-                data: ["d", "e"],
-                next: "cursor_2",
-                last: false,
-            })
-                .mockResolvedValueOnce({
-                data: ["f"],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a", "b", "c"], next: "cursor_1", last: false },
-                loader,
-            });
-            const pages = [];
-            for await (const p of page.pages()) {
-                pages.push(p);
-            }
-            expect(pages).toHaveLength(3);
-            expect(pages[0].data).toEqual(["a", "b", "c"]);
-            expect(pages[1].data).toEqual(["d", "e"]);
-            expect(pages[2].data).toEqual(["f"]);
-            expect(loader).toHaveBeenCalledTimes(2);
-        });
-        it("should stop when next() returns null", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: [],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: "cursor", last: false },
-                loader,
-            });
-            const pages = [];
-            for await (const p of page.pages()) {
-                pages.push(p);
-            }
-            expect(pages).toHaveLength(2); // original + one fetched
-        });
-    });
-    describe("Symbol.asyncIterator", () => {
-        it("should iterate over items in single page", async () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a", "b", "c"], next: null, last: true },
-                loader: vi.fn(),
-            });
-            const items = [];
-            for await (const item of page) {
-                items.push(item);
-            }
-            expect(items).toEqual(["a", "b", "c"]);
-        });
-        it("should iterate over items across multiple pages", async () => {
-            const loader = vi.fn().mockResolvedValueOnce({
-                data: ["d", "e"],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a", "b", "c"], next: "cursor_1", last: false },
-                loader,
-            });
-            const items = [];
-            for await (const item of page) {
-                items.push(item);
-            }
-            expect(items).toEqual(["a", "b", "c", "d", "e"]);
-        });
-        it("should handle empty pages gracefully", async () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: [], next: null, last: true },
-                loader: vi.fn(),
-            });
-            const items = [];
-            for await (const item of page) {
-                items.push(item);
-            }
-            expect(items).toEqual([]);
-        });
-        it("should work with complex objects", async () => {
-            const users = [
-                { id: "1", name: "Alice" },
-                { id: "2", name: "Bob" },
-            ];
-            const page = new CursorPage({
-                params: {},
-                response: { data: users, next: null, last: true },
-                loader: vi.fn(),
-            });
-            const collected = [];
-            for await (const user of page) {
-                collected.push(user);
-            }
-            expect(collected).toEqual(users);
-            expect(collected[0]).toEqual({ id: "1", name: "Alice" });
-        });
-    });
-    describe("collect()", () => {
-        it("should collect all items from single page", async () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a", "b", "c"], next: null, last: true },
-                loader: vi.fn(),
-            });
-            const items = await page.collect();
-            expect(items).toEqual(["a", "b", "c"]);
-        });
-        it("should collect all items from multiple pages", async () => {
-            const loader = vi
-                .fn()
-                .mockResolvedValueOnce({
-                data: ["d", "e", "f"],
-                next: "cursor_2",
-                last: false,
-            })
-                .mockResolvedValueOnce({
-                data: ["g", "h"],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a", "b", "c"], next: "cursor_1", last: false },
-                loader,
-            });
-            const items = await page.collect();
-            expect(items).toEqual(["a", "b", "c", "d", "e", "f", "g", "h"]);
-            expect(loader).toHaveBeenCalledTimes(2);
-        });
-        it("should return empty array for empty page", async () => {
-            const page = new CursorPage({
-                params: {},
-                response: { data: [], next: null, last: true },
-                loader: vi.fn(),
-            });
-            const items = await page.collect();
-            expect(items).toEqual([]);
-        });
-        it("should preserve item order across pages", async () => {
-            const loader = vi
-                .fn()
-                .mockResolvedValueOnce({ data: [4, 5, 6], next: null, last: true });
-            const page = new CursorPage({
-                params: {},
-                response: { data: [1, 2, 3], next: "cursor", last: false },
-                loader,
-            });
-            const items = await page.collect();
-            expect(items).toEqual([1, 2, 3, 4, 5, 6]);
-        });
-    });
-    describe("edge cases", () => {
-        it("should handle consecutive next() calls correctly", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["next"],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: "cursor", last: false },
-                loader,
-            });
-            const next1 = await page.next();
-            const next2 = await page.next();
-            expect(next1).not.toBe(null);
-            expect(next2).not.toBe(null);
-            expect(loader).toHaveBeenCalledTimes(2);
-        });
-        it("should handle loader throwing error", async () => {
-            const loader = vi.fn().mockRejectedValue(new Error("Network error"));
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: "cursor", last: false },
-                loader,
-            });
-            await expect(page.next()).rejects.toThrow("Network error");
-        });
-        it("should not call loader when last is true", async () => {
-            const loader = vi.fn();
-            const page = new CursorPage({
-                params: {},
-                response: { data: ["a"], next: null, last: true },
-                loader,
-            });
-            await page.next();
-            expect(loader).not.toHaveBeenCalled();
-        });
-        it("should handle params with custom properties", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["b"],
-                next: null,
-                last: true,
-            });
-            const page = new CursorPage({
-                params: { agentId: "agent-1", filter: "active", limit: 10 },
-                response: { data: ["a"], next: "cursor", last: false },
-                loader,
-            });
-            await page.next();
-            expect(loader).toHaveBeenCalledWith({
-                agentId: "agent-1",
-                filter: "active",
-                limit: 10,
-                cursor: "cursor",
-            });
-        });
-    });
-});

package/dist/api/__tests__/offset-page.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=offset-page.test.d.ts.map

package/dist/api/__tests__/offset-page.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"offset-page.test.d.ts","sourceRoot":"","sources":["../../../src/api/__tests__/offset-page.test.ts"],"names":[],"mappings":""}