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

package/dist/src/DependencyTracker.js

@@ -0,0 +1,239 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyTracker = void 0;
+var path = __importStar(require("path"));
+var minimatch_1 = require("minimatch");
+var SchemaCache_1 = require("./SchemaCache");
+/**
+ * Tracks dependencies and computes content hashes for schema files
+ */
+var DependencyTracker = /** @class */ (function () {
+    function DependencyTracker(projectRoot, config) {
+        var _a;
+        this.projectRoot = projectRoot;
+        this.dependencyCache = new Map();
+        this.config = {
+            excludeNodeModules: (_a = config === null || config === void 0 ? void 0 : config.excludeNodeModules) !== null && _a !== void 0 ? _a : true,
+            includePatterns: (config === null || config === void 0 ? void 0 : config.includePatterns) || [],
+        };
+    }
+    /**
+     * Check if a file path should be tracked in the cache
+     */
+    DependencyTracker.prototype.shouldTrackFile = function (filePath) {
+        var isNodeModules = filePath.includes('node_modules');
+        // If not in node_modules, always track
+        if (!isNodeModules) {
+            return true;
+        }
+        // If excludeNodeModules is false, track all node_modules
+        if (!this.config.excludeNodeModules) {
+            return true;
+        }
+        // Check if path matches any include pattern
+        if (this.config.includePatterns && this.config.includePatterns.length > 0) {
+            var relativePath = path.relative(this.projectRoot, filePath);
+            for (var _i = 0, _a = this.config.includePatterns; _i < _a.length; _i++) {
+                var pattern = _a[_i];
+                if ((0, minimatch_1.minimatch)(relativePath, pattern) || (0, minimatch_1.minimatch)(filePath, pattern)) {
+                    return true;
+                }
+            }
+        }
+        // Exclude by default
+        return false;
+    };
+    /**
+     * Build dependency graph for a schema file
+     * Returns map of absolute file paths to their content hashes
+     */
+    DependencyTracker.prototype.buildDependencyGraph = function (schemaFile, resolveImports) {
+        return __awaiter(this, void 0, void 0, function () {
+            var dependencies, visited;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        dependencies = new Map();
+                        visited = new Set();
+                        // Recursively collect all dependencies
+                        return [4 /*yield*/, this.collectDependencies(schemaFile, resolveImports, visited, dependencies)];
+                    case 1:
+                        // Recursively collect all dependencies
+                        _a.sent();
+                        return [2 /*return*/, dependencies];
+                }
+            });
+        });
+    };
+    /**
+     * Recursively collect dependencies and compute hashes
+     */
+    DependencyTracker.prototype.collectDependencies = function (filePath, resolveImports, visited, dependencies) {
+        return __awaiter(this, void 0, void 0, function () {
+            var hash, imports;
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        // Skip if already visited
+                        if (visited.has(filePath)) {
+                            return [2 /*return*/];
+                        }
+                        visited.add(filePath);
+                        // Check if file should be tracked based on config
+                        if (!this.shouldTrackFile(filePath)) {
+                            return [2 /*return*/];
+                        }
+                        return [4 /*yield*/, SchemaCache_1.SchemaCache.hashFile(filePath)];
+                    case 1:
+                        hash = _a.sent();
+                        if (hash) {
+                            dependencies.set(filePath, hash);
+                        }
+                        imports = resolveImports(filePath);
+                        // Recursively process imports
+                        return [4 /*yield*/, Promise.all(imports.map(function (importPath) {
+                                return _this.collectDependencies(importPath, resolveImports, visited, dependencies);
+                            }))];
+                    case 2:
+                        // Recursively process imports
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Batch compute hashes for multiple files
+     * Returns map of file paths to hashes
+     */
+    DependencyTracker.prototype.batchHashFiles = function (filePaths) {
+        return __awaiter(this, void 0, void 0, function () {
+            var hashes, results, _i, results_1, _a, filePath, hash;
+            var _this = this;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        hashes = new Map();
+                        return [4 /*yield*/, Promise.all(filePaths.map(function (filePath) { return __awaiter(_this, void 0, void 0, function () {
+                                var _a;
+                                return __generator(this, function (_b) {
+                                    switch (_b.label) {
+                                        case 0:
+                                            _a = {
+                                                filePath: filePath
+                                            };
+                                            return [4 /*yield*/, SchemaCache_1.SchemaCache.hashFile(filePath)];
+                                        case 1: return [2 /*return*/, (_a.hash = _b.sent(),
+                                                _a)];
+                                    }
+                                });
+                            }); }))];
+                    case 1:
+                        results = _b.sent();
+                        // Build map
+                        for (_i = 0, results_1 = results; _i < results_1.length; _i++) {
+                            _a = results_1[_i], filePath = _a.filePath, hash = _a.hash;
+                            if (hash) {
+                                hashes.set(filePath, hash);
+                            }
+                        }
+                        return [2 /*return*/, hashes];
+                }
+            });
+        });
+    };
+    /**
+     * Check if any dependencies changed
+     * Returns list of changed file paths
+     */
+    DependencyTracker.prototype.findChangedDependencies = function (dependencies, cachedHashes) {
+        return __awaiter(this, void 0, void 0, function () {
+            var changed, _i, _a, _b, filePath, currentHash, cachedHash;
+            return __generator(this, function (_c) {
+                changed = [];
+                for (_i = 0, _a = Array.from(dependencies.entries()); _i < _a.length; _i++) {
+                    _b = _a[_i], filePath = _b[0], currentHash = _b[1];
+                    cachedHash = cachedHashes[filePath];
+                    if (cachedHash !== currentHash) {
+                        changed.push(filePath);
+                    }
+                }
+                return [2 /*return*/, changed];
+            });
+        });
+    };
+    /**
+     * Get relative path for display purposes
+     */
+    DependencyTracker.prototype.getRelativePath = function (filePath) {
+        return path.relative(this.projectRoot, filePath);
+    };
+    /**
+     * Clear dependency cache
+     */
+    DependencyTracker.prototype.clearCache = function () {
+        this.dependencyCache.clear();
+    };
+    return DependencyTracker;
+}());
+exports.DependencyTracker = DependencyTracker;

package/dist/src/FlinkApp.d.ts

@@ -1,13 +1,19 @@
+import Ajv from "ajv";
 import { OptionsJson } from "body-parser";
 import express, { Express } from "express";
 import { JSONSchema7 } from "json-schema";
 import { Db, MongoClient } from "mongodb";
 import { ToadScheduler } from "toad-scheduler";
+import { FlinkAgentFile } from "./ai/FlinkAgent";
+import { FlinkToolFile } from "./ai/FlinkTool";
+import { AgentObserver } from "./ai/FlinkAgent";
+import { LLMAdapter } from "./ai/LLMAdapter";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
 import { FlinkError } from "./FlinkErrors";
 import { FlinkRequest, HandlerFile, HttpMethod, QueryParamMetadata, RouteProps } from "./FlinkHttpHandler";
 import { FlinkJobFile } from "./FlinkJob";
+import { LeaderElectionOptions } from "./LeaderElection";
 import { FlinkPlugin } from "./FlinkPlugin";
 import { FlinkRepo } from "./FlinkRepo";
 import { FlinkResponse } from "./FlinkResponse";
@@ -24,6 +30,7 @@ export declare const expressFn: typeof express;
 export declare const autoRegisteredHandlers: {
     handler: HandlerFile;
     assumedHttpMethod: HttpMethod;
+    __file?: string;
 }[];
 /**
  * This will be populated at compile time when the apps repos
@@ -39,7 +46,25 @@ export declare const autoRegisteredRepos: {
  * are picked up by TypeScript compiler
  */
 export declare const autoRegisteredJobs: FlinkJobFile[];
-export interface FlinkOptions {
+/**
+ * This will be populated at compile time when the apps tools
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredTools: FlinkToolFile[];
+/**
+ * This will be populated at compile time when the apps agents
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredAgents: FlinkAgentFile<any, any>[];
+/**
+ * This will be populated at compile time when the apps services
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredServices: {
+    serviceInstanceName: string;
+    Service: any;
+}[];
+export interface FlinkOptions<C extends FlinkContext = FlinkContext> {
     /**
      * Name of application, will only show in logs and in HTTP header.
      */
@@ -117,10 +142,61 @@ export interface FlinkOptions {
          * Defaults to true.
          */
         enabled?: boolean;
+        /**
+         * Enable leader election for horizontally scaled deployments.
+         *
+         * When enabled, only one instance (the leader) will run scheduled jobs.
+         * If the leader goes down, another instance automatically takes over.
+         *
+         * Requires a database connection (`db` option) since leader election
+         * state is persisted in MongoDB. If no database is configured, a warning
+         * will be logged and jobs will run on all instances (no leader election).
+         *
+         * Set to `true` for default settings, or pass an options object to customize.
+         *
+         * @example
+         * ```ts
+         * // Use defaults (15s lease, 5s heartbeat)
+         * scheduling: { leaderElection: true }
+         *
+         * // Custom settings
+         * scheduling: {
+         *   leaderElection: {
+         *     leaseDurationMs: 30000,
+         *     heartbeatIntervalMs: 10000,
+         *   }
+         * }
+         * ```
+         */
+        leaderElection?: boolean | LeaderElectionOptions;
+    };
+    /**
+     * 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;
+        };
+        /**
+         * Global agent observer for app-level tracing, APM, cost accounting, dev tools, etc.
+         *
+         * Fires for every agent execution in the app. Observer callbacks are invoked
+         * fire-and-forget — they may return a Promise but the framework does not await
+         * them, and any thrown/rejected errors are caught and logged without affecting
+         * agent execution.
+         *
+         * Events: `onRun` (pre-loop), `onLlmCall` (per step, pre-adapter call),
+         * `onStep` (per step end), `onFinish` (post-loop, including error path).
+         *
+         * For agent-local business logic (conversation persistence, guardrails) use the
+         * per-agent `beforeRun` / `onStep` / `afterRun` hooks on `FlinkAgent` instead.
+         */
+        observer?: AgentObserver;
     };
     /**
      * If true, the HTTP server will be disabled.
-     * Only useful when starting a Flink app for testing purposes.
      */
     disableHttpServer?: boolean;
     /**
@@ -139,17 +215,26 @@ export interface FlinkOptions {
         format?: string;
     };
     /**
-     * Optional callback invoked when an error occurs in a handler.
+     * Optional callback invoked when an error occurs while serving a request.
      * The error response and request context are passed for custom
      * error logging or monitoring. This is a side-effect only and
      * will not modify the response flow.
      *
+     * Invoked for:
+     * - Handler-thrown errors (FlinkErrors and unhandled exceptions)
+     * - Request validation failures (400 Bad request)
+     * - Response validation failures (500 Bad response)
+     *
+     * Not invoked for errors in streaming (SSE/NDJSON) handlers, which are
+     * delivered to the client via `stream.error()` instead.
+     *
      * Supports both synchronous and asynchronous callbacks. Any errors
      * thrown or rejected by the callback will be caught and logged
-     * without affecting the error response to the client.
+     * without affecting the error response to the client. Async callbacks
+     * are fire-and-forget — they are not awaited before the response is sent.
      *
      * @param error - The error response with status and error details
-     * @param context - Request context including method, path, and request ID
+     * @param context - Request context including method, path, request ID and the app context
      *
      * @example
      * ```ts
@@ -165,12 +250,14 @@ export interface FlinkOptions {
      *   }
      * }
      *
-     * // Asynchronous callback
+     * // Asynchronous callback using the app context
      * onError: async (error, context) => {
      *   if (error.status >= 500) {
-     *     await monitoringService.reportError({
-     *       error,
-     *       context
+     *     await context.ctx.repos.errorLogRepo.create({
+     *       status: error.status,
+     *       detail: error.error?.detail,
+     *       route: `${context.method} ${context.path}`,
+     *       reqId: context.reqId,
      *     });
      *   }
      * }
@@ -181,6 +268,7 @@ export interface FlinkOptions {
         method: HttpMethod;
         path: string;
         reqId: string;
+        ctx: C;
     }) => void | Promise<void>;
 }
 export interface HandlerConfig {
@@ -213,6 +301,8 @@ export declare class FlinkApp<C extends FlinkContext> {
     started: boolean;
     private _ctx?;
     private dbOpts?;
+    private schemaManifest?;
+    private schemaAjv?;
     private debug;
     private onDbConnection?;
     private plugins;
@@ -226,13 +316,20 @@ export declare class FlinkApp<C extends FlinkContext> {
     private expressServer;
     private onError?;
     private repos;
+    private services;
+    private llmAdapters;
+    private agentObserver?;
+    private tools;
+    private agents;
     /**
      * Internal cache used to track registered handlers and potentially any overlapping routes
      */
     private handlerRouteCache;
     scheduler?: ToadScheduler;
+    private allInstanceScheduler?;
+    private leaderElection?;
     private accessLog;
-    constructor(opts: FlinkOptions);
+    constructor(opts: FlinkOptions<C>);
     get ctx(): C;
     start(): Promise<this>;
     stop(): Promise<void>;
@@ -244,6 +341,47 @@ export declare class FlinkApp<C extends FlinkContext> {
      */
     addHandler(handler: HandlerFile, routePropsOverride?: Partial<HandlerConfig["routeProps"]>): void;
     private registerHandler;
+    /**
+     * Load schema manifest from .flink directory.
+     * Returns empty structure if manifest doesn't exist (dev mode without build).
+     *
+     * The manifest contains:
+     * - definitions: ALL JSON Schema type definitions (supports $ref resolution)
+     * - handlers: Handler metadata with schema names (references to definitions)
+     * - tools: Tool metadata with schema names (references to definitions)
+     */
+    private loadSchemaManifest;
+    /**
+     * Get the AJV instance for validation (v2.0 manifests).
+     * Returns undefined for v1.0 manifests.
+     */
+    getSchemaAjv(): Ajv | undefined;
+    /**
+     * Register plugin schemas into the app's AJV instance.
+     * Schema $id values are prefixed with `pluginId::` to avoid collisions
+     * with the app's own schemas or other plugins.
+     *
+     * @param pluginId Unique identifier for the plugin (used as namespace prefix)
+     * @param schemas Record of schema name to JSON Schema object (already prefixed)
+     */
+    registerSchemas(pluginId: string, schemas: Record<string, any>): void;
+    /**
+     * Check if a schema has unresolved generic type parameter references.
+     * Generic type parameters like T, U, V are single uppercase letters.
+     *
+     * @param schema JSON schema object
+     * @param registeredSchemaIds List of schema IDs in the manifest
+     * @returns true if schema references generic type params that don't exist
+     */
+    private hasUnresolvedTypeParams;
+    /**
+     * Resolve schema by name from manifest.
+     * Works with both v1.0 (definitions) and v2.0 (schema universe) formats.
+     *
+     * @param schemaName Schema name or $id
+     * @returns JSON schema object or undefined
+     */
+    private resolveSchema;
     /**
      * Register handlers found within the `/src/handlers`
      * directory in Flink App.
@@ -253,11 +391,18 @@ export declare class FlinkApp<C extends FlinkContext> {
     private registerAutoRegisterableHandlers;
     private registerAutoRegisterableJobs;
     addRepo(instanceName: string, repoInstance: FlinkRepo<C, any>): void;
+    private registerAutoRegisterableTools;
+    private registerAutoRegisterableAgents;
     /**
      * Constructs the app context. Will inject context in all components
      * except for handlers which are handled in later stage.
      */
     private buildContext;
+    /**
+     * Initialize agents after they've been registered and context is ready
+     * Must be called after registerAutoRegisterableAgents()
+     */
+    private initializeAgents;
     /**
      * Connects to database.
      */
@@ -267,7 +412,15 @@ export declare class FlinkApp<C extends FlinkContext> {
      */
     private initPluginDb;
     private authenticate;
+    /**
+     * Invokes the optional onError callback in a fire-and-forget manner.
+     * Any error thrown or rejected by the callback is caught and logged so
+     * it never affects the error response sent to the client.
+     */
+    private invokeOnError;
     getRegisteredRoutes(): string[];
     private get isSchedulingEnabled();
+    private get leaderElectionConfig();
+    private startLeaderElection;
     private getMongoConnectionOptions;
 }