kernl 0.12.2 → 0.12.4

package/.turbo/turbo-build.log

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

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @kernl/core
 
+## 0.12.4
+
+### Patch Changes
+
+- 296c377: Make tool execute method public for direct invocation
+
+## 0.12.3
+
+### Patch Changes
+
+- 884e513: Align with @ai-sdk/provider v3 stable release
+  - Update LanguageModelUsage to nested structure (inputTokens.total, outputTokens.total, etc.)
+  - Update LanguageModelFinishReason to object with unified and raw properties
+  - Rename LanguageModelWarning to SharedWarning with updated structure
+  - Update tool type from "provider-defined" to "provider"
+  - Bump @ai-sdk peer dependencies from beta to stable (^3.0.3)
+
+- 0576a77: Fix model not being updated when resuming thread from storage
+- Updated dependencies [884e513]
+  - @kernl-sdk/protocol@0.5.1
+  - @kernl-sdk/retrieval@0.1.10
+
 ## 0.12.2
 
 ### Patch Changes

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"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,EAAW,KAAK,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;IAyD/D;;;;;;;OAOG;IACI,MAAM,CACX,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,aAAa,CAAC,iBAAiB,CAAC;IA0DnC;;;;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"}
+{"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,EAAW,KAAK,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;IA4D/D;;;;;;;OAOG;IACI,MAAM,CACX,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,aAAa,CAAC,iBAAiB,CAAC;IA6DnC;;;;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

@@ -27,14 +27,11 @@ export class Agent extends BaseAgent {
      * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
      */
     async run(input, options) {
+        let thread = null;
         if (!this.kernl) {
             throw new MisconfiguredError(`Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`);
         }
-        const items = typeof input === "string"
-            ? [message({ role: "user", text: input })]
-            : input;
         const tid = options?.threadId;
-        let thread = null;
         if (tid) {
             // no concurrent execution of same thread - correctness contract
             // TODO: race condition - need to check again after async storage.get()
@@ -48,6 +45,9 @@ export class Agent extends BaseAgent {
                 }));
             }
         }
+        const items = typeof input === "string"
+            ? [message({ role: "user", text: input })]
+            : input;
         // create new thread if not found in storage or no tid provided
         if (!thread) {
             const ctx = options?.context
@@ -69,6 +69,9 @@ export class Agent extends BaseAgent {
         if (options?.context) {
             thread.context.context = options.context;
         }
+        if (options?.model) {
+            thread.model = options.model;
+        }
         thread.append(...items);
         return this.kernl.schedule(thread);
     }
@@ -124,6 +127,9 @@ export class Agent extends BaseAgent {
         if (options?.context) {
             thread.context.context = options.context;
         }
+        if (options?.model) {
+            thread.model = options.model;
+        }
         thread.append(...items);
         yield* this.kernl.scheduleStream(thread);
     }

package/dist/lib/env.d.ts

@@ -7,11 +7,11 @@ import { z } from "zod";
  */
 declare const envSchema: z.ZodObject<{
     LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
-        error: "error";
         trace: "trace";
         debug: "debug";
         info: "info";
         warn: "warn";
+        error: "error";
         fatal: "fatal";
     }>>;
     KERNL_LOG_MODEL_DATA: z.ZodPipe<z.ZodOptional<z.ZodEnum<{
@@ -31,7 +31,7 @@ declare const envSchema: z.ZodObject<{
  * console.log(env.LOG_LEVEL);
  */
 export declare const env: {
-    LOG_LEVEL: "error" | "trace" | "debug" | "info" | "warn" | "fatal";
+    LOG_LEVEL: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
     KERNL_LOG_MODEL_DATA: boolean;
     KERNL_LOG_TOOL_DATA: boolean;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../../src/thread/__tests__/mock.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EAGrB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,CAAC,QAAQ,UAAU;IAC3B,QAAQ,CAAC,OAAO,gBAAgB;IAE1B,QAAQ,CACZ,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAgC1B,MAAM,CACX,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,wBAAwB,CAAC;IAK1C;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../../src/thread/__tests__/mock.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EAGrB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,CAAC,QAAQ,UAAU;IAC3B,QAAQ,CAAC,OAAO,gBAAgB;IAE1B,QAAQ,CACZ,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAyC1B,MAAM,CACX,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,wBAAwB,CAAC;IAK1C;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB"}

package/dist/thread/__tests__/mock.js

@@ -26,13 +26,22 @@ export class MockLanguageModel {
             },
         ];
         // Return with fake usage stats
+        const tokens = this.countTokens(userText);
         return {
             content,
-            finishReason: "stop",
+            finishReason: { unified: "stop", raw: "stop" },
             usage: {
-                inputTokens: this.countTokens(userText),
-                outputTokens: this.countTokens(userText),
-                totalTokens: this.countTokens(userText) * 2,
+                inputTokens: {
+                    total: tokens,
+                    noCache: tokens,
+                    cacheRead: undefined,
+                    cacheWrite: undefined,
+                },
+                outputTokens: {
+                    total: tokens,
+                    text: tokens,
+                    reasoning: undefined,
+                },
             },
             warnings: [],
         };

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

@@ -936,6 +936,247 @@ describe("Thread", () => {
             expect(thread._tick).toBe(2);
         });
     });
+    describe("Event Sequencing", () => {
+        it("should assign incrementing seq values to all persisted events", async () => {
+            let callCount = 0;
+            const model = createMockModel(async (req) => {
+                callCount++;
+                if (callCount === 1) {
+                    return {
+                        content: [
+                            {
+                                kind: "message",
+                                id: "msg_1",
+                                role: "assistant",
+                                content: [],
+                            },
+                            {
+                                kind: "tool.call",
+                                toolId: "echo",
+                                state: IN_PROGRESS,
+                                callId: "call_1",
+                                arguments: JSON.stringify({ text: "test" }),
+                            },
+                        ],
+                        finishReason: "stop",
+                        usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                        warnings: [],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            kind: "message",
+                            id: "msg_2",
+                            role: "assistant",
+                            content: [{ kind: "text", text: "Done!" }],
+                        },
+                    ],
+                    finishReason: "stop",
+                    usage: { inputTokens: 4, outputTokens: 2, totalTokens: 6 },
+                    warnings: [],
+                };
+            });
+            const echoTool = tool({
+                id: "echo",
+                description: "Echoes input",
+                parameters: z.object({ text: z.string() }),
+                execute: async (ctx, { text }) => `Echo: ${text}`,
+            });
+            const agent = new Agent({
+                id: "test",
+                name: "Test",
+                instructions: "Test agent",
+                model,
+                toolkits: [
+                    new FunctionToolkit({ id: "test-tools", tools: [echoTool] }),
+                ],
+            });
+            const thread = new Thread({ agent, input: userMessage("test") });
+            await thread.execute();
+            const history = thread.history;
+            // Verify all events have seq values
+            for (const event of history) {
+                expect(event).toHaveProperty("seq");
+                expect(typeof event.seq).toBe("number");
+            }
+            // Verify seq values increment: 0, 1, 2, 3, 4
+            const seqValues = history.map((e) => e.seq);
+            expect(seqValues).toEqual([0, 1, 2, 3, 4]);
+        });
+        it("should assign consistent tid to all events in a thread", async () => {
+            const model = createMockModel(async (req) => {
+                return {
+                    content: [
+                        {
+                            kind: "message",
+                            id: "msg_1",
+                            role: "assistant",
+                            content: [{ kind: "text", text: "Hello" }],
+                        },
+                    ],
+                    finishReason: "stop",
+                    usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                    warnings: [],
+                };
+            });
+            const agent = new Agent({
+                id: "test",
+                name: "Test",
+                instructions: "Test agent",
+                model,
+            });
+            const thread = new Thread({ agent, input: userMessage("test") });
+            await thread.execute();
+            const history = thread.history;
+            const threadId = thread.tid;
+            // All events should have the same tid as the thread
+            for (const event of history) {
+                expect(event).toHaveProperty("tid");
+                expect(event.tid).toBe(threadId);
+            }
+        });
+        it("should assign timestamps to all events", async () => {
+            const model = createMockModel(async (req) => {
+                return {
+                    content: [
+                        {
+                            kind: "message",
+                            id: "msg_1",
+                            role: "assistant",
+                            content: [{ kind: "text", text: "Hello" }],
+                        },
+                    ],
+                    finishReason: "stop",
+                    usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                    warnings: [],
+                };
+            });
+            const agent = new Agent({
+                id: "test",
+                name: "Test",
+                instructions: "Test agent",
+                model,
+            });
+            const thread = new Thread({ agent, input: userMessage("test") });
+            await thread.execute();
+            const history = thread.history;
+            for (const event of history) {
+                expect(event).toHaveProperty("timestamp");
+                expect(event.timestamp).toBeInstanceOf(Date);
+            }
+        });
+        it("should generate event ids in expected format", async () => {
+            let callCount = 0;
+            const model = createMockModel(async (req) => {
+                callCount++;
+                if (callCount === 1) {
+                    return {
+                        content: [
+                            {
+                                kind: "message",
+                                id: "msg_1",
+                                role: "assistant",
+                                content: [],
+                            },
+                            {
+                                kind: "tool.call",
+                                toolId: "simple",
+                                state: IN_PROGRESS,
+                                callId: "call_1",
+                                arguments: "{}",
+                            },
+                        ],
+                        finishReason: "stop",
+                        usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                        warnings: [],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            kind: "message",
+                            id: "msg_2",
+                            role: "assistant",
+                            content: [{ kind: "text", text: "Done" }],
+                        },
+                    ],
+                    finishReason: "stop",
+                    usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                    warnings: [],
+                };
+            });
+            const simpleTool = tool({
+                id: "simple",
+                description: "Simple tool",
+                parameters: undefined,
+                execute: async () => "result",
+            });
+            const agent = new Agent({
+                id: "test",
+                name: "Test",
+                instructions: "Test agent",
+                model,
+                toolkits: [
+                    new FunctionToolkit({ id: "test-tools", tools: [simpleTool] }),
+                ],
+            });
+            const thread = new Thread({ agent, input: userMessage("test") });
+            await thread.execute();
+            const history = thread.history;
+            // Messages should have id format "message:{original_id}"
+            const messages = history.filter((e) => e.kind === "message");
+            for (const msg of messages) {
+                expect(msg.id).toMatch(/^message:/);
+            }
+            // Tool calls use callId (not id), so tevent falls back to randomID()
+            const toolCalls = history.filter((e) => e.kind === "tool.call");
+            for (const tc of toolCalls) {
+                expect(tc.id).toBeDefined();
+                expect(typeof tc.id).toBe("string");
+            }
+            // Tool results also use callId, so tevent falls back to randomID()
+            const toolResults = history.filter((e) => e.kind === "tool.result");
+            for (const tr of toolResults) {
+                expect(tr.id).toBeDefined();
+                expect(typeof tr.id).toBe("string");
+            }
+        });
+        it("should yield sequenced events during streaming", async () => {
+            const model = createMockModel(async (req) => {
+                return {
+                    content: [
+                        {
+                            kind: "message",
+                            id: "msg_1",
+                            role: "assistant",
+                            content: [{ kind: "text", text: "Hello" }],
+                        },
+                    ],
+                    finishReason: "stop",
+                    usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                    warnings: [],
+                };
+            });
+            const agent = new Agent({
+                id: "test",
+                name: "Test",
+                instructions: "Test agent",
+                model,
+            });
+            const thread = new Thread({ agent, input: userMessage("test") });
+            const events = [];
+            for await (const event of thread.stream()) {
+                events.push(event);
+            }
+            // Find the complete message event (not deltas)
+            const messageEvent = events.find((e) => e.kind === "message" && e.role === "assistant");
+            expect(messageEvent).toBeDefined();
+            expect(messageEvent).toHaveProperty("seq");
+            expect(messageEvent).toHaveProperty("tid");
+            expect(messageEvent).toHaveProperty("timestamp");
+        });
+    });
     describe("Final Output Parsing", () => {
         it("should return text output when output is 'text'", async () => {
             const model = createMockModel(async (req) => {

package/dist/thread/thread.js

@@ -155,13 +155,13 @@ export class Thread {
             for await (const e of this.tick()) {
                 if (e.kind === "error") {
                     err = e.error;
-                    logger.error(e.error); // (TODO): onError callback in options
+                    logger.error(err.message); // (TODO): onError callback in options
                 }
                 // complete items get persisted with seq, deltas are ephemeral
                 if (notDelta(e)) {
-                    const [seqd] = this.append(e);
-                    events.push(seqd);
-                    yield seqd;
+                    const [eseq] = this.append(e);
+                    events.push(eseq);
+                    yield eseq;
                 }
                 else {
                     yield e;
@@ -187,8 +187,8 @@ export class Thread {
             const { actions, pendingApprovals } = await this.performActions(intentions);
             // append + yield action events (sequenced)
             for (const a of actions) {
-                const [seqd] = this.append(a);
-                yield seqd;
+                const [eseq] = this.append(a);
+                yield eseq;
             }
             await this.checkpoint(); /* c3: tick complete */
             if (pendingApprovals.length > 0) {
@@ -216,7 +216,7 @@ export class Thread {
         const req = await this.prepareModelRequest(this.history);
         this.emit("model.call.start", { settings: req.settings ?? {} });
         let usage;
-        let finishReason = "unknown";
+        let finishReason = { unified: "other", raw: undefined };
         try {
             if (this.model.stream) {
                 for await (const event of this.model.stream(req)) {

package/dist/tool/tool.d.ts

@@ -1,6 +1,6 @@
 import { Context, UnknownContext } from "../context.js";
 import { type LanguageModelTool } from "@kernl-sdk/protocol";
-import type { ToolConfig, ToolApprovalFunction, ToolEnabledFunction, ToolErrorFunction, ToolInputParameters, ToolResult } from "./types.js";
+import type { ToolConfig, ToolApprovalFunction, ToolEnabledFunction, ToolErrorFunction, ToolExecuteFunction, ToolInputParameters, ToolResult } from "./types.js";
 /**
  * Exposes a function to the agent as a tool to be called
  *
@@ -42,7 +42,7 @@ export declare class FunctionTool<TContext = UnknownContext, TParameters extends
     readonly description: string;
     readonly parameters?: TParameters;
     readonly mode: "blocking" | "async";
-    private execute;
+    execute: ToolExecuteFunction<TContext, TParameters, TResult>;
     errorfn: ToolErrorFunction | null;
     requiresApproval: ToolApprovalFunction<TParameters>;
     isEnabled: ToolEnabledFunction<TContext>;

package/dist/tool/tool.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -32,11 +32,11 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.2",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "yaml": "^2.8.2",
-    "@kernl-sdk/protocol": "0.5.0",
-    "@kernl-sdk/shared": "^0.4.0",
-    "@kernl-sdk/retrieval": "0.1.9"
+    "@kernl-sdk/protocol": "0.5.1",
+    "@kernl-sdk/retrieval": "0.1.10",
+    "@kernl-sdk/shared": "^0.4.0"
   },
   "peerDependencies": {
     "zod": "^4.1.8"

package/src/agent.ts

@@ -71,20 +71,15 @@ export class Agent<
     input: string | LanguageModelItem[],
     options?: ThreadExecuteOptions<TContext>,
   ): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>> {
+    let thread: Thread<TContext, TOutput> | null = null;
+
     if (!this.kernl) {
       throw new MisconfiguredError(
         `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
       );
     }
 
-    const items =
-      typeof input === "string"
-        ? [message({ role: "user", text: input })]
-        : input;
     const tid = options?.threadId;
-
-    let thread: Thread<TContext, TOutput> | null = null;
-
     if (tid) {
       // no concurrent execution of same thread - correctness contract
       // TODO: race condition - need to check again after async storage.get()
@@ -100,6 +95,11 @@ export class Agent<
       }
     }
 
+    const items =
+      typeof input === "string"
+        ? [message({ role: "user", text: input })]
+        : input;
+
     // create new thread if not found in storage or no tid provided
     if (!thread) {
       const ctx = options?.context
@@ -123,6 +123,9 @@ export class Agent<
     if (options?.context) {
       thread.context.context = options.context;
     }
+    if (options?.model) {
+      thread.model = options.model;
+    }
     thread.append(...items);
     return this.kernl.schedule(thread);
   }
@@ -192,6 +195,9 @@ export class Agent<
     if (options?.context) {
       thread.context.context = options.context;
     }
+    if (options?.model) {
+      thread.model = options.model;
+    }
     thread.append(...items);
     yield* this.kernl.scheduleStream(thread);
   }

package/src/thread/__tests__/mock.ts

@@ -40,13 +40,22 @@ export class MockLanguageModel implements LanguageModel {
     ];
 
     // Return with fake usage stats
+    const tokens = this.countTokens(userText);
     return {
       content,
-      finishReason: "stop",
+      finishReason: { unified: "stop", raw: "stop" },
       usage: {
-        inputTokens: this.countTokens(userText),
-        outputTokens: this.countTokens(userText),
-        totalTokens: this.countTokens(userText) * 2,
+        inputTokens: {
+          total: tokens,
+          noCache: tokens,
+          cacheRead: undefined,
+          cacheWrite: undefined,
+        },
+        outputTokens: {
+          total: tokens,
+          text: tokens,
+          reasoning: undefined,
+        },
       },
       warnings: [],
     };

package/src/thread/__tests__/thread.test.ts

@@ -1060,6 +1060,286 @@ describe("Thread", () => {
     });
   });
 
+  describe("Event Sequencing", () => {
+    it("should assign incrementing seq values to all persisted events", async () => {
+      let callCount = 0;
+
+      const model = createMockModel(async (req: LanguageModelRequest) => {
+        callCount++;
+
+        if (callCount === 1) {
+          return {
+            content: [
+              {
+                kind: "message" as const,
+                id: "msg_1",
+                role: "assistant" as const,
+                content: [],
+              },
+              {
+                kind: "tool.call" as const,
+                toolId: "echo",
+                state: IN_PROGRESS,
+                callId: "call_1",
+                arguments: JSON.stringify({ text: "test" }),
+              },
+            ],
+            finishReason: "stop",
+            usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+            warnings: [],
+          };
+        }
+
+        return {
+          content: [
+            {
+              kind: "message" as const,
+              id: "msg_2",
+              role: "assistant" as const,
+              content: [{ kind: "text" as const, text: "Done!" }],
+            },
+          ],
+          finishReason: "stop",
+          usage: { inputTokens: 4, outputTokens: 2, totalTokens: 6 },
+          warnings: [],
+        };
+      });
+
+      const echoTool = tool({
+        id: "echo",
+        description: "Echoes input",
+        parameters: z.object({ text: z.string() }),
+        execute: async (ctx, { text }) => `Echo: ${text}`,
+      });
+
+      const agent = new Agent({
+        id: "test",
+        name: "Test",
+        instructions: "Test agent",
+        model,
+        toolkits: [
+          new FunctionToolkit({ id: "test-tools", tools: [echoTool] }),
+        ],
+      });
+
+      const thread = new Thread({ agent, input: userMessage("test") });
+      await thread.execute();
+
+      const history = (thread as any).history as ThreadEvent[];
+
+      // Verify all events have seq values
+      for (const event of history) {
+        expect(event).toHaveProperty("seq");
+        expect(typeof event.seq).toBe("number");
+      }
+
+      // Verify seq values increment: 0, 1, 2, 3, 4
+      const seqValues = history.map((e) => e.seq);
+      expect(seqValues).toEqual([0, 1, 2, 3, 4]);
+    });
+
+    it("should assign consistent tid to all events in a thread", async () => {
+      const model = createMockModel(async (req: LanguageModelRequest) => {
+        return {
+          content: [
+            {
+              kind: "message" as const,
+              id: "msg_1",
+              role: "assistant" as const,
+              content: [{ kind: "text" as const, text: "Hello" }],
+            },
+          ],
+          finishReason: "stop",
+          usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+          warnings: [],
+        };
+      });
+
+      const agent = new Agent({
+        id: "test",
+        name: "Test",
+        instructions: "Test agent",
+        model,
+      });
+
+      const thread = new Thread({ agent, input: userMessage("test") });
+      await thread.execute();
+
+      const history = (thread as any).history as ThreadEvent[];
+      const threadId = thread.tid;
+
+      // All events should have the same tid as the thread
+      for (const event of history) {
+        expect(event).toHaveProperty("tid");
+        expect(event.tid).toBe(threadId);
+      }
+    });
+
+    it("should assign timestamps to all events", async () => {
+      const model = createMockModel(async (req: LanguageModelRequest) => {
+        return {
+          content: [
+            {
+              kind: "message" as const,
+              id: "msg_1",
+              role: "assistant" as const,
+              content: [{ kind: "text" as const, text: "Hello" }],
+            },
+          ],
+          finishReason: "stop",
+          usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+          warnings: [],
+        };
+      });
+
+      const agent = new Agent({
+        id: "test",
+        name: "Test",
+        instructions: "Test agent",
+        model,
+      });
+
+      const thread = new Thread({ agent, input: userMessage("test") });
+      await thread.execute();
+
+      const history = (thread as any).history as ThreadEvent[];
+
+      for (const event of history) {
+        expect(event).toHaveProperty("timestamp");
+        expect(event.timestamp).toBeInstanceOf(Date);
+      }
+    });
+
+    it("should generate event ids in expected format", async () => {
+      let callCount = 0;
+
+      const model = createMockModel(async (req: LanguageModelRequest) => {
+        callCount++;
+
+        if (callCount === 1) {
+          return {
+            content: [
+              {
+                kind: "message" as const,
+                id: "msg_1",
+                role: "assistant" as const,
+                content: [],
+              },
+              {
+                kind: "tool.call" as const,
+                toolId: "simple",
+                state: IN_PROGRESS,
+                callId: "call_1",
+                arguments: "{}",
+              },
+            ],
+            finishReason: "stop",
+            usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+            warnings: [],
+          };
+        }
+
+        return {
+          content: [
+            {
+              kind: "message" as const,
+              id: "msg_2",
+              role: "assistant" as const,
+              content: [{ kind: "text" as const, text: "Done" }],
+            },
+          ],
+          finishReason: "stop",
+          usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+          warnings: [],
+        };
+      });
+
+      const simpleTool = tool({
+        id: "simple",
+        description: "Simple tool",
+        parameters: undefined,
+        execute: async () => "result",
+      });
+
+      const agent = new Agent({
+        id: "test",
+        name: "Test",
+        instructions: "Test agent",
+        model,
+        toolkits: [
+          new FunctionToolkit({ id: "test-tools", tools: [simpleTool] }),
+        ],
+      });
+
+      const thread = new Thread({ agent, input: userMessage("test") });
+      await thread.execute();
+
+      const history = (thread as any).history as ThreadEvent[];
+
+      // Messages should have id format "message:{original_id}"
+      const messages = history.filter((e) => e.kind === "message");
+      for (const msg of messages) {
+        expect(msg.id).toMatch(/^message:/);
+      }
+
+      // Tool calls use callId (not id), so tevent falls back to randomID()
+      const toolCalls = history.filter((e) => e.kind === "tool.call");
+      for (const tc of toolCalls) {
+        expect(tc.id).toBeDefined();
+        expect(typeof tc.id).toBe("string");
+      }
+
+      // Tool results also use callId, so tevent falls back to randomID()
+      const toolResults = history.filter((e) => e.kind === "tool.result");
+      for (const tr of toolResults) {
+        expect(tr.id).toBeDefined();
+        expect(typeof tr.id).toBe("string");
+      }
+    });
+
+    it("should yield sequenced events during streaming", async () => {
+      const model = createMockModel(async (req: LanguageModelRequest) => {
+        return {
+          content: [
+            {
+              kind: "message" as const,
+              id: "msg_1",
+              role: "assistant" as const,
+              content: [{ kind: "text" as const, text: "Hello" }],
+            },
+          ],
+          finishReason: "stop",
+          usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+          warnings: [],
+        };
+      });
+
+      const agent = new Agent({
+        id: "test",
+        name: "Test",
+        instructions: "Test agent",
+        model,
+      });
+
+      const thread = new Thread({ agent, input: userMessage("test") });
+
+      const events: any[] = [];
+      for await (const event of thread.stream()) {
+        events.push(event);
+      }
+
+      // Find the complete message event (not deltas)
+      const messageEvent = events.find(
+        (e) => e.kind === "message" && e.role === "assistant",
+      );
+
+      expect(messageEvent).toBeDefined();
+      expect(messageEvent).toHaveProperty("seq");
+      expect(messageEvent).toHaveProperty("tid");
+      expect(messageEvent).toHaveProperty("timestamp");
+    });
+  });
+
   describe("Final Output Parsing", () => {
     it("should return text output when output is 'text'", async () => {
       const model = createMockModel(async (req: LanguageModelRequest) => {

package/src/thread/thread.ts

@@ -216,13 +216,13 @@ export class Thread<
       for await (const e of this.tick()) {
         if (e.kind === "error") {
           err = e.error;
-          logger.error(e.error); // (TODO): onError callback in options
+          logger.error(err.message); // (TODO): onError callback in options
         }
         // complete items get persisted with seq, deltas are ephemeral
         if (notDelta(e)) {
-          const [seqd] = this.append(e);
-          events.push(seqd);
-          yield seqd;
+          const [eseq] = this.append(e);
+          events.push(eseq);
+          yield eseq;
         } else {
           yield e;
         }
@@ -253,8 +253,8 @@ export class Thread<
 
       // append + yield action events (sequenced)
       for (const a of actions) {
-        const [seqd] = this.append(a);
-        yield seqd;
+        const [eseq] = this.append(a);
+        yield eseq;
       }
 
       await this.checkpoint(); /* c3: tick complete */
@@ -289,7 +289,7 @@ export class Thread<
     this.emit("model.call.start", { settings: req.settings ?? {} });
 
     let usage: LanguageModelUsage | undefined;
-    let finishReason: LanguageModelFinishReason = "unknown";
+    let finishReason: LanguageModelFinishReason = { unified: "other", raw: undefined };
 
     try {
       if (this.model.stream) {

package/src/tool/tool.ts

@@ -84,7 +84,7 @@ export class FunctionTool<
   readonly description: string;
   readonly parameters?: TParameters;
   readonly mode: "blocking" | "async";
-  private execute: ToolExecuteFunction<TContext, TParameters, TResult>;
+  execute: ToolExecuteFunction<TContext, TParameters, TResult>;
 
   errorfn: ToolErrorFunction | null;
   requiresApproval: ToolApprovalFunction<TParameters>;