kernl 0.2.1 → 0.6.0

package/dist/thread/__tests__/thread.test.js

@@ -47,23 +47,21 @@ describe("Thread", () => {
                 model,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("Hello world"));
+            const thread = new Thread({ agent, input: userMessage("Hello world") });
             const result = await thread.execute();
             // Access private history via type assertion for testing
             const history = thread.history;
             expect(history).toEqual([
-                {
+                expect.objectContaining({
                     kind: "message",
-                    id: expect.any(String),
                     role: "user",
                     content: [{ kind: "text", text: "Hello world" }],
-                },
-                {
+                }),
+                expect.objectContaining({
                     kind: "message",
-                    id: "msg_1",
                     role: "assistant",
                     content: [{ kind: "text", text: "Hello world" }],
-                },
+                }),
             ]);
             expect(thread._tick).toBe(1);
         });
@@ -94,16 +92,15 @@ describe("Thread", () => {
                 model,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("Test input"));
+            const thread = new Thread({ agent, input: userMessage("Test input") });
             await thread.execute();
             const history = thread.history;
             const firstMessage = history[0];
-            expect(firstMessage).toEqual({
+            expect(firstMessage).toEqual(expect.objectContaining({
                 kind: "message",
-                id: expect.any(String),
                 role: "user",
                 content: [{ kind: "text", text: "Test input" }],
-            });
+            }));
         });
         it("should use array input as-is", async () => {
             const model = createMockModel(async (req) => {
@@ -140,11 +137,15 @@ describe("Thread", () => {
                 },
             ];
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, events);
+            const thread = new Thread({ agent, input: events });
             await thread.execute();
             const history = thread.history;
             const firstMessage = history[0];
-            expect(firstMessage).toEqual(events[0]);
+            expect(firstMessage).toEqual(expect.objectContaining({
+                kind: events[0].kind,
+                role: events[0].role,
+                content: events[0].content,
+            }));
         });
     });
     describe("Multi-Turn Execution", () => {
@@ -214,48 +215,45 @@ describe("Thread", () => {
                 ],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("Use the echo tool"));
+            const thread = new Thread({ agent, input: userMessage("Use the echo tool") });
             const result = await thread.execute();
             const history = thread.history;
             expect(history).toEqual([
                 // Initial user message
-                {
+                expect.objectContaining({
                     kind: "message",
-                    id: expect.any(String),
                     role: "user",
                     content: [{ kind: "text", text: "Use the echo tool" }],
-                },
+                }),
                 // Assistant message (tick 1)
-                {
+                expect.objectContaining({
                     kind: "message",
-                    id: "msg_1",
                     role: "assistant",
                     content: [],
-                },
+                }),
                 // Tool call (tick 1)
-                {
+                expect.objectContaining({
                     kind: "tool-call",
                     toolId: "echo",
                     callId: "call_1",
                     state: IN_PROGRESS,
                     arguments: JSON.stringify({ text: "test" }),
-                },
+                }),
                 // Tool result (executed after tick 1)
-                {
+                expect.objectContaining({
                     kind: "tool-result",
                     callId: "call_1",
                     toolId: "echo",
                     state: COMPLETED,
                     result: "Echo: test",
                     error: null,
-                },
+                }),
                 // Final assistant message (tick 2)
-                {
+                expect.objectContaining({
                     kind: "message",
-                    id: "msg_2",
                     role: "assistant",
                     content: [{ kind: "text", text: "Done!" }],
-                },
+                }),
             ]);
             expect(thread._tick).toBe(2);
         });
@@ -349,7 +347,7 @@ describe("Thread", () => {
                 ],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("Start"));
+            const thread = new Thread({ agent, input: userMessage("Start") });
             const result = await thread.execute();
             const history = thread.history;
             // Should have: 1 user msg + 3 assistant msgs + 2 tool calls + 2 tool results = 8 events
@@ -416,19 +414,19 @@ describe("Thread", () => {
                 toolkits: [], // No tools available
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             await thread.execute();
             const history = thread.history;
             // Check that the tool result is an error
             const toolResult = history.find((e) => e.kind === "tool-result");
-            expect(toolResult).toEqual({
+            expect(toolResult).toEqual(expect.objectContaining({
                 kind: "tool-result",
                 callId: "call_1",
                 toolId: "nonexistent",
                 state: FAILED,
                 result: undefined,
                 error: "Tool nonexistent not found",
-            });
+            }));
         });
         it("should handle tool execution error", async () => {
             let callCount = 0;
@@ -498,7 +496,7 @@ describe("Thread", () => {
                 ],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             await thread.execute();
             const history = thread.history;
             const toolResult = history.find((e) => e.kind === "tool-result");
@@ -575,19 +573,19 @@ describe("Thread", () => {
                 toolkits: [new FunctionToolkit({ id: "test-tools", tools: [addTool] })],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("Add 5 and 3"));
+            const thread = new Thread({ agent, input: userMessage("Add 5 and 3") });
             await thread.execute();
             // @ts-expect-error
             const history = thread.history;
             const toolResult = history.find((e) => e.kind === "tool-result");
-            expect(toolResult).toEqual({
+            expect(toolResult).toEqual(expect.objectContaining({
                 kind: "tool-result",
                 callId: "call_1",
                 toolId: "add",
                 state: COMPLETED,
                 result: 8,
                 error: null,
-            });
+            }));
         });
     });
     describe("Parallel Tool Execution", () => {
@@ -670,29 +668,29 @@ describe("Thread", () => {
                 ],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             await thread.execute();
             const history = thread.history;
             // Should have both tool results in history
             const toolResults = history.filter((e) => e.kind === "tool-result");
             expect(toolResults).toHaveLength(2);
             expect(toolResults).toEqual(expect.arrayContaining([
-                {
+                expect.objectContaining({
                     kind: "tool-result",
                     callId: "call_1",
                     toolId: "tool1",
                     state: COMPLETED,
                     result: "Tool1: a",
                     error: null,
-                },
-                {
+                }),
+                expect.objectContaining({
                     kind: "tool-result",
                     callId: "call_2",
                     toolId: "tool2",
                     state: COMPLETED,
                     result: "Tool2: b",
                     error: null,
-                },
+                }),
             ]));
         });
     });
@@ -761,7 +759,7 @@ describe("Thread", () => {
                 ],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             expect(thread._tick).toBe(3);
         });
@@ -829,7 +827,7 @@ describe("Thread", () => {
                 ],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             // Verify the thread executed both turns
             expect(thread._tick).toBe(2);
@@ -864,7 +862,7 @@ describe("Thread", () => {
                 model,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             expect(thread._tick).toBe(1);
         });
@@ -932,7 +930,7 @@ describe("Thread", () => {
                 ],
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             // Should have made 2 calls - first with tool, second without
             expect(thread._tick).toBe(2);
@@ -967,7 +965,7 @@ describe("Thread", () => {
                 responseType: "text",
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             expect(result.response).toBe("Hello, world!");
             expect(thread._tick).toBe(1);
@@ -1010,7 +1008,7 @@ describe("Thread", () => {
                 responseType: responseSchema,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             expect(result.response).toEqual({
                 name: "Alice",
@@ -1054,7 +1052,7 @@ describe("Thread", () => {
                 responseType: responseSchema,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             await expect(thread.execute()).rejects.toThrow(ModelBehaviorError);
         });
         it("should throw ModelBehaviorError when JSON doesn't match schema", async () => {
@@ -1094,7 +1092,7 @@ describe("Thread", () => {
                 responseType: responseSchema,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             await expect(thread.execute()).rejects.toThrow(ModelBehaviorError);
         });
         it("should throw ModelBehaviorError when required fields are missing", async () => {
@@ -1135,7 +1133,7 @@ describe("Thread", () => {
                 responseType: responseSchema,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             await expect(thread.execute()).rejects.toThrow(ModelBehaviorError);
         });
         it("should handle nested structured output", async () => {
@@ -1189,7 +1187,7 @@ describe("Thread", () => {
                 responseType: responseSchema,
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             expect(result.response).toEqual({
                 user: {
@@ -1250,7 +1248,7 @@ describe("Thread", () => {
                 responseType: "text",
             });
             const kernl = new Kernl();
-            const thread = new Thread(kernl, agent, userMessage("test"));
+            const thread = new Thread({ agent, input: userMessage("test") });
             const result = await thread.execute();
             // Should have made 2 calls
             expect(callCount).toBe(2);

package/dist/thread/thread.d.ts

@@ -1,30 +1,71 @@
-import { Kernl } from "../kernl";
 import { Agent } from "../agent";
 import { Context } from "../context";
 import type { Task } from "../task";
+import type { ResolvedAgentResponse } from "../guardrail";
 import { LanguageModel } from "@kernl-sdk/protocol";
-import type { ThreadEvent, ThreadOptions, ThreadExecuteResult, ThreadState, ThreadStreamEvent } from "../types/thread";
+import type { ThreadEvent, ThreadState, ThreadOptions, ThreadEventInner, ThreadStreamEvent, ThreadExecuteResult } from "../types/thread";
 import type { AgentResponseType } from "../types/agent";
-import type { ResolvedAgentResponse } from "../guardrail";
 /**
  * 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 declare class Thread<TContext = unknown, TResponse extends AgentResponseType = "text"> {
-    private kernl;
-    readonly id: string;
+    readonly tid: string;
+    readonly namespace: string;
     readonly agent: Agent<TContext, TResponse>;
     readonly context: Context<TContext>;
     readonly model: LanguageModel;
     readonly parent: Task<TContext> | null;
-    readonly mode: "blocking" | "stream";
-    readonly input: ThreadEvent[];
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    readonly metadata: Record<string, unknown> | null;
     _tick: number;
+    _seq: number;
     state: ThreadState;
+    private cpbuf;
+    private persisted;
     private history;
     private abort?;
-    constructor(kernl: Kernl, agent: Agent<TContext, TResponse>, input: ThreadEvent[], options?: ThreadOptions<TContext>);
+    private storage?;
+    constructor(options: ThreadOptions<TContext, TResponse>);
     /**
-     * Blocking execution loop - runs until terminal state or interruption
+     * Blocking execution - runs until terminal state or interruption
      */
     execute(): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
     /**
@@ -32,15 +73,7 @@ export declare class Thread<TContext = unknown, TResponse extends AgentResponseT
      */
     stream(): AsyncIterable<ThreadStreamEvent>;
     /**
-     * Cancel the running thread
-     */
-    cancel(): void;
-    /**
-     * Append a new event to the thread history
-     */
-    append(event: ThreadEvent): void;
-    /**
-     * 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).
@@ -53,6 +86,25 @@ export declare class Thread<TContext = unknown, TResponse extends AgentResponseT
      * For now, we stream text-delta and tool events, final validation happens in _execute().
      */
     private tick;
+    /**
+     * 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 checkpoint;
+    /**
+     * 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[];
+    /**
+     * Cancel the running thread
+     */
+    cancel(): void;
     /**
      * Perform the actions returned by the model
      */

package/dist/thread/thread.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/thread/thread.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC,OAAO,EAEL,aAAa,EAMd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,WAAW,EACX,aAAa,EACb,mBAAmB,EAEnB,WAAW,EACX,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AASzD;;GAEG;AACH,qBAAa,MAAM,CACjB,QAAQ,GAAG,OAAO,EAClB,SAAS,SAAS,iBAAiB,GAAG,MAAM;IAE5C,OAAO,CAAC,KAAK,CAAQ;IAErB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC;IAI9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,OAAO,CAAsE;IACrF,OAAO,CAAC,KAAK,CAAC,CAAkB;gBAG9B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,EACjC,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC;IAgBnC;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CACtD;IAcD;;OAEG;IACI,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAkBjD;;OAEG;IACH,MAAM;IAIN;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIhC;;;;;OAKG;YACY,QAAQ;IAiDvB;;;;;OAKG;YACY,IAAI;IAwBnB;;OAEG;YACW,cAAc;IA6C5B;;;;OAIG;YACW,YAAY;IA4C1B;;OAEG;YACW,mBAAmB;CA2ClC"}
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/thread/thread.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EAML,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,WAAW,EACX,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAUvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,MAAM,CACjB,QAAQ,GAAG,OAAO,EAClB,SAAS,SAAS,iBAAiB,GAAG,MAAM;IAE5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAIlD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAwE;IAEvF,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAC,CAAc;gBAElB,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC;IA+BvD;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CACtD;IAoBD;;OAEG;IACI,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAuBjD;;;;;OAKG;YACY,QAAQ;IAgEvB;;;;;OAKG;YACY,IAAI;IA8BnB;;;;;OAKG;YACW,UAAU;IAuCxB;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,KAAK,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE;IAiBnD;;OAEG;IACH,MAAM;IAQN;;OAEG;YACW,cAAc;IAyC5B;;;;OAIG;YACW,YAAY;IA2C1B;;OAEG;YACW,mBAAmB;CA2ClC"}