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

package/spec/AgentRunner.spec.ts

@@ -0,0 +1,1062 @@
+import { z } from "zod";
+import { AgentRunner } from "../src/ai/AgentRunner";
+import { FlinkAgentProps } from "../src/ai/FlinkAgent";
+import { ToolExecutor } from "../src/ai/ToolExecutor";
+import { FlinkContext } from "../src/FlinkContext";
+import { FlinkToolProps } from "../src/ai/FlinkTool";
+import { LLMAdapter } from "../src/ai/LLMAdapter";
+import { createStreamingMock } from "./testHelpers";
+
+describe("AgentRunner", () => {
+    let mockCtx: FlinkContext;
+    let mockLLMAdapter: LLMAdapter;
+
+    beforeEach(() => {
+        mockCtx = {
+            repos: {},
+            plugins: {},
+        };
+
+        // Mock LLM Adapter with default response
+        mockLLMAdapter = createStreamingMock([
+            {
+                textContent: "Test response",
+                toolCalls: [],
+                usage: { inputTokens: 10, outputTokens: 20 },
+                stopReason: "end_turn" as const,
+            },
+        ]);
+    });
+
+    describe("Basic execution", () => {
+        it("should execute simple agent without tools", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are a helpful assistant",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+            const chunks: any[] = [];
+
+            for await (const chunk of generator) {
+                chunks.push(chunk);
+            }
+
+            // Should have complete event
+            expect(chunks.length).toBeGreaterThan(0);
+            const completeChunk = chunks.find((c) => c.type === "complete");
+            expect(completeChunk).toBeDefined();
+            expect(completeChunk.result.message).toBe("Test response");
+            expect(completeChunk.result.stepsUsed).toBeGreaterThan(0);
+            expect(completeChunk.result.toolCalls).toEqual([]);
+        });
+
+        it("should track token usage", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are a helpful assistant",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result.usage).toBeDefined();
+                    expect(chunk.result.usage?.inputTokens).toBeGreaterThan(0);
+                    expect(chunk.result.usage?.outputTokens).toBeGreaterThan(0);
+                }
+            }
+        });
+    });
+
+    describe("Tool calling", () => {
+        it("should execute tool calls", async () => {
+            // Create mock tool
+            const toolProps: FlinkToolProps = {
+                id: "get_weather",
+                description: "Get weather",
+                inputSchema: z.object({ city: z.string() }),
+            };
+
+            const toolFn = jasmine.createSpy("toolFn").and.returnValue(
+                Promise.resolve({
+                    success: true,
+                    data: { temperature: 22, conditions: "sunny" },
+                })
+            );
+
+            const toolExecutor = new ToolExecutor(toolProps, toolFn as any, mockCtx);
+            const toolsMap = new Map([["get_weather", toolExecutor]]);
+
+            // Mock LLM adapter response with tool call
+            const weatherMockAdapter = createStreamingMock([
+                // First call: agent requests tool
+                {
+                    textContent: "Let me check the weather",
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "get_weather",
+                            input: { city: "Stockholm" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+                // Second call: agent responds with result
+                {
+                    textContent: "It's sunny and 22°C",
+                    toolCalls: [],
+                    usage: { inputTokens: 15, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "weather_agent",
+                description: "Weather assistant",
+                instructions: "You help with weather",
+                tools: ["get_weather"],
+            };
+
+            const llmAdapters = new Map();
+            llmAdapters.set("default", weatherMockAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "What's the weather in Stockholm?" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result.message).toBe("It's sunny and 22°C");
+                    expect(chunk.result.toolCalls.length).toBe(1);
+                    expect(chunk.result.toolCalls[0].name).toBe("get_weather");
+                    expect(chunk.result.toolCalls[0].input).toEqual({ city: "Stockholm" });
+                    expect(chunk.result.toolCalls[0].output).toEqual({
+                        temperature: 22,
+                        conditions: "sunny",
+                    });
+                    expect(chunk.result.stepsUsed).toBe(2);
+                }
+            }
+
+            // Verify tool was called
+            expect(toolFn).toHaveBeenCalledWith({
+                input: { city: "Stockholm" },
+                ctx: mockCtx,
+                user: undefined,
+                permissions: undefined,
+                conversationCtx: undefined,
+            });
+        });
+
+        it("should handle tool errors gracefully", async () => {
+            // Create mock tool that returns error
+            const toolProps: FlinkToolProps = {
+                id: "get_weather",
+                description: "Get weather",
+                inputSchema: z.object({ city: z.string() }),
+            };
+
+            const toolFn = jasmine.createSpy("toolFn").and.returnValue(
+                Promise.resolve({
+                    success: false,
+                    error: "API unavailable",
+                    code: "SERVICE_ERROR",
+                })
+            );
+
+            const toolExecutor = new ToolExecutor(toolProps, toolFn as any, mockCtx);
+            const toolsMap = new Map([["get_weather", toolExecutor]]);
+
+            // Mock LLM adapter response with tool call
+            const errorMockAdapter = createStreamingMock([
+                // First call: agent requests tool
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "get_weather",
+                            input: { city: "Stockholm" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+                // Second call: agent handles error
+                {
+                    textContent: "Sorry, weather service is unavailable",
+                    toolCalls: [],
+                    usage: { inputTokens: 15, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "weather_agent",
+                description: "Weather assistant",
+                instructions: "You help with weather",
+                tools: ["get_weather"],
+            };
+
+            const llmAdapters = new Map();
+            llmAdapters.set("default", errorMockAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "What's the weather?" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result.toolCalls.length).toBe(1);
+                    expect(chunk.result.toolCalls[0].error).toBe("API unavailable");
+                    expect(chunk.result.toolCalls[0].output).toBeNull();
+                }
+            }
+        });
+
+        it("should handle missing tools", async () => {
+            const toolsMap = new Map(); // No tools registered
+
+            // Mock LLM adapter response requesting non-existent tool
+            const missingToolMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "missing_tool",
+                            input: {},
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Tool not available",
+                    toolCalls: [],
+                    usage: { inputTokens: 15, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const llmAdapters = new Map();
+            llmAdapters.set("default", missingToolMockAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "Test" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result.toolCalls.length).toBe(1);
+                    expect(chunk.result.toolCalls[0].error).toContain("not found");
+                }
+            }
+        });
+    });
+
+    describe("Step limits", () => {
+        it("should respect maxSteps limit", async () => {
+            // Mock infinite tool calling loop
+            const infiniteLoopMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "test_tool",
+                            input: {},
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+            ]);
+
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({}),
+            };
+
+            const toolFn = async () => ({ success: true as const, data: {} });
+            const toolExecutor = new ToolExecutor(toolProps, toolFn, mockCtx);
+            const toolsMap = new Map([["test_tool", toolExecutor]]);
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: ["test_tool"],
+                limits: { maxSteps: 3 },
+            };
+
+            const llmAdapters = new Map();
+            llmAdapters.set("default", infiniteLoopMockAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "Test" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result.stepsUsed).toBe(3);
+                    expect(chunk.result.stoppedEarly).toBe(true);
+                }
+            }
+        });
+
+        it("should allow runtime maxSteps override", async () => {
+            const runtimeOverrideMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "test_tool",
+                            input: {},
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+            ]);
+
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({}),
+            };
+
+            const toolFn = async () => ({ success: true as const, data: {} });
+            const toolExecutor = new ToolExecutor(toolProps, toolFn, mockCtx);
+            const toolsMap = new Map([["test_tool", toolExecutor]]);
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: ["test_tool"],
+                limits: { maxSteps: 10 },
+            };
+
+            const llmAdapters = new Map();
+            llmAdapters.set("default", runtimeOverrideMockAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({
+                message: "Test",
+                options: { maxSteps: 2 },
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result.stepsUsed).toBe(2);
+                    expect(chunk.result.stoppedEarly).toBe(true);
+                }
+            }
+        });
+    });
+
+    describe("Message format conversion", () => {
+        it("should convert string to message array", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result).toBeDefined();
+                }
+            }
+
+            // Verify LLM adapter was called with user message
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            expect(callArgs.messages.length).toBeGreaterThanOrEqual(1);
+            expect(callArgs.messages[0]).toEqual({ role: "user", content: "Hello" });
+        });
+
+        it("should convert Message[] to Anthropic format", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({
+                message: [
+                    { role: "user", content: "Hello" },
+                    { role: "user", content: "How are you?" },
+                ],
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result).toBeDefined();
+                }
+            }
+
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+        });
+    });
+
+    describe("Model configuration", () => {
+        it("should pass configuration to LLM adapter", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            // Verify LLM adapter was called via stream
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.mostRecent().args[0];
+            expect(callArgs.instructions).toBe("You are helpful");
+        });
+
+        it("should pass custom temperature and maxTokens", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+                model: {
+                    temperature: 0.3,
+                    maxTokens: 2000,
+                },
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.mostRecent().args[0];
+            expect(callArgs.temperature).toBe(0.3);
+            expect(callArgs.maxTokens).toBe(2000);
+        });
+    });
+
+    describe("Error handling", () => {
+        it("should throw error when LLM adapter not configured", () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map(); // Empty map
+
+            expect(() => {
+                new AgentRunner(agentProps, toolsMap, llmAdapters);
+            }).toThrowError(/not configured/);
+        });
+
+        it("should throw error for unregistered adapter", () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+                model: {
+                    adapterId: "openai",
+                },
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+
+            expect(() => {
+                new AgentRunner(agentProps, toolsMap, llmAdapters);
+            }).toThrowError(/LLM adapter "openai" not configured/);
+        });
+    });
+
+    describe("Message Conversion with Conversation History", () => {
+        it("should preserve assistant messages without tool calls", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const history = [
+                { role: "user" as const, content: "Who are you?" },
+                { role: "assistant" as const, content: "I'm a weather assistant." },
+            ];
+
+            const generator = runner.streamGenerator({
+                message: "What's the weather?",
+                history,
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            // Verify LLM adapter was called with history preserved
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            const messages = callArgs.messages;
+
+            // Note: messages array gets mutated after LLM call (assistant message added)
+            // So we check that the first 3 messages are correct (history + new user message)
+            expect(messages.length).toBeGreaterThanOrEqual(3);
+            expect(messages[0]).toEqual({ role: "user", content: "Who are you?" });
+            expect(messages[1]).toEqual({ role: "assistant", content: "I'm a weather assistant." });
+            expect(messages[2]).toEqual({ role: "user", content: "What's the weather?" });
+
+            // Verify assistant message from history was preserved (not filtered out)
+            expect(messages[1].role).toBe("assistant");
+            expect(messages[1].content).toBe("I'm a weather assistant.");
+        });
+
+        it("should preserve assistant messages with tool calls", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const history = [
+                { role: "user" as const, content: "What's the weather in Stockholm?" },
+                {
+                    role: "assistant" as const,
+                    content: "",
+                    toolCalls: [{ id: "1", name: "get-weather", input: { city: "Stockholm" } }],
+                },
+                { role: "tool" as const, toolCallId: "1", toolName: "get-weather", result: "22°C, Sunny" },
+            ];
+
+            const generator = runner.streamGenerator({
+                message: "And tomorrow?",
+                history,
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            const messages = callArgs.messages;
+
+            // Note: messages array gets mutated after LLM call
+            // Check first 4 messages: history (3) + new user message (1)
+            expect(messages.length).toBeGreaterThanOrEqual(4);
+            expect(messages[0].role).toBe("user");
+            expect(messages[1].role).toBe("assistant");
+            expect(messages[2].role).toBe("user"); // Tool result
+            expect(messages[3].role).toBe("user"); // New message
+
+            // Assistant message should have tool_use content blocks (preserved from history)
+            expect(Array.isArray(messages[1].content)).toBe(true);
+            const contentBlocks = messages[1].content as any[];
+            expect(contentBlocks.length).toBe(1);
+            expect(contentBlocks[0].type).toBe("tool_use");
+            expect(contentBlocks[0].name).toBe("get-weather");
+            expect(contentBlocks[0].input).toEqual({ city: "Stockholm" });
+        });
+
+        it("should maintain alternating user/assistant pattern", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const history = [
+                { role: "user" as const, content: "Hello" },
+                { role: "assistant" as const, content: "Hi there!" },
+                { role: "user" as const, content: "How are you?" },
+                { role: "assistant" as const, content: "I'm doing well!" },
+            ];
+
+            const generator = runner.streamGenerator({
+                message: "What's your name?",
+                history,
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            const messages = callArgs.messages;
+
+            // Note: messages array gets mutated after LLM call
+            // Check first 5 messages: history (4) + new user message (1)
+            expect(messages.length).toBeGreaterThanOrEqual(5);
+
+            // Verify no consecutive user or assistant messages in the first 5 (input messages)
+            for (let i = 1; i < Math.min(5, messages.length); i++) {
+                expect(messages[i].role).not.toBe(messages[i - 1].role);
+            }
+        });
+
+        it("should handle assistant messages with both text and tool calls", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const history = [
+                { role: "user" as const, content: "Check the weather" },
+                {
+                    role: "assistant" as const,
+                    content: "Let me check that for you",
+                    toolCalls: [{ id: "1", name: "get-weather", input: { city: "Stockholm" } }],
+                },
+            ];
+
+            const generator = runner.streamGenerator({ message: history });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            const messages = callArgs.messages;
+
+            // Assistant message should have both text and tool_use blocks
+            expect(Array.isArray(messages[1].content)).toBe(true);
+            const contentBlocks = messages[1].content as any[];
+            expect(contentBlocks.length).toBe(2);
+            expect(contentBlocks[0].type).toBe("text");
+            expect(contentBlocks[0].text).toBe("Let me check that for you");
+            expect(contentBlocks[1].type).toBe("tool_use");
+            expect(contentBlocks[1].name).toBe("get-weather");
+        });
+
+        it("should convert tool messages to user messages with results", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const history = [
+                { role: "user" as const, content: "Check weather" },
+                {
+                    role: "assistant" as const,
+                    content: "",
+                    toolCalls: [{ id: "1", name: "get-weather", input: { city: "Stockholm" } }],
+                },
+                { role: "tool" as const, toolCallId: "1", toolName: "get-weather", result: "22°C" },
+            ];
+
+            const generator = runner.streamGenerator({ message: history });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            const messages = callArgs.messages;
+
+            // Tool message should be converted to user message with tool_result content block
+            expect(messages[2].role).toBe("user");
+            expect(Array.isArray(messages[2].content)).toBe(true);
+            const contentBlocks = messages[2].content as any[];
+            expect(contentBlocks.length).toBe(1);
+            expect(contentBlocks[0].type).toBe("tool_result");
+            expect(contentBlocks[0].tool_use_id).toBe("1");
+            expect(contentBlocks[0].content).toBe("22°C");
+        });
+
+        it("should handle empty content with tool calls", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "You are helpful",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters);
+
+            const history = [
+                { role: "user" as const, content: "Check weather" },
+                {
+                    role: "assistant" as const,
+                    content: "", // Empty content
+                    toolCalls: [{ id: "1", name: "get-weather", input: {} }],
+                },
+            ];
+
+            const generator = runner.streamGenerator({ message: history });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            const messages = callArgs.messages;
+
+            // Assistant message should only have tool_use block (no text block for empty content)
+            expect(Array.isArray(messages[1].content)).toBe(true);
+            const contentBlocks = messages[1].content as any[];
+            expect(contentBlocks.length).toBe(1);
+            expect(contentBlocks[0].type).toBe("tool_use");
+        });
+    });
+
+    describe("Dynamic Instructions", () => {
+        it("should use static string instructions (backwards compatibility)", async () => {
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: "Static instructions",
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters, "test_agent", mockCtx);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            // Verify LLM was called with static instructions
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const callArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            expect(callArgs.instructions).toBe("Static instructions");
+        });
+
+        it("should resolve synchronous callback instructions", async () => {
+            const instructionsCallback = jasmine.createSpy("instructionsCallback").and.returnValue("Dynamic: test-user");
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: instructionsCallback,
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters, "test_agent", mockCtx);
+
+            const generator = runner.streamGenerator({
+                message: "Hello",
+                user: { id: "123", name: "test-user" },
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            // Verify callback was called with correct context
+            expect(instructionsCallback).toHaveBeenCalledTimes(1);
+            const callArgs = instructionsCallback.calls.first().args;
+            expect(callArgs[0]).toBe(mockCtx); // ctx
+            expect(callArgs[1].user).toEqual({ id: "123", name: "test-user" }); // agentContext
+
+            // Verify LLM was called with resolved instructions
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const llmCallArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            expect(llmCallArgs.instructions).toBe("Dynamic: test-user");
+        });
+
+        it("should resolve async callback instructions", async () => {
+            const mockUser = { id: "123", name: "test-user", tier: "premium" };
+            const mockRepoCtx = {
+                repos: {
+                    userRepo: {
+                        getById: jasmine.createSpy("getById").and.returnValue(Promise.resolve(mockUser)),
+                    },
+                },
+                plugins: {},
+            };
+
+            const instructionsCallback = async (ctx: any, agentContext: any) => {
+                const profile = await ctx.repos.userRepo.getById(agentContext.user.id);
+                return `You are a support agent. Customer: ${profile.name}, Tier: ${profile.tier}`;
+            };
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: instructionsCallback,
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters, "test_agent", mockRepoCtx);
+
+            const generator = runner.streamGenerator({
+                message: "Hello",
+                user: { id: "123" },
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            // Verify repo was called
+            expect(mockRepoCtx.repos.userRepo.getById).toHaveBeenCalledWith("123");
+
+            // Verify LLM was called with resolved instructions
+            expect(mockLLMAdapter.stream).toHaveBeenCalled();
+            const llmCallArgs = (mockLLMAdapter.stream as jasmine.Spy).calls.first().args[0];
+            expect(llmCallArgs.instructions).toBe("You are a support agent. Customer: test-user, Tier: premium");
+        });
+
+        it("should pass correct context to callback", async () => {
+            const instructionsCallback = jasmine.createSpy("instructionsCallback").and.returnValue("Instructions");
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: instructionsCallback,
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters, "test_agent", mockCtx);
+
+            const generator = runner.streamGenerator({
+                message: "Hello",
+                user: { id: "123" },
+                conversationId: "conv-456",
+                metadata: { source: "handler" },
+            });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    break;
+                }
+            }
+
+            // Verify callback received correct context
+            expect(instructionsCallback).toHaveBeenCalledTimes(1);
+            const callArgs = instructionsCallback.calls.first().args;
+
+            // Check ctx parameter
+            expect(callArgs[0]).toBe(mockCtx);
+
+            // Check execContext parameter
+            const execContext = callArgs[1];
+            expect(execContext.agentId).toBe("test_agent");
+            expect(execContext.conversationId).toBe("conv-456");
+            expect(execContext.user).toEqual({ id: "123" });
+            expect(execContext.metadata).toEqual({ source: "handler" });
+        });
+
+        it("should handle callback errors gracefully", async () => {
+            const instructionsCallback = () => {
+                throw new Error("Database connection failed");
+            };
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: instructionsCallback,
+                tools: [],
+            };
+
+            const toolsMap = new Map();
+            const llmAdapters = new Map();
+            llmAdapters.set("default", mockLLMAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters, "test_agent", mockCtx);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+
+            try {
+                for await (const chunk of generator) {
+                    // Should not reach here
+                }
+                fail("Expected error to be thrown");
+            } catch (err: any) {
+                expect(err.message).toContain("Failed to resolve instructions for agent test_agent");
+                expect(err.message).toContain("Database connection failed");
+            }
+        });
+
+        it("should resolve instructions once per execution", async () => {
+            let callCount = 0;
+            const instructionsCallback = () => {
+                callCount++;
+                return "Instructions";
+            };
+
+            // Mock adapter that calls LLM 3 times (3 steps with tool calls)
+            const multiStepMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [{ id: "tool_1", name: "test_tool", input: {} }],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: undefined,
+                    toolCalls: [{ id: "tool_2", name: "test_tool", input: {} }],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Final response",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({}),
+            };
+            const toolFn = async () => ({ success: true as const, data: {} });
+            const toolExecutor = new ToolExecutor(toolProps, toolFn, mockCtx);
+            const toolsMap = new Map([["test_tool", toolExecutor]]);
+
+            const agentProps: FlinkAgentProps<typeof mockCtx> = {
+                id: "test_agent",
+                description: "Test agent",
+                instructions: instructionsCallback,
+                tools: ["test_tool"],
+            };
+
+            const llmAdapters = new Map();
+            llmAdapters.set("default", multiStepMockAdapter);
+            const runner = new AgentRunner(agentProps, toolsMap, llmAdapters, "test_agent", mockCtx);
+
+            const generator = runner.streamGenerator({ message: "Hello" });
+
+            for await (const chunk of generator) {
+                if (chunk.type === "complete") {
+                    expect(chunk.result.stepsUsed).toBe(3);
+                }
+            }
+
+            // Callback should be called ONCE, not 3 times
+            expect(callCount).toBe(1);
+        });
+    });
+});