kernl 0.2.0 → 0.6.0

package/src/storage/in-memory.ts

@@ -0,0 +1,372 @@
+/**
+ * In-memory storage implementation for Kernl.
+ *
+ * Pure domain-level - no codecs, schemas, or DB records.
+ *
+ * Defined here so that it can be used as default and for testing.
+ */
+
+import { Thread } from "@/thread";
+import { Context } from "@/context";
+import { STOPPED } from "@kernl-sdk/protocol";
+import { UnimplementedError } from "@kernl-sdk/shared/lib";
+
+import type {
+  KernlStorage,
+  Transaction,
+  ThreadStore,
+  NewThread,
+  ThreadUpdate,
+  ThreadInclude,
+  ThreadListOptions,
+  ThreadHistoryOptions,
+  ThreadFilter,
+  SortOrder,
+} from "@/storage";
+import type { ThreadEvent, ThreadState } from "@/types/thread";
+import type { AgentRegistry, ModelRegistry } from "@/types/kernl";
+
+/**
+ * In-memory storage implementation.
+ */
+export class InMemoryStorage implements KernlStorage {
+  threads: InMemoryThreadStore;
+
+  constructor() {
+    this.threads = new InMemoryThreadStore();
+  }
+
+  bind(registries: { agents: AgentRegistry; models: ModelRegistry }): void {
+    this.threads.bind(registries);
+  }
+
+  async transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T> {
+    throw new UnimplementedError(
+      "Transactions not supported in in-memory storage",
+    );
+  }
+
+  async init(): Promise<void> {
+    // no-op
+  }
+
+  async close(): Promise<void> {
+    // no-op
+  }
+
+  async migrate(): Promise<void> {
+    // no-op
+  }
+}
+
+/**
+ * In-memory thread data (minimal - just what can't be reconstructed from agent/model registries)
+ */
+interface ThreadData {
+  tid: string;
+  namespace: string;
+  agentId: string;
+  model: string; // "provider/modelId"
+  context: unknown;
+  tick: number;
+  state: ThreadState;
+  parentTaskId: string | null;
+  metadata: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * In-memory thread store implementation.
+ */
+export class InMemoryThreadStore implements ThreadStore {
+  private threads = new Map<string, ThreadData>();
+  private events = new Map<string, ThreadEvent[]>(); // tid -> events
+  private registries: { agents: AgentRegistry; models: ModelRegistry } | null =
+    null;
+
+  bind(registries: { agents: AgentRegistry; models: ModelRegistry }): void {
+    this.registries = registries;
+  }
+
+  async get(tid: string, include?: ThreadInclude): Promise<Thread | null> {
+    const data = this.threads.get(tid);
+    if (!data) return null;
+
+    const history = include?.history
+      ? this.filterHistory(tid, include.history)
+      : [];
+
+    try {
+      return this.hydrate(data, history);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  async list(options?: ThreadListOptions): Promise<Thread[]> {
+    let threads = Array.from(this.threads.values());
+
+    // Apply filters
+    if (options?.filter) {
+      threads = this.applyFilters(threads, options.filter);
+    }
+
+    // Apply sorting
+    threads = this.applySorting(threads, options?.order);
+
+    // Apply pagination
+    if (options?.offset) threads = threads.slice(options.offset);
+    if (options?.limit) threads = threads.slice(0, options.limit);
+
+    return threads
+      .map((data) => {
+        try {
+          return this.hydrate(data, []);
+        } catch (error) {
+          // Skip threads with non-existent agent/model (graceful degradation)
+          return null;
+        }
+      })
+      .filter((thread): thread is Thread => thread !== null);
+  }
+
+  async insert(thread: NewThread): Promise<Thread> {
+    const now = new Date();
+    const data: ThreadData = {
+      tid: thread.id,
+      namespace: thread.namespace,
+      agentId: thread.agentId,
+      model: thread.model,
+      context: thread.context ?? {},
+      tick: thread.tick ?? 0,
+      state: thread.state ?? STOPPED,
+      parentTaskId: thread.parentTaskId ?? null,
+      metadata: thread.metadata ?? null,
+      createdAt: thread.createdAt ?? now,
+      updatedAt: thread.updatedAt ?? now,
+    };
+
+    this.threads.set(thread.id, data);
+    this.events.set(thread.id, []);
+
+    return this.hydrate(data, []);
+  }
+
+  async update(tid: string, patch: ThreadUpdate): Promise<Thread> {
+    const data = this.threads.get(tid);
+    if (!data) throw new Error(`Thread ${tid} not found`);
+
+    if (patch.tick !== undefined) data.tick = patch.tick;
+    if (patch.state !== undefined) data.state = patch.state;
+    if (patch.context !== undefined) {
+      // Store raw context value, not the Context wrapper.
+      data.context = patch.context.context;
+    }
+    if (patch.metadata !== undefined) data.metadata = patch.metadata;
+    data.updatedAt = new Date();
+
+    return this.hydrate(data, []);
+  }
+
+  async delete(tid: string): Promise<void> {
+    this.threads.delete(tid);
+    this.events.delete(tid);
+  }
+
+  async history(
+    tid: string,
+    opts?: ThreadHistoryOptions,
+  ): Promise<ThreadEvent[]> {
+    return this.filterHistory(tid, opts);
+  }
+
+  async append(events: ThreadEvent[]): Promise<void> {
+    if (events.length === 0) return;
+
+    // Group by tid
+    const byThread = new Map<string, ThreadEvent[]>();
+    for (const event of events) {
+      if (!byThread.has(event.tid)) byThread.set(event.tid, []);
+      byThread.get(event.tid)!.push(event);
+    }
+
+    // Append to each thread's event log (idempotent on event.id)
+    for (const [tid, newEvents] of Array.from(byThread.entries())) {
+      let existing = this.events.get(tid);
+      if (!existing) {
+        existing = [];
+        this.events.set(tid, existing);
+      }
+
+      const existingIds = new Set(existing.map((e) => e.id));
+
+      for (const event of newEvents) {
+        if (!existingIds.has(event.id)) {
+          existing.push(event);
+        }
+      }
+
+      // Keep sorted by seq
+      existing.sort((a, b) => a.seq - b.seq);
+    }
+  }
+
+  /**
+   * Hydrate a Thread instance from in-memory data.
+   */
+  private hydrate(data: ThreadData, history: ThreadEvent[]): Thread {
+    if (!this.registries) {
+      throw new Error(
+        "Registries must be bound before hydrating threads (call bind() first)",
+      );
+    }
+
+    const agent = this.registries.agents.get(data.agentId);
+    const model = this.registries.models.get(data.model);
+
+    if (!agent || !model) {
+      throw new Error(
+        `Thread ${data.tid} references non-existent agent/model (agent: ${data.agentId}, model: ${data.model})`,
+      );
+    }
+
+    return new Thread({
+      agent,
+      tid: data.tid,
+      context: new Context(data.namespace, data.context),
+      model,
+      history,
+      tick: data.tick,
+      state: data.state,
+      namespace: data.namespace,
+      task: null, // TODO: load from TaskStore when it exists
+      metadata: data.metadata,
+      storage: this, // pass storage reference so resumed thread can persist
+      persisted: true,
+    });
+  }
+
+  /**
+   * Filter and sort event history based on options.
+   */
+  private filterHistory(
+    tid: string,
+    opts?: boolean | ThreadHistoryOptions,
+  ): ThreadEvent[] {
+    let events = this.events.get(tid) ?? [];
+
+    // Handle boolean flag: true = all events, false = no events
+    if (typeof opts === "boolean") {
+      return opts ? [...events] : [];
+    }
+
+    // No options provided = return all events
+    if (opts === undefined) {
+      return [...events];
+    }
+
+    // Apply filters
+    if (opts.after !== undefined) {
+      events = events.filter((e) => e.seq > opts.after!);
+    }
+    if (opts.kinds && opts.kinds.length > 0) {
+      const kinds = new Set(opts.kinds);
+      events = events.filter((e) => kinds.has(e.kind));
+    }
+
+    // Clone before sorting/slicing to avoid mutating the original
+    events = [...events];
+
+    // Apply ordering
+    if (opts.order === "desc") {
+      events.reverse();
+    }
+
+    // Apply limit
+    if (opts.limit !== undefined) {
+      events = events.slice(0, opts.limit);
+    }
+
+    return events;
+  }
+
+  /**
+   * Apply filters to thread list.
+   */
+  private applyFilters(
+    threads: ThreadData[],
+    filter: ThreadFilter,
+  ): ThreadData[] {
+    return threads.filter((thread) => {
+      // Filter by namespace
+      if (filter.namespace !== undefined) {
+        if (thread.namespace !== filter.namespace) return false;
+      }
+
+      // Filter by state
+      if (filter.state !== undefined) {
+        if (Array.isArray(filter.state)) {
+          if (!filter.state.includes(thread.state)) return false;
+        } else {
+          if (thread.state !== filter.state) return false;
+        }
+      }
+
+      // Filter by agentId
+      if (filter.agentId !== undefined) {
+        if (thread.agentId !== filter.agentId) return false;
+      }
+
+      // Filter by parentTaskId
+      if (filter.parentTaskId !== undefined) {
+        if (thread.parentTaskId !== filter.parentTaskId) return false;
+      }
+
+      // Filter by createdAfter
+      if (filter.createdAfter !== undefined) {
+        if (thread.createdAt <= filter.createdAfter) return false;
+      }
+
+      // Filter by createdBefore
+      if (filter.createdBefore !== undefined) {
+        if (thread.createdAt >= filter.createdBefore) return false;
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Apply sorting to thread list.
+   */
+  private applySorting(
+    threads: ThreadData[],
+    order?: { createdAt?: SortOrder; updatedAt?: SortOrder },
+  ): ThreadData[] {
+    if (!order) {
+      // Default: most recent first
+      return threads.sort(
+        (a, b) => b.createdAt.getTime() - a.createdAt.getTime(),
+      );
+    }
+
+    return threads.sort((a, b) => {
+      // Sort by createdAt first if specified
+      if (order.createdAt) {
+        const diff = a.createdAt.getTime() - b.createdAt.getTime();
+        if (diff !== 0) {
+          return order.createdAt === "asc" ? diff : -diff;
+        }
+      }
+
+      // Then by updatedAt if specified
+      if (order.updatedAt) {
+        const diff = a.updatedAt.getTime() - b.updatedAt.getTime();
+        return order.updatedAt === "asc" ? diff : -diff;
+      }
+
+      return 0;
+    });
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Storage contracts for Kernl.
+ *
+ * Core owns these interfaces; storage packages implement them.
+ * (must be defined here to avoid circular deps)
+ */
+
+export type {
+  NewThread,
+  ThreadUpdate,
+  ThreadFilter,
+  ThreadHistoryOptions,
+  ThreadInclude,
+  SortOrder,
+  ThreadListOptions,
+  ThreadStore,
+} from "./thread";
+
+export type { Transaction, KernlStorage } from "./base";
+
+export { InMemoryStorage, InMemoryThreadStore } from "./in-memory";

package/src/storage/thread.ts

@@ -0,0 +1,141 @@
+/**
+ * Thread storage contracts.
+ */
+
+import type { Thread } from "@/thread";
+import type { Context } from "@/context";
+import type { ThreadEvent, ThreadState } from "@/types/thread";
+
+/* ---- Store ---- */
+
+/**
+ * Thread persistence store.
+ */
+export interface ThreadStore {
+  /**
+   * Get a thread by id.
+   *
+   * Optionally include the thread_events.
+   */
+  get(tid: string, include?: ThreadInclude): Promise<Thread | null>;
+
+  /**
+   * List threads matching the filter.
+   */
+  list(options?: ThreadListOptions): Promise<Thread[]>;
+
+  /**
+   * Insert a new thread into the store.
+   */
+  insert(thread: NewThread): Promise<Thread>;
+
+  /**
+   * Update thread runtime state (tick, state, metadata).
+   *
+   * Does NOT mutate the event log, which is append-only.
+   */
+  update(tid: string, patch: ThreadUpdate): Promise<Thread>;
+
+  /**
+   * Delete a thread and cascade to thread_events.
+   */
+  delete(tid: string): Promise<void>;
+
+  /**
+   * Get the event history for a thread.
+   */
+  history(tid: string, options?: ThreadHistoryOptions): Promise<ThreadEvent[]>;
+
+  /**
+   * Append events to the thread history.
+   *
+   * Semantics:
+   * - Guaranteed per-thread ordering via a monotonically increasing `seq`.
+   * - Idempotent on `(tid, event.id)`: duplicate ids MUST NOT create duplicate rows.
+   * - Events maintain insertion order.
+   *
+   * Note:
+   * - Thread class manages monotonic seq and timestamp assignment.
+   */
+  append(events: ThreadEvent[]): Promise<void>;
+}
+
+/* ---- DTOs ---- */
+
+/**
+ * Input for creating a new thread.
+ */
+export interface NewThread {
+  id: string;
+  namespace: string;
+  agentId: string;
+  model: string; // composite key: '{provider}/{modelId}'
+  context?: unknown; // becomes a Context instance in a Thread
+  tick?: number;
+  state?: ThreadState;
+  parentTaskId?: string | null;
+  metadata?: Record<string, unknown> | null;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+/**
+ * Partial update for thread runtime state.
+ *
+ * Only mutable fields are exposed (tick, state, context, metadata).
+ */
+export interface ThreadUpdate {
+  tick?: number;
+  state?: ThreadState;
+  context?: Context;
+  metadata?: Record<string, unknown> | null;
+}
+
+/**
+ * Filter for listing threads.
+ */
+export interface ThreadFilter {
+  namespace?: string;
+  state?: ThreadState | ThreadState[];
+  agentId?: string;
+  parentTaskId?: string;
+  createdAfter?: Date;
+  createdBefore?: Date;
+}
+
+/**
+ * Options for querying thread history.
+ */
+export interface ThreadHistoryOptions {
+  after?: number; // seq number
+  limit?: number;
+  order?: "asc" | "desc";
+  kinds?: string[]; // filter by event kind
+}
+
+/**
+ * Include options for eager loading related data.
+ */
+export interface ThreadInclude {
+  history?: boolean | ThreadHistoryOptions;
+}
+
+/**
+ * Sort order direction.
+ */
+export type SortOrder = "asc" | "desc";
+
+/**
+ * Options for listing threads.
+ */
+export interface ThreadListOptions {
+  filter?: ThreadFilter;
+  include?: ThreadInclude;
+  order?: {
+    createdAt?: SortOrder;
+    updatedAt?: SortOrder;
+  };
+  limit?: number;
+  offset?: number;
+  cursor?: string;
+}

package/src/task.ts

@@ -1,6 +1,5 @@
 import type { Agent } from "@/agent";
 import type { Context, UnknownContext } from "@/context";
-
 import type { Thread } from "@/thread";
 
 /**
@@ -8,7 +7,7 @@ import type { Thread } from "@/thread";
  * Analogous to task_struct in the Linux kernel.
  */
 export class Task<TContext = UnknownContext, TResult = unknown> {
-  pid: string /* process ID - unique identifier for this task */;
+  id: string /* unique identifier for this task (pid) */;
   // tgid: string | null; /* task groupid */
   // prio: TaskPriority;
   instructions:
@@ -17,6 +16,7 @@ export class Task<TContext = UnknownContext, TResult = unknown> {
   // sched: TaskSched; /* scheduling (timers, timeouts, deadlines) */
   state: TaskState /* current state of the task */;
   owner: Agent<TContext> /* agent that currently owns this task */;
+  namespace: string;
 
   context: Context<TContext> /* execution context propagated throughout call graph */;
   // cred: Credentials; /* Effective (overridable) subjective task credentials (COW): */
@@ -35,20 +35,22 @@ export class Task<TContext = UnknownContext, TResult = unknown> {
   // TODO: Deferred fields for later implementation
   // tgid: string;              // Thread group ID
   // limits: TaskLimits;        // Resource limits (max ticks, tokens, timeout)
-  // nsproxy: NamespaceProxy;   // Namespace isolation
+  // nsproxy: NamespaceProxy;   // Namespace isolation (partially implemented via namespace string)
 
-  constructor(init: {
-    pid: string;
+  constructor(options: {
+    id: string;
     instructions: string | ((context: Context<TContext>) => string);
     state: TaskState;
     owner: Agent<TContext>;
     context: Context<TContext>;
+    namespace?: string;
   }) {
-    this.pid = init.pid;
-    this.instructions = init.instructions;
-    this.state = init.state;
-    this.owner = init.owner;
-    this.context = init.context;
+    this.id = options.id;
+    this.instructions = options.instructions;
+    this.state = options.state;
+    this.owner = options.owner;
+    this.context = options.context;
+    this.namespace = options.namespace ?? "kernl";
     this.threads = [];
     this.current = null;
     this.result = null;

package/src/thread/__tests__/fixtures/mock-model.ts

@@ -55,15 +55,13 @@ async function* streamFromResponse(
  * Creates a mock LanguageModel that automatically implements streaming
  * based on the generate() implementation.
  */
-export function createMockModel(
-  generateFn: (req: LanguageModelRequest) => Promise<LanguageModelResponse>,
-): LanguageModel {
+export function createMockModel(generateFn: any): any {
   return {
     spec: "1.0" as const,
     provider: "test",
     modelId: "test-model",
     generate: generateFn,
-    stream: async function* (req: LanguageModelRequest) {
+    stream: async function* (req: any) {
       const response = await generateFn(req);
       yield* streamFromResponse(response);
     },