@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/spec/ai/ConversationAgent.spec.ts

@@ -0,0 +1,520 @@
+import {
+    ConversationAgent,
+    ConversationData,
+    StorageMessage,
+    FlinkContext,
+} from "../../src";
+
+// Mock agent for testing
+class MockConversationAgent extends ConversationAgent<FlinkContext> {
+    id = "mock-agent";
+    description = "Mock agent for testing";
+    instructions() { return "You are a test agent"; }
+    tools = [];
+
+    // Spy methods
+    loadConversationSpy = jasmine.createSpy("loadConversation");
+    saveConversationSpy = jasmine.createSpy("saveConversation");
+
+    protected async loadConversation(
+        conversationId: string
+    ): Promise<ConversationData | null> {
+        return this.loadConversationSpy(conversationId);
+    }
+
+    protected async saveConversation(
+        conversationId: string,
+        data: ConversationData
+    ): Promise<void> {
+        return this.saveConversationSpy(conversationId, data);
+    }
+
+    // Expose protected methods for testing
+    public testBeforeRun(input: any, context: any) {
+        return (this as any).beforeRun(input, context);
+    }
+
+    public testAfterRun(result: any, context: any) {
+        return (this as any).afterRun(result, context);
+    }
+
+    public testConvertToMessages(llmMessages: any[]): StorageMessage[] {
+        return (this as any).convertToMessages(llmMessages);
+    }
+}
+
+describe("ConversationAgent", () => {
+    let agent: MockConversationAgent;
+    let mockContext: FlinkContext;
+
+    beforeEach(() => {
+        mockContext = {} as FlinkContext;
+        agent = new MockConversationAgent();
+        (agent as any).ctx = mockContext;
+    });
+
+    describe("beforeRun", () => {
+        it("should load conversation when conversationId is provided", async () => {
+            const conversationId = "conv-123";
+            const conversationData: ConversationData = {
+                messages: [
+                    { role: "user", content: "Hello" },
+                    { role: "assistant", content: "Hi there" },
+                ],
+                providerMetadata: {
+                    openai: { responseId: "resp-123", instructionsHash: "hash-456" },
+                },
+            };
+
+            agent.loadConversationSpy.and.returnValue(
+                Promise.resolve(conversationData)
+            );
+
+            const input: any = { conversationId };
+            const context: any = {};
+
+            await agent.testBeforeRun(input, context);
+
+            expect(agent.loadConversationSpy).toHaveBeenCalledWith(
+                conversationId
+            );
+            expect(input.history).toBeDefined();
+            expect(input.history.length).toBe(2);
+            expect(input.providerMetadata).toEqual(
+                conversationData.providerMetadata
+            );
+        });
+
+        it("should not populate history if conversation not found", async () => {
+            const conversationId = "conv-nonexistent";
+
+            agent.loadConversationSpy.and.returnValue(Promise.resolve(null));
+
+            const input: any = { conversationId };
+            const context: any = {};
+
+            await agent.testBeforeRun(input, context);
+
+            expect(agent.loadConversationSpy).toHaveBeenCalledWith(
+                conversationId
+            );
+            expect(input.history).toBeUndefined();
+            expect(input.providerMetadata).toBeUndefined();
+        });
+
+        it("should not call loadConversation if conversationId not provided", async () => {
+            const input: any = {};
+            const context: any = {};
+
+            await agent.testBeforeRun(input, context);
+
+            expect(agent.loadConversationSpy).not.toHaveBeenCalled();
+            expect(input.history).toBeUndefined();
+        });
+
+        it("should propagate load errors", async () => {
+            const conversationId = "conv-error";
+            const error = new Error("Database connection failed");
+
+            agent.loadConversationSpy.and.returnValue(Promise.reject(error));
+
+            const input: any = { conversationId };
+            const context: any = {};
+
+            await expectAsync(
+                agent.testBeforeRun(input, context)
+            ).toBeRejectedWith(error);
+        });
+    });
+
+    describe("provider metadata", () => {
+        it("should always preserve provider metadata", async () => {
+            const conversationData: ConversationData = {
+                messages: [{ role: "user", content: "Hello" }],
+                providerMetadata: { openai: { responseId: "resp-123" } },
+            };
+
+            agent.loadConversationSpy.and.returnValue(
+                Promise.resolve(conversationData)
+            );
+
+            const input: any = { conversationId: "conv-123" };
+            await agent.testBeforeRun(input, {});
+
+            // Metadata is always preserved (no strategy filtering)
+            expect(input.providerMetadata).toEqual({
+                openai: { responseId: "resp-123" },
+            });
+        });
+    });
+
+    describe("afterRun", () => {
+        it("should save conversation after successful execution", async () => {
+            const conversationId = "conv-123";
+            const llmMessages = [
+                {
+                    role: "user",
+                    content: [{ type: "text", text: "What cars do you have?" }],
+                },
+                {
+                    role: "assistant",
+                    content: [{ type: "text", text: "We have sedans and SUVs" }],
+                },
+            ];
+            const providerMetadata = {
+                openai: { responseId: "resp-456", instructionsHash: "hash-789" },
+            };
+
+            agent.saveConversationSpy.and.returnValue(Promise.resolve());
+
+            const result: any = {
+                message: "Response",
+                toolCalls: [],
+                stepsUsed: 1,
+                stoppedEarly: false,
+                providerMetadata,
+            };
+
+            const context: any = {
+                messages: llmMessages,
+                conversationId,
+            };
+
+            await agent.testAfterRun(result, context);
+
+            expect(agent.saveConversationSpy).toHaveBeenCalled();
+
+            const [savedConvId, savedData] =
+                agent.saveConversationSpy.calls.argsFor(0);
+            expect(savedConvId).toBe(conversationId);
+            expect(savedData.messages).toEqual([
+                { role: "user", content: "What cars do you have?" },
+                { role: "assistant", content: "We have sedans and SUVs" },
+            ]);
+            expect(savedData.providerMetadata).toEqual(providerMetadata);
+        });
+
+        it("should skip save when conversationId not provided", async () => {
+            const result: any = {
+                message: "Response",
+                toolCalls: [],
+                stepsUsed: 1,
+                stoppedEarly: false,
+            };
+
+            const context: any = {
+                messages: [],
+                input: {},
+            };
+
+            await agent.testAfterRun(result, context);
+
+            expect(agent.saveConversationSpy).not.toHaveBeenCalled();
+        });
+
+        it("should not throw on save errors (log only)", async () => {
+            const conversationId = "conv-123";
+            const error = new Error("Database write failed");
+
+            agent.saveConversationSpy.and.returnValue(Promise.reject(error));
+
+            const result: any = {
+                message: "Response",
+                toolCalls: [],
+                stepsUsed: 1,
+                stoppedEarly: false,
+            };
+
+            const context: any = {
+                messages: [
+                    {
+                        role: "user",
+                        content: [{ type: "text", text: "Hello" }],
+                    },
+                ],
+                conversationId,
+            };
+
+            // Should not throw - just log error
+            await expectAsync(agent.testAfterRun(result, context)).toBeResolved();
+
+            expect(agent.saveConversationSpy).toHaveBeenCalled();
+        });
+    });
+
+    describe("convertToAgentMessages (loading from storage)", () => {
+        it("should convert user messages with toolResults to tool Messages", async () => {
+            const conversationData: ConversationData = {
+                messages: [
+                    { role: "user", content: "What is the weather?" },
+                    { role: "assistant", content: "Let me check" },
+                    {
+                        role: "user",
+                        toolResults: [
+                            { id: "call_1", result: { temp: "22C", condition: "sunny" } },
+                        ],
+                    },
+                ],
+            };
+
+            agent.loadConversationSpy.and.returnValue(Promise.resolve(conversationData));
+
+            const input: any = { conversationId: "conv-123" };
+            await agent.testBeforeRun(input, {});
+
+            expect(input.history).toBeDefined();
+            expect(input.history.length).toBe(3);
+
+            // First message: user
+            expect(input.history[0]).toEqual({
+                role: "user",
+                content: "What is the weather?",
+            });
+
+            // Second message: assistant
+            expect(input.history[1]).toEqual({
+                role: "assistant",
+                content: "Let me check",
+                toolCalls: undefined,
+            });
+
+            // Third message: tool result (converted from user with toolResults)
+            expect(input.history[2]).toEqual({
+                role: "tool",
+                toolCallId: "call_1",
+                toolName: "",
+                result: JSON.stringify({ temp: "22C", condition: "sunny" }),
+            });
+        });
+
+        it("should convert multiple tool results to multiple tool Messages", async () => {
+            const conversationData: ConversationData = {
+                messages: [
+                    {
+                        role: "user",
+                        toolResults: [
+                            { id: "call_1", result: { location: "Stockholm" } },
+                            { id: "call_2", result: { temp: "22C" } },
+                        ],
+                    },
+                ],
+            };
+
+            agent.loadConversationSpy.and.returnValue(Promise.resolve(conversationData));
+
+            const input: any = { conversationId: "conv-123" };
+            await agent.testBeforeRun(input, {});
+
+            expect(input.history).toBeDefined();
+            expect(input.history.length).toBe(2);
+
+            // Each tool result becomes a separate Message
+            expect(input.history[0]).toEqual({
+                role: "tool",
+                toolCallId: "call_1",
+                toolName: "",
+                result: JSON.stringify({ location: "Stockholm" }),
+            });
+
+            expect(input.history[1]).toEqual({
+                role: "tool",
+                toolCallId: "call_2",
+                toolName: "",
+                result: JSON.stringify({ temp: "22C" }),
+            });
+        });
+
+        it("should not double-encode string tool results on reload", async () => {
+            // Real production flow: ToolExecutor.formatResultForAI returns a JSON string,
+            // which is what AgentRunner stores on tool_result content blocks. On the
+            // round-trip back from storage, that string must NOT be JSON.stringified
+            // again — otherwise the model sees escaped JSON literals on every reload.
+            const alreadyStringified = JSON.stringify({ temp: "22C", condition: "sunny" });
+
+            const conversationData: ConversationData = {
+                messages: [
+                    {
+                        role: "user",
+                        toolResults: [{ id: "call_1", result: alreadyStringified }],
+                    },
+                ],
+            };
+
+            agent.loadConversationSpy.and.returnValue(Promise.resolve(conversationData));
+
+            const input: any = { conversationId: "conv-123" };
+            await agent.testBeforeRun(input, {});
+
+            expect(input.history[0]).toEqual({
+                role: "tool",
+                toolCallId: "call_1",
+                toolName: "",
+                result: alreadyStringified, // not JSON.stringify(alreadyStringified)
+            });
+        });
+
+        it("should preserve assistant messages with toolCalls", async () => {
+            const conversationData: ConversationData = {
+                messages: [
+                    {
+                        role: "assistant",
+                        content: "Let me check",
+                        toolCalls: [
+                            { id: "call_1", name: "get-weather", input: { city: "Stockholm" } },
+                        ],
+                    },
+                ],
+            };
+
+            agent.loadConversationSpy.and.returnValue(Promise.resolve(conversationData));
+
+            const input: any = { conversationId: "conv-123" };
+            await agent.testBeforeRun(input, {});
+
+            expect(input.history).toBeDefined();
+            expect(input.history.length).toBe(1);
+            expect(input.history[0]).toEqual({
+                role: "assistant",
+                content: "Let me check",
+                toolCalls: [
+                    { id: "call_1", name: "get-weather", input: { city: "Stockholm" } },
+                ],
+            });
+        });
+    });
+
+    describe("message conversion", () => {
+        it("should convert text content blocks to StorageMessage format", () => {
+            const llmMessages = [
+                {
+                    role: "user",
+                    content: [{ type: "text", text: "Hello world" }],
+                },
+                {
+                    role: "assistant",
+                    content: [{ type: "text", text: "Hi there!" }],
+                },
+            ];
+
+            const result = agent.testConvertToMessages(llmMessages);
+
+            expect(result).toEqual([
+                { role: "user", content: "Hello world" },
+                { role: "assistant", content: "Hi there!" },
+            ]);
+        });
+
+        it("should convert tool calls from content blocks", () => {
+            const llmMessages = [
+                {
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "tool_use",
+                            id: "tool-123",
+                            name: "search-cars",
+                            input: { query: "SUV" },
+                        },
+                    ],
+                },
+            ];
+
+            const result = agent.testConvertToMessages(llmMessages);
+
+            expect(result).toEqual([
+                {
+                    role: "assistant",
+                    toolCalls: [
+                        {
+                            id: "tool-123",
+                            name: "search-cars",
+                            input: { query: "SUV" },
+                        },
+                    ],
+                },
+            ]);
+        });
+
+        it("should convert tool results from content blocks", () => {
+            const llmMessages = [
+                {
+                    role: "user",
+                    content: [
+                        {
+                            type: "tool_result",
+                            tool_use_id: "tool-123",
+                            content: { cars: ["Model X", "Model Y"] },
+                        },
+                    ],
+                },
+            ];
+
+            const result = agent.testConvertToMessages(llmMessages);
+
+            expect(result).toEqual([
+                {
+                    role: "user",
+                    toolResults: [
+                        {
+                            id: "tool-123",
+                            result: { cars: ["Model X", "Model Y"] },
+                        },
+                    ],
+                },
+            ]);
+        });
+
+        it("should handle string content (legacy format)", () => {
+            const llmMessages = [
+                {
+                    role: "user",
+                    content: "Hello",
+                },
+                {
+                    role: "assistant",
+                    content: "Hi there",
+                },
+            ];
+
+            const result = agent.testConvertToMessages(llmMessages);
+
+            expect(result).toEqual([
+                { role: "user", content: "Hello" },
+                { role: "assistant", content: "Hi there" },
+            ]);
+        });
+
+        it("should handle mixed content blocks (text + tool calls)", () => {
+            const llmMessages = [
+                {
+                    role: "assistant",
+                    content: [
+                        { type: "text", text: "Let me search for that" },
+                        {
+                            type: "tool_use",
+                            id: "tool-123",
+                            name: "search-cars",
+                            input: { query: "sedan" },
+                        },
+                    ],
+                },
+            ];
+
+            const result = agent.testConvertToMessages(llmMessages);
+
+            expect(result).toEqual([
+                {
+                    role: "assistant",
+                    content: "Let me search for that",
+                    toolCalls: [
+                        {
+                            id: "tool-123",
+                            name: "search-cars",
+                            input: { query: "sedan" },
+                        },
+                    ],
+                },
+            ]);
+        });
+    });
+});

package/spec/ai/InMemoryConversationAgent.spec.ts

@@ -0,0 +1,144 @@
+import { InMemoryConversationAgent, FlinkContext } from "../../src";
+
+class TestAgent extends InMemoryConversationAgent<FlinkContext> {
+    id = "test-agent";
+    description = "Test agent";
+    instructions() { return "You are a test agent"; }
+    tools = [];
+}
+
+describe("InMemoryConversationAgent", () => {
+    let agent: TestAgent;
+
+    beforeEach(() => {
+        InMemoryConversationAgent.clearAll();
+        agent = new TestAgent();
+        (agent as any).ctx = {} as FlinkContext;
+    });
+
+    describe("conversation storage", () => {
+        it("should save and load conversations", async () => {
+            const conversationId = "test-conv-1";
+            const testData = {
+                messages: [
+                    { role: "user" as const, content: "Hello" },
+                    { role: "assistant" as const, content: "Hi there" },
+                ],
+                providerMetadata: { openai: { responseId: "resp-123" } },
+            };
+
+            // Save
+            await (agent as any).saveConversation(conversationId, testData, {}, {});
+
+            // Load
+            const loaded = await (agent as any).loadConversation(conversationId);
+
+            expect(loaded).toEqual(testData);
+            expect(loaded?.messages.length).toBe(2);
+            expect(loaded?.providerMetadata?.openai?.responseId).toBe("resp-123");
+        });
+
+        it("should return null for non-existent conversations", async () => {
+            const loaded = await (agent as any).loadConversation("non-existent");
+            expect(loaded).toBeNull();
+        });
+
+        it("should update existing conversations", async () => {
+            const conversationId = "test-conv-2";
+
+            // First save
+            await (agent as any).saveConversation(
+                conversationId,
+                { messages: [{ role: "user", content: "First" }] },
+                {},
+                {}
+            );
+
+            // Update
+            await (agent as any).saveConversation(
+                conversationId,
+                {
+                    messages: [
+                        { role: "user", content: "First" },
+                        { role: "assistant", content: "Second" },
+                    ],
+                },
+                {},
+                {}
+            );
+
+            const loaded = await (agent as any).loadConversation(conversationId);
+            expect(loaded?.messages.length).toBe(2);
+        });
+    });
+
+    describe("static utilities", () => {
+        it("should track conversation count", async () => {
+            expect(InMemoryConversationAgent.getConversationCount()).toBe(0);
+
+            await (agent as any).saveConversation("conv-1", { messages: [] }, {}, {});
+            expect(InMemoryConversationAgent.getConversationCount()).toBe(1);
+
+            await (agent as any).saveConversation("conv-2", { messages: [] }, {}, {});
+            expect(InMemoryConversationAgent.getConversationCount()).toBe(2);
+        });
+
+        it("should clear all conversations", async () => {
+            await (agent as any).saveConversation("conv-1", { messages: [] }, {}, {});
+            await (agent as any).saveConversation("conv-2", { messages: [] }, {}, {});
+
+            expect(InMemoryConversationAgent.getConversationCount()).toBe(2);
+
+            InMemoryConversationAgent.clearAll();
+
+            expect(InMemoryConversationAgent.getConversationCount()).toBe(0);
+        });
+
+        it("should get specific conversation", async () => {
+            const testData = { messages: [{ role: "user" as const, content: "Test" }] };
+            await (agent as any).saveConversation("conv-1", testData, {}, {});
+
+            const retrieved = InMemoryConversationAgent.getConversation("conv-1");
+            expect(retrieved).toEqual(testData);
+
+            const missing = InMemoryConversationAgent.getConversation("missing");
+            expect(missing).toBeUndefined();
+        });
+
+        it("should get all conversation IDs", async () => {
+            await (agent as any).saveConversation("conv-1", { messages: [] }, {}, {});
+            await (agent as any).saveConversation("conv-2", { messages: [] }, {}, {});
+            await (agent as any).saveConversation("conv-3", { messages: [] }, {}, {});
+
+            const ids = InMemoryConversationAgent.getAllConversationIds();
+            expect(ids.length).toBe(3);
+            expect(ids).toContain("conv-1");
+            expect(ids).toContain("conv-2");
+            expect(ids).toContain("conv-3");
+        });
+    });
+
+    describe("isolation", () => {
+        it("should isolate conversations by ID", async () => {
+            await (agent as any).saveConversation(
+                "conv-a",
+                { messages: [{ role: "user" as const, content: "A" }] },
+                {},
+                {}
+            );
+
+            await (agent as any).saveConversation(
+                "conv-b",
+                { messages: [{ role: "user" as const, content: "B" }] },
+                {},
+                {}
+            );
+
+            const convA = await (agent as any).loadConversation("conv-a");
+            const convB = await (agent as any).loadConversation("conv-b");
+
+            expect(convA?.messages[0].content).toBe("A");
+            expect(convB?.messages[0].content).toBe("B");
+        });
+    });
+});