@flink-app/flink 1.0.0 → 2.0.0-alpha.49

package/spec/ConversationHooks.spec.ts

@@ -0,0 +1,290 @@
+import { z } from "zod";
+import { AgentExecuteContext, AgentExecuteInput, FlinkAgent, Message } from "../src/ai/FlinkAgent";
+import { FlinkToolProps } from "../src/ai/FlinkTool";
+import { LLMAdapter } from "../src/ai/LLMAdapter";
+import { ToolExecutor } from "../src/ai/ToolExecutor";
+import { FlinkContext } from "../src/FlinkContext";
+import { createStreamingMock } from "./testHelpers";
+
+describe("Conversation Hooks", () => {
+    let mockCtx: FlinkContext;
+    let mockLLMAdapter: LLMAdapter;
+
+    beforeEach(() => {
+        mockCtx = {
+            repos: {},
+            plugins: {},
+            agents: {},
+        };
+
+        mockLLMAdapter = createStreamingMock([
+            {
+                textContent: "Test response",
+                toolCalls: [],
+                usage: { inputTokens: 10, outputTokens: 20 },
+                stopReason: "end_turn" as const,
+            },
+        ]);
+    });
+
+    describe("beforeRun hook", () => {
+        it("should be called before execution with context", async () => {
+            const beforeRunSpy = jasmine.createSpy("beforeRun");
+
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools: string[] = [];
+
+                protected beforeRun = beforeRunSpy;
+
+                async query(message: string, conversationId?: string) {
+                    const response = this.execute({ message, conversationId });
+                    return await response.result;
+                }
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            await agent.query("Hello", "conv-123");
+
+            expect(beforeRunSpy).toHaveBeenCalled();
+            const [input, context] = beforeRunSpy.calls.mostRecent().args;
+            expect(input.message).toBe("Hello");
+            expect(input.conversationId).toBe("conv-123");
+            expect(context.conversationId).toBe("conv-123");
+            expect(context.isSubAgent).toBe(false);
+        });
+
+        it("should allow loading conversation history", async () => {
+            const mockHistory: Message[] = [
+                { role: "user", content: "Previous question" },
+                { role: "assistant", content: "Previous answer" },
+            ];
+
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools: string[] = [];
+
+                protected async beforeRun(input: AgentExecuteInput, context: AgentExecuteContext) {
+                    if (input.conversationId === "conv-123") {
+                        input.history = mockHistory;
+                    }
+                }
+
+                async query(message: string, conversationId?: string) {
+                    const response = this.execute({ message, conversationId });
+                    return await response.result;
+                }
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            await agent.query("New question", "conv-123");
+
+            // Verify LLM was called with history via stream
+            const llmCall = (mockLLMAdapter.stream as jasmine.Spy).calls.mostRecent();
+            const messages = llmCall.args[0].messages;
+
+            expect(messages.length).toBeGreaterThan(1);
+            expect(messages[0].content).toBe("Previous question");
+            expect(messages[1].content).toBe("Previous answer");
+        });
+    });
+
+    describe("onStep hook", () => {
+        it("should be called after each step with context", async () => {
+            const onStepSpy = jasmine.createSpy("onStep");
+
+            // Create tool that triggers multiple steps
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({}),
+            };
+            const toolFn = jasmine.createSpy("toolFn").and.returnValue(Promise.resolve({ success: true, data: { result: "ok" } }));
+            const toolExecutor = new ToolExecutor(toolProps, toolFn as any, mockCtx);
+            const toolsMap = new Map([["test_tool", toolExecutor]]);
+
+            // Mock LLM to call tool, then finish
+            const toolMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [{ id: "1", name: "test_tool", input: {} }],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Done",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools: string[] = ["test_tool"];
+
+                protected onStep = onStepSpy;
+
+                async query(message: string) {
+                    const response = this.execute({ message });
+                    return await response.result;
+                }
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", toolMockAdapter]]), Object.fromEntries(toolsMap));
+
+            await agent.query("Test");
+
+            // Should be called twice (after each step)
+            expect(onStepSpy).toHaveBeenCalledTimes(2);
+
+            const firstCall = onStepSpy.calls.first().args[0];
+            expect(firstCall.step).toBe(1);
+            expect(firstCall.messages).toBeDefined();
+            expect(Array.isArray(firstCall.messages)).toBe(true);
+        });
+    });
+
+    describe("afterRun hook", () => {
+        it("should be called after execution with full context", async () => {
+            const afterRunSpy = jasmine.createSpy("afterRun");
+
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools: string[] = [];
+
+                protected afterRun = afterRunSpy;
+
+                async query(message: string, conversationId?: string) {
+                    const response = this.execute({ message, conversationId });
+                    return await response.result;
+                }
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            await agent.query("Hello", "conv-456");
+
+            expect(afterRunSpy).toHaveBeenCalled();
+            const [result, context] = afterRunSpy.calls.mostRecent().args;
+            expect(result.message).toBe("Test response");
+            expect(context.conversationId).toBe("conv-456");
+            expect(context.messages).toBeDefined();
+            expect(context.result).toBe(result);
+        });
+
+        it("should not be called for sub-agents when using inherit strategy", async () => {
+            const afterRunSpy = jasmine.createSpy("afterRun");
+
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools: string[] = [];
+                conversationStrategy = "inherit" as const;
+
+                protected afterRun = afterRunSpy;
+
+                async query(message: string) {
+                    const response = this.execute({ message });
+                    return await response.result;
+                }
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            // Execute with isSubAgentCall metadata using public run method
+            const response = agent.run({
+                message: "Test",
+                metadata: { isSubAgentCall: true, parentAgentId: "parent" },
+            });
+            await response.result;
+
+            // afterRun should still be called (agent decides whether to save based on isSubAgent flag)
+            expect(afterRunSpy).toHaveBeenCalled();
+            const context = afterRunSpy.calls.mostRecent().args[1];
+            expect(context.isSubAgent).toBe(true);
+        });
+    });
+
+    describe("metadata propagation", () => {
+        it("should propagate metadata through execution context", async () => {
+            const beforeRunSpy = jasmine.createSpy("beforeRun");
+            const afterRunSpy = jasmine.createSpy("afterRun");
+
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools: string[] = [];
+
+                protected beforeRun = beforeRunSpy;
+                protected afterRun = afterRunSpy;
+
+                async query(message: string) {
+                    const response = this.execute({
+                        message,
+                        metadata: { customKey: "customValue", traceId: "trace-123" },
+                    });
+                    return await response.result;
+                }
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            await agent.query("Test");
+
+            const beforeRunContext = beforeRunSpy.calls.mostRecent().args[1];
+            expect(beforeRunContext.metadata).toEqual({
+                customKey: "customValue",
+                traceId: "trace-123",
+            });
+
+            const afterRunContext = afterRunSpy.calls.mostRecent().args[1];
+            expect(afterRunContext.metadata).toEqual({
+                customKey: "customValue",
+                traceId: "trace-123",
+            });
+        });
+    });
+});

package/spec/FlinkAgent.spec.ts

@@ -0,0 +1,310 @@
+import { z } from "zod";
+import { FlinkAgent } from "../src/ai/FlinkAgent";
+import { FlinkToolProps } from "../src/ai/FlinkTool";
+import { LLMAdapter } from "../src/ai/LLMAdapter";
+import { ToolExecutor } from "../src/ai/ToolExecutor";
+import { FlinkContext } from "../src/FlinkContext";
+import { createStreamingMock } from "./testHelpers";
+
+describe("FlinkAgent", () => {
+    let mockCtx: FlinkContext;
+    let mockLLMAdapter: LLMAdapter;
+
+    beforeEach(() => {
+        mockCtx = {
+            repos: {},
+            plugins: {},
+        };
+
+        // Mock LLM Adapter
+        mockLLMAdapter = createStreamingMock([
+            {
+                textContent: "Test response",
+                toolCalls: [],
+                usage: { inputTokens: 10, outputTokens: 20 },
+                stopReason: "end_turn" as const,
+            },
+        ]);
+    });
+
+    describe("withUser binding", () => {
+        class TestAgent extends FlinkAgent<FlinkContext> {
+            description = "Test agent";
+            instructions = "Test instructions";
+            tools: string[] = [];
+
+            async query(message: string) {
+                const response = this.execute({ message });
+                return await response.result;
+            }
+
+            setContext(ctx: FlinkContext) {
+                (this as any).ctx = ctx;
+            }
+        }
+
+        it("should bind user to agent instance", () => {
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+
+            const user = { id: "123", permissions: ["admin"] };
+            const boundAgent = agent.withUser(user);
+
+            // Should return a new instance
+            expect(boundAgent).not.toBe(agent);
+            // Should have bound user
+            expect((boundAgent as any)._boundUser).toBe(user);
+        });
+
+        it("should use bound user for agent permission checks", async () => {
+            class PermissionedAgent extends TestAgent {
+                permissions = "admin";
+            }
+
+            const agent = new PermissionedAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            const userWithoutPermission = { permissions: [] };
+            const userWithPermission = { permissions: ["admin"] };
+
+            // Should fail without permission
+            const boundAgentFail = agent.withUser(userWithoutPermission);
+            await expectAsync(boundAgentFail.query("test")).toBeRejected();
+
+            // Should succeed with permission
+            const boundAgentSuccess = agent.withUser(userWithPermission);
+            const result = await boundAgentSuccess.query("test");
+            expect(result.message).toBeDefined();
+        });
+
+        it("should pass bound user to tools", async () => {
+            const toolSpy = jasmine.createSpy("toolFn").and.returnValue(Promise.resolve({ success: true, data: { result: "ok" } }));
+
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({}),
+            };
+
+            const toolExecutor = new ToolExecutor(toolProps, toolSpy as any, mockCtx);
+            const toolsMap = new Map([["test_tool", toolExecutor]]);
+
+            // Mock LLM to call tool
+            const toolMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [{ id: "1", name: "test_tool", input: {} }],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Done",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 20 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            class ToolAgent extends TestAgent {
+                tools: string[] = ["test_tool"];
+            }
+
+            const agent = new ToolAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", toolMockAdapter]]), Object.fromEntries(toolsMap));
+
+            const user = { id: "123", permissions: ["admin"] };
+            const boundAgent = agent.withUser(user);
+
+            await boundAgent.query("test");
+
+            // Tool should have been called with the bound user
+            expect(toolSpy).toHaveBeenCalled();
+            const toolCall = (toolSpy as jasmine.Spy).calls.mostRecent();
+            expect(toolCall.args[0].user).toBe(user);
+        });
+    });
+
+    describe("Tool permission filtering", () => {
+        class TestAgent extends FlinkAgent<FlinkContext> {
+            description = "Test agent";
+            instructions = "Test instructions";
+            tools: string[] = ["public_tool", "admin_tool"];
+
+            async query(message: string) {
+                const response = this.execute({ message });
+                return await response.result;
+            }
+
+            setContext(ctx: FlinkContext) {
+                (this as any).ctx = ctx;
+            }
+        }
+
+        it("should filter out tools user doesn't have permission for", async () => {
+            // Create public tool (no permissions)
+            const publicToolProps: FlinkToolProps = {
+                id: "public_tool",
+                description: "Public tool",
+                inputSchema: z.object({}),
+            };
+            const publicToolFn = async () => ({ success: true as const, data: {} });
+            const publicTool = new ToolExecutor(publicToolProps, publicToolFn, mockCtx);
+
+            // Create admin tool (requires admin permission)
+            const adminToolProps: FlinkToolProps = {
+                id: "admin_tool",
+                description: "Admin tool",
+                inputSchema: z.object({}),
+                permissions: "admin",
+            };
+            const adminToolFn = async () => ({ success: true as const, data: {} });
+            const adminTool = new ToolExecutor(adminToolProps, adminToolFn, mockCtx);
+
+            const toolsMap = new Map([
+                ["public_tool", publicTool],
+                ["admin_tool", adminTool],
+            ]);
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), Object.fromEntries(toolsMap));
+
+            // User without admin permission
+            const regularUser = { permissions: [] };
+            const boundAgent = agent.withUser(regularUser);
+
+            await boundAgent.query("test");
+
+            // LLM should have been called with only the public tool via stream
+            const llmCall = (mockLLMAdapter.stream as jasmine.Spy).calls.mostRecent();
+            const toolsProvided = llmCall.args[0].tools;
+
+            expect(toolsProvided.length).toBe(1);
+            expect(toolsProvided[0].name).toBe("public_tool");
+        });
+
+        it("should show all tools to admin users", async () => {
+            // Create public and admin tools (same as above)
+            const publicToolProps: FlinkToolProps = {
+                id: "public_tool",
+                description: "Public tool",
+                inputSchema: z.object({}),
+            };
+            const publicToolFn = async () => ({ success: true as const, data: {} });
+            const publicTool = new ToolExecutor(publicToolProps, publicToolFn, mockCtx);
+
+            const adminToolProps: FlinkToolProps = {
+                id: "admin_tool",
+                description: "Admin tool",
+                inputSchema: z.object({}),
+                permissions: "admin",
+            };
+            const adminToolFn = async () => ({ success: true as const, data: {} });
+            const adminTool = new ToolExecutor(adminToolProps, adminToolFn, mockCtx);
+
+            const toolsMap = new Map([
+                ["public_tool", publicTool],
+                ["admin_tool", adminTool],
+            ]);
+
+            const agent = new TestAgent();
+            agent.setContext(mockCtx);
+            agent.__init(new Map([["default", mockLLMAdapter]]), Object.fromEntries(toolsMap));
+
+            // User with admin permission
+            const adminUser = { permissions: ["admin"] };
+            const boundAgent = agent.withUser(adminUser);
+
+            await boundAgent.query("test");
+
+            // LLM should have been called with both tools via stream
+            const llmCall = (mockLLMAdapter.stream as jasmine.Spy).calls.mostRecent();
+            const toolsProvided = llmCall.args[0].tools;
+
+            expect(toolsProvided.length).toBe(2);
+            expect(toolsProvided.map((t: any) => t.name).sort()).toEqual(["admin_tool", "public_tool"]);
+        });
+    });
+
+    describe("Tool references (FlinkToolFile imports)", () => {
+        it("should support tool file references in addition to string IDs", () => {
+            // Create mock tool file (same structure as real tool files)
+            const mockToolFile = {
+                Tool: {
+                    id: "mock-tool",
+                    description: "Mock tool for testing",
+                    inputSchema: z.object({ input: z.string() }),
+                },
+                default: async () => ({ success: true as const, data: "ok" }),
+            };
+
+            // Create tool executor from the mock file
+            const toolExecutor = new ToolExecutor(mockToolFile.Tool, mockToolFile.default as any, mockCtx);
+
+            // Set up tools in context (not as Map, but as plain object for _tools)
+            // Agent using tool reference instead of string ID
+            class TestAgentWithToolRef extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools = [mockToolFile]; // Direct tool file reference!
+
+                async query(message: string) {
+                    const response = this.execute({ message });
+                    return await response.result;
+                }
+            }
+
+            const agent = new TestAgentWithToolRef();
+            (agent as any).ctx = mockCtx;
+            agent.__init(new Map([["default", mockLLMAdapter]]), { "mock-tool": toolExecutor });
+
+            // Verify resolveTools() correctly extracts tool ID from FlinkToolFile
+            const resolvedTools = (agent as any).resolveTools();
+            expect(resolvedTools.has("mock-tool")).toBe(true);
+            expect(resolvedTools.get("mock-tool")).toBe(toolExecutor);
+        });
+
+        it("should support mixed string IDs and tool file references", () => {
+            // Create two tools: one referenced by string, one by file reference
+            const mockToolFile = {
+                Tool: {
+                    id: "tool-by-reference",
+                    description: "Tool referenced by import",
+                    inputSchema: z.object({}),
+                },
+                default: async () => ({ success: true as const, data: "ok" }),
+            };
+
+            const toolByRefExecutor = new ToolExecutor(mockToolFile.Tool, mockToolFile.default as any, mockCtx);
+            const toolByStringExecutor = new ToolExecutor(
+                { id: "tool-by-string", description: "Tool by string", inputSchema: z.object({}) },
+                async () => ({ success: true as const, data: "ok" }),
+                mockCtx
+            );
+
+            class MixedToolsAgent extends FlinkAgent<FlinkContext> {
+                description = "Test agent";
+                instructions = "Test instructions";
+                tools = [
+                    mockToolFile, // File reference
+                    "tool-by-string", // String ID
+                ];
+            }
+
+            const agent = new MixedToolsAgent();
+            (agent as any).ctx = mockCtx;
+            agent.__init(new Map([["default", mockLLMAdapter]]), {
+                "tool-by-reference": toolByRefExecutor,
+                "tool-by-string": toolByStringExecutor,
+            });
+
+            // Both tools should be resolved correctly
+            const resolvedTools = (agent as any).resolveTools();
+            expect(resolvedTools.size).toBe(2);
+            expect(resolvedTools.has("tool-by-reference")).toBe(true);
+            expect(resolvedTools.has("tool-by-string")).toBe(true);
+        });
+    });
+});

package/spec/FlinkApp.onError.spec.ts

@@ -1,9 +1,8 @@
 import { FlinkApp } from "../src/FlinkApp";
 import { FlinkContext } from "../src/FlinkContext";
-import { FlinkResponse } from "../src/FlinkResponse";
 import { FlinkError } from "../src/FlinkErrors";
-import { badRequest, internalServerError, notFound } from "../src/FlinkErrors";
 import { HttpMethod } from "../src/FlinkHttpHandler";
+import { FlinkResponse } from "../src/FlinkResponse";
 
 interface TestContext extends FlinkContext {}