kernl 0.1.4 → 0.2.1

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

@@ -0,0 +1,315 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { z } from "zod";
+import { openai } from "@ai-sdk/openai";
+import { AISDKLanguageModel } from "@kernl-sdk/ai";
+import { Agent } from "../../agent";
+import { Kernl } from "../../kernl";
+import { tool, Toolkit } from "../../tool";
+import { Thread } from "../thread";
+/**
+ * Integration tests for Thread streaming with real AI SDK providers.
+ *
+ * These tests require an OPENAI_API_KEY environment variable to be set.
+ * They will be skipped if the API key is not available.
+ *
+ * Run with: OPENAI_API_KEY=your-key pnpm test:run
+ */
+const SKIP_INTEGRATION_TESTS = !process.env.OPENAI_API_KEY;
+describe.skipIf(SKIP_INTEGRATION_TESTS)("Thread streaming integration", () => {
+    let kernl;
+    let model;
+    beforeAll(() => {
+        kernl = new Kernl();
+        model = new AISDKLanguageModel(openai("gpt-4o"));
+    });
+    describe("stream()", () => {
+        it("should yield both delta events and complete items", async () => {
+            const agent = new Agent({
+                id: "test-stream",
+                name: "Test Stream Agent",
+                instructions: "You are a helpful assistant.",
+                model,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [
+                        { kind: "text", text: "Say 'Hello World' and nothing else." },
+                    ],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const events = [];
+            for await (const event of thread.stream()) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have text-delta events (for streaming UX)
+            const textDeltas = events.filter((e) => e.kind === "text-delta");
+            expect(textDeltas.length).toBeGreaterThan(0);
+            // Should have text-start event
+            const textStarts = events.filter((e) => e.kind === "text-start");
+            expect(textStarts.length).toBeGreaterThan(0);
+            // Should have text-end event
+            const textEnds = events.filter((e) => e.kind === "text-end");
+            expect(textEnds.length).toBeGreaterThan(0);
+            // Should have complete Message item (for history)
+            const messages = events.filter((e) => e.kind === "message");
+            expect(messages.length).toBeGreaterThan(0);
+            const assistantMessage = messages.find((m) => m.role === "assistant");
+            expect(assistantMessage).toBeDefined();
+            expect(assistantMessage.content).toBeDefined();
+            expect(assistantMessage.content.length).toBeGreaterThan(0);
+            // Message should have accumulated text from all deltas
+            const textContent = assistantMessage.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            expect(textContent.text).toBeDefined();
+            expect(textContent.text.length).toBeGreaterThan(0);
+            // Verify accumulated text matches concatenated deltas
+            const accumulatedFromDeltas = textDeltas.map((d) => d.text).join("");
+            expect(textContent.text).toBe(accumulatedFromDeltas);
+            // Should have finish event
+            const finishEvents = events.filter((e) => e.kind === "finish");
+            expect(finishEvents.length).toBe(1);
+        }, 30000);
+        it("should filter deltas from history but include complete items", async () => {
+            const agent = new Agent({
+                id: "test-history",
+                name: "Test History Agent",
+                instructions: "You are a helpful assistant.",
+                model,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [{ kind: "text", text: "Count to 3" }],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const streamEvents = [];
+            for await (const event of thread.stream()) {
+                streamEvents.push(event);
+            }
+            // Access private history via type assertion for testing
+            const history = thread.history;
+            // History should only contain complete items (message, reasoning, tool-call, tool-result)
+            // TypeScript already enforces this via ThreadEvent type, but let's verify at runtime
+            for (const event of history) {
+                expect(["message", "reasoning", "tool-call", "tool-result"]).toContain(event.kind);
+            }
+            // Stream events should include deltas (but history should not)
+            const streamDeltas = streamEvents.filter((e) => e.kind === "text-delta" ||
+                e.kind === "text-start" ||
+                e.kind === "text-end");
+            expect(streamDeltas.length).toBeGreaterThan(0);
+            // History should contain the input message
+            expect(history[0]).toEqual(input[0]);
+            // History should contain complete Message items
+            const historyMessages = history.filter((e) => e.kind === "message");
+            expect(historyMessages.length).toBeGreaterThan(1); // input + assistant response
+            // Verify assistant message has complete text (not deltas)
+            const assistantMessage = historyMessages.find((m) => m.role === "assistant");
+            expect(assistantMessage).toBeDefined();
+            const textContent = assistantMessage.content.find((c) => c.kind === "text");
+            expect(textContent.text).toBeTruthy();
+            expect(textContent.text.length).toBeGreaterThan(0);
+        }, 30000);
+        it("should work with tool calls", async () => {
+            const addTool = tool({
+                id: "add",
+                name: "add",
+                description: "Add two numbers together",
+                parameters: z.object({
+                    a: z.number().describe("The first number"),
+                    b: z.number().describe("The second number"),
+                }),
+                execute: async (ctx, { a, b }) => {
+                    return a + b;
+                },
+            });
+            const toolkit = new Toolkit({
+                id: "math",
+                tools: [addTool],
+            });
+            const agent = new Agent({
+                id: "test-tools",
+                name: "Test Tools Agent",
+                instructions: "You are a helpful assistant that can do math.",
+                model,
+                toolkits: [toolkit],
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [{ kind: "text", text: "What is 25 + 17?" }],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const events = [];
+            for await (const event of thread.stream()) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have tool calls
+            const toolCalls = events.filter((e) => e.kind === "tool-call");
+            expect(toolCalls.length).toBeGreaterThan(0);
+            // Verify tool was called with correct parameters
+            const addToolCall = toolCalls.find((tc) => tc.toolId === "add");
+            expect(addToolCall).toBeDefined();
+            expect(JSON.parse(addToolCall.arguments)).toEqual({ a: 25, b: 17 });
+            // Should have tool results
+            const toolResults = events.filter((e) => e.kind === "tool-result");
+            expect(toolResults.length).toBeGreaterThan(0);
+            // Verify tool result is correct
+            const addToolResult = toolResults.find((tr) => tr.callId === addToolCall.callId);
+            expect(addToolResult).toBeDefined();
+            expect(addToolResult.result).toBe(42);
+            // History should contain tool calls and results
+            const history = thread.history;
+            const historyToolCalls = history.filter((e) => e.kind === "tool-call");
+            const historyToolResults = history.filter((e) => e.kind === "tool-result");
+            expect(historyToolCalls.length).toBe(toolCalls.length);
+            expect(historyToolResults.length).toBe(toolResults.length);
+            // Verify the assistant's final response references the correct answer
+            const messages = events.filter((e) => e.kind === "message");
+            const assistantMessage = messages.find((m) => m.role === "assistant");
+            expect(assistantMessage).toBeDefined();
+            const textContent = assistantMessage.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            expect(textContent.text).toContain("42");
+        }, 30000);
+        it("should properly encode tool results with matching callIds for multi-turn", async () => {
+            const multiplyTool = tool({
+                id: "multiply",
+                name: "multiply",
+                description: "Multiply two numbers",
+                parameters: z.object({
+                    a: z.number().describe("First number"),
+                    b: z.number().describe("Second number"),
+                }),
+                execute: async (ctx, { a, b }) => {
+                    return a * b;
+                },
+            });
+            const toolkit = new Toolkit({
+                id: "math",
+                tools: [multiplyTool],
+            });
+            const agent = new Agent({
+                id: "test-multi-turn",
+                name: "Test Multi-Turn Agent",
+                instructions: "You are a helpful assistant that can do math.",
+                model,
+                toolkits: [toolkit],
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [{ kind: "text", text: "What is 7 times 6?" }],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const events = [];
+            // Collect all events from the stream
+            for await (const event of thread.stream()) {
+                events.push(event);
+            }
+            // Find the tool call and result
+            const toolCalls = events.filter((e) => e.kind === "tool-call");
+            const toolResults = events.filter((e) => e.kind === "tool-result");
+            expect(toolCalls.length).toBeGreaterThan(0);
+            expect(toolResults.length).toBeGreaterThan(0);
+            const multiplyCall = toolCalls[0];
+            const multiplyResult = toolResults[0];
+            // Verify callId matches between tool call and result
+            expect(multiplyCall.callId).toBe(multiplyResult.callId);
+            expect(multiplyCall.toolId).toBe("multiply");
+            expect(multiplyResult.toolId).toBe("multiply");
+            // Verify the tool result has the correct structure
+            expect(multiplyResult.callId).toBeDefined();
+            expect(typeof multiplyResult.callId).toBe("string");
+            expect(multiplyResult.callId.length).toBeGreaterThan(0);
+            // Verify history contains both with matching callIds
+            const history = thread.history;
+            const historyToolCall = history.find((e) => e.kind === "tool-call" && e.toolId === "multiply");
+            const historyToolResult = history.find((e) => e.kind === "tool-result" && e.toolId === "multiply");
+            expect(historyToolCall).toBeDefined();
+            expect(historyToolResult).toBeDefined();
+            expect(historyToolCall.callId).toBe(historyToolResult.callId);
+            // Verify final response uses the tool result
+            const messages = events.filter((e) => e.kind === "message");
+            const assistantMessage = messages.find((m) => m.role === "assistant");
+            expect(assistantMessage).toBeDefined();
+            const textContent = assistantMessage.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            expect(textContent.text).toContain("42");
+        }, 30000);
+    });
+    describe("execute()", () => {
+        it("should consume stream and return final response", async () => {
+            const agent = new Agent({
+                id: "test-blocking",
+                name: "Test Blocking Agent",
+                instructions: "You are a helpful assistant.",
+                model,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [{ kind: "text", text: "Say 'Testing' and nothing else." }],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const result = await thread.execute();
+            // Should have a response
+            expect(result.response).toBeDefined();
+            expect(typeof result.response).toBe("string");
+            expect(result.response.length).toBeGreaterThan(0);
+            // Should have final state
+            expect(result.state).toBe("stopped");
+        }, 30000);
+        it("should validate structured output in blocking mode", async () => {
+            const responseSchema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            const agent = new Agent({
+                id: "test-structured",
+                name: "Test Structured Agent",
+                instructions: "You are a helpful assistant. Return JSON with name and age fields.",
+                model,
+                responseType: responseSchema,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [
+                        {
+                            kind: "text",
+                            text: 'Return a JSON object with name "Alice" and age 30',
+                        },
+                    ],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const result = await thread.execute();
+            // Response should be validated and parsed
+            expect(result.response).toBeDefined();
+            expect(typeof result.response).toBe("object");
+            expect(result.response.name).toBeTruthy();
+            expect(typeof result.response.age).toBe("number");
+        }, 30000);
+    });
+});

package/dist/thread/__tests__/stream.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stream.test.d.ts.map

package/dist/thread/__tests__/stream.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.test.d.ts","sourceRoot":"","sources":["../../../src/thread/__tests__/stream.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,244 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { z } from "zod";
+import { openai } from "@ai-sdk/openai";
+import { AISDKLanguageModel } from "@kernl-sdk/ai";
+import { Agent } from "../../agent";
+import { Kernl } from "../../kernl";
+import { tool, Toolkit } from "../../tool";
+import { Thread } from "../thread";
+/**
+ * Integration tests for Thread streaming with real AI SDK providers.
+ *
+ * These tests require an OPENAI_API_KEY environment variable to be set.
+ * They will be skipped if the API key is not available.
+ *
+ * Run with: OPENAI_API_KEY=your-key pnpm test:run
+ */
+const SKIP_INTEGRATION_TESTS = !process.env.OPENAI_API_KEY;
+describe.skipIf(SKIP_INTEGRATION_TESTS)("Thread streaming integration", () => {
+    let kernl;
+    let model;
+    beforeAll(() => {
+        kernl = new Kernl();
+        model = new AISDKLanguageModel(openai("gpt-4o-mini"));
+    });
+    describe("stream()", () => {
+        it("should yield both delta events and complete items", async () => {
+            const agent = new Agent({
+                id: "test-stream",
+                name: "Test Stream Agent",
+                instructions: "You are a helpful assistant.",
+                model,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [
+                        { kind: "text", text: "Say 'Hello World' and nothing else." },
+                    ],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const events = [];
+            for await (const event of thread.stream()) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have text-delta events (for streaming UX)
+            const textDeltas = events.filter((e) => e.kind === "text-delta");
+            expect(textDeltas.length).toBeGreaterThan(0);
+            // Should have text-start event
+            const textStarts = events.filter((e) => e.kind === "text-start");
+            expect(textStarts.length).toBeGreaterThan(0);
+            // Should have text-end event
+            const textEnds = events.filter((e) => e.kind === "text-end");
+            expect(textEnds.length).toBeGreaterThan(0);
+            // Should have complete Message item (for history)
+            const messages = events.filter((e) => e.kind === "message");
+            expect(messages.length).toBeGreaterThan(0);
+            const assistantMessage = messages.find((m) => m.role === "assistant");
+            expect(assistantMessage).toBeDefined();
+            expect(assistantMessage.content).toBeDefined();
+            expect(assistantMessage.content.length).toBeGreaterThan(0);
+            // Message should have accumulated text from all deltas
+            const textContent = assistantMessage.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            expect(textContent.text).toBeDefined();
+            expect(textContent.text.length).toBeGreaterThan(0);
+            // Verify accumulated text matches concatenated deltas
+            const accumulatedFromDeltas = textDeltas.map((d) => d.text).join("");
+            expect(textContent.text).toBe(accumulatedFromDeltas);
+            // Should have finish event
+            const finishEvents = events.filter((e) => e.kind === "finish");
+            expect(finishEvents.length).toBe(1);
+        });
+        it("should filter deltas from history but include complete items", async () => {
+            const agent = new Agent({
+                id: "test-history",
+                name: "Test History Agent",
+                instructions: "You are a helpful assistant.",
+                model,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [{ kind: "text", text: "Count to 3" }],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const streamEvents = [];
+            for await (const event of thread.stream()) {
+                streamEvents.push(event);
+            }
+            // Access private history via type assertion for testing
+            const history = thread.history;
+            // History should only contain complete items (message, reasoning, tool-call, tool-result)
+            // TypeScript already enforces this via ThreadEvent type, but let's verify at runtime
+            for (const event of history) {
+                expect(["message", "reasoning", "tool-call", "tool-result"]).toContain(event.kind);
+            }
+            // Stream events should include deltas (but history should not)
+            const streamDeltas = streamEvents.filter((e) => e.kind === "text-delta" ||
+                e.kind === "text-start" ||
+                e.kind === "text-end");
+            expect(streamDeltas.length).toBeGreaterThan(0);
+            // History should contain the input message
+            expect(history[0]).toEqual(input[0]);
+            // History should contain complete Message items
+            const historyMessages = history.filter((e) => e.kind === "message");
+            expect(historyMessages.length).toBeGreaterThan(1); // input + assistant response
+            // Verify assistant message has complete text (not deltas)
+            const assistantMessage = historyMessages.find((m) => m.role === "assistant");
+            expect(assistantMessage).toBeDefined();
+            const textContent = assistantMessage.content.find((c) => c.kind === "text");
+            expect(textContent.text).toBeTruthy();
+            expect(textContent.text.length).toBeGreaterThan(0);
+        });
+        it("should work with tool calls", async () => {
+            const calculateTool = tool({
+                name: "calculate",
+                description: "Perform a mathematical calculation",
+                parameters: z.object({
+                    expression: z
+                        .string()
+                        .describe("The mathematical expression to evaluate"),
+                }),
+                execute: async (ctx, { expression }) => {
+                    // Simple eval for testing (don't do this in production!)
+                    try {
+                        return { result: eval(expression) };
+                    }
+                    catch {
+                        return { error: "Invalid expression" };
+                    }
+                },
+            });
+            const toolkit = new Toolkit({
+                id: "math",
+                tools: [calculateTool],
+            });
+            const agent = new Agent({
+                id: "test-tools",
+                name: "Test Tools Agent",
+                instructions: "You are a helpful assistant that can do calculations.",
+                model,
+                toolkits: [toolkit],
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [{ kind: "text", text: "What is 25 + 17?" }],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const events = [];
+            for await (const event of thread.stream()) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have tool calls
+            const toolCalls = events.filter((e) => e.kind === "tool-call");
+            expect(toolCalls.length).toBeGreaterThan(0);
+            // Should have tool results
+            const toolResults = events.filter((e) => e.kind === "tool-result");
+            expect(toolResults.length).toBeGreaterThan(0);
+            // History should contain tool calls and results
+            const history = thread.history;
+            const historyToolCalls = history.filter((e) => e.kind === "tool-call");
+            const historyToolResults = history.filter((e) => e.kind === "tool-result");
+            expect(historyToolCalls.length).toBe(toolCalls.length);
+            expect(historyToolResults.length).toBe(toolResults.length);
+        });
+    });
+    describe("execute()", () => {
+        it("should consume stream and return final response", async () => {
+            const agent = new Agent({
+                id: "test-blocking",
+                name: "Test Blocking Agent",
+                instructions: "You are a helpful assistant.",
+                model,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [{ kind: "text", text: "Say 'Testing' and nothing else." }],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const result = await thread.execute();
+            // Should have a response
+            expect(result.response).toBeDefined();
+            expect(typeof result.response).toBe("string");
+            expect(result.response.length).toBeGreaterThan(0);
+            // Should have final state
+            expect(result.state).toBe("stopped");
+            // History should NOT contain deltas
+            const history = thread.history;
+            const historyDeltas = history.filter((e) => e.kind === "text-delta" ||
+                e.kind === "text-start" ||
+                e.kind === "text-end");
+            expect(historyDeltas.length).toBe(0);
+        });
+        it("should validate structured output in blocking mode", async () => {
+            const responseSchema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            const agent = new Agent({
+                id: "test-structured",
+                name: "Test Structured Agent",
+                instructions: "You are a helpful assistant. Return JSON with name and age fields.",
+                model,
+                responseType: responseSchema,
+            });
+            const input = [
+                {
+                    kind: "message",
+                    id: "msg-1",
+                    role: "user",
+                    content: [
+                        {
+                            kind: "text",
+                            text: 'Return a JSON object with name "Alice" and age 30',
+                        },
+                    ],
+                },
+            ];
+            const thread = new Thread(kernl, agent, input);
+            const result = await thread.execute();
+            // Response should be validated and parsed
+            expect(result.response).toBeDefined();
+            expect(typeof result.response).toBe("object");
+            expect(result.response.name).toBeTruthy();
+            expect(typeof result.response.age).toBe("number");
+        });
+    });
+});