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

package/src/FlinkApp.ts

@@ -9,6 +9,10 @@ import morgan from "morgan";
 import ms from "ms";
 import { AsyncTask, CronJob, SimpleIntervalJob, ToadScheduler } from "toad-scheduler";
 import { v4 } from "uuid";
+import { FlinkAgentFile } from "./ai/FlinkAgent";
+import { FlinkToolFile } from "./ai/FlinkTool";
+import { LLMAdapter } from "./ai/LLMAdapter";
+import { ToolExecutor } from "./ai/ToolExecutor";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
 import { FlinkError, internalServerError, notFound, unauthorized } from "./FlinkErrors";
@@ -18,6 +22,7 @@ import { log } from "./FlinkLog";
 import { FlinkPlugin } from "./FlinkPlugin";
 import { FlinkRepo } from "./FlinkRepo";
 import { FlinkResponse } from "./FlinkResponse";
+import { StreamWriterFactory } from "./handlers/StreamWriterFactory";
 import generateMockData from "./mock-data-generator";
 import { formatValidationErrors, getPathParams, isError } from "./utils";
 
@@ -63,6 +68,18 @@ export const autoRegisteredRepos: {
  */
 export const autoRegisteredJobs: FlinkJobFile[] = [];
 
+/**
+ * This will be populated at compile time when the apps tools
+ * are picked up by TypeScript compiler
+ */
+export const autoRegisteredTools: FlinkToolFile[] = [];
+
+/**
+ * This will be populated at compile time when the apps agents
+ * are picked up by TypeScript compiler
+ */
+export const autoRegisteredAgents: FlinkAgentFile[] = [];
+
 export interface FlinkOptions {
     /**
      * Name of application, will only show in logs and in HTTP header.
@@ -175,6 +192,15 @@ export interface FlinkOptions {
         //     autoAssignCollection?: string;
     };
 
+    /**
+     * AI configuration for agents and tools
+     * Register LLM adapters with custom IDs (e.g., "anthropic", "openai", "anthropic-eu", etc.)
+     * This allows multiple adapters of the same type with different configurations
+     */
+    ai?: {
+        llms?: { [id: string]: LLMAdapter };
+    };
+
     /**
      * If true, the HTTP server will be disabled.
      * Only useful when starting a Flink app for testing purposes.
@@ -294,6 +320,10 @@ export class FlinkApp<C extends FlinkContext> {
 
     private repos: { [x: string]: FlinkRepo<C, any> } = {};
 
+    private llmAdapters: Map<string, LLMAdapter> = new Map();
+    private tools: { [x: string]: ToolExecutor<C> } = {};
+    private agents: { [x: string]: any } = {}; // FlinkAgent<C> instances
+
     /**
      * Internal cache used to track registered handlers and potentially any overlapping routes
      */
@@ -314,14 +344,20 @@ export class FlinkApp<C extends FlinkContext> {
         this.rawContentTypes = Array.isArray(opts.rawContentTypes)
             ? opts.rawContentTypes
             : typeof opts.rawContentTypes === "string"
-            ? [opts.rawContentTypes]
-            : undefined;
+              ? [opts.rawContentTypes]
+              : undefined;
         this.auth = opts.auth;
         this.jsonOptions = opts.jsonOptions || { limit: "1mb" };
         this.schedulingOptions = opts.scheduling;
         this.disableHttpServer = !!opts.disableHttpServer;
         this.accessLog = { enabled: true, format: "dev", ...opts.accessLog };
         this.onError = opts.onError;
+
+        // Register LLM adapters if configured
+        if (opts.ai?.llms) {
+            // Convert plain object to Map for internal use
+            this.llmAdapters = new Map(Object.entries(opts.ai.llms));
+        }
     }
 
     get ctx() {
@@ -342,6 +378,7 @@ export class FlinkApp<C extends FlinkContext> {
             log.bgColorLog("cyan", `Init db took ${offsetTime - startTime} ms`);
         }
 
+        // Build initial context (without agents - they'll be added later)
         await this.buildContext();
 
         if (this.debug) {
@@ -349,6 +386,30 @@ export class FlinkApp<C extends FlinkContext> {
             offsetTime = Date.now();
         }
 
+        // Register tools (needs context for ToolExecutor)
+        await this.registerAutoRegisterableTools();
+
+        if (this.debug) {
+            log.bgColorLog("cyan", `Register tools took ${Date.now() - offsetTime} ms`);
+            offsetTime = Date.now();
+        }
+
+        // Register agents (creates agent instances)
+        await this.registerAutoRegisterableAgents();
+
+        if (this.debug) {
+            log.bgColorLog("cyan", `Register agents took ${Date.now() - offsetTime} ms`);
+            offsetTime = Date.now();
+        }
+
+        // Initialize agents now that context and tools are ready
+        await this.initializeAgents();
+
+        if (this.debug) {
+            log.bgColorLog("cyan", `Initialize agents took ${Date.now() - offsetTime} ms`);
+            offsetTime = Date.now();
+        }
+
         if (this.isSchedulingEnabled) {
             this.scheduler = new ToadScheduler();
         } else {
@@ -519,7 +580,7 @@ export class FlinkApp<C extends FlinkContext> {
         this.handlers.push(handlerConfig);
 
         const { routeProps, schema = {} } = handlerConfig;
-        const { method } = routeProps;
+        const { method, streamFormat } = routeProps;
 
         if (!method) {
             log.error(`Route ${routeProps.path} is missing http method`);
@@ -543,8 +604,8 @@ export class FlinkApp<C extends FlinkContext> {
                 validateReq = ajv.compile(schema.reqSchema);
             }
 
-            // Compile response schema if validation mode requires it
-            if (schema.resSchema && validationMode !== ValidationMode.SkipValidation && validationMode !== ValidationMode.ValidateRequest) {
+            // Skip response validation for streaming handlers (responses are stream chunks, not final JSON)
+            if (!streamFormat && schema.resSchema && validationMode !== ValidationMode.SkipValidation && validationMode !== ValidationMode.ValidateRequest) {
                 validateRes = ajv.compile(schema.resSchema);
             }
 
@@ -573,7 +634,8 @@ export class FlinkApp<C extends FlinkContext> {
                     }
                 }
 
-                if (routeProps.mockApi && schema.resSchema) {
+                // Skip mock API for streaming handlers
+                if (routeProps.mockApi && schema.resSchema && !streamFormat) {
                     log.warn(`Mock response for ${req.method.toUpperCase()} ${req.path}`);
 
                     const data = generateMockData(schema.resSchema);
@@ -603,6 +665,9 @@ export class FlinkApp<C extends FlinkContext> {
                     req.query = normalizedQuery;
                 }
 
+                // Create stream writer if streaming handler
+                const stream = streamFormat ? StreamWriterFactory.create(res, streamFormat) : undefined;
+
                 let handlerRes: FlinkResponse<any>;
 
                 try {
@@ -611,8 +676,19 @@ export class FlinkApp<C extends FlinkContext> {
                         req: req as FlinkRequest,
                         ctx: this.ctx,
                         origin: routeProps.origin,
+                        stream,
                     });
                 } catch (err: any) {
+                    // Handle errors for streaming handlers
+                    if (streamFormat && stream) {
+                        log.error(`Streaming handler error on ${req.method.toUpperCase()} ${req.path}: ${err.message}`, {
+                            error: err,
+                            path: req.path,
+                            method: req.method,
+                        });
+                        stream.error(err);
+                        return;
+                    }
                     let errorResponse: FlinkResponse<FlinkError>;
 
                     // duck typing to check if it is a FlinkError
@@ -656,6 +732,16 @@ export class FlinkApp<C extends FlinkContext> {
                     return res.status(errorResponse.status || 500).json(errorResponse);
                 }
 
+                // Skip response handling for streaming handlers (stream controls response lifecycle)
+                if (streamFormat) {
+                    return;
+                }
+
+                // Ensure handlerRes is defined for non-streaming handlers
+                if (!handlerRes) {
+                    return res.status(204).send();
+                }
+
                 if (validateRes && !isError(handlerRes)) {
                     const valid = validateRes(JSON.parse(JSON.stringify(handlerRes.data)));
 
@@ -684,7 +770,7 @@ export class FlinkApp<C extends FlinkContext> {
                 return process.exit(1); // TODO: Do we need to exit?
             } else {
                 this.handlerRouteCache.set(methodAndRoute, JSON.stringify(routeProps));
-                log.info(`Registered route ${methodAndRoute}`);
+                log.info(`Registered ${streamFormat ? 'streaming ' : ''}route ${methodAndRoute}${streamFormat ? ` (${streamFormat})` : ''}`);
             }
         }
     }
@@ -836,6 +922,151 @@ export class FlinkApp<C extends FlinkContext> {
         // repoInstance.ctx = this.ctx;
     }
 
+    private async registerAutoRegisterableTools() {
+        const { ToolExecutor } = require("./ai/ToolExecutor");
+        const { getRepoInstanceName } = require("./utils");
+
+        for (const toolFile of autoRegisteredTools) {
+            if (!toolFile.Tool) {
+                log.error(`Missing FlinkToolProps export in tool ${toolFile.__file}`);
+                continue;
+            }
+
+            if (!toolFile.default) {
+                log.error(`Missing exported tool function in tool ${toolFile.__file}`);
+                continue;
+            }
+
+            const toolId = toolFile.Tool.id;
+            if (!toolId) {
+                log.error(`Tool ${toolFile.__file} missing 'id' property`);
+                continue;
+            }
+
+            const toolInstanceName = getRepoInstanceName(toolId);
+
+            const toolExecutor = new ToolExecutor(toolFile.Tool, toolFile.default, this.ctx);
+            this.tools[toolInstanceName] = toolExecutor;
+
+            log.info(`Registered tool ${toolInstanceName} (${toolId})`);
+        }
+    }
+
+    private async registerAutoRegisterableAgents() {
+        const { getRepoInstanceName, toKebabCase } = require("./utils");
+        const { SubAgentExecutor } = require("./ai/SubAgentExecutor");
+
+        for (const agentFile of autoRegisteredAgents) {
+            // agentFile now exports a class, not a config object
+            const AgentClass = agentFile.default;
+
+            if (!AgentClass) {
+                log.error(`Missing default export in agent ${agentFile.__file}`);
+                continue;
+            }
+
+            // Instantiate agent (similar to repo instantiation)
+            const agentInstance = new AgentClass();
+
+            // Derive instance name from class name (camelCase)
+            const agentInstanceName = getRepoInstanceName(AgentClass.name);
+
+            // Get agent ID (kebab-case) - either explicit or derived
+            const agentId = agentInstance.id || toKebabCase(AgentClass.name);
+
+            // Check for duplicate instance name
+            if (this.agents[agentInstanceName]) {
+                const existingAgent = this.agents[agentInstanceName];
+                throw new Error(
+                    `Duplicate agent instance name: "${agentInstanceName}". ` +
+                    `Agent class "${AgentClass.name}" conflicts with existing agent "${existingAgent.constructor.name}". ` +
+                    `Instance names are derived by lowercasing the first letter of the class name. ` +
+                    `Rename one of the classes or use a unique explicit 'id' property.`
+                );
+            }
+
+            // Check for duplicate agent ID
+            const existingAgentWithSameId = Object.values(this.agents).find(
+                (agent: any) => {
+                    const existingId = agent.id || toKebabCase(agent.constructor.name);
+                    return existingId === agentId;
+                }
+            );
+
+            if (existingAgentWithSameId) {
+                throw new Error(
+                    `Duplicate agent ID: "${agentId}". ` +
+                    `Agent class "${AgentClass.name}" conflicts with existing agent "${existingAgentWithSameId.constructor.name}". ` +
+                    `Agent IDs are derived from class names using kebab-case (e.g., CarAgent → car-agent). ` +
+                    `Use an explicit 'id' property to resolve this conflict:\n` +
+                    `  id = "my-unique-id";`
+                );
+            }
+
+            // Validate tools exist
+            for (const toolRef of agentInstance.tools) {
+                // Handle both string IDs and tool file references
+                const toolId = typeof toolRef === "string"
+                    ? toolRef
+                    : toolRef.Tool.id; // Extract ID from FlinkToolFile
+
+                const tool = this.tools[toolId];
+
+                if (!tool) {
+                    log.error(`Agent ${AgentClass.name} references tool ${toolId} which is not registered`);
+                    throw new Error(`Invalid tool reference in agent ${AgentClass.name}`);
+                }
+            }
+
+            // Validate and register sub-agents
+            if (agentInstance.agents && agentInstance.agents.length > 0) {
+                for (const agentRef of agentInstance.agents) {
+                    // Get instance name directly from class reference or string
+                    const subAgentInstanceName = typeof agentRef === "string" ? agentRef : getRepoInstanceName(agentRef.name);
+
+                    // Validate that sub-agent will exist (will be registered in this loop)
+                    // For now, just log - actual validation happens at runtime
+                    log.debug(`Agent ${AgentClass.name} references sub-agent ${subAgentInstanceName}`);
+
+                    // Create a SubAgentExecutor as a special tool
+                    const subAgentToolName = `ask_${subAgentInstanceName}`;
+                    const subAgentExecutor = new SubAgentExecutor(subAgentInstanceName, this.ctx);
+
+                    // Register as a tool so it appears in the agent's tool list
+                    this.tools[subAgentToolName] = subAgentExecutor as any;
+                    log.debug(`Created sub-agent tool ${subAgentToolName} for ${subAgentInstanceName}`);
+                }
+            }
+
+            // Register agent (duplicate checks already performed above)
+            this.agents[agentInstanceName] = agentInstance;
+            log.info(`Registered agent ${agentInstanceName} (${AgentClass.name}) with ID: ${agentId}`);
+        }
+
+        // Second pass: validate all sub-agent references
+        for (const agentFile of autoRegisteredAgents) {
+            const AgentClass = agentFile.default;
+
+            if (!AgentClass) {
+                continue;
+            }
+
+            const agentInstance = new AgentClass();
+
+            if (agentInstance.agents && agentInstance.agents.length > 0) {
+                for (const agentRef of agentInstance.agents) {
+                    // Get instance name directly from class reference or string
+                    const subAgentInstanceName = typeof agentRef === "string" ? agentRef : getRepoInstanceName(agentRef.name);
+
+                    if (!this.agents[subAgentInstanceName]) {
+                        log.error(`Agent ${AgentClass.name} references sub-agent ${subAgentInstanceName} which is not registered`);
+                        throw new Error(`Invalid sub-agent reference in agent ${AgentClass.name}: ${subAgentInstanceName}`);
+                    }
+                }
+            }
+        }
+    }
+
     /**
      * Constructs the app context. Will inject context in all components
      * except for handlers which are handled in later stage.
@@ -865,6 +1096,7 @@ export class FlinkApp<C extends FlinkContext> {
             repos: this.repos,
             plugins: pluginCtx,
             auth: this.auth,
+            agents: this.agents,
         } as C;
 
         for (const repo of Object.values(this.repos)) {
@@ -872,6 +1104,18 @@ export class FlinkApp<C extends FlinkContext> {
         }
     }
 
+    /**
+     * Initialize agents after they've been registered and context is ready
+     * Must be called after registerAutoRegisterableAgents()
+     */
+    private async initializeAgents() {
+        // Inject context and initialize agents
+        for (const agent of Object.values(this.agents)) {
+            agent.ctx = this.ctx;
+            agent.__init(this.llmAdapters, this.tools);
+        }
+    }
+
     /**
      * Connects to database.
      */

package/src/FlinkContext.ts

@@ -1,5 +1,6 @@
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkRepo } from "./FlinkRepo";
+import { FlinkAgent } from "./ai/FlinkAgent";
 
 export interface FlinkContext<P = any> {
     repos: {
@@ -12,4 +13,25 @@ export interface FlinkContext<P = any> {
      * Type of authentication, if any.
      */
     auth?: FlinkAuthPlugin;
+
+    /**
+     * AI namespace containing agents
+     *
+     * Define agents directly in your context interface:
+     *
+     * @example
+     * interface AppCtx extends FlinkContext<PluginCtx> {
+     *     auth: JwtAuthPlugin;
+     *     repos: {
+     *         carRepo: CarRepo;
+     *     };
+     *     agents: {
+     *         carAgent: CarAgent;
+     *         userAgent: UserAgent;
+     *     };
+     * }
+     */
+    agents?: {
+        [x: string]: FlinkAgent<any>;
+    };
 }

package/src/FlinkHttpHandler.ts

@@ -62,9 +62,54 @@ type Params = Record<string, string>;
 type Query = Record<string, string | string[]>;
 
 /**
- * Flink request extends express Request but adds reqId and user object.
+ * Stream format for streaming handlers.
+ * - sse: Server-Sent Events (text/event-stream)
+ * - ndjson: Newline-Delimited JSON (application/x-ndjson)
  */
-export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & { reqId: string; user?: any };
+export type StreamFormat = "sse" | "ndjson";
+
+/**
+ * Stream writer interface for SSE/NDJSON streaming.
+ *
+ * Provides methods to write data chunks, handle errors, and manage the stream lifecycle.
+ * Only available in handlers where streamFormat is specified in RouteProps.
+ */
+export interface StreamWriter<T = any> {
+    /**
+     * Write data to the stream.
+     * Data is automatically JSON-stringified and formatted according to streamFormat.
+     */
+    write(data: T): void;
+
+    /**
+     * Send error to client and close the stream.
+     */
+    error(error: Error | string): void;
+
+    /**
+     * Close the stream gracefully.
+     */
+    end(): void;
+
+    /**
+     * Check if stream is still open (client connected).
+     * Returns false if client has disconnected.
+     */
+    isOpen(): boolean;
+}
+
+/**
+ * Flink request extends express Request but adds reqId, user object, and userPermissions.
+ *
+ * userPermissions is populated by auth plugins during authentication and contains
+ * the resolved permissions array based on the plugin's configuration (roles, dynamic
+ * roles, custom permissions, etc.)
+ */
+export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & {
+    reqId: string;
+    user?: any;
+    userPermissions?: string[]; // Resolved permissions from auth plugin
+};
 
 /**
  * Route props to control routing.
@@ -99,6 +144,27 @@ export interface RouteProps {
 
     /**
      * Set permissions needed to access route if route requires authentication.
+     *
+     * When an array is provided, the user must have **ALL** permissions in the array (AND logic).
+     * To require any one of multiple permissions (OR logic), implement custom permission
+     * checking in the handler using the `user.permissions` array.
+     *
+     * @example
+     * ```typescript
+     * // Single permission
+     * permissions: "car:create"
+     *
+     * // Multiple permissions (user must have ALL)
+     * permissions: ["car:create", "car:premium"]
+     *
+     * // OR logic requires custom implementation
+     * const handler = async ({ ctx, user }) => {
+     *   if (!user.permissions.includes("car:admin") && !user.permissions.includes("car:moderator")) {
+     *     throw forbidden("Need admin or moderator permission");
+     *   }
+     *   // ... handler logic
+     * };
+     * ```
      */
     permissions?: string | string[];
 
@@ -147,16 +213,48 @@ export interface RouteProps {
      * @default ValidationMode.Validate
      */
     validation?: ValidationMode;
+
+    /**
+     * Stream format for streaming handlers (SSE or NDJSON).
+     *
+     * When specified, the handler becomes a streaming handler and receives a `stream`
+     * parameter for writing data chunks. Response validation is automatically skipped
+     * for streaming handlers (chunks are progressive, not a final JSON response).
+     *
+     * **Formats:**
+     * - sse: Server-Sent Events (text/event-stream) - ideal for browser EventSource API
+     * - ndjson: Newline-Delimited JSON (application/x-ndjson) - ideal for LLM text streaming
+     *
+     * **Example:**
+     * ```typescript
+     * export const Route: RouteProps = {
+     *   path: "/ai/stream",
+     *   streamFormat: "sse"
+     * };
+     *
+     * const handler: GetHandler<{}, void> = async ({ ctx, stream }) => {
+     *   if (!stream) throw new Error("Stream not available");
+     *   stream.write({ message: "Hello" });
+     *   stream.end();
+     * };
+     * ```
+     */
+    streamFormat?: StreamFormat;
 }
 
 /**
  * Http handler function that handlers implements in order to
  * handle HTTP requests and return a JSON response.
+ *
+ * For streaming handlers (when streamFormat is specified in RouteProps),
+ * the stream parameter is available. Streaming handlers should still return
+ * a FlinkResponse (can be empty), but it will be ignored by the framework.
  */
 export type Handler<Ctx extends FlinkContext, ReqSchema = any, ResSchema = any, P extends Params = Params, Q extends Query = Query> = (props: {
     req: FlinkRequest<ReqSchema, P, Q>;
     ctx: Ctx;
     origin?: string;
+    stream?: StreamWriter;
 }) => Promise<FlinkResponse<ResSchema | FlinkError>>;
 
 /**