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

package/spec/AsyncLocalStorageContext.spec.ts

@@ -0,0 +1,223 @@
+import { FlinkContext } from '../src/FlinkContext';
+import { ToolExecutor } from '../src/ai/ToolExecutor';
+import { FlinkTool, FlinkToolProps } from '../src/ai/FlinkTool';
+import { requestContext, getRequestUser, getReqId, getRequestPermissions, hasPermission, hasAllPermissions, hasAnyPermission } from '../src/FlinkRequestContext';
+import { z } from 'zod';
+
+describe("AsyncLocalStorage Request Context", () => {
+    let mockCtx: FlinkContext;
+
+    beforeEach(() => {
+        mockCtx = {
+            repos: {},
+            plugins: {},
+        };
+    });
+
+    describe("Basic context availability", () => {
+        it("should provide request context within requestContext.run()", async () => {
+            const testContext = {
+                reqId: "test-123",
+                user: { id: "user-1", username: "testuser" },
+                userPermissions: ["car:read"],
+                timestamp: Date.now(),
+            };
+
+            await requestContext.run(testContext, async () => {
+                expect(getReqId()).toBe("test-123");
+                expect(getRequestUser()).toEqual(testContext.user);
+                expect(getRequestPermissions()).toEqual(["car:read"]);
+            });
+        });
+
+        it("should return undefined outside of request context", () => {
+            expect(getReqId()).toBeUndefined();
+            expect(getRequestUser()).toBeUndefined();
+            expect(getRequestPermissions()).toEqual([]);
+        });
+    });
+
+    describe("Tool execution with context", () => {
+        it("should access context inside tool execution", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test-tool",
+                description: "Test tool",
+                inputSchema: z.object({ value: z.string() }),
+            };
+
+            let capturedReqId: string | undefined;
+            let capturedUser: any;
+
+            const toolFn: FlinkTool<any, any, any> = async ({ input }) => {
+                capturedReqId = getReqId();
+                capturedUser = getRequestUser();
+                return { success: true, data: { result: input.value } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const testContext = {
+                reqId: "tool-test-123",
+                user: { id: "user-2", username: "tooltester" },
+                timestamp: Date.now(),
+            };
+
+            await requestContext.run(testContext, async () => {
+                const result = await executor.execute({ value: "hello" });
+                expect(result.success).toBe(true);
+            });
+
+            expect(capturedReqId).toBe("tool-test-123");
+            expect(capturedUser).toEqual(testContext.user);
+        });
+
+        it("should inject user and permissions into tool handler parameters", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test-tool-params",
+                description: "Test tool with user/permissions parameters",
+                inputSchema: z.object({ value: z.string() }),
+            };
+
+            let capturedUser: any;
+            let capturedPermissions: string[] | undefined;
+
+            const toolFn: FlinkTool<any, any, any> = async ({ input, user, permissions }) => {
+                capturedUser = user;
+                capturedPermissions = permissions;
+                return { success: true, data: { result: input.value } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const testContext = {
+                reqId: "params-test-123",
+                user: { id: "user-3", username: "paramstester" },
+                userPermissions: ["car:read", "car:write"],
+                timestamp: Date.now(),
+            };
+
+            await requestContext.run(testContext, async () => {
+                const result = await executor.execute({ value: "test" });
+                expect(result.success).toBe(true);
+            });
+
+            expect(capturedUser).toEqual(testContext.user);
+            expect(capturedPermissions).toEqual(["car:read", "car:write"]);
+        });
+
+        it("should support override parameters for testing", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test-tool-override",
+                description: "Test tool with overrides",
+                inputSchema: z.object({ value: z.string() }),
+            };
+
+            let capturedUser: any;
+            let capturedPermissions: string[] | undefined;
+
+            const toolFn: FlinkTool<any, any, any> = async ({ input, user, permissions }) => {
+                capturedUser = user;
+                capturedPermissions = permissions;
+                return { success: true, data: { result: input.value } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            // Execute with explicit overrides (no AsyncLocalStorage context)
+            const result = await executor.execute(
+                { value: "test" },
+                {
+                    user: { id: "override-user", username: "override" },
+                    permissions: ["override:permission"],
+                }
+            );
+
+            expect(result.success).toBe(true);
+            expect(capturedUser).toEqual({ id: "override-user", username: "override" });
+            expect(capturedPermissions).toEqual(["override:permission"]);
+        });
+    });
+
+    describe("Nested async operations", () => {
+        it("should maintain context across async boundaries", async () => {
+            const testContext = {
+                reqId: "nested-123",
+                user: { id: "user-3" },
+                timestamp: Date.now(),
+            };
+
+            await requestContext.run(testContext, async () => {
+                // Simulate async operation
+                await new Promise(resolve => setTimeout(resolve, 10));
+
+                expect(getReqId()).toBe("nested-123");
+
+                // Nested async operation
+                await (async () => {
+                    await new Promise(resolve => setTimeout(resolve, 10));
+                    expect(getReqId()).toBe("nested-123");
+                })();
+            });
+        });
+    });
+
+    describe("Permission helpers", () => {
+        it("should check permissions correctly", async () => {
+            const testContext = {
+                reqId: "perm-test",
+                userPermissions: ["car:read", "car:write"],
+                timestamp: Date.now(),
+            };
+
+            await requestContext.run(testContext, async () => {
+                expect(hasPermission("car:read")).toBe(true);
+                expect(hasPermission("car:delete")).toBe(false);
+                expect(hasAllPermissions(["car:read", "car:write"])).toBe(true);
+                expect(hasAllPermissions(["car:read", "car:delete"])).toBe(false);
+                expect(hasAnyPermission(["car:read", "car:delete"])).toBe(true);
+                expect(hasAnyPermission(["car:delete", "car:admin"])).toBe(false);
+            });
+        });
+
+        it("should return false for permissions when no context exists", () => {
+            expect(hasPermission("car:read")).toBe(false);
+            expect(hasAllPermissions(["car:read"])).toBe(false);
+            expect(hasAnyPermission(["car:read"])).toBe(false);
+        });
+    });
+
+    describe("Multiple concurrent contexts", () => {
+        it("should isolate contexts between concurrent requests", async () => {
+            const context1 = {
+                reqId: "req-1",
+                user: { id: "user-1" },
+                timestamp: Date.now(),
+            };
+
+            const context2 = {
+                reqId: "req-2",
+                user: { id: "user-2" },
+                timestamp: Date.now(),
+            };
+
+            // Run two contexts concurrently
+            const [result1, result2] = await Promise.all([
+                requestContext.run(context1, async () => {
+                    await new Promise(resolve => setTimeout(resolve, 5));
+                    return { reqId: getReqId(), userId: getRequestUser()?.id };
+                }),
+                requestContext.run(context2, async () => {
+                    await new Promise(resolve => setTimeout(resolve, 5));
+                    return { reqId: getReqId(), userId: getRequestUser()?.id };
+                }),
+            ]);
+
+            // Each context should maintain its own values
+            expect(result1.reqId).toBe("req-1");
+            expect(result1.userId).toBe("user-1");
+            expect(result2.reqId).toBe("req-2");
+            expect(result2.userId).toBe("user-2");
+        });
+    });
+
+});

package/spec/ConversationHooks.spec.ts

@@ -0,0 +1,257 @@
+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> {
+                id = "test-agent";
+                description = "Test agent";
+                instructions() { return "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");
+        });
+
+        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> {
+                id = "test-agent";
+                description = "Test agent";
+                instructions() { return "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> {
+                id = "test-agent";
+                description = "Test agent";
+                instructions() { return "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> {
+                id = "test-agent";
+                description = "Test agent";
+                instructions() { return "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);
+        });
+
+    });
+
+    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> {
+                id = "test-agent";
+                description = "Test agent";
+                instructions() { return "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",
+            });
+        });
+    });
+});