kernl 0.2.1 → 0.6.0

package/src/thread/thread.ts

@@ -1,86 +1,144 @@
 import assert from "assert";
 
-import { Kernl } from "@/kernl";
 import { Agent } from "@/agent";
 import { Context } from "@/context";
 import type { Task } from "@/task";
+import type { ResolvedAgentResponse } from "@/guardrail";
+import type { ThreadStore } from "@/storage";
+
+import { logger } from "@/lib/logger";
 
 import {
-  ToolCall,
-  LanguageModel,
-  LanguageModelRequest,
-  LanguageModelItem,
   FAILED,
   RUNNING,
   STOPPED,
+  message,
+  ToolCall,
+  LanguageModel,
+  LanguageModelItem,
+  LanguageModelRequest,
 } from "@kernl-sdk/protocol";
 import { randomID, filter } from "@kernl-sdk/shared/lib";
 
 import type {
   ActionSet,
   ThreadEvent,
+  ThreadState,
   ThreadOptions,
+  ThreadEventInner,
+  ThreadStreamEvent,
   ThreadExecuteResult,
   PerformActionsResult,
-  ThreadState,
-  ThreadStreamEvent,
 } from "@/types/thread";
 import type { AgentResponseType } from "@/types/agent";
-import type { ResolvedAgentResponse } from "@/guardrail";
 
 import {
+  tevent,
   notDelta,
-  getFinalResponse,
   getIntentions,
+  getFinalResponse,
   parseFinalResponse,
 } from "./utils";
 
 /**
  * A thread drives the execution loop for an agent.
+ *
+ * Ground principles:
+ *
+ *   1) Event log is source of truth.
+ *      - Persistent storage (e.g. Postgres) is treated as an append-only per-thread log of `ThreadEvent`s:
+ *        monotonic `seq`, no gaps, no updates/deletes.
+ *      - `Thread.state`, `tick`, etc. are projections of that log, not an alternative source of truth.
+ *
+ *   2) Single writer per thread.
+ *      - At most one executor is allowed for a given `tid` at a time.
+ *      - Callers are responsible for enforcing this (e.g. locking/versioning) so two processes cannot
+ *        interleave or race on `seq` or state.
+ *
+ *   3) Persist before use / observation.
+ *      - Before an event can:
+ *        - influence a future tick (i.e. be part of `history` fed back into the model), or
+ *        - be considered “delivered” to a client,
+ *        it SHOULD be durably written to storage when storage is configured.
+ *
+ *   4) Transaction boundaries match semantic steps.
+ *      - The intended strategy is to buffer within a tick, then atomically persist all new events + state
+ *        at the end of `tick()`.
+ *      - After a crash, you only ever see whole ticks or none, never half a tick, from the store’s
+ *        point of view.
+ *
+ *   5) Recovery is replay.
+ *      - On restart, callers rebuild a `Thread` from the stored event log (plus optional snapshots).
+ *      - Any incomplete tick or pending tool call is handled by a clear, deterministic policy at a
+ *        higher layer (e.g. re-run, mark failed, or require manual intervention).
+ *
+ * On storage failures:
+ *
+ *   “If storage is configured, it is authoritative” → fail hard on persist errors rather than
+ *   treating persistence as best-effort.
+ *
+ *   If a storage implementation is present, `persist(...)` is expected to throw on failure, and
+ *   that error should bubble out of `_execute()` / `stream()` and stop the thread.
  */
 export class Thread<
   TContext = unknown,
   TResponse extends AgentResponseType = "text",
 > {
-  private kernl: Kernl;
-
-  readonly id: string;
+  readonly tid: string;
+  readonly namespace: string;
   readonly agent: Agent<TContext, TResponse>;
   readonly context: Context<TContext>;
   readonly model: LanguageModel; /* inherited from the agent unless specified */
   readonly parent: Task<TContext> | null; /* parent task which spawned this thread */
-  readonly mode: "blocking" | "stream"; /* TODO */
-  readonly input: ThreadEvent[]; /* the initial input for the thread */
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly metadata: Record<string, unknown> | null;
   // readonly stats: ThreadMetrics;
 
   /* state */
-  _tick: number;
+  _tick: number; /* number of LLM roundtrips */
+  _seq: number; /* monotonic event sequence */
   state: ThreadState;
-  private history: ThreadEvent[] /* events generated during this thread's execution */;
+  private cpbuf: ThreadEvent[]; /* checkpoint buffer - events pending persistence */
+  private persisted: boolean; /* indicates thread was hydrated from storage */
+  private history: ThreadEvent[] /* history representing the event log for the thread */;
+
   private abort?: AbortController;
+  private storage?: ThreadStore;
+
+  constructor(options: ThreadOptions<TContext, TResponse>) {
+    this.tid = options.tid ?? `tid_${randomID()}`;
+    this.namespace = options.namespace ?? "kernl";
+    this.agent = options.agent;
+    this.context =
+      options.context ?? new Context<TContext>(this.namespace, {} as TContext);
+    this.parent = options.task ?? null;
+    this.model = options.model ?? options.agent.model;
+    this.storage = options.storage;
+    this.createdAt = options.createdAt ?? new Date();
+    this.updatedAt = options.updatedAt ?? new Date();
+    this.metadata = options.metadata ?? null;
+
+    this._tick = options.tick ?? 0;
+    this._seq = -1;
+    this.state = options.state ?? STOPPED;
+    this.cpbuf = [];
+    this.persisted = options.persisted ?? false;
+    this.history = options.history ?? [];
+
+    // seek to latest seq (not persisted)
+    if (this.history.length > 0) {
+      this._seq = Math.max(...this.history.map((e) => e.seq));
+    }
 
-  constructor(
-    kernl: Kernl,
-    agent: Agent<TContext, TResponse>,
-    input: ThreadEvent[],
-    options?: ThreadOptions<TContext>,
-  ) {
-    this.id = `tid_${randomID()}`;
-    this.agent = agent;
-    this.context = options?.context ?? new Context<TContext>();
-    this.kernl = kernl;
-    this.parent = options?.task ?? null;
-    this.model = options?.model ?? agent.model;
-    this.mode = "blocking"; // (TODO): add streaming
-    this.input = input;
-
-    this._tick = 0;
-    this.state = STOPPED;
-    this.history = input;
+    // append initial input if provided (for new threads)
+    if (options.input && options.input.length > 0) {
+      this.append(...options.input);
+    }
   }
 
   /**
-   * Blocking execution loop - runs until terminal state or interruption
+   * Blocking execution - runs until terminal state or interruption
    */
   async execute(): Promise<
     ThreadExecuteResult<ResolvedAgentResponse<TResponse>>
@@ -89,10 +147,16 @@ export class Thread<
       // just consume the stream (already in history in _execute())
     }
 
-    // extract final response from accumulated history
-    const text = getFinalResponse(this.history);
-    assert(text, "_execute continues until text !== null"); // (TODO): consider preventing infinite loops here
+    // filter for language model items
+    const items = this.history
+      .filter((e) => e.kind !== "system")
+      .map((e) => {
+        const { tid, seq, timestamp, metadata, ...item } = e;
+        return item as LanguageModelItem;
+      });
 
+    const text = getFinalResponse(items);
+    assert(text, "_execute continues until text !== null"); // (TODO): consider preventing infinite loops here
     const parsed = parseFinalResponse(text, this.agent.responseType);
 
     return { response: parsed, state: this.state };
@@ -109,6 +173,10 @@ export class Thread<
     this.state = RUNNING;
     this.abort = new AbortController();
 
+    await this.checkpoint(); /* c1: persist RUNNING state + initial input */
+
+    yield { kind: "stream-start" }; // always yield start immediately
+
     try {
       yield* this._execute();
     } catch (err) {
@@ -116,66 +184,68 @@ export class Thread<
     } finally {
       this.state = STOPPED;
       this.abort = undefined;
+      await this.checkpoint(); /* c4: final checkpoint - persist STOPPED state */
     }
   }
 
   /**
-   * Cancel the running thread
-   */
-  cancel() {
-    this.abort?.abort();
-  }
-
-  /**
-   * Append a new event to the thread history
-   */
-  append(event: ThreadEvent): void {
-    this.history.push(event);
-  }
-
-  /**
-   * Main execution loop - always yields events, callers can propagate or discard (as in execute())
+   * Main execution loop - always yields events, callers can propagate or discard.
    *
    * NOTE: Streaming structured output deferred for now. Prioritizing correctness + simplicity,
    * and unclear what use cases there would actually be for streaming a structured output (other than maybe gen UI).
    */
   private async *_execute(): AsyncGenerator<ThreadStreamEvent, void> {
     for (;;) {
+      let err = false;
+
       if (this.abort?.signal.aborted) {
         return;
       }
 
       const events = [];
       for await (const e of this.tick()) {
+        if (e.kind === "error") {
+          err = true;
+          logger.error(e.error); // (TODO): onError callback in options
+        }
         // we don't want deltas in the history
         if (notDelta(e)) {
           events.push(e);
-          this.history.push(e);
+          this.append(e);
         }
         yield e;
       }
 
-      // if model returns a message with no action intentions -> terminal state
+      // if an error event occurred → terminate
+      if (err) {
+        return;
+      }
+
+      // if model returns a message with no action intentions → terminal state
       const intentions = getIntentions(events);
       if (!intentions) {
         const text = getFinalResponse(events);
         if (!text) continue; // run again, policy-dependent? (how to ensure no infinite loop here?)
 
+        await this.checkpoint(); /* c2: terminal tick - no tool calls */
+
         // await this.agent.runOutputGuardails(context, state);
         // this.kernl.emit("thread.terminated", context, output);
         return;
       }
 
-      // perform actions intended by the model
+      // perform intended actions
       const { actions, pendingApprovals } =
         await this.performActions(intentions);
 
-      // yield action events
+      // append + yield action events
       for (const a of actions) {
-        this.history.push(a);
+        this.append(a);
         yield a;
       }
 
+      await this.checkpoint(); /* c3: tick complete */
+
       if (pendingApprovals.length > 0) {
         // publish a batch approval request containing all of them
         //
@@ -202,22 +272,108 @@ export class Thread<
 
     const req = await this.prepareModelRequest(this.history);
 
-    // try to stream if model supports it
-    if (this.model.stream) {
-      const stream = this.model.stream(req);
-      for await (const event of stream) {
-        yield event; // [text-delta, tool-call, message, reasoning, ...]
-      }
-    } else {
-      // fallback: blocking generate, yield events as batch
-      const res = await this.model.generate(req);
-      for (const event of res.content) {
-        yield event;
+    try {
+      if (this.model.stream) {
+        const stream = this.model.stream(req);
+        for await (const event of stream) {
+          yield event; // [text-delta, tool-call, message, reasoning, ...]
+        }
+      } else {
+        // fallback: blocking generate, yield events as batch
+        const res = await this.model.generate(req);
+        for (const event of res.content) {
+          yield event;
+        }
+        // (TODO): this.stats.usage.add(res.usage)
       }
-      // (TODO): track usage (this.stats.usage.add(res.usage))
+    } catch (error) {
+      yield {
+        kind: "error",
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+
+  /**
+   * Persist current thread state to storage.
+   *
+   * - If storage is configured, it is authoritative - failures throw and halt execution.
+   * - No-op if storage is not configured.
+   */
+  private async checkpoint(): Promise<void> {
+    if (!this.storage) {
+      logger.warn(
+        "thread: storage is not configured, thread will not be persisted",
+      );
+      return;
     }
+
+    // insert thread record on first persist for new threads
+    if (!this.persisted) {
+      await this.storage.insert({
+        id: this.tid,
+        namespace: this.namespace,
+        agentId: this.agent.id,
+        parentTaskId: this.parent?.id ?? null,
+        model: `${this.model.provider}/${this.model.modelId}`,
+        context: this.context.context,
+        tick: this._tick,
+        state: this.state,
+        metadata: this.metadata,
+      });
+      this.persisted = true;
+    }
+
+    // append + drain events from checkpoint buffer
+    if (this.cpbuf.length > 0) {
+      await this.storage.append(this.cpbuf);
+      this.cpbuf = [];
+    }
+
+    // update thread state
+    await this.storage.update(this.tid, {
+      state: this.state,
+      tick: this._tick,
+      context: this.context,
+      metadata: this.metadata,
+    });
   }
 
+  /**
+   * Append one or more items to history + enrich w/ runtime headers.
+   *
+   * Core rule:
+   *
+   * > An event becomes a ThreadEvent (and gets seq/timestamp) exactly when it is appended to history. <
+   */
+  append(...items: ThreadEventInner[]): ThreadEvent[] {
+    const events: ThreadEvent[] = [];
+    for (const item of items) {
+      const seq = ++this._seq;
+      const e = tevent({
+        tid: this.tid,
+        seq,
+        kind: item.kind,
+        data: item,
+      });
+      this.history.push(e);
+      this.cpbuf.push(e);
+      events.push(e);
+    }
+    return events;
+  }
+
+  /**
+   * Cancel the running thread
+   */
+  cancel() {
+    this.abort?.abort();
+  }
+
+  // ----------------------------
+  // utils
+  // ----------------------------
+
   /**
    * Perform the actions returned by the model
    */
@@ -239,7 +395,7 @@ export class Thread<
     const toolEvents = await this.executeTools(intentions.toolCalls);
     // const mcpEvents = await this.executeMCPRequests(actions.mcpRequests);
 
-    const actions: ThreadEvent[] = [];
+    const actions: ThreadEventInner[] = [];
     const pendingApprovals: ToolCall[] = [];
 
     // (TODO): clean this - approval tracking should be handled differently
@@ -249,12 +405,8 @@ export class Thread<
         (e.state as any) === "requires_approval" // (TODO): fix this
       ) {
         // Find the original tool call for this pending approval
-        const originalCall = intentions.toolCalls.find(
-          (call) => call.callId === e.callId,
-        );
-        if (originalCall) {
-          pendingApprovals.push(originalCall);
-        }
+        const call = intentions.toolCalls.find((c) => c.callId === e.callId);
+        call && pendingApprovals.push(call);
       } else {
         actions.push(e);
       }
@@ -271,7 +423,7 @@ export class Thread<
    *
    * TODO: refactor into actions system
    */
-  private async executeTools(calls: ToolCall[]): Promise<ThreadEvent[]> {
+  private async executeTools(calls: ToolCall[]): Promise<ThreadEventInner[]> {
     return await Promise.all(
       calls.map(async (call: ToolCall) => {
         try {
@@ -288,7 +440,7 @@ export class Thread<
 
           // (TMP) - passing the approval status through the context until actions system
           // is refined
-          const ctx = new Context(this.context.context);
+          const ctx = new Context(this.namespace, this.context.context);
           ctx.approve(call.callId); // mark this call as approved
           const res = await tool.invoke(ctx, call.arguments, call.callId);
 
@@ -301,7 +453,6 @@ export class Thread<
             error: res.error,
           };
         } catch (error) {
-          // Handles both tool not found AND any execution errors
           return {
             kind: "tool-result" as const,
             callId: call.callId,
@@ -325,32 +476,32 @@ export class Thread<
       ...this.agent.modelSettings,
     };
 
-    // // TODO: what do we want to do with this?
+    // (TODO): what do we want to do with this?
     // settings = maybeResetToolChoice(this.agent, this.state.toolUse, settings);
 
     const system = await this.agent.instructions(this.context);
+
+    // filter for model items + strip event headers
+    const items = history
+      .filter((e) => e.kind !== "system") // system events are not sent to model
+      .map((event) => {
+        const { id, tid, seq, timestamp, metadata, ...item } = event;
+        return item as LanguageModelItem;
+      });
+
     const input: LanguageModelItem[] = system
-      ? [
-          // (TODO): add message(role, text) helper
-          {
-            kind: "message",
-            id: randomID(),
-            role: "system",
-            content: [{ kind: "text", text: system }],
-          },
-          ...history, // (TODO): filter for LanguageModelItem specifically - there may be other thread events
-        ]
-      : history;
-
-    // TODO: apply custom input filters - arguably want global + agent-scoped -> apply in a middleware-like chain
+      ? [message({ role: "system", text: system }), ...items]
+      : items;
+
+    // (TODO): apply custom input filters - arguably want global + agent-scoped -> apply in a middleware-like chain
     // const filtered = await applyInputFilters(inputWithSystem, context);
 
     const filtered = input;
 
     // serialize action repertoire
-    const allTools = await this.agent.tools(this.context);
+    const all = await this.agent.tools(this.context);
     const enabled = await filter(
-      allTools,
+      all,
       async (tool) => await tool.isEnabled(this.context, this.agent),
     );
     const tools = enabled.map((tool) => tool.serialize());

package/src/thread/utils.ts

@@ -3,18 +3,61 @@ import { ZodType } from "zod";
 import type { ResolvedAgentResponse } from "@/guardrail";
 
 /* lib */
-import { json } from "@kernl-sdk/shared/lib";
-import { ToolCall } from "@kernl-sdk/protocol";
+import { json, randomID } from "@kernl-sdk/shared/lib";
+import { ToolCall, LanguageModelItem } from "@kernl-sdk/protocol";
 import { ModelBehaviorError } from "@/lib/error";
 
 /* types */
 import type { AgentResponseType } from "@/types/agent";
-import type { ThreadEvent, ThreadStreamEvent, ActionSet } from "@/types/thread";
+import type {
+  ThreadEvent,
+  ThreadEventBase,
+  ThreadStreamEvent,
+  ActionSet,
+  PublicThreadEvent,
+} from "@/types/thread";
 
 /**
- * Check if an event represents an intention (action to be performed)
+ * Create a ThreadEvent from a LanguageModelItem with thread metadata.
+ *
+ * @example
+ * ```typescript
+ * tevent({
+ *   kind: "message",
+ *   seq: 0,
+ *   tid: "tid_123",
+ *   data: message({role: "user", text: "hello"}),
+ * })
+ * // → {kind: "message", role: "user", content: [...], id: "message:msg_xyz", tid: "tid_123", seq: 0, timestamp: Date}
+ * ```
+ */
+export function tevent(event: {
+  seq: number;
+  tid: string;
+  kind: ThreadEvent["kind"];
+  data: LanguageModelItem | null; // null for system events
+  id?: string;
+  timestamp?: Date;
+  metadata?: Record<string, unknown>;
+}): ThreadEvent {
+  const iid = event.data ? event.data.id : undefined;
+  const defaultId = iid ? `${event.kind}:${iid}` : randomID();
+
+  return {
+    ...(event.data || {}),
+    kind: event.kind,
+    id: event.id ?? defaultId,
+    tid: event.tid,
+    seq: event.seq,
+    timestamp: event.timestamp ?? new Date(),
+    metadata: event.metadata ?? {},
+  } as ThreadEvent;
+}
+
+/**
+ * Check if an event is a tool call
  */
-export function isActionIntention(event: ThreadEvent): event is ToolCall {
+export function isActionIntention(event: LanguageModelItem): event is ToolCall {
   return event.kind === "tool-call";
 }
 
@@ -22,7 +65,7 @@ export function isActionIntention(event: ThreadEvent): event is ToolCall {
  * Extract action intentions from a list of events.
  * Returns ActionSet if there are any tool calls, null otherwise.
  */
-export function getIntentions(events: ThreadEvent[]): ActionSet | null {
+export function getIntentions(events: LanguageModelItem[]): ActionSet | null {
   const toolCalls = events.filter(isActionIntention);
   return toolCalls.length > 0 ? { toolCalls } : null;
 }
@@ -31,7 +74,7 @@ export function getIntentions(events: ThreadEvent[]): ActionSet | null {
  * Check if an event is NOT a delta/start/end event (i.e., a complete item).
  * Returns true for complete items: Message, Reasoning, ToolCall, ToolResult
  */
-export function notDelta(event: ThreadStreamEvent): event is ThreadEvent {
+export function notDelta(event: ThreadStreamEvent): event is LanguageModelItem {
   switch (event.kind) {
     case "message":
     case "reasoning":
@@ -46,16 +89,36 @@ export function notDelta(event: ThreadStreamEvent): event is ThreadEvent {
 }
 
 /**
- * Extract the final text response from a list of events.
+ * Check if an event is public/client-facing (not internal).
+ * Filters out internal system events that clients don't need.
+ */
+export function isPublicEvent(event: ThreadEvent): event is PublicThreadEvent {
+  switch (event.kind) {
+    case "message":
+    case "reasoning":
+    case "tool-call":
+    case "tool-result":
+      return true;
+
+    case "system":
+      return false;
+
+    default:
+      return false;
+  }
+}
+
+/**
+ * Extract the final text response from a list of items.
  * Returns null if no assistant message with text content is found.
  */
-export function getFinalResponse(events: ThreadEvent[]): string | null {
+export function getFinalResponse(items: LanguageModelItem[]): string | null {
   // Scan backwards for the last assistant message
-  for (let i = events.length - 1; i >= 0; i--) {
-    const event = events[i];
-    if (event.kind === "message" && event.role === "assistant") {
+  for (let i = items.length - 1; i >= 0; i--) {
+    const item = items[i];
+    if (item.kind === "message" && item.role === "assistant") {
       // Extract text from content parts
-      for (const part of event.content) {
+      for (const part of item.content) {
         if (part.kind === "text") {
           return part.text;
         }

package/src/tool/__tests__/fixtures.ts

@@ -6,7 +6,7 @@ import { tool, HostedTool } from "../tool";
  * Create a minimal mock context for testing
  */
 export const mockContext = <T = any>(data?: T): Context<T> => {
-  return new Context<T>(data ?? ({} as T));
+  return new Context<T>("test-namespace", data ?? ({} as T));
 };
 
 /**