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

package/spec/mock-project/dist/src/FlinkApp.js

@@ -0,0 +1,1000 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+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 };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlinkApp = exports.autoRegisteredAgents = exports.autoRegisteredTools = exports.autoRegisteredJobs = exports.autoRegisteredRepos = exports.autoRegisteredHandlers = exports.expressFn = void 0;
+var ajv_1 = __importDefault(require("ajv"));
+var ajv_formats_1 = __importDefault(require("ajv-formats"));
+var body_parser_1 = __importDefault(require("body-parser"));
+var cors_1 = __importDefault(require("cors"));
+var express_1 = __importDefault(require("express"));
+var mongodb_1 = require("mongodb");
+var morgan_1 = __importDefault(require("morgan"));
+var ms_1 = __importDefault(require("ms"));
+var toad_scheduler_1 = require("toad-scheduler");
+var uuid_1 = require("uuid");
+var FlinkErrors_1 = require("./FlinkErrors");
+var FlinkHttpHandler_1 = require("./FlinkHttpHandler");
+var FlinkLog_1 = require("./FlinkLog");
+var FlinkLogFactory_1 = require("./FlinkLogFactory");
+var FlinkRequestContext_1 = require("./FlinkRequestContext");
+var StreamWriterFactory_1 = require("./handlers/StreamWriterFactory");
+var mock_data_generator_1 = __importDefault(require("./mock-data-generator"));
+var utils_1 = require("./utils");
+var ajv = new ajv_1.default();
+(0, ajv_formats_1.default)(ajv);
+var defaultCorsOptions = {
+    allowedHeaders: "",
+    credentials: true,
+    origin: [/.*/],
+};
+/**
+ * Re-export express factory function so sub packages
+ * do not need its own express
+ */
+exports.expressFn = express_1.default;
+/**
+ * This will be populated at compile time when the apps handlers
+ * are picked up by TypeScript compiler
+ */
+exports.autoRegisteredHandlers = [];
+/**
+ * This will be populated at compile time when the apps repos
+ * are picked up by TypeScript compiler
+ */
+exports.autoRegisteredRepos = [];
+/**
+ * This will be populated at compile time when the apps jobs
+ * are picked up by TypeScript compiler
+ */
+exports.autoRegisteredJobs = [];
+/**
+ * This will be populated at compile time when the apps tools
+ * are picked up by TypeScript compiler
+ */
+exports.autoRegisteredTools = [];
+/**
+ * This will be populated at compile time when the apps agents
+ * are picked up by TypeScript compiler
+ */
+exports.autoRegisteredAgents = [];
+var FlinkApp = /** @class */ (function () {
+    function FlinkApp(opts) {
+        var _a;
+        this.handlers = [];
+        this.started = false;
+        this.debug = false;
+        this.plugins = [];
+        this.routingConfigured = false;
+        this.disableHttpServer = false;
+        this.repos = {};
+        this.llmAdapters = new Map();
+        this.tools = {};
+        this.agents = {}; // FlinkAgent<C> instances
+        /**
+         * Internal cache used to track registered handlers and potentially any overlapping routes
+         */
+        this.handlerRouteCache = new Map();
+        // Performance logger for tracking application startup and operations
+        this.perfLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.perf");
+        // Initialize logging from environment variables (LOG_LEVEL, DEBUG, LOG_LEVELS, etc.)
+        FlinkLogFactory_1.FlinkLogFactory.configure();
+        this.name = opts.name;
+        this.port = opts.port || 3333;
+        this.dbOpts = opts.db;
+        this.debug = !!opts.debug;
+        this.onDbConnection = opts.onDbConnection;
+        this.plugins = opts.plugins || [];
+        this.corsOpts = __assign(__assign({}, defaultCorsOptions), opts.cors);
+        this.rawContentTypes = Array.isArray(opts.rawContentTypes)
+            ? opts.rawContentTypes
+            : typeof opts.rawContentTypes === "string"
+                ? [opts.rawContentTypes]
+                : undefined;
+        this.auth = opts.auth;
+        this.jsonOptions = opts.jsonOptions || { limit: "1mb" };
+        this.schedulingOptions = opts.scheduling;
+        this.disableHttpServer = !!opts.disableHttpServer;
+        this.accessLog = __assign({ enabled: true, format: "dev" }, opts.accessLog);
+        this.onError = opts.onError;
+        // Register LLM adapters if configured
+        if ((_a = opts.ai) === null || _a === void 0 ? void 0 : _a.llms) {
+            // Convert plain object to Map for internal use
+            this.llmAdapters = new Map(Object.entries(opts.ai.llms));
+        }
+    }
+    Object.defineProperty(FlinkApp.prototype, "ctx", {
+        get: function () {
+            if (!this._ctx) {
+                throw new Error("Context is not yet initialized");
+            }
+            return this._ctx;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    FlinkApp.prototype.start = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var startTime, offsetTime, dbStartTime, contextStartTime, toolsStartTime, agentsStartTime, agentInitStartTime, _i, _a, type, pluginsStartTime, _b, _c, plugin, db, handlersStartTime, jobsStartTime, totalStartTime;
+            var _this = this;
+            var _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        startTime = Date.now();
+                        offsetTime = startTime;
+                        dbStartTime = Date.now();
+                        return [4 /*yield*/, this.initDb()];
+                    case 1:
+                        _e.sent();
+                        this.perfLog.debug("Init db took ".concat(Date.now() - dbStartTime, "ms"));
+                        contextStartTime = Date.now();
+                        return [4 /*yield*/, this.buildContext()];
+                    case 2:
+                        _e.sent();
+                        this.perfLog.debug("Build context took ".concat(Date.now() - contextStartTime, "ms"));
+                        toolsStartTime = Date.now();
+                        return [4 /*yield*/, this.registerAutoRegisterableTools()];
+                    case 3:
+                        _e.sent();
+                        this.perfLog.debug("Register tools took ".concat(Date.now() - toolsStartTime, "ms"));
+                        agentsStartTime = Date.now();
+                        return [4 /*yield*/, this.registerAutoRegisterableAgents()];
+                    case 4:
+                        _e.sent();
+                        this.perfLog.debug("Register agents took ".concat(Date.now() - agentsStartTime, "ms"));
+                        agentInitStartTime = Date.now();
+                        return [4 /*yield*/, this.initializeAgents()];
+                    case 5:
+                        _e.sent();
+                        this.perfLog.debug("Initialize agents took ".concat(Date.now() - agentInitStartTime, "ms"));
+                        if (this.isSchedulingEnabled) {
+                            this.scheduler = new toad_scheduler_1.ToadScheduler();
+                        }
+                        else {
+                            FlinkLog_1.log.info("🚫 Scheduling is disabled");
+                        }
+                        if (!this.disableHttpServer) {
+                            this.expressApp = (0, express_1.default)();
+                            this.expressApp.use((0, cors_1.default)(this.corsOpts));
+                            if (this.rawContentTypes) {
+                                for (_i = 0, _a = this.rawContentTypes; _i < _a.length; _i++) {
+                                    type = _a[_i];
+                                    this.expressApp.use(express_1.default.raw({ type: type }));
+                                }
+                            }
+                            this.expressApp.use(body_parser_1.default.json(this.jsonOptions));
+                            if (this.accessLog.enabled) {
+                                this.expressApp.use((0, morgan_1.default)(this.accessLog.format));
+                            }
+                            this.expressApp.use(function (req, res, next) {
+                                req.reqId = (0, uuid_1.v4)();
+                                next();
+                            });
+                        }
+                        pluginsStartTime = Date.now();
+                        _b = 0, _c = this.plugins;
+                        _e.label = 6;
+                    case 6:
+                        if (!(_b < _c.length)) return [3 /*break*/, 12];
+                        plugin = _c[_b];
+                        db = void 0;
+                        if (!plugin.db) return [3 /*break*/, 8];
+                        return [4 /*yield*/, this.initPluginDb(plugin)];
+                    case 7:
+                        db = _e.sent();
+                        _e.label = 8;
+                    case 8:
+                        if (!plugin.init) return [3 /*break*/, 10];
+                        return [4 /*yield*/, plugin.init(this, db)];
+                    case 9:
+                        _e.sent();
+                        _e.label = 10;
+                    case 10:
+                        FlinkLog_1.log.info("Initialized plugin '".concat(plugin.id, "'"));
+                        _e.label = 11;
+                    case 11:
+                        _b++;
+                        return [3 /*break*/, 6];
+                    case 12:
+                        if (this.plugins.length > 0) {
+                            this.perfLog.debug("Initialize plugins took ".concat(Date.now() - pluginsStartTime, "ms (").concat(this.plugins.length, " plugins)"));
+                        }
+                        handlersStartTime = Date.now();
+                        return [4 /*yield*/, this.registerAutoRegisterableHandlers()];
+                    case 13:
+                        _e.sent();
+                        this.perfLog.debug("Register handlers took ".concat(Date.now() - handlersStartTime, "ms"));
+                        if (!this.isSchedulingEnabled) return [3 /*break*/, 15];
+                        jobsStartTime = Date.now();
+                        return [4 /*yield*/, this.registerAutoRegisterableJobs()];
+                    case 14:
+                        _e.sent();
+                        this.perfLog.debug("Register jobs took ".concat(Date.now() - jobsStartTime, "ms"));
+                        _e.label = 15;
+                    case 15:
+                        // Register 404 with slight delay to allow all manually added routes to be added
+                        // TODO: Is there a better solution to force this handler to always run last?
+                        setTimeout(function () {
+                            if (!_this.disableHttpServer) {
+                                _this.expressApp.use(function (req, res, next) {
+                                    res.status(404).json((0, FlinkErrors_1.notFound)());
+                                });
+                            }
+                            _this.routingConfigured = true;
+                        });
+                        if (this.disableHttpServer) {
+                            FlinkLog_1.log.info("🚧 HTTP server is disabled, but flink app is running");
+                            this.started = true;
+                        }
+                        else {
+                            this.expressServer = (_d = this.expressApp) === null || _d === void 0 ? void 0 : _d.listen(this.port, function () {
+                                FlinkLog_1.log.fontColorLog("magenta", "\u26A1\uFE0F HTTP server '".concat(_this.name, "' is running and waiting for connections on ").concat(_this.port));
+                                _this.started = true;
+                            });
+                        }
+                        totalStartTime = Date.now() - startTime;
+                        this.perfLog.info("\u2713 FlinkApp started in ".concat(totalStartTime, "ms"));
+                        return [2 /*return*/, this];
+                }
+            });
+        });
+    };
+    FlinkApp.prototype.stop = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        FlinkLog_1.log.info("🛑 Stopping Flink app...");
+                        if (!this.scheduler) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.scheduler.stop()];
+                    case 1:
+                        _a.sent();
+                        _a.label = 2;
+                    case 2:
+                        if (this.expressServer) {
+                            return [2 /*return*/, new Promise(function (resolve, reject) {
+                                    var int = setTimeout(function () {
+                                        reject("Failed to stop HTTP server in time");
+                                    }, 2000);
+                                    _this.expressServer.close(function () {
+                                        clearInterval(int);
+                                        FlinkLog_1.log.info("HTTP server stopped");
+                                        resolve();
+                                    });
+                                })];
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Manually registers a handler.
+     *
+     * Typescript compiler will scan handler function and set schemas
+     * which are derived from handler function type arguments.
+     */
+    FlinkApp.prototype.addHandler = function (handler, routePropsOverride) {
+        var _a, _b, _c, _d, _e, _f;
+        if (this.routingConfigured) {
+            throw new Error("Cannot add handler after routes has been registered, make sure to invoke earlier");
+        }
+        var routeProps = __assign(__assign({}, (handler.Route || {})), routePropsOverride);
+        if (!routeProps.method) {
+            FlinkLog_1.log.error("Failed to register handler '".concat(handler.__file, "': Missing 'method' in route props, either set it or name handler file with HTTP method as prefix"));
+            return;
+        }
+        if (!routeProps.path) {
+            FlinkLog_1.log.error("Failed to register handler '".concat(handler.__file, "': Missing 'path' in route props"));
+            return;
+        }
+        var dup = this.handlers.find(function (h) { return h.routeProps.path === routeProps.path && h.routeProps.method === routeProps.method; });
+        var methodAndPath = "".concat(routeProps.method.toUpperCase(), " ").concat(routeProps.path);
+        if (dup) {
+            // TODO: Not sure if there is a case where you'd want to overwrite a route?
+            FlinkLog_1.log.warn("".concat(methodAndPath, " overlaps existing route"));
+        }
+        var handlerConfig = {
+            routeProps: __assign(__assign({}, routeProps), { method: routeProps.method, path: routeProps.path }),
+            schema: {
+                reqSchema: (_a = handler.__schemas) === null || _a === void 0 ? void 0 : _a.reqSchema,
+                resSchema: (_b = handler.__schemas) === null || _b === void 0 ? void 0 : _b.resSchema,
+            },
+            queryMetadata: handler.__query || [],
+            paramsMetadata: handler.__params || [],
+        };
+        if (((_c = handler.__schemas) === null || _c === void 0 ? void 0 : _c.reqSchema) && !((_d = handlerConfig.schema) === null || _d === void 0 ? void 0 : _d.reqSchema)) {
+            FlinkLog_1.log.warn("Expected request schema ".concat(handler.__schemas.reqSchema, " for handler ").concat(methodAndPath, " but no such schema was found"));
+        }
+        if (((_e = handler.__schemas) === null || _e === void 0 ? void 0 : _e.resSchema) && !((_f = handlerConfig.schema) === null || _f === void 0 ? void 0 : _f.resSchema)) {
+            FlinkLog_1.log.warn("Expected response schema ".concat(handler.__schemas.resSchema, " for handler ").concat(methodAndPath, " but no such schema was found"));
+        }
+        this.registerHandler(handlerConfig, handler.default);
+    };
+    FlinkApp.prototype.registerHandler = function (handlerConfig, handler) {
+        var _this = this;
+        this.handlers.push(handlerConfig);
+        var routeProps = handlerConfig.routeProps, _a = handlerConfig.schema, schema = _a === void 0 ? {} : _a;
+        var method = routeProps.method, streamFormat = routeProps.streamFormat;
+        if (!method) {
+            FlinkLog_1.log.error("Route ".concat(routeProps.path, " is missing http method"));
+        }
+        if (method) {
+            var methodAndRoute_1 = "".concat(method.toUpperCase(), " ").concat(routeProps.path);
+            if (this.disableHttpServer) {
+                return;
+            }
+            var validateReq_1;
+            var validateRes_1;
+            // Determine validation mode (default to Validate if not specified)
+            var validationMode = routeProps.validation || FlinkHttpHandler_1.ValidationMode.Validate;
+            // Compile request schema if validation mode requires it
+            if (schema.reqSchema && validationMode !== FlinkHttpHandler_1.ValidationMode.SkipValidation && validationMode !== FlinkHttpHandler_1.ValidationMode.ValidateResponse) {
+                validateReq_1 = ajv.compile(schema.reqSchema);
+            }
+            // Skip response validation for streaming handlers (responses are stream chunks, not final JSON)
+            // Skip response validation for non-JSON response types (html, csv, etc.)
+            if (!streamFormat &&
+                !routeProps.responseType &&
+                schema.resSchema &&
+                validationMode !== FlinkHttpHandler_1.ValidationMode.SkipValidation &&
+                validationMode !== FlinkHttpHandler_1.ValidationMode.ValidateRequest) {
+                validateRes_1 = ajv.compile(schema.resSchema);
+            }
+            this.expressApp[method](routeProps.path, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+                var valid, formattedErrors, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, flinkReq_1, err_1, errorResponse, result, valid, formattedErrors;
+                var _this = this;
+                return __generator(this, function (_c) {
+                    switch (_c.label) {
+                        case 0:
+                            if (!routeProps.permissions) return [3 /*break*/, 2];
+                            return [4 /*yield*/, this.authenticate(req, routeProps.permissions)];
+                        case 1:
+                            if (!(_c.sent())) {
+                                return [2 /*return*/, res.status(401).json((0, FlinkErrors_1.unauthorized)())];
+                            }
+                            _c.label = 2;
+                        case 2:
+                            if (validateReq_1) {
+                                valid = validateReq_1(req.body);
+                                if (!valid) {
+                                    formattedErrors = (0, utils_1.formatValidationErrors)(validateReq_1.errors, req.body);
+                                    FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad request\n").concat(formattedErrors));
+                                    return [2 /*return*/, res.status(400).json({
+                                            status: 400,
+                                            error: {
+                                                id: (0, uuid_1.v4)(),
+                                                title: "Bad request",
+                                                detail: formattedErrors,
+                                            },
+                                        })];
+                                }
+                            }
+                            // Skip mock API for streaming handlers
+                            if (routeProps.mockApi && schema.resSchema && !streamFormat) {
+                                FlinkLog_1.log.warn("Mock response for ".concat(req.method.toUpperCase(), " ").concat(req.path));
+                                data = (0, mock_data_generator_1.default)(schema.resSchema);
+                                res.status(200).json({
+                                    status: 200,
+                                    data: data,
+                                });
+                                return [2 /*return*/];
+                            }
+                            // Normalize query parameters to predictable string or string[] types
+                            // Express query parser can produce numbers, booleans, objects, etc.
+                            // We normalize everything to strings or string arrays for consistency
+                            if (req.query && typeof req.query === "object") {
+                                normalizedQuery = {};
+                                for (_i = 0, _a = Object.entries(req.query); _i < _a.length; _i++) {
+                                    _b = _a[_i], key = _b[0], value = _b[1];
+                                    if (Array.isArray(value)) {
+                                        // Handle array values (e.g., ?tag=a&tag=b)
+                                        normalizedQuery[key] = value.map(function (v) { return String(v); });
+                                    }
+                                    else if (value !== undefined && value !== null) {
+                                        // Convert single values to strings
+                                        normalizedQuery[key] = String(value);
+                                    }
+                                    // Skip undefined/null values - they won't appear in the normalized query
+                                }
+                                req.query = normalizedQuery;
+                            }
+                            stream = streamFormat ? StreamWriterFactory_1.StreamWriterFactory.create(res, streamFormat) : undefined;
+                            _c.label = 3;
+                        case 3:
+                            _c.trys.push([3, 5, , 6]);
+                            flinkReq_1 = req;
+                            return [4 /*yield*/, FlinkRequestContext_1.requestContext.run({
+                                    reqId: flinkReq_1.reqId,
+                                    user: flinkReq_1.user,
+                                    userPermissions: flinkReq_1.userPermissions,
+                                    method: method,
+                                    path: routeProps.path,
+                                    timestamp: Date.now(),
+                                    isStreaming: !!streamFormat,
+                                }, function () { return __awaiter(_this, void 0, void 0, function () {
+                                    return __generator(this, function (_a) {
+                                        switch (_a.label) {
+                                            case 0: return [4 /*yield*/, handler({
+                                                    req: flinkReq_1,
+                                                    ctx: this.ctx,
+                                                    origin: routeProps.origin,
+                                                    stream: stream,
+                                                })];
+                                            case 1: return [2 /*return*/, _a.sent()];
+                                        }
+                                    });
+                                }); })];
+                        case 4:
+                            handlerRes = _c.sent();
+                            return [3 /*break*/, 6];
+                        case 5:
+                            err_1 = _c.sent();
+                            // Handle errors for streaming handlers
+                            if (streamFormat && stream) {
+                                FlinkLog_1.log.error("Streaming handler error on ".concat(req.method.toUpperCase(), " ").concat(req.path, ": ").concat(err_1.message), {
+                                    error: err_1,
+                                    path: req.path,
+                                    method: req.method,
+                                });
+                                stream.error(err_1);
+                                return [2 /*return*/];
+                            }
+                            errorResponse = void 0;
+                            // duck typing to check if it is a FlinkError
+                            if (typeof err_1.status === "number" && err_1.status >= 400 && err_1.status < 600 && err_1.error) {
+                                errorResponse = {
+                                    status: err_1.status,
+                                    error: {
+                                        id: err_1.error.id || (0, uuid_1.v4)(),
+                                        title: err_1.error.title || "Unhandled error: ".concat(err_1.error.code || err_1.status),
+                                        detail: err_1.error.detail,
+                                        code: err_1.error.code,
+                                    },
+                                };
+                            }
+                            else {
+                                FlinkLog_1.log.warn("Handler '".concat(methodAndRoute_1, "' threw unhandled exception ").concat(err_1));
+                                console.error(err_1);
+                                errorResponse = (0, FlinkErrors_1.internalServerError)(err_1);
+                            }
+                            // Invoke onError callback if provided
+                            if (this.onError) {
+                                try {
+                                    result = this.onError(errorResponse, {
+                                        req: req,
+                                        method: method,
+                                        path: routeProps.path,
+                                        reqId: req.reqId,
+                                    });
+                                    // Handle async callbacks - don't wait for them
+                                    if (result instanceof Promise) {
+                                        result.catch(function (callbackErr) {
+                                            FlinkLog_1.log.error("onError callback rejected with: ".concat(callbackErr));
+                                        });
+                                    }
+                                }
+                                catch (callbackErr) {
+                                    FlinkLog_1.log.error("onError callback threw an exception: ".concat(callbackErr));
+                                }
+                            }
+                            return [2 /*return*/, res.status(errorResponse.status || 500).json(errorResponse)];
+                        case 6:
+                            // Skip response handling for streaming handlers (stream controls response lifecycle)
+                            if (streamFormat) {
+                                return [2 /*return*/];
+                            }
+                            // Ensure handlerRes is defined for non-streaming handlers
+                            if (!handlerRes) {
+                                return [2 /*return*/, res.status(204).send()];
+                            }
+                            if (validateRes_1 && !(0, utils_1.isError)(handlerRes)) {
+                                valid = validateRes_1(JSON.parse(JSON.stringify(handlerRes.data)));
+                                if (!valid) {
+                                    formattedErrors = (0, utils_1.formatValidationErrors)(validateRes_1.errors, handlerRes.data);
+                                    FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad response\n").concat(formattedErrors));
+                                    return [2 /*return*/, res.status(500).json({
+                                            status: 500,
+                                            error: {
+                                                id: (0, uuid_1.v4)(),
+                                                title: "Bad response",
+                                                detail: formattedErrors,
+                                            },
+                                        })];
+                                }
+                            }
+                            res.set(handlerRes.headers);
+                            if (routeProps.responseType) {
+                                return [2 /*return*/, res
+                                        .status(handlerRes.status || 200)
+                                        .type(routeProps.responseType)
+                                        .send(handlerRes.data)];
+                            }
+                            res.status(handlerRes.status || 200).json(handlerRes);
+                            return [2 /*return*/];
+                    }
+                });
+            }); });
+            if (this.handlerRouteCache.has(methodAndRoute_1)) {
+                FlinkLog_1.log.error("Cannot register handler ".concat(methodAndRoute_1, " - route already registered"));
+                return process.exit(1); // TODO: Do we need to exit?
+            }
+            else {
+                this.handlerRouteCache.set(methodAndRoute_1, JSON.stringify(routeProps));
+                FlinkLog_1.log.info("Registered ".concat(streamFormat ? "streaming " : "", "route ").concat(methodAndRoute_1).concat(streamFormat ? " (".concat(streamFormat, ")") : ""));
+            }
+        }
+    };
+    /**
+     * Register handlers found within the `/src/handlers`
+     * directory in Flink App.
+     *
+     * Will not register any handlers added programmatically.
+     */
+    FlinkApp.prototype.registerAutoRegisterableHandlers = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _i, _a, _b, handler, assumedHttpMethod, pathParams, _c, _d, param;
+            var _e, _f, _g;
+            return __generator(this, function (_h) {
+                for (_i = 0, _a = exports.autoRegisteredHandlers.sort(function (a, b) { var _a, _b; return (((_a = a.handler.Route) === null || _a === void 0 ? void 0 : _a.order) || 0) - (((_b = b.handler.Route) === null || _b === void 0 ? void 0 : _b.order) || 0); }); _i < _a.length; _i++) {
+                    _b = _a[_i], handler = _b.handler, assumedHttpMethod = _b.assumedHttpMethod;
+                    if (!handler.Route) {
+                        FlinkLog_1.log.error("Missing Props in handler ".concat(handler.__file));
+                        continue;
+                    }
+                    if (!handler.default) {
+                        FlinkLog_1.log.error("Missing exported handler function in handler ".concat(handler.__file));
+                        continue;
+                    }
+                    if (!!((_e = handler.__params) === null || _e === void 0 ? void 0 : _e.length)) {
+                        pathParams = (0, utils_1.getPathParams)(handler.Route.path);
+                        for (_c = 0, _d = handler.__params; _c < _d.length; _c++) {
+                            param = _d[_c];
+                            if (!pathParams.includes(param.name)) {
+                                FlinkLog_1.log.error("Handler ".concat(handler.__file, " has param ").concat(param.name, " but it is not present in the path '").concat(handler.Route.path, "'"));
+                                throw new Error("Invalid/missing handler path param");
+                            }
+                        }
+                        if (pathParams.length !== handler.__params.length) {
+                            FlinkLog_1.log.warn("Handler ".concat(handler.__file, " has ").concat(handler.__params.length, " typed params but the path '").concat(handler.Route.path, "' has ").concat(pathParams.length, " params"));
+                        }
+                    }
+                    this.registerHandler({
+                        routeProps: __assign(__assign({}, handler.Route), { method: handler.Route.method || assumedHttpMethod, origin: this.name }),
+                        schema: {
+                            reqSchema: (_f = handler.__schemas) === null || _f === void 0 ? void 0 : _f.reqSchema,
+                            resSchema: (_g = handler.__schemas) === null || _g === void 0 ? void 0 : _g.resSchema,
+                        },
+                        queryMetadata: handler.__query || [],
+                        paramsMetadata: handler.__params || [],
+                    }, handler.default);
+                }
+                return [2 /*return*/];
+            });
+        });
+    };
+    FlinkApp.prototype.registerAutoRegisterableJobs = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _loop_1, this_1, _i, autoRegisteredJobs_1, _a, jobProps, jobFn, __file;
+            var _this = this;
+            return __generator(this, function (_b) {
+                if (!this.scheduler) {
+                    throw new Error("Scheduler not initialized"); // should never happen
+                }
+                _loop_1 = function (jobProps, jobFn, __file) {
+                    if (jobProps.cron && jobProps.interval) {
+                        FlinkLog_1.log.error("Cannot register job ".concat(jobProps.id, " - both cron and interval are set in ").concat(__file));
+                        return "continue";
+                    }
+                    if (jobProps.cron && jobProps.afterDelay) {
+                        FlinkLog_1.log.error("Cannot register job ".concat(jobProps.id, " - both cron and afterDelay are set in ").concat(__file));
+                        return "continue";
+                    }
+                    if (jobProps.interval && jobProps.afterDelay) {
+                        FlinkLog_1.log.error("Cannot register job ".concat(jobProps.id, " - both interval and afterDelay are set in ").concat(__file));
+                        return "continue";
+                    }
+                    if (this_1.scheduler.existsById(jobProps.id)) {
+                        FlinkLog_1.log.error("Job with id ".concat(jobProps.id, " is already registered, found duplicate in ").concat(__file));
+                        return "continue";
+                    }
+                    FlinkLog_1.log.debug("Registering job ".concat(jobProps.id, ": ").concat(JSON.stringify(jobProps), " from ").concat(__file));
+                    var task = new toad_scheduler_1.AsyncTask(jobProps.id, function () { return __awaiter(_this, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            switch (_a.label) {
+                                case 0: return [4 /*yield*/, jobFn({ ctx: this.ctx })];
+                                case 1:
+                                    _a.sent();
+                                    FlinkLog_1.log.debug("Job ".concat(jobProps.id, " completed"));
+                                    if (jobProps.afterDelay) {
+                                        // afterDelay runs only once, so we remove the job
+                                        this.scheduler.removeById(jobProps.id);
+                                    }
+                                    return [2 /*return*/];
+                            }
+                        });
+                    }); }, function (err) {
+                        FlinkLog_1.log.error("Job ".concat(jobProps.id, " threw unhandled exception ").concat(err));
+                        console.error(err);
+                    });
+                    if (jobProps.cron) {
+                        var job = new toad_scheduler_1.CronJob({ timezone: jobProps.timezone, cronExpression: jobProps.cron }, task, {
+                            id: jobProps.id,
+                            preventOverrun: jobProps.singleton,
+                        });
+                        this_1.scheduler.addCronJob(job);
+                    }
+                    else if (jobProps.interval) {
+                        var job = new toad_scheduler_1.SimpleIntervalJob({
+                            milliseconds: (0, ms_1.default)(jobProps.interval),
+                            runImmediately: false, // TODO: Expose to props?
+                        }, task, {
+                            id: jobProps.id,
+                            preventOverrun: jobProps.singleton,
+                        });
+                        this_1.scheduler.addSimpleIntervalJob(job);
+                    }
+                    else if (jobProps.afterDelay !== undefined) {
+                        var job = new toad_scheduler_1.SimpleIntervalJob({
+                            milliseconds: (0, ms_1.default)(jobProps.afterDelay),
+                            runImmediately: false,
+                        }, task, {
+                            id: jobProps.id,
+                            preventOverrun: jobProps.singleton,
+                        });
+                        this_1.scheduler.addSimpleIntervalJob(job);
+                    }
+                    else {
+                        FlinkLog_1.log.error("Cannot register job ".concat(jobProps.id, " - no cron, interval or once set in ").concat(__file));
+                        return "continue";
+                    }
+                };
+                this_1 = this;
+                for (_i = 0, autoRegisteredJobs_1 = exports.autoRegisteredJobs; _i < autoRegisteredJobs_1.length; _i++) {
+                    _a = autoRegisteredJobs_1[_i], jobProps = _a.Job, jobFn = _a.default, __file = _a.__file;
+                    _loop_1(jobProps, jobFn, __file);
+                }
+                return [2 /*return*/];
+            });
+        });
+    };
+    FlinkApp.prototype.addRepo = function (instanceName, repoInstance) {
+        this.repos[instanceName] = repoInstance;
+        // TODO: Find out if we need to set ctx here or wanted not to if plugin has its own context
+        // repoInstance.ctx = this.ctx;
+    };
+    FlinkApp.prototype.registerAutoRegisterableTools = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var ToolExecutor, getRepoInstanceName, _i, autoRegisteredTools_1, toolFile, toolId, toolInstanceName, toolExecutor;
+            return __generator(this, function (_a) {
+                ToolExecutor = require("./ai/ToolExecutor").ToolExecutor;
+                getRepoInstanceName = require("./utils").getRepoInstanceName;
+                for (_i = 0, autoRegisteredTools_1 = exports.autoRegisteredTools; _i < autoRegisteredTools_1.length; _i++) {
+                    toolFile = autoRegisteredTools_1[_i];
+                    if (!toolFile.Tool) {
+                        FlinkLog_1.log.error("Missing FlinkToolProps export in tool ".concat(toolFile.__file));
+                        continue;
+                    }
+                    if (!toolFile.default) {
+                        FlinkLog_1.log.error("Missing exported tool function in tool ".concat(toolFile.__file));
+                        continue;
+                    }
+                    toolId = toolFile.Tool.id;
+                    if (!toolId) {
+                        FlinkLog_1.log.error("Tool ".concat(toolFile.__file, " missing 'id' property"));
+                        continue;
+                    }
+                    toolInstanceName = getRepoInstanceName(toolId);
+                    toolExecutor = new ToolExecutor(toolFile.Tool, toolFile.default, this.ctx, toolFile.__schemas // Auto-generated schemas from type parameters
+                    );
+                    this.tools[toolInstanceName] = toolExecutor;
+                    FlinkLog_1.log.info("Registered tool ".concat(toolInstanceName, " (").concat(toolId, ")"));
+                }
+                return [2 /*return*/];
+            });
+        });
+    };
+    FlinkApp.prototype.registerAutoRegisterableAgents = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a, getRepoInstanceName, toKebabCase, _loop_2, this_2, _i, autoRegisteredAgents_1, agentFile;
+            return __generator(this, function (_b) {
+                _a = require("./utils"), getRepoInstanceName = _a.getRepoInstanceName, toKebabCase = _a.toKebabCase;
+                _loop_2 = function (agentFile) {
+                    // agentFile now exports a class, not a config object
+                    var AgentClass = agentFile.default;
+                    if (!AgentClass) {
+                        FlinkLog_1.log.error("Missing default export in agent ".concat(agentFile.__file));
+                        return "continue";
+                    }
+                    // Instantiate agent (similar to repo instantiation)
+                    var agentInstance = new AgentClass();
+                    // Derive instance name from class name (camelCase)
+                    var agentInstanceName = getRepoInstanceName(AgentClass.name);
+                    // Get agent ID (kebab-case) - either explicit or derived
+                    var agentId = agentInstance.id;
+                    // Check for duplicate instance name
+                    if (this_2.agents[agentInstanceName]) {
+                        var existingAgent = this_2.agents[agentInstanceName];
+                        throw new Error("Duplicate agent instance name: \"".concat(agentInstanceName, "\". ") +
+                            "Agent class \"".concat(AgentClass.name, "\" conflicts with existing agent \"").concat(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
+                    var existingAgentWithSameId = Object.values(this_2.agents).find(function (agent) { return agent.id === agentId; });
+                    if (existingAgentWithSameId) {
+                        throw new Error("Duplicate agent ID: \"".concat(agentId, "\". ") +
+                            "Agent class \"".concat(AgentClass.name, "\" conflicts with existing agent \"").concat(existingAgentWithSameId.constructor.name, "\". ") +
+                            "Change the 'id' property on one of them to resolve the conflict.");
+                    }
+                    // Validate tools exist
+                    if (agentInstance.tools) {
+                        for (var _c = 0, _d = agentInstance.tools; _c < _d.length; _c++) {
+                            var toolRef = _d[_c];
+                            // Handle string IDs, tool file references, and tool props
+                            var toolId = void 0;
+                            if (typeof toolRef === "string") {
+                                toolId = toolRef;
+                            }
+                            else if ("Tool" in toolRef) {
+                                // FlinkToolFile - extract ID from Tool property
+                                toolId = toolRef.Tool.id;
+                            }
+                            else {
+                                // FlinkToolProps - extract ID directly
+                                toolId = toolRef.id;
+                            }
+                            var tool = this_2.tools[toolId];
+                            if (!tool) {
+                                FlinkLog_1.log.error("Agent ".concat(AgentClass.name, " references tool ").concat(toolId, " which is not registered"));
+                                throw new Error("Invalid tool reference in agent ".concat(AgentClass.name));
+                            }
+                        }
+                    }
+                    // Register agent (duplicate checks already performed above)
+                    this_2.agents[agentInstanceName] = agentInstance;
+                    FlinkLog_1.log.info("Registered agent ".concat(agentInstanceName, " (").concat(AgentClass.name, ") with ID: ").concat(agentId));
+                };
+                this_2 = this;
+                for (_i = 0, autoRegisteredAgents_1 = exports.autoRegisteredAgents; _i < autoRegisteredAgents_1.length; _i++) {
+                    agentFile = autoRegisteredAgents_1[_i];
+                    _loop_2(agentFile);
+                }
+                return [2 /*return*/];
+            });
+        });
+    };
+    /**
+     * Constructs the app context. Will inject context in all components
+     * except for handlers which are handled in later stage.
+     */
+    FlinkApp.prototype.buildContext = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _i, autoRegisteredRepos_1, _a, collectionName, repoInstanceName, Repo, repoInstance, pluginCtx, _b, _c, repo;
+            return __generator(this, function (_d) {
+                if (this.dbOpts) {
+                    for (_i = 0, autoRegisteredRepos_1 = exports.autoRegisteredRepos; _i < autoRegisteredRepos_1.length; _i++) {
+                        _a = autoRegisteredRepos_1[_i], collectionName = _a.collectionName, repoInstanceName = _a.repoInstanceName, Repo = _a.Repo;
+                        repoInstance = new Repo(collectionName, this.db, this.dbClient);
+                        this.repos[repoInstanceName] = repoInstance;
+                        FlinkLog_1.log.info("Registered repo ".concat(repoInstanceName));
+                    }
+                }
+                else if (exports.autoRegisteredRepos.length > 0) {
+                    FlinkLog_1.log.warn("No db configured but found repo(s)");
+                }
+                pluginCtx = this.plugins.reduce(function (out, plugin) {
+                    if (out[plugin.id]) {
+                        throw new Error("Plugin ".concat(plugin.id, " is already registered"));
+                    }
+                    out[plugin.id] = plugin.ctx;
+                    return out;
+                }, {});
+                this._ctx = {
+                    repos: this.repos,
+                    plugins: pluginCtx,
+                    auth: this.auth,
+                    agents: this.agents,
+                };
+                for (_b = 0, _c = Object.values(this.repos); _b < _c.length; _b++) {
+                    repo = _c[_b];
+                    repo.ctx = this.ctx;
+                }
+                return [2 /*return*/];
+            });
+        });
+    };
+    /**
+     * Initialize agents after they've been registered and context is ready
+     * Must be called after registerAutoRegisterableAgents()
+     */
+    FlinkApp.prototype.initializeAgents = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _i, _a, agent;
+            return __generator(this, function (_b) {
+                // Inject context and initialize agents
+                for (_i = 0, _a = Object.values(this.agents); _i < _a.length; _i++) {
+                    agent = _a[_i];
+                    agent.ctx = this.ctx;
+                    agent.__init(this.llmAdapters, this.tools);
+                }
+                return [2 /*return*/];
+            });
+        });
+    };
+    /**
+     * Connects to database.
+     */
+    FlinkApp.prototype.initDb = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var client, err_2;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!this.dbOpts) return [3 /*break*/, 6];
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        FlinkLog_1.log.debug("Connecting to db");
+                        return [4 /*yield*/, mongodb_1.MongoClient.connect(this.dbOpts.uri, this.getMongoConnectionOptions())];
+                    case 2:
+                        client = _a.sent();
+                        this.db = client.db();
+                        this.dbClient = client;
+                        return [3 /*break*/, 4];
+                    case 3:
+                        err_2 = _a.sent();
+                        FlinkLog_1.log.error("Failed to connect to db: " + err_2);
+                        process.exit(1);
+                        return [3 /*break*/, 4];
+                    case 4:
+                        if (!this.onDbConnection) return [3 /*break*/, 6];
+                        return [4 /*yield*/, this.onDbConnection(this.db)];
+                    case 5:
+                        _a.sent();
+                        _a.label = 6;
+                    case 6: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Connects plugin to database.
+     */
+    FlinkApp.prototype.initPluginDb = function (plugin) {
+        return __awaiter(this, void 0, void 0, function () {
+            var client, err_3;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!plugin.db) {
+                            return [2 /*return*/];
+                        }
+                        if (!plugin.db) return [3 /*break*/, 5];
+                        if (!plugin.db.useHostDb) return [3 /*break*/, 1];
+                        if (!this.db) {
+                            FlinkLog_1.log.error("Plugin '".concat(this.name, " configured to use host app db, but no db exists in FlinkApp'"));
+                        }
+                        else {
+                            return [2 /*return*/, this.db];
+                        }
+                        return [3 /*break*/, 5];
+                    case 1:
+                        if (!plugin.db.uri) return [3 /*break*/, 5];
+                        _a.label = 2;
+                    case 2:
+                        _a.trys.push([2, 4, , 5]);
+                        FlinkLog_1.log.debug("Connecting to '".concat(plugin.id, "' db"));
+                        return [4 /*yield*/, mongodb_1.MongoClient.connect(plugin.db.uri, this.getMongoConnectionOptions())];
+                    case 3:
+                        client = _a.sent();
+                        return [2 /*return*/, client.db()];
+                    case 4:
+                        err_3 = _a.sent();
+                        FlinkLog_1.log.error("Failed to connect to db defined in plugin '".concat(plugin.id, "': ") + err_3);
+                        return [3 /*break*/, 5];
+                    case 5: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    FlinkApp.prototype.authenticate = function (req, permissions) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!this.auth) {
+                            throw new Error("Attempting to authenticate request (".concat(req.method, " ").concat(req.path, ") but no authPlugin is set"));
+                        }
+                        return [4 /*yield*/, this.auth.authenticateRequest(req, permissions)];
+                    case 1: return [2 /*return*/, _a.sent()];
+                }
+            });
+        });
+    };
+    FlinkApp.prototype.getRegisteredRoutes = function () {
+        return Array.from(this.handlerRouteCache.values());
+    };
+    Object.defineProperty(FlinkApp.prototype, "isSchedulingEnabled", {
+        get: function () {
+            var _a;
+            return ((_a = this.schedulingOptions) === null || _a === void 0 ? void 0 : _a.enabled) !== false;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    FlinkApp.prototype.getMongoConnectionOptions = function () {
+        if (!this.dbOpts) {
+            throw new Error("No db configured");
+        }
+        var driverVersion = require("mongodb/package.json").version;
+        if (driverVersion.startsWith("3")) {
+            FlinkLog_1.log.debug("Using legacy mongodb connection options as mongo client is version ".concat(driverVersion));
+            return {
+                useNewUrlParser: true,
+                useUnifiedTopology: true,
+            };
+        }
+        FlinkLog_1.log.debug("Using modern MongoDB client options (driver version ".concat(driverVersion, ")"));
+        return {
+            serverApi: {
+                version: mongodb_1.ServerApiVersion.v1,
+                strict: process.env.FLINK_MONGO_SERVER_API_DISABLE_STRICT !== "true",
+                deprecationErrors: process.env.FLINK_MONGO_SERVER_API_DISABLE_DEPRECATION !== "true",
+            },
+            connectTimeoutMS: 10 * 1000,
+        };
+    };
+    return FlinkApp;
+}());
+exports.FlinkApp = FlinkApp;