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

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@flink-app/flink",
-  "version": "0.14.3",
+  "version": "2.0.0-alpha.100",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./ai": {
+      "types": "./dist/src/ai/index.d.ts",
+      "default": "./dist/src/ai/index.js"
+    }
+  },
   "repository": "FrostDigital/flink",
   "bin": {
     "flink": "./dist/bin/flink.js"
@@ -18,17 +28,21 @@
     "@types/cors": "^2.8.10",
     "@types/express": "^4.17.13",
     "@types/fs-extra": "^9.0.12",
+    "@types/handlebars": "^4.1.0",
     "@types/ms": "^0.7.31",
     "@types/uuid": "^8.3.0",
     "ajv": "^8.2.0",
     "ajv-formats": "^2.1.0",
     "body-parser": "^1.19.0",
+    "chokidar": "^3.6.0",
     "cors": "^2.8.5",
     "croner": "^5.4.1",
     "express": "^4.17.1",
     "folder-hash": "^4.0.1",
     "fs-extra": "^10.0.0",
+    "handlebars": "^4.7.8",
     "json-schema": "^0.4.0",
+    "minimatch": "^10.0.1",
     "mkdirp": "^1.0.4",
     "mock-json-schema": "^1.0.8",
     "morgan": "^1.10.0",
@@ -39,22 +53,33 @@
     "reflect-metadata": "^0.1.13",
     "tiny-glob": "^0.2.9",
     "toad-scheduler": "^2.2.0",
-    "ts-json-schema-generator": "2.3.0",
     "ts-morph": "24.0.0",
-    "uuid": "^8.3.2"
+    "uuid": "^8.3.2",
+    "zod": "^4.3.6",
+    "@flink-app/ts-source-to-json-schema": "^0.1.7"
   },
   "devDependencies": {
+    "@swc/core": "^1.15.17",
     "@types/folder-hash": "^4.0.0",
     "@types/jasmine": "^3.7.1",
     "@types/json-schema": "^7.0.7",
     "@types/mkdirp": "^1.0.1",
     "@types/morgan": "^1.9.4",
     "@types/node": "22.13.10",
+    "@types/supertest": "^6.0.3",
     "mongodb": "^6.15.0",
+    "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
   "peerDependencies": {
-    "mongodb": ">=3.7.0 <7.0.0"
+    "mongodb": ">=3.7.0 <7.0.0",
+    "zod": ">=3.25.0 <5.0.0",
+    "@swc/core": ">=1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@swc/core": {
+      "optional": true
+    }
   },
   "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
   "scripts": {

package/readme.md

@@ -218,6 +218,505 @@ 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.
+
+#### Persistent Conversations
+
+For multi-turn conversations, extend `ConversationAgent` to automatically handle conversation history and provider metadata persistence:
+
+```typescript
+// src/agents/ChatAgent.ts
+import { ConversationAgent, ConversationData } from "@flink-app/flink";
+import AppCtx from "../AppCtx";
+
+export default class ChatAgent extends ConversationAgent<AppCtx> {
+    id = "chat-agent";
+    description = "Chat assistant with conversation memory";
+    instructions = "You are a helpful assistant...";
+    tools = ["search-knowledge"];
+
+    protected async loadConversation(conversationId: string) {
+        const conv = await this.ctx.repos.conversationRepo.getById(conversationId);
+        return conv ? {
+            messages: conv.messages,
+            providerMetadata: conv.providerMetadata
+        } : null;
+    }
+
+    protected async saveConversation(conversationId: string, data: ConversationData) {
+        await this.ctx.repos.conversationRepo.upsert({
+            _id: conversationId,
+            agentId: this.id,
+            messages: data.messages,
+            providerMetadata: data.providerMetadata,
+            updatedAt: new Date()
+        });
+    }
+}
+```
+
+**Benefits:**
+- Automatic message history loading/saving
+- Provider metadata persistence (e.g., OpenAI's `previousResponseId` for 40-80% cost savings)
+- Sub-agent aware (parent handles persistence, not children)
+- Storage backend flexibility (MongoDB, Redis, in-memory)
+
+##### Controlling Persistence Strategy
+
+By default, ConversationAgent uses "auto" mode which automatically leverages provider optimizations (like OpenAI's previousResponseId) for 40-80% cost savings. You can control this behavior at the agent level or per-execution:
+
+**Agent-level default:**
+```typescript
+export default class ChatAgent extends ConversationAgent<AppCtx> {
+    protected persistenceStrategy = "full-history"; // Always send full history
+    // ... other configuration
+}
+```
+
+**Per-execution override:**
+```typescript
+await agent.execute({
+    message: "Hello",
+    conversationId: "conv-123",
+    options: { persistenceStrategy: "full-history" } // Debug mode
+});
+```
+
+**Strategy options:**
+- `"auto"` (default): Use provider optimization when available
+- `"provider-optimized"`: Explicitly prefer optimization
+- `"full-history"`: Always send full history (debugging, compliance)
+
+**When to use "full-history":**
+- Debugging caching issues
+- Compliance requirements (audit trail of all messages)
+- Testing with predictable behavior
+
+See the [demo-app examples](../demo-app/src/agents) for MongoDB, Redis, and in-memory storage implementations.
+
+#### 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