kernl 0.8.3 → 0.9.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> kernl@0.8.3 build /home/runner/work/kernl/kernl/packages/kernl
+> kernl@0.9.0 build /home/runner/work/kernl/kernl/packages/kernl
 > tsc && tsc-alias --resolve-full-paths
 

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @kernl/core
 
+## 0.9.0
+
+### Minor Changes
+
+- 572ae80: Add realtime voice agent support with memory capabilities.
+  - **protocol**: Add realtime model and event types for voice agents
+  - **kernl**: Extract BaseAgent class shared by Agent and RealtimeAgent, enabling memory support for realtime agents. Add `kind` discriminator for type narrowing.
+  - **openai**: Add OpenAI realtime voice provider with WebSocket-based streaming
+
+### Patch Changes
+
+- Updated dependencies [572ae80]
+  - @kernl-sdk/protocol@0.3.0
+  - @kernl-sdk/retrieval@0.1.4
+
+## 0.8.4
+
+### Patch Changes
+
+- e90b227: Make memory embedding opt-in with config warnings
+
 ## 0.8.3
 
 ### Patch Changes

package/dist/agent/base.d.ts

@@ -0,0 +1,73 @@
+import type { Context, UnknownContext } from "../context.js";
+import type { Tool, BaseToolkit } from "../tool/index.js";
+import { AgentHooks } from "../lifecycle.js";
+import type { Kernl } from "../kernl/index.js";
+import type { AgentMemoryCreate, AgentMemoryUpdate, MemoryListOptions, MemorySearchQuery } from "../memory/index.js";
+import type { AgentKind, AgentMemoryConfig, AgentOutputType } from "./types.js";
+import type { TextOutput } from "../thread/types.js";
+/**
+ * Base configuration shared by all agent types.
+ */
+export interface BaseAgentConfig<TContext = UnknownContext> {
+    id: string;
+    name: string;
+    description?: string;
+    instructions: string | ((context: Context<TContext>) => Promise<string> | string);
+    toolkits?: BaseToolkit<TContext>[];
+    memory?: AgentMemoryConfig;
+}
+/**
+ * Common model interface shared by all model types.
+ */
+export interface BaseModel {
+    readonly provider: string;
+    readonly modelId: string;
+}
+/**
+ * Abstract base class for all agent types.
+ *
+ * Provides common functionality shared between text-based agents (Agent)
+ * and realtime agents (RealtimeAgent).
+ */
+export declare abstract class BaseAgent<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput> extends AgentHooks<TContext, TOutput> {
+    protected kernl?: Kernl;
+    abstract readonly kind: AgentKind;
+    abstract readonly model: BaseModel;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly instructions: (context: Context<TContext>) => Promise<string> | string;
+    readonly toolkits: BaseToolkit<TContext>[];
+    readonly systools: BaseToolkit<TContext>[];
+    readonly memory: AgentMemoryConfig;
+    constructor(config: BaseAgentConfig<TContext>);
+    /**
+     * Bind this agent to a kernl instance. Called by kernl.register().
+     */
+    bind(kernl: Kernl): void;
+    /**
+     * Get a specific tool by ID from systools and toolkits.
+     */
+    tool(id: string): Tool<TContext> | undefined;
+    /**
+     * Get all tools available from systools and toolkits for the given context.
+     */
+    tools(context: Context<TContext>): Promise<Tool<TContext>[]>;
+    /**
+     * Memory management scoped to this agent.
+     */
+    get memories(): {
+        list: (params?: Omit<MemoryListOptions, "filter"> & {
+            collection?: string;
+            limit?: number;
+        }) => Promise<import("../memory/index.js").MemoryRecord[]>;
+        create: (params: AgentMemoryCreate) => Promise<import("../memory/index.js").MemoryRecord>;
+        update: (params: AgentMemoryUpdate) => Promise<import("../memory/index.js").MemoryRecord>;
+        search: (params: Omit<MemorySearchQuery, "filter"> & {
+            filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
+                scope?: Omit<NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>, "agentId">;
+            };
+        }) => Promise<import("@kernl-sdk/retrieval").SearchHit<import("../memory/index.js").IndexMemoryRecord>[]>;
+    };
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/agent/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/agent/base.ts"],"names":[],"mappings":"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"}

package/dist/agent/base.js

@@ -0,0 +1,137 @@
+import { randomID } from "@kernl-sdk/shared/lib";
+import { memory } from "../tool/index.js";
+import { MisconfiguredError } from "../lib/error.js";
+import { AgentHooks } from "../lifecycle.js";
+/**
+ * Abstract base class for all agent types.
+ *
+ * Provides common functionality shared between text-based agents (Agent)
+ * and realtime agents (RealtimeAgent).
+ */
+export class BaseAgent extends AgentHooks {
+    kernl;
+    id;
+    name;
+    description;
+    instructions;
+    toolkits;
+    systools;
+    memory;
+    constructor(config) {
+        super();
+        if (config.id.trim() === "") {
+            throw new MisconfiguredError("Agent must have an id.");
+        }
+        this.id = config.id;
+        this.name = config.name;
+        this.description = config.description;
+        this.instructions =
+            typeof config.instructions === "function"
+                ? config.instructions
+                : () => config.instructions;
+        this.toolkits = config.toolkits ?? [];
+        this.systools = [];
+        this.memory = config.memory ?? { enabled: false };
+        for (const toolkit of this.toolkits) {
+            toolkit.bind(this);
+        }
+    }
+    /**
+     * Bind this agent to a kernl instance. Called by kernl.register().
+     */
+    bind(kernl) {
+        this.kernl = kernl;
+        // initialize system toolkits
+        if (this.memory.enabled) {
+            // safety: system tools only rely on ctx.agent, not ctx.context
+            const toolkit = memory;
+            this.systools.push(toolkit);
+            toolkit.bind(this);
+        }
+    }
+    /**
+     * Get a specific tool by ID from systools and toolkits.
+     */
+    tool(id) {
+        // 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;
+        }
+        return undefined;
+    }
+    /**
+     * Get all tools available from systools and toolkits for the given context.
+     */
+    async tools(context) {
+        const all = [];
+        for (const toolkit of [...this.systools, ...this.toolkits]) {
+            all.push(...(await toolkit.list(context)));
+        }
+        const ids = all.map((t) => t.id);
+        const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
+        if (duplicates.length > 0) {
+            throw new MisconfiguredError(`Duplicate tool IDs found: ${[...new Set(duplicates)].join(", ")}`);
+        }
+        return all;
+    }
+    /**
+     * Memory management scoped to this agent.
+     */
+    get memories() {
+        if (!this.kernl) {
+            throw new MisconfiguredError(`Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`);
+        }
+        const agentId = this.id;
+        const kmem = this.kernl.memories;
+        return {
+            list: (params) => kmem.list({
+                filter: {
+                    scope: { agentId },
+                    collections: params?.collection ? [params.collection] : undefined,
+                },
+                limit: params?.limit,
+            }),
+            create: (params) => kmem.create({
+                id: params.id ?? `mem_${randomID()}`,
+                scope: {
+                    namespace: params.namespace,
+                    entityId: params.entityId,
+                    agentId,
+                },
+                kind: "semantic",
+                collection: params.collection,
+                content: params.content,
+                wmem: params.wmem,
+                smem: params.smem,
+                timestamp: params.timestamp,
+                metadata: params.metadata,
+            }),
+            update: (params) => kmem.update({
+                id: params.id,
+                content: params.content,
+                collection: params.collection,
+                wmem: params.wmem,
+                smem: params.smem,
+                metadata: params.metadata,
+            }),
+            search: (params) => kmem.search({
+                ...params,
+                filter: {
+                    ...params.filter,
+                    scope: {
+                        ...params.filter?.scope,
+                        agentId,
+                    },
+                },
+            }),
+        };
+    }
+}

package/dist/agent/index.d.ts

@@ -1 +1,3 @@
+export * from "./base.js";
+export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/agent/index.js

@@ -1 +1,2 @@
-"use strict";
+export * from "./base.js";
+export * from "./types.js";

package/dist/agent/types.d.ts

@@ -113,4 +113,8 @@ export interface AgentMemoryConfig {
      */
     enabled: boolean;
 }
+/**
+ * Agent kind discriminator.
+ */
+export type AgentKind = "llm" | "realtime";
 //# sourceMappingURL=types.d.ts.map

package/dist/agent/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,EACL,aAAa,EACb,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,eAAe,GAAG,UAAU;IAE5C,EAAE,EAAE,MAAM,CAA2C;IACrD,IAAI,EAAE,MAAM,CAA8D;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAkD;IAEtE;;;;;;;OAOG;IACH,YAAY,EACR,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;IAS/D;;;;OAIG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAsBtC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,eAAe,GAAG,UAAU;IAC3E;;;OAGG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB;;;OAGG;IACH,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,OAAO,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,EACL,aAAa,EACb,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,eAAe,GAAG,UAAU;IAE5C,EAAE,EAAE,MAAM,CAA2C;IACrD,IAAI,EAAE,MAAM,CAA8D;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAkD;IAEtE;;;;;;;OAOG;IACH,YAAY,EACR,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;IAS/D;;;;OAIG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAsBtC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,eAAe,GAAG,UAAU;IAC3E;;;OAGG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB;;;OAGG;IACH,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,OAAO,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,UAAU,CAAC"}

package/dist/agent.d.ts

@@ -1,36 +1,21 @@
 import { LanguageModel, LanguageModelItem, LanguageModelRequestSettings } from "@kernl-sdk/protocol";
-import type { Kernl } from "./kernl/index.js";
 import type { RThreadsListParams, RThreadCreateParams, RThreadGetOptions, RThreadHistoryParams, RThreadUpdateParams } from "./api/resources/threads/types.js";
-import type { Context, UnknownContext } from "./context.js";
-import { Tool } from "./tool/index.js";
-import { BaseToolkit } from "./tool/toolkit.js";
+import type { UnknownContext } from "./context.js";
 import { InputGuardrail, OutputGuardrail, type ResolvedAgentResponse } from "./guardrail.js";
-import { AgentHooks } from "./lifecycle.js";
-import type { AgentMemoryCreate, AgentMemoryUpdate, MemoryListOptions, MemorySearchQuery } from "./memory/index.js";
-import type { AgentConfig, AgentMemoryConfig, AgentOutputType } from "./agent/types.js";
+import { BaseAgent } from "./agent/base.js";
+import type { AgentConfig, AgentOutputType } from "./agent/types.js";
 import type { TextOutput, ThreadExecuteOptions, ThreadExecuteResult, ThreadStreamEvent } from "./thread/types.js";
-export declare class Agent<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput> extends AgentHooks<TContext, TOutput> implements AgentConfig<TContext, TOutput> {
-    private kernl?;
-    id: string;
-    name: string;
-    description?: string;
-    instructions: (context: Context<TContext>) => Promise<string> | string;
-    model: LanguageModel;
-    modelSettings: LanguageModelRequestSettings;
-    toolkits: BaseToolkit<TContext>[];
-    systools: BaseToolkit<TContext>[];
-    memory: AgentMemoryConfig;
-    guardrails: {
+export declare class Agent<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput> extends BaseAgent<TContext, TOutput> implements AgentConfig<TContext, TOutput> {
+    readonly kind = "llm";
+    readonly model: LanguageModel;
+    readonly modelSettings: LanguageModelRequestSettings;
+    readonly guardrails: {
         input: InputGuardrail[];
         output: OutputGuardrail<AgentOutputType>[];
     };
-    output: TOutput;
-    resetToolChoice: boolean;
+    readonly output: TOutput;
+    readonly resetToolChoice: boolean;
     constructor(config: AgentConfig<TContext, TOutput>);
-    /**
-     * Bind this agent to a kernl instance. Called by kernl.register().
-     */
-    bind(kernl: Kernl): void;
     /**
      * Blocking execution - spawns or resumes thread and waits for completion
      *
@@ -47,29 +32,6 @@ export declare class Agent<TContext = UnknownContext, TOutput extends AgentOutpu
      * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
      */
     stream(input: string | LanguageModelItem[], options?: ThreadExecuteOptions<TContext>): AsyncIterable<ThreadStreamEvent>;
-    /**
-     * @internal
-     *
-     * 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;
-    /**
-     * @internal
-     *
-     * 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
-     * together and give agents more options for dealing with tool groups.
-     *
-     * @param context The context to use for filtering tools
-     * @returns Array of all available tools
-     * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
-     */
-    tools(context: Context<TContext>): Promise<Tool<TContext>[]>;
     /**
      * Thread management scoped to this agent.
      *
@@ -83,47 +45,5 @@ export declare class Agent<TContext = UnknownContext, TOutput extends AgentOutpu
         create: (params: Omit<RThreadCreateParams, "agentId" | "model">) => Promise<import("./index.js").Thread>;
         update: (tid: string, patch: RThreadUpdateParams) => Promise<import("./index.js").Thread | null>;
     };
-    /**
-     * Memory management scoped to this agent.
-     *
-     * Provides a simplified API for creating memories with:
-     * - Auto-generated IDs
-     * - Flattened scope fields (namespace, entityId) - agentId is implicit
-     * - Default kind of "semantic"
-     *
-     * @example
-     * ```ts
-     * await agent.memories.create({
-     *   namespace: "user-123",
-     *   collection: "preferences",
-     *   content: { text: "User prefers TypeScript" },
-     * });
-     * ```
-     */
-    get memories(): {
-        /**
-         * List memories scoped to this agent.
-         */
-        list: (params?: Omit<MemoryListOptions, "filter"> & {
-            collection?: string;
-            limit?: number;
-        }) => Promise<import("./memory/index.js").MemoryRecord[]>;
-        /**
-         * Create a new memory scoped to this agent.
-         */
-        create: (params: AgentMemoryCreate) => Promise<import("./memory/index.js").MemoryRecord>;
-        /**
-         * Update an existing memory scoped to this agent.
-         */
-        update: (params: AgentMemoryUpdate) => Promise<import("./memory/index.js").MemoryRecord>;
-        /**
-         * Search memories scoped to this agent.
-         */
-        search: (params: Omit<MemorySearchQuery, "filter"> & {
-            filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
-                scope?: Omit<NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>, "agentId">;
-            };
-        }) => Promise<import("@kernl-sdk/retrieval").SearchHit<import("./memory/index.js").IndexMemoryRecord>[]>;
-    };
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EACb,iBAAiB,EACjB,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,KAAK,CACd,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,eAAe,GAAG,UAAU,CAE9C,SAAQ,SAAS,CAAC,QAAQ,EAAE,OAAO,CACnC,YAAW,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC;IAEzC,QAAQ,CAAC,IAAI,SAAS;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,4BAA4B,CAAC;IAErD,QAAQ,CAAC,UAAU,EAAE;QACnB,KAAK,EAAE,cAAc,EAAE,CAAC;QACxB,MAAM,EAAE,eAAe,CAAC,eAAe,CAAC,EAAE,CAAC;KAC5C,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAqB;IAC7C,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;gBAEtB,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC;IAYlD;;;;;OAKG;IACG,GAAG,CACP,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IAkD/D;;;;;;;OAOG;IACI,MAAM,CACX,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,aAAa,CAAC,iBAAiB,CAAC;IAmDnC;;;;OAIG;IACH,IAAI,OAAO;mBAWI,MAAM,YAAY,iBAAiB;wBAE/B,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC;sBAEpC,MAAM;uBACL,MAAM,WAAW,oBAAoB;yBAEnC,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,OAAO,CAAC;sBASjD,MAAM,SAAS,mBAAmB;MAGnD;CACF"}

package/dist/agent.js

@@ -1,63 +1,23 @@
 import { message, } from "@kernl-sdk/protocol";
 import { Thread } from "./thread/index.js";
-import { memory } from "./tool/index.js";
-import { AgentHooks } from "./lifecycle.js";
-import { randomID } from "@kernl-sdk/shared/lib";
+import { BaseAgent } from "./agent/base.js";
 import { MisconfiguredError, RuntimeError } from "./lib/error.js";
-export class Agent extends AgentHooks {
-    kernl;
-    id;
-    name;
-    description;
-    instructions;
+export class Agent extends BaseAgent {
+    kind = "llm";
     model;
     modelSettings;
-    // actions: ActionSet; /* TODO */
-    toolkits;
-    systools;
-    memory;
     guardrails;
     output = "text";
     resetToolChoice;
     constructor(config) {
-        super();
-        if (config.id.trim() === "") {
-            throw new MisconfiguredError("Agent must have an id.");
-        }
-        this.id = config.id;
-        this.name = config.name;
-        this.description = config.description;
-        this.instructions =
-            typeof config.instructions === "function"
-                ? config.instructions
-                : () => config.instructions;
-        this.model = config.model; // (TODO): include optional default setting for convenience like env.DEFAULT_LLM = "gpt-5"
+        super(config);
+        this.model = config.model;
         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);
-        }
         this.guardrails = config.guardrails ?? { input: [], output: [] };
         if (config.output) {
             this.output = config.output;
         }
         this.resetToolChoice = config.resetToolChoice ?? true;
-        // this.toolUseBehavior = config.toolUseBehavior ?? "run_llm_again";
-    }
-    /**
-     * Bind this agent to a kernl instance. Called by kernl.register().
-     */
-    bind(kernl) {
-        this.kernl = kernl;
-        // initialize system toolkits
-        if (this.memory.enabled) {
-            // safety: system tools only rely on ctx.agent, not ctx.context
-            const toolkit = memory;
-            this.systools.push(toolkit);
-            toolkit.bind(this);
-        }
     }
     /**
      * Blocking execution - spawns or resumes thread and waits for completion
@@ -154,54 +114,6 @@ export class Agent extends AgentHooks {
         thread.append(...items);
         yield* this.kernl.scheduleStream(thread);
     }
-    /**
-     * @internal
-     *
-     * 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) {
-        // 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;
-        }
-        return undefined;
-    }
-    /**
-     * @internal
-     *
-     * 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
-     * together and give agents more options for dealing with tool groups.
-     *
-     * @param context The context to use for filtering tools
-     * @returns Array of all available tools
-     * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
-     */
-    async tools(context) {
-        const all = [];
-        for (const toolkit of [...this.systools, ...this.toolkits]) {
-            all.push(...(await toolkit.list(context)));
-        }
-        const ids = all.map((t) => t.id);
-        const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
-        if (duplicates.length > 0) {
-            throw new MisconfiguredError(`Duplicate tool IDs found: ${[...new Set(duplicates)].join(", ")}`);
-        }
-        return all;
-    }
     /**
      * Thread management scoped to this agent.
      *
@@ -229,82 +141,4 @@ export class Agent extends AgentHooks {
             update: (tid, patch) => kthreads.update(tid, patch),
         };
     }
-    /**
-     * Memory management scoped to this agent.
-     *
-     * Provides a simplified API for creating memories with:
-     * - Auto-generated IDs
-     * - Flattened scope fields (namespace, entityId) - agentId is implicit
-     * - Default kind of "semantic"
-     *
-     * @example
-     * ```ts
-     * await agent.memories.create({
-     *   namespace: "user-123",
-     *   collection: "preferences",
-     *   content: { text: "User prefers TypeScript" },
-     * });
-     * ```
-     */
-    get memories() {
-        if (!this.kernl) {
-            throw new MisconfiguredError(`Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`);
-        }
-        const agentId = this.id;
-        const kmem = this.kernl.memories;
-        return {
-            /**
-             * List memories scoped to this agent.
-             */
-            list: (params) => kmem.list({
-                filter: {
-                    scope: { agentId },
-                    collections: params?.collection ? [params.collection] : undefined,
-                },
-                limit: params?.limit,
-            }),
-            /**
-             * Create a new memory scoped to this agent.
-             */
-            create: (params) => kmem.create({
-                id: params.id ?? `mem_${randomID()}`,
-                scope: {
-                    namespace: params.namespace,
-                    entityId: params.entityId,
-                    agentId,
-                },
-                kind: "semantic",
-                collection: params.collection,
-                content: params.content,
-                wmem: params.wmem,
-                smem: params.smem,
-                timestamp: params.timestamp,
-                metadata: params.metadata,
-            }),
-            /**
-             * Update an existing memory scoped to this agent.
-             */
-            update: (params) => kmem.update({
-                id: params.id,
-                content: params.content,
-                collection: params.collection,
-                wmem: params.wmem,
-                smem: params.smem,
-                metadata: params.metadata,
-            }),
-            /**
-             * Search memories scoped to this agent.
-             */
-            search: (params) => kmem.search({
-                ...params,
-                filter: {
-                    ...params.filter,
-                    scope: {
-                        ...params.filter?.scope,
-                        agentId,
-                    },
-                },
-            }),
-        };
-    }
 }

package/dist/api/resources/agents/agents.d.ts

@@ -1,4 +1,5 @@
-import type { Agent } from "../../../agent.js";
+import { Agent } from "../../../agent.js";
+import type { BaseAgent } from "../../../agent/base.js";
 import type { AgentOutputType } from "../../../agent/types.js";
 import type { UnknownContext } from "../../../context.js";
 import type { TextOutput } from "../../../thread/types.js";
@@ -8,26 +9,29 @@ import type { TextOutput } from "../../../thread/types.js";
  * 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 declare class RAgents {
     private readonly registry;
-    constructor(registry: Map<string, Agent>);
+    constructor(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.
      */
     get<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput>(id: string): Agent<TContext, TOutput> | 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;
     /**
-     * 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>[];
     /**