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

package/readme.md

@@ -218,6 +218,431 @@ export const Props: RouteProps {
 }
 ```
 
+### AI Agents
+
+Flink includes a comprehensive AI agents and tools framework for building LLM-powered applications with multi-agent orchestration, streaming responses, and type-safe tool execution.
+
+Agents are placed in `src/agents/` folder and extend the `FlinkAgent` base class. They are automatically registered and available via the context.
+
+#### Creating an Agent
+
+Agents extend `FlinkAgent<Ctx>` and define their configuration as class properties:
+
+```typescript
+// src/agents/CarAgent.ts
+import { FlinkAgent } from "@flink-app/flink";
+import AppCtx from "../AppCtx";
+import GetCarsTool from "../tools/GetCarsTool";
+
+export default class CarAgent extends FlinkAgent<AppCtx> {
+    id = "car-agent"; // Optional: defaults to "car-agent" (kebab-case class name)
+    description = "Expert in car models and specifications";
+    instructions = "You are a knowledgeable car expert...";
+    tools = [GetCarsTool]; // Tool class references
+
+    model = {
+        adapterId: "default", // References registered LLM adapter
+        maxTokens: 2000,
+        temperature: 0.7,
+    };
+
+    limits = {
+        maxSteps: 10, // Maximum execution steps
+        maxSubAgentDepth: 5, // Prevents infinite recursion (default: 5)
+    };
+
+    // Define domain-specific methods for better type safety
+    async searchByBrand(brand: string) {
+        const response = this.execute({
+            message: `Find all ${brand} cars`
+        });
+        return await response.result;
+    }
+}
+```
+
+#### Creating Tools
+
+Tools define actions that agents can perform. They use Zod for type-safe input/output validation:
+
+```typescript
+// src/tools/GetCarsTool.ts
+import { FlinkTool, FlinkToolProps, ToolResult } from "@flink-app/flink";
+import { z } from "zod";
+import AppCtx from "../AppCtx";
+
+export const Tool: FlinkToolProps = {
+    id: "get-cars-tool",
+    description: "Search for cars in inventory",
+    inputSchema: z.object({
+        brand: z.string().optional(),
+        maxPrice: z.number().optional(),
+    }),
+};
+
+const GetCarsTool: FlinkTool<AppCtx, z.infer<typeof Tool.inputSchema>> = async ({
+    input,
+    ctx
+}) => {
+    const cars = await ctx.repos.carRepo.findAll({
+        brand: input.brand,
+        price: { $lte: input.maxPrice }
+    });
+
+    return { success: true, data: cars };
+};
+
+export default GetCarsTool;
+```
+
+#### Multi-Agent Orchestration
+
+Agents can delegate to specialized sub-agents using class references:
+
+```typescript
+// src/agents/OrchestratorAgent.ts
+import { FlinkAgent } from "@flink-app/flink";
+import AppCtx from "../AppCtx";
+import CarAgent from "./CarAgent";
+import PricingAgent from "./PricingAgent";
+
+export default class OrchestratorAgent extends FlinkAgent<AppCtx> {
+    description = "Coordinates between specialized agents";
+    instructions = "Route queries to appropriate specialists...";
+    tools = []; // No direct tools, only sub-agents
+    agents = [CarAgent, PricingAgent]; // Type-safe class references!
+
+    limits = {
+        maxSubAgentDepth: 3, // Prevent infinite delegation loops
+    };
+}
+```
+
+**Recursion Protection**: The `maxSubAgentDepth` limit (default: 5) prevents infinite loops when agents delegate to each other. If Agent A calls Agent B, which calls Agent A again, the framework will throw an error when the depth limit is exceeded, preventing stack overflow and infinite execution.
+
+#### Using Agents in Handlers
+
+Access agents through the context and optionally bind a user for permissions:
+
+```typescript
+// src/handlers/car/PostCarQuery.ts
+import { Handler } from "@flink-app/flink";
+import AppCtx from "../../AppCtx";
+
+const PostCarQuery: Handler<AppCtx, { question: string }, { answer: string }> = async ({
+    ctx,
+    req
+}) => {
+    const result = await ctx.agents.carAgent
+        .withUser(req.user)
+        .searchByBrand(req.body.question);
+
+    return { data: { answer: result.message } };
+};
+
+export default PostCarQuery;
+```
+
+#### Streaming Responses
+
+Agents support real-time streaming for better UX:
+
+```typescript
+// src/handlers/car/PostCarQueryStream.ts
+import { Handler } from "@flink-app/flink";
+import AppCtx from "../../AppCtx";
+
+const PostCarQueryStream: Handler<AppCtx, { question: string }> = async ({
+    ctx,
+    req,
+    res
+}) => {
+    const response = ctx.agents.carAgent.execute({
+        message: req.body.question
+    });
+
+    res.setHeader("Content-Type", "text/event-stream");
+
+    for await (const text of response.textStream) {
+        res.write(`data: ${text}\n\n`);
+    }
+
+    res.end();
+};
+
+export default PostCarQueryStream;
+```
+
+#### AI Permissions
+
+Flink provides a flexible permission system for agents and tools that integrates with authentication plugins. Starting in v0.15.0, auth plugins populate `req.userPermissions` with resolved permissions based on roles, dynamic roles, or custom logic.
+
+**Three Permission Patterns:**
+
+1. **String-based**: Single required permission
+2. **Array-based**: Multiple required permissions (ALL required, AND logic)
+3. **Function-based**: Custom permission logic with async support
+
+**Agent Permissions Example:**
+
+```typescript
+export default class CarAgent extends FlinkAgent<AppCtx> {
+    description = "Expert in car models";
+    instructions = "You are a car expert...";
+    tools = ["get-cars-tool", "create-car-tool"];
+    permissions = "car:access"; // Single permission required
+}
+```
+
+**Tool Permissions Example:**
+
+```typescript
+// String-based: Simple permission check
+export const Tool: FlinkToolProps = {
+    id: "create-car",
+    description: "Create a new car",
+    permissions: "car:create", // User must have this permission
+    inputSchema: z.object({
+        brand: z.string(),
+        model: z.string(),
+    }),
+};
+
+// Array-based: Multiple permissions required (AND logic)
+export const Tool: FlinkToolProps = {
+    id: "premium-report",
+    description: "Generate premium analytics",
+    permissions: ["car:read", "premium-features"], // ALL required
+    inputSchema: z.object({
+        carId: z.string(),
+    }),
+};
+
+// Function-based: Custom logic (async supported)
+export const Tool: FlinkToolProps = {
+    id: "delete-car",
+    description: "Delete a car (admin or owner only)",
+    permissions: async (input, user) => {
+        // Admin can delete any car
+        if (user?.permissions?.includes("admin")) return true;
+
+        // Owner can delete their own car
+        const car = await carRepo.getById(input.carId);
+        return car.ownerId === user?.id;
+    },
+    inputSchema: z.object({
+        carId: z.string(),
+    }),
+};
+```
+
+**Using Permissions in Handlers:**
+
+Auth plugins (like JWT Auth Plugin) populate `req.userPermissions` during authentication. Pass this to agents for automatic permission checks:
+
+```typescript
+const handler: Handler<AppCtx, RequestBody, ResponseBody> = async ({ req, ctx }) => {
+    const agent = ctx.agents.carAgent
+        .withUser(req.user)
+        .withPermissions(req.userPermissions); // Pass resolved permissions
+
+    return await agent.execute({ message: req.body.message });
+};
+```
+
+**How `userPermissions` Works:**
+
+Auth plugins automatically populate `req.userPermissions` based on their configuration:
+
+```typescript
+// Strategy 1: Direct permissions from user object
+jwtAuthPlugin({
+    secret: process.env.JWT_SECRET,
+    getUser: async (tokenData) => {
+        const user = await userRepo.getById(tokenData.userId);
+        return {
+            id: user.id,
+            permissions: user.permissions, // Direct permissions array
+        };
+    },
+    rolePermissions: {},
+});
+// Result: req.userPermissions = user.permissions
+
+// Strategy 2: Static role mapping
+jwtAuthPlugin({
+    secret: process.env.JWT_SECRET,
+    getUser: async (tokenData) => {
+        return { id: tokenData.userId };
+    },
+    rolePermissions: {
+        admin: ["car:read", "car:create", "car:delete"],
+        user: ["car:read"],
+        premium: ["car:read", "car:create", "premium-features"],
+    },
+});
+// JWT token has roles: ["user", "premium"]
+// Result: req.userPermissions = ["car:read", "car:create", "premium-features"]
+
+// Strategy 3: Dynamic roles (multi-tenant)
+jwtAuthPlugin({
+    secret: process.env.JWT_SECRET,
+    useDynamicRoles: true, // Enable dynamic role resolution
+    getUser: async (tokenData, req) => {
+        const orgId = req.headers['x-organization-id'];
+        const membership = await orgMembershipRepo.getByUserAndOrg(
+            tokenData.userId,
+            orgId
+        );
+        return {
+            id: tokenData.userId,
+            roles: [membership.role], // Org-specific role
+        };
+    },
+    rolePermissions: {
+        admin: ["car:read", "car:create", "car:delete"],
+        user: ["car:read"],
+    },
+});
+// Same user, different orgs → different permissions
+// Org A: admin role → ["car:read", "car:create", "car:delete"]
+// Org B: user role → ["car:read"]
+```
+
+**Permission Benefits:**
+
+- ✅ **Performance**: Permissions computed once per request (not per tool use)
+- ✅ **Tool Filtering**: LLM only sees tools user has access to (prevents hallucination)
+- ✅ **Consistent**: Same permission logic across handlers, agents, and tools
+- ✅ **Flexible**: String/array for simple cases, function for complex logic
+- ✅ **Multi-tenant**: Dynamic roles support org-specific permissions
+
+**Backward Compatibility:**
+
+The system is fully backward compatible:
+- If `req.userPermissions` is not set → falls back to `user.permissions`
+- Function-based permissions continue to work as before
+- No breaking changes to existing apps
+
+#### Registering LLM Adapters
+
+LLM adapters are configured in `FlinkOptions.ai.llms`:
+
+```typescript
+// src/index.ts
+import Anthropic from "@anthropic-ai/sdk";
+import { FlinkApp } from "@flink-app/flink";
+import { AnthropicAdapter } from "@flink-app/anthropic-adapter";
+import AppCtx from "./AppCtx";
+
+const app = new FlinkApp<AppCtx>({
+    name: "My App",
+    ai: {
+        llms: {
+            default: new AnthropicAdapter(
+                new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+                "claude-3-5-sonnet-20241022"
+            ),
+            fast: new AnthropicAdapter(
+                new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+                "claude-3-haiku-20240307"
+            ),
+        },
+    },
+});
+
+app.start();
+```
+
+#### Custom LLM Adapters
+
+Create custom adapters by implementing the `LLMAdapter` interface:
+
+```typescript
+import { LLMAdapter, LLMStreamChunk } from "@flink-app/flink";
+
+/**
+ * Custom LLM adapter implementation
+ *
+ * Note: LLM adapters are streaming-only. Flink's AgentRunner only calls stream().
+ * The streaming approach provides better UX (time-to-first-token <500ms) and
+ * FlinkAgent's lazy generator supports both streaming and non-streaming consumption.
+ */
+export class CustomAdapter implements LLMAdapter {
+    constructor(private client: any, private model: string) {}
+
+    async *stream(params: {
+        instructions: string;
+        messages: any[];
+        tools: any[];
+        maxTokens: number;
+        temperature: number;
+    }): AsyncGenerator<LLMStreamChunk> {
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            messages: [
+                { role: "system", content: params.instructions },
+                ...params.messages
+            ],
+            tools: params.tools,
+            max_tokens: params.maxTokens,
+            temperature: params.temperature,
+            stream: true,
+        });
+
+        let inputTokens = 0;
+        let outputTokens = 0;
+
+        for await (const chunk of stream) {
+            const delta = chunk.choices[0]?.delta;
+
+            // Stream text deltas
+            if (delta?.content) {
+                yield { type: "text", delta: delta.content };
+            }
+
+            // Stream tool calls
+            if (delta?.tool_calls) {
+                for (const toolCall of delta.tool_calls) {
+                    yield {
+                        type: "tool_call",
+                        toolCall: {
+                            id: toolCall.id,
+                            name: toolCall.function.name,
+                            input: JSON.parse(toolCall.function.arguments),
+                        },
+                    };
+                }
+            }
+
+            // Track usage
+            if (chunk.usage) {
+                inputTokens = chunk.usage.prompt_tokens;
+                outputTokens = chunk.usage.completion_tokens;
+            }
+        }
+
+        // Emit usage
+        yield {
+            type: "usage",
+            usage: { inputTokens, outputTokens },
+        };
+
+        // Emit done
+        yield {
+            type: "done",
+            stopReason: "end_turn",
+        };
+    }
+}
+```
+
+#### Available Packages
+
+- `@flink-app/flink` - Core framework with AI agents & tools
+- `@flink-app/anthropic-adapter` - Official Anthropic Claude adapter
+- `@flink-app/fake-llm-adapter` - Deterministic testing adapter
+
 ## 🤕 Known issues
 
 -   Current TypeScript compiler is slow when project gets larger

package/spec/AgentDuplicateDetection.spec.ts

@@ -0,0 +1,112 @@
+import { toKebabCase } from "../src/utils";
+
+describe("Agent Duplicate Detection Logic", () => {
+    describe("Instance name collisions (camelCase)", () => {
+        // Instance names are derived by lowercasing first character
+        const getInstanceName = (className: string) => {
+            return className.charAt(0).toLowerCase() + className.substring(1);
+        };
+
+        it("should show CarAgent vs Caragent do NOT collide (different casing)", () => {
+            const instance1 = getInstanceName("CarAgent");
+            const instance2 = getInstanceName("Caragent");
+
+            // CarAgent → carAgent, Caragent → caragent (no collision)
+            expect(instance1).toBe("carAgent");
+            expect(instance2).toBe("caragent");
+            expect(instance1).not.toBe(instance2);
+        });
+
+        it("should detect collision example: CarAgent vs CARAgent", () => {
+            // This is a contrived example, but shows the logic
+            const instance1 = getInstanceName("CarAgent");
+            const instance2 = getInstanceName("CarAgent"); // Exact same name
+
+            // Both become "carAgent" - COLLISION!
+            expect(instance1).toBe("carAgent");
+            expect(instance2).toBe("carAgent");
+            expect(instance1).toBe(instance2);
+        });
+
+        it("should not collide for different class names", () => {
+            const instance1 = getInstanceName("CarAgent");
+            const instance2 = getInstanceName("BikeAgent");
+
+            expect(instance1).toBe("carAgent");
+            expect(instance2).toBe("bikeAgent");
+            expect(instance1).not.toBe(instance2);
+        });
+    });
+
+    describe("Agent ID collisions (kebab-case)", () => {
+        it("should detect APIAgent vs ApiAgent collision", () => {
+            const id1 = toKebabCase("APIAgent");
+            const id2 = toKebabCase("ApiAgent");
+
+            // Both become "api-agent" - COLLISION!
+            expect(id1).toBe("api-agent");
+            expect(id2).toBe("api-agent");
+            expect(id1).toBe(id2);
+        });
+
+        it("should detect HTMLParser vs HtmlParser collision", () => {
+            const id1 = toKebabCase("HTMLParser");
+            const id2 = toKebabCase("HtmlParser");
+
+            // Both become "html-parser" - COLLISION!
+            expect(id1).toBe("html-parser");
+            expect(id2).toBe("html-parser");
+            expect(id1).toBe(id2);
+        });
+
+        it("should detect XMLHttpRequest vs XmlHttpRequest collision", () => {
+            const id1 = toKebabCase("XMLHttpRequest");
+            const id2 = toKebabCase("XmlHttpRequest");
+
+            // Both become "xml-http-request" - COLLISION!
+            expect(id1).toBe("xml-http-request");
+            expect(id2).toBe("xml-http-request");
+            expect(id1).toBe(id2);
+        });
+
+        it("should not collide for different agent names", () => {
+            const id1 = toKebabCase("CarAgent");
+            const id2 = toKebabCase("BikeAgent");
+
+            expect(id1).toBe("car-agent");
+            expect(id2).toBe("bike-agent");
+            expect(id1).not.toBe(id2);
+        });
+
+        it("should not collide for similar but distinct names", () => {
+            const id1 = toKebabCase("CarAgent");
+            const id2 = toKebabCase("CarPricingAgent");
+
+            expect(id1).toBe("car-agent");
+            expect(id2).toBe("car-pricing-agent");
+            expect(id1).not.toBe(id2);
+        });
+    });
+
+    describe("Real-world collision scenarios", () => {
+        it("should show that explicit IDs prevent collisions", () => {
+            // Even if class names would collide, explicit IDs prevent issues
+            const explicitId1 = "api-agent-v1";
+            const explicitId2 = "api-agent-v2";
+
+            expect(explicitId1).not.toBe(explicitId2);
+        });
+
+        it("should demonstrate the collision resolution path", () => {
+            // Problem: Both APIAgent and ApiAgent → "api-agent"
+            const problematicId1 = toKebabCase("APIAgent");
+            const problematicId2 = toKebabCase("ApiAgent");
+            expect(problematicId1).toBe(problematicId2); // Collision!
+
+            // Solution: Use explicit IDs
+            const resolvedId1 = "api-agent-v1";
+            const resolvedId2 = "api-agent-v2";
+            expect(resolvedId1).not.toBe(resolvedId2); // No collision
+        });
+    });
+});