kernl 0.2.1 → 0.6.0

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjE;;;GAGG;AACH,qBAAa,OAAO,CAAC,QAAQ,GAAG,cAAc;IAC5C;;OAEG;IACH,OAAO,EAAE,QAAQ,CAAC;IAMlB;;;OAGG;IACH,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAEvC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI7B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;gBAwBhB,OAAO,GAAE,QAAyB;IAQ9C;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM;IAevC;;;;;;;;;;;;;;OAcG;IACH,EAAE,IAAI,MAAM;IAIZ;;;;;;;;;;OAUG;IACH,IAAI,IAAI,MAAM;IAId,MAAM,IAAI;QACR,OAAO,EAAE,GAAG,CAAC;KAGd;CAsIF;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjE;;;GAGG;AACH,qBAAa,OAAO,CAAC,QAAQ,GAAG,cAAc;IAC5C;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,QAAQ,CAAC;IAMlB;;;OAGG;IACH,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAEvC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI7B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;gBAyB1B,SAAS,GAAE,MAAgB,EAC3B,OAAO,GAAE,QAAyB;IAUpC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM;IAevC;;;;;;;;;;;;;;OAcG;IACH,EAAE,IAAI,MAAM;IAIZ;;;;;;;;;;OAUG;IACH,IAAI,IAAI,MAAM;IAId,MAAM,IAAI;QACR,OAAO,EAAE,GAAG,CAAC;KAGd;CAsIF;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC"}

package/dist/context.js

@@ -3,6 +3,10 @@
  * execution units.
  */
 export class Context {
+    /**
+     * The namespace that this context belongs to.
+     */
+    namespace;
     /**
      * The inner context object.
      */
@@ -45,7 +49,8 @@ export class Context {
     //  * A map of tool names to whether they have been approved.
     //  */
     // #approvals: Map<string, ApprovalRecord>;
-    constructor(context = {}) {
+    constructor(namespace = "kernl", context = {}) {
+        this.namespace = namespace;
         this.context = context;
         this.approvals = new Map();
         // this.format = format; // (TODO): configure()

package/dist/index.d.ts

@@ -1,5 +1,13 @@
 export { Kernl } from "./kernl";
+export type { KernlOptions, StorageOptions, AgentRegistry, ModelRegistry, } from "./types/kernl";
 export { Agent } from "./agent";
-export type { Context } from "./context";
+export { Context } from "./context";
 export { tool, Toolkit, FunctionToolkit, MCPToolkit } from "./tool";
+export { MCPServerSSE } from "./mcp/sse";
+export { MCPServerStdio } from "./mcp/stdio";
+export { MCPServerStreamableHttp } from "./mcp/http";
+export type { MThread as Thread, MThreadEvent as ThreadEvent, MThreadEventBase as ThreadEventBase, } from "./api/models";
+export type { RThreadsListParams as ThreadsListParams, RThreadGetOptions as ThreadGetOptions, RThreadHistoryParams as ThreadHistoryParams, RThreadCreateParams as ThreadCreateParams, RThreadUpdateParams as ThreadUpdateParams, } from "./api/resources/threads";
+export { THREAD_STATES, type ThreadState, type PublicThreadEvent, } from "./types/thread";
+export type { ThreadStore, NewThread, ThreadUpdate, ThreadFilter, ThreadHistoryOptions, ThreadInclude, ThreadListOptions, SortOrder, KernlStorage, Transaction, } from "./storage";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAGrD,YAAY,EACV,OAAO,IAAI,MAAM,EACjB,YAAY,IAAI,WAAW,EAC3B,gBAAgB,IAAI,eAAe,GACpC,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,kBAAkB,IAAI,iBAAiB,EACvC,iBAAiB,IAAI,gBAAgB,EACrC,oBAAoB,IAAI,mBAAmB,EAC3C,mBAAmB,IAAI,kBAAkB,EACzC,mBAAmB,IAAI,kBAAkB,GAC1C,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,WAAW,GACZ,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,3 +1,10 @@
 export { Kernl } from "./kernl";
 export { Agent } from "./agent";
+export { Context } from "./context";
+// --- tools --
 export { tool, Toolkit, FunctionToolkit, MCPToolkit } from "./tool";
+export { MCPServerSSE } from "./mcp/sse";
+export { MCPServerStdio } from "./mcp/stdio";
+export { MCPServerStreamableHttp } from "./mcp/http";
+// --- thread state enums ---
+export { THREAD_STATES, } from "./types/thread";

package/dist/internal.d.ts

@@ -0,0 +1,4 @@
+export { Thread } from "./thread/thread";
+export type { IThread, ThreadEvent, ThreadEventBase, ThreadEventInner, ThreadSystemEvent, ThreadState, PublicThreadEvent, } from "./types/thread";
+export { THREAD_STATES } from "./types/thread";
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,YAAY,EACV,OAAO,EACP,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/internal.js

@@ -0,0 +1,2 @@
+export { Thread } from "./thread/thread";
+export { THREAD_STATES } from "./types/thread";

package/dist/kernl/index.d.ts

@@ -0,0 +1,3 @@
+export { Kernl } from "./kernl";
+export { ThreadsResource, type ThreadsListParams, type ThreadGetOptions } from "./threads";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kernl/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/kernl/index.js

@@ -0,0 +1,2 @@
+export { Kernl } from "./kernl";
+export { ThreadsResource } from "./threads";

package/dist/kernl/kernl.d.ts

@@ -0,0 +1,64 @@
+import { Agent } from "../agent";
+import { UnknownContext } from "../context";
+import { KernlHooks } from "../lifecycle";
+import type { Thread } from "../thread";
+import type { ResolvedAgentResponse } from "../guardrail";
+import { type KernlStorage } from "../storage";
+import type { KernlOptions } from "../types/kernl";
+import type { ThreadExecuteResult, ThreadStreamEvent } from "../types/thread";
+import type { AgentResponseType } from "../types/agent";
+import { ThreadsResource } from "./threads";
+/**
+ * The kernl - manages agent processes, scheduling, and task lifecycle.
+ *
+ * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
+ * tracing.
+ */
+export declare class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
+    private agents;
+    private models;
+    readonly storage: KernlStorage;
+    athreads: Map<string, Thread<any, any>>;
+    private initPromise;
+    /**
+     * Thread management API.
+     * Provides methods to get, list, and delete threads.
+     */
+    readonly threads: ThreadsResource;
+    constructor(options?: KernlOptions);
+    /**
+     * Registers a new agent with the kernl instance.
+     */
+    register(agent: Agent): void;
+    /**
+     * Spawn a new thread - blocking execution
+     */
+    spawn<TContext, TResponse extends AgentResponseType>(thread: Thread<TContext, TResponse>): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
+    /**
+     * Schedule an existing thread - blocking execution
+     *
+     * NOTE: just blocks for now
+     */
+    schedule<TContext, TResponse extends AgentResponseType>(thread: Thread<TContext, TResponse>): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
+    /**
+     * (TMP) - won't make sense in async scheduling contexts
+     *
+     * Spawn a new thread - streaming execution
+     */
+    spawnStream<TContext, TResponse extends AgentResponseType>(thread: Thread<TContext, TResponse>): AsyncIterable<ThreadStreamEvent>;
+    /**
+     * (TMP) - won't make sense with async scheduling contexts
+     *
+     * Schedule an existing thread - streaming execution
+     */
+    scheduleStream<TContext, TResponse extends AgentResponseType>(thread: Thread<TContext, TResponse>): AsyncIterable<ThreadStreamEvent>;
+    /**
+     * Ensure the underlying storage backend has been initialized.
+     *
+     * This is called lazily on first use so that callers do not need to worry
+     * about calling storage.init() themselves. Safe and idempotent to call
+     * multiple times; concurrent calls share the same initialization promise.
+     */
+    private ensureInitialized;
+}
+//# sourceMappingURL=kernl.d.ts.map

package/dist/kernl/kernl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernl.d.ts","sourceRoot":"","sources":["../../src/kernl/kernl.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;GAKG;AACH,qBAAa,KAAM,SAAQ,UAAU,CAAC,cAAc,EAAE,iBAAiB,CAAC;IACtE,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,MAAM,CAAyC;IAEvD,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAa;IAEpD,OAAO,CAAC,WAAW,CAA8B;IAEjD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;gBAEtB,OAAO,GAAE,YAAiB;IAOtC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAa5B;;OAEG;IACG,KAAK,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EACvD,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAUjE;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EAC1D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAUjE;;;;OAIG;IACI,WAAW,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EAC9D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,aAAa,CAAC,iBAAiB,CAAC;IAUnC;;;;OAIG;IACI,cAAc,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EACjE,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,aAAa,CAAC,iBAAiB,CAAC;IAUnC;;;;;;OAMG;YACW,iBAAiB;CAWhC"}

package/dist/kernl/kernl.js

@@ -0,0 +1,116 @@
+import { KernlHooks } from "../lifecycle";
+import { InMemoryStorage } from "../storage";
+import { ThreadsResource } from "./threads";
+/**
+ * The kernl - manages agent processes, scheduling, and task lifecycle.
+ *
+ * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
+ * tracing.
+ */
+export class Kernl extends KernlHooks {
+    agents = new Map();
+    models = new Map();
+    storage;
+    athreads = new Map(); /* active threads */
+    initPromise = null;
+    /**
+     * Thread management API.
+     * Provides methods to get, list, and delete threads.
+     */
+    threads;
+    constructor(options = {}) {
+        super();
+        this.storage = options.storage?.db ?? new InMemoryStorage();
+        this.storage.bind({ agents: this.agents, models: this.models });
+        this.threads = new ThreadsResource(this.storage.threads);
+    }
+    /**
+     * Registers a new agent with the kernl instance.
+     */
+    register(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);
+        }
+    }
+    /**
+     * Spawn a new thread - blocking execution
+     */
+    async spawn(thread) {
+        await this.ensureInitialized();
+        this.athreads.set(thread.tid, thread);
+        try {
+            return await thread.execute();
+        }
+        finally {
+            this.athreads.delete(thread.tid);
+        }
+    }
+    /**
+     * Schedule an existing thread - blocking execution
+     *
+     * NOTE: just blocks for now
+     */
+    async schedule(thread) {
+        await this.ensureInitialized();
+        this.athreads.set(thread.tid, thread);
+        try {
+            return await thread.execute();
+        }
+        finally {
+            this.athreads.delete(thread.tid);
+        }
+    }
+    /**
+     * (TMP) - won't make sense in async scheduling contexts
+     *
+     * Spawn a new thread - streaming execution
+     */
+    async *spawnStream(thread) {
+        await this.ensureInitialized();
+        this.athreads.set(thread.tid, thread);
+        try {
+            yield* thread.stream();
+        }
+        finally {
+            this.athreads.delete(thread.tid);
+        }
+    }
+    /**
+     * (TMP) - won't make sense with async scheduling contexts
+     *
+     * Schedule an existing thread - streaming execution
+     */
+    async *scheduleStream(thread) {
+        await this.ensureInitialized();
+        this.athreads.set(thread.tid, thread);
+        try {
+            yield* thread.stream();
+        }
+        finally {
+            this.athreads.delete(thread.tid);
+        }
+    }
+    /**
+     * Ensure the underlying storage backend has been initialized.
+     *
+     * This is called lazily on first use so that callers do not need to worry
+     * about calling storage.init() themselves. Safe and idempotent to call
+     * multiple times; concurrent calls share the same initialization promise.
+     */
+    async ensureInitialized() {
+        if (!this.initPromise) {
+            this.initPromise = this.storage.init().catch((error) => {
+                // Allow a retry if initialization fails.
+                this.initPromise = null;
+                throw error;
+            });
+        }
+        await this.initPromise;
+    }
+}

package/dist/kernl/threads.d.ts

@@ -0,0 +1,110 @@
+import type { ThreadStore } from "../storage";
+import type { ThreadResource, PublicThreadEvent } from "../types/thread";
+/**
+ * Threads resource - provides a clean API for managing threads.
+ *
+ * Returns public ThreadResource types, not internal Thread class instances.
+ */
+export declare class ThreadsResource {
+    private store;
+    constructor(store: ThreadStore);
+    /**
+     * Get a thread by ID.
+     *
+     * @param id - Thread ID
+     * @param options - Include options (history included by default)
+     * @returns Thread resource, or null if not found
+     *
+     * @example
+     * ```ts
+     * // With history (default)
+     * const thread = await kernl.threads.get("thread_123");
+     * console.log(thread?.history); // Array of ThreadEvents
+     *
+     * // Without history
+     * const thread = await kernl.threads.get("thread_123", { includeHistory: false });
+     * ```
+     */
+    get(id: string, options?: ThreadGetOptions): Promise<ThreadResource | null>;
+    /**
+     * List threads with optional filtering and pagination.
+     *
+     * Returns thread metadata only (no event history).
+     * Use get() with includeHistory to retrieve full thread details.
+     *
+     * @param params - List parameters
+     * @returns Array of thread resources (metadata only)
+     *
+     * @example
+     * ```ts
+     * // List recent threads for a specific agent
+     * const threads = await kernl.threads.list({
+     *   agentId: "jarvis",
+     *   limit: 20
+     * });
+     * ```
+     */
+    list(params?: ThreadsListParams): Promise<ThreadResource[]>;
+    /**
+     * Delete a thread and all its events.
+     *
+     * @param id - Thread ID
+     *
+     * @example
+     * ```ts
+     * await kernl.threads.delete("thread_123");
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get the event history for a thread.
+     *
+     * Returns only public/client-facing events (excludes internal system events).
+     *
+     * @param id - Thread ID
+     * @returns Array of public thread events
+     *
+     * @example
+     * ```ts
+     * const events = await kernl.threads.history("thread_123");
+     * console.log(events.length); // Number of events in thread
+     * ```
+     */
+    history(id: string): Promise<PublicThreadEvent[]>;
+}
+/**
+ * Parameters for listing threads.
+ */
+export interface ThreadsListParams {
+    /**
+     * Maximum number of threads to return.
+     */
+    limit?: number;
+    /**
+     * Return threads created before this cursor.
+     */
+    before?: string;
+    /**
+     * Return threads created after this cursor.
+     */
+    after?: string;
+    /**
+     * Filter by namespace.
+     */
+    namespace?: string;
+    /**
+     * Filter by agent ID.
+     */
+    agentId?: string;
+}
+/**
+ * Options for getting a thread.
+ */
+export interface ThreadGetOptions {
+    /**
+     * Include full event history in the response.
+     * @default true
+     */
+    includeHistory?: boolean;
+}
+//# sourceMappingURL=threads.d.ts.map

package/dist/kernl/threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threads.d.ts","sourceRoot":"","sources":["../../src/kernl/threads.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,WAAW,CAAC;AAChE,OAAO,KAAK,EAEV,cAAc,EACd,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAGxB;;;;GAIG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAEtC;;;;;;;;;;;;;;;;OAgBG;IACG,GAAG,CACP,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAYjC;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAerE;;;;;;;;;OASG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAIxD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/dist/kernl/threads.js

@@ -0,0 +1,126 @@
+import { isPublicEvent } from "../thread/utils";
+/**
+ * Threads resource - provides a clean API for managing threads.
+ *
+ * Returns public ThreadResource types, not internal Thread class instances.
+ */
+export class ThreadsResource {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Get a thread by ID.
+     *
+     * @param id - Thread ID
+     * @param options - Include options (history included by default)
+     * @returns Thread resource, or null if not found
+     *
+     * @example
+     * ```ts
+     * // With history (default)
+     * const thread = await kernl.threads.get("thread_123");
+     * console.log(thread?.history); // Array of ThreadEvents
+     *
+     * // Without history
+     * const thread = await kernl.threads.get("thread_123", { includeHistory: false });
+     * ```
+     */
+    async get(id, options) {
+        const includeHistory = options?.includeHistory ?? true; // include history by default
+        const thread = await this.store.get(id, { history: includeHistory });
+        if (!thread) {
+            return null;
+        }
+        const history = includeHistory ? await this.store.history(id) : undefined;
+        return ThreadResourceCodec.decode(thread, history);
+    }
+    /**
+     * List threads with optional filtering and pagination.
+     *
+     * Returns thread metadata only (no event history).
+     * Use get() with includeHistory to retrieve full thread details.
+     *
+     * @param params - List parameters
+     * @returns Array of thread resources (metadata only)
+     *
+     * @example
+     * ```ts
+     * // List recent threads for a specific agent
+     * const threads = await kernl.threads.list({
+     *   agentId: "jarvis",
+     *   limit: 20
+     * });
+     * ```
+     */
+    async list(params = {}) {
+        const options = {
+            limit: params.limit,
+            filter: {
+                agentId: params.agentId,
+                namespace: params.namespace,
+            },
+            order: { createdAt: "desc" },
+        };
+        // TODO: Implement cursor-based pagination with before/after
+        const threads = await this.store.list(options);
+        return threads.map((t) => ThreadResourceCodec.decode(t));
+    }
+    /**
+     * Delete a thread and all its events.
+     *
+     * @param id - Thread ID
+     *
+     * @example
+     * ```ts
+     * await kernl.threads.delete("thread_123");
+     * ```
+     */
+    async delete(id) {
+        return this.store.delete(id);
+    }
+    /**
+     * Get the event history for a thread.
+     *
+     * Returns only public/client-facing events (excludes internal system events).
+     *
+     * @param id - Thread ID
+     * @returns Array of public thread events
+     *
+     * @example
+     * ```ts
+     * const events = await kernl.threads.history("thread_123");
+     * console.log(events.length); // Number of events in thread
+     * ```
+     */
+    async history(id) {
+        const events = await this.store.history(id);
+        return events.filter(isPublicEvent);
+    }
+}
+/**
+ * Codec: Convert internal Thread instance to public ThreadResource.
+ */
+const ThreadResourceCodec = {
+    decode(thread, history) {
+        const resource = {
+            tid: thread.tid,
+            namespace: thread.namespace,
+            agentId: thread.agent.id,
+            model: {
+                provider: thread.model.provider,
+                modelId: thread.model.modelId,
+            },
+            context: thread.context.context,
+            parentTaskId: thread.parent?.id ?? null,
+            state: thread.state,
+            createdAt: thread.createdAt,
+            updatedAt: thread.updatedAt,
+        };
+        if (history !== undefined) {
+            // Filter to only public events (exclude internal system events)
+            resource.history = history.filter(isPublicEvent);
+        }
+        return resource;
+    },
+};

package/dist/kernl.d.ts

@@ -2,18 +2,26 @@ import { Agent } from "./agent";
 import { UnknownContext } from "./context";
 import { KernlHooks } from "./lifecycle";
 import type { Thread } from "./thread";
-import type { AgentResponseType } from "./types/agent";
-import type { ThreadExecuteResult, ThreadStreamEvent } from "./types/thread";
 import type { ResolvedAgentResponse } from "./guardrail";
+import { type KernlStorage } from "./storage";
+import { RThreads } from "./api/resources/threads";
+import type { KernlOptions } from "./types/kernl";
+import type { ThreadExecuteResult, ThreadStreamEvent } from "./types/thread";
+import type { AgentResponseType } from "./types/agent";
 /**
- * The kernl - manages agent processes, scheduling, and task lifecycle
+ * The kernl - manages agent processes, scheduling, and task lifecycle.
  *
  * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
  * tracing.
  */
 export declare class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
     private agents;
-    threads: Map<string, Thread<any, any>>;
+    private models;
+    readonly storage: KernlStorage;
+    athreads: Map<string, Thread<any, any>>;
+    private initPromise;
+    readonly threads: RThreads;
+    constructor(options?: KernlOptions);
     /**
      * Registers a new agent with the kernl instance.
      */
@@ -29,16 +37,24 @@ export declare class Kernl extends KernlHooks<UnknownContext, AgentResponseType>
      */
     schedule<TContext, TResponse extends AgentResponseType>(thread: Thread<TContext, TResponse>): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
     /**
-     * (TMP) - probably won't make sense with assync scheduling contexts
+     * (TMP) - won't make sense in async scheduling contexts
      *
      * Spawn a new thread - streaming execution
      */
     spawnStream<TContext, TResponse extends AgentResponseType>(thread: Thread<TContext, TResponse>): AsyncIterable<ThreadStreamEvent>;
     /**
-     * (TMP) - probably won't make sense with assync scheduling contexts
+     * (TMP) - won't make sense with async scheduling contexts
      *
      * Schedule an existing thread - streaming execution
      */
     scheduleStream<TContext, TResponse extends AgentResponseType>(thread: Thread<TContext, TResponse>): AsyncIterable<ThreadStreamEvent>;
+    /**
+     * Ensure the underlying storage backend has been initialized.
+     *
+     * This is called lazily on first use so that callers do not need to worry
+     * about calling storage.init() themselves. Safe and idempotent to call
+     * multiple times; concurrent calls share the same initialization promise.
+     */
+    private ensureInitialized;
 }
 //# sourceMappingURL=kernl.d.ts.map

package/dist/kernl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernl.d.ts","sourceRoot":"","sources":["../src/kernl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;GAKG;AACH,qBAAa,KAAM,SAAQ,UAAU,CAAC,cAAc,EAAE,iBAAiB,CAAC;IACtE,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAa;IAEnD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAK5B;;OAEG;IACG,KAAK,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EACvD,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAKjE;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EAC1D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAIjE;;;;OAIG;IACI,WAAW,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EAC9D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,aAAa,CAAC,iBAAiB,CAAC;IAKnC;;;;OAIG;IACI,cAAc,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EACjE,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,aAAa,CAAC,iBAAiB,CAAC;CAGpC"}
+{"version":3,"file":"kernl.d.ts","sourceRoot":"","sources":["../src/kernl.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,KAAM,SAAQ,UAAU,CAAC,cAAc,EAAE,iBAAiB,CAAC;IACtE,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,MAAM,CAAyC;IAEvD,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAa;IAEpD,OAAO,CAAC,WAAW,CAA8B;IAGjD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;gBAEf,OAAO,GAAE,YAAiB;IAOtC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAa5B;;OAEG;IACG,KAAK,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EACvD,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAUjE;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EAC1D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAUjE;;;;OAIG;IACI,WAAW,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EAC9D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,aAAa,CAAC,iBAAiB,CAAC;IAUnC;;;;OAIG;IACI,cAAc,CAAC,QAAQ,EAAE,SAAS,SAAS,iBAAiB,EACjE,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAClC,aAAa,CAAC,iBAAiB,CAAC;IAUnC;;;;;;OAMG;YACW,iBAAiB;CAWhC"}