kernl 0.7.3 → 0.8.0

package/src/guardrail.ts

@@ -4,19 +4,19 @@ import { LanguageModelResponse } from "@kernl-sdk/protocol";
 
 import { Agent } from "./agent";
 import { Context, UnknownContext } from "./context";
-import type { AgentResponseType } from "@/agent/types";
-import type { TextResponse, ThreadEvent } from "@/thread/types";
+import type { AgentOutputType } from "@/agent/types";
+import type { TextOutput, ThreadEvent } from "@/thread/types";
 
 /**
  * Resolves the agent output type based on the response type.
- * - If TResponse is "text" → output is string
- * - If TResponse is a ZodType → output is the inferred type from that schema
+ * - If TOutput is "text" → output is string
+ * - If TOutput is a ZodType → output is the inferred type from that schema
  */
-export type ResolvedAgentResponse<TResponse extends AgentResponseType> =
-  TResponse extends TextResponse
+export type ResolvedAgentResponse<TOutput extends AgentOutputType> =
+  TOutput extends TextOutput
     ? string
-    : TResponse extends ZodType
-      ? z.infer<TResponse>
+    : TOutput extends ZodType
+      ? z.infer<TOutput>
       : never;
 
 /**
@@ -149,10 +149,10 @@ export function defineInputGuardrail({
  */
 export interface OutputGuardrailFunctionArgs<
   TContext = UnknownContext,
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   agent: Agent<any, any>;
-  agentOutput: ResolvedAgentResponse<TResponse>; // ??
+  agentOutput: ResolvedAgentResponse<TOutput>; // ??
   context: Context<TContext>;
   /**
    * Additional details about the agent output.
@@ -166,16 +166,16 @@ export interface OutputGuardrailFunctionArgs<
  * A function that takes an output guardrail function arguments and returns a `GuardrailFunctionOutput`.
  */
 export type OutputGuardrailFunction<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > = (
-  args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
+  args: OutputGuardrailFunctionArgs<UnknownContext, TOutput>,
 ) => Promise<GuardrailFunctionOutput>;
 
 /**
  * A guardrail that checks the output of the agent.
  */
 export interface OutputGuardrail<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   /**
    * The name of the guardrail.
@@ -185,7 +185,7 @@ export interface OutputGuardrail<
   /**
    * The function that performs the guardrail check.
    */
-  execute: OutputGuardrailFunction<TResponse>;
+  execute: OutputGuardrailFunction<TOutput>;
 }
 
 /**
@@ -201,7 +201,7 @@ export interface OutputGuardrailMetadata {
  */
 export interface OutputGuardrailResult<
   TMeta = OutputGuardrailMetadata,
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   /**
    * The metadata of the guardrail.
@@ -211,12 +211,12 @@ export interface OutputGuardrailResult<
   /**
    * The output of the agent that ran.
    */
-  agentOutput: ResolvedAgentResponse<TResponse>; // ??
+  agentOutput: ResolvedAgentResponse<TOutput>; // ??
 
   /**
    * The agent that ran.
    */
-  agent: Agent<UnknownContext, TResponse>;
+  agent: Agent<UnknownContext, TOutput>;
 
   /**
    * The output of the guardrail.
@@ -229,43 +229,43 @@ export interface OutputGuardrailResult<
  */
 export interface OutputGuardrailDefinition<
   TMeta = OutputGuardrailMetadata,
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > extends OutputGuardrailMetadata {
-  guardrailFunction: OutputGuardrailFunction<TResponse>;
+  guardrailFunction: OutputGuardrailFunction<TOutput>;
   run(
-    args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
-  ): Promise<OutputGuardrailResult<TMeta, TResponse>>;
+    args: OutputGuardrailFunctionArgs<UnknownContext, TOutput>,
+  ): Promise<OutputGuardrailResult<TMeta, TOutput>>;
 }
 
 /**
  * Arguments for defining an output guardrail definition.
  */
 export interface DefineOutputGuardrailArgs<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > {
   name: string;
-  execute: OutputGuardrailFunction<TResponse>;
+  execute: OutputGuardrailFunction<TOutput>;
 }
 
 /**
  * Creates an output guardrail definition.
  */
 export function defineOutputGuardrail<
-  TResponse extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 >({
   name,
   execute,
-}: DefineOutputGuardrailArgs<TResponse>): OutputGuardrailDefinition<
+}: DefineOutputGuardrailArgs<TOutput>): OutputGuardrailDefinition<
   OutputGuardrailMetadata,
-  TResponse
+  TOutput
 > {
   return {
     type: "output",
     name,
     guardrailFunction: execute,
     async run(
-      args: OutputGuardrailFunctionArgs<UnknownContext, TResponse>,
-    ): Promise<OutputGuardrailResult<OutputGuardrailMetadata, TResponse>> {
+      args: OutputGuardrailFunctionArgs<UnknownContext, TOutput>,
+    ): Promise<OutputGuardrailResult<OutputGuardrailMetadata, TOutput>> {
       return {
         guardrail: { type: "output", name },
         agent: args.agent,

package/src/kernl/kernl.ts

@@ -17,7 +17,7 @@ import {
 } from "@/memory";
 
 import type { ThreadExecuteResult, ThreadStreamEvent } from "@/thread/types";
-import type { AgentResponseType } from "@/agent/types";
+import type { AgentOutputType } from "@/agent/types";
 
 import type { KernlOptions } from "./types";
 
@@ -27,7 +27,7 @@ import type { KernlOptions } from "./types";
  * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
  * tracing.
  */
-export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
+export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
   private readonly _agents: Map<string, Agent> = new Map();
   private readonly _models: Map<string, LanguageModel> = new Map();
 
@@ -94,9 +94,9 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
   /**
    * Spawn a new thread - blocking execution
    */
-  async spawn<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
-  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+  async spawn<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>> {
     this.athreads.set(thread.tid, thread);
     try {
       return await thread.execute();
@@ -110,9 +110,9 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
    *
    * NOTE: just blocks for now
    */
-  async schedule<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
-  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>> {
+  async schedule<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
+  ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>> {
     this.athreads.set(thread.tid, thread);
     try {
       return await thread.execute();
@@ -126,8 +126,8 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
    *
    * Spawn a new thread - streaming execution
    */
-  async *spawnStream<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
+  async *spawnStream<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
   ): AsyncIterable<ThreadStreamEvent> {
     this.athreads.set(thread.tid, thread);
     try {
@@ -142,8 +142,8 @@ export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
    *
    * Schedule an existing thread - streaming execution
    */
-  async *scheduleStream<TContext, TResponse extends AgentResponseType>(
-    thread: Thread<TContext, TResponse>,
+  async *scheduleStream<TContext, TOutput extends AgentOutputType>(
+    thread: Thread<TContext, TOutput>,
   ): AsyncIterable<ThreadStreamEvent> {
     this.athreads.set(thread.tid, thread);
     try {

package/src/lib/error.ts

@@ -9,8 +9,8 @@ import { randomID } from "@kernl-sdk/shared/lib";
 // import { SerializedThread } from "@/lib/serde/thread";
 type SerializedThread = any;
 
-import { AgentResponseType } from "@/agent/types";
-import { TextResponse } from "@/thread/types";
+import { AgentOutputType } from "@/agent/types";
+import { TextOutput } from "@/thread/types";
 
 /**
  * Abstract base class for all `kernl` errors
@@ -144,7 +144,7 @@ export class InputGuardrailTripwireTriggered extends AgentError {
  */
 export class OutputGuardrailTripwireTriggered<
   TMeta extends OutputGuardrailMetadata,
-  TOutputType extends AgentResponseType = TextResponse,
+  TOutputType extends AgentOutputType = TextOutput,
 > extends AgentError {
   result: OutputGuardrailResult<TMeta, TOutputType>;
   constructor(

package/src/lifecycle.ts

@@ -5,8 +5,8 @@ import { Context, UnknownContext } from "./context";
 import { Tool } from "./tool";
 import type { ToolCall } from "@kernl-sdk/protocol";
 
-import { AgentResponseType } from "@/agent/types";
-import { TextResponse } from "@/thread/types";
+import { AgentOutputType } from "@/agent/types";
+import { TextOutput } from "@/thread/types";
 
 export type EventEmitterEvents = Record<string, any[]>;
 
@@ -60,7 +60,7 @@ class TypedEventEmitter<
 
 export type AgentHookEvents<
   TContext = UnknownContext,
-  TOutput extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > = {
   /**
    * @param context - The context of the run
@@ -107,7 +107,7 @@ export type AgentHookEvents<
  */
 export class AgentHooks<
   TContext = UnknownContext,
-  TOutput extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > extends TypedEventEmitter<AgentHookEvents<TContext, TOutput>> {}
 
 /**
@@ -119,7 +119,7 @@ export class AgentHooks<
  */
 export type KernlHookEvents<
   TContext = UnknownContext,
-  TOutput extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > = {
   /**
    * @param context - The context of the run
@@ -177,5 +177,5 @@ export type KernlHookEvents<
  */
 export class KernlHooks<
   TContext = UnknownContext,
-  TOutput extends AgentResponseType = TextResponse,
+  TOutput extends AgentOutputType = TextOutput,
 > extends TypedEventEmitter<KernlHookEvents<TContext, TOutput>> {}

package/src/memory/__tests__/encoder.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, vi } from "vitest";
+import type { EmbeddingModel } from "@kernl-sdk/protocol";
+
+import { MemoryByteEncoder, ObjectTextCodec } from "../encoder";
+import type { MemoryByte } from "../types";
+
+// Mock embedder that returns predictable vectors
+function createMockEmbedder(): EmbeddingModel<string> {
+  return {
+    provider: "test",
+    modelId: "test-embedder",
+    embed: vi.fn(async ({ values }: { values: string[] }) => ({
+      embeddings: values.map((v) => [v.length, 0, 0]), // simple: [length, 0, 0]
+    })),
+  } as unknown as EmbeddingModel<string>;
+}
+
+describe("ObjectTextCodec", () => {
+  it("encodes simple object to YAML", () => {
+    const obj = { name: "Tony", preference: "coffee" };
+    const result = ObjectTextCodec.encode(obj);
+
+    expect(result).toContain("name: Tony");
+    expect(result).toContain("preference: coffee");
+  });
+
+  it("sorts keys for determinism", () => {
+    const obj1 = { z: 1, a: 2, m: 3 };
+    const obj2 = { a: 2, m: 3, z: 1 };
+
+    expect(ObjectTextCodec.encode(obj1)).toBe(ObjectTextCodec.encode(obj2));
+  });
+
+  it("truncates long objects with ellipsis", () => {
+    const longValue = "x".repeat(4000);
+    const obj = { data: longValue };
+    const result = ObjectTextCodec.encode(obj);
+
+    expect(result.length).toBeLessThanOrEqual(3005); // 3000 + "\n..."
+    expect(result.endsWith("\n...")).toBe(true);
+  });
+
+  it("handles nested objects", () => {
+    const obj = {
+      user: {
+        name: "Tony",
+        prefs: { coffee: { shots: 2 } },
+      },
+    };
+    const result = ObjectTextCodec.encode(obj);
+
+    expect(result).toContain("user:");
+    expect(result).toContain("name: Tony");
+    expect(result).toContain("shots: 2");
+  });
+
+  it("handles arrays", () => {
+    const obj = { items: ["a", "b", "c"] };
+    const result = ObjectTextCodec.encode(obj);
+
+    expect(result).toContain("items:");
+    expect(result).toContain("- a");
+  });
+});
+
+describe("MemoryByteEncoder", () => {
+  describe("encode", () => {
+    it("encodes text-only content", async () => {
+      const embedder = createMockEmbedder();
+      const encoder = new MemoryByteEncoder(embedder);
+
+      const byte: MemoryByte = { text: "Hello world" };
+      const result = await encoder.encode(byte);
+
+      expect(result.text).toBe("Hello world");
+      expect(result.objtext).toBeUndefined();
+      expect(result.tvec).toBeDefined();
+      expect(embedder.embed).toHaveBeenCalledWith({ values: ["Hello world"] });
+    });
+
+    it("encodes object-only content with projection", async () => {
+      const embedder = createMockEmbedder();
+      const encoder = new MemoryByteEncoder(embedder);
+
+      const byte: MemoryByte = {
+        object: { preference: "coffee", shots: 2 },
+      };
+      const result = await encoder.encode(byte);
+
+      // text falls back to objtext projection
+      expect(result.text).toContain("preference: coffee");
+      expect(result.objtext).toContain("preference: coffee");
+      expect(result.tvec).toBeDefined();
+    });
+
+    it("combines text and object for embedding", async () => {
+      const embedder = createMockEmbedder();
+      const encoder = new MemoryByteEncoder(embedder);
+
+      const byte: MemoryByte = {
+        text: "Tony likes coffee",
+        object: { shots: 2, sugar: false },
+      };
+      const result = await encoder.encode(byte);
+
+      expect(result.text).toBe("Tony likes coffee");
+      expect(result.objtext).toContain("shots: 2");
+
+      // embedding should be called with combined text
+      const embedCall = (embedder.embed as ReturnType<typeof vi.fn>).mock
+        .calls[0][0];
+      expect(embedCall.values[0]).toContain("Tony likes coffee");
+      expect(embedCall.values[0]).toContain("shots: 2");
+    });
+
+    it("does not set metadata (handled by domain codec)", async () => {
+      const embedder = createMockEmbedder();
+      const encoder = new MemoryByteEncoder(embedder);
+
+      const byte: MemoryByte = {
+        text: "test",
+        object: { key: "value" },
+      };
+      const result = await encoder.encode(byte);
+
+      expect(result.metadata).toBeUndefined();
+    });
+
+    it("returns undefined tvec when no content", async () => {
+      const embedder = createMockEmbedder();
+      const encoder = new MemoryByteEncoder(embedder);
+
+      const byte: MemoryByte = {};
+      const result = await encoder.encode(byte);
+
+      expect(result.text).toBeUndefined();
+      expect(result.objtext).toBeUndefined();
+      expect(result.tvec).toBeUndefined();
+      expect(embedder.embed).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("embed", () => {
+    it("exposes embed method for query embedding", async () => {
+      const embedder = createMockEmbedder();
+      const encoder = new MemoryByteEncoder(embedder);
+
+      const vec = await encoder.embed("search query");
+
+      expect(vec).toEqual([12, 0, 0]); // "search query".length = 12
+    });
+  });
+});

package/src/memory/codecs/domain.ts

@@ -58,6 +58,11 @@ export const MEMORY_FILTER: Codec<MemoryFilter, SearchFilter> = {
 
 /**
  * Create a codec for MemoryRecord -> IndexMemoryRecord.
+ *
+ * Combines:
+ * - Record scope/timestamps from MemoryRecord
+ * - Indexed content (text, object projection, embeddings) from byte codec
+ * - User metadata from record.metadata (not from content.object)
  */
 export function recordCodec(
   bytecodec: MemoryByteCodec,
@@ -76,6 +81,7 @@ export function recordCodec(
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
         ...indexable,
+        metadata: record.metadata ?? null, // user metadata, not content.object
       };
     },
     async decode(): Promise<MemoryRecord> {

package/src/memory/encoder.ts

@@ -2,10 +2,41 @@
  * MemoryByte encoder - converts MemoryByte to IndexableByte with embeddings.
  */
 
-import type { EmbeddingModel } from "@kernl-sdk/protocol";
+import type { EmbeddingModel, JSONObject } from "@kernl-sdk/protocol";
+import { stringify as yamlStringify } from "yaml";
 
 import type { MemoryByte, IndexableByte, MemoryByteCodec } from "./types";
 
+// ---------------------
+// ObjectTextCodec
+// ---------------------
+
+const MAX_OBJECT_TEXT_LENGTH = 3000;
+
+/**
+ * Codec for converting JSONObject to a canonical text representation.
+ *
+ * Uses YAML for human-readable, deterministic output suitable for:
+ * - Full-text search indexing
+ * - Embedding input (combined with text field)
+ *
+ * TODO: Allow users to pass custom codec via MemoryOptions.
+ */
+export const ObjectTextCodec = {
+  /**
+   * Encode a JSONObject to canonical text.
+   * Uses YAML with sorted keys for determinism.
+   * Truncates at MAX_OBJECT_TEXT_LENGTH chars.
+   */
+  encode(obj: JSONObject): string {
+    const yaml = yamlStringify(obj, { sortMapEntries: true });
+    if (yaml.length <= MAX_OBJECT_TEXT_LENGTH) {
+      return yaml;
+    }
+    return yaml.slice(0, MAX_OBJECT_TEXT_LENGTH) + "\n...";
+  },
+};
+
 /**
  * Encoder that converts MemoryByte to IndexableByte.
  *
@@ -20,21 +51,35 @@ export class MemoryByteEncoder implements MemoryByteCodec {
 
   /**
    * Encode a MemoryByte to IndexableByte.
-   * Extracts text and computes embeddings for each modality.
+   *
+   * - 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 text = byte.text;
-    const tvec = text ? await this.embed(text) : undefined;
+    const objtext = byte.object
+      ? ObjectTextCodec.encode(byte.object) // encode object as embeddable string
+      : undefined;
+
+    // (TODO): this behavior deserves consideration - do we always want to merge text + object?
+    //
+    // combine text + object for richer embedding
+    const combined = [byte.text, objtext].filter(Boolean).join("\n");
+    const tvec = combined ? await this.embed(combined) : undefined;
 
     // TODO: embed other modalities (image, audio, video)
+    //
     // const ivec = byte.image ? await this.embedImage(byte.image) : undefined;
     // const avec = byte.audio ? await this.embedAudio(byte.audio) : undefined;
     // const vvec = byte.video ? await this.embedVideo(byte.video) : undefined;
 
     return {
-      text,
+      text: byte.text ?? objtext, // fallback to projection if no text
+      objtext,
       tvec,
-      metadata: byte.object ?? null,
     };
   }
 

package/src/memory/index.ts

@@ -3,7 +3,7 @@
  */
 
 export { Memory } from "./memory";
-export { MemoryByteEncoder } from "./encoder";
+export { MemoryByteEncoder, ObjectTextCodec } from "./encoder";
 export { buildMemoryIndexSchema } from "./schema";
 export { MemoryIndexHandle } from "./handle";
 export type { MemoryIndexHandleConfig } from "./handle";
@@ -22,6 +22,7 @@ export type {
   MemoryKind,
   NewMemory,
   AgentMemoryCreate,
+  AgentMemoryUpdate,
   MemoryConfig,
   MemoryReindexParams,
   MemoryRecord,

package/src/memory/schema.ts

@@ -105,6 +105,11 @@ export function buildMemoryIndexSchema(
       fts: true,
       optional: true,
     },
+    objtext: {
+      type: "string",
+      fts: true,
+      optional: true,
+    },
 
     // vector fields for different modalities
     tvec: {

package/src/memory/types.ts

@@ -63,6 +63,7 @@ export interface MemoryByte {
  */
 export interface IndexableByte {
   text?: string; // canonical semantic text
+  objtext?: string; // string projection of object for indexing (not full JSON)
   tvec?: number[]; // text embedding
   ivec?: number[]; // image embedding
   avec?: number[]; // audio embedding
@@ -128,7 +129,7 @@ export interface NewMemory {
   id: string;
   scope: MemoryScope;
   kind: MemoryKind;
-  collection: string;
+  collection?: string;
   content: MemoryByte;
   wmem?: boolean;
   smem?: { expiresAt: number | null };
@@ -148,7 +149,7 @@ export interface AgentMemoryCreate {
   id?: string;
   namespace?: string;
   entityId?: string;
-  collection: string;
+  collection?: string;
   content: MemoryByte;
   wmem?: boolean;
   smem?: { expiresAt: number | null };
@@ -156,6 +157,21 @@ export interface AgentMemoryCreate {
   metadata?: JSONObject | null;
 }
 
+/**
+ * Simplified input for agent-scoped memory updates.
+ *
+ * Allows updating content, collection, and memory layer flags.
+ * Scope (namespace, entityId, agentId) cannot be changed after creation.
+ */
+export interface AgentMemoryUpdate {
+  id: string;
+  content?: MemoryByte;
+  collection?: string;
+  wmem?: boolean;
+  smem?: { expiresAt: number | null };
+  metadata?: JSONObject | null;
+}
+
 /**
  * Base memory record fields.
  */
@@ -163,7 +179,7 @@ interface BaseMemoryRecord {
   id: string;
   scope: MemoryScope;
   kind: MemoryKind;
-  collection: string;
+  collection: string | null;
   content: MemoryByte;
   wmem: boolean;
   smem: { expiresAt: number | null };
@@ -260,7 +276,7 @@ export interface IndexMemoryRecord extends IndexableByte {
   entityId: string | null;
   agentId: string | null;
   kind: MemoryKind;
-  collection: string;
+  collection: string | null;
   timestamp: number;
   createdAt: number;
   updatedAt: number;

package/src/storage/in-memory.ts

@@ -415,7 +415,7 @@ export class InMemoryMemoryStore implements MemoryStore {
       id: memory.id,
       scope: memory.scope,
       kind: memory.kind,
-      collection: memory.collection,
+      collection: memory.collection ?? null,
       content: memory.content,
       wmem: memory.wmem ?? false,
       smem: memory.smem ?? { expiresAt: null },
@@ -490,7 +490,11 @@ export class InMemoryMemoryStore implements MemoryStore {
       }
 
       // Filter by collections
-      if (filter.collections && !filter.collections.includes(record.collection)) {
+      if (
+        filter.collections &&
+        (record.collection === null ||
+          !filter.collections.includes(record.collection))
+      ) {
         return false;
       }